chore: align task1 spec compliance

docs/plans/2026-03-28-binance-event-contract-agent-design.md

@@ -0,0 +1,400 @@
+# Binance Event Contract Agent Design
+
+## Summary
+
+Build a high-cohesion single-project quantitative agent platform for Binance event contracts with:
+
+- modular-monolith backend
+- React frontend for live visibility and operator control
+- multi-agent orchestration built on deepagents
+- parallel dry-run strategy execution
+- backtesting and experiment management
+- self-optimization through validated strategy iteration
+- OpenAI-compatible model abstraction for provider-agnostic model switching
+- manual confirmation gate for any live order
+
+The system starts as a local development project and should later deploy to a personal cloud server without architectural rework.
+
+## Product Goals
+
+- Focus only on Binance event contracts for up/down prediction markets.
+- Support `dry-run` simulation for multiple strategies at the same time.
+- Support historical backtesting and forward-style evaluation.
+- Support continuous self-improvement through AI-proposed strategy variants that are validated before promotion.
+- Avoid single-agent lock-in; the architecture must support multiple cooperating agents.
+- Keep deployment simple by using a single repository and a single deployable application.
+- Provide a React frontend that exposes data, strategy performance, experiments, and live confirmation actions in real time.
+
+## Non-Goals For V1
+
+- Fully automatic live trading without human approval
+- Multi-exchange support
+- External sentiment, news, or on-chain data ingestion
+- Multi-service microservice deployment
+- Complex user/team management
+
+## Architectural Direction
+
+Use a modular monolith:
+
+- one repository
+- one backend application process boundary
+- one frontend application
+- shared database and cache
+
+Internally, split responsibilities into modules rather than services. This preserves simple deployment while keeping agent logic, experiment logic, data ingestion, and execution control from collapsing into one code path.
+
+## Core Modules
+
+### Frontend
+
+React application for:
+
+- live market and strategy monitoring
+- experiment visibility
+- model/config management
+- manual live trade confirmation
+
+### API/App
+
+Single backend entrypoint exposing:
+
+- HTTP APIs
+- WebSocket streams
+- job scheduling entrypoints
+- configuration management
+- audit/log access
+
+### Agent Runtime
+
+deepagents-based orchestration layer responsible for:
+
+- agent role definitions
+- shared context passing
+- structured outputs
+- task lifecycle management
+- strategy run coordination
+
+### Strategy Lab
+
+Holds the strategy lifecycle:
+
+- strategy definitions
+- candidate generation
+- dry-run execution
+- backtest execution
+- scoring
+- promotion/demotion states
+
+### Market Data
+
+Responsible for:
+
+- Binance market/event contract data ingestion
+- normalization
+- snapshot/versioning
+- storage and replay support
+
+V1 uses only base market data and event-contract-related inputs, while preserving extension points for future external datasets.
+
+### Execution Ledger
+
+Responsible for:
+
+- simulated orders
+- live trade proposals
+- manual confirmation workflow
+- trade and position records
+- audit logs
+
+## Multi-Agent Design
+
+V1 uses five agent roles.
+
+### Orchestrator Agent
+
+Coordinates runs and experiments. It starts tasks, routes context, and manages the lifecycle of research, dry-run, and backtest sessions. It does not directly own execution rights.
+
+### Signal Agent
+
+Produces directional predictions, confidence, and structured rationale from standardized market inputs for a specific strategy instance.
+
+### Risk Agent
+
+Evaluates whether a signal should be reduced, skipped, or flagged as unsafe based on explicit risk rules and uncertainty markers.
+
+### Evaluator Agent
+
+Analyzes dry-run and backtest outcomes to explain where a strategy is performing well or degrading.
+
+### Optimizer Agent
+
+Proposes new strategy variants by changing prompts, thresholds, feature windows, risk parameters, model profiles, or role bindings. It cannot bypass validation.
+
+## Control Boundaries
+
+- Agents are proposers, not final executors.
+- System state transitions control promotion and execution.
+- Live trading always requires explicit human confirmation.
+- Invalid model outputs are rejected instead of being silently interpreted.
+
+## Strategy Model
+
+Treat every strategy as a versioned experiment unit with:
+
+- strategy id
+- version
+- agent composition
+- model profile bindings
+- feature configuration
+- risk configuration
+- scoring configuration
+- current state: `draft`, `candidate`, `dry-run`, `approved-for-live`, `archived`
+- result summaries and experiment lineage
+
+This enables many strategies to run in parallel without losing comparability.
+
+## Time Horizon Design
+
+Binance event contracts impose a minimum short-horizon decision cycle around 10 minutes. The system should therefore:
+
+- align decision opportunities with event contract timing constraints
+- keep the trade decision cycle centered on supported market windows such as `10m`
+- allow feature observation windows to vary and be optimized experimentally
+
+The optimization process may test different observation horizons such as `5m`, `15m`, `30m`, and longer context windows, but the underlying tradeable event window remains grounded in exchange constraints.
+
+## Optimization Objective
+
+The primary optimization target is risk-adjusted return, not raw profit or hit rate.
+
+Recommended scoring inputs:
+
+- net return
+- max drawdown penalty
+- stability across windows
+- minimum sample sufficiency
+- overtrading penalty
+
+This prevents the optimizer from overfitting to noisy short-term gains.
+
+## Data Scope
+
+V1 implements only core market data and event-contract-relevant inputs, while preserving extension points for future external sources.
+
+This means:
+
+- ingest and store normalized core market data first
+- do not block the architecture on sentiment/news/on-chain feeds
+- model the feature pipeline so external factors can be added later without redesign
+
+## Core Pipelines
+
+### 1. Real-Time Observation Pipeline
+
+`market-data -> normalization -> storage/cache -> websocket/frontend`
+
+This pipeline produces trustworthy current-state inputs and never fabricates strategy outputs.
+
+### 2. Dry-Run Decision Pipeline
+
+For every active strategy and decision point:
+
+`market-data snapshot -> Signal Agent -> Risk Agent -> simulated order -> settlement -> ledger`
+
+Parallel dry-run strategies are a first-class feature.
+
+### 3. Backtest and Experiment Pipeline
+
+For every proposed candidate variant:
+
+`historical window selection -> replay -> scoring -> ranking -> persistence`
+
+Backtest results determine candidate quality but do not directly authorize live trading.
+
+### 4. Optimization Feedback Loop
+
+`Evaluator Agent -> structured diagnosis -> Optimizer Agent proposal -> backtest queue -> candidate promotion`
+
+AI proposes changes. The platform validates them. Validated results become future input to the AI. This closed loop is central to the project.
+
+## Versioning Requirements
+
+The platform should version at least:
+
+- market data snapshots
+- strategy definitions
+- prompt templates
+- model profiles
+- experiment runs
+- evaluation outputs
+
+Without versioning, later comparisons and regressions become untrustworthy.
+
+## Model Abstraction
+
+Use OpenAI-compatible APIs behind a provider-agnostic model profile layer.
+
+Each `LLM Profile` should include:
+
+- profile name
+- provider name
+- API base URL
+- API key reference
+- model name
+- generation parameters
+- timeout/retry metadata
+- structured output capability flags
+- optional cost metadata
+- optional tags such as `fast`, `cheap`, `reasoning`, `production`
+
+## Model Configuration Layers
+
+### Global Defaults
+
+Project-wide fallbacks for model behavior and timeouts.
+
+### Agent-Level Binding
+
+Specific agents bind to specific model profiles.
+
+### Strategy-Level Override
+
+Individual strategy experiments may override model profile bindings to support controlled comparisons.
+
+This structure supports systematic experiments such as swapping only the `Signal Agent` model while keeping all else fixed.
+
+## Frontend Views
+
+V1 should provide five core views.
+
+### Dashboard
+
+Shows:
+
+- current market state
+- event contract timing
+- active strategy counts
+- recent signals
+- recent simulated outcomes
+- alerts and runtime health
+
+### Strategies
+
+Shows:
+
+- strategy version metadata
+- current state
+- recent performance metrics
+- drawdown
+- hit rate
+- score trend
+
+### Experiments
+
+Shows:
+
+- queued/running/completed backtests
+- ranking tables
+- parameter deltas
+- model comparisons
+- promotion decisions
+
+### Live Confirm
+
+Shows:
+
+- proposed live trade
+- confidence
+- risk summary
+- recent comparable performance
+- explicit confirm/reject actions
+
+This screen is the manual gate for all live execution.
+
+### Models & Config
+
+Shows and edits:
+
+- OpenAI-compatible model profiles
+- agent bindings
+- optimization parameters
+- risk limits
+
+## Realtime Communication
+
+Use:
+
+- HTTP for CRUD and historical queries
+- WebSocket for streaming market updates, strategy events, experiment progress, and alerts
+
+## Safety, Risk, and Promotion Rules
+
+- Dry-run may be automatic.
+- Live execution may not be automatic.
+- No strategy may enter live use without explicit human confirmation.
+- Candidate promotion requires minimum sample size and drawdown/stability gates.
+- Missing or stale data causes a skip, not a fabricated signal.
+
+## Error Handling
+
+The platform must explicitly handle:
+
+- market data gaps or staleness
+- malformed or timed-out model responses
+- replay/backtest alignment failures
+- frontend/backend state drift
+
+Rule: when reliability is uncertain, skip the decision and record why.
+
+## Testing and Trustworthiness
+
+V1 should include:
+
+- unit tests for scoring, validation, and risk rules
+- replay tests for deterministic historical decision reproduction
+- integration tests for end-to-end dry-run flow
+- benchmark comparisons against simple baselines
+
+Required baselines:
+
+- random direction baseline
+- simple momentum baseline
+- simple mean-reversion baseline
+
+Any AI-generated strategy must outperform relevant baselines on risk-adjusted criteria before it is considered useful.
+
+## Backtest Integrity Rules
+
+- separate training, validation, and forward evaluation windows
+- no future leakage
+- feature construction only from historically available data
+- sample-out performance matters more than in-sample optimization
+- strategy promotion uses risk-adjusted metrics, not only peak profit
+
+## Deployment Direction
+
+The project should be designed so that:
+
+- local development is straightforward
+- later deployment to a personal cloud server does not require architecture changes
+- packaging can converge toward a single-command local start and a simple containerized deployment path
+
+## Delivery Guidance
+
+V1 should prioritize a narrow but rigorous vertical slice:
+
+- data ingestion
+- one decision cycle
+- multi-strategy dry-run
+- backtest loop
+- optimizer proposal loop
+- React visibility
+- manual live-confirm screen
+
+This is enough to validate the platform without prematurely building a broad trading system.
+
+## Constraints And Open Preconditions
+
+- Current workspace is not a Git repository, so the design document cannot be committed yet.
+- The implementation plan should assume repository initialization or placement inside a real project repository before coding begins.