GO — Healthy across the board

• Last commit 2w ago
• 33+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• MIT licensed
• CI configured
• Tests present

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

Qlib is an AI-powered quantitative investment research platform that automates the entire workflow from idea exploration to production deployment. It provides a unified framework supporting supervised learning, reinforcement learning, and market dynamics modeling, and integrates with RD-Agent for LLM-based autonomous factor mining and model optimization. Monolithic Python package structure with qlib/ as main source root, supporting multiple modeling paradigms (supervised learning, RL via Tianshou, market dynamics). Includes data handling layer (likely in qlib/data/), strategy/portfolio management, backtesting engine, and feature engineering modules. Cython extensions for performance-critical components (.pyx files). Examples and docs in docs/, workflows in .github/workflows/, Docker support via Dockerfile for reproducible environments.

Quantitative researchers and algorithmic traders who need to build, backtest, and deploy ML-driven trading strategies without reinventing data pipelines, feature engineering, and backtesting infrastructure. Also targets fintech teams wanting to automate the factor discovery and model optimization R&D loop.

Production-ready and actively developed: 2.4M lines of Python, 400+ commits in recent workflows, comprehensive CI/CD via GitHub Actions (test_qlib_from_source, test_qlib_from_pip, slow tests), published on PyPI as pyqlib with version badges, and official ReadTheDocs documentation. Recent major addition is RD-Agent integration (2025) with published research paper, indicating active innovation.

Moderate risk: heavy dependency on NumPy, SciPy, scikit-learn, pandas, and Cython (data science stack); Cython compilation can fail on some platforms. Single organizational owner (Microsoft) with no indication of multi-vendor governance. No visible open issue count or PR backlog in provided data. Breaking changes are possible given active feature development (RL framework, RD-Agent additions).

Active integration of RD-Agent (released 2025) for autonomous factor mining and model optimization. Recent releases tracked via .github/workflows/release.yml, with version history in CHANGELOG.md and CHANGES.rst. Linting and code quality enforced via .pylintrc, mypy type checking (.mypy.ini), pre-commit hooks, and commit message linting (.commitlintrc.js). Platform expansion: supporting Linux, Windows, macOS per PyPI badges.

git clone https://github.com/microsoft/qlib.git && cd qlib && pip install -e . (or pip install pyqlib for PyPI release). For development: review setup.py in root (not shown but implied by MANIFEST.in), ensure Python 3.7+ (per PyPI badges), and Cython/CMake installed (in dependencies). Docker: bash build_docker_image.sh for containerized environment.

Daily commands: After pip install -e ., use qlib CLI or Python scripts; see docs/_static/demo.sh for example workflows. For development server: Makefile likely contains test/build targets (visible in file list). Backtesting: instantiate a Strategy with trained model, call Portfolio.backtest() with market data. Example notebooks likely in examples/ (not listed but typical for research repos).

• qlib/__init__.py — Package entry point defining Qlib's public API and initialization flow for the quantitative investment platform
• qlib/data — Core data layer handling market data loading, caching, and feature engineering—foundational to all modeling tasks
• qlib/model — Abstract model interfaces and base classes for supervised learning, RL, and market dynamics paradigms
• qlib/workflow — Orchestration engine coordinating data preparation, model training, backtesting, and result analysis pipelines
• setup.py — Build and dependency configuration; defines Cython extensions and core package metadata required for installation
• docs/conf.py — Documentation generation and configuration; essential for understanding how to navigate and extend docs

• Data Provider (Pandas, NumPy, Cython) — Abstracts market data source (CSV, database, API); handles OHLC normalization, feature engineering, and caching

Add a New Data Provider

1. Create a new provider class inheriting from qlib.data.base.DataProvider (qlib/data/__init__.py)
2. Implement required methods: load_data, query, and get_instruments (qlib/data/base.py)
3. Register provider in qlib's global provider registry via qlib.data.register (qlib/data/__init__.py)
4. Add integration tests and document provider configuration in docs (docs/component/data.rst)

Add a New ML Model

1. Create model class inheriting from qlib.model.base.BaseModel (qlib/model/__init__.py)
2. Implement fit(), predict(), and score() methods (qlib/model/base.py)
3. Integrate with workflow by adding model configuration in experiment YAML (docs/component/model.rst)
4. Add model to workflow's model registry for task assignment (qlib/workflow/__init__.py)

Build a New Analysis Metric

1. Create metric class in qlib/analysis module inheriting from base analyzer (qlib/analysis/__init__.py)
2. Implement compute() method calculating metric from predictions and labels (qlib/analysis/base.py)
3. Register metric in analysis manager for automated reporting (qlib/analysis/report.py)
4. Add visualization in report component (plot methods) (docs/component/report.rst)

Create a Custom RL Environment

1. Define environment class inheriting from qlib/component/rl base environment (qlib/component/rl/env.py)
2. Implement step(), reset(), and reward calculation matching Tianshou interface (qlib/component/rl/base.py)
3. Configure agent and environment in RL task YAML (docs/component/rl/quickstart.rst)
4. Register with Qlib's RL manager for task scheduling (qlib/component/rl/__init__.py)

• Tianshou (RL framework) — Provides modular, production-ready RL algorithms (DQN, PPO, A3C) and integrates seamlessly with market simulators for portfolio optimization
• Cython (C extensions) — Accelerates data loading, feature engineering, and backtest simulation which are IO-heavy and require tight loops
• Pandas/NumPy — Standard for financial time-series manipulation, OHLC aggregation, and vectorized feature computation across instruments
• Scikit-learn — Provides baseline ML models (Linear, Tree-based) and cross-validation utilities for supervised learning baselines
• Sphinx + RTD Theme — Scales documentation for complex research APIs and enables hosted docs at readthedocs.org for accessibility

• Workflow YAML-driven (not pure Python API)

  • Why: Enables non-programmers (quants) to compose experiments and encourages reproducibility through config-as-code
  • Consequence: Adds config validation overhead but reduces boilerplate; requires schema version management

• Persistent disk cache for market data

  • Why: Avoids re-downloading/recomputing expensive market data across experiments
  • Consequence: Trades disk space (~GB per instrument-year) for reduced latency and network load; requires cache invalidation strategy

• Decoupled model interfaces (supervised, RL, market-dynamics)

  • Why: Allows independent development of modeling paradigms without forcing one abstraction
  • Consequence: Higher code duplication in training loops; adds integration testing burden

• Online prediction separate from training

  • Why: Supports real-time serving and incremental learning in production
  • Consequence: Requires dual code paths (offline training vs. online inference); risk of train-serve skew

• Real-time tick-level market data ingestion (supports daily/minute OHLC, not sub-millisecond)
• Automated portfolio rebalancing in live markets (backtest-only, not a broker integration)
• Proprietary data source licensing (delegates to providers; users supply credentials)
• GPU acceleration for training (CPU-based, though TensorFlow/PyTorch models supported)
• Multi-asset class derivatives pricing (equities focus; FX/bonds via custom models)

Cython modules require compilation on first install (pip install -e . builds .pyx files); may fail without cmake/gcc on Windows—use pre-built wheels when available. Time-series data requires aligned DatetimeIndex in pandas DataFrames; misaligned indices cause silent NaN propagation in backtests. Market microstructure assumptions (e.g., filling logic, transaction costs) are embedded in Portfolio/Executor classes; changing them requires understanding data pipeline ordering. RD-Agent integration may have undocumented LLM API dependencies (OpenAI, etc.) not listed in core requirements.

• Rolling Window Backtesting — Core backtesting methodology in Qlib; you must understand train/validation/test window alignment to avoid lookahead bias and overfitting in time-series models
• Factor Engineering & Alpha Generation — Central to Qlib's feature engineering layer; knowledge of technical indicators, fundamental ratios, and factor construction is essential for building effective trading signals
• Portfolio Rebalancing & Transaction Cost Modeling — Qlib's backtest engine embeds realistic trading costs, slippage, and rebalancing constraints; ignoring these leads to overly optimistic returns
• Information Coefficient (IC) & Rank IC — Standard metrics in Qlib's analysis module for evaluating factor predictive power; IC > 0.05 is considered significant in quant research
• Cython JIT Compilation — Qlib uses Cython for performance-critical data processing (feature calculation, backtesting loops); understanding .pyx files is necessary for optimization contributions
• Market Microstructure & Order Execution — Qlib's Portfolio/Executor classes model order filling, market impact, and execution delays; misunderstanding these assumptions invalidates backtest results
• Reinforcement Learning for Portfolio Management — Qlib integrates Tianshou RL agents for learning dynamic trading policies; understanding MDP formulation in finance context is needed for RL-based strategies

• microsoft/RD-Agent — Official companion repo providing LLM-based autonomous agent for automated factor mining and model optimization; tightly integrated with Qlib as shown in README
• pytorch/rl — General-purpose RL library; Qlib uses Tianshou (built on PyTorch) for market dynamics modeling and RL agents
• scikit-learn/scikit-learn — Machine learning foundation used throughout Qlib for supervised learning models and feature transformations
• pandas-dev/pandas — Data structure and time-series manipulation backbone; all Qlib data pipelines and backtesting rely on pandas DataFrames and DatetimeIndex
• openai/gpt-discord-bot — Example of LLM integration pattern; Qlib's RD-Agent uses similar patterns for autonomous code generation and factor discovery

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 testing RL components with tianshou

The repo integrates tianshou for RL modeling and mentions RD-Agent integration, but there's no dedicated CI workflow testing RL-specific functionality. Currently, only general source/pip tests exist (.github/workflows/test_qlib_from_source.yml, test_qlib_from_pip.yml). A focused RL test workflow would catch regressions in the RL framework early, especially given the complexity of RL dependencies and the RL_framework.png diagrams in docs/_static/img/.

• [ ] Create .github/workflows/test_rl_components.yml with tianshou-specific tests
• [ ] Test RL model training/evaluation against sample market data
• [ ] Include tests for RD-Agent integration if applicable
• [ ] Ensure workflow runs on Python versions listed in README badges
• [ ] Document expected test runtime in .github/workflows/test_rl_components.yml comments

Add integration tests for Docker image building and runtime

The repo has Dockerfile and build_docker_image.sh but no CI workflow validating that the Docker image builds successfully or runs core functionality. This is critical for users wanting containerized deployments. Adding a workflow to build and test the Docker image would prevent broken image releases.

• [ ] Create .github/workflows/test_docker_build.yml
• [ ] Add steps to build the Docker image using build_docker_image.sh
• [ ] Run basic Qlib import and initialization tests inside the container
• [ ] Push to Docker registry on release (integrate with release.yml if applicable)
• [ ] Validate Python version and key dependencies (numpy, pandas, scikit-learn) are present

Add type hints validation and mypy configuration expansion

The repo has .mypy.ini configured but type checking isn't enforced in CI pipelines (not visible in .github/workflows/). Given the complexity of Qlib's ML modeling paradigms and the presence of diverse modules, adding mypy validation would improve code quality. Currently, only lint_title.yml exists for lint checks, missing static type validation.

• [ ] Create .github/workflows/mypy_check.yml to run mypy against qlib source directories
• [ ] Expand .mypy.ini with strict mode settings and ignore rules for third-party libraries
• [ ] Annotate high-value modules (e.g., core market dynamics modeling, feature extraction) with type hints
• [ ] Run mypy check on all Python versions in README to catch compatibility issues
• [ ] Document type checking requirements in CONTRIBUTING guidelines

• Add type hints to qlib/data/ loaders and DataProvider interfaces; currently likely missing .pyi stubs, breaking IDE autocomplete for data science users.
• Write integration tests for RD-Agent → Qlib factor discovery pipeline in tests/; currently no visible test coverage for the new R&D automation loop mentioned in recent README.
• Document Cython extension modules in docs/advanced/; .pyx files in qlib/ are performance-critical but lack API docs for contributors wanting to optimize compute-heavy steps (e.g., indicator calculation).

Failed to generate security analysis.

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

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

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/microsoft/qlib 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.

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

What it runs against: a local clone of microsoft/qlib — 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 microsoft/qlib | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 47 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/qlib. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/qlib.git
#   cd qlib
#
# 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 microsoft/qlib and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "qlib/__init__.py" \\
  && ok "qlib/__init__.py" \\
  || miss "missing critical file: qlib/__init__.py"
test -f "qlib/data" \\
  && ok "qlib/data" \\
  || miss "missing critical file: qlib/data"
test -f "qlib/model" \\
  && ok "qlib/model" \\
  || miss "missing critical file: qlib/model"
test -f "qlib/workflow" \\
  && ok "qlib/workflow" \\
  || miss "missing critical file: qlib/workflow"
test -f "setup.py" \\
  && ok "setup.py" \\
  || miss "missing critical file: setup.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 47 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~17d)"
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/microsoft/qlib"
  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).

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