@niscorp/signal 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,591 @@
+import { z, ZodType } from 'zod';
+
+type ImageSource = {
+    type: 'url';
+    url: string;
+} | {
+    type: 'base64';
+    mediaType: string;
+    data: string;
+};
+type ContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: ImageSource;
+};
+type AssistantToolCall = {
+    id: string;
+    name: string;
+    args: string;
+};
+type Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string | ContentPart[];
+} | {
+    role: 'assistant';
+    content: string;
+    toolCalls?: AssistantToolCall[];
+} | {
+    role: 'tool';
+    toolCallId: string;
+    name: string;
+    content: string;
+};
+type ToolConfig<TInput = unknown> = {
+    name: string;
+    description: string;
+    input: z.ZodType<TInput>;
+    execute: (input: TInput) => Promise<unknown> | unknown;
+};
+type Tool = {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType;
+    execute: (input: unknown) => Promise<unknown> | unknown;
+};
+type ToolCallRecord = {
+    name: string;
+    args: unknown;
+    result: unknown;
+    durationMs: number;
+};
+type EndpointCapabilities = {
+    nativeTools: boolean;
+    nativeJsonMode: boolean;
+    validatesToolArgs: boolean;
+    supportsEmbedding: boolean;
+};
+type ModelCapabilities = {
+    nativeJsonSchema: boolean;
+    toolsWithStructuredOutput: boolean;
+    manglesNestedToolArgs: boolean;
+    multimodal: boolean;
+};
+type Capabilities = EndpointCapabilities & ModelCapabilities;
+declare const REASONING_EFFORTS: readonly ["none", "default", "minimal", "low", "medium", "high", "xhigh", "max"];
+type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+type SignalOptions = {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+    seed?: number;
+    signal?: AbortSignal;
+    reasoningEffort?: ReasoningEffort;
+};
+type ProviderError = {
+    code: string;
+    message: string;
+    recovered: boolean;
+    raw?: unknown;
+};
+type SignalMeta = {
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    durationMs: number;
+    retries: number;
+    toolCalls: ToolCallRecord[];
+    provider: {
+        raw: unknown;
+        errors: ProviderError[];
+    };
+};
+type SignalResult<T> = {
+    response: T;
+    history: Message[];
+    meta: SignalMeta;
+};
+type StepToolCall = {
+    id: string;
+    name: string;
+    args: unknown;
+};
+type StepInputMessage = Message | {
+    role: 'tool';
+    toolCallId: string;
+    name: string;
+    content: string;
+};
+type Rejection = {
+    name?: string;
+    args?: unknown;
+    argsText: string;
+    truncated: boolean;
+};
+type StepOutcome = {
+    kind: 'tool_calls';
+    calls: StepToolCall[];
+} | {
+    kind: 'output';
+    value: unknown;
+} | {
+    kind: 'failed';
+    evidence: string;
+    truncated?: boolean;
+};
+type WireReport = {
+    rung?: string;
+    recovered?: {
+        strategy: string;
+        name?: string;
+        truncated: boolean;
+    };
+    notes?: string[];
+};
+type StepToolDescriptor = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+type ResponseFormat = {
+    type: 'json_schema';
+    jsonSchema: {
+        name: string;
+        strict: boolean;
+        schema: Record<string, unknown>;
+    };
+} | {
+    type: 'json_object';
+};
+type StepRequest = {
+    messages: ReadonlyArray<StepInputMessage>;
+    tools?: ReadonlyArray<StepToolDescriptor>;
+    toolChoice?: 'auto' | 'none' | 'required' | {
+        name: string;
+    };
+    output?: {
+        accept: z.ZodType;
+        outputTool?: string;
+    };
+    responseFormat?: ResponseFormat;
+    options?: SignalOptions;
+};
+type StepResult = {
+    content: string;
+    toolCalls: StepToolCall[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        reported: boolean;
+    };
+    finishReason: string;
+    raw: unknown;
+    outcome?: StepOutcome;
+    wire?: WireReport;
+};
+type CountInput = string | ReadonlyArray<StepInputMessage>;
+type EmbedOptions = {
+    dimensions?: number;
+    onUsage?: (usage: {
+        inputTokens: number;
+        totalTokens: number;
+    }, model: string) => void;
+};
+type EmbedRequest = {
+    model: string;
+    input: string | string[];
+    dimensions?: number;
+};
+type EmbedResponse = {
+    embeddings: number[][];
+    usage: {
+        inputTokens: number;
+        totalTokens: number;
+    };
+};
+type ChoiceQuestion<K extends string = string> = {
+    type: 'choice';
+    instructions: string;
+    criteria: Record<K, string>;
+};
+type ScoreQuestion = {
+    type: 'score';
+    instructions: string;
+    criteria: readonly string[];
+};
+type NoulQuestion = {
+    type: 'noul';
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+};
+type Question = ChoiceQuestion | ScoreQuestion | NoulQuestion;
+type Questions = Record<string, Question>;
+type DecideState = string | Record<string, unknown> | readonly unknown[];
+type UncalibratedDecision<Q extends Question> = Q extends ChoiceQuestion<infer K> ? {
+    choice: K;
+} : Q extends ScoreQuestion ? {
+    level: number;
+} : {
+    answer: boolean;
+};
+type CalibratedDecision<Q extends Question> = Q extends ChoiceQuestion<infer K> ? {
+    choice: K;
+    probabilities: Record<K, number>;
+    confidence: number;
+} : Q extends ScoreQuestion ? {
+    level: number;
+    score: number;
+    probabilities: number[];
+    confidence: number;
+} : {
+    answer: boolean;
+    noul: number;
+};
+type DecideRequest<Qs extends Questions> = {
+    state: DecideState;
+    questions: Qs;
+    options?: {
+        signal?: AbortSignal;
+    };
+};
+type DecideMeta = {
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        reported: boolean;
+    };
+    durationMs: number;
+    provider: {
+        raw: unknown;
+    };
+};
+type DecideResult<Qs extends Questions> = {
+    calibrated: true;
+    decisions: {
+        [N in keyof Qs]: CalibratedDecision<Qs[N]>;
+    };
+    meta: DecideMeta;
+} | {
+    calibrated: false;
+    decisions: {
+        [N in keyof Qs]: UncalibratedDecision<Qs[N]>;
+    };
+    meta: DecideMeta;
+};
+type StreamEvent<T> = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_start';
+    name: string;
+    args: unknown;
+} | {
+    type: 'tool_end';
+    name: string;
+    result: unknown;
+} | {
+    type: 'retry';
+    reason: string;
+    attempt: number;
+} | {
+    type: 'error';
+    error: Error;
+    recovered: boolean;
+} | {
+    type: 'done';
+    response: T;
+    history: Message[];
+    meta: SignalMeta;
+};
+type StepStreamEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool_call_delta';
+    index: number;
+    id?: string;
+    name?: string;
+    argsText: string;
+} | {
+    type: 'done';
+    result: StepResult;
+};
+type StreamOptions = {
+    signal?: AbortSignal;
+};
+type ProviderStreamDelta = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool_call';
+    index: number;
+    id?: string;
+    name?: string;
+    argsFragment?: string;
+} | {
+    type: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+} | {
+    type: 'finish';
+    finishReason: string;
+};
+type ProviderRequest = {
+    model: string;
+    messages: Message[];
+    responseFormat?: ResponseFormat;
+    tools?: Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    toolChoice?: 'auto' | 'none' | 'required' | {
+        name: string;
+    };
+    options?: SignalOptions;
+};
+type ProviderResponse = {
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        args: string;
+    }>;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+    raw: unknown;
+};
+type ChatAdapter = {
+    kind: 'chat';
+    id: string;
+    chat: (request: ProviderRequest) => Promise<ProviderResponse>;
+    chatStream: (request: ProviderRequest, options?: {
+        signal?: AbortSignal;
+    }) => AsyncIterable<ProviderStreamDelta>;
+    embed?: (request: EmbedRequest) => Promise<EmbedResponse>;
+};
+type DecisionAdapter = {
+    kind: 'decisions';
+    id: string;
+    decide: (request: DecisionRequest, options?: {
+        signal?: AbortSignal;
+    }) => Promise<DecisionResponse>;
+};
+type ProviderAdapter = ChatAdapter | DecisionAdapter;
+type DecisionRequest = {
+    model: string;
+    state: DecideState;
+    questions: Questions;
+};
+type DecisionResponse = {
+    model?: string;
+    answers: unknown;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    raw: unknown;
+};
+
+type SignalConfig = {
+    readonly provider: string | CustomProviderConfig;
+    readonly apiKey?: string;
+    readonly model?: string;
+    readonly client?: unknown;
+    readonly systemPrompt?: string;
+    readonly history?: Message[];
+    readonly schema?: ZodType;
+    readonly tools?: Tool[];
+    readonly retries?: number;
+    readonly options?: SignalOptions;
+    readonly onRetry?: (error: Error, attempt: number) => void;
+    readonly onToolCall?: (name: string, args: unknown) => void;
+};
+type CustomProviderBase = {
+    baseUrl: string;
+    apiKey?: string;
+    model?: string;
+};
+type CustomChatProviderConfig = CustomProviderBase & {
+    adapter?: 'openai-compatible' | 'anthropic' | 'google';
+    capabilities?: Partial<Capabilities>;
+    wire?: string[];
+};
+type CustomDecisionProviderConfig = CustomProviderBase & {
+    adapter: 'systemone';
+};
+type CustomProviderConfig = CustomChatProviderConfig | CustomDecisionProviderConfig;
+
+type Signal<T = string> = {
+    apiKey: (key: string) => Signal<T>;
+    model: (model: string) => Signal<T>;
+    systemPrompt: (prompt: string) => Signal<T>;
+    history: (messages: Message[]) => Signal<T>;
+    schema: <U>(schema: ZodType<U>) => Signal<U>;
+    tools: (tools: Tool[]) => Signal<T>;
+    retries: (count: number) => Signal<T>;
+    options: (opts: SignalOptions) => Signal<T>;
+    onRetry: (handler: (error: Error, attempt: number) => void) => Signal<T>;
+    onToolCall: (handler: (name: string, args: unknown) => void) => Signal<T>;
+    complete: (input: string | ContentPart[]) => Promise<SignalResult<T>>;
+    stream: (input: string | ContentPart[], options?: StreamOptions) => AsyncIterable<StreamEvent<T>>;
+    describe: () => SignalDescription;
+    step: (request: StepRequest) => Promise<StepResult>;
+    stepStream: (request: StepRequest, options?: StreamOptions) => AsyncIterable<StepStreamEvent>;
+    count: (input: CountInput) => Promise<number>;
+    embed: {
+        (input: string, options?: EmbedOptions): Promise<number[]>;
+        (input: string[], options?: EmbedOptions): Promise<number[][]>;
+    };
+    decide: <const Qs extends Questions>(request: DecideRequest<Qs>) => Promise<DecideResult<Qs>>;
+};
+type SignalDescription = {
+    provider: string;
+    model: string | undefined;
+    kind: ProviderAdapter['kind'];
+    capabilities: Capabilities;
+    modelKnown: boolean;
+};
+declare const createSignal: (provider: string | CustomProviderConfig, options?: Partial<Omit<SignalConfig, "provider">>) => Signal<string>;
+
+declare const defineTool: <TInput>(config: ToolConfig<TInput>) => Tool;
+
+declare const ErrorCode: {
+    readonly PROVIDER_NOT_FOUND: "E_PROVIDER_NOT_FOUND";
+    readonly MISSING_API_KEY: "E_MISSING_API_KEY";
+    readonly MISSING_MODEL: "E_MISSING_MODEL";
+    readonly MISSING_SDK: "E_MISSING_SDK";
+    readonly VALIDATION_FAILED: "E_VALIDATION_FAILED";
+    readonly MAX_RETRIES: "E_MAX_RETRIES";
+    readonly MAX_ITERATIONS: "E_MAX_ITERATIONS";
+    readonly PROVIDER_ERROR: "E_PROVIDER_ERROR";
+    readonly TOOL_NOT_FOUND: "E_TOOL_NOT_FOUND";
+    readonly TOOL_EXECUTION: "E_TOOL_EXECUTION";
+    readonly TOOL_VALIDATION: "E_TOOL_VALIDATION";
+    readonly VERB_NOT_SUPPORTED: "E_VERB_NOT_SUPPORTED";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class SignalError extends Error {
+    readonly code: ErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: ErrorCode, context?: Record<string, unknown>);
+}
+
+type ProviderEntryBase = {
+    id: string;
+    baseUrl: string;
+    envKey: string;
+    defaultModel: string;
+};
+type ChatProviderEntry = ProviderEntryBase & {
+    adapter: 'openai-compatible' | 'anthropic' | 'google';
+    endpoint: EndpointCapabilities;
+    wire?: string[];
+    reasoningRequest?: Record<string, unknown>;
+};
+type DecisionProviderEntry = ProviderEntryBase & {
+    adapter: 'systemone';
+};
+type ProviderEntry = ChatProviderEntry | DecisionProviderEntry;
+type ModelEntry = {
+    capabilities: ModelCapabilities;
+    reasoningEfforts: readonly ReasoningEffort[];
+    verified: string;
+};
+declare const providerRegistry: Record<string, ProviderEntry>;
+declare const modelRegistry: Record<string, ModelEntry>;
+declare const UNMEASURED_MODEL: ModelCapabilities;
+declare const modelKey: (provider: string, model: string) => string;
+declare const modelEntry: (provider: string, model: string) => ModelEntry | undefined;
+declare const chatProviderEntry: (id: string) => ChatProviderEntry | undefined;
+
+type ErrorWireStrategy = {
+    id: string;
+    hook: 'error';
+    matches: (error: unknown) => boolean;
+    recover: (error: unknown) => Rejection | undefined;
+};
+type ResponseWireStrategy = {
+    id: string;
+    hook: 'response';
+    candidates: (content: string) => string[];
+};
+type WireStrategy = ErrorWireStrategy | ResponseWireStrategy;
+
+type RouteRequest = {
+    content: string;
+    toolCalls: ReadonlyArray<StepToolCall>;
+    declared: ReadonlySet<string>;
+    outputTool?: string | undefined;
+    accept?: ZodType | undefined;
+    responseStrategies: ReadonlyArray<ResponseWireStrategy>;
+};
+type Routed = {
+    outcome: StepOutcome;
+    wire: WireReport;
+};
+declare const routeResponse: (request: RouteRequest) => Routed;
+declare const routeRejection: (rejection: Rejection, request: Omit<RouteRequest, "content" | "toolCalls">) => Routed;
+
+type ExtractResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+declare const extractJson: (content: string) => ExtractResult;
+declare const repairEscapeDamage: (text: string) => string[];
+declare const decodeJsonish: (value: unknown) => unknown;
+declare const deepDecodeJsonish: (value: unknown) => unknown;
+declare const closeTruncated: (content: string) => string | undefined;
+declare const isTruncatedJson: (content: string) => boolean;
+
+type OutputTransport = 'respond' | 'native' | 'emit';
+type ResponseMode = 'required' | 'optional';
+type TransportSpec = {
+    wire: ZodType;
+    looseWire: ZodType;
+    responseMode: ResponseMode;
+    hasData: boolean;
+    hasTools: boolean;
+    choice?: 'auto' | OutputTransport;
+    forceTool?: boolean;
+};
+type ResolvedTransport = {
+    transport: OutputTransport;
+    responseMode: ResponseMode;
+    respondDetail?: 'full' | 'loose' | 'permissive';
+    respondDescriptor?: StepToolDescriptor;
+    outputToolName?: string;
+    responseFormat?: ResponseFormat;
+    toolChoice?: 'required';
+    injectSchemaDoc: boolean;
+    finishProtocol: string;
+    corrections: {
+        termination: string;
+        invalidOutput: string;
+    };
+};
+declare const RESPOND_TOOL_NAME = "respond";
+declare const resolveTransport: (spec: TransportSpec, caps: Capabilities) => ResolvedTransport;
+
+export { type AssistantToolCall, type CalibratedDecision, type Capabilities, type ChatProviderEntry, type ChoiceQuestion, type ContentPart, type CountInput, type CustomChatProviderConfig, type CustomDecisionProviderConfig, type CustomProviderConfig, type DecideMeta, type DecideRequest, type DecideResult, type DecideState, type DecisionProviderEntry, type EmbedOptions, type EmbedRequest, type EmbedResponse, type EndpointCapabilities, ErrorCode, type ErrorWireStrategy, type ExtractResult, type ImageSource, type Message, type ModelCapabilities, type ModelEntry, type NoulQuestion, type OutputTransport, type ProviderEntry, type ProviderError, type Question, type Questions, REASONING_EFFORTS, RESPOND_TOOL_NAME, type ReasoningEffort, type Rejection, type ResolvedTransport, type ResponseFormat, type ResponseWireStrategy, type ScoreQuestion, type Signal, type SignalConfig, type SignalDescription, SignalError, type SignalMeta, type SignalOptions, type SignalResult, type StepInputMessage, type StepOutcome, type StepRequest, type StepResult, type StepStreamEvent, type StepToolCall, type StepToolDescriptor, type StreamEvent, type StreamOptions, type Tool, type ToolCallRecord, type ToolConfig, type TransportSpec, UNMEASURED_MODEL, type UncalibratedDecision, type WireReport, type WireStrategy, chatProviderEntry, closeTruncated, createSignal, decodeJsonish, deepDecodeJsonish, defineTool, extractJson, isTruncatedJson, modelEntry, modelKey, modelRegistry, providerRegistry, repairEscapeDamage, resolveTransport, routeRejection, routeResponse };