BondTrader

What it is

BondTrader is a Python fixed income analytics codebase: bond valuation (YTM, duration, convexity, fair value), risk and portfolio-style analytics, optional ML-assisted pricing workflows, a FastAPI REST surface, and a Streamlit dashboard. It is aimed at research, education, and lab-style deployments—not a turn-key production trading system without additional hardening (see Disclaimer).

The repo is a monorepo mid-migration: a legacy top-level package bondtrader/ plus installable subpackages under packages/ (bondtrader_domain, bondtrader_data, bondtrader_ml, bondtrader_api) and Streamlit adapters in apps/dashboard/. Public numerical behavior for core valuation is guarded by contract tests and versioned golden JSON under tests/fixtures/golden/.

Governance: Contributing · Support · Security · ADRs · AGENTS.md · Layout & import rules

Overview

BondTrader provides:

• Core bond valuation: cashflow-style fair value, YTM (solver with strip / fractional-period handling where applicable), duration, convexity; several bond type enums and pricers (maturity varies by type)
• Risk & analytics: VaR-style and credit/tail/liquidity modules, portfolio optimization helpers, arbitrage-style mispricing detection (configurable)
• ML (optional paths): Scikit-learn–centric stack with optional XGBoost/LightGBM/CatBoost/MLflow/SHAP via pyproject.toml optional-dependencies (ml, all)
• REST API: FastAPI app (install bondtrader[api] or use requirements.lock / Docker); OpenAPI export used in CI via scripts/export_openapi_fixed.py
• Dashboard: Streamlit UI; auth helpers live under apps/dashboard/ to keep Streamlit out of core utils where split

Project status: Active development. See Current limitations and ROADMAP.md.

Table of Contents

• Features
• Quick Start
• Current Limitations
• Project Structure
• Configuration
• Testing
• Documentation
• Contributing
• Security
• License

Features

Core Capabilities

• Bond Valuation: DCF, YTM (Newton-Raphson), duration, convexity, and credit spread adjustments
• Bond Types: Zero Coupon, Fixed Rate, Floating Rate, Treasury, Corporate, Municipal, High Yield
• Arbitrage Detection: Configurable profit threshold detection for mispriced bonds
• Risk Analytics: VaR (3 methodologies), credit risk, liquidity risk, tail risk (CVaR)
• ML-Enhanced Pricing: Multiple model types with hyperparameter tuning and ensemble methods
• Portfolio Analytics: Portfolio optimization (Markowitz, Black-Litterman, risk parity)

Advanced Features (Implementation Status Varies)

• Option-Adjusted Spread (OAS): Basic implementation for bonds with embedded options
• Multi-Curve Framework: Yield curve modeling with discounting and forwarding curves
• Factor Models: PCA-based risk attribution
• Backtesting: Historical strategy validation framework
• ML Operations: MLflow integration for experiment tracking
• Explainable AI: SHAP values and feature importance

See ROADMAP.md for detailed feature status and planned improvements.

Quick Start

Installation

Option 1: Docker (Recommended)

git clone https://github.com/SafetyMP/BondTrader.git
cd BondTrader

# Configure environment
cp docker/.env.example docker/.env
# Edit docker/.env with your settings

# Start all services
make up
# Or: docker-compose -f docker/docker-compose.yml up -d

Access services:

• Dashboard: http://localhost:8501
• API: http://localhost:8000/docs
• MLflow: http://localhost:5000

Option 2: Local installation (library + tools)

git clone https://github.com/SafetyMP/BondTrader.git
cd BondTrader

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Reproducible env (matches CI)
pip install --upgrade pip
pip install -r requirements.lock

# Editable root package
pip install -e .

# REST API & v2 / contract tests need FastAPI + installable packages:
pip install -e ".[api,dev]"
pip install -e packages/bondtrader_domain -e packages/bondtrader_data \
            -e packages/bondtrader_ml -e packages/bondtrader_api

Alternate mutable pins: pip install -r requirements.txt (refresh lock with bash scripts/compile_requirements_lock.sh after changing top-level constraints). See CONTRIBUTING.md.

Note: Dependency set is large; some stacks (e.g. full ml extras) add heavy wheels. Docker remains the fastest path to a known-good stack.

Usage Examples

Python Library

from bondtrader.core import Bond, BondType, BondValuator, ArbitrageDetector
from bondtrader.ml import EnhancedMLBondAdjuster
from datetime import datetime, timedelta

# Create a bond
bond = Bond(
    bond_id="BOND-001",
    bond_type=BondType.CORPORATE,
    face_value=1000,
    coupon_rate=5.0,
    maturity_date=datetime.now() + timedelta(days=1825),
    issue_date=datetime.now() - timedelta(days=365),
    current_price=950,
    credit_rating="BBB",
    issuer="Example Corp",
    frequency=2
)

# Value the bond
valuator = BondValuator(risk_free_rate=0.03)
fair_value = valuator.calculate_fair_value(bond)
ytm = valuator.calculate_yield_to_maturity(bond)

print(f"Fair Value: ${fair_value:.2f}")
print(f"YTM: {ytm*100:.2f}%")

REST API

Start the API server:

python scripts/api_server.py
# Or: uvicorn scripts.api_server:app --reload

API available at http://localhost:8000 with interactive docs at /docs.

Example API Usage:

# Health check
curl http://localhost:8000/health

# Create a bond (authentication required if enabled)
curl -X POST "http://localhost:8000/bonds" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bond_id": "BOND-001",
    "bond_type": "CORPORATE",
    "face_value": 1000,
    "coupon_rate": 0.05,
    "maturity_date": "2029-12-31",
    "current_price": 950
  }'

Dashboard

streamlit run scripts/dashboard.py

Dashboard opens at http://localhost:8501.

See API Reference and User Guide for detailed documentation.

Current Limitations

This section provides an honest assessment of what's implemented, what's in progress, and what's planned.

Implementation Status

Fully Implemented:

• Core bond valuation (DCF, YTM, duration, convexity)
• Multiple bond types (Fixed Rate, Zero Coupon, Treasury, Corporate, etc.)
• Basic ML models (Random Forest, XGBoost, LightGBM)
• VaR calculations (3 methodologies)
• REST API with authentication
• Streamlit dashboard
• Docker containerization

Partially Implemented:

• Floating rate bonds (enum exists, pricing logic incomplete)
• Option-Adjusted Spread (OAS) - basic implementation, needs enhancement
• Portfolio optimization - Markowitz implemented, Black-Litterman incomplete
• Factor models - PCA exists but needs full integration
• Backtesting - framework exists, needs historical data integration
• Alternative data pipeline - framework only, not production-ready

Not Yet Implemented:

• Real-time market data integration (Bloomberg, Reuters)
• Full regulatory compliance framework (audit trails exist but need enhancement)
• Comprehensive day count conventions (currently assumes 30/360 or ACT/365.25)
• Advanced credit risk models (Merton structural model, reduced-form models)
• Production-scale performance benchmarks
• Horizontal scaling architecture

Known Issues

• Dependencies: Large dependency list (60+ packages) may cause conflicts. Some optional dependencies require system-level libraries (e.g., QuantLib requires C++).
• Test Coverage: Current test coverage is ~46% (target: 60%). Some modules have lower coverage than others.
• Performance: No comprehensive performance benchmarks. Performance characteristics not measured for large portfolios (>1000 bonds).
• Data Validation: Market data validation is basic. Users should validate data quality before use.
• Model Risk: ML models are trained on synthetic/historical data. Real-world performance may vary.
• Documentation: Some advanced features lack detailed usage examples.

Production Readiness Considerations

Before deploying to production:

1. Security Audit: Conduct a security review. Authentication and rate limiting exist but haven't undergone professional security audit.
2. Performance Testing: Benchmark with your expected workload and data volumes.
3. Data Integration: Integrate with your market data providers. Current implementations are examples.
4. Regulatory Compliance: Review compliance requirements. Audit trails exist but may need enhancement for your jurisdiction.
5. Monitoring: Set up monitoring and alerting. Prometheus/Grafana configs exist but need customization.
6. Backup & Recovery: Implement backup strategies for PostgreSQL data and trained ML models.

Scaling Limitations

• Single-Node Design: Current architecture assumes single-node deployment. Horizontal scaling requires architectural changes.
• Database: PostgreSQL setup is basic. Production deployments should consider connection pooling, read replicas, and tuning.
• ML Model Serving: Models are loaded in-memory. Large model serving requires additional infrastructure.
• API Rate Limits: Rate limiting is per-IP in-memory. Distributed rate limiting (Redis-based) is not yet implemented.

See ROADMAP.md for planned improvements and docs/development/COMPETITIVE_ANALYSIS.md for detailed feature gaps.

Project Structure

BondTrader/
├── bondtrader/              # Legacy application package (core, ml, risk, analytics, data, utils)
├── packages/                # Installable wheels: bondtrader_domain, bondtrader_data, bondtrader_ml, bondtrader_api
├── apps/dashboard/           # Streamlit-specific dashboard adapters (auth wrappers)
├── scripts/                 # Entrypoints (API server, dashboard, training, OpenAPI export)
│                            # CI OpenAPI artifact: scripts/export_openapi_fixed.py
├── tests/
│   ├── contract/           # Golden parity (+ pytest -m contract)
│   ├── unit/               # Unit tests (pytest -m unit)
│   ├── integration/        # Pipelines (pytest -m integration)
│   ├── smoke/              # Smoke (pytest -m smoke)
│   ├── property/           # Hypothesis property tests
│   ├── load/ chaos/ benchmarks/   # Scheduled in CI (.github/workflows/extended-tests.yml)
│   └── fixtures/golden/    # Versioned JSON contract expectations
├── docs/                    # adr/, api/, development/, guides/, QUALITY_GATES.md
├── docker/                  # Compose + observability configs
├── historical_data/ sample_data/  # Illustrative datasets (see docs + CONTRIBUTING)
└── requirements.lock        # Locked deps for CI and reproducible installs

Canonical layout, import rules, and data policy: docs/ORGANIZATION.md.

Configuration

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Essential Configuration:

# API Security
API_KEY=your_secret_api_key_here
REQUIRE_API_KEY=false  # Set to true to enable authentication
CORS_ALLOWED_ORIGINS=http://localhost:8000,http://localhost:8501

# Rate Limiting
API_RATE_LIMIT=100  # Requests per window
API_RATE_LIMIT_WINDOW=60  # Window in seconds

# External Data Sources (Optional)
FRED_API_KEY=your_fred_api_key  # For Federal Reserve data
FINRA_API_KEY=your_finra_api_key  # For FINRA market data

# Application
DEFAULT_RFR=0.03  # Default risk-free rate
ML_MODEL_TYPE=random_forest
BOND_DB_PATH=./data/bonds.db

Note: The system works with simulated data without API keys. External API keys are only needed for live market data.

Testing

Running Tests

# All tests
pytest tests/ -v

# Unit tests only
pytest tests/unit -m unit -v

# Integration tests
pytest tests/integration -m integration -v

# Contract parity (golden JSON)
pytest tests/contract -m contract -v

# Property-based tests (Hypothesis; also runs in CI)
pytest tests/property -q --tb=short

# With coverage report
pytest tests/ -v --cov=bondtrader --cov-report=html

Heavier load, chaos, and benchmark suites run on a weekly workflow (workflow_dispatch also).

Test Coverage

• Current: ~46% (varies by module)
• Target: 60%
• CI Threshold: 55% (enforced in CI/CD)

Coverage report available after running tests: open htmlcov/index.html

See tests/README.md for detailed testing documentation.

CI/CD

On push / PR (main, develop), CI:

• Installs requirements.lock, installs editable packages/*, runs contract tests (pytest tests/contract -m contract), property (tests/property), unit, smoke, integration on Python 3.10–3.12
• Lint/format: Black, isort, Ruff on bondtrader, scripts, tests, packages, apps; Flake8 (critical selectors + full report); Pyright on package src trees + apps/dashboard (docs/QUALITY_GATES.md)
• Coverage: Combined threshold on legacy + packages; stricter floors per package via scripts/ci_package_coverage.sh
• Security/SBOM: pip-audit on lockfile; Trufflehog (non-blocking optional); artifact upload for OpenAPI (Python 3.10 job)
• Extended: Weekly extended-tests.yml runs load, chaos, and benchmark suites (workflow_dispatch supported)

dependency-review.yml comments on dependency changes in PRs. Configuration: .github/workflows/ci.yml.

Documentation

Documentation is available in the docs/ directory:

Quick Links

• Quick Start Guide - Getting started
• User Guide - Complete usage guide
• API Reference - API documentation
• Architecture - System architecture
• Contributing Guide - How to contribute

Additional Documentation

• User guides (training data, historical data, drift detection)
• Development docs (architecture, competitive analysis)
• Technical analysis reports

See docs/README.md for complete index.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Development Setup

1. Fork and clone the repository
2. Create a virtual environment (python -m venv .venv and activate it).
3. Install locked deps and extras as in Option 2: Local installation.
4. Optional: pre-commit install

Code Quality

Before submitting a PR:

• Tests: pytest tests/ and pytest tests/contract -m contract when valuation, goldens, or /v2 change (CONTRIBUTING.md)
• Format: black bondtrader/ scripts/ tests/ packages/ apps/ (line length 127)
• Imports: isort bondtrader/ scripts/ tests/ packages/ apps/ (black profile)
• Lint: ruff check bondtrader scripts tests packages apps
• Types: pyright (see QUALITY_GATES; legacy bondtrader/ is gradually typed via mypy in CI)

Security

Security Features

• API Authentication: Bearer token authentication (optional, configurable)
• Rate Limiting: Per-IP rate limiting (in-memory, configurable)
• CORS Protection: Configurable CORS policies
• Input Validation: Basic input validation and path traversal prevention
• Secrets Management: Support for encrypted file storage, AWS Secrets Manager, HashiCorp Vault
• Audit Logging: Basic audit trails for operations

Security Considerations

• Authentication is optional by default. Enable REQUIRE_API_KEY=true for production.
• Rate limiting is per-IP in-memory. For distributed deployments, implement Redis-based rate limiting.
• Secrets management requires configuration. No default credentials.
• Security features exist but haven't undergone professional security audit.

Security Disclosure: Report vulnerabilities through SECURITY.md.

Architecture & Design Patterns

BondTrader uses common software design patterns:

• Service Layer: Business logic separation
• Repository Pattern: Data access abstraction
• Result Pattern: Type-safe error handling
• Circuit Breaker: Resilience for external dependencies
• Factory Pattern: Object creation abstraction

See docs/development/ARCHITECTURE.md for details.

• Python: 3.10+ (pyproject.toml)
• Web: FastAPI + Uvicorn (optional [api] extra), Streamlit (dashboard)
• Core numerics: NumPy, pandas, SciPy, statsmodels; optional numba hot paths
• ML (optional extras): scikit-learn, XGBoost, LightGBM, CatBoost, Optuna, MLflow, SHAP
• Data & ops: SQLAlchemy, Alembic, Redis, Dask; PostgreSQL in Docker paths
• Quality: pytest, pytest-cov, Hypothesis (property tests), Ruff, Black, Pyright, Mypy (gradual on legacy)

Install dev tools: pip install -e ".[dev]" after the core lock install.

License

Apache License 2.0 - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Repository: https://github.com/SafetyMP/BondTrader

Roadmap

See ROADMAP.md for planned features and improvements.

Disclaimer

BondTrader is provided as-is for education and research. Before any production or regulated use: validate against your data and policies, engage qualified finance and engineering review, and implement security, monitoring, and compliance appropriate to your environment.

The authors and contributors are not liable for losses or damages from use of this software.