Make into a framework

Author: cpparnell

.DS_Store

@@ -211,6 +211,8 @@ __marimo__/
 
 # Misc.
 NOTES.md
+CHANGELOG.md
 
 # Temporary files
-tmp/
+tmp/
+prompts/personal/

.gitignore

@@ -1,5 +1,36 @@
 # Changelog
 
+## Feature — 2026-04-30 (v3: strategy framework — config-driven council)
+
+Implements `specs/v3.md` phases 1–6. Users can now define a complete trading strategy in a single YAML file without writing Python. Test suite: **305 → 344** passing.
+
+### Added
+- `src/strategies/config.py` — typed `StrategyConfig` Pydantic model: `AgentConfig` (name, model, prompt, weight, is_veto), `DeliberationConfig` (optional), `ScoringConfig` (confidence_floor, trade_threshold), `RiskRules` (stop_loss/take_profit SLTPRule + max_position_pct), `ValidationConfig` (max_drawdown_pct, atr_spike_multiplier, min_news_count); `model_validator` enforces weight-sum=1.0 and at-most-one veto agent
+- `src/strategies/loader.py` — `load_strategy(path)`: loads YAML, validates schema, and checks all prompt files exist on disk; prompt paths are resolved relative to project root
+- `src/strategies/context.py` — `render_context_block(ctx)`: renders the full `MarketContext` as a structured text block (PRICE / INDICATORS / NEWS / SENTIMENT / ON-CHAIN / MACRO / PORTFOLIO sections); single shared input for all agents in a generic run
+- `src/strategies/runner.py` — `run_strategy_council(ctx, config, client)`: config-driven generic runner; runs all agents in parallel; short-circuits to HOLD on veto; calls `compute_generic_score`; optionally runs deliberation; computes SL/TP via `compute_sl_tp`; returns `GenericCouncilResult`
+- `src/strategies/scoring.py` — `compute_generic_score(outputs, config)`: config-driven confidence-weighted signed-score; weights normalised at call time; confidence_floor and trade_threshold sourced from `ScoringConfig`; `score_to_position_size_pct(score, config)` scales size from |score|
+- `src/strategies/risk_rules.py` — `compute_sl_tp(rules, ctx, entry_price)`: computes SL/TP prices from `RiskRules`; supports `atr_multiple` (price ± N×ATR-14), `fixed_pct` (price × (1 ± pct)), and `none` (0.0, 0.0); SL clamped > 0
+- `strategies/default.yaml` — current v2 council expressed as a strategy file (technical 0.40 / sentiment 0.25 / fundamental 0.35 / risk veto; deliberation enabled; scoring thresholds and validation thresholds matching current hardcoded constants)
+- `strategies/example.yaml` — fully-commented example strategy (`momentum` + `macro` + `risk_guard` veto); shows every config option
+- `prompts/deliberation_generic_v1.txt` — built-in deliberation prompt for generic runs; requests a 2–4 sentence narrative synthesis
+- `prompts/agent_template.txt` — starting-point prompt for directional agents with annotated output schema and confidence calibration guide
+- `prompts/veto_agent_template.txt` — starting-point prompt for veto agents with `VetoAgentOutput` schema guidance
+- `prompts/risk_manager_veto_v1.txt` — purpose-built veto prompt for `default.yaml`'s risk agent (cleaner than repurposing `risk_manager_v2.txt`)
+- `tests/test_strategy_loader.py` (12 tests) — valid configs, weight validation, veto count, missing fields, missing prompt files, `default.yaml` and `example.yaml` smoke loads
+- `tests/test_strategy_scoring.py` (16 tests) — all directions, confidence floor exclusion, threshold gating, weighted score formula, SL/TP for all three rule types
+- `tests/test_strategy_runner.py` (8 tests) — BUY/HOLD/SELL signals, veto short-circuit, veto=false passthrough, SL/TP on result, conviction derivation, deliberation failure non-fatal, no-veto-agent skips veto call
+- `tests/test_strategy_parity.py` (3 tests) — BUY/HOLD/veto scenarios confirm generic and legacy scorers agree on identical inputs
+
+### Changed
+- `src/models.py` — added `GenericAgentOutput`, `VetoAgentOutput`, `GenericCouncilOutputs`, `GenericDeliberationOutput` (additive; all existing models unchanged)
+- `src/validation.py` — `check_drawdown_halt` and `check_volatility_halt` now accept `max_drawdown_pct` and `atr_spike_multiplier` params (backward-compatible defaults match previous constants); `validate_context` accepts both params and passes them through
+- `src/data/assembler.py` — `assemble_context` accepts `max_drawdown_pct` and `atr_spike_multiplier` params and passes them to `validate_context`
+- `src/main.py` — added `--strategy PATH` CLI argument; when provided, calls `run_strategy_council` instead of legacy `run_council`; validation params derived from strategy config
+- `src/backtest/signals.py` — `generate_signals` accepts `strategy_config` param; routes to generic runner when provided; agent logs written per-agent-name for generic runs
+- `src/backtest/engine.py` — `run_backtest` accepts `strategy_config` param; `_parse_args` adds `--strategy PATH`
+- `pyproject.toml` — added `pyyaml>=6.0` as explicit dependency (was transitively available; now declared)
+
 ## Bugfix — 2026-04-27 (risk manager stop-loss above entry price)
 
 ### Fixed

CHANGELOG.md

@@ -1,32 +1,38 @@
 # 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 (paper) or mainnet (live).
+A Bitcoin swing trading framework built around a **council of LLM agents** that vote on daily BUY/SELL/HOLD signals. Fully configurable — define your own agents, weights, and risk rules in a single YAML file without writing code.
 
 ## Architecture
 
 ```
-Data Pipeline (CCXT/Kraken, CryptoPanic, Alternative.me, Glassnode)
+strategy.yaml  (agents, weights, SL/TP rules, validation thresholds)
+    │
+    ▼
+Data Pipeline (CCXT/Kraken, GDELT news, Alternative.me, CoinMetrics, yfinance)
     │
     ▼
 Tier-0 Validation (price freshness, news count, drawdown halt, ATR halt)
+    │                          ↑ thresholds from strategy.yaml
+    ▼
+Generic Council Runner — agents defined in strategy.yaml, run in parallel
+    ├── Directional agents  (any number, any model, user-defined prompts)
+    └── Veto agent          (optional; forces HOLD if veto=true)
     │
     ▼
-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)
+Deterministic Scorer (confidence-weighted signed-score from strategy weights)
     │
     ▼
-Deliberation / Chair (claude-sonnet-4-6) → BUY / SELL / HOLD
+Optional Deliberation (narrative synthesis, claude-sonnet-4-6) → BUY / SELL / HOLD
     │
     ▼
-Execution Layer (Binance testnet/mainnet) + SQLite Logging
+Execution Layer (Kraken paper/live) + SQLite Logging
     │
     ├── Reflection Loop (post-trade analysis, claude-sonnet-4-6)
     └── Weekly Summary  (performance review, claude-sonnet-4-6)
 ```
 
+The default strategy (`strategies/default.yaml`) reproduces the original v2 council: Technical (40%) + Sentiment (25%) + Fundamental (35%) + Risk veto.
+
 ## Setup
 
 ```bash
@@ -35,14 +41,56 @@ pip install -e ".[dev]"
 cp .env.example .env   # fill in ANTHROPIC_API_KEY at minimum
 ```
 
+## Custom Strategies (v3)
+
+Define a strategy as a YAML file — no Python required.
+
+```yaml
+# strategies/my_strategy.yaml
+name: "My Momentum Strategy"
+agents:
+  - name: trend
+    model: claude-haiku-4-5
+    prompt: prompts/agent_template.txt   # copy & customise
+    weight: 0.60
+  - name: macro
+    model: claude-haiku-4-5
+    prompt: prompts/agent_template.txt
+    weight: 0.40
+  - name: risk_guard
+    model: claude-sonnet-4-6
+    prompt: prompts/veto_agent_template.txt
+    is_veto: true
+scoring:
+  confidence_floor: 30
+  trade_threshold: 0.25
+risk:
+  stop_loss:
+    type: atr_multiple
+    value: 2.0
+  take_profit:
+    type: fixed_pct
+    value: 0.08
+  max_position_pct: 15.0
+validation:
+  max_drawdown_pct: 12.0
+  atr_spike_multiplier: 2.5
+```
+
+Start from `strategies/example.yaml` (fully commented) and `prompts/agent_template.txt` / `prompts/veto_agent_template.txt`.
+
 ## Running
 
 ```bash
-# One-shot cycle (run once and exit)
+# One-shot cycle — default v2 council
 python -m src.main
 
+# One-shot cycle — custom strategy
+python -m src.main --strategy strategies/my_strategy.yaml
+
 # Dry run (logs council decision, no orders placed)
 DRY_RUN=1 python -m src.main
+DRY_RUN=1 python -m src.main --strategy strategies/my_strategy.yaml
 
 # Daily scheduler (00:05 UTC) + weekly summary (Sunday 08:00 UTC)
 python -m src.main --schedule
@@ -56,13 +104,20 @@ python -m src.main --weekly
 Run the LLM council against historical BTC data without executing real orders:
 
 ```bash
-# Backtest over 2024 (requires ANTHROPIC_API_KEY only — no Binance credentials needed)
+# Backtest over 2024 — default council
 python -m src.backtest.engine \
     --start 2024-01-01 \
     --end   2025-01-01 \
     --capital 250000
 
-# Shorter date range for a quick smoke test
+# Backtest with a custom strategy
+python -m src.backtest.engine \
+    --start 2023-01-01 \
+    --end   2024-01-01 \
+    --capital 250000 \
+    --strategy strategies/my_strategy.yaml
+
+# Quick smoke test
 python -m src.backtest.engine \
     --start 2024-06-01 \
     --end   2024-09-01 \
@@ -83,13 +138,17 @@ Output includes Return%, Sharpe, Max Drawdown, Win Rate, Avg Trade, and Expectan
 ## Testing
 
 ```bash
-pytest -v                                    # all 235 tests
+pytest -v                                    # all 344 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_backtest.py -v            # backtesting module
 pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
+pytest tests/test_strategy_loader.py -v     # strategy YAML loader
+pytest tests/test_strategy_scoring.py -v   # generic scoring + SL/TP rules
+pytest tests/test_strategy_runner.py -v    # generic council runner
+pytest tests/test_strategy_parity.py -v    # legacy vs generic scorer parity
 ```
 
 ## Environment Variables
@@ -108,38 +167,3 @@ pytest tests/test_agents.py::test_run_council_hold_on_veto -v  # single test
 | `LUNARCRUSH_API_KEY` | No | — | Sentiment (falls back to Fear/Greed proxy) |
 | `GLASSNODE_API_KEY` | No | — | On-chain data (falls back to zeros) |
 
-## Development Phases
-
-### v0 — Live Trading Bot
-- **Phase 1** ✅ Data pipeline + Tier-0 validation
-- **Phase 2** ✅ Agent framework (4 agents + deliberation)
-- **Phase 3** ✅ Execution layer + SQLite logging + reflection loop
-- **Phase 4** ✅ Performance metrics + weekly summary agent
-- **Phase 5** ✅ Exchange migration: Binance → Kraken (US-accessible, free)
-- **Phase 6** Paper trading (60 days minimum, DRY_RUN=1)
-- **Phase 7** Live deployment (≤ $500 initial capital, Kraken mainnet)
-
-### v1 — Backtesting
-- **Phase 1** ✅ Patch data layer (override params, `skip_freshness`)
-- **Phase 2** ✅ Historical data module (`fetch_full_ohlcv`, `slice_ohlcv`, sentiment history)
-- **Phase 3** ✅ Async signal generation loop (`generate_signals`, `_PortfolioTracker`)
-- **Phase 4** ✅ `backtesting.py` strategy + CLI runner (`run_backtest`)
-- **Phase 5** ✅ Exchange migration: Binance → Kraken
-- **Phase 6** ✅ Historical data source: Kraken OHLCV → Yahoo Finance (yfinance; unlimited history)
-
-### v2 — Agent Enhancement (spec/v2.md)
-- **Phase 1** ✅ Historical news via GDELT DOC 2.0 (`src/data/news_historical.py`) — replaces NEUTRAL_NEWS_STUB with real dated headlines filtered to an allowlist (Reuters / Bloomberg / CoinDesk / WSJ / FT / CoinTelegraph / etc.), 24h publish-lag cutoff, disk-cached under `tmp/cache/gdelt/`
-- **Phase 2** ✅ Historical on-chain via CoinMetrics Community (`src/data/onchain_historical.py`) — replaces NEUTRAL_ONCHAIN_STUB with MVRV (as SOPR proxy), transfer-volume trend (as net-flow proxy), and activity-intensity (as whale proxy)
-- **Phase 2.5** ✅ Decision-logic rework (`src/agents/scoring.py`) — replaces v1's hard 60/70 thresholds with a confidence-weighted signed-score; deliberation LLM writes narrative, Python computes the final signal deterministically; risk-veto still overrides
-- **Phase 3** ✅ Macro context via yfinance (`src/data/macro.py`) — DXY / VIX / SPX / ^TNX bundle with derived risk-on / risk-off / neutral classifier, wired through the fundamental agent
-- **Phase 4** ✅ v2 prompts (`prompts/*_v2.txt`) — directional agents retuned to use the full 0–100 confidence range and be more assertive in clear regimes; deliberation refocused on narrative; v1 prompts kept in-tree for reproducibility
-- **Phase 5** Pending — tuning sweep on 2022 window, holdout backtest Jan–Aug 2023
-
-## Success Targets (Phase 5 evaluation)
-
-| Metric | Target |
-|---|---|
-| Sharpe ratio | ≥ 1.5 |
-| Max drawdown | < 20% |
-| Expectancy | Positive |
-| Council consistency | ≥ 40% unanimous cycles |

README.md

@@ -0,0 +1,37 @@
+You are a [DESCRIBE YOUR AGENT ROLE] for a Bitcoin swing trading system.
+
+[DESCRIBE WHAT YOUR AGENT FOCUSES ON — e.g., technical price action, news sentiment, on-chain activity, macro conditions, or a combination. Be specific about which sections of the market context are most relevant to your analysis.]
+
+Your output must be a JSON object with exactly these fields:
+
+  direction   — "BUY", "SELL", or "HOLD"
+                BUY  = you believe price is likely to rise over the next 1–3 days
+                SELL = you believe price is likely to fall, or the position should be closed
+                HOLD = insufficient conviction, conflicting signals, or no clear edge
+
+  confidence  — integer 0 to 100
+                Calibration guide:
+                  80–100: very strong signal, clear and aligned evidence
+                  60–79:  solid signal, most evidence points one way
+                  40–59:  moderate signal, some evidence but notable uncertainty
+                  20–39:  weak signal, mixed or thin evidence
+                  0–19:   near-neutral, use HOLD direction at this range
+
+                Avoid defaulting to 50. Use the full scale. Low confidence should
+                be reflected in HOLD direction, not in a 50-confidence BUY/SELL.
+
+  reasoning   — string (2–4 sentences)
+                Explain WHY you chose this direction and confidence. Cite the
+                specific data from the context that drove your conclusion.
+                Mention what would change your view (invalidation conditions).
+
+Available context sections (from the market context block):
+  PRICE               — current price, 24h change, volume
+  TECHNICAL INDICATORS — RSI, MACD, Bollinger Bands, EMAs, ATR, regime
+  NEWS                — recent headlines with source and timestamp
+  SENTIMENT           — Fear/Greed index, Reddit sentiment, social volume
+  ON-CHAIN            — exchange flows, whale transactions, MVRV
+  MACRO               — VIX, DXY, SPX trend, 10Y yield, macro bias
+  PORTFOLIO           — current position, cash, drawdown
+
+Focus your analysis on the sections most relevant to your role.