Merge pull request #1 from cpparnell/feature/v1

v1.0

Author: cpparnell

.DS_Store

@@ -1,16 +1,17 @@
 # Anthropic API key (required for all LLM agent calls)
 ANTHROPIC_API_KEY=
 
-# Trading mode: paper (Binance testnet, default) | live (Binance mainnet)
+# Trading mode: paper (DRY_RUN, default) | live (Kraken 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=
+# Kraken API credentials (required for live order execution only)
+# Not needed for backtesting or paper trading (DRY_RUN=1)
+KRAKEN_API_KEY=
+KRAKEN_SECRET=
 
-# News feeds
+# News feeds (optional — falls back to empty list without keys)
 CRYPTOPANIC_API_KEY=
 NEWSAPI_KEY=
 
@@ -25,15 +26,11 @@ CRYPTOQUANT_API_KEY=
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
 
-# 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)
+# Set to 1 to skip order execution and log only (paper trading mode)
 # DRY_RUN=0

.env.example

@@ -210,4 +210,9 @@ __marimo__/
 .claude/
 
 # Misc.
-NOTES.md
+NOTES.md
+CHANGELOG.md
+
+# Temporary files
+tmp/
+prompts/personal/

.gitignore

@@ -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/Binance, 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
@@ -51,26 +99,65 @@ python -m src.main --schedule
 python -m src.main --weekly
 ```
 
+## Backtesting
+
+Run the LLM council against historical BTC data without executing real orders:
+
+```bash
+# Backtest over 2024 — default council
+python -m src.backtest.engine \
+    --start 2024-01-01 \
+    --end   2025-01-01 \
+    --capital 250000
+
+# 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 \
+    --capital 250000 \
+    --no-save-csv
+```
+
+**Cost:** ~$10–15 in Anthropic API calls per year of daily cycles (~365 × ~$0.03).
+
+**Capital note:** Set `--capital` high enough that 20% position sizing can buy at least 1 BTC. At ~$50k/BTC you need at least `--capital 250000`.
+
+Each run creates a timestamped folder under `tmp/YYYYMMDD_HHMMSS/` containing:
+- `backtest_signals_<start>_<end>.csv` — per-day signal log, written one row per cycle (flushed immediately) so it survives a kill
+- `run.log` — full console output, written continuously (line-buffered) so it survives a kill
+
+Output includes Return%, Sharpe, Max Drawdown, Win Rate, Avg Trade, and Expectancy.
+
 ## Testing
 
 ```bash
-pytest -v                                    # all 203 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
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `ANTHROPIC_API_KEY` | Yes | — | Claude API key |
-| `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 |
+| `KRAKEN_API_KEY` | Live mode | — | Kraken API key |
+| `KRAKEN_SECRET` | Live mode | — | Kraken private key |
 | `COUNCIL_DB_PATH` | No | `./council.db` | SQLite database path |
 | `INITIAL_CAPITAL` | No | `10000` | Starting paper capital (USD) |
 | `TRADING_MODE` | No | `paper` | `paper` (testnet) or `live` (mainnet) |
@@ -80,20 +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
-
-- **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** 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 |

CHANGELOG.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.