agent-capital 0.1.1

Agent Capital CLI

Agent Capital

Agent Capital is a CLI-first, simulation-only quant operations lab for generating agent-assisted, data-verified multi-asset investment research reports.

Installation

Agent Capital uses a Python uv workspace and a Rust workspace crate exposed to Python through PyO3/maturin.

For end users after PyPI release, run the complete weekly cycle without cloning the repository:

uvx agent-capital weekly
uvx agent-capital weekly --lookback-days 365 --data-dir ~/.agent-capital
uvx agent-capital weekly --start 2026-01-01 --end 2026-06-30

The default data directory is ~/.agent-capital. It contains the market-data cache at ~/.agent-capital/prices.sqlite, the operating ledger at ~/.agent-capital/ledger.sqlite, and generated output under ~/.agent-capital/runs/.

Set these environment variables before running the weekly cycle:

• COINGECKO_API_KEY: CoinGecko market-data API key.
• FRED_API_KEY: FRED market-data API key.
• OPENAI_API_KEY: OpenAI API key for LLM-backed reports.
• AGENT_CAPITAL_OPENAI_MODEL: OpenAI model name for LLM-backed reports.

Scheduling is available on Linux and WSL only. It installs a cron entry, so the scheduled time uses the system cron timezone:

uvx agent-capital schedule install --weekday mon --time 09:00 --lookback-days 365
uvx agent-capital schedule status
uvx agent-capital schedule remove

Cron does not inherit environment variables exported only in an interactive shell. The API credentials and model name must exist in the cron job or cron daemon environment when the job starts. One operator-controlled method is to run crontab -e and add the required environment assignments outside the BEGIN/END AGENT CAPITAL WEEKLY managed block, for example:

COINGECKO_API_KEY='replace-with-key'
FRED_API_KEY='replace-with-key'
OPENAI_API_KEY='replace-with-key'
AGENT_CAPITAL_OPENAI_MODEL='replace-with-model'

Keep the user crontab private, quote values using crontab assignment syntax, and never place secrets in the Agent Capital managed command. On systems with centrally managed cron daemon environments, an administrator can provide the same variables there instead.

For local development:

uv sync --all-packages --dev
uv run maturin develop --manifest-path crates/agent_capital_backtest_core/Cargo.toml

Quick Start

1. Install the workspace dependencies and Rust/Python backtest extension:

   uv sync --all-packages --dev
   uv run maturin develop --manifest-path crates/agent_capital_backtest_core/Cargo.toml
   

2. Check the configured weekly operating cycle without running side effects:

   uv run agent-capital run --dry-run --config configs/weekly.toml
   

3. Refresh the local market-data cache:

   START=$(uv run python -c "from datetime import date, timedelta; print(date.today() - timedelta(days=210))")
   END=$(uv run python -c "from datetime import date; print(date.today())")
   uv run agent-capital data refresh --config configs/weekly.toml --cache runs/prices.sqlite --start "$START" --end "$END"
   

4. Generate a weekly paper report:

   uv run agent-capital run --config configs/weekly.toml --ledger runs/ledger.sqlite --cache runs/prices.sqlite --output-dir runs
   

Or refresh the rolling 210-day window and run the cycle in one command:

.\scripts\run-weekly.ps1

./scripts/run-weekly.sh

Usage Examples

Inspect the Weekly Cycle

uv run agent-capital run --dry-run --config configs/weekly.toml

This prints a run ID, the configured weekly cadence, asset class counts, and the operating-cycle stages.

Refresh Market Data

START=$(uv run python -c "from datetime import date, timedelta; print(date.today() - timedelta(days=210))")
END=$(uv run python -c "from datetime import date; print(date.today())")
uv run agent-capital data refresh --config configs/weekly.toml --cache runs/prices.sqlite --start "$START" --end "$END"

This creates or updates the SQLite price cache with provider-backed daily data for the assets in configs/weekly.toml. The configured providers are yfinance, coingecko, and fred; CoinGecko refreshes require a free Demo API key in COINGECKO_API_KEY, and FRED refreshes require FRED_API_KEY. This implementation uses CoinGecko's /market_chart endpoint and rejects a start date more than 365 days before the current UTC date. The weekly runner requests 210 days: 150 weekdays before market holidays, leaving a 24-observation margin over the 126-observation promotion gate. Demo rate limits still apply, so a throttled refresh exits before the paper cycle and can be retried later.

Generate a Report

uv run agent-capital run --config configs/weekly.toml --ledger runs/ledger.sqlite --cache runs/prices.sqlite --output-dir runs

This creates a run directory under runs/ and prints paths for:

• report.md
• metrics.json
• orders.json
• state.json
• portfolio.json
• strategy-comparison.json

LLM-backed report generation requires OPENAI_API_KEY and AGENT_CAPITAL_OPENAI_MODEL.

Weekly Paper Operation

Weekly is the v1 default cadence. The first successful cycle starts with USD 10,000 cash, creates no orders without an active strategy, and may approve one candidate for the next ISO week. Later cycles activate an approved strategy only when its effective_from week arrives, evaluate deterministic signals, and either simulate the complete rebalance batch or record HOLD/blocked orders. Promotion is automatic only when every configured observation, return, Sharpe, drawdown, subperiod, cooldown, tradability, and portfolio-risk gate passes.

Execution uses the most recent cached close dated on or before the run date. Every configured series must have a fresh cache entry; missing or stale required data stops the cycle before orders. Completed execution is stored atomically in runs/ledger.sqlite, while generated artifacts live under runs/<run-id>/. Re-running the same completed ISO week reads the durable snapshot and regenerates missing reports without duplicating orders.

Cycle and ISO week keys are calculated in UTC. For Linux/WSL cron, use an absolute repository path, expose the required API/model environment variables to cron, and schedule after the UTC Monday boundary. This example assumes the cron host itself uses UTC and runs Monday at 00:15 UTC:

15 0 * * 1 cd "/absolute/path/to/agent capital" && mkdir -p runs && ./scripts/run-weekly.sh >> runs/weekly.log 2>&1

On a KST-configured cron host, the equivalent time is Monday 09:15 KST (15 9 * * 1). On Windows, schedule powershell.exe -NoProfile -File "D:\absolute path\to\agent-capital\scripts\run-weekly.ps1" after 09:00 Monday KST in Task Scheduler. Both scripts stop if data refresh fails. They also take a nonblocking repository lock; an overlapping cron or manual run exits nonzero with an already running message instead of invoking the CLI.

Daily paper trading and replacement of the sequential weekly coordinator with a durable LangGraph graph remain tracked TODOs; this command intentionally implements only the weekly cycle.

Project Structure

Path	Purpose
apps/cli	Typer CLI entrypoint exposed as agent-capital.
packages/agent_capital_core	Shared contracts, IDs, asset models, config loading, and errors.
packages/agent_capital_data	Provider adapters and SQLite-backed price cache.
packages/agent_capital_research	Research briefs and market feature calculations.
packages/agent_capital_strategy	Strategy candidate schemas and signal evaluation.
packages/agent_capital_execution	Simulated execution models and services.
packages/agent_capital_risk	Guardrail rules and review decisions.
packages/agent_capital_reporting	Markdown/JSON report models, rendering, and disclaimers.
packages/agent_capital_agents	Narrative provider boundary for agent market analysis, strategy hypotheses, and report interpretation.
packages/agent_capital_ops	Weekly report-cycle orchestration.
packages/agent_capital_ledger	SQLite ledger models and persistence.
crates/agent_capital_backtest_core	Rust backtest and metrics core exposed as agent_capital_backtest_core.
configs/weekly.toml	Default weekly multi-asset operating-cycle configuration.

Metrics and Outputs

The Rust backtest core calculates these report metrics:

• total_return
• annualized_return
• volatility
• max_drawdown
• sharpe_ratio

Generated reports include the project disclaimer: outputs are for research, education, and simulation only. The system does not place live orders, is not investment advice, does not guarantee profits or returns, and requires independent review before any financial decision.

Development Checks

Run the Python test suite:

uv run pytest

Run Python lint checks:

uv run ruff check .

Check Python formatting:

uv run ruff format --check .

Run Rust tests:

cargo test --workspace

License

No root LICENSE file is present. The Rust workspace metadata declares Proprietary.