Lumibot Trading Framework
Build, backtest, and run Python trading strategies with deterministic rules or AI trading teams.
- Source repo
- Lumiwealth/lumibot
- Stars
- ★ 2.2k
- Last updated
- 1d ago
- License
- GPL-3.0
- Primary language
- Python
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Python trader who wants to validate a buy rule on Yahoo historical data for 2023–2024 before running the same class on Alpaca paper trading.
- Not a fit if
- Users who want a ready-made hosted service without configuring broker credentials
- Users expecting blanket support for every CCXT exchange
- Source review
- 57/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Lumibot is a Python algorithmic-trading framework that runs the same Strategy in historical backtests, paper trading, and broker-connected execution. Its documented interfaces include Strategy, Trader, Alpaca, and backtesting classes such as YahooDataBacktesting. The built-in AI agent runtime creates specialized agents inside a strategy loop; they can inspect market data, fundamentals, SEC filings, FRED data, indicators, and local memory, while authorized agents can submit orders. Agent runs can record memory, tool calls, decisions, orders, and other artifacts in local SQLite and Parquet files for review. The framework can be self-hosted, with BotSpot presented as an optional managed deployment path around Lumibot.
A developer subclasses Strategy, implements on_trading_iteration, creates orders with create_order, and submits them with submit_order. Strategy.backtest(YahooDataBacktesting, start, end) runs a strategy against historical data and simulated orders; paper or live execution constructs an Alpaca broker, adds the strategy to Trader, and calls trader.run_all(). AI strategies create agents with self.agents.create(name, model, allow_trading, system_prompt) and sequence them with self.agents[...].run(task_prompt, context) for research, bull, bear, and trading decisions; only agents with allow_trading=True may trade. Documented built-in tools cover market and account state, orders, DuckDB, documentation search, indicators, SEC, FRED, local memory, and Telegram notifications, and external MCP servers can be mounted.
- A Python trader who wants to validate a buy rule on Yahoo historical data for 2023–2024 before running the same class on Alpaca paper trading.
- A quant team that wants researcher, bull, bear, and portfolio-manager agents to build and challenge an ETF or stock trade decision in sequence.
- A developer who wants Python risk gates around agent research and inspect orders, logs, and backtest artifacts before connecting real capital.
- A strategy author selecting broker or data paths for stocks, options, crypto, futures, forex, or Polymarket prediction contracts.
- A researcher who wants DuckDB time-series analysis, local SQLite/Parquet agent memory, and traceability for the evidence behind a trade.
How do you install or deploy this agent?
Install with pip install lumibot. For source development, the documented command is pip install -r requirements_dev.txt && pip install -e .. The AI trading-team example needs a valid model-provider key; the README example uses GEMINI_API_KEY. Alpaca paper or live execution also requires ALPACA_API_KEY, ALPACA_API_SECRET, and optionally ALPACA_IS_PAPER=true.
How do you use this agent?
Create my_strategy.py, import Strategy from lumibot.strategies and YahooDataBacktesting from lumibot.backtesting, define on_trading_iteration, then call MyStrategy.backtest(YahooDataBacktesting, datetime(2023, 1, 1), datetime(2024, 1, 1)) and run python my_strategy.py. To use Alpaca, set ALPACA_API_KEY, ALPACA_API_SECRET, and ALPACA_IS_PAPER=true; construct Alpaca from the configuration dictionary, add MyStrategy(broker=broker) to Trader, and call trader.run_all(). For the AI team example, set GEMINI_API_KEY plus the Alpaca variables and run python ai_trading_team_bull_bear_leveraged_etf.py; setting IS_BACKTESTING = True in that file switches it to the example's Yahoo backtest path.
What are this agent's strengths and limitations?
- The same Strategy code path is documented for backtests, paper trading, and broker execution rather than only research or prompt demonstrations.
- Its AI runtime supports specialized multi-agent flows, read-only research agents, and trading permissions that can be combined with deterministic Python controls.
- Backtests and agent runs can retain SQLite and Parquet memory, orders, tool calls, and decision artifacts for auditability.
- The README documents multiple broker, market, and backtesting paths, including Alpaca, Interactive Brokers, Tradier, Schwab, options, futures, and Polymarket.
- Paper and live operation require the relevant broker credentials, while market data, routing, and execution depend on external network services.
- The AI-team example depends on a valid model-provider key; the project stops with a provider-key error if a key is absent or invalid.
- CCXT coverage is explicitly limited: the README lists selected automatic credential paths, manual setups, and backtesting examples rather than every exchange.
- The supplied licensing evidence conflicts: repository metadata says GPL-3.0, while the README badge and license section say MIT; adopters need to verify the LICENSE file.
How does this agent compare with similar options?
The README compares Lumibot with TradingAgents, ai-hedge-fund, OpenAlice, QuantDinger, OpenBB, and Qlib, positioning it around Python strategies, flexible agent teams, replayable decision review, and broker execution. It also compares Lumibot with Backtrader, Freqtrade, Zipline, Backtesting.py, Jesse, vectorbt, NautilusTrader, and Hummingbot, emphasizing same-code backtest/live operation, options support, an embedded AI runtime, and the BotSpot managed path.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Lumibot Trading Framework This agent | 57 · Major gaps | Library / SDKFree + model costs | ★ 2.2k | 1d ago | Python | Codex · Claude Code |
| Blave Agent | 87 · Good | Desktop appFreemium | ★ 307 | 1d ago | Python | Codex · Claude Code |
| Vibe-Trading | 64 · Some gaps | CLIFree + model costs | ★ 38k | 1d ago | Python | OpenAI API · Claude API |
| Alpaca Multi-Agent Trading Workbench | 48 · Major gaps | CLIFree + model costs | ★ 283 | 10d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README emphasizes paper trading before live, examples set PAPER=true, and AI agents default allow_trading=False, only trader agent can trade, reflecting least privilege. But no user confirmation mechanism found, data flow transparency only partial (e.g., agent context passing), sensitive data handling has SECURITY.md and .env loading, but no explicit encryption or redaction. Dependency security has CI and dependency list, but no vulnerability scanning mentioned. External effects (e.g., order submission) are clearly described, but rollback mechanism is absent. Source attribution has LICENSE and author info, but publisher unverified.
Evidence shows: README and example code are consistent, CI configuration is complete, dependency list is explicit, failure messages have examples (e.g., 'No price available'), but no error handling documentation.
Evidence shows: README clearly identifies target users (developers, traders), supports multiple asset classes and scenarios, capability boundaries are described (e.g., supported and unsupported assets), trigger conditions (e.g., trading signals) have examples, environment fit (e.g., Python versions, OS) is described.
Evidence shows: README structure is clear, installation instructions are simple, naming is stable (e.g., Strategy class), examples are abundant, but known limitations are not explicitly listed, license is GPL-3.0 (inconsistent with MIT badge in README), versioning/changelog not provided, maintenance responsibility has community links.
Evidence shows: Output usability (e.g., backtest reports, logs) is described, marginal value (e.g., AI agent teams) is compared, cost-benefit (e.g., BotSpot hosting) is mentioned, but no specific data provided.
Evidence shows: Claims in README are supported by code examples, but cross-source verification is insufficient (e.g., comparisons with other projects lack data), fact-inference separation is unclear (e.g., performance claims).
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- License inconsistency: README shows MIT badge, but LICENSE file is GPL-3.0, need to confirm actual license.
- Example strategy contains local absolute paths (e.g., /Users/robertgrzesik/...), which may leak development environment info and are not portable.
- Dependency list includes many large libraries, but no version pinning or security audit, posing supply chain risk.
- AI agents' trading permission is off by default, but users must ensure correct configuration to avoid unintended trades.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * v4.6.47 - Broker lifecycle, Kalshi discovery and backtest correctness by @grzesir in https://github.com/Lumiwealth/lumibot/pull/1266 Full Changelog: https://github.com/Lumiwealth/lumibot/compare/v4.6.46...v4.6.47View on GitHub ↗ -
Release notes excerpt
What's Changed * Release 4.6.46: current ProjectX quote startup by @grzesir in https://github.com/Lumiwealth/lumibot/pull/1265 Full Changelog: https://github.com/Lumiwealth/lumibot/compare/v4.6.45...v4.6.46View on GitHub ↗ -
Release notes excerpt
What's Changed * Release 4.6.45: terminal-safe SmartLimit and broker lifecycle recovery by @grzesir in https://github.com/Lumiwealth/lumibot/pull/1264 Full Changelog: https://github.com/Lumiwealth/lumibot/compare/v4.6.44...v4.6.45View on GitHub ↗
FAQ
Can it be used for live trading?
Can AI agents place orders on their own?
allow_trading=False; only the final trader agent with allow_trading=True can submit trades.Do backtests require a fresh model call every time?
Is BotSpot required?
pip install lumibot and a self-hosted Alpaca/Trader flow. BotSpot is an optional managed path for data, backtests, deployment, and monitoring.