cognitive-core 0.2.5 → 0.3.1

package/dist/learning/convention-distiller.js

@@ -0,0 +1,268 @@
+/**
+ * ConventionDistiller — LLM-backed distillation of correction signals into
+ * scoped, standing convention items (PR-D3).
+ *
+ * Design mirrors TrajectoryDistiller (PR-D1):
+ *   - One LLM call per correction batch, temperature 0 for determinism.
+ *   - Results cached by sha256(canonical-correction-form + PROMPT_VERSION).
+ *   - self-check rubric: at least 2 of 3 criteria must pass.
+ *   - Malformed or ambiguous corrections → null (never fabricate a rule).
+ *
+ * Prompt frame differs from the playbook distiller:
+ *   "What standing preference or convention does this correction imply,
+ *    and what is its scope?"
+ *
+ * Evidence threshold (enforced by KnowledgeBank.upsertConvention):
+ *   - 'instruction' type → binding immediately (evidenceCount=1 suffices)
+ *   - 'edit-diff' | 'rejection' → binding only after evidenceCount >= 2
+ *
+ * SessionBank transcript harvesting is OUT OF SCOPE for this PR.
+ * Follow-up hook: wire CorrectionEvent extraction from SessionBank transcripts
+ * into the trajectory ingestion path (trajectory-sources/session-bank.ts).
+ */
+import { createHash } from 'node:crypto';
+import { createConvention } from '../types/knowledge.js';
+// ============================================================================
+// Prompt versioning — bump whenever the prompt changes to invalidate cache
+// ============================================================================
+export const CONVENTION_DISTILLER_PROMPT_VERSION = 'v1';
+const DEFAULT_CONFIG = {
+    model: 'claude-sonnet-4-5',
+    maxTokens: 800,
+};
+// ============================================================================
+// ConventionDistiller
+// ============================================================================
+export class ConventionDistiller {
+    llm;
+    persistence;
+    config;
+    constructor(llm, persistence, config) {
+        this.llm = llm;
+        this.persistence = persistence;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Distill one or more correction events into a convention item.
+     *
+     * Returns null when:
+     *   - The LLM returns malformed JSON / fails the self-check rubric.
+     *   - The LLM call itself throws.
+     *   - The correction content is too ambiguous to form a standing rule.
+     *
+     * The caller is responsible for storing the result via
+     * KnowledgeBank.upsertConvention() which handles the evidence threshold.
+     */
+    async distill(corrections, context) {
+        if (corrections.length === 0)
+            return null;
+        // 1. Build cache key
+        const cacheKey = this.buildCacheKey(corrections);
+        // 2. Cache hit — return without an LLM call
+        if (this.persistence) {
+            const cached = this.persistence.getDistillationCache(cacheKey);
+            if (cached) {
+                try {
+                    return JSON.parse(cached.playbook_json);
+                }
+                catch {
+                    // Corrupt cache entry — fall through to re-distill
+                }
+            }
+        }
+        // 3. Build prompt and call LLM
+        const prompt = buildConventionPrompt(corrections, context);
+        let raw;
+        try {
+            raw = await this.llm.complete([{ role: 'user', content: prompt }], {
+                temperature: 0,
+                maxTokens: this.config.maxTokens,
+            });
+        }
+        catch {
+            return null;
+        }
+        // 4. Parse response
+        const parsed = parseConventionResponse(raw);
+        if (!parsed)
+            return null;
+        // 5. Self-check: at least 2 of 3 rubric criteria must pass
+        const selfCheckScore = (parsed.selfCheck.specific ? 1 : 0) +
+            (parsed.selfCheck.scoped ? 1 : 0) +
+            (parsed.selfCheck.actionable ? 1 : 0);
+        if (selfCheckScore < 2)
+            return null;
+        // 6. Determine immediate binding: explicit instruction corrections are binding at count=1
+        const hasInstruction = corrections.some((c) => c.type === 'instruction');
+        const result = {
+            conventionText: parsed.conventionText,
+            scope: parsed.scope,
+            rationale: parsed.rationale,
+            immediateBinding: hasInstruction,
+        };
+        // 7. Store in cache (reuse distillation_cache table via playbook_json column)
+        if (this.persistence) {
+            try {
+                this.persistence.setDistillationCache({
+                    cache_key: cacheKey,
+                    playbook_json: JSON.stringify(result),
+                    created_at: new Date().toISOString(),
+                });
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+        return result;
+    }
+    /**
+     * Distill corrections and convert directly to a KnowledgeNote ready for
+     * KnowledgeBank.upsertConvention().
+     *
+     * Returns null on any distillation failure.
+     */
+    async distillToNote(corrections, context) {
+        const result = await this.distill(corrections, context);
+        if (!result)
+            return null;
+        const hasInstruction = corrections.some((c) => c.type === 'instruction');
+        const binding = result.immediateBinding;
+        return createConvention({
+            conventionText: result.conventionText,
+            scope: result.scope,
+            rationale: result.rationale,
+            binding,
+            evidenceCount: 1,
+            domain: context?.domain ? [context.domain] : [],
+            tags: hasInstruction ? ['instruction'] : ['correction'],
+            source: {
+                origin: 'extracted',
+                trajectories: [],
+            },
+        });
+    }
+    /**
+     * Build the cache key for a set of corrections.
+     * Exposed for testing.
+     */
+    buildCacheKey(corrections) {
+        const canonical = corrections.map((c) => `${c.type}:${c.content}:${c.target ?? ''}`).join('\0');
+        return sha256(`convention:${canonical}:${CONVENTION_DISTILLER_PROMPT_VERSION}`);
+    }
+}
+// ============================================================================
+// Factory (repo convention)
+// ============================================================================
+export function createConventionDistiller(llm, persistence, config) {
+    return new ConventionDistiller(llm, persistence, config);
+}
+// ============================================================================
+// Prompt construction
+// ============================================================================
+/**
+ * The convention distillation prompt.
+ *
+ * Preference-frame: the model asks "what standing preference or convention
+ * does this correction imply?" rather than "what went wrong?".
+ *
+ * Rubric:
+ *   (a) SPECIFIC: names a concrete behavior, tool, command, or pattern — not a platitude.
+ *   (b) SCOPED: identifies who it applies to (user, repo, domain, or global) and why.
+ *   (c) ACTIONABLE: an agent reading it would know exactly what to do differently.
+ *
+ * Self-check forces the model to score its output before emitting.
+ * Ambiguous corrections (can't satisfy 2/3 criteria) must emit null.
+ */
+function buildConventionPrompt(corrections, context) {
+    const correctionLines = corrections
+        .map((c, i) => {
+        const targetNote = c.target ? ` (target: ${c.target})` : '';
+        return `Correction ${i + 1} [${c.type}]${targetNote}:\n  ${c.content}`;
+    })
+        .join('\n\n');
+    const contextSection = context
+        ? `\n## Context\nTask: ${context.taskDescription ?? 'unknown'}\nDomain: ${context.domain ?? 'unknown'}`
+        : '';
+    return `You are a convention distiller. Your job is to extract a single standing preference or convention from one or more user correction signals.
+
+A correction signal means the user edited an agent's output, rejected a suggestion, or stated an explicit rule. Your job is to identify the STANDING CONVENTION implied — the durable preference the user wants applied going forward.${contextSection}
+
+## Correction signals
+${correctionLines}
+
+## Your job
+Answer: "What standing preference or convention does this correction imply, and what is its scope?"
+
+Scope options:
+- "user"   — personal preference that applies regardless of project (e.g. "always use 2-space indentation")
+- "repo"   — specific to this repository or project (e.g. "use make check, not npm test, in this repo")
+- "domain" — applies to a technology/language/framework (e.g. "in TypeScript, always use .js extensions in imports")
+- "global" — universal rule with no meaningful exceptions
+
+## Quality rubric — your output MUST satisfy ALL THREE criteria:
+(a) SPECIFIC: names a concrete behavior, tool, command, file pattern, or coding practice — not a vague preference. "Be more careful" FAILS. "Use \`make check\` instead of \`npm test\`" PASSES.
+(b) SCOPED: clearly identifies the scope (user/repo/domain/global) and includes a brief reason why that scope is correct.
+(c) ACTIONABLE: an agent reading the convention would know exactly what to do or avoid, without further clarification.
+
+## Self-check
+Before emitting your JSON, score your output: does it satisfy (a), (b), and (c)? If the correction is too ambiguous to derive a standing convention (e.g. one-off context-specific feedback), set all selfCheck fields to false. Do NOT fabricate a rule when the correction is unclear.
+
+## Output format
+Respond with ONLY a JSON object (no markdown fences, no prose):
+{
+  "conventionText": "<1-2 sentences: the concrete standing convention, phrased as an affirmative rule>",
+  "scope": "<user|repo|domain|global>",
+  "rationale": "<1 sentence: why this scope, what the correction evidence tells us>",
+  "selfCheck": {
+    "specific": <true|false>,
+    "scoped": <true|false>,
+    "actionable": <true|false>
+  }
+}`;
+}
+// ============================================================================
+// Response parsing
+// ============================================================================
+function parseConventionResponse(raw) {
+    const cleaned = raw
+        .replace(/^```(?:json)?\s*/m, '')
+        .replace(/\s*```$/m, '')
+        .trim();
+    try {
+        const obj = JSON.parse(cleaned);
+        if (typeof obj.conventionText !== 'string' ||
+            typeof obj.scope !== 'string' ||
+            typeof obj.rationale !== 'string' ||
+            !obj.selfCheck ||
+            typeof obj.selfCheck !== 'object' ||
+            typeof obj.selfCheck.specific !== 'boolean' ||
+            typeof obj.selfCheck.scoped !== 'boolean' ||
+            typeof obj.selfCheck.actionable !== 'boolean') {
+            return null;
+        }
+        // Validate scope value
+        const validScopes = ['user', 'repo', 'domain', 'global'];
+        if (!validScopes.includes(obj.scope))
+            return null;
+        return {
+            conventionText: String(obj.conventionText),
+            scope: obj.scope,
+            rationale: String(obj.rationale),
+            selfCheck: {
+                specific: obj.selfCheck.specific,
+                scoped: obj.selfCheck.scoped,
+                actionable: obj.selfCheck.actionable,
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function sha256(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+//# sourceMappingURL=convention-distiller.js.map

package/dist/learning/convention-distiller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention-distiller.js","sourceRoot":"","sources":["../../src/learning/convention-distiller.ts"],"names":[],"mappings":"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"}

package/dist/learning/distiller.d.ts

@@ -0,0 +1,82 @@
+/**
+ * TrajectoryDistiller — LLM-backed distillation of trajectories into
+ * transferable, condition-tagged Playbook items.
+ *
+ * Design (Phase 3 / PR-D1):
+ *   - One LLM call per trajectory, batched in the dream/batch phase (never the
+ *     <200ms InstantLoop hot path).
+ *   - Output mapped into the *existing* Playbook schema: no new core type.
+ *   - Failures distill to anti-pattern-only items (never positive exemplars).
+ *   - Results cached by sha256(canonical-trajectory-form + PROMPT_VERSION) so
+ *     re-runs are fully reproducible and LLM-free after the first distillation.
+ *   - Heuristic PlaybookExtractor remains the no-LLM fallback; this distiller
+ *     is the LLM-backed alternative (switched by patternExtractor==='llm').
+ *
+ * PR-D2 hook (curation / dedup):
+ *   - `distill()` returns a raw Playbook; callers decide whether to add or
+ *     merge. The comment "D2-hook" marks the call-site in unified-pipeline.ts
+ *     where near-dup checking will be inserted.
+ */
+import type { LLMProvider } from '../agents/types.js';
+import type { Trajectory, Outcome } from '../types/index.js';
+import type { Playbook } from '../types/playbook.js';
+import type { SqlitePersistence } from '../persistence/sqlite-persistence.js';
+export declare const DISTILLER_PROMPT_VERSION = "v2";
+export interface TrajectoryDistillerConfig {
+    /**
+     * Pinned model identifier forwarded to LLMProvider.complete() via the
+     * `model` key in CompletionOptions metadata. Temperature is always 0 for
+     * determinism. Default: 'claude-sonnet-4-5' — revise after D4 rubric.
+     */
+    model?: string;
+    /**
+     * Max tokens for the distillation response. Default: 1200.
+     */
+    maxTokens?: number;
+    /**
+     * Base confidence for a freshly distilled playbook from a SUCCESS trajectory.
+     * The actual initial confidence is derived from the self-check score via:
+     *   confidence = initialConfidenceBase + 0.1 * selfCheckScore
+     * With selfCheckScore in {2, 3} (only passing items reach buildPlaybook):
+     *   selfCheckScore=2 → 0.5 + 0.2 = ... wait, we use the formula:
+     *   confidence = 0.4 + 0.1 * selfCheckScore
+     *   selfCheckScore=2 → 0.6
+     *   selfCheckScore=3 → 0.7 (above the router 0.7 gate)
+     *
+     * This field is the OVERRIDE base for the formula.  When provided, the
+     * formula becomes: confidence = initialConfidenceBase + 0.1 * selfCheckScore.
+     * Default: 0.4 (giving 0.6–0.7 for passing items instead of a flat 0.25).
+     *
+     * Failure items are multiplied by 0.8 regardless (see buildPlaybook).
+     */
+    initialConfidenceBase?: number;
+}
+export type { DistillationCacheRow } from '../persistence/sqlite-persistence.js';
+export declare class TrajectoryDistiller {
+    private readonly llm;
+    private readonly persistence;
+    private readonly config;
+    constructor(llm: LLMProvider, persistence?: SqlitePersistence, config?: Partial<TrajectoryDistillerConfig>);
+    /**
+     * Distill a single trajectory into a Playbook item.
+     *
+     * - Success trajectories → strategy + tactics + applicability + antiPatterns.
+     * - Failure trajectories → antiPattern-only item (guidance.strategy is the
+     *   lesson-as-negative; no tactics, no positive exemplar injected).
+     *
+     * Returns null when:
+     *   - The LLM returns malformed JSON / fails the self-check rubric.
+     *   - The LLM call itself throws.
+     *
+     * The caller (unified-pipeline) is responsible for storing/merging the result.
+     * PR-D2 curation (near-dup check) hooks here at the call-site.
+     */
+    distill(trajectory: Trajectory, outcome: Outcome, verifierOutput?: string): Promise<Playbook | null>;
+    /**
+     * Build the cache key for a trajectory.
+     * Exposed for testing (cache pre-seeding).
+     */
+    buildCacheKey(trajectory: Trajectory, verifierOutput?: string): string;
+}
+export declare function createTrajectoryDistiller(llm: LLMProvider, persistence?: SqlitePersistence, config?: Partial<TrajectoryDistillerConfig>): TrajectoryDistiller;
+//# sourceMappingURL=distiller.d.ts.map

package/dist/learning/distiller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distiller.d.ts","sourceRoot":"","sources":["../../src/learning/distiller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAW9E,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAM7C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAcD,YAAY,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AA4BjF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;gBAG3D,GAAG,EAAE,WAAW,EAChB,WAAW,CAAC,EAAE,iBAAiB,EAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC;IAO7C;;;;;;;;;;;;;OAaG;IACG,OAAO,CACX,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoE3B;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM;CAKvE;AAMD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,WAAW,EAChB,WAAW,CAAC,EAAE,iBAAiB,EAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,GAC1C,mBAAmB,CAErB"}