# Agent Q3 — Orchestrator Standards
**Bucket:** `MADdegens/agent-q3-orchestrator`
**Owner:** Nick McLeod (MADdegen)
**Last updated:** 2026-05-27

---

## What this bucket is

An isolated backup of the Agent Q3 orchestrator Python layer only — `orchestrator/` from the full source tree. This is the production brain of the Agent Q3 HF Space (`MADdegens/Agent-Q3`). It is used for version control, Docker mounting, and isolated deployment of the orchestrator service.

**Do not mix in compiler, skills, or Dockerfile content here. Orchestrator Python files only.**

---

## Module structure (what belongs here)

```
orchestrator/
├── __init__.py
├── main.py              *** PROTECTED — live endpoint definitions ***
├── router.py            *** PROTECTED — cloud_priority routing logic ***
├── models.py            *** PROTECTED — Pydantic request/response schemas ***
├── config.py            *** PROTECTED — all env var settings ***
├── memory.py            — Redis 48h TTL memory facade
├── mcp_client.py        — MCP protocol client
├── skills.py            — skill file loader/registry
├── plugins.py           — plugin hook system
├── services/
│   ├── capacity.py      — backend load/quota tracking
│   ├── coder.py         — 2-stage Hermes+Qwen3 code review
│   ├── mcp_bridge.py    — gateway to all MCP servers
│   ├── monitor.py       — Hermes analysis + Qwen3 remediation
│   ├── research.py      — multi-provider deep research
│   └── skill_compiler.py — ChromaDB RAG engine (auto skill injection)
├── tools/
│   ├── free_search.py
│   ├── mcp_search.py
│   ├── memory_store.py  — Redis setex 172800s (48h TTL)
│   ├── multi_agent_router.py
│   ├── perplexity_search.py
│   ├── prediction_markets.py
│   └── web_search.py
├── reasoning/
│   └── decision_graph.py
├── observability/
│   └── tracing.py
└── providers/
    └── __init__.py
```

---

## PROTECTED files — never overwrite without explicit owner approval

These 4 files define the live production service. Any change requires:
1. Show the full diff to the owner
2. Receive explicit written confirmation
3. Only then upload

| File | Why protected |
|------|--------------|
| `main.py` | All 8 live endpoints — `/v1/chat`, `/v1/instruct`, `/v1/reason`, `/v1/code`, `/v1/coder`, `/v1/generate`, `/v1/parse`, `/v1/tandem` |
| `router.py` | cloud_priority chain: Ollama Cloud → Moonshot → OpenRouter → HF Router → RunPod |
| `models.py` | Pydantic schemas — breaking change = live Space crash |
| `config.py` | All env var bindings — wrong value = silent failure in production |

---

## Model name rules (enforce on every upload)

All model references MUST use the `nicholasjmcleod/` Ollama Cloud namespace:

| Role | Correct tag |
|------|-------------|
| reasoner | `nicholasjmcleod/kimi-linear:q6_k` |
| tandem | `nicholasjmcleod/harmonic-hermes:q6_k` |
| coder / coder_dedicated | `nicholasjmcleod/qwen3-coder-53b:q6_k` |
| kimi_distilled | `nicholasjmcleod/kimi-distilled:iq4_xs` |
| genstruct | `nicholasjmcleod/genstruct:q6_k` |
| infinity_parser | `nicholasjmcleod/infinity-parser:latest` |

**Never use:** `maddegens/*`, `hermes3:8b`, `qwen3:48b-a4b`, `fallback`, `qwopus`, or any removed model name.

---

## Redis memory TTL

`memory_store.py` uses `setex(..., 172800, ...)` — **48 hours**. Do not change without owner instruction.

---

## Upload procedure

```bash
hf sync ./orchestrator/ hf://buckets/MADdegens/agent-q3-orchestrator
```

---

## Post-upload audit checklist

```bash
hf buckets ls MADdegens/agent-q3-orchestrator --recursive
```

- [ ] All 4 protected files present (`main.py`, `router.py`, `models.py`, `config.py`)
- [ ] `services/skill_compiler.py` present
- [ ] `tools/memory_store.py` TTL is 172800 (grep to verify)
- [ ] No `.env`, credentials, or MAD Gambit content
- [ ] No compiler/Gradio files mixed in

---

## Change log

| Date | Action | Files changed | By |
|------|--------|---------------|----|
| 2026-05-27 | Initial bucket upload — 28 orchestrator files | All modules | Claude Code / MADdegen |
| 2026-05-27 | Redis TTL updated 86400 → 172800 (24h → 48h) | `tools/memory_store.py` | Claude Code / MADdegen |