@warmdrift/kgauto-compiler 2.0.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+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 } from './profiles-C5lVqF8_.js';
+export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, 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-C5lVqF8_.js';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, IntentArchetypeName, 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;
+    /**
+     * 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>;
+
+/**
+ * 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;
+
+/**
+ * @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, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, record, resetTokenizer, setTokenizer };