wotann 0.5.0

package/dist/intelligence/smart-retry.js

@@ -0,0 +1,177 @@
+/**
+ * Smart Retry -- when something fails, analyze why and try differently.
+ * Not just "retry the same thing" but "understand the failure and adapt."
+ *
+ * Strategies: modify-prompt, switch-model, decompose-task, add-context, change-approach.
+ * Each retry attempts a different strategy based on error analysis.
+ * Tracks all attempts with detailed diagnostics.
+ */
+const ERROR_PATTERNS = [
+    [/rate.?limit|too.?many.?requests|429|throttl/i, "rate-limit"],
+    [/timeout|timed?\s*out|ETIMEDOUT|ECONNRESET/i, "timeout"],
+    [/context.?(?:length|overflow|too.?long|window)|max.?tokens|token.?limit/i, "context-overflow"],
+    [/invalid.?(?:response|json|format|output)|unexpected.?token|SyntaxError/i, "invalid-response"],
+    [/refus|cannot.?(?:help|assist)|policy|content.?filter|safety/i, "model-refusal"],
+    [/parse|JSON\.parse|unexpected.?end/i, "parse-error"],
+    [/auth|unauthorized|forbidden|401|403/i, "auth-error"],
+];
+const CATEGORY_STRATEGIES = new Map([
+    ["rate-limit", ["switch-model"]],
+    ["timeout", ["decompose-task", "switch-model"]],
+    ["context-overflow", ["decompose-task", "modify-prompt"]],
+    ["invalid-response", ["modify-prompt", "add-context"]],
+    ["model-refusal", ["modify-prompt", "change-approach"]],
+    ["parse-error", ["modify-prompt", "add-context"]],
+    ["auth-error", ["switch-model"]],
+    ["unknown", ["modify-prompt", "decompose-task", "change-approach"]],
+]);
+// -- Strategy descriptions ---------------------------------------------------
+const STRATEGY_DESCRIPTIONS = new Map([
+    ["modify-prompt", "Rephrase the prompt to avoid the issue that caused failure"],
+    ["switch-model", "Try a different model that may handle this task better"],
+    ["decompose-task", "Break the task into smaller subtasks and tackle them individually"],
+    ["add-context", "Add more context or examples to help the model understand"],
+    ["change-approach", "Try a fundamentally different approach to solving the problem"],
+]);
+// -- Implementation ----------------------------------------------------------
+export class SmartRetryEngine {
+    /**
+     * Analyze a failure and determine the best retry strategy.
+     */
+    analyzeFailure(error, context, previousAttempts) {
+        const classification = classifyError(error);
+        const usedStrategies = new Set(previousAttempts.map((a) => a.strategy));
+        const attemptNumber = previousAttempts.length + 1;
+        // Find the first unused strategy from the suggested list
+        let selectedStrategy = null;
+        for (const strategy of classification.suggestedStrategies) {
+            if (!usedStrategies.has(strategy)) {
+                selectedStrategy = strategy;
+                break;
+            }
+        }
+        // If all suggested strategies have been tried, use the full fallback chain
+        if (!selectedStrategy) {
+            const allStrategies = [
+                "modify-prompt",
+                "switch-model",
+                "decompose-task",
+                "add-context",
+                "change-approach",
+            ];
+            for (const strategy of allStrategies) {
+                if (!usedStrategies.has(strategy)) {
+                    selectedStrategy = strategy;
+                    break;
+                }
+            }
+        }
+        // If truly all strategies exhausted, cycle back to the most promising
+        if (!selectedStrategy) {
+            selectedStrategy = classification.suggestedStrategies[0] ?? "modify-prompt";
+        }
+        const confidence = computeConfidence(classification, previousAttempts.length);
+        const reason = buildReason(classification.category, selectedStrategy, error);
+        const modification = STRATEGY_DESCRIPTIONS.get(selectedStrategy) ?? "Unknown strategy";
+        return {
+            type: selectedStrategy,
+            reason,
+            modification,
+            confidence,
+            attemptNumber,
+        };
+    }
+    /**
+     * Execute a function with smart retry logic.
+     */
+    async executeWithRetry(fn, maxAttempts) {
+        const attempts = [];
+        const startTime = Date.now();
+        for (let i = 0; i < maxAttempts; i++) {
+            try {
+                const value = await fn();
+                return {
+                    success: true,
+                    value,
+                    attempts,
+                    finalStrategy: attempts.length > 0 ? attempts[attempts.length - 1]?.strategy ?? null : null,
+                    totalAttempts: i + 1,
+                    totalDurationMs: Date.now() - startTime,
+                };
+            }
+            catch (err) {
+                const errorStr = err instanceof Error ? err.message : String(err);
+                const strategy = this.analyzeFailure(errorStr, "", attempts);
+                attempts.push({
+                    strategy: strategy.type,
+                    error: errorStr,
+                    context: strategy.reason,
+                    attemptNumber: i + 1,
+                    timestamp: Date.now(),
+                });
+                // Don't retry auth errors -- they won't resolve by retrying
+                const classification = classifyError(errorStr);
+                if (!classification.shouldRetry) {
+                    break;
+                }
+            }
+        }
+        return {
+            success: false,
+            value: null,
+            attempts,
+            finalStrategy: attempts.length > 0 ? attempts[attempts.length - 1]?.strategy ?? null : null,
+            totalAttempts: attempts.length,
+            totalDurationMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Get all available retry strategies.
+     */
+    getAvailableStrategies() {
+        return ["modify-prompt", "switch-model", "decompose-task", "add-context", "change-approach"];
+    }
+    /**
+     * Classify an error string into an error category.
+     */
+    classifyError(error) {
+        return classifyError(error);
+    }
+}
+// -- Helpers -----------------------------------------------------------------
+function classifyError(error) {
+    for (const [pattern, category] of ERROR_PATTERNS) {
+        if (pattern.test(error)) {
+            const strategies = CATEGORY_STRATEGIES.get(category) ?? ["modify-prompt"];
+            const shouldRetry = category !== "auth-error";
+            return { category, suggestedStrategies: strategies, shouldRetry };
+        }
+    }
+    return {
+        category: "unknown",
+        suggestedStrategies: CATEGORY_STRATEGIES.get("unknown") ?? ["modify-prompt"],
+        shouldRetry: true,
+    };
+}
+function computeConfidence(classification, previousAttemptCount) {
+    // Base confidence per category
+    const baseConfidence = {
+        "rate-limit": 0.9,
+        "timeout": 0.7,
+        "context-overflow": 0.8,
+        "invalid-response": 0.6,
+        "model-refusal": 0.5,
+        "parse-error": 0.7,
+        "auth-error": 0.1,
+        "unknown": 0.3,
+    };
+    const base = baseConfidence[classification.category];
+    // Confidence drops with each retry
+    const decay = Math.max(0, 1 - previousAttemptCount * 0.15);
+    return Math.round(base * decay * 100) / 100;
+}
+function buildReason(category, strategy, error) {
+    const shortError = error.length > 80 ? error.slice(0, 77) + "..." : error;
+    return `Error classified as "${category}". Applying "${strategy}" strategy. Original error: ${shortError}`;
+}
+//# sourceMappingURL=smart-retry.js.map

package/dist/intelligence/smart-retry.js.map

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

package/dist/intelligence/strict-schema.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Deterministic tool-call schema enforcement — Phase 4 Sprint B2 item 18.
+ *
+ * OpenAI's `strict: true` mode and Anthropic's `strict` tools both
+ * guarantee that the model's tool-call output conforms EXACTLY to the
+ * schema — no hallucinated keys, no missing required fields, no type
+ * violations. Without it, ~2-4% of benchmark tool-calls get rejected
+ * downstream because the model fabricated a `reason` field that wasn't
+ * in the schema, or omitted a required `path`.
+ *
+ * This module ships three pieces:
+ *   1. makeStrict(schema) — transforms a JSON Schema into strict-safe
+ *      form: `additionalProperties: false` on every object, every
+ *      property listed in `required` (optional fields become union with
+ *      null). Applied at tool-registration time.
+ *   2. validateToolArguments(args, schema) — runtime validation. Returns
+ *      {valid, errors, corrected} so callers can choose to reject the
+ *      call, retry with a correction prompt, or auto-correct.
+ *   3. enforceDeterministicSchema(args, schema) — convenience that runs
+ *      both (strict-schema transform for the SHAPE + validation for the
+ *      ARGUMENTS) and auto-corrects when possible.
+ *
+ * No external deps. Pure structural traversal.
+ */
+export type JsonSchemaNode = Record<string, unknown>;
+export interface ValidationError {
+    /** Dot-path into the args (e.g. "options.verbose"). */
+    readonly path: string;
+    /** Human-readable message. */
+    readonly message: string;
+    /** Error category for automated correction. */
+    readonly kind: "missing-required" | "additional-property" | "type-mismatch" | "invalid-enum" | "shape-mismatch";
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+    /**
+     * Corrected args produced by dropping additional properties and
+     * filling missing required fields with null. Only populated when
+     * auto-correction is possible without fabricating data.
+     */
+    readonly corrected?: Record<string, unknown>;
+}
+/**
+ * Recursively transform a schema into OpenAI strict-mode compatible
+ * form. Rules:
+ *   - Every object gets additionalProperties: false
+ *   - Every object's properties all appear in required
+ *   - Optional fields become union [T, "null"]
+ *   - anyOf/oneOf preserved (models handle these)
+ *   - Arrays recurse into items
+ *
+ * The transform is PURE — returns a new object, leaves input untouched.
+ */
+export declare function makeStrict(schema: JsonSchemaNode): JsonSchemaNode;
+/**
+ * Validate tool arguments against a schema. Returns a detailed error
+ * report. Optionally produces a `corrected` args object that:
+ *   - Drops additional properties (strict-mode violation)
+ *   - Fills missing required fields with null (if the schema type
+ *     allows null — otherwise left missing so caller must retry)
+ */
+export declare function validateToolArguments(args: unknown, schema: JsonSchemaNode): ValidationResult;
+export interface EnforcementResult {
+    readonly strictSchema: JsonSchemaNode;
+    readonly validation: ValidationResult;
+    /** args to pass forward — corrected when possible, original when valid. */
+    readonly finalArgs: Record<string, unknown> | null;
+}
+/**
+ * Full pipeline: make schema strict + validate args + auto-correct.
+ * Returns `finalArgs: null` when the call is unrecoverable (missing
+ * required non-nullable field).
+ */
+export declare function enforceDeterministicSchema(args: unknown, schema: JsonSchemaNode): EnforcementResult;
+//# sourceMappingURL=strict-schema.d.ts.map

package/dist/intelligence/strict-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-schema.d.ts","sourceRoot":"","sources":["../../src/intelligence/strict-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EACT,kBAAkB,GAClB,qBAAqB,GACrB,eAAe,GACf,cAAc,GACd,gBAAgB,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAmDjE;AA4ID;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAY7F;AA8CD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,GACrB,iBAAiB,CAanB"}

package/dist/intelligence/strict-schema.js

@@ -0,0 +1,287 @@
+/**
+ * Deterministic tool-call schema enforcement — Phase 4 Sprint B2 item 18.
+ *
+ * OpenAI's `strict: true` mode and Anthropic's `strict` tools both
+ * guarantee that the model's tool-call output conforms EXACTLY to the
+ * schema — no hallucinated keys, no missing required fields, no type
+ * violations. Without it, ~2-4% of benchmark tool-calls get rejected
+ * downstream because the model fabricated a `reason` field that wasn't
+ * in the schema, or omitted a required `path`.
+ *
+ * This module ships three pieces:
+ *   1. makeStrict(schema) — transforms a JSON Schema into strict-safe
+ *      form: `additionalProperties: false` on every object, every
+ *      property listed in `required` (optional fields become union with
+ *      null). Applied at tool-registration time.
+ *   2. validateToolArguments(args, schema) — runtime validation. Returns
+ *      {valid, errors, corrected} so callers can choose to reject the
+ *      call, retry with a correction prompt, or auto-correct.
+ *   3. enforceDeterministicSchema(args, schema) — convenience that runs
+ *      both (strict-schema transform for the SHAPE + validation for the
+ *      ARGUMENTS) and auto-corrects when possible.
+ *
+ * No external deps. Pure structural traversal.
+ */
+// ── Strict transform ───────────────────────────────────
+function isObjectSchema(node) {
+    return node["type"] === "object" || node["properties"] !== undefined;
+}
+function isArraySchema(node) {
+    return node["type"] === "array" || node["items"] !== undefined;
+}
+/**
+ * Recursively transform a schema into OpenAI strict-mode compatible
+ * form. Rules:
+ *   - Every object gets additionalProperties: false
+ *   - Every object's properties all appear in required
+ *   - Optional fields become union [T, "null"]
+ *   - anyOf/oneOf preserved (models handle these)
+ *   - Arrays recurse into items
+ *
+ * The transform is PURE — returns a new object, leaves input untouched.
+ */
+export function makeStrict(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    // Shallow clone so we never mutate caller's object
+    const out = { ...schema };
+    if (isObjectSchema(out)) {
+        const props = out["properties"];
+        const existingRequired = Array.isArray(out["required"])
+            ? [...out["required"]]
+            : [];
+        if (props) {
+            // Recurse into each property
+            const newProps = {};
+            const allKeys = [];
+            for (const [key, child] of Object.entries(props)) {
+                const transformedChild = makeStrict(child);
+                // If this key wasn't required, make it nullable
+                if (!existingRequired.includes(key)) {
+                    newProps[key] = makeOptionalNullable(transformedChild);
+                }
+                else {
+                    newProps[key] = transformedChild;
+                }
+                allKeys.push(key);
+            }
+            out["properties"] = newProps;
+            // strict-mode requires ALL keys in required (optional kept via nullable)
+            out["required"] = allKeys;
+        }
+        out["additionalProperties"] = false;
+    }
+    if (isArraySchema(out)) {
+        const items = out["items"];
+        if (items && typeof items === "object" && !Array.isArray(items)) {
+            out["items"] = makeStrict(items);
+        }
+    }
+    // anyOf / oneOf: recurse into each branch
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = out[key];
+        if (Array.isArray(branches)) {
+            out[key] = branches.map((b) => typeof b === "object" && b ? makeStrict(b) : b);
+        }
+    }
+    return out;
+}
+function makeOptionalNullable(node) {
+    if (!node || typeof node !== "object")
+        return node;
+    const type = node["type"];
+    if (!type) {
+        // No explicit type — leave as-is (likely a union via anyOf)
+        return node;
+    }
+    if (Array.isArray(type)) {
+        return type.includes("null") ? node : { ...node, type: [...type, "null"] };
+    }
+    if (typeof type === "string") {
+        return type === "null" ? node : { ...node, type: [type, "null"] };
+    }
+    return node;
+}
+// ── Runtime validation ────────────────────────────────
+function typeMatches(value, expectedType) {
+    switch (expectedType) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && !Number.isNaN(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return true;
+    }
+}
+function validateNode(value, schema, path, errors) {
+    if (!schema || typeof schema !== "object")
+        return;
+    // anyOf/oneOf: at least one must validate
+    const anyOf = schema["anyOf"];
+    if (Array.isArray(anyOf)) {
+        for (const branch of anyOf) {
+            const branchErrors = [];
+            validateNode(value, branch, path, branchErrors);
+            if (branchErrors.length === 0)
+                return;
+        }
+        errors.push({
+            path,
+            message: `value did not match any variant of anyOf`,
+            kind: "shape-mismatch",
+        });
+        return;
+    }
+    // Type check
+    const type = schema["type"];
+    if (type) {
+        const types = Array.isArray(type) ? type : [type];
+        const ok = types.some((t) => typeMatches(value, String(t)));
+        if (!ok) {
+            errors.push({
+                path,
+                message: `expected ${types.join("|")}, got ${describe(value)}`,
+                kind: "type-mismatch",
+            });
+            return;
+        }
+    }
+    // Enum check
+    const enums = schema["enum"];
+    if (Array.isArray(enums) && !enums.includes(value)) {
+        errors.push({
+            path,
+            message: `expected one of [${enums.map((e) => JSON.stringify(e)).join(", ")}], got ${JSON.stringify(value)}`,
+            kind: "invalid-enum",
+        });
+        return;
+    }
+    // Object: check required + additional properties + recurse
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+        const props = (schema["properties"] ?? {});
+        const addlProp = schema["additionalProperties"];
+        for (const req of required) {
+            if (!(req in value)) {
+                errors.push({
+                    path: path ? `${path}.${req}` : req,
+                    message: `required property is missing`,
+                    kind: "missing-required",
+                });
+            }
+        }
+        const seenKeys = new Set();
+        for (const [key, val] of Object.entries(value)) {
+            seenKeys.add(key);
+            const subSchema = props[key];
+            if (subSchema) {
+                validateNode(val, subSchema, path ? `${path}.${key}` : key, errors);
+            }
+            else if (addlProp === false) {
+                errors.push({
+                    path: path ? `${path}.${key}` : key,
+                    message: `additional property not allowed`,
+                    kind: "additional-property",
+                });
+            }
+        }
+    }
+    // Array: recurse into items
+    if (Array.isArray(value)) {
+        const items = schema["items"];
+        if (items && typeof items === "object" && !Array.isArray(items)) {
+            for (let i = 0; i < value.length; i++) {
+                validateNode(value[i], items, `${path}[${i}]`, errors);
+            }
+        }
+    }
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * Validate tool arguments against a schema. Returns a detailed error
+ * report. Optionally produces a `corrected` args object that:
+ *   - Drops additional properties (strict-mode violation)
+ *   - Fills missing required fields with null (if the schema type
+ *     allows null — otherwise left missing so caller must retry)
+ */
+export function validateToolArguments(args, schema) {
+    const errors = [];
+    validateNode(args, schema, "", errors);
+    const valid = errors.length === 0;
+    if (valid || !args || typeof args !== "object" || Array.isArray(args)) {
+        return { valid, errors };
+    }
+    // Best-effort correction: drop extra keys, fill nullable missing fields
+    const corrected = tryCorrect(args, schema, errors);
+    return { valid, errors, corrected };
+}
+function tryCorrect(args, schema, errors) {
+    const out = { ...args };
+    let changed = false;
+    // Drop additional-property errors
+    for (const e of errors) {
+        if (e.kind === "additional-property") {
+            const key = e.path.split(".").pop() ?? e.path;
+            if (key in out) {
+                delete out[key];
+                changed = true;
+            }
+        }
+    }
+    // Fill missing-required fields with null IF nullable
+    const props = (schema["properties"] ?? {});
+    for (const e of errors) {
+        if (e.kind === "missing-required") {
+            const key = e.path.split(".").pop() ?? e.path;
+            const subSchema = props[key];
+            if (subSchema && allowsNull(subSchema)) {
+                out[key] = null;
+                changed = true;
+            }
+        }
+    }
+    return changed ? out : undefined;
+}
+function allowsNull(schema) {
+    const type = schema["type"];
+    if (Array.isArray(type))
+        return type.includes("null");
+    if (type === "null")
+        return true;
+    return false;
+}
+/**
+ * Full pipeline: make schema strict + validate args + auto-correct.
+ * Returns `finalArgs: null` when the call is unrecoverable (missing
+ * required non-nullable field).
+ */
+export function enforceDeterministicSchema(args, schema) {
+    const strictSchema = makeStrict(schema);
+    const validation = validateToolArguments(args, strictSchema);
+    let finalArgs = null;
+    if (validation.valid && args && typeof args === "object" && !Array.isArray(args)) {
+        finalArgs = args;
+    }
+    else if (validation.corrected) {
+        const recheck = validateToolArguments(validation.corrected, strictSchema);
+        finalArgs = recheck.valid ? validation.corrected : null;
+    }
+    return { strictSchema, validation, finalArgs };
+}
+//# sourceMappingURL=strict-schema.js.map

package/dist/intelligence/strict-schema.js.map

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

package/dist/intelligence/task-semantic-router.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Task-Semantic Model Router -- classifies user prompts by task type and
+ * complexity, then recommends the optimal model from available providers.
+ *
+ * Inspired by Perplexity's task-aware routing. Instead of always using
+ * the most expensive model, match model capabilities to the actual task.
+ *
+ * Classification uses pattern matching against known task indicators.
+ * Model selection uses a preference matrix keyed by task type + complexity.
+ *
+ * V9 DEHARDCODE: TRIVIAL_MODELS is derived from PROVIDER_DEFAULTS.workerModel
+ * across all known providers — adding a new provider/model happens in
+ * model-defaults.ts only and the router picks it up automatically. The
+ * MODEL_PREFERENCES table still lists per-task ranked models because each
+ * entry encodes a quality-per-task ranking that isn't expressible as a
+ * single tier name; see the comment above each entry for rationale.
+ */
+export type TaskType = "code-generation" | "code-review" | "debugging" | "research" | "creative-writing" | "data-analysis" | "conversation" | "math-reasoning" | "document-processing" | "image-understanding";
+export type TaskComplexity = "trivial" | "simple" | "moderate" | "complex" | "expert";
+export interface TaskClassification {
+    readonly type: TaskType;
+    readonly complexity: TaskComplexity;
+    readonly confidence: number;
+    readonly recommendedModel: string;
+    readonly fallbackModels: readonly string[];
+    readonly estimatedTokens: number;
+    readonly estimatedCostUsd: number;
+}
+export declare class TaskSemanticRouter {
+    /**
+     * Classify a prompt into task type + complexity using pattern matching,
+     * then recommend the optimal model from available models.
+     */
+    classify(prompt: string, availableModels: readonly string[]): TaskClassification;
+    /**
+     * Return the best model for a given task type from available models.
+     * For trivial tasks, always prefer cheap models regardless of task type.
+     */
+    selectModel(taskType: TaskType, complexity: TaskComplexity, available: readonly string[]): string;
+    /**
+     * Get all supported task types.
+     */
+    getSupportedTaskTypes(): readonly TaskType[];
+    /**
+     * Get the model preference list for a task type.
+     */
+    getPreferences(taskType: TaskType): readonly string[];
+}
+//# sourceMappingURL=task-semantic-router.d.ts.map

package/dist/intelligence/task-semantic-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-semantic-router.d.ts","sourceRoot":"","sources":["../../src/intelligence/task-semantic-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,QAAQ,GAChB,iBAAiB,GACjB,aAAa,GACb,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAItF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AA6PD,qBAAa,kBAAkB;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB;IAoChF;;;OAGG;IACH,WAAW,CACT,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,cAAc,EAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM;IAkCT;;OAEG;IACH,qBAAqB,IAAI,SAAS,QAAQ,EAAE;IAI5C;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE;CAGtD"}