Implement v0 phase 3, add changes to CHANGELOG

Author: cpparnell

.env.example

@@ -1,3 +1,6 @@
+# Anthropic API key (required for all LLM agent calls)
+ANTHROPIC_API_KEY=
+
 # Binance testnet API credentials (for order execution in Phase 3)
 BINANCE_TESTNET_API_KEY=
 BINANCE_TESTNET_SECRET=

CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## Phase 3 — 2026-04-05
+
+### Added
+- `src/db/schema.py` — SQLAlchemy table definitions (`cycles`, `trades`, `portfolio_state`, `reflections`)
+- `src/db/store.py` — CRUD operations: `log_cycle`, `open_trade`, `close_trade`, `get_open_trade`, `get_portfolio_state`, `update_portfolio_state`, `save_reflection`, `get_reflection`
+- `src/execution/orders.py` — `place_market_buy`, `place_market_sell`, `place_stop_loss`, `cancel_order` with retry logic (max 3 attempts, exponential back-off)
+- `src/execution/state.py` — `build_portfolio_dict`: loads live portfolio state from DB for context assembly
+- `src/execution/router.py` — `route_signal`: translates `CouncilResult` → exchange orders + DB updates; `reconcile_open_position`: detects stop-outs at cycle start
+- `src/agents/reflection.py` — post-trade reflection agent (claude-sonnet-4-6)
+- `prompts/reflection_v1.txt` — system prompt for the reflection agent
+- `src/main.py` — full cycle entry point; supports one-shot and `--schedule` (APScheduler daily at 00:05 UTC); `DRY_RUN=1` skips order execution
+- `tests/test_db.py` — 16 tests for DB schema and CRUD
+- `tests/test_execution.py` — 22 tests for orders, state, and router
+- `tests/test_reflection.py` — 8 tests for the reflection agent
+- `sqlalchemy>=2.0.0` and `apscheduler>=3.10.0` added to dependencies
+
+## Phase 2 — Agent Framework
+
+### Added
+- `src/models.py` — extended with all agent output models: `TechnicalAnalystOutput`, `SentimentAnalystOutput`, `FundamentalAnalystOutput`, `RiskManagerOutput`, `CouncilOutputs`, `DeliberationOutput`, `AgentWeights`
+- `src/agents/base.py` — `call_agent()` helper: loads prompt file, calls Anthropic API at `temperature=0`, strips markdown fences from response, validates JSON against Pydantic schema; raises `AgentError` on any failure
+- `src/agents/technical.py` — Technical Analyst agent (claude-haiku-4-5); analyses RSI momentum, MACD crosses, Bollinger Band position, EMA alignment, ATR volatility
+- `src/agents/sentiment.py` — Sentiment Analyst agent (claude-haiku-4-5); analyses news tone, fear/greed index, social volume, dominant narrative
+- `src/agents/fundamental.py` — Fundamental Analyst agent (claude-haiku-4-5); analyses exchange net flows, whale transactions, SOPR, macro bias
+- `src/agents/risk.py` — Risk Manager agent (claude-sonnet-4-6); evaluates portfolio risk, outputs position size, stop-loss, take-profit, R:R; has veto authority
+- `src/agents/deliberation.py` — Deliberation Chair agent (claude-sonnet-4-6); synthesises all four agent outputs into final BUY/SELL/HOLD signal with conviction level
+- `src/agents/runner.py` — `run_council()`: runs all four agents in parallel via `asyncio.gather()`; short-circuits to HOLD immediately if risk manager vetoes (skips deliberation); returns `CouncilResult`
+- `prompts/technical_analyst_v1.txt` — system prompt for Technical Analyst
+- `prompts/sentiment_analyst_v1.txt` — system prompt for Sentiment Analyst
+- `prompts/fundamental_analyst_v1.txt` — system prompt for Fundamental Analyst
+- `prompts/risk_manager_v1.txt` — system prompt for Risk Manager
+- `prompts/deliberation_v1.txt` — system prompt for Deliberation Chair (includes consensus rules: all-3-agree ≥70% → full size; 2-of-3 ≥60% → 50% size; else HOLD)
+- `tests/test_agents.py` — 38 tests: `call_agent` base utility, individual agent schema validation, deliberation consensus logic, runner veto short-circuit, prompt file existence checks
+
+## Phase 1 — Data Pipeline + Tier-0 Validation
+
+### Added
+- `src/models.py` — Pydantic v2 models for the full context schema: `PriceData`, `IndicatorData`, `NewsItem`, `SentimentData`, `OnchainData`, `PortfolioData`, `MarketContext`; literal types for `Direction`, `MACDSignal`, `BBPosition`, `Regime`, etc.
+- `src/data/price.py` — CCXT Binance testnet OHLCV fetcher (`fetch_ohlcv`, `build_price_data`); raises `ValueError` if fewer than 200 candles returned
+- `src/data/indicators.py` — `compute_indicators()`: RSI-14, MACD cross detection, Bollinger Band position, EMA 20/50/200, ATR-14, ATR-30 rolling average, regime classifier (trending/ranging/high_volatility via ADX + ATR)
+- `src/data/news.py` — async CryptoPanic fetcher; returns empty list if API key absent
+- `src/data/sentiment.py` — async Alternative.me Fear/Greed Index fetcher; LunarCrush stub returning neutral defaults
+- `src/data/onchain.py` — Glassnode/CryptoQuant stubs returning zero defaults
+- `src/data/assembler.py` — `assemble_context()`: fetches OHLCV synchronously (ccxt is sync), fetches news/sentiment/on-chain in parallel with `asyncio.gather()`, assembles `MarketContext`, runs Tier-0 validation
+- `src/validation.py` — `validate_context()`: price freshness check (< 5 min), minimum news count (≥ 10), numeric range checks; `HardRuleViolation` raised for drawdown halt (> 15% from peak) and ATR volatility halt (ATR-14 > 2× ATR-30 avg)
+- `tests/test_indicators.py` — 35 tests for all indicator computations
+- `tests/test_assembler.py` — context assembly tests with mocked data feeds and default portfolio
+- `tests/test_validation.py` — 35 tests for price freshness, news count, numeric ranges, drawdown halt, volatility halt

README.md

@@ -1,2 +1,80 @@
-# council
-Council of LLMs BTC Trading Strategy
+# Council — BTC LLM Trading Bot
+
+A Bitcoin swing trading bot that uses a council of specialised LLM agents to generate daily BUY/SELL/HOLD signals and execute them against Binance testnet.
+
+## Architecture
+
+```
+Data Pipeline (CCXT/Binance, CryptoPanic, Alternative.me, Glassnode)
+    │
+    ▼
+Tier-0 Validation (price freshness, news count, drawdown halt, ATR halt)
+    │
+    ▼
+Council of LLMs (parallel)
+    ├── Technical Analyst  (claude-haiku-4-5)
+    ├── Sentiment Analyst  (claude-haiku-4-5)
+    ├── Fundamental Analyst (claude-haiku-4-5)
+    └── Risk Manager       (claude-sonnet-4-6)
+    │
+    ▼
+Deliberation / Chair (claude-sonnet-4-6) → BUY / SELL / HOLD
+    │
+    ▼
+Execution Layer (Binance testnet) + SQLite Logging
+    │
+    └── Reflection Loop (post-trade analysis)
+```
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+cp .env.example .env   # fill in ANTHROPIC_API_KEY at minimum
+```
+
+## Running
+
+```bash
+# One-shot cycle (run once and exit)
+python -m src.main
+
+# Dry run (logs only, no orders placed)
+DRY_RUN=1 python -m src.main
+
+# Daily scheduler (00:05 UTC)
+python -m src.main --schedule
+```
+
+## Testing
+
+```bash
+pytest -v                                    # all tests
+pytest tests/test_db.py -v                  # DB layer
+pytest tests/test_execution.py -v           # execution + router
+pytest tests/test_agents.py -v              # agent framework
+pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ANTHROPIC_API_KEY` | Yes | — | Claude API key |
+| `BINANCE_TESTNET_API_KEY` | For execution | — | Binance testnet key |
+| `BINANCE_TESTNET_SECRET` | For execution | — | Binance testnet secret |
+| `COUNCIL_DB_PATH` | No | `./council.db` | SQLite database path |
+| `INITIAL_CAPITAL` | No | `10000` | Starting paper capital (USD) |
+| `DRY_RUN` | No | `0` | Set to `1` to skip order execution |
+| `CRYPTOPANIC_API_KEY` | No | — | News feed (falls back to empty list) |
+| `LUNARCRUSH_API_KEY` | No | — | Sentiment (falls back to Fear/Greed proxy) |
+| `GLASSNODE_API_KEY` | No | — | On-chain data (falls back to zeros) |
+
+## Development Phases
+
+- **Phase 1** ✅ Data pipeline + Tier-0 validation
+- **Phase 2** ✅ Agent framework (4 agents + deliberation)
+- **Phase 3** ✅ Execution layer + SQLite logging + reflection loop
+- **Phase 4** Paper trading (60 days minimum)
+- **Phase 5** Live deployment (≤ $500 initial capital)

prompts/reflection_v1.txt

@@ -0,0 +1,19 @@
+You are a trading journal analyst reviewing a completed BTC swing trade made by the Council — a committee of four specialised AI agents (Technical Analyst, Sentiment Analyst, Fundamental Analyst, Risk Manager) whose outputs were synthesised by a Chair into a final signal.
+
+Your job is to produce a concise, honest post-trade reflection that will be stored in the trading log and read by the human operator.
+
+You will be given:
+1. The council outputs (each agent's analysis at the time of the trade decision)
+2. The deliberation summary (the Chair's synthesis and final signal)
+3. The trade outcome (entry price, exit price, PnL)
+
+Your reflection must address:
+1. Which agent's view was most predictive of the actual outcome? Which was least accurate?
+2. Was the deliberation's conviction level appropriate in hindsight?
+3. Was the stop-loss placement reasonable, or should it have been wider/tighter?
+4. What single change to the prompts or decision logic would most improve future trades?
+5. Any recurring pattern worth flagging for the weekly summary?
+
+Tone: Direct and analytical. Do not pad with praise. Be specific — reference actual numbers from the council outputs.
+
+Length: 200–350 words. Plain prose, no JSON, no bullet points.

pyproject.toml

@@ -15,6 +15,8 @@ dependencies = [
     "httpx>=0.27.0",
     "pandas>=2.0.0",
     "numpy>=1.26.0",
+    "sqlalchemy>=2.0.0",
+    "apscheduler>=3.10.0",
 ]
 
 [project.optional-dependencies]

src/agents/reflection.py

@@ -0,0 +1,85 @@
+"""
+Reflection agent — runs after a position is closed.
+
+Feeds the original council outputs, deliberation, and trade outcome to a
+language model and returns a plain-text summary for the cycle log.  This
+does NOT alter agent weights dynamically; summaries are for human review
+and prompt refinement only.
+"""
+
+import os
+
+import anthropic
+
+from src.agents.base import AgentError, load_prompt
+from src.models import CouncilOutputs, DeliberationOutput
+
+MODEL = "claude-sonnet-4-6"
+PROMPT_FILE = "reflection_v1.txt"
+
+
+def _build_user_message(
+    outputs: CouncilOutputs,
+    deliberation: DeliberationOutput,
+    trade: dict,
+) -> str:
+    pnl_usd = trade.get("pnl_usd", 0.0)
+    pnl_pct = trade.get("pnl_pct", 0.0)
+    outcome = "profit" if pnl_usd >= 0 else "loss"
+
+    return (
+        f"## Trade outcome\n"
+        f"Side: {trade['side']}\n"
+        f"Entry: {trade['entry_price']:,.2f} USD\n"
+        f"Exit: {trade['exit_price']:,.2f} USD\n"
+        f"Stop-loss: {trade['stop_loss']:,.2f} USD\n"
+        f"Status: {trade['status']}\n"
+        f"PnL: {pnl_usd:+,.2f} USD ({pnl_pct:+.2f}%) — {outcome}\n\n"
+        f"## Council outputs at decision time\n\n"
+        f"### Technical Analyst\n{outputs.technical.model_dump_json(indent=2)}\n\n"
+        f"### Sentiment Analyst\n{outputs.sentiment.model_dump_json(indent=2)}\n\n"
+        f"### Fundamental Analyst\n{outputs.fundamental.model_dump_json(indent=2)}\n\n"
+        f"### Risk Manager\n{outputs.risk.model_dump_json(indent=2)}\n\n"
+        f"## Deliberation summary\n{deliberation.model_dump_json(indent=2)}\n\n"
+        "Please write your reflection now."
+    )
+
+
+async def run_reflection(
+    outputs: CouncilOutputs,
+    deliberation: DeliberationOutput,
+    trade: dict,
+    client: anthropic.AsyncAnthropic | None = None,
+) -> str:
+    """Generate a post-trade reflection summary.
+
+    Args:
+        outputs:      CouncilOutputs from the cycle that opened the trade.
+        deliberation: DeliberationOutput from the same cycle.
+        trade:        Closed trade dict from the DB (must include exit_price, pnl_usd, etc.).
+        client:       Optional AsyncAnthropic client; created from env if not provided.
+
+    Returns:
+        Plain-text reflection summary (200–350 words).
+
+    Raises:
+        AgentError: If the API call fails.
+    """
+    if client is None:
+        client = anthropic.AsyncAnthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+
+    system = load_prompt(PROMPT_FILE)
+    user = _build_user_message(outputs, deliberation, trade)
+
+    try:
+        response = await client.messages.create(
+            model=MODEL,
+            max_tokens=1024,
+            temperature=0,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+    except anthropic.APIError as exc:
+        raise AgentError(f"Reflection agent API error: {exc}") from exc
+
+    return response.content[0].text.strip()

src/db/__init__.py

@@ -0,0 +1,103 @@
+"""
+SQLAlchemy table definitions for the Council trading bot.
+
+Tables
+------
+cycles          One row per council run (context snapshot + agent outputs + signal).
+trades          One row per order placed (entry → exit lifecycle).
+portfolio_state Singleton row tracking cash and peak portfolio value.
+reflections     One row per post-trade reflection summary.
+
+Usage
+-----
+    from src.db.schema import get_engine, create_all
+
+    engine = get_engine()          # default: ./council.db
+    create_all(engine)             # idempotent — safe to call every startup
+"""
+
+import os
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    Float,
+    Integer,
+    String,
+    Text,
+    create_engine,
+)
+from sqlalchemy import MetaData
+
+metadata = MetaData()
+
+from sqlalchemy import Table
+
+cycles = Table(
+    "cycles",
+    metadata,
+    Column("id", Integer, primary_key=True, autoincrement=True),
+    Column("timestamp", DateTime, nullable=False),
+    Column("asset", String(16), nullable=False),
+    Column("signal", String(8), nullable=False),       # BUY | SELL | HOLD
+    Column("conviction", String(8), nullable=False),   # high | medium | low
+    Column("vetoed", Boolean, nullable=False),
+    Column("context_json", Text, nullable=False),
+    Column("council_outputs_json", Text, nullable=False),
+    Column("deliberation_json", Text, nullable=False),
+)
+
+trades = Table(
+    "trades",
+    metadata,
+    Column("id", Integer, primary_key=True, autoincrement=True),
+    Column("cycle_id", Integer, nullable=False),       # FK → cycles.id
+    Column("symbol", String(16), nullable=False),
+    Column("side", String(4), nullable=False),         # BUY | SELL
+    Column("entry_price", Float, nullable=False),
+    Column("entry_time", DateTime, nullable=False),
+    Column("position_size_usd", Float, nullable=False),
+    Column("position_size_btc", Float, nullable=False),
+    Column("stop_loss", Float, nullable=False),
+    Column("take_profit", Float, nullable=True),
+    Column("exchange_order_id", String(64), nullable=True),
+    Column("sl_order_id", String(64), nullable=True),
+    # Filled in when the position is closed
+    Column("exit_price", Float, nullable=True),
+    Column("exit_time", DateTime, nullable=True),
+    Column("pnl_usd", Float, nullable=True),
+    Column("pnl_pct", Float, nullable=True),
+    Column("status", String(8), nullable=False, default="open"),  # open | closed | stopped
+)
+
+portfolio_state = Table(
+    "portfolio_state",
+    metadata,
+    # Always a single row with id=1 (upsert pattern).
+    Column("id", Integer, primary_key=True),
+    Column("cash_usd", Float, nullable=False),
+    Column("peak_value", Float, nullable=False),
+    Column("updated_at", DateTime, nullable=False),
+)
+
+reflections = Table(
+    "reflections",
+    metadata,
+    Column("id", Integer, primary_key=True, autoincrement=True),
+    Column("trade_id", Integer, nullable=False),       # FK → trades.id
+    Column("summary", Text, nullable=False),
+    Column("created_at", DateTime, nullable=False),
+)
+
+_DEFAULT_DB_PATH = os.getenv("COUNCIL_DB_PATH", "council.db")
+
+
+def get_engine(db_path: str = _DEFAULT_DB_PATH):
+    """Return a SQLAlchemy engine.  Use ``db_path=':memory:'`` for tests."""
+    return create_engine(f"sqlite:///{db_path}", future=True)
+
+
+def create_all(engine) -> None:
+    """Create all tables if they do not exist (idempotent)."""
+    metadata.create_all(engine)