If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lballabio/QuantLib shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 11 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lballabio/QuantLib repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lballabio/QuantLib.

What it runs against: a local clone of lballabio/QuantLib — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lballabio/QuantLib | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lballabio/QuantLib. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lballabio/QuantLib.git
#   cd QuantLib
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lballabio/QuantLib and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lballabio/QuantLib(\\.git)?\\b" \\
  && ok "origin remote is lballabio/QuantLib" \\
  || miss "origin remote is not lballabio/QuantLib (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "QuantLib/ql/quantlib.hpp" \\
  && ok "QuantLib/ql/quantlib.hpp" \\
  || miss "missing critical file: QuantLib/ql/quantlib.hpp"
test -f "QuantLib/ql/math" \\
  && ok "QuantLib/ql/math" \\
  || miss "missing critical file: QuantLib/ql/math"
test -f "QuantLib/ql/instruments" \\
  && ok "QuantLib/ql/instruments" \\
  || miss "missing critical file: QuantLib/ql/instruments"
test -f "QuantLib/ql/pricingengines" \\
  && ok "QuantLib/ql/pricingengines" \\
  || miss "missing critical file: QuantLib/ql/pricingengines"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lballabio/QuantLib"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

QuantLib is a comprehensive C++ library for quantitative finance that provides tools for modeling, pricing, and risk management of financial instruments. It implements pricing models, interest rate curves, bond analytics, option valuation (Black-Scholes, lattice methods), Monte Carlo simulation, and portfolio optimization—enabling institutions to build trading and risk management systems without implementing these algorithms from scratch. Monolithic C++ library organized by domain: ql/ directory contains subdirectories for instruments/, pricingengines/, termstructures/, quotes/, methods/, math/, time/, cashflows/. Build system supports three paths: autotools (Makefile), CMake (modern preference per workflows), and MSVC project files (.ci/VS*.props). Extensive CI matrix (.github/workflows/) tests across compiler versions and configurations; .clang-format enforces code style.

Quantitative analysts, financial engineers, and risk managers at banks, hedge funds, and asset managers who need production-grade implementations of derivatives pricing, fixed income analytics, and portfolio risk calculations. Also academic researchers and open-source fintech developers building systems that require sophisticated financial models.

Production-ready and actively maintained. The library has 13+ years of development history, comprehensive GitHub Actions CI/CD across Linux/Windows/macOS/CMake, 60+ workflow files showing rigorous testing (CodeQL, Coveralls, sanitizers, tidy checks), and frequent releases. Large C++ codebase (33.5M lines) with BSD 3-Clause license and active community via mailing lists.

Low risk for adoption but requires C++ expertise: primary surface is C++, though SWIG bindings exist. Monolithic library means changes to core algorithms affect many downstream uses. Single primary maintainer (Luigi Ballabio) creates single-person bottleneck for release decisions. Requires careful version pinning since financial calculations are sensitive to algorithm changes, and breaking API changes have occurred in major releases.

Active continuous development visible in extensive GitHub Actions workflows: daily builds across Linux/macOS/MSVC, code quality checks (Codacy, CodeQL, clang-tidy), automated copyright/license validation, version numbering automation, and documentation generation (Doxygen). Recent workflow additions show investment in coverage (Coveralls integration) and sanitizer testing (LSAN), indicating focus on correctness and memory safety.

Clone and build using CMake (modern standard): git clone https://github.com/lballabio/QuantLib.git && cd QuantLib && mkdir build && cd build && cmake .. && cmake --build . && ctest. Alternatively, use autotools: ./configure && make && make test. Windows: use Visual Studio via provided .props files in .ci/ or CMake generator.

Daily commands: For library only (non-interactive): build via CMake then link against libQuantLib. For testing: cd build && ctest (runs test suite). No server/daemon mode—QuantLib is a linkable library. Python bindings (if built): import QuantLib after installation.

• CMakeLists.txt — Primary build configuration for the entire C++ library; all contributors must understand the build system and how to add new modules.
• QuantLib/ql/quantlib.hpp — Main include file that exposes the public API surface; essential for understanding what gets exported and how the library is organized.
• QuantLib/ql/math — Core mathematical utilities and numerical methods that underpin pricing engines and financial calculations throughout the library.
• QuantLib/ql/instruments — Financial instrument definitions (bonds, options, swaps) forming the domain model that all pricing and analytics depend on.
• QuantLib/ql/pricingengines — Engine implementations for instrument valuation; critical extension point where most new pricing models are added.
• QuantLib/ql/termstructures — Yield curve and volatility surface abstractions; foundational for risk-free rate and market data modeling.
• QuantLib/ql/processes — Stochastic process definitions (Black-Scholes, CIR, etc.) that drive Monte Carlo simulations and analytical pricing.

Add a New Financial Instrument

1. Create instrument header in QuantLib/ql/instruments/ defining the contract terms and cash flow generation logic (QuantLib/ql/instruments/[newinstrument].hpp)
2. Inherit from QuantLib/ql/instrument.hpp and implement performCalculations() to set NPV (QuantLib/ql/instrument.hpp)
3. Create pricing engine(s) in QuantLib/ql/pricingengines/[instrument]/ with an engine class inheriting from PricingEngine (QuantLib/ql/pricingengines/[instrument]/[method]engine.hpp)
4. Register engine in CMakeLists.txt and add test case in test suite referencing the new instrument (CMakeLists.txt)

Add a New Stochastic Process

1. Create process class in QuantLib/ql/processes/ inheriting from StochasticProcess, implement drift() and diffusion() (QuantLib/ql/processes/[newprocess].hpp)
2. Implement pathGenerator() or override expectation() for analytical solutions if available (QuantLib/ql/processes/[newprocess].hpp)
3. Create corresponding pricing engines in QuantLib/ql/pricingengines/ that use the new process (QuantLib/ql/pricingengines/[instrument]/[newprocess]engine.hpp)
4. Add CMake entries and unit tests validating drift/diffusion and Monte Carlo sample paths (CMakeLists.txt)

Add a New Term Structure (Curve)

1. Create curve class in QuantLib/ql/termstructures/ inheriting from TermStructure and implement discountFactor(), zeroRate(), or forward() (QuantLib/ql/termstructures/[newcurve].hpp)
2. Define bootstrap or interpolation logic to construct the curve from market quotes and rates (QuantLib/ql/termstructures/[newcurve].hpp)
3. Add curve observer pattern using QuantLib/ql/quote.hpp to handle market data updates (QuantLib/ql/termstructures/[newcurve].hpp)
4. Register in CMakeLists.txt, test with real and synthetic market data in test suite (CMakeLists.txt)

Add a New Pricing Engine Method

1. Create engine class in QuantLib/ql/pricingengines/[instrument]/[method]/ inheriting from appropriate engine interface (QuantLib/ql/pricingengines/[instrument]/[method]engine.hpp)
2. Implement calculate() method performing valuation using the chosen method (analytical, binomial, PDE, Monte Carlo) (QuantLib/ql/pricingengines/[instrument]/[method]engine.hpp)
3. Leverage QuantLib/ql/math/ for numerical operations and QuantLib/ql/processes/ for dynamics (QuantLib/ql/pricingengines/[instrument]/[method]engine.hpp)
4. Add comprehensive tests comparing against benchmarks, analytical solutions, or other engines in test suite (CMakeLists.txt)

• C++ — High-performance numerical computing essential for real-time pricing and risk calculations; Boost and STL provide mature abstractions
• CMake — Cross-platform build system supporting Windows (MSVC), Linux (GCC), and macOS (Clang) with unified configuration
• Observer pattern (Handles) — Enables lazy re-evaluation and caching when market data or settings change without explicit invalidation
• Template metaprogramming — Compile-time specialization for numerical methods (Monte Carlo, PDE, binomial) reduces runtime overhead
• GitHub Actions CI — undefined

No mandatory external dependencies (by design), but SWIG optional build requires Boost headers present. CMake vs. autotools: .github/workflows/ prioritizes CMake but autotools still supported; mixing build systems on same source tree causes rebuild issues. Test suite is large and slow (test-times workflow tracks this); CI runs full suite on each PR. Platform-specific: .ci/*.props files are Windows-only; Linux/macOS use CMake + autotools. Version pins critical: QuantLib makes no guarantees about numerical stability across versions, so production code must pin exact library version. The library uses aggressive inlining and templates; debug builds are slow; release builds mandatory for performance evaluation.

• Term Structure (Yield Curve) — Foundation of fixed-income valuation and discount factor calculation—nearly every pricing model in QuantLib depends on forward/zero curves, making this QuantLib's most critical abstraction
• Option Pricing: Black-Scholes vs. Lattice Methods — QuantLib implements both analytical (BS) and numerical (tree, finite-difference) pricing; understanding when each applies is essential for using the right pricing engine for different instrument/scenario combinations
• Monte Carlo Simulation for Path-Dependent Derivatives — Critical for pricing exotic options, callable bonds, and path-dependent exotics; QuantLib's ql/methods/montecarlo/ implements variance reduction techniques (antithetic sampling, control variates) that dramatically affect convergence
• Interest Rate Models (Hull-White, LMM, Vasicek) — QuantLib implements multiple stochastic interest rate models in ql/models/rates/; choosing the right model for an asset class is non-obvious and affects pricing accuracy significantly
• Day Count Conventions and Calendar Adjustments — ql/time/ enforces complex financial conventions (Actual/360, 30/360, business day adjustments) that look trivial but are critical for settlement and coupon calculations across markets
• Factory Pattern for Pricing Engine Construction — QuantLib uses factories extensively to decouple instrument definition from pricing strategy; understanding this pattern is essential to extend the library with new models
• Volatility Smile and Stochastic Volatility Models — ql/termstructures/volatility/ implements local vol and stochastic vol (Heston); these are essential for realistic option pricing beyond Black-Scholes' constant-vol assumption

• klauer/QuantLib-Python — Community-maintained Python bindings for QuantLib with recent updates; primary way Python developers use this library
• test-ipynb/QuantLib-Notebooks — Educational Jupyter notebooks demonstrating QuantLib pricing workflows and examples in Python
• finmath-lib/finmath-lib — Java-based alternative for quantitative finance with similar scope (pricing, risk, curves) for JVM environments
• lballabio/QuantLib-SWIG — Official SWIG interface definitions enabling language bindings (Python, R, .NET, Java) from QuantLib C++ core

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for Python bindings CI

QuantLib has extensive Python bindings but there's no dedicated CI workflow for testing them. The .github/workflows directory shows comprehensive C++ testing (linux.yml, msvc.yml, macos.yml) but no Python-specific validation. This would catch binding issues early and ensure the Python API remains functional across releases.

• [ ] Create .github/workflows/python-bindings.yml workflow file
• [ ] Add steps to build SWIG Python bindings on Linux/macOS/Windows
• [ ] Add pytest execution for Python test suite (if tests exist in ql/python/test/ or similar)
• [ ] Integrate with setup.py/pyproject.toml for installation testing
• [ ] Add to README badges for Python binding build status

Add integration tests for CMake cross-platform builds

The repo has both CMakeLists.txt and CMakePresets.json but the existing workflows (.github/workflows/cmake.yml, cmake-latest-runners.yml) don't validate preset configurations comprehensively. A dedicated workflow testing multiple preset combinations would prevent broken CMake configurations from merging.

• [ ] Create .github/workflows/cmake-presets-validation.yml
• [ ] Test each preset in CMakePresets.json on appropriate runners (VS2019, VS2022, clang, gcc)
• [ ] Validate both Release and Debug configurations
• [ ] Add configuration validation tests for different feature flags (e.g., WITH_UNITY_BUILD)
• [ ] Document preset usage in docs or CONTRIBUTING.md

Create missing Doxygen documentation for public API in Docs/pages/

The file structure shows Docs/pages/ exists with some documentation (config.docs, currencies.docs, datetime.docs, engines.docs) but coverage appears incomplete. Analyzing QL headers against existing .docs files would identify API modules lacking documentation pages, improving maintainability.

• [ ] Audit QuantLib/ql/ directory structure against existing Docs/pages/*.docs files
• [ ] Create missing .docs files for undocumented modules (e.g., if instruments, pricingengines, or math modules lack coverage)
• [ ] Add cross-references and code examples to new .docs files following existing format in config.docs/engines.docs
• [ ] Update Docs/pages/coreclasses.docs to reference new documentation pages
• [ ] Run Doxygen locally (.github/workflows/doxygen.yml) to validate generated output

• Add unit tests for the newly added credit derivatives models in ql/instruments/creditderivatives/ (currently sparse test coverage in test-suite/creditderivatives/ compared to vanilla instruments)
• Implement missing documentation/Doxygen comments for ql/math/ namespace functions, particularly in convexity.hpp and optimization routines, to improve API discoverability
• Add CMake cross-compilation support validation by testing builds for ARM64/mingw targets and documenting results (currently workflows test x86_64 Linux/macOS/Windows only)

QuantLib demonstrates a generally solid security posture with comprehensive CI/CD pipelines, automated dependency management via Dependabot, and static analysis tools (.clang-tidy, .lgtm.yml, MSVC analysis). The codebase is a well-maintained open-source library with good build and test infrastructure. No critical vulnerabilities were identified from the visible file structure. Primary concerns are around ensuring CI/CD configurations don't inadvertently expose secrets, and that code analysis rules are properly configured for maximum security coverage. As a C++ financial library, memory safety and numerical stability should remain top development priorities. Recommendations include regular audits of analysis rule configurations and continued reliance on automated security scanning in CI/CD pipelines.

• Medium · Multiple CI/CD Pipeline Configuration Files — .github/workflows/. The repository contains numerous CI/CD workflow files (.github/workflows/) that may contain sensitive environment variables, secrets, or security tokens if misconfigured. These files are tracked in version control and publicly visible. Fix: Audit all workflow files to ensure no secrets are hardcoded. Use GitHub Secrets management for sensitive values. Implement branch protection rules and require reviews for workflow modifications.
• Low · Potential Code Quality Analysis Configuration — .lgtm.yml, .clang-tidy. The repository uses .lgtm.yml and .clang-tidy configuration files which may contain rules that could be bypassed or misconfigured, potentially allowing unsafe code patterns to pass analysis. Fix: Regularly review and update static analysis configurations. Ensure strict security-focused rules are enabled in clang-tidy. Document why any rules are disabled.
• Low · MSVC Analysis Ruleset Configuration — .msvc-analysis.ruleset. The .msvc-analysis.ruleset file may have security-related rules disabled or configured with low severity, potentially missing security issues in Windows builds. Fix: Review the ruleset to ensure all security-related checks (CWE, CERT) are enabled with appropriate severity levels. Consider enabling maximum security strictness.
• Low · Leak Sanitizer Configuration — .lsan.txt. The .lsan.txt file may contain suppressions for memory leaks that could mask genuine security issues if overly broad. Fix: Review suppression patterns to ensure they are specific and necessary. Avoid blanket suppressions that could hide real memory safety issues.
• Low · Dependency Management via Dependabot — .github/dependabot.yml. While Dependabot integration (.github/dependabot.yml) is good practice, the effectiveness depends on proper configuration and timely review of automated PRs. Fix: Ensure Dependabot is configured to check all dependency types. Set up automatic review and merging policies for patch updates. Monitor security advisories closely.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.