@warmdrift/kgauto-compiler 2.0.0-alpha.3 → 2.0.0-alpha.31

package/README.md

@@ -1,4 +1,4 @@
-# @warmdrift/kgauto-compiler — v2.0.0-alpha.3
+# @warmdrift/kgauto-compiler — v2.0.0-alpha.6
 
 > Prompt compiler + central learning brain for multi-model AI apps.
 > **Swap models without rewriting prompts.**
@@ -18,8 +18,8 @@ mutations.
 - **Package:** alpha — coexists with v1 (`@warmdrift/kgauto@1.2.0`) under
   the temporary name `@warmdrift/kgauto-compiler`. Renames to v2 final once
   v1 is fully retired from production.
-- **Tests:** 132/132 passing
-- **Build:** clean (43KB ESM, 60KB CJS)
+- **Tests:** 201/201 passing
+- **Build:** clean (47KB ESM, 68KB CJS)
 - **Brain:** schema ready (see `brain/migrations/001_initial_schema.sql`);
   awaiting dedicated Supabase provisioning.
 - **Mutation engine:** v2.1 (after enough outcome data accumulates).
@@ -89,6 +89,48 @@ await record({
 });
 ```
 
+## Structured advisories API (alpha.29+)
+
+kgauto's compile-time advisories (`caching-off-on-claude`, `tool-bloat`,
+`archetype-perf-floor-breach`, etc.) used to vanish after the consumer read
+the compile result. alpha.29 ships a structured query + resolution surface
+so Admin UIs can render "what's open right now?" without log-scraping.
+
+```ts
+import {
+  getActionableAdvisories,
+  markAdvisoryResolved,
+} from '@warmdrift/kgauto-compiler';
+
+// Query open advisories for this app
+const open = await getActionableAdvisories({
+  appId: 'playbacksam',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+
+for (const a of open) {
+  console.log(`[${a.severity}] ${a.rule} — ${a.observationCount} firings since ${a.openedAt}`);
+  console.log(`  ${a.message}`);
+  if (a.suggestedFix?.docsLink) console.log(`  ↳ ${a.suggestedFix.docsLink}`);
+}
+
+// After the operator fixes the issue, mark it resolved:
+const r = await markAdvisoryResolved({
+  id: open[0].id,
+  resolutionNote: 'wired historyCachePolicy in compile() — PR #99',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+if (!r.ok) console.error(r.reason);
+```
+
+The view enforces server-side auto-resolution: advisories with no firing
+in the last 14 days flip to `status='resolved'` automatically; the next
+firing reopens the rule with a fresh stable `id`.
+
 ## Architecture
 
 ```
@@ -154,6 +196,48 @@ The 5 prod empty-responses in tt-intelligence's `gemini-2.5-flash` dashboard
 calls? v2 catches those automatically — `expectedShortOutput` constraint plus
 the `force_thinking_budget_zero` cliff guard.
 
+## Tools
+
+Tools are first-class IR fields. The compiler's tool-relevance pass drops
+tools that don't apply to the current intent before lowering — saves
+context budget on every call.
+
+```ts
+const tools: ToolDefinition[] = [
+  {
+    name: 'web_search',
+    description: 'Search the public web',
+    parameters: { type: 'object', properties: { q: { type: 'string' } } },
+    relevanceByIntent: {
+      ask: 0.9,        // primary tool for ask
+      hunt: 0.9,
+      classify: 0.0,   // never useful for classification
+      summarize: 0.0,
+      extract: 0.1,
+    },
+  },
+  // ...
+];
+```
+
+Each tool declares per-intent relevance scores 0..1. The pass keeps tools
+where `relevanceByIntent[currentIntent] >= toolRelevanceThreshold` (default
+`0.2`). Missing entries default to neutral (`0.5`) — kept by default. Set
+explicit `0.0` to hard-exclude.
+
+Tool definitions eat ~350 tokens of context per tool (L-051), so trimming
+matters: 12 declared tools, only 3 relevant → 9 × 350 = 3150 tokens
+recovered per call.
+
+The `tool-bloat` advisory (alpha.6) fires when more than 10 tools survive
+the relevance pass on a short-output archetype (`classify`, `extract`,
+`summarize`, `transform`, `critique`) — those archetypes typically use
+≤3 tools, so a kept-count >10 indicates either missing `relevanceByIntent`
+or scores set too generously.
+
+DeepSeek profiles cap tools to 1 (sequential-only). Other providers
+inherit the count from the IR after the relevance pass.
+
 ## Brain provisioning
 
 1. Create a NEW Supabase project (suggested name: `kgauto-brain`)