123 lines
4.2 KiB
Markdown
123 lines
4.2 KiB
Markdown
|
# 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
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
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](http://143.198.27.163:3000/Rockachopa/Timmy-time-dashboard/issues/972) for the full spec and rationale.
|
|||
|
|
|
|||
|
|
Research artifacts committed to `docs/research/`.
|