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

package/dist/profiles-C5lVqF8_.d.ts

@@ -1,489 +0,0 @@
-import { IntentArchetypeName } from './dialect.js';
-
-/**
- * Intermediate Representation — the structured form of a prompt.
- *
- * Everything kgauto v2 does, it does on the IR. The IR is constructed by the
- * caller (or by `parse()` from a string-style prompt for backwards-compat),
- * transformed by the compiler passes, and lowered to a target-specific wire
- * request only at the very end.
- *
- * The IR carries STRUCTURE, not just text. Sections are first-class. Tools
- * carry per-intent relevance. History knows its turn-age. Constraints are
- * explicit. This is what lets passes do real work.
- */
-
-/**
- * A semantically-named section of the system prompt. Sections enable
- * intent-aware slicing (drop sections not tagged for this intent), dedupe
- * (collapse identical sections across files), and cache marking (identify
- * the stable prefix).
- */
-interface PromptSection {
-    /** Stable identifier — used for slicing, dedupe, and cache markers. */
-    id: string;
-    /** Section text. */
-    text: string;
-    /**
-     * Which intents this section applies to. Empty = applies to all intents.
-     * Pass `compile()` will drop sections whose intents array doesn't include
-     * the current intent.
-     */
-    intents?: IntentArchetypeName[];
-    /**
-     * If true, this section is part of the stable cacheable prefix. The lower
-     * pass uses this to place cache markers correctly per target.
-     */
-    cacheable?: boolean;
-    /**
-     * Section weight when ordering — lower = earlier in the assembled prompt.
-     * Defaults to insertion order.
-     */
-    weight?: number;
-}
-interface ToolDefinition {
-    name: string;
-    description?: string;
-    parameters?: Record<string, unknown>;
-    /**
-     * Per-intent relevance scores. Compile uses these to drop irrelevant tools.
-     * Missing intents default to 0.5 (neutral).
-     */
-    relevanceByIntent?: Partial<Record<IntentArchetypeName, number>>;
-    /** Pass-through for provider-specific fields (Anthropic input_schema, etc.). */
-    [key: string]: unknown;
-}
-interface Message {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string;
-    /** Optional structured parts (tool calls, results) — passed through to lowering. */
-    parts?: unknown[];
-    /** For tool messages — which tool this corresponds to. */
-    toolName?: string;
-    /** For tool messages — the call id. */
-    toolCallId?: string;
-}
-/**
- * The compile-time intent declaration. `name` is the app's local label;
- * `archetype` is the canonical dialect-v1 archetype the app maps it to.
- *
- * Apps with their own intent vocabulary (tt-intelligence's "ask"/"hunt"/
- * "dashboard") declare the mapping here. The brain learns by archetype, not
- * by app-local name.
- */
-interface IntentDeclaration {
-    /** App-local intent name (free-form, for app's own debugging). */
-    name: string;
-    /** Canonical dialect-v1 archetype. Required for cross-app learning. */
-    archetype: IntentArchetypeName;
-}
-interface Constraints {
-    /** Hard latency ceiling — compiler will down-rank slow models. Advisory. */
-    maxLatencyMs?: number;
-    /** Hard cost ceiling per call (USD). Advisory. */
-    maxCostUsd?: number;
-    /** Caller wants structured (JSON) output. */
-    structuredOutput?: boolean;
-    /** Hint: caller expects a short response (used to disable thinking on Gemini). */
-    expectedShortOutput?: boolean;
-    /** Hint: max response words. */
-    maxResponseWords?: number;
-    /** Override target model selection — if set, compiler uses this instead of routing. */
-    forceModel?: string;
-}
-/**
- * Consumer-declared policy for model selection. Lives outside the IR
- * (passed via CompileOptions) because it's a SESSION/APP-level constraint,
- * not a per-call shape.
- *
- * The original tt-intelligence scenario (s11): user capped Anthropic
- * spending on Sonnet for cost reasons. v2 compile() kept picking Sonnet
- * as the best target, Hunter's preflight hit the cap and fell back to
- * Flash — every single call. CompilePolicy.blockedModels lets the
- * consumer tell kgauto "don't pick Sonnet right now" and the compiler
- * routes to the next-best option directly. No wasted preflight tax.
- *
- * This is the "coach knows the constraints" feature — kgauto stops
- * recommending things the consumer has already ruled out.
- */
-interface CompilePolicy {
-    /**
-     * Model IDs the consumer has gated. Compile() will never select these.
-     * Use for: cost caps, account-level rate limits, "this model is broken
-     * for our workload" decisions.
-     */
-    blockedModels?: string[];
-    /**
-     * Hard ceiling on estimated input cost per call (USD). Models whose
-     * estimated cost exceeds this are rejected. Use for: budget enforcement
-     * on high-volume routes.
-     */
-    maxCostPerCallUsd?: number;
-    /**
-     * Model IDs the consumer prefers. When multiple models fit, preferred
-     * models get a rank boost (large enough to overcome small quality
-     * differences but not large enough to override hard rejects).
-     */
-    preferredModels?: string[];
-}
-/**
- * The IR — the input to compile().
- */
-interface PromptIR {
-    /** App identifier — required for multi-tenant brain. */
-    appId: string;
-    /** Intent declaration — what is this call doing? */
-    intent: IntentDeclaration;
-    /** Structured system prompt sections. */
-    sections: PromptSection[];
-    /** Available tools (compiler may drop based on intent relevance + budget). */
-    tools?: ToolDefinition[];
-    /** Conversation history (compiler may compress old turns). */
-    history?: Message[];
-    /** The user's current turn — never dropped. */
-    currentTurn?: Message;
-    /** Allowed model IDs, in caller-preference order. Compiler picks among these. */
-    models: string[];
-    /** Compile constraints. */
-    constraints?: Constraints;
-}
-type Provider = 'anthropic' | 'google' | 'openai' | 'deepseek' | 'mistral' | 'xai';
-/**
- * Mutation IDs that fired during compile. Empty in v1 (no mutation engine
- * yet). Populated when the brain is online and pushing mutations.
- */
-type MutationApplied = {
-    id: string;
-    source: string;
-    passName: string;
-    description: string;
-};
-/**
- * Target-specific wire request. Shape varies by provider — caller passes the
- * right field to the right SDK.
- */
-type CompiledRequest = {
-    provider: 'anthropic';
-    model: string;
-    system: Array<{
-        type: 'text';
-        text: string;
-        cache_control?: {
-            type: 'ephemeral';
-        };
-    }>;
-    messages: Array<{
-        role: string;
-        content: unknown;
-    }>;
-    tools?: unknown[];
-    max_tokens?: number;
-} | {
-    provider: 'google';
-    model: string;
-    systemInstruction?: {
-        role: 'system';
-        parts: Array<{
-            text: string;
-        }>;
-    };
-    contents: Array<{
-        role: string;
-        parts: unknown[];
-    }>;
-    tools?: unknown[];
-    generationConfig?: Record<string, unknown>;
-    cachedContent?: string;
-} | {
-    provider: 'openai';
-    model: string;
-    messages: Array<{
-        role: string;
-        content: unknown;
-    }>;
-    tools?: unknown[];
-    response_format?: unknown;
-    reasoning_effort?: string;
-} | {
-    provider: 'deepseek';
-    model: string;
-    messages: Array<{
-        role: string;
-        content: unknown;
-    }>;
-    tools?: unknown[];
-};
-interface CompileResult {
-    /** Unique handle for this call — pass to record() to correlate the outcome. */
-    handle: string;
-    /** Selected target model id. */
-    target: string;
-    /** Selected provider. */
-    provider: Provider;
-    /** The wire request — pass the appropriate fields to your SDK. */
-    request: CompiledRequest;
-    /** Estimated tokens (input). */
-    tokensIn: number;
-    /** Estimated cost in USD (input portion). */
-    estimatedCostUsd: number;
-    /** Mutations that fired during compile (informational). */
-    mutationsApplied: MutationApplied[];
-    /** Fallback chain — try these in order if target fails. */
-    fallbackChain: string[];
-    /** Diagnostics for caller-side logging. */
-    diagnostics: {
-        sectionsKept: number;
-        sectionsDropped: number;
-        toolsKept: number;
-        toolsDropped: number;
-        historyKept: number;
-        historyDropped: number;
-        cacheableTokens: number;
-        estimatedCacheSavingsUsd: number;
-    };
-}
-/**
- * Token usage normalized across providers. `cached` and `cacheCreated` are
- * Anthropic prompt-cache reads/writes (Gemini implicit caching populates
- * `cached` from `usageMetadata.cachedContentTokenCount`; OpenAI populates
- * from `prompt_tokens_details.cached_tokens`).
- */
-interface NormalizedTokens {
-    input: number;
-    output: number;
-    total: number;
-    cached?: number;
-    cacheCreated?: number;
-}
-/**
- * Tool call in a provider-agnostic shape. Anthropic `tool_use` blocks,
- * Google `functionCall` parts, and OpenAI/DeepSeek `tool_calls[]` all
- * collapse to this.
- */
-interface ToolCall {
-    id: string;
-    name: string;
-    args: Record<string, unknown>;
-}
-interface NormalizedResponse {
-    /** Main text body. Empty string if response had no text content. */
-    text: string;
-    /**
-     * Parsed structured output. Populated when ir.constraints.structuredOutput
-     * is true and JSON.parse(text) succeeds. Null otherwise.
-     */
-    structuredOutput: unknown | null;
-    /** Tool calls in normalized shape. Empty array if none. */
-    toolCalls: ToolCall[];
-    tokens: NormalizedTokens;
-    /** Provider-specific finish reason, passed through unchanged. */
-    finishReason?: string;
-    /** Untouched provider response — escape hatch for consumers needing fields not yet normalized. */
-    raw: unknown;
-    /** Set when structuredOutput parsing was attempted and failed. */
-    parseError?: string;
-}
-interface ApiKeys {
-    anthropic?: string;
-    google?: string;
-    openai?: string;
-    deepseek?: string;
-}
-/**
- * Per-provider override fields shallow-merged into the lowered request before
- * execution. Lets consumers reach Gemini `safetySettings`, Anthropic
- * `tool_choice`, OpenAI `seed` etc. without bypassing kgauto.
- */
-interface ProviderOverrides {
-    anthropic?: Record<string, unknown>;
-    google?: Record<string, unknown>;
-    openai?: Record<string, unknown>;
-    deepseek?: Record<string, unknown>;
-}
-interface CallOptions {
-    /** Forwarded to compile(). */
-    policy?: CompilePolicy;
-    toolRelevanceThreshold?: number;
-    compressHistoryAfter?: number;
-    /** Override API keys (defaults: process.env). */
-    apiKeys?: ApiKeys;
-    /** Provider-specific request fields shallow-merged into the lowered request. */
-    providerOverrides?: ProviderOverrides;
-    /** Override fetch (for tests). */
-    fetchImpl?: typeof fetch;
-    /** Disable retry/fallback walk on retryable errors. Default: enabled. */
-    noFallback?: boolean;
-}
-interface CallAttempt {
-    model: string;
-    status: 'success' | 'retryable' | 'terminal';
-    errorCode?: string;
-    message?: string;
-}
-interface CallResult {
-    /** Compile handle (still valid for record() if consumer wants to add oracle scores later). */
-    handle: string;
-    /** The model that ACTUALLY served the response (post-fallback). */
-    actualModel: string;
-    /** What compile() originally targeted. */
-    requestedModel: string;
-    provider: Provider;
-    response: NormalizedResponse;
-    latencyMs: number;
-    /** Mutations that fired during compile (informational, mirrors CompileResult.mutationsApplied). */
-    mutationsApplied: MutationApplied[];
-    /** One entry per provider attempt — observability for retry/fallback walks. */
-    attempts: CallAttempt[];
-}
-/**
- * Thrown when call() exhausts the fallback chain without success.
- * `attempts` carries every model tried + classification.
- */
-declare class CallError extends Error {
-    readonly attempts: CallAttempt[];
-    readonly lastErrorCode?: string;
-    readonly lastStatus?: number;
-    constructor(message: string, attempts: CallAttempt[], lastStatus?: number, lastErrorCode?: string);
-}
-interface OracleScore {
-    /** 0..1 overall quality. */
-    score: number;
-    /** Optional per-dimension breakdown. */
-    dimensions?: Record<string, number>;
-    /** Free-form explanation for debugging. */
-    rationale?: string;
-}
-interface RecordInput {
-    /** Handle from CompileResult. */
-    handle: string;
-    /** Actual tokens consumed (post-call). */
-    tokensIn: number;
-    tokensOut: number;
-    /** Wall-clock latency in ms. */
-    latencyMs: number;
-    /** True iff the call returned a usable response. */
-    success: boolean;
-    /** True iff the call returned 0 output tokens despite success. */
-    emptyResponse?: boolean;
-    /** Provider error code if any. */
-    errorType?: string;
-    /** Tools actually invoked by the model. */
-    toolsCalled?: string[];
-    /** Oracle quality score — required for learning to fire. */
-    oracleScore?: OracleScore;
-    /** Optional: scrubbed prompt/response previews for debugging. */
-    promptPreview?: string;
-    responsePreview?: string;
-    /**
-     * The model that ACTUALLY RAN. Set this when consumer-side fallback ran
-     * a different model than v2 compile() targeted. Brain stores this as
-     * `model` (the truth) and the original target as `requested_model`.
-     *
-     * Omit when no fallback occurred — brain stores compile target as `model`
-     * (still the truth in that case) and `requested_model` stays NULL.
-     *
-     * s11 fix: prevents the brain from misattributing fallback traffic to
-     * the originally-requested model.
-     */
-    actualModel?: string;
-}
-
-/**
- * Model profiles — executable knowledge about each provider/model.
- *
- * Unlike v1 which carried `known_failures` as prose strings, v2 makes them
- * executable: cliffs trigger guards, lowering describes the wire format,
- * recovery handlers describe what to do after specific failures.
- *
- * Each profile is the answer to "if I want to call THIS model with THIS
- * shape of work, what does it need from me, and what should I do when it
- * fails?"
- */
-
-type StructuredOutputCapability = 'native' | 'grammar' | 'none';
-type SystemPromptMode = 'inline' | 'separate' | 'as_developer' | 'unsupported';
-type CacheStrategy = 'cache_control' | 'cachedContent' | 'unsupported';
-interface CliffRule {
-    /** What metric triggers this cliff. */
-    metric: 'input_tokens' | 'tool_count' | 'history_turns' | 'thinking_with_short_output';
-    /** Threshold — meaning depends on metric. */
-    threshold: number;
-    /** What action to take when triggered. */
-    action: 'downgrade_quality_warning' | 'drop_to_top_relevant' | 'force_thinking_budget_zero' | 'force_terse_output' | 'escalate_target' | 'strip_tools';
-    /**
-     * Optional: only fire this cliff when the IR's intent.archetype matches.
-     * Used for archetype-specific failure modes (e.g. Gemini Flash returns
-     * empty when summarize is offered tools).
-     */
-    whenIntent?: IntentArchetypeName;
-    /** Human-readable reason for digest reporting. */
-    reason: string;
-}
-interface RecoveryRule {
-    /** What signal triggers recovery. */
-    signal: 'empty_response_after_tool' | 'empty_response' | 'malformed_function_call' | 'rate_limit' | 'model_not_found' | 'context_overflow';
-    /** Action: retry with adjusted params, or escalate to next fallback. */
-    action: 'retry_with_params' | 'escalate' | 'log_only';
-    /** When action=retry_with_params, the param adjustments to apply. */
-    retryParams?: Record<string, unknown>;
-    /** Max retries with this rule. */
-    maxRetries?: number;
-    /** Human-readable reason for digest reporting. */
-    reason: string;
-}
-interface LoweringSpec {
-    /** Where the system prompt goes. */
-    system: {
-        mode: SystemPromptMode;
-        field?: string;
-    };
-    /** Cache strategy + parameters. */
-    cache: {
-        strategy: CacheStrategy;
-        /** Min tokens before caching is worth it (provider rules). */
-        minTokens?: number;
-        /** Discount factor on cached input (0.1 = 10% of normal price). */
-        discount?: number;
-        /** TTL hint in seconds. */
-        ttlSeconds?: number;
-    };
-    /** Tool format identifier — see lower.ts for supported formats. */
-    tools?: {
-        format: 'anthropic' | 'google' | 'openai' | 'deepseek';
-    };
-    /** Thinking config — present iff this model has a thinking knob. */
-    thinking?: {
-        /** Field path on the request. */
-        field: string;
-        /** Default value when caller hasn't specified. */
-        default?: number | 'auto' | 'off';
-    };
-}
-interface ModelProfile {
-    id: string;
-    provider: Provider;
-    status: 'current' | 'preview' | 'legacy';
-    maxContextTokens: number;
-    maxOutputTokens: number;
-    maxTools: number;
-    parallelToolCalls: boolean;
-    structuredOutput: StructuredOutputCapability;
-    systemPromptMode: SystemPromptMode;
-    streaming: boolean;
-    cliffs: CliffRule[];
-    costInputPer1m: number;
-    costOutputPer1m: number;
-    lowering: LoweringSpec;
-    recovery: RecoveryRule[];
-    strengths: string[];
-    weaknesses: string[];
-    notes?: string;
-    verifiedAgainstDocs?: string;
-}
-declare const ALIASES: Record<string, string>;
-declare function getProfile(id: string): ModelProfile;
-declare function tryGetProfile(id: string): ModelProfile | undefined;
-declare function allProfiles(): readonly ModelProfile[];
-declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
-
-export { type ApiKeys as A, type CompilePolicy as C, type IntentDeclaration as I, type LoweringSpec as L, type ModelProfile as M, type NormalizedResponse as N, type OracleScore as O, type ProviderOverrides as P, type RecordInput as R, type StructuredOutputCapability as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, ALIASES as f, type CacheStrategy as g, type CallAttempt as h, CallError as i, type CliffRule as j, type Constraints as k, type Message as l, type MutationApplied as m, type NormalizedTokens as n, type PromptSection as o, type Provider as p, type RecoveryRule as q, type SystemPromptMode as r, type ToolDefinition as s, allProfiles as t, getProfile as u, profilesByProvider as v, tryGetProfile as w };