consolidate: unified Agent Q3 README — HQ + Evo

README.md

@@ -0,0 +1,116 @@
+---
+language:
+- en
+license: apache-2.0
+tags:
+- agent
+- multi-agent
+- langgraph
+- gguf
+- lora
+- qwen
+- prediction-markets
+- mad-gambit
+- solidity
+- tandem-core
+- agent-q3
+- agent-q3-hq
+- agent-q3-evo
+pipeline_tag: text-generation
+---
+
+# Agent Q3
+
+> **MAD Gambit** — Multi-agent intelligence layer
+> Contains both **Agent Q3 [HQ]** (production orchestration) and **Agent Q3 [Evo]** (self-improving research pipeline)
+
+---
+
+## Variants
+
+| Variant | Role | Key Tech |
+|---------|------|----------|
+| **Agent Q3 [HQ]** | Production orchestration | Tandem Core · ComputeRouter · LangGraph · MCP · Solidity audit |
+| **Agent Q3 [Evo]** | Self-improving research | LoRA fine-tuning · arXiv ingestion · ChromaDB · Unsloth · benchmarks |
+
+---
+
+## File Structure
+
+```
+Agent-Q3/
+├── README.md
+│
+├── hq/                          ← Agent Q3 [HQ] — Production
+│   ├── Dockerfile
+│   ├── docker-compose.yml
+│   ├── requirements.txt
+│   ├── .env.example
+│   ├── orchestrator.py          ← FastAPI + ComputeRouter
+│   ├── compute_router.py        ← Multi-backend weighted routing
+│   ├── tandem_core.py           ← Gemma4 Reasoner + Qwen3.5 Coder chain
+│   ├── langgraph_graph.py       ← StateGraph agent orchestration
+│   ├── mcp_config.json          ← 14 MCP server connectors
+│   ├── litellm_config.yaml      ← LiteLLM routing config
+│   └── metrics.py               ← Prometheus /metrics endpoint
+│
+├── evo/                         ← Agent Q3 [Evo] — Research
+│   ├── Dockerfile
+│   ├── requirements.txt
+│   ├── .env.example
+│   ├── training_pipeline.py     ← Unsloth LoRA fine-tuning
+│   ├── arxiv_ingestor.py        ← arXiv fetch → chunk → embed
+│   ├── chromadb_store.py        ← Vector store (nomic-embed-text 384-dim)
+│   ├── feedback_collector.py    ← DPO/RLHF signal capture
+│   ├── benchmark_runner.py      ← Domain QA evaluation
+│   ├── lora_pusher.py           ← Push adapters to HF
+│   └── langgraph_graph.py       ← StateGraph agent orchestration
+│
+└── shared/                      ← Shared utilities
+    ├── auth.py
+    ├── logger.py
+    └── config.py
+```
+
+---
+
+## HQ — Quick Start
+
+```bash
+cd hq
+cp .env.example .env
+docker compose up --build
+```
+
+**Endpoints:**
+- `POST /v1/chat` — auto-classify → Reasoner or Coder
+- `POST /v1/reason` — force Gemma4-E4B (planning, research, audit)
+- `POST /v1/code` — force Qwen3.5-4B (code, debug, file ops)
+- `POST /v1/tandem` — Gemma4 reasons → Qwen3.5 implements
+- `GET  /health` — backend health + loaded models
+- `GET  /metrics` — Prometheus metrics
+
+## Evo — Quick Start
+
+```bash
+cd evo
+cp .env.example .env
+pip install -r requirements.txt
+python training_pipeline.py
+```
+
+---
+
+## Linked HF Assets
+
+| Type | Label | Link |
+|------|-------|------|
+| Model | Agent Q3 (unified) | [madDegen/agent-q3-core](https://hf.co/madDegen/agent-q3-core) |
+| Dataset | Agent Q3 (unified) | [madDegen/agent-q3](https://hf.co/datasets/madDegen/agent-q3) |
+| Space | Agent Q3 (unified) | [madDegen/agent-q3-space](https://hf.co/spaces/madDegen/agent-q3-space) |
+
+---
+
+## License
+
+Apache 2.0