From 6905a10f05c11a33c16b7c6f69ae3b463690a66e Mon Sep 17 00:00:00 2001
From: Bill <bill@bballou.com>
Date: Sat, 1 Nov 2025 11:33:58 -0400
Subject: [PATCH] docs: add development mode documentation

Add comprehensive development mode documentation to README.md, API_REFERENCE.md, and CLAUDE.md:

README.md:
- New "Development Mode" section after Configuration
- Quick start guide with environment variables
- Explanation of DEV vs PROD mode behavior
- Mock AI behavior and stock rotation details
- Environment variables reference
- Use cases and limitations

API_REFERENCE.md:
- New "Deployment Mode" section after health check
- Response format with deployment_mode fields
- DEV mode behavior explanation
- Health check example with deployment fields
- Use cases for testing and CI/CD

CLAUDE.md:
- New "Development Mode" subsection in Important Implementation Details
- Deployment modes overview
- DEV mode characteristics
- Implementation details with file references
- Testing commands and mock behavior notes

All sections explain:
- DEPLOYMENT_MODE environment variable (PROD/DEV)
- PRESERVE_DEV_DATA flag for dev data persistence
- Mock AI provider with deterministic stock rotation
- Separate dev database and data paths
- Use cases for development and testing
---
 API_REFERENCE.md | 56 +++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md        | 31 +++++++++++++++++++++++
 README.md        | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 152 insertions(+)

diff --git a/API_REFERENCE.md b/API_REFERENCE.md
index 2f789a8..15b34e8 100644
--- a/API_REFERENCE.md
+++ b/API_REFERENCE.md
@@ -414,6 +414,62 @@ curl http://localhost:8080/health
 
 ---
 
+## Deployment Mode
+
+All API responses include a `deployment_mode` field indicating whether the service is running in production or development mode.
+
+### Response Format
+
+```json
+{
+  "job_id": "abc123",
+  "status": "completed",
+  "deployment_mode": "DEV",
+  "is_dev_mode": true,
+  "preserve_dev_data": false
+}
+```
+
+**Fields:**
+- `deployment_mode`: "PROD" or "DEV"
+- `is_dev_mode`: Boolean flag
+- `preserve_dev_data`: Null in PROD, boolean in DEV
+
+### DEV Mode Behavior
+
+When `DEPLOYMENT_MODE=DEV` is set:
+- No AI API calls (mock responses)
+- Separate dev database (`jobs_dev.db`)
+- Separate data directory (`dev_agent_data/`)
+- Database reset on startup (unless PRESERVE_DEV_DATA=true)
+
+**Health Check Example:**
+
+```bash
+curl http://localhost:8080/health
+```
+
+Response in DEV mode:
+```json
+{
+  "status": "healthy",
+  "database": "connected",
+  "timestamp": "2025-01-16T10:00:00Z",
+  "deployment_mode": "DEV",
+  "is_dev_mode": true,
+  "preserve_dev_data": false
+}
+```
+
+### Use Cases
+
+- **Testing:** Validate orchestration without AI API costs
+- **CI/CD:** Automated testing in pipelines
+- **Development:** Rapid iteration on system logic
+- **Configuration validation:** Test settings before production
+
+---
+
 ## Common Workflows
 
 ### Trigger and Monitor a Simulation
diff --git a/CLAUDE.md b/CLAUDE.md
index 0610ac5..2aa5f4d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -294,6 +294,37 @@ bash main.sh
 - Logs include timestamps, signature, and all message exchanges
 - Position updates append to single `position/position.jsonl`
 
+**Development Mode:**
+
+AI-Trader supports a development mode that mocks AI API calls for testing without costs.
+
+**Deployment Modes:**
+- `DEPLOYMENT_MODE=PROD`: Real AI calls, production data paths
+- `DEPLOYMENT_MODE=DEV`: Mock AI, isolated dev environment
+
+**DEV Mode Characteristics:**
+- Uses `MockChatModel` from `agent/mock_provider/`
+- Data paths: `data/dev_agent_data/` and `data/trading_dev.db`
+- Dev database reset on startup (controlled by `PRESERVE_DEV_DATA`)
+- API responses flagged with `deployment_mode` field
+
+**Implementation Details:**
+- Deployment config: `tools/deployment_config.py`
+- Mock provider: `agent/mock_provider/mock_ai_provider.py`
+- LangChain wrapper: `agent/mock_provider/mock_langchain_model.py`
+- BaseAgent integration: `agent/base_agent/base_agent.py:146-189`
+- Database handling: `api/database.py` (automatic path resolution)
+
+**Testing Dev Mode:**
+```bash
+DEPLOYMENT_MODE=DEV python main.py configs/default_config.json
+```
+
+**Mock AI Behavior:**
+- Deterministic stock rotation (AAPL → MSFT → GOOGL → etc.)
+- Each response includes price query, buy order, and finish signal
+- No actual AI API calls or costs
+
 ## Testing Changes
 
 When modifying agent behavior or adding tools:
diff --git a/README.md b/README.md
index 4895e41..36d53b2 100644
--- a/README.md
+++ b/README.md
@@ -365,6 +365,71 @@ Edit `configs/default_config.json`:
 
 ---
 
+## 🛠️ Development Mode
+
+AI-Trader supports a development mode that mocks AI API calls for testing without costs.
+
+### Quick Start
+
+```bash
+# Set environment variables
+export DEPLOYMENT_MODE=DEV
+export PRESERVE_DEV_DATA=false
+
+# Run simulation (uses mock AI, isolated dev database)
+python main.py configs/default_config.json
+```
+
+### How It Works
+
+**DEPLOYMENT_MODE=DEV:**
+- Mock AI responses (no API calls to OpenAI/Anthropic)
+- Separate database: `data/trading_dev.db`
+- Separate data directory: `data/dev_agent_data/`
+- Dev database reset on startup (unless PRESERVE_DEV_DATA=true)
+- Warnings logged if production API keys detected
+
+**DEPLOYMENT_MODE=PROD** (default):
+- Real AI API calls
+- Production database: `data/trading.db`
+- Production data directory: `data/agent_data/`
+
+### Mock AI Behavior
+
+The mock provider returns deterministic responses that rotate through stocks:
+- Day 1: AAPL
+- Day 2: MSFT
+- Day 3: GOOGL
+- Etc. (cycles through 10 stocks)
+
+Each mock response includes:
+- Price queries for selected stock
+- Buy order for 5 shares
+- Finish signal to end session
+
+### Environment Variables
+
+```bash
+DEPLOYMENT_MODE=PROD          # PROD or DEV (default: PROD)
+PRESERVE_DEV_DATA=false      # Keep dev data between runs (default: false)
+```
+
+### Use Cases
+
+- **Orchestration testing:** Verify agent loop, position tracking, logging
+- **CI/CD pipelines:** Run tests without API costs
+- **Configuration validation:** Test date ranges, model configs
+- **Development iteration:** Rapid testing of code changes
+
+### Limitations
+
+- Mock responses are static (not context-aware)
+- No actual market analysis
+- Fixed trading pattern
+- For logic testing only, not trading strategy validation
+
+---
+
 ## 📊 Database Schema
 
 SQLite database at `data/jobs.db` contains: