WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 3 active contributors
• GPL-3.0 licensed
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ Scorecard: default branch unprotected (0/10)

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

Abu is an open-source Python quantitative trading system supporting stocks, options, futures, cryptocurrencies, and machine learning strategies. It provides a complete backtesting engine with alpha factor generation (ABuAlpha), position sizing (ABuBeta via Kelly criterion and ATR), and parallel stock/time-series picker workers for strategy discovery across Chinese and US markets. Modular monolith organized by responsibility: abupy/AlphaBu/ contains factor generation (ABuAlpha, ABuPickStock*, ABuPickTime*), abupy/BetaBu/ holds position sizing strategies (Kelly, ATR), abupy/CoreBu/ is the engine (ABu.py main class, ABuEnv config, ABuParallel distribution), abupy/CrawlBu/ fetches data via XQ API, abupy/DLBu/ integrates deep learning (Caffe-based). Workers use master-worker pattern for parallelism.

Quantitative traders and ML engineers in China who want to backtest algorithmic trading strategies on Chinese exchanges (A-shares, HSI) and US markets without paying for Bloomberg terminals; researchers exploring machine learning on time-series financial data.

Mature but aging: ~29MB of Python code suggests substantial codebase, but no visible recent commits in the provided data and the README references example notebooks suggesting documentation from ~2015-2018 era. Production use reported on actual markets (see abuquant.com AI reports), but active maintenance status unclear from snapshot.

Moderate risk: single large monolith (abupy/) with deep interdependencies between AlphaBu, BetaBu, CoreBu modules makes refactoring dangerous. Chinese-focused infrastructure (data from XQ API in CrawlBu) may have availability issues for non-CN users. No visible test directory structure in top 60 files. Legacy patterns (ABuDeprecated.py exists) indicate accumulated technical debt.

Currently serving live AI research reports on abuquant.com for 25+ instruments (Shanghai Index, gold, NASDAQ, Bitcoin, etc.). abupy_lecture and abupy_ui indicate active educational content. No specific PR or milestone data visible, but deployed system suggests stable production use rather than active feature development.

git clone https://github.com/bbfamily/abu.git
cd abu
pip install -e .  # Inferred from setup.py patterns
# or: python setup.py install

Refer to abupy_lecture/ directory for Jupyter notebooks with quickstart examples. See abuquant.com for live strategy reports.

Daily commands: No explicit Makefile/docker found in top 60. Start with example scripts in abupy_lecture/ directory or the 《量化交易之路》 book examples. Core entry: import abupy; abupy.run_backtest(...) per CoreBu/ABu.py patterns, or use abupy_ui web interface (location not detailed in file list).

• abupy/CoreBu/ABu.py — Main entry point and orchestrator for the quantitative trading system; all trading workflows flow through this core module.
• abupy/CoreBu/ABuBase.py — Base class hierarchy defining fundamental abstractions for all trading components (factors, positions, strategies).
• abupy/AlphaBu/ABuPickStockMaster.py — Master stock selection algorithm coordinator; critical for alpha factor selection and parallel execution.
• abupy/FactorBuyBu/ABuFactorBuyBase.py — Base class for all buy factor implementations; defines the contract for entry signal generation.
• abupy/FactorSellBu/ABuFactorSellBase.py — Base class for all sell factor implementations; controls exit signal generation and position management.
• abupy/BetaBu/ABuPositionBase.py — Position sizing and risk management abstraction; determines capital allocation across trades.
• abupy/CoreBu/ABuParallel.py — Parallel execution framework using multiprocessing; enables distributed backtesting and strategy optimization.

Add a New Buy Factor

1. Create a new class inheriting from ABuFactorBuyBase in a new file (abupy/FactorBuyBu/ABuFactorBuy[YourStrategy].py)
2. Implement required methods: should_buy(), fit() for signal generation logic (abupy/FactorBuyBu/ABuFactorBuy[YourStrategy].py)
3. Register your factor in the buy factor wrapper system (abupy/FactorBuyBu/ABuBuyFactorWrap.py)
4. Reference your factor in trading strategy by adding to factor list in ABu.py or strategy config (abupy/CoreBu/ABu.py)

Add a New Sell (Exit) Factor

1. Create a new class inheriting from ABuFactorSellBase in a new file (abupy/FactorSellBu/ABuFactorSell[YourStrategy].py)
2. Implement required methods: should_sell() for exit signal logic and fit() for calibration (abupy/FactorSellBu/ABuFactorSell[YourStrategy].py)
3. Register factor in sell factor registry (ABuFS.py) or add to strategy's sell factors list (abupy/FactorSellBu/ABuFS.py)
4. Integrate into trading workflow via strategy configuration or ABu.py (abupy/CoreBu/ABu.py)

Add a New Technical Indicator

1. Create a new indicator class inheriting from ABuNDBase in appropriate file (abupy/IndicatorBu/ABuND[YourIndicator].py)
2. Implement calc() method with numpy/pandas vectorized calculation over OHLC data (abupy/IndicatorBu/ABuND[YourIndicator].py)
3. Register indicator in the indicator registry (ABuND.py) (abupy/IndicatorBu/ABuND.py)
4. Use the indicator in buy/sell factors via ABuNDBase API for signal generation (abupy/FactorBuyBu/ABuFactorBuy[Strategy].py)

Add a New Position Sizing Strategy

1. Create a new class inheriting from ABuPositionBase (abupy/BetaBu/ABu[YourMethod]Position.py)
2. Implement the position_size() method to calculate shares based on risk parameters (abupy/BetaBu/ABu[YourMethod]Position.py)
3. Configure position strategy in strategy initialization or environment config (abupy/CoreBu/ABuEnv.py)
4. Pass the position strategy instance to trading orchestrator (abupy/CoreBu/ABu.py)

XqApi (XQ quotes provider) may have rate limits or region restrictions outside mainland China. Deep learning module (DLBu) requires Caffe installation; proto files indicate custom model architecture not auto-built. ABuEnv.py likely requires explicit market/symbol configuration before backtesting (no default universe visible). Legacy Python 2.7 patterns (ABuDeprecated.py) may conflict with Python 3.9+; verify compatibility. Parallel workers in AlphaBu spawn child processes—ensure sufficient RAM for large universes. Data cache/store location controlled by ABuStore.py; check disk space for multi-year history.

• Kelly Criterion for Position Sizing — Core component in abupy/BetaBu/ABuKellyPosition.py; mathematically optimal bet sizing given win rate and risk/reward, critical for long-term wealth growth in quantitative trading
• Average True Range (ATR) Risk Adjustment — Implemented in abupy/BetaBu/ABuAtrPosition.py; volatility-adaptive position sizing that prevents outsized losses in high-volatility regimes
• Alpha and Beta Separation — Core philosophy of Abu's architecture (separate ABuAlpha factor generation from ABuBeta position sizing); enables independent testing and optimization of return generation vs. risk management
• Master-Worker Pattern for Distributed Backtesting — Implemented in ABuPickStockMaster/Worker and ABuPickTimeMaster/Worker; parallelizes strategy evaluation across CPU cores to handle thousands of stocks/factors efficiently
• Time-Series Cross-Validation (Walk-Forward Analysis) — Implied by ABuPickTime* modules; prevents look-ahead bias when backtesting by ensuring model parameters are optimized on past data only before forward testing
• Multiprocessing for Python GIL Bypass — Explored in abupy/CoreBu/ABuParallel.py; Python's GIL blocks true parallelism in threads, so Abu uses process spawning (not threads) for CPU-bound backtest loops on multi-core systems
• Caffe Deep Learning Framework (Legacy) — DLBu/ module with .prototxt files suggests Caffe-based CNN image classification for technical analysis; understanding protobuf model definition essential for extending DL strategies

• vnpy/vnpy — Chinese open-source trading system with similar scope (backtesting, live trading, multiple asset classes) but modular architecture; comparison reference for position sizing and event-driven design
• quantopian/zipline — De facto Python backtesting engine for US equities with Pythonic API; Abu's architecture (master-worker, alpha/beta separation) partly mirrors Zipline's design
• QuantConnect/Lean — Cloud-based backtester supporting global assets including crypto; inspiration for Abu's multi-asset support (stocks/futures/options/crypto)
• bbfamily/abu_ml — Companion repo cited in README for 《机器学习之路》 examples; demonstrates ML feature engineering integrated with Abu's backtester
• pydata/pandas — Foundational dependency for Abu's time-series data handling; understanding DataFrame/Series patterns essential for extending AlphaBu and BetaBu

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 comprehensive unit tests for ABuPickBase.py and stock/time picker implementations

The AlphaBu module (ABuPickBase.py, ABuPickStockExecute.py, ABuPickStockWorker.py, ABuPickTimeExecute.py, ABuPickTimeWorker.py) lacks visible test coverage. These are core components for stock/time-based alpha strategy selection. Adding unit tests would catch regressions in picker logic, worker thread coordination, and master-worker communication patterns used across the quantitative trading pipeline.

• [ ] Create abupy/tests/AlphaBu/test_pick_base.py for ABuPickBase base class tests
• [ ] Create abupy/tests/AlphaBu/test_pick_stock_execute.py testing stock picker execution flow with mock data
• [ ] Create abupy/tests/AlphaBu/test_pick_time_execute.py testing time-based picker execution
• [ ] Add tests for worker/master synchronization patterns in ABuPickStockWorker and ABuPickTimeMaster
• [ ] Ensure tests cover edge cases like empty picks, concurrent execution, and strategy filtering

Add integration tests for position sizing strategies (ATR, Kelly, PT position classes)

The BetaBu module contains critical position sizing implementations (ABuAtrPosition.py, ABuKellyPosition.py, ABuPtPosition.py) that inherit from ABuPositionBase.py. These determine risk management and position allocation. Without integration tests, changes to position calculations or base class refactoring could silently break portfolio risk management across all trading strategies.

• [ ] Create abupy/tests/BetaBu/test_atr_position.py with tests for ATR-based position sizing under different volatility scenarios
• [ ] Create abupy/tests/BetaBu/test_kelly_position.py testing Kelly Criterion calculations with various win rates and profit factors
• [ ] Create abupy/tests/BetaBu/test_pt_position.py for profit-taking position strategy
• [ ] Add tests validating position constraints (max/min position sizes) across all position classes
• [ ] Create integration test showing position sizing across a simulated multi-trade sequence

Add CI/CD workflow for testing across Python versions with ABuParallel and external API mocking

The repo has parallel processing (ABuParallel.py) and external API crawling (CrawlBu/ABuXqCrawl.py, ABuXqApi.py) but no visible GitHub Actions workflow. This is critical because: (1) the joblib-based parallel backend needs testing on multiple Python versions, (2) external API calls (Xueqiu) should be mocked in CI to avoid rate limiting/network dependencies, and (3) the ExtBu bundled libraries (empyrical, futures, joblib) may have compatibility issues.

• [ ] Create .github/workflows/python-tests.yml running pytest on Python 3.8, 3.9, 3.10, 3.11
• [ ] Configure workflow to mock ABuXqApi calls using pytest-mock or responses library to avoid external API dependencies
• [ ] Add pytest configuration in pytest.ini or setup.cfg to auto-discover tests and generate coverage reports
• [ ] Set up workflow to test ABuParallel with both ThreadPoolExecutor and ProcessPoolExecutor backends
• [ ] Include linting checks for the main abupy package (excluding ExtBu bundled code) using flake8 or ruff

• No test directory visible in top 60 files—add pytest unit tests for abupy/CoreBu/ABuEnv.py configuration validation to prevent silent misconfiguration bugs: Medium
• ABuPickBase.py is a base class for stock/time pickers, but no docstrings or examples in top 60—write a tutorial Jupyter notebook demonstrating how to implement a custom alpha factor by extending ABuAlpha.py (analogous to the existing book examples): Easy-Medium
• CrawlBu only shows XQ API integration—add a data source adapter for another provider (e.g., yfinance for US stocks or tushare for A-shares) following the ABuXqCrawlImp pattern to reduce single-provider risk: Medium-Hard

• High · Potential Hardcoded Credentials in CrawlBu Module — abupy/CrawlBu/. The CrawlBu module contains XQ API integration (ABuXqApi.py, ABuXqConsts.py) which typically requires API credentials. Without visibility into these files, there is a significant risk that API keys, tokens, or authentication credentials may be hardcoded in the source code rather than managed through environment variables. Fix: Implement credential management using environment variables or a secure vault system. Use python-dotenv or similar for credential handling. Never commit API keys to version control. Implement pre-commit hooks to detect secrets.
• High · Outdated and Potentially Vulnerable Dependencies — abupy/ExtBu/. The codebase includes bundled third-party libraries (joblib, six, empyrical) that are vendored into ExtBu directory. These bundled dependencies may contain known vulnerabilities and are not receiving security updates. The specific versions are unknown, making it difficult to assess CVE exposure. Fix: Replace vendored dependencies with proper package management (pip, poetry). Pin specific versions in requirements.txt. Regularly run pip audit and safety check to identify vulnerable dependencies. Use tools like Dependabot for automated vulnerability scanning.
• High · Pickle Deserialization Risk — abupy/AlphaBu/. The presence of 'ABuPickStockExecute.py', 'ABuPickStockMaster.py', 'ABuPickStockWorker.py', 'ABuPickTimeExecute.py', 'ABuPickTimeMaster.py', and 'ABuPickTimeWorker.py' suggests use of Python's pickle module. Pickle is fundamentally insecure as it can execute arbitrary code during deserialization when processing untrusted data. Fix: Avoid pickle for serializing untrusted data. Use secure alternatives like JSON for data interchange, or use pickle.loads() only on trusted data with strict validation. If pickle is required, implement whitelisting of allowed classes via __reduce__ method restrictions or use jsonpickle with restricted types.
• Medium · Parallel Processing Without Security Context — abupy/CoreBu/ABuParallel.py. The presence of ABuParallel.py suggests use of multiprocessing/parallel execution. Without proper security context isolation, this could lead to privilege escalation, data leakage between processes, or injection attacks across process boundaries. Fix: Implement proper process isolation and security contexts. Validate all data passed between processes. Use secure IPC mechanisms. Avoid using multiprocessing.Manager() with untrusted input. Implement proper error handling and logging for parallel operations.
• Medium · Potential SQL Injection in Data Access Layer — abupy/CoreBu/ABuStore.py. The codebase handles financial data and trading operations. Without visibility into ABuStore.py and database interaction code, there is risk of SQL injection if dynamic queries are constructed with user input or market data without proper parameterization. Fix: Use parameterized queries/prepared statements for all database operations. Never concatenate user input directly into SQL queries. Use ORM frameworks like SQLAlchemy. Implement input validation and sanitization. Use principle of least privilege for database accounts.
• Medium · Missing Input Validation in Trading System — abupy/FactorBuyBu/, abupy/BetaBu/, abupy/AlphaBu/. A trading system processing market data, API requests, and user input (evident from file structure) without visible comprehensive input validation frameworks. This could allow malformed data to crash the system or trigger unexpected behavior. Fix: Implement comprehensive input validation for all user-supplied and external data. Validate types, ranges, formats, and business logic constraints. Use schema validation libraries like jsonschema or pydantic. Implement rate limiting and sanity checks on trading parameters.
• Medium · Unsafe Deserialization in Memory Caching — abupy/ExtBu/joblib/. The presence of joblib (used for caching and serialization) without visible secure configuration suggests potential unsafe deserialization of cached objects, especially if cache files are stored in shared locations. Fix: Configure joblib with safe serialization methods. Validate cache file integrity and location permissions. Use cryptographic signatures for cache files

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/bbfamily/abu 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 bbfamily/abu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bbfamily/abu.

What it runs against: a local clone of bbfamily/abu — 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 bbfamily/abu | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | 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 ≤ 134 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 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 "abupy/CoreBu/ABu.py" \\
  && ok "abupy/CoreBu/ABu.py" \\
  || miss "missing critical file: abupy/CoreBu/ABu.py"
test -f "abupy/CoreBu/ABuBase.py" \\
  && ok "abupy/CoreBu/ABuBase.py" \\
  || miss "missing critical file: abupy/CoreBu/ABuBase.py"
test -f "abupy/AlphaBu/ABuPickStockMaster.py" \\
  && ok "abupy/AlphaBu/ABuPickStockMaster.py" \\
  || miss "missing critical file: abupy/AlphaBu/ABuPickStockMaster.py"
test -f "abupy/FactorBuyBu/ABuFactorBuyBase.py" \\
  && ok "abupy/FactorBuyBu/ABuFactorBuyBase.py" \\
  || miss "missing critical file: abupy/FactorBuyBu/ABuFactorBuyBase.py"
test -f "abupy/FactorSellBu/ABuFactorSellBase.py" \\
  && ok "abupy/FactorSellBu/ABuFactorSellBase.py" \\
  || miss "missing critical file: abupy/FactorSellBu/ABuFactorSellBase.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 134 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~104d)"
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/bbfamily/abu"
  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.