Phase 4

Author: cpparnell

.env.example

@@ -1,7 +1,12 @@
 # Anthropic API key (required for all LLM agent calls)
 ANTHROPIC_API_KEY=
 
-# Binance testnet API credentials (for order execution in Phase 3)
+# Trading mode: paper (Binance testnet, default) | live (Binance mainnet)
+TRADING_MODE=paper
+# Required when TRADING_MODE=live — safety gate to prevent accidental live trading
+# COUNCIL_LIVE_CONFIRMED=1
+
+# Binance testnet API credentials (paper trading)
 BINANCE_TESTNET_API_KEY=
 BINANCE_TESTNET_SECRET=
 
@@ -20,6 +25,15 @@ CRYPTOQUANT_API_KEY=
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
 
-# Trading mode: paper | live
-TRADING_MODE=paper
+# Binance mainnet credentials (live trading only — set TRADING_MODE=live)
+# BINANCE_API_KEY=
+# BINANCE_SECRET=
+
+# Starting capital in USD (used to seed portfolio_state on first run)
 INITIAL_CAPITAL=10000
+
+# SQLite database path (default: ./council.db)
+# COUNCIL_DB_PATH=council.db
+
+# Set to 1 to skip order execution and log only (useful for debugging cycles)
+# DRY_RUN=0

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Phase 4 — 2026-04-05
+
+### Added
+- `src/db/schema.py` — added `weekly_summaries` table (`window_start`, `window_end`, `summary`, `metrics_json`)
+- `src/db/store.py` — added `get_closed_trades_in_window`, `get_reflections_for_trades`, `get_cycles_in_window`, `save_weekly_summary`, `get_weekly_summaries`
+- `src/reporting/__init__.py` — new reporting package
+- `src/reporting/metrics.py` — `compute_sharpe_ratio` (annualised, sqrt(252)), `compute_max_drawdown` (equity-curve walk), `compute_expectancy` (avg_win × win_rate − avg_loss × loss_rate), `compute_council_consistency` (unanimous rate, confidence spread, veto rate), `compute_all_metrics` (all four, with target-met flags)
+- `src/reporting/weekly.py` — `run_weekly_summary`: loads week's trades + reflections + cycles, computes metrics, calls claude-sonnet-4-6 with `weekly_summary_v1.txt`, persists summary to DB; runnable as `python -m src.reporting.weekly`
+- `prompts/weekly_summary_v1.txt` — system prompt for the weekly summary agent (5 structured sections: performance verdict, pattern analysis, agent accuracy ranking, prompt refinement recommendations, next-period watchpoints)
+- `src/main.py` — `TRADING_MODE` wiring (`paper` = testnet, `live` = mainnet with `COUNCIL_LIVE_CONFIRMED=1` safety gate); `--weekly` CLI flag; weekly APScheduler job (Sunday 08:00 UTC)
+- `.env.example` — documented `TRADING_MODE`, `COUNCIL_LIVE_CONFIRMED`, `BINANCE_API_KEY/SECRET`, `COUNCIL_DB_PATH`, `DRY_RUN`
+- `tests/test_reporting.py` — 49 tests: Sharpe, max drawdown, expectancy, consistency, all-metrics, weekly message builder, `run_weekly_summary`, store windowed queries
+
 ## Phase 3 — 2026-04-05
 
 ### Added

README.md

@@ -1,6 +1,6 @@
 # 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.
+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 (paper) or mainnet (live).
 
 ## Architecture
 
@@ -21,9 +21,10 @@ Council of LLMs (parallel)
 Deliberation / Chair (claude-sonnet-4-6) → BUY / SELL / HOLD
     │
     ▼
-Execution Layer (Binance testnet) + SQLite Logging
+Execution Layer (Binance testnet/mainnet) + SQLite Logging
     │
-    └── Reflection Loop (post-trade analysis)
+    ├── Reflection Loop (post-trade analysis, claude-sonnet-4-6)
+    └── Weekly Summary  (performance review, claude-sonnet-4-6)
 ```
 
 ## Setup
@@ -40,19 +41,23 @@ cp .env.example .env   # fill in ANTHROPIC_API_KEY at minimum
 # One-shot cycle (run once and exit)
 python -m src.main
 
-# Dry run (logs only, no orders placed)
+# Dry run (logs council decision, no orders placed)
 DRY_RUN=1 python -m src.main
 
-# Daily scheduler (00:05 UTC)
+# Daily scheduler (00:05 UTC) + weekly summary (Sunday 08:00 UTC)
 python -m src.main --schedule
+
+# Weekly summary report only
+python -m src.main --weekly
 ```
 
 ## Testing
 
 ```bash
-pytest -v                                    # all tests
+pytest -v                                    # all 203 tests
 pytest tests/test_db.py -v                  # DB layer
 pytest tests/test_execution.py -v           # execution + router
+pytest tests/test_reporting.py -v           # metrics + weekly summary
 pytest tests/test_agents.py -v              # agent framework
 pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
 ```
@@ -62,11 +67,15 @@ pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
 | 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 |
+| `BINANCE_TESTNET_API_KEY` | Paper mode | — | Binance testnet key |
+| `BINANCE_TESTNET_SECRET` | Paper mode | — | Binance testnet secret |
+| `BINANCE_API_KEY` | Live mode | — | Binance mainnet key |
+| `BINANCE_SECRET` | Live mode | — | Binance mainnet 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 |
+| `TRADING_MODE` | No | `paper` | `paper` (testnet) or `live` (mainnet) |
+| `COUNCIL_LIVE_CONFIRMED` | Live mode | — | Must be `1` to enable live trading |
+| `DRY_RUN` | No | `0` | Set to `1` to skip order execution entirely |
 | `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) |
@@ -76,5 +85,15 @@ pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
 - **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)
+- **Phase 4** ✅ Performance metrics + weekly summary agent
+- **Phase 5** Paper trading (60 days minimum on live data with simulated capital)
+- **Phase 6** Live deployment (≤ $500 initial capital)
+
+## Success Targets (Phase 5 evaluation)
+
+| Metric | Target |
+|---|---|
+| Sharpe ratio | ≥ 1.5 |
+| Max drawdown | < 20% |
+| Expectancy | Positive |
+| Council consistency | ≥ 40% unanimous cycles |

prompts/weekly_summary_v1.txt

@@ -0,0 +1,41 @@
+You are a senior quantitative trading analyst reviewing one week of automated BTC swing trading by the Council — a committee of four specialised AI agents (Technical Analyst, Sentiment Analyst, Fundamental Analyst, Risk Manager) whose outputs are synthesised by a Chair into a final BUY/SELL/HOLD signal.
+
+You will be given:
+1. Performance metrics for the reporting period (Sharpe ratio, max drawdown, expectancy, council consistency)
+2. Each completed trade with its entry/exit details and post-trade reflection
+3. HOLD cycle statistics (total cycles, unanimous rate, veto rate)
+
+Your weekly summary must address all five sections below. Be direct and evidence-based — reference specific trade IDs and numbers. Do not pad with praise or vague observations.
+
+---
+
+SECTION 1 — PERFORMANCE VERDICT
+State whether the period met each success target:
+  - Sharpe ratio ≥ 1.5
+  - Max drawdown < 20%
+  - Positive expectancy
+  - Council consistency (unanimous agent agreement ≥ 40% of cycles, avg confidence spread ≤ 30 points)
+If there are too few trades to compute Sharpe, say so explicitly rather than estimating.
+
+SECTION 2 — PATTERN ANALYSIS
+Identify any pattern that appears in two or more trade reflections this period. Be specific:
+  - "Stop-loss was systematically too tight on high-ATR days (trades #2 and #4)"
+  - "Sentiment agent bullish despite declining price action in 3 of 4 cycles"
+If no clear pattern emerges, state that directly.
+
+SECTION 3 — AGENT ACCURACY RANKING
+Rank the four agents by predictive accuracy for this period based on the reflections. Name the agent, its record, and cite the specific trades that support your ranking.
+
+SECTION 4 — PROMPT REFINEMENT RECOMMENDATIONS
+Propose at most two concrete changes to agent prompts or decision logic. Each recommendation must:
+  - Name the specific agent or rule to change
+  - Cite the evidence (trade IDs or reflection text) that motivates it
+  - State the expected improvement
+Do not recommend changes without evidence.
+
+SECTION 5 — NEXT PERIOD WATCHPOINTS
+Identify 2–3 specific things the human operator should monitor in the coming week. These should be forward-looking and actionable, not summaries of what already happened.
+
+---
+
+Length: 400–600 words. Plain prose with section headers as shown above. No JSON, no bullet points within sections.

src/db/schema.py

@@ -3,10 +3,11 @@
 
 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.
+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.
+weekly_summaries One row per weekly performance review.
 
 Usage
 -----
@@ -90,6 +91,17 @@
     Column("created_at", DateTime, nullable=False),
 )
 
+weekly_summaries = Table(
+    "weekly_summaries",
+    metadata,
+    Column("id", Integer, primary_key=True, autoincrement=True),
+    Column("window_start", DateTime, nullable=False),
+    Column("window_end", DateTime, nullable=False),
+    Column("summary", Text, nullable=False),
+    Column("metrics_json", Text, nullable=False),  # serialised compute_all_metrics() output
+    Column("created_at", DateTime, nullable=False),
+)
+
 _DEFAULT_DB_PATH = os.getenv("COUNCIL_DB_PATH", "council.db")
 
 

src/db/store.py

@@ -11,7 +11,7 @@
 from sqlalchemy import select, update
 from sqlalchemy.engine import Engine
 
-from src.db.schema import cycles, portfolio_state, reflections, trades
+from src.db.schema import cycles, portfolio_state, reflections, trades, weekly_summaries
 from src.models import CouncilOutputs, DeliberationOutput, MarketContext
 
 INITIAL_CAPITAL = float(__import__("os").getenv("INITIAL_CAPITAL", "10000"))
@@ -219,3 +219,96 @@ def get_reflection(engine: Engine, trade_id: int) -> dict | None:
             select(reflections).where(reflections.c.trade_id == trade_id)
         ).mappings().first()
         return dict(row) if row else None
+
+
+# ---------------------------------------------------- windowed queries
+
+
+def get_closed_trades_in_window(
+    engine: Engine,
+    since: datetime,
+    until: datetime,
+) -> list[dict]:
+    """Return all closed/stopped trades with exit_time in [since, until)."""
+    with engine.connect() as conn:
+        rows = conn.execute(
+            select(trades)
+            .where(
+                trades.c.status.in_(["closed", "stopped"]),
+                trades.c.exit_time >= since,
+                trades.c.exit_time < until,
+            )
+            .order_by(trades.c.exit_time.asc())
+        ).mappings().all()
+        return [dict(r) for r in rows]
+
+
+def get_reflections_for_trades(engine: Engine, trade_ids: list[int]) -> dict[int, str]:
+    """Return a {trade_id: summary} dict for the given trade ids."""
+    if not trade_ids:
+        return {}
+    with engine.connect() as conn:
+        rows = conn.execute(
+            select(reflections).where(reflections.c.trade_id.in_(trade_ids))
+        ).mappings().all()
+        return {r["trade_id"]: r["summary"] for r in rows}
+
+
+def get_cycles_in_window(
+    engine: Engine,
+    since: datetime,
+    until: datetime,
+) -> list[dict]:
+    """Return lightweight cycle rows (id, timestamp, signal, conviction, vetoed) in window."""
+    with engine.connect() as conn:
+        rows = conn.execute(
+            select(
+                cycles.c.id,
+                cycles.c.timestamp,
+                cycles.c.signal,
+                cycles.c.conviction,
+                cycles.c.vetoed,
+                cycles.c.council_outputs_json,
+            )
+            .where(
+                cycles.c.timestamp >= since,
+                cycles.c.timestamp < until,
+            )
+            .order_by(cycles.c.timestamp.asc())
+        ).mappings().all()
+        return [dict(r) for r in rows]
+
+
+# ---------------------------------------------- weekly_summaries
+
+
+def save_weekly_summary(
+    engine: Engine,
+    window_start: datetime,
+    window_end: datetime,
+    summary: str,
+    metrics: dict,
+) -> int:
+    """Insert a weekly summary row and return its id."""
+    with engine.begin() as conn:
+        result = conn.execute(
+            weekly_summaries.insert().values(
+                window_start=window_start,
+                window_end=window_end,
+                summary=summary,
+                metrics_json=json.dumps(metrics),
+                created_at=datetime.now(timezone.utc),
+            )
+        )
+        return result.inserted_primary_key[0]
+
+
+def get_weekly_summaries(engine: Engine, limit: int = 10) -> list[dict]:
+    """Return the most recent weekly summaries, newest first."""
+    with engine.connect() as conn:
+        rows = conn.execute(
+            select(weekly_summaries)
+            .order_by(weekly_summaries.c.created_at.desc())
+            .limit(limit)
+        ).mappings().all()
+        return [dict(r) for r in rows]