SOVEREIGNTY.md — Research Sovereignty Manifest

"If this spec is implemented correctly, it is the last research document Alexander should need to request from a corporate AI." — Issue #972, March 22 2026

What This Is

A machine-readable declaration of Timmy's research independence: where we are, where we're going, and how to measure progress.

The Problem We're Solving

On March 22, 2026, a single Claude session produced six deep research reports. It consumed ~3 hours of human time and substantial corporate AI inference. Every report was valuable — but the workflow was linear. It would cost exactly the same to reproduce tomorrow.

This file tracks the pipeline that crystallizes that workflow into something Timmy can run autonomously.

The Six-Step Pipeline

Step	What Happens	Status
1. Scope	Human describes knowledge gap → Gitea issue with template	✅ Done (`skills/research/`)
2. Query	LLM slot-fills template → 5–15 targeted queries	✅ Done (`research.py`)
3. Search	Execute queries → top result URLs	✅ Done (`research_tools.py`)
4. Fetch	Download + extract full pages (trafilatura)	✅ Done (`tools/system_tools.py`)
5. Synthesize	Compress findings → structured report	✅ Done (`research.py` cascade)
6. Deliver	Store to semantic memory + optional disk persist	✅ Done (`research.py`)

Cascade Tiers (Synthesis Quality vs. Cost)

Tier	Model	Cost	Quality	Status
4	SQLite semantic cache	$0.00 / instant	reuses prior	✅ Active
3	Ollama `qwen3:14b`	$0.00 / local	★★★	✅ Active
2	Claude API (haiku)	~$0.01/report	★★★★	✅ Active (opt-in)
1	Groq `llama-3.3-70b`	$0.00 / rate-limited	★★★★	🔲 Planned (#980)

Set ANTHROPIC_API_KEY to enable Tier 2 fallback.

Research Templates

Six prompt templates live in skills/research/:

Template	Use Case
`tool_evaluation.md`	Find all shipping tools for `{domain}`
`architecture_spike.md`	How to connect `{system_a}` to `{system_b}`
`game_analysis.md`	Evaluate `{game}` for AI agent play
`integration_guide.md`	Wire `{tool}` into `{stack}` with code
`state_of_art.md`	What exists in `{field}` as of `{date}`
`competitive_scan.md`	How does `{project}` compare to `{alternatives}`

Sovereignty Metrics

Metric	Target (Week 1)	Target (Month 1)	Target (Month 3)	Graduation
Queries answered locally	10%	40%	80%	>90%
API cost per report	<$1.50	<$0.50	<$0.10	<$0.01
Time from question to report	<3 hours	<30 min	<5 min	<1 min
Human involvement	100% (review)	Review only	Approve only	None

How to Use the Pipeline

from timmy.research import run_research

# Quick research (no template)
result = await run_research("best local embedding models for 36GB RAM")

# With a template and slot values
result = await run_research(
    topic="PDF text extraction libraries for Python",
    template="tool_evaluation",
    slots={"domain": "PDF parsing", "use_case": "RAG pipeline", "focus_criteria": "accuracy"},
    save_to_disk=True,
)

print(result.report)
print(f"Backend: {result.synthesis_backend}, Cached: {result.cached}")

Implementation Status

Component	Issue	Status
`web_fetch` tool (trafilatura)	#973	✅ Done
Research template library (6 templates)	#974	✅ Done
`ResearchOrchestrator` (`research.py`)	#975	✅ Done
Semantic index for outputs	#976	🔲 Planned
Auto-create Gitea issues from findings	#977	🔲 Planned
Paperclip task runner integration	#978	🔲 Planned
Kimi delegation via labels	#979	🔲 Planned
Groq free-tier cascade tier	#980	🔲 Planned
Sovereignty metrics dashboard	#981	🔲 Planned

Governing Spec

See issue #972 for the full spec and rationale.

Research artifacts committed to docs/research/.

4.2 KiB Raw Blame History Unescape Escape