@warmdrift/kgauto-compiler 2.0.0-alpha.4 → 2.0.0-alpha.42

package/dist/profiles.d.mts

@@ -1,2 +1,164 @@
-export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-CH_nKPjp.mjs';
-import './dialect.mjs';
+import { k as Provider } from './ir-BG70lg9b.mjs';
+import { IntentArchetypeName } from './dialect.mjs';
+
+/**
+ * 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;
+    /**
+     * Hand-curated per-archetype performance score on a 0-10 scale.
+     *
+     *   10 = frontier on this archetype (e.g. Opus 4.7 on critique)
+     *    8 = strong second tier (Sonnet on plan, Pro on extract)
+     *    7 = competent (Haiku on classify, Flash on hunt)
+     *    5 = acceptable for tolerant archetypes (Flash-Lite on classify)
+     *    3 = degraded (Flash on critique, DeepSeek on hunt)
+     *
+     * Missing archetypes default to `5` (no data, neutral). Each non-default
+     * value should carry a one-line rationale in the profile's note or inline
+     * comment citing brain evidence, family prior, or "starter hypothesis —
+     * verify with telemetry."
+     *
+     * Source today: hand-curated from master plan §3.3 + §6.2 starter tables.
+     * Source tomorrow (alpha.10+): brain `archetype_model_evidence` view.
+     *
+     * Anti-hallucination guardrail (master plan §2.5): when the watcher's
+     * `--audit-fields` flag flags a profile stale (>90 days since
+     * verifiedAgainstDocs), the archetypePerf values get re-audited
+     * alongside capability fields. AI-trained intuition is NOT a valid
+     * source — only docs or brain evidence.
+     *
+     * alpha.9.
+     */
+    archetypePerf?: Partial<Record<IntentArchetypeName, number>>;
+    /**
+     * alpha.41 — model-family identifier (e.g. `'claude-opus'`,
+     * `'gemini-flash'`). Reads through from `kgauto_models.family` (migration
+     * 024). When unset on a brain row, runtime falls back to
+     * `deriveFamilyFromModelId(model.id)` (see `family-resolution.ts`).
+     *
+     * Used by `getRecommendedPrimary({ family, ... })` and the IR-level
+     * `{ family: string }` chain entry resolution at compile time.
+     */
+    family?: string;
+    /**
+     * alpha.41 — version string of the kgauto release that first introduced
+     * this profile (e.g. `'2.0.0-alpha.36'`). Threaded through from the brain
+     * row's `version_added` column. Family-resolution sorts candidates by
+     * `version_added DESC` (lexicographic) as the secondary tiebreaker after
+     * `archetypePerf[archetype]`. Undefined on bundled profiles (no brain
+     * row).
+     */
+    versionAdded?: string;
+    /**
+     * alpha.41 — whether the brain row is `active = TRUE`. False or undefined
+     * means the model is retired / not actively served (kgauto_models row
+     * exists but won't be selected by family resolution). Bundled profiles
+     * default to `true` when not threaded through (every PROFILES_RAW entry
+     * is by definition the active source of truth at bundle time).
+     */
+    active?: boolean;
+}
+declare const ALIASES: Record<string, string>;
+interface ProfileBrainHook {
+    getProfile?: (canonicalId: string) => ModelProfile | undefined;
+    resolveAlias?: (id: string) => string | undefined;
+}
+/** @internal — called by models-brain.ts at module load. */
+declare function _setProfileBrainHook(hook: ProfileBrainHook): void;
+declare function getProfile(id: string): ModelProfile;
+declare function tryGetProfile(id: string): ModelProfile | undefined;
+declare function allProfiles(): readonly ModelProfile[];
+/** @internal — bundled-only access for adapters that need a non-brain
+ *  fallback baseline (avoids a brain → profiles → brain re-entry). */
+declare function allProfilesRaw(): readonly ModelProfile[];
+declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
+
+export { ALIASES, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };

package/dist/profiles.d.ts

@@ -1,2 +1,164 @@
-export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-CDttLtaD.js';
-import './dialect.js';
+import { k as Provider } from './ir-BmumS1Du.js';
+import { IntentArchetypeName } from './dialect.js';
+
+/**
+ * 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;
+    /**
+     * Hand-curated per-archetype performance score on a 0-10 scale.
+     *
+     *   10 = frontier on this archetype (e.g. Opus 4.7 on critique)
+     *    8 = strong second tier (Sonnet on plan, Pro on extract)
+     *    7 = competent (Haiku on classify, Flash on hunt)
+     *    5 = acceptable for tolerant archetypes (Flash-Lite on classify)
+     *    3 = degraded (Flash on critique, DeepSeek on hunt)
+     *
+     * Missing archetypes default to `5` (no data, neutral). Each non-default
+     * value should carry a one-line rationale in the profile's note or inline
+     * comment citing brain evidence, family prior, or "starter hypothesis —
+     * verify with telemetry."
+     *
+     * Source today: hand-curated from master plan §3.3 + §6.2 starter tables.
+     * Source tomorrow (alpha.10+): brain `archetype_model_evidence` view.
+     *
+     * Anti-hallucination guardrail (master plan §2.5): when the watcher's
+     * `--audit-fields` flag flags a profile stale (>90 days since
+     * verifiedAgainstDocs), the archetypePerf values get re-audited
+     * alongside capability fields. AI-trained intuition is NOT a valid
+     * source — only docs or brain evidence.
+     *
+     * alpha.9.
+     */
+    archetypePerf?: Partial<Record<IntentArchetypeName, number>>;
+    /**
+     * alpha.41 — model-family identifier (e.g. `'claude-opus'`,
+     * `'gemini-flash'`). Reads through from `kgauto_models.family` (migration
+     * 024). When unset on a brain row, runtime falls back to
+     * `deriveFamilyFromModelId(model.id)` (see `family-resolution.ts`).
+     *
+     * Used by `getRecommendedPrimary({ family, ... })` and the IR-level
+     * `{ family: string }` chain entry resolution at compile time.
+     */
+    family?: string;
+    /**
+     * alpha.41 — version string of the kgauto release that first introduced
+     * this profile (e.g. `'2.0.0-alpha.36'`). Threaded through from the brain
+     * row's `version_added` column. Family-resolution sorts candidates by
+     * `version_added DESC` (lexicographic) as the secondary tiebreaker after
+     * `archetypePerf[archetype]`. Undefined on bundled profiles (no brain
+     * row).
+     */
+    versionAdded?: string;
+    /**
+     * alpha.41 — whether the brain row is `active = TRUE`. False or undefined
+     * means the model is retired / not actively served (kgauto_models row
+     * exists but won't be selected by family resolution). Bundled profiles
+     * default to `true` when not threaded through (every PROFILES_RAW entry
+     * is by definition the active source of truth at bundle time).
+     */
+    active?: boolean;
+}
+declare const ALIASES: Record<string, string>;
+interface ProfileBrainHook {
+    getProfile?: (canonicalId: string) => ModelProfile | undefined;
+    resolveAlias?: (id: string) => string | undefined;
+}
+/** @internal — called by models-brain.ts at module load. */
+declare function _setProfileBrainHook(hook: ProfileBrainHook): void;
+declare function getProfile(id: string): ModelProfile;
+declare function tryGetProfile(id: string): ModelProfile | undefined;
+declare function allProfiles(): readonly ModelProfile[];
+/** @internal — bundled-only access for adapters that need a non-brain
+ *  fallback baseline (avoids a brain → profiles → brain re-entry). */
+declare function allProfilesRaw(): readonly ModelProfile[];
+declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
+
+export { ALIASES, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };