Cambr

Competitive Algorithmic Mutation Bot Reactor — evolutionary crypto trading via AI agents.

AI agents write trading strategy code (the genome), a custom backtest engine evaluates fitness via walk-forward validation, and git tracks lineage. Unlike traditional genetic algorithms that optimize parameter vectors, Cambr evolves entire strategy codebases.

Quick start

# 1. Enter the dev environment
nix develop

# 2. Install Python dependencies
uv sync

# 3. Fetch historical data
cambr fetch BTC/USDT --timeframe 1h --since 2025-01-01 --until 2025-02-01

# 4. Write a strategy (or use an existing one)
cat > /tmp/sma_cross.py << 'EOF'
import pandas as pd
from cambr.strategy import Strategy, StrategyMetadata

class SmaCross(Strategy):
    @property
    def metadata(self) -> StrategyMetadata:
        return StrategyMetadata(
            name="sma_cross", version="1.0.0",
            description="SMA 10/30 crossover",
        )

    def generate_signals(self, open, high, low, close, volume):
        fast = close.rolling(10).mean()
        slow = close.rolling(30).mean()
        entries = (fast > slow) & (fast.shift(1) <= slow.shift(1))
        exits = (fast < slow) & (fast.shift(1) >= slow.shift(1))
        return entries.fillna(False), exits.fillna(False)
EOF

# 5. Backtest it
cambr backtest /tmp/sma_cross.py --symbol BTC/USDT --timeframe 1h \
    --since 2025-01-01 --until 2025-02-01

# 6. Run full fitness evaluation (walk-forward validation)
cambr evaluate /tmp/sma_cross.py --symbol BTC/USDT --timeframe 1h \
    --since 2025-01-01 --until 2025-02-01

# 7. Evolve a population of strategies via AI (requires ANTHROPIC_API_KEY)
cambr evolve --symbol BTC/USDT --timeframe 1h \
    --since 2025-01-01 --until 2025-02-01 --max-generations 5

Architecture

src/cambr/
├── strategy.py      Strategy ABC — the contract agents implement
├── backtest.py      Custom backtest engine (pandas/numpy)
├── metrics.py       Financial performance metrics (Sharpe, drawdown, etc.)
├── fitness.py       Walk-forward fitness evaluation + composite scoring
├── data.py          OHLCV fetching (ccxt) + SQLite caching + retry
├── loader.py        Dynamic strategy module loading
├── agent.py         LLM integration (Anthropic + OpenRouter)
├── population.py    Population loading, saving, diversity enforcement
├── evolve.py        Evolution loop orchestration
└── cli.py           CLI entry point + logging config

Two-repo structure:

• cambr (this repo, public) — the engine and framework
• cambr-strategies (private) — evolved strategy modules

See docs/architecture.md for detailed design documentation.

CLI

cambr evolve --since 2024-01-01 --until 2025-01-01
cambr backtest <strategy.py> --symbol BTC/USDT --timeframe 1h --since 2025-01-01 --until 2025-02-01
cambr evaluate <strategy.py> --symbol BTC/USDT --timeframe 1h --since 2025-01-01 --until 2025-02-01
cambr fetch BTC/USDT --timeframe 1h --since 2025-01-01 --until 2025-02-01

Command	Description
evolve	Evolve trading strategies via AI — the full evolution loop
backtest	Run a single backtest and print performance metrics
evaluate	Full walk-forward fitness evaluation (70/30 IS/OOS split)
fetch	Download and cache OHLCV data without running a backtest

Set CAMBR_LOG_LEVEL=DEBUG for verbose output (cache hits, fetch progress, strategy loading).

Example output

$ cambr evolve --since 2024-01-01 --until 2025-01-01 --max-generations 3 --population-size 5

Symbol:     BTC/USDT (1h)
Period:     2024-01-01 to 2025-01-01 (8760 bars)
Model:      claude-sonnet-4-6 (anthropic)
Population: 5, Children: 6

--- Generation 1 ---
Best:  momentum_rsi_filter (0.5832)
Avg:   0.3214
Population: 5
Children: 6 generated, 4 viable

--- Generation 2 ---
Best:  momentum_rsi_breakout (0.6104)
Avg:   0.4127
Population: 5
Children: 6 generated, 5 viable

--- Generation 3 ---
Best:  momentum_rsi_breakout (0.6104)
Avg:   0.4531
Population: 5
Children: 6 generated, 3 viable

=== Evolution Complete ===
Generations: 3
Converged:   False
Best:        momentum_rsi_breakout
Score:       0.6104

Final population (5):
  1. momentum_rsi_breakout (0.6104)
  2. momentum_rsi_filter (0.5832)
  3. volatility_mean_revert (0.5201)
  4. ema_volume_spike (0.4417)
  5. obv_trend_follow (0.3105)

$ cambr backtest sma_cross.py --symbol BTC/USDT --timeframe 1h --since 2025-01-01 --until 2025-02-01

Strategy: sma_cross v1.0.0
Symbol:   BTC/USDT (1h)
Period:   2025-01-01 to 2025-02-01 (744 bars)

Final value:   $10,243.17
Total return:  +2.43%
Sharpe ratio:  1.42
Max drawdown:  3.12%
Win rate:      58.33%
Trade count:   12
Profit factor: 1.87

Strategy contract

Strategies implement the Strategy ABC. The contract is minimal:

from cambr.strategy import Strategy, StrategyMetadata

class MyStrategy(Strategy):
    @property
    def metadata(self) -> StrategyMetadata:
        return StrategyMetadata(
            name="my_strategy",
            version="1.0.0",
            description="What it does",
            parent_names=(),
        )

    def generate_signals(self, open, high, low, close, volume):
        entries = ...  # pd.Series of booleans
        exits = ...    # pd.Series of booleans
        return entries, exits

Rules:

• Deterministic — same input produces same output
• Pure — no side effects, no network calls
• One class per module — the loader validates this
• pandas/numpy only — no external dependencies in signal logic

Development

nix develop          # enter dev environment (or: direnv allow)
uv sync              # install Python deps

pytest               # run tests
ruff check .         # lint
ruff format .        # format
pyright src/         # type check (strict mode)

License

MIT