Metadata-Version: 2.4
Name: agent-capital
Version: 0.1.2
Summary: Agent Capital CLI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: agent-capital-backtest-core==0.1.0
Requires-Dist: langchain>=1.1
Requires-Dist: langchain-openai
Requires-Dist: openai>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: yfinance>=0.2

<!-- generated-by: gsd-doc-writer -->
# 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:

```bash
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
uvx agent-capital weekly --env-file ~/.agent-capital/env
```

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.

Scheduled runs load credentials from `~/.agent-capital/env` by default. Create the file before
installing the schedule:

```dotenv
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
```

Restrict it to the current user on macOS, Linux, and WSL:

```bash
chmod 600 ~/.agent-capital/env
```

Scheduling uses a macOS user LaunchAgent or a Linux/WSL cron entry automatically. The selected
time uses the system timezone:

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

Pass `--env-file PATH` to use another file. Installation stops if it does not exist. The file is
parsed as `KEY=VALUE` data and is not executed as a shell script. On macOS the managed definition
is `~/Library/LaunchAgents/com.agent-capital.weekly.plist`; output is written to
`~/.agent-capital/weekly.log` and errors to `~/.agent-capital/weekly.err.log`.

For local development:

```bash
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:

   ```bash
   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:

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

3. Refresh the local market-data cache:

   ```bash
   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:

   ```bash
   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:

```powershell
.\scripts\run-weekly.ps1
```

```bash
./scripts/run-weekly.sh
```

## Usage Examples

### Inspect the Weekly Cycle

```bash
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

```bash
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

```bash
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:

```cron
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:

```bash
uv run pytest
```

Run Python lint checks:

```bash
uv run ruff check .
```

Check Python formatting:

```bash
uv run ruff format --check .
```

Run Rust tests:

```bash
cargo test --workspace
```

## License

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