@warmdrift/kgauto-compiler 2.0.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,509 @@
+import { M as ModelProfile, C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory, f as Provider } from './profiles-Bgri1pe7.js';
+export { g as ALIASES, h as CacheStrategy, i as CallAttempt, j as CallError, k as CliffRule, l as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, L as LoweringSpec, m as Message, n as MutationApplied, o as NormalizedTokens, p as PromptSection, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-Bgri1pe7.js';
+import { IntentArchetypeName } from './dialect.js';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
+
+/**
+ * compile() — the main orchestrator.
+ *
+ * Runs all passes in order, picks a target, lowers to wire format, returns
+ * a CompileResult the caller uses to make the actual provider call.
+ *
+ * Pure function in v2.0.0-alpha.1: no network, no I/O, no mutation cache yet.
+ * Mutation cache will be added in v2.1 when the brain has data to push.
+ */
+
+interface CompileOptions {
+    /** Custom profile resolver — for tests or custom profile sets. */
+    profileResolver?: (id: string) => ModelProfile;
+    /** Tool relevance threshold (default 0.2). */
+    toolRelevanceThreshold?: number;
+    /** History compression — turns count threshold (default 8). */
+    compressHistoryAfter?: number;
+    /**
+     * History compression — token threshold (alpha.7). When total history
+     * tokens exceed this AND there are more recent turns to keep, compress
+     * even when count threshold is below `compressHistoryAfter`. Catches
+     * fat-message bloat (tool-using agents pack many tool-call/result pairs
+     * into single assistant messages — count stays low, tokens explode).
+     * Default undefined (disabled — backward-compatible).
+     */
+    compressHistoryAboveTokens?: number;
+    /**
+     * Consumer-declared policy. Filters blocked models, enforces cost
+     * ceiling, boosts preferred. See CompilePolicy in ir.ts.
+     */
+    policy?: CompilePolicy;
+}
+
+/**
+ * execute() — fire a CompiledRequest at the right provider, normalize the
+ * response shape across providers.
+ *
+ * This is what call() composes with compile() to own the network round-trip.
+ * Pure-fetch consumers stop reinventing per-provider parsing.
+ *
+ * Error classification follows L-061: 429/5xx/timeout/model_not_found are
+ * retryable; auth/validation are terminal. The orchestrator (call.ts) walks
+ * fallbackChain on retryable; surfaces terminal immediately.
+ */
+
+interface ExecuteOptions {
+    apiKeys?: ApiKeys;
+    fetchImpl?: typeof fetch;
+    providerOverrides?: ProviderOverrides;
+}
+interface ExecuteOk {
+    ok: true;
+    status: number;
+    response: NormalizedResponse;
+}
+interface ExecuteErr {
+    ok: false;
+    status: number;
+    errorType: 'retryable' | 'terminal';
+    errorCode: string;
+    message: string;
+    raw: unknown;
+}
+type ExecuteResult = ExecuteOk | ExecuteErr;
+declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promise<ExecuteResult>;
+
+/**
+ * call() — the high-level orchestrator that owns the network round-trip.
+ *
+ *   call(ir) ≈ compile(ir) → execute(request) → normalize(response) → record(...)
+ *
+ * Plain-fetch consumers (playbacksam, future incantato/glass-box/ivypass) use
+ * call() instead of importing fetch and reinventing per-provider response
+ * parsing. AI-SDK consumers can keep using compile() unchanged — call() is a
+ * sibling, not a replacement.
+ *
+ * Retry/fallback: on a retryable error (429, 5xx, 404, network), walk
+ * CompileResult.fallbackChain by re-running compile() with forceModel set on
+ * each fallback target. Each fallback gets fresh cliffs + fresh lowering.
+ * Hard cap at fallbackChain.length + 1 attempts. Terminal errors short-circuit.
+ */
+
+/**
+ * Compile, execute, normalize, record. Returns a CallResult once a provider
+ * actually serves the request. Throws CallError if the fallback chain is
+ * exhausted without success.
+ */
+declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
+
+/**
+ * Brain client — fire-and-forget telemetry to the central kgauto Supabase.
+ *
+ * The brain is the centralized learning store. Apps POST outcomes here;
+ * mutations flow back through a separate pull (in v2.1).
+ *
+ * Design: never blocks the caller. Failures are silent (logged via optional
+ * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
+ */
+
+interface BrainConfig {
+    /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
+    endpoint: string;
+    /** Bearer token for auth. */
+    apiKey?: string;
+    /** Optional error hook for debugging. Defaults to console.warn. */
+    onError?: (err: unknown) => void;
+    /** If true, records are sent synchronously and awaited (test mode). */
+    sync?: boolean;
+    /** Optional fetch override (for tests). */
+    fetchImpl?: typeof fetch;
+}
+declare function configureBrain(config: BrainConfig): void;
+declare function clearBrain(): void;
+/**
+ * Record the outcome of a compiled call. Fire-and-forget by default.
+ *
+ * Returns a Promise so callers in `sync` mode can await; in async mode the
+ * promise resolves immediately (after the request is queued) and any
+ * network error is swallowed/forwarded to onError.
+ */
+declare function record(input: RecordInput): Promise<void>;
+/**
+ * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
+ *
+ * Exported so consumer proxies can `import { OutcomePayload } from
+ * '@warmdrift/kgauto-compiler'` instead of redefining the shape — that way
+ * TypeScript catches future schema additions (cache fields, advisory
+ * telemetry, etc.) at consumer build time, not silently at runtime.
+ *
+ * **Forward-compat rule:** consumer proxies should pass the body through to
+ * Supabase rather than reconstructing field-by-field. The recommended shape
+ * is `const row = { ...body }` (or `await supabase.from('compile_outcomes')
+ * .insert(body)` directly). Filtering proxies break schema evolution
+ * silently — see s17 root-cause investigation 2026-05-10.
+ */
+interface OutcomePayload {
+    handle: string;
+    app_id?: string;
+    intent_archetype?: string;
+    /** The model that ACTUALLY RAN (post-fallback). */
+    model?: string;
+    /** The model v2 compile() originally targeted. NULL when no fallback. */
+    requested_model?: string;
+    provider?: string;
+    shape_key?: string;
+    learning_key?: string;
+    mutations_applied: string[];
+    tokens_in: number;
+    tokens_out: number;
+    estimated_tokens_in?: number;
+    latency_ms: number;
+    success: boolean;
+    empty_response: boolean;
+    error_type?: string;
+    tools_called?: string[];
+    oracle_score?: number;
+    oracle_dimensions?: Record<string, number>;
+    oracle_rationale?: string;
+    prompt_preview?: string;
+    response_preview?: string;
+    dialect_version: string;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cost_usd_actual?: number;
+    ttft_ms?: number;
+    history_cacheable_tokens?: number;
+    history_tokens_at_compile?: number;
+}
+
+/**
+ * Oracle contract — how an app tells the brain whether a response was good.
+ *
+ * The brain learns from oracle scores. Apps provide an oracle function per
+ * intent (or one default). Without oracle scores the brain can still record
+ * structural metrics (tokens, latency, success) but mutations cannot fire —
+ * structural metrics aren't quality.
+ *
+ * Two oracle styles supported:
+ *   1. App-provided synchronous scorer: cheap, deterministic, app-specific.
+ *      Examples: "did the SQL filter return non-empty?", "did the JSON parse?",
+ *      "did the response cite a known source?".
+ *   2. LLM-as-judge async scorer: built into kgauto for cold-start use. Calls
+ *      a frontier model with a comparison prompt and parses a score.
+ */
+
+interface OracleContext {
+    /** App identifier. */
+    appId: string;
+    /** App-local intent name. */
+    intentName: string;
+    /** Canonical archetype. */
+    archetype: string;
+    /** The original user turn text. */
+    userTurn?: string;
+    /** The model's text response. */
+    response: string;
+    /** Whether tool calls were involved. */
+    hadTools: boolean;
+    /** Free-form metadata the caller can attach. */
+    meta?: Record<string, unknown>;
+}
+/** App-provided oracle: pure function (sync or async). */
+type AppOracle = (ctx: OracleContext) => OracleScore | Promise<OracleScore>;
+interface LLMJudgeOptions {
+    /** Function that calls the judge model. Caller wires their own SDK. */
+    judgeCall: (prompt: string) => Promise<string>;
+    /**
+     * The dimensions to score. Default: 4-dimension rubric (correctness,
+     * completeness, conciseness, format).
+     */
+    dimensions?: string[];
+    /** Hard cap on judge calls per minute (rate limiting). */
+    rateLimitPerMin?: number;
+}
+/**
+ * Build an LLM-as-judge oracle. Returns an AppOracle that asks the judge
+ * model to rate the response and parses a JSON score.
+ */
+declare function buildLLMJudge(opts: LLMJudgeOptions): AppOracle;
+
+/**
+ * Tokenizer abstraction.
+ *
+ * Default: char-based fallback (~4 chars/token, ±20% accuracy).
+ * Recommended: caller wires js-tiktoken or a provider-specific tokenizer
+ * via setTokenizer(). The compiler always calls countTokens(); the rest of
+ * the system never touches the implementation directly.
+ */
+/**
+ * Wire a real tokenizer. Caller is responsible for picking one accurate
+ * enough for their dominant provider.
+ */
+declare function setTokenizer(impl: (text: string) => number): void;
+/**
+ * Reset to the char-based fallback. Useful in tests.
+ */
+declare function resetTokenizer(): void;
+/**
+ * Count tokens for a string. Wraps the configured implementation with
+ * safety (never throws, always returns ≥ 0 for non-empty input).
+ */
+declare function countTokens(text: string): number;
+
+/**
+ * Best-practice advisor — alpha.6 Phase 1.
+ *
+ * Inspects an IR + the selected profile + compile diagnostics and emits a
+ * list of `BestPracticeAdvisory` entries describing detected gaps. Runs
+ * after `lower()` in the compile pipeline; the result lands on
+ * `CompileResult.advisories` for the consumer to log, surface, or filter.
+ *
+ * Driven by interfaces/kgauto.md `best-practice-advisories` (IC, 2026-05-07).
+ * Phase 1 ships 4 starter rules sourced from the s14 kgauto comment +
+ * s15 empirical seed of brain anti-patterns:
+ *
+ *   1. `caching-off-on-claude`        system >2000 chars on Anthropic, no cacheable=true
+ *   2. `single-chunk-system`          Anthropic, only one PromptSection >1000 chars
+ *   3. `tool-bloat`                   >10 tools on a short-output archetype
+ *   4. `history-uncached-on-claude`   Anthropic, ≥2 history messages, no historyCachePolicy
+ *
+ * Each rule is a pure function: (ir, result, profile) → BestPracticeAdvisory[].
+ * No side effects. No randomness. Deterministic for a given IR.
+ *
+ * The thresholds (2000 chars, 1000 chars, 10 tools, 2 history) are chosen
+ * to balance noise vs. signal — too low fires on innocuous calls, too high
+ * misses real waste. They may tune with brain evidence over time; for now
+ * they're literals in the rule bodies. Make them configurable when the
+ * cost-watcher's R-rules graduate to here.
+ */
+
+/** Subset of CompileResult fields the advisor needs. */
+type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
+/**
+ * Run all phased rules and return collected advisories. Order is fixed so
+ * output is stable across runs. The `policy` argument is alpha.9 — the
+ * `single-model-array` rule needs to know whether the consumer explicitly
+ * declared `posture: 'locked'` (in which case single-model is intentional
+ * and shouldn't warn).
+ */
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+
+/**
+ * env.ts — provider env-key resolution + reachability predicates.
+ *
+ * Centralizes the per-provider env var names that kgauto checks for
+ * reachability. Used by:
+ *
+ *   - execute.ts          — to find an API key when one isn't passed via apiKeys
+ *   - call.ts             — to auto-filter unreachable models from the fallback walk
+ *   - getDefaultFallbackChain — opt-in chain filter when consumer passes `reachability`
+ *   - operator scripts    — getReachabilityDiagnostic() prints what's wired up
+ *
+ * Keeping the map in ONE place means execute() and the reachability check
+ * always agree. Without this, kgauto could declare a model "reachable" because
+ * env.ts found GOOGLE_GENERATIVE_AI_API_KEY, while execute() looks at
+ * GOOGLE_API_KEY only and 401s — shipping the bug we're trying to fix.
+ *
+ * Resolution order (apiKeys takes precedence):
+ *   1. opts.apiKeys?.[provider]
+ *   2. process.env[name] for each name in PROVIDER_ENV_KEYS[provider] (first-present wins)
+ *
+ * alpha.10 (2026-05-14). Resolves the auto-filter-unreachable-models-silently
+ * request from PB after first-deploy 401 on the alpha.9 summarize chain.
+ */
+
+/**
+ * Providers kgauto can resolve keys for today. Subset of `Provider` — `mistral`
+ * and `xai` are declared in the type union but not yet executable (no profiles,
+ * no execute() handler, no env-var convention). Narrowing here keeps the
+ * reachability check structurally honest.
+ */
+type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek';
+/**
+ * Per-provider env var names kgauto recognizes. Order doesn't matter —
+ * first-present wins. Multiple names per provider supported because Google
+ * has historical drift (`GOOGLE_API_KEY` from older Google Cloud SDKs,
+ * `GEMINI_API_KEY` in many examples, `GOOGLE_GENERATIVE_AI_API_KEY` is the
+ * Vercel AI SDK convention used by IC + tt-intel adapters).
+ *
+ * Frozen so consumers/tests can't mutate (would break the cache invariant
+ * that execute() and reachability checks agree).
+ */
+declare const PROVIDER_ENV_KEYS: Readonly<Record<SupportedProvider, readonly string[]>>;
+interface ReachabilityOpts {
+    /** Explicit keys (alpha.3 ApiKeys). Checked first; takes precedence over env. */
+    apiKeys?: ApiKeys;
+    /**
+     * Override env source. Defaults to `process.env` in Node-shaped runtimes,
+     * `{}` everywhere else. Pass `{}` explicitly in tests for hermetic runs.
+     */
+    envSource?: Record<string, string | undefined>;
+}
+/**
+ * Resolve a usable API key for the provider. Returns the key string, or
+ * undefined if neither apiKeys nor any of the env names are set.
+ *
+ * Used internally by execute.ts so the reachability check and the actual
+ * call check stay in sync.
+ */
+declare function resolveProviderKey(provider: Provider, opts?: ReachabilityOpts): string | undefined;
+/**
+ * True iff the provider has a usable key — either via explicit `apiKeys`
+ * or one of the `PROVIDER_ENV_KEYS[provider]` names is set in envSource.
+ */
+declare function isProviderReachable(provider: Provider, opts?: ReachabilityOpts): boolean;
+/**
+ * True iff the model's profile exists AND its provider is reachable.
+ * Unknown model id returns false (treat as unreachable; the chain walker
+ * will surface "no reachable models" if everything filters out).
+ */
+declare function isModelReachable(modelId: string, opts?: ReachabilityOpts): boolean;
+interface ProviderReachability {
+    reachable: boolean;
+    /** How the key was found. `null` when unreachable. */
+    via: 'apiKeys' | 'env' | null;
+    /** Which env var name supplied the key (only when via === 'env'). */
+    envKeyFound?: string;
+}
+/**
+ * Snapshot of which providers are reachable from the current env / apiKeys.
+ * Useful for operator scripts ("kgauto diagnose"), startup-time logging,
+ * and the cost-watcher's "which consumer is missing what" report.
+ *
+ * Does NOT log the key value itself — only the env var name that supplied it.
+ */
+declare function getReachabilityDiagnostic(opts?: ReachabilityOpts): Record<SupportedProvider, ProviderReachability>;
+
+/**
+ * getDefaultFallbackChain — the alpha.9 cascading ship.
+ *
+ * Returns a per-archetype fallback chain that walks the cost/performance
+ * Pareto frontier (master plan §1.3 + §3). Three customer postures:
+ *
+ *   locked    — caller passes [theOneModel]; never call this function
+ *   preferred — caller passes `primary`; chain returned is [primary, ...fallbacks]
+ *   open      — caller passes no `primary`; chain returned is [best, ...fallbacks]
+ *
+ * The chain at each step:
+ *   1. Costs strictly less than the previous (no expensive sideways moves)
+ *   2. Comes from a different provider than the previous step where possible
+ *      (correlated outages don't kill consecutive attempts)
+ *   3. Stays above the archetype's perf floor (skip models scored <baseline
+ *      for archetypes where degradation would be unacceptable)
+ *
+ * In alpha.9 the chain is **hand-curated** per archetype (§3.3 starter
+ * table). Brain-query mode lands in alpha.10. Policy.blockedModels filters
+ * the result; policy.maxCostPerCallUsd is NOT applied here because the
+ * function doesn't see the IR's token counts — that filtering happens at
+ * `passScoreTargets()` time inside compile().
+ *
+ * The function is **pure** — no brain query, no I/O, no randomness. Same
+ * inputs always produce the same chain.
+ */
+
+/**
+ * Posture passed into `getDefaultFallbackChain`. The chain function only
+ * sees `'open'` and `'preferred'` — callers in `'locked'` posture should
+ * pass `models: [theOneModel]` directly and skip this function entirely.
+ *
+ * Equivalent to `CompilePolicy.posture` minus `'locked'`. Kept distinct so
+ * the type system enforces "don't ask for a chain when you don't want one."
+ */
+type FallbackPosture = 'open' | 'preferred';
+interface GetDefaultFallbackChainOpts {
+    /** The archetype the call is performing. Drives chain shape. */
+    archetype: IntentArchetypeName;
+    /**
+     * The user-selected or caller-anchored primary model. When provided, it
+     * appears at position 0 of the returned chain and fallbacks follow.
+     * When omitted, the function picks the best-perf model for the archetype
+     * as position 0 (open posture).
+     */
+    primary?: string;
+    /**
+     * Informational. `'preferred'` and `'open'` produce the same chain shape
+     * given the same `primary`/no-primary input — posture is a tag the brain
+     * uses to distinguish "user-anchored" from "library-anchored" telemetry.
+     */
+    posture?: FallbackPosture;
+    /**
+     * Cap on chain length. Default 3. Min 1. Useful when the consumer wants
+     * to keep the worst-case latency low (each fallback adds a round-trip).
+     */
+    maxDepth?: number;
+    /**
+     * Consumer-side gating. `blockedModels` are filtered from the chain.
+     * `preferredModels` is informational (no boost applied at this layer —
+     * compile()'s `passScoreTargets` handles preference ranking).
+     * `maxCostPerCallUsd` is NOT applied here — needs IR-level token
+     * estimation. Use compile()'s policy plumbing instead.
+     */
+    policy?: CompilePolicy;
+    /**
+     * alpha.10. When provided, the chain is filtered to models whose provider
+     * has a reachable API key (via `apiKeys` or one of `PROVIDER_ENV_KEYS[provider]`).
+     * Models whose provider can't be reached are silently dropped. If filtering
+     * leaves the chain empty, returns `[]` — caller decides what to do (call()
+     * throws CallError; this function stays pure).
+     *
+     * Pass `{}` to opt in with `process.env` as the env source. Pass `{ apiKeys, envSource }`
+     * for explicit control (tests, non-Node runtimes). Omit entirely for the
+     * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
+     */
+    reachability?: ReachabilityOpts;
+}
+declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
+/**
+ * Returns a shallow copy of the hand-curated starter chain for an archetype.
+ * Useful for tests + the `scripts/digest.mjs` operator readout.
+ */
+declare function getStarterChain(archetype: IntentArchetypeName): string[];
+/**
+ * Returns a shallow copy of all starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits.
+ */
+declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
+
+/**
+ * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
+ *
+ * Two functions you'll use most:
+ *   compile(ir, opts?) → CompileResult
+ *   record(input)      → Promise<void>
+ *
+ * Plus:
+ *   configureBrain({ endpoint, apiKey })  — point at the central brain
+ *   buildLLMJudge({ judgeCall })          — cold-start oracle
+ *
+ * Quickstart:
+ *
+ *   import { compile, record, configureBrain } from '@warmdrift/kgauto';
+ *
+ *   configureBrain({ endpoint: 'https://kgauto-brain.vercel.app/api', apiKey: '...' });
+ *
+ *   const r = compile({
+ *     appId: 'my-app',
+ *     intent: { name: 'search', archetype: 'ask' },
+ *     sections: [
+ *       { id: 'role', text: 'You are an assistant.', cacheable: true },
+ *       { id: 'task', text: userQuestion },
+ *     ],
+ *     models: ['claude-sonnet-4-6', 'gemini-2.5-flash'],
+ *   });
+ *
+ *   const start = Date.now();
+ *   const response = await callProvider(r.target, r.request);
+ *
+ *   await record({
+ *     handle: r.handle,
+ *     tokensIn: response.usage.input,
+ *     tokensOut: response.usage.output,
+ *     latencyMs: Date.now() - start,
+ *     success: true,
+ *     oracleScore: { score: 0.85 },
+ *   });
+ */
+
+/**
+ * Compile a request. Wraps the pure compile() with brain registration so
+ * record() can find call metadata later.
+ */
+declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
+
+export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PROVIDER_ENV_KEYS, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, record, resetTokenizer, resolveProviderKey, runAdvisor, setTokenizer };