|
| 1 | +# Imprint — Self-Learning Task Handler for A3M Router |
| 2 | +### *Every request leaves an imprint. Eventually, the imprints become instinct.* |
| 3 | + |
| 4 | +**Package:** `imprint-router` (npm ✅ PyPI ✅) · **Product name:** Imprint · **Repo (planned):** `Das-rebel/imprint` |
| 5 | +**Status:** Plan v2 — rebuilt by agent council (Claude-MiniMax + Gemini-2.5 + research agents ×10) |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## Executive Summary (council-rebuilt) |
| 10 | + |
| 11 | +Imprint is a complementary service that watches A3M Router traffic, detects repeatable task |
| 12 | +patterns ("signatures"), and progressively optimizes them — **v1 by evolving context/skill-prompts, |
| 13 | +v2 by distilling weights into self-managed local adapters.** Its key differentiator is an adaptive |
| 14 | +learning policy driven by router economics data (cost-per-signature, cache affinity) that no |
| 15 | +competitor has. Promotion ladder (`shadow → canary → preferred → pinned`) with drift-triggered |
| 16 | +auto-demote ensures quality never silently regresses. The result: your AI bill decays over time. |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## The Strategic Pivot (from council review) |
| 21 | + |
| 22 | +**v1 evolves CONTEXT, not weights.** |
| 23 | + |
| 24 | +| | Weight-distillation (old plan) | Context-evolution (new v1) | |
| 25 | +|---|---|---| |
| 26 | +| Mechanism | QLoRA per signature | Optimized skill-prompts + few-shot packs per signature | |
| 27 | +| Ship time | ~10 weeks to first value | **~3 weeks** | |
| 28 | +| Risk | Silent quality regression, GPU needed | Prompt-only failure modes, CPU-only | |
| 29 | +| Evidence | ACE framework: context often beats weights for narrow adaptation | SkillOpt (16K⭐) validates demand | |
| 30 | +| v2 role | — | Weights kick in when prompts plateau (Phase 3+) | |
| 31 | + |
| 32 | +This directly addresses the council's #1 strategic flaw: weight-distillation-first was premature. |
| 33 | +Microsoft SkillOpt proves trace→skill works; nobody pairs it with router economics. That's our wedge. |
| 34 | + |
| 35 | +--- |
| 36 | + |
| 37 | +## Architecture |
| 38 | + |
| 39 | +``` |
| 40 | +A3M Router ──telemetry──▶ Collector ──▶ Signature Miner ──▶ Skill Evolver (v1) |
| 41 | + ▲ │ │ |
| 42 | + │ ▼ ▼ |
| 43 | + └────────── OpenAI-compatible ◀──── Promotion Ladder ◀──── Eval Gate |
| 44 | + endpoint: imprint-local (shadow→canary→preferred→pinned) |
| 45 | + │ |
| 46 | + Phase 3+: Distiller (QLoRA via LoRAX) |
| 47 | +``` |
| 48 | + |
| 49 | +- **Serving backend (v2): LoRAX** (Apache-2, 3.8K⭐) — purpose-built multi-adapter serving on one 24GB GPU. |
| 50 | +- **Escalation-on-uncertainty:** low-confidence responses return `X-Imprint-Escalate: true`; A3M routes live. |
| 51 | +- **Loose coupling:** Imprint subscribes to A3M logs; appears back as provider `imprint-local` (cost≈0). |
| 52 | + |
| 53 | +## The Killer Differentiator (open gap confirmed by research) |
| 54 | + |
| 55 | +**Economics-driven learning policy:** signatures are prioritized for optimization by |
| 56 | +`monthly_savings = volume × (routed_cost − optimized_cost_estimate)` weighted by cache affinity. |
| 57 | +No competitor (SkillOpt, DSPy, OpenPipe, LoRAX) sees cost data — they optimize blindly. |
| 58 | +Imprint optimizes what's *worth* optimizing, and shows users a live "bill decay curve." |
| 59 | + |
| 60 | +## Guardrails |
| 61 | + |
| 62 | +- **Training refusal threshold:** <100 occurrences/week/signature → refuse to learn (maintenance > savings). |
| 63 | +- **Behavioral cloning objectives only** (accepted outputs); never train on unverified responses. |
| 64 | +- **Replay buffers + model merging** (v2) to prevent catastrophic forgetting across retrain cycles. |
| 65 | +- **Drift monitor:** embedding-distance + outcome-quality checks; auto-demote on drift. |
| 66 | + |
| 67 | +## Phased Roadmap |
| 68 | + |
| 69 | +| Phase | Duration | Deliverable | Exit criteria | |
| 70 | +|-------|----------|-------------|---------------| |
| 71 | +| **0: Validate** | 1 week | 24–48h traffic capture → top signature → manually optimize its prompt → measure Δcost | ≥30% cost cut on one real signature | |
| 72 | +| **1: Skill Evolver (v1)** | 3 wks | Automated prompt-skill evolution per signature + eval gate | 5 signatures auto-optimized, zero regressions | |
| 73 | +| **2: Promotion ladder** | 4 wks | shadow→canary→preferred state machine + drift demote | 3+ signatures live-preferred, 30 days no-touch | |
| 74 | +| **3: Distiller (v2)** | 6 wks | QLoRA via LoRAX for signatures where prompts plateaued | distilled adapter beats best prompt-skill | |
| 75 | +| **4: Productize** | — | `pip install imprint-router`, bill-decay dashboard, benchmark post | Public launch | |
| 76 | + |
| 77 | +## Naming Decision (council split, resolved) |
| 78 | + |
| 79 | +| Option | Verdict | |
| 80 | +|--------|---------| |
| 81 | +| ~~imprint~~ / ~~imprint-ai~~ | ❌ TAKEN on npm | |
| 82 | +| **imprint-router** ✅ | Available npm+PyPI; consistent with `a3m-router`; keeps your chosen brand | |
| 83 | +| knack-ai | Available; council minority pick; weaker tie to A3M story | |
| 84 | + |
| 85 | +**Decision: Product = "Imprint" · Package = `imprint-router`** |
| 86 | + |
| 87 | +## Next Step When Building |
| 88 | +Create `Das-rebel/imprint` repo with this PLAN.md + Phase 0 skeleton (collector notebook over real A3M logs). |
0 commit comments