11# ChainCommand — Claude Code Guide
22
33## Project Overview
4- ChainCommand is a supply chain AI agent system with 10 autonomous agents, ML forecasting, optimization, and event-driven architecture .
4+ ChainCommand is a supply chain risk and inventory operations platform combining CP-SAT constraint optimization, RL inventory policy, BOM management, supplier risk scoring, and CTB (Clear-to-Build) analysis .
55
66## Quick Start
77``` bash
@@ -11,52 +11,53 @@ pytest tests/ -v # Run tests
1111ruff check chaincommand/ tests/ # Lint
1212```
1313
14- ## Architecture (v2.0)
15- - ** 10 agents** across 4 layers (strategic/tactical/operational/orchestration)
16- - ** Orchestration** : Classic sequential OR LangGraph state machine (` CC_ORCHESTRATOR_MODE ` )
17- - ** Forecasting** : LSTM + XGBoost ensemble + optional Chronos-2
18- - ** Optimization** : GA + DQN hybrid + OR-Tools CP-SAT (supplier allocation)
19- - ** Causal** : DoWhy causal inference for supplier switching decisions
20- - ** Observability** : AgentTracer, TokenBudget, ResponseCache
21- - ** Resilience** : CircuitBreaker, GracefulDegradation (4 levels)
14+ ## Architecture (v3.0)
15+ - ** CP-SAT Optimization** : OR-Tools MILP solver for multi-supplier allocation
16+ - ** RL Inventory Policy** : PPO (Stable-Baselines3) with (s,S) baseline comparison
17+ - ** BOM Management** : Multi-tier BOM tree, explosion, where-used, cost rollup
18+ - ** Supplier Risk Scoring** : 5-factor rule-based + RandomForest ML blending
19+ - ** CTB Dashboard** : Clear-to-Build analysis with shortage detection
20+ - ** ML Models** : LSTM + XGBoost ensemble forecaster, Isolation Forest anomaly detector
21+ - ** Event Bus** : Async pub/sub for KPI violations and alerts
22+ - ** AWS Backend** : Optional S3/Redshift/Athena/QuickSight persistence
2223
2324## Key Directories
24- - ` chaincommand/agents/ ` — 10 agent implementations
25- - ` chaincommand/models/ ` — ML models (forecaster, anomaly_detector, optimizer, chronos)
2625- ` chaincommand/optimization/ ` — CP-SAT MILP optimizer + benchmark
27- - ` chaincommand/causal/ ` — DoWhy causal inference
26+ - ` chaincommand/rl/ ` — RL inventory environment, trainer, policy
27+ - ` chaincommand/bom/ ` — BOM tree models + manager
28+ - ` chaincommand/risk/ ` — Supplier risk scoring (rule-based + ML)
29+ - ` chaincommand/ctb/ ` — Clear-to-Build analyzer
30+ - ` chaincommand/models/ ` — ML models (forecaster, anomaly_detector, optimizer)
2831- ` chaincommand/kpi/ ` — 12-metric KPI engine
2932- ` chaincommand/events/ ` — Async pub/sub event bus
3033- ` chaincommand/api/ ` — FastAPI REST + WebSocket
3134- ` chaincommand/aws/ ` — AWS persistence (S3/Redshift/Athena/QuickSight)
32- - ` tests/ ` — 120 + tests across 10 test modules
35+ - ` tests/ ` — 100 + tests across test modules
3336
3437## Configuration
35- All settings via ` CC_ ` env prefix or ` .env ` file. Key v2.0 settings:
36- - ` CC_ORCHESTRATOR_MODE ` : classic | langgraph
37- - ` CC_ENABLE_CAUSAL_ANALYSIS ` : true/false
38- - ` CC_ENABLE_CHRONOS ` : true/false
39- - ` CC_TOKEN_BUDGET_PER_CYCLE ` : token limit per decision cycle
40- - ` CC_CIRCUIT_BREAKER_FAILURE_THRESHOLD ` : failures before circuit opens
38+ All settings via ` CC_ ` env prefix or ` .env ` file. Key settings:
39+ - ` CC_ORTOOLS_RISK_LAMBDA ` : Risk-cost trade-off for CP-SAT (default: 0.3)
40+ - ` CC_RL_TOTAL_TIMESTEPS ` : RL training steps (default: 50000)
41+ - ` CC_BOM_DEFAULT_ASSEMBLIES ` : Synthetic BOM count (default: 5)
42+ - ` CC_CTB_DEFAULT_BUILD_QTY ` : Default build quantity for CTB (default: 100)
4143
4244## Testing
4345``` bash
4446pytest tests/ -v --tb=short # All tests
4547pytest tests/test_optimization/ # CP-SAT tests only
46- pytest tests/test_causal/ # Causal inference tests
47- pytest tests/test_resilience/ # Circuit breaker tests
48+ pytest tests/test_rl/ # RL inventory tests
49+ pytest tests/test_bom/ # BOM tests
50+ pytest tests/test_ctb/ # CTB tests
51+ pytest tests/test_risk/ # Risk scoring tests
4852```
4953
5054## Development Guidelines
51- - Always JSON-serialize datetime objects and numpy types before sending through WebSocket. Use ` SafeEncoder ` (see root CLAUDE.md).
52- - Test WebSocket ` /ws/live ` endpoint immediately after changes to catch routing/serialization issues.
55+ - Always JSON-serialize datetime objects and numpy types before sending through WebSocket.
5356- After editing Python files, verify syntax with ` python -m py_compile <file> ` .
5457- Run ` pytest tests/ -v ` after code changes, not as a final step.
5558
5659## Dependencies
5760Core deps always installed. Optional groups:
58- - ` pip install -e ".[langgraph]" ` — LangGraph orchestrator
5961- ` pip install -e ".[ortools]" ` — OR-Tools CP-SAT
60- - ` pip install -e ".[causal]" ` — DoWhy
61- - ` pip install -e ".[chronos]" ` — Chronos-2
62+ - ` pip install -e ".[rl]" ` — Gymnasium + Stable-Baselines3
6263- ` pip install -e ".[all]" ` — Everything
0 commit comments