Add ECC Harness: phd_research_os/ARCHITECTURE.md

phd_research_os/ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# PhD Research OS — Architecture Map
+
+> **WAKE-UP INSTRUCTION**: This file is the ground truth for all file locations,
+> API configurations, and system topology. Read this FIRST before touching anything.
+
+## System Topology
+
+```
+phd-research-os-brain/
+├── ARCHITECTURE.md              ← YOU ARE HERE (project map)
+├── AGENTS.md                    ← Agent role registry & contracts
+├── MEMORY.md                    ← Persistent cross-session state
+├── plan.md                      ← Current task plan (mutable)
+├── HARNESS_EVOLUTION.md         ← ECC rule amendments log
+│
+├── train.py                     ← SFT training script (Qwen2.5-3B + QLoRA)
+├── generate_dataset.py          ← Synthetic dataset generator (1900 examples)
+│
+├── phd_research_os/             ← CORE PACKAGE
+│   ├── __init__.py              ← v1.0.0
+│   ├── db.py                    ← SQLite data layer (Phase 0)
+│   │                              Tables: claims, sources, goals, conflicts,
+│   │                              decisions, overrides, experiments,
+│   │                              api_usage_log, calibration_log, embedding_cache
+│   │                              + companion_agents, agent_tasks, agent_audit_log
+│   ├── agents.py                ← Original 6-role AI brain (ResearchOSBrain)
+│   ├── agent_os.py              ← ECC HARNESS ORCHESTRATOR (companion AI factory)
+│   │                              CompanionAgent lifecycle: spawn → preflight →
+│   │                              plan → execute → postflight → retire
+│   ├── pipeline.py              ← Paper ingestion (PDF → claims)
+│   ├── obsidian_export.py       ← Obsidian vault export (one-directional)
+│   ├── evaluation.py            ← Golden dataset eval harness + regression gate
+│   ├── conflict_detector.py     ← Pairwise contradiction detection
+│   └── backup.py                ← SQLite backup & restore
+│
+├── tests/
+│   ├── test_db.py               ← 22 unit tests (data layer)
+│   └── test_agent_os.py         ← ECC harness integration tests
+│
+└── output/
+    └── research_os/
+        └── db.py                ← Symlink/alias → phd_research_os/db.py
+```
+
+## API Configuration
+
+| Provider | Env Variable | Default Model | Use Case |
+|----------|-------------|---------------|----------|
+| Anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 | Primary brain + companion agents |
+| OpenAI | `OPENAI_API_KEY` | gpt-4o-mini | Fallback |
+| OpenRouter | `OPENROUTER_API_KEY` | (configurable) | Multi-model companion agents |
+| HF Local | (model path) | nkshirsa/phd-research-os-brain | Fine-tuned local inference |
+
+## Database Schema (db.py)
+
+### Core Tables (Research OS)
+- `claims` — Scientific claims with fixed-point confidence (×1000)
+- `sources` — Paper metadata (DOI, journal tier, study type)
+- `goals` — Research goals with priority ordering
+- `conflicts` — Claim contradiction pairs (hypothesis_confidence ALWAYS "low")
+- `decisions` — Proposed research actions with info gain scores
+- `overrides` — Expert confidence overrides (lock mechanism)
+- `experiments` — Lab data objects (manual approval required)
+- `api_usage_log` — Cost tracking per API call
+- `calibration_log` — Brier score data collection
+- `embedding_cache` — Semantic cache (text_hash → embedding)
+
+### ECC Harness Tables (agent_os.py)
+- `companion_agents` — Registry of spawned companion AIs
+- `agent_tasks` — Task lifecycle tracking (preflight → done)
+- `agent_audit_log` — Every action, decision, and deviation logged
+
+## Key Invariants (NEVER violate)
+
+1. **Fixed-Point Math**: All probabilities stored as INTEGER × 1000. No floats in DB.
+2. **Provenance**: All AI output is Level 5 (LLM Hypothesis). Human required for promotion.
+3. **Hypothesis Confidence**: Conflict hypotheses are ALWAYS "low". Never auto-promote.
+4. **Expert Override**: Once set, system cannot overwrite. Only human can change.
+5. **Schema Version**: Every record carries `schema_version` tag.
+6. **Companion Agent Isolation**: Companions cannot modify claims directly — they propose, humans approve.