@warmdrift/kgauto 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,229 @@
+/**
+ * KG-auto types — shared across adapter, logger, and public API.
+ */
+interface ModelProfile {
+    id: string;
+    provider: string;
+    status: 'current' | 'legacy' | 'preview';
+    max_tools: number;
+    max_context_tokens: number;
+    max_output_tokens: number;
+    parallel_tool_calls: boolean;
+    output_modes: ('generateText' | 'generateObject')[];
+    prompt_rules: string[];
+    known_failures: string[];
+    strengths: string[];
+    weaknesses: string[];
+    cost_input_per_1m: number;
+    cost_output_per_1m: number;
+    step_limit_default: number;
+    notes: string;
+}
+interface Message {
+    role: string;
+    content: string;
+}
+interface ToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface AdapterConstraints {
+    /** Tool relevance scores (0-1). Higher = more likely to be kept during budgeting. */
+    relevanceHints?: Record<string, number>;
+    /** Hard word limit injected into system prompt. */
+    maxResponseWords?: number;
+    /** Whether the caller wants structured JSON output. */
+    structuredOutput?: boolean;
+    /** Max latency hint (advisory, not enforced by adapter). */
+    maxLatencyMs?: number;
+    /** Quality floor hint (advisory). */
+    qualityFloor?: number;
+    /** Caller-provided intent classification (skips heuristic detection). */
+    intentHint?: string;
+    /** Project identifier for logging. */
+    project?: string;
+}
+interface PrepareInput {
+    /** Target model profile ID (e.g. "gemini-2.5-flash"). */
+    model: string;
+    /** Raw system prompt before adaptation. */
+    systemPrompt: string;
+    /** Conversation messages. */
+    messages: Message[];
+    /** Available tools — adapter may reduce this set. */
+    tools?: ToolDefinition[];
+    /** Constraints and hints. */
+    constraints?: AdapterConstraints;
+}
+interface ToolPolicy {
+    name: string;
+    parallelSafe: boolean;
+    maxPerResponse: number | null;
+    reason: string | null;
+}
+interface PrepareResult {
+    requestId: string;
+    model: string;
+    provider: string;
+    systemPrompt: string;
+    messages: Message[];
+    tools: ToolDefinition[];
+    outputStrategy: 'generateText' | 'generateObject';
+    promptRulesApplied: string[];
+    tokensEstimated: number;
+    contextBudget: number;
+    toolsOriginalCount: number;
+    toolsSelectedCount: number;
+    toolPolicies: ToolPolicy[] | null;
+}
+interface LogInput {
+    requestId: string;
+    model: string;
+    provider: string;
+    project?: string;
+    intent?: string;
+    toolsOffered?: number;
+    toolsSelected?: number;
+    toolsUsed?: number;
+    tokensIn: number;
+    tokensOut: number;
+    latencyMs: number;
+    success: boolean;
+    emptyResponse?: boolean;
+    errorType?: string;
+    adapterRulesApplied?: string[];
+    mode?: string;
+    toolsCalled?: string[];
+}
+interface LogResult {
+    logged: boolean;
+    requestId: string;
+    inputRatio: number | null;
+    efficiencyFlag: 'healthy' | 'warning' | 'critical' | null;
+    textOnly: boolean | null;
+    parallelismWarnings: string[] | null;
+}
+interface KGAutoConfig {
+    /** Optional: HTTP endpoint for centralized logging. If omitted, logs to console. */
+    logUrl?: string;
+    /** Project identifier for logging. Default: "default". */
+    project?: string;
+    /** Suppress console log output. Default: false. */
+    silent?: boolean;
+}
+
+/**
+ * Request Adapter — transforms raw requests so the target model handles them correctly.
+ *
+ * Port of gateway/adapter.py. Pure transform, no IO, no state.
+ *
+ * Three stages applied in order:
+ * 1. Unified token budget (tools + system prompt + messages share one context window)
+ * 2. Prompt rewriting (composable rules from model profile)
+ * 3. Output strategy selection (generateObject vs generateText)
+ */
+
+/**
+ * Prepare a request for a specific model.
+ *
+ * Pure function. Takes the raw request and returns an adapted request
+ * with budgeted tools, rewritten prompt, and output strategy.
+ *
+ * Throws Error if the system prompt exceeds the model's context budget.
+ */
+declare function prepare(input: PrepareInput): PrepareResult;
+
+/**
+ * Outcome logger — diagnostics for every model call.
+ *
+ * Three destinations:
+ * - console (default): human-readable log line
+ * - http: POST to a centralized endpoint (fire-and-forget)
+ * - silent: no output (for tests)
+ *
+ * Every log() call returns instant diagnostics:
+ * - efficiency flag (input/output ratio assessment)
+ * - text-only detection (tools offered but none used)
+ * - parallelism warnings (serial-only tools called multiple times)
+ */
+
+/** Compute all diagnostics for a log entry. */
+declare function computeDiagnostics(input: LogInput): LogResult;
+interface LogDestination {
+    write(input: LogInput, result: LogResult): void;
+}
+declare class ConsoleDestination implements LogDestination {
+    write(input: LogInput, result: LogResult): void;
+}
+declare class HttpDestination implements LogDestination {
+    private url;
+    constructor(url: string);
+    write(input: LogInput, _result: LogResult): void;
+}
+declare class SilentDestination implements LogDestination {
+    write(): void;
+}
+/**
+ * Log an outcome and return instant diagnostics.
+ *
+ * The diagnostics are computed synchronously. The write to the destination
+ * is fire-and-forget (may be async for HTTP, but never blocks the caller).
+ */
+declare function log(input: LogInput, destination: LogDestination): LogResult;
+
+/**
+ * Model profiles — bundled at build time from profiles/models.yaml.
+ *
+ * Adding a model = adding an entry to profiles.json + npm version bump.
+ */
+
+/** All loaded model profiles, keyed by model ID. */
+declare const PROFILES: Readonly<Record<string, ModelProfile>>;
+/** Get a single profile by ID. Throws if not found. */
+declare function getProfile(modelId: string): ModelProfile;
+/** Get all profiles with status "current". */
+declare function getCurrentProfiles(): Record<string, ModelProfile>;
+/** Get profiles filtered by provider. */
+declare function getProfilesByProvider(provider: string): Record<string, ModelProfile>;
+
+/**
+ * Per-tool execution policies — advises consumers on parallel safety.
+ *
+ * These tools cause side effects when called concurrently.
+ * The adapter advises; the consumer enforces.
+ *
+ * Source: tt-intelligence production data (61 fixtures, 50+ sessions).
+ */
+
+/** Tools that must NOT run in parallel. */
+declare const SERIAL_TOOLS: Record<string, string>;
+/** Compute tool policies for a set of tools. Only returns policies for serial-only tools. */
+declare function computeToolPolicies(tools: ToolDefinition[]): ToolPolicy[];
+/** Detect parallelism violations in a list of called tools. */
+declare function detectParallelismWarnings(toolsCalled: string[]): string[];
+
+/**
+ * Token counting — lightweight estimation for token budgeting.
+ *
+ * Uses char/4 heuristic by default (within 15% of tiktoken for English).
+ * The adapter's 10% safety margin on context budget absorbs the error.
+ *
+ * For precise counting, callers can inject a custom tokenizer via setTokenizer().
+ * Example: setTokenizer(text => tiktoken.encode(text).length)
+ */
+
+/**
+ * Override the default tokenizer with a precise one.
+ *
+ * Example with js-tiktoken:
+ *   import { encodingForModel } from 'js-tiktoken';
+ *   const enc = encodingForModel('gpt-4o');
+ *   setTokenizer(text => enc.encode(text).length);
+ */
+declare function setTokenizer(fn: (text: string) => number): void;
+/** Count tokens in a string. */
+declare function countTokens(text: string): number;
+
+export { type AdapterConstraints, ConsoleDestination, HttpDestination, type KGAutoConfig, type LogDestination, type LogInput, type LogResult, type Message, type ModelProfile, PROFILES, type PrepareInput, type PrepareResult, SERIAL_TOOLS, SilentDestination, type ToolDefinition, type ToolPolicy, computeDiagnostics, computeToolPolicies, countTokens, detectParallelismWarnings, getCurrentProfiles, getProfile, getProfilesByProvider, log, prepare, setTokenizer };

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * KG-auto types — shared across adapter, logger, and public API.
+ */
+interface ModelProfile {
+    id: string;
+    provider: string;
+    status: 'current' | 'legacy' | 'preview';
+    max_tools: number;
+    max_context_tokens: number;
+    max_output_tokens: number;
+    parallel_tool_calls: boolean;
+    output_modes: ('generateText' | 'generateObject')[];
+    prompt_rules: string[];
+    known_failures: string[];
+    strengths: string[];
+    weaknesses: string[];
+    cost_input_per_1m: number;
+    cost_output_per_1m: number;
+    step_limit_default: number;
+    notes: string;
+}
+interface Message {
+    role: string;
+    content: string;
+}
+interface ToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface AdapterConstraints {
+    /** Tool relevance scores (0-1). Higher = more likely to be kept during budgeting. */
+    relevanceHints?: Record<string, number>;
+    /** Hard word limit injected into system prompt. */
+    maxResponseWords?: number;
+    /** Whether the caller wants structured JSON output. */
+    structuredOutput?: boolean;
+    /** Max latency hint (advisory, not enforced by adapter). */
+    maxLatencyMs?: number;
+    /** Quality floor hint (advisory). */
+    qualityFloor?: number;
+    /** Caller-provided intent classification (skips heuristic detection). */
+    intentHint?: string;
+    /** Project identifier for logging. */
+    project?: string;
+}
+interface PrepareInput {
+    /** Target model profile ID (e.g. "gemini-2.5-flash"). */
+    model: string;
+    /** Raw system prompt before adaptation. */
+    systemPrompt: string;
+    /** Conversation messages. */
+    messages: Message[];
+    /** Available tools — adapter may reduce this set. */
+    tools?: ToolDefinition[];
+    /** Constraints and hints. */
+    constraints?: AdapterConstraints;
+}
+interface ToolPolicy {
+    name: string;
+    parallelSafe: boolean;
+    maxPerResponse: number | null;
+    reason: string | null;
+}
+interface PrepareResult {
+    requestId: string;
+    model: string;
+    provider: string;
+    systemPrompt: string;
+    messages: Message[];
+    tools: ToolDefinition[];
+    outputStrategy: 'generateText' | 'generateObject';
+    promptRulesApplied: string[];
+    tokensEstimated: number;
+    contextBudget: number;
+    toolsOriginalCount: number;
+    toolsSelectedCount: number;
+    toolPolicies: ToolPolicy[] | null;
+}
+interface LogInput {
+    requestId: string;
+    model: string;
+    provider: string;
+    project?: string;
+    intent?: string;
+    toolsOffered?: number;
+    toolsSelected?: number;
+    toolsUsed?: number;
+    tokensIn: number;
+    tokensOut: number;
+    latencyMs: number;
+    success: boolean;
+    emptyResponse?: boolean;
+    errorType?: string;
+    adapterRulesApplied?: string[];
+    mode?: string;
+    toolsCalled?: string[];
+}
+interface LogResult {
+    logged: boolean;
+    requestId: string;
+    inputRatio: number | null;
+    efficiencyFlag: 'healthy' | 'warning' | 'critical' | null;
+    textOnly: boolean | null;
+    parallelismWarnings: string[] | null;
+}
+interface KGAutoConfig {
+    /** Optional: HTTP endpoint for centralized logging. If omitted, logs to console. */
+    logUrl?: string;
+    /** Project identifier for logging. Default: "default". */
+    project?: string;
+    /** Suppress console log output. Default: false. */
+    silent?: boolean;
+}
+
+/**
+ * Request Adapter — transforms raw requests so the target model handles them correctly.
+ *
+ * Port of gateway/adapter.py. Pure transform, no IO, no state.
+ *
+ * Three stages applied in order:
+ * 1. Unified token budget (tools + system prompt + messages share one context window)
+ * 2. Prompt rewriting (composable rules from model profile)
+ * 3. Output strategy selection (generateObject vs generateText)
+ */
+
+/**
+ * Prepare a request for a specific model.
+ *
+ * Pure function. Takes the raw request and returns an adapted request
+ * with budgeted tools, rewritten prompt, and output strategy.
+ *
+ * Throws Error if the system prompt exceeds the model's context budget.
+ */
+declare function prepare(input: PrepareInput): PrepareResult;
+
+/**
+ * Outcome logger — diagnostics for every model call.
+ *
+ * Three destinations:
+ * - console (default): human-readable log line
+ * - http: POST to a centralized endpoint (fire-and-forget)
+ * - silent: no output (for tests)
+ *
+ * Every log() call returns instant diagnostics:
+ * - efficiency flag (input/output ratio assessment)
+ * - text-only detection (tools offered but none used)
+ * - parallelism warnings (serial-only tools called multiple times)
+ */
+
+/** Compute all diagnostics for a log entry. */
+declare function computeDiagnostics(input: LogInput): LogResult;
+interface LogDestination {
+    write(input: LogInput, result: LogResult): void;
+}
+declare class ConsoleDestination implements LogDestination {
+    write(input: LogInput, result: LogResult): void;
+}
+declare class HttpDestination implements LogDestination {
+    private url;
+    constructor(url: string);
+    write(input: LogInput, _result: LogResult): void;
+}
+declare class SilentDestination implements LogDestination {
+    write(): void;
+}
+/**
+ * Log an outcome and return instant diagnostics.
+ *
+ * The diagnostics are computed synchronously. The write to the destination
+ * is fire-and-forget (may be async for HTTP, but never blocks the caller).
+ */
+declare function log(input: LogInput, destination: LogDestination): LogResult;
+
+/**
+ * Model profiles — bundled at build time from profiles/models.yaml.
+ *
+ * Adding a model = adding an entry to profiles.json + npm version bump.
+ */
+
+/** All loaded model profiles, keyed by model ID. */
+declare const PROFILES: Readonly<Record<string, ModelProfile>>;
+/** Get a single profile by ID. Throws if not found. */
+declare function getProfile(modelId: string): ModelProfile;
+/** Get all profiles with status "current". */
+declare function getCurrentProfiles(): Record<string, ModelProfile>;
+/** Get profiles filtered by provider. */
+declare function getProfilesByProvider(provider: string): Record<string, ModelProfile>;
+
+/**
+ * Per-tool execution policies — advises consumers on parallel safety.
+ *
+ * These tools cause side effects when called concurrently.
+ * The adapter advises; the consumer enforces.
+ *
+ * Source: tt-intelligence production data (61 fixtures, 50+ sessions).
+ */
+
+/** Tools that must NOT run in parallel. */
+declare const SERIAL_TOOLS: Record<string, string>;
+/** Compute tool policies for a set of tools. Only returns policies for serial-only tools. */
+declare function computeToolPolicies(tools: ToolDefinition[]): ToolPolicy[];
+/** Detect parallelism violations in a list of called tools. */
+declare function detectParallelismWarnings(toolsCalled: string[]): string[];
+
+/**
+ * Token counting — lightweight estimation for token budgeting.
+ *
+ * Uses char/4 heuristic by default (within 15% of tiktoken for English).
+ * The adapter's 10% safety margin on context budget absorbs the error.
+ *
+ * For precise counting, callers can inject a custom tokenizer via setTokenizer().
+ * Example: setTokenizer(text => tiktoken.encode(text).length)
+ */
+
+/**
+ * Override the default tokenizer with a precise one.
+ *
+ * Example with js-tiktoken:
+ *   import { encodingForModel } from 'js-tiktoken';
+ *   const enc = encodingForModel('gpt-4o');
+ *   setTokenizer(text => enc.encode(text).length);
+ */
+declare function setTokenizer(fn: (text: string) => number): void;
+/** Count tokens in a string. */
+declare function countTokens(text: string): number;
+
+export { type AdapterConstraints, ConsoleDestination, HttpDestination, type KGAutoConfig, type LogDestination, type LogInput, type LogResult, type Message, type ModelProfile, PROFILES, type PrepareInput, type PrepareResult, SERIAL_TOOLS, SilentDestination, type ToolDefinition, type ToolPolicy, computeDiagnostics, computeToolPolicies, countTokens, detectParallelismWarnings, getCurrentProfiles, getProfile, getProfilesByProvider, log, prepare, setTokenizer };