gauss-ts 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,492 @@
+import { D as Disposable, H as Handle, E as EvalScorerType, J as JsMessage, e as CostEstimate, M as Message, b as AgentResult } from './types-BkwC4s1P.cjs';
+export { A as AgentOptions, f as Citation, C as CodeExecutionOptions, g as CodeExecutionResult, h as CoercionStrategy, G as GeneratedImageData, i as GroundingChunk, j as GroundingMetadata, I as ImageGenerationConfig, k as ImageGenerationResult, l as MemoryEntry, m as MemoryStats, n as MessageRole, o as PiiAction, d as ProviderCapabilities, c as ProviderOptions, P as ProviderType, R as RecallOptions, p as SearchResult, S as StreamCallback, T as ToolDef, a as ToolExecutor, V as VectorChunk, q as detectProvider, r as resolveApiKey } from './types-BkwC4s1P.cjs';
+import { A as AgentConfig, a as Agent } from './agent-CMp1wFzs.cjs';
+export { b as AgentStream, S as StreamEvent, g as gauss } from './agent-CMp1wFzs.cjs';
+export { BatchItem, availableRuntimes, batch, executeCode, generateImage } from './agent.cjs';
+export { Memory, VectorStore } from './rag.cjs';
+export { ConsensusStrategy, ForkNodeConfig, Graph, GraphNodeConfig, Network, Team, TeamResult, TeamStrategy, Workflow, WorkflowStepConfig } from './orchestration.cjs';
+export { GuardrailChain, MiddlewareChain, PluginRegistry } from './middleware.cjs';
+export { A2aClient, A2aClientOptions, A2aMessage, A2aMessageRole, AgentCapabilities, AgentCard, AgentSkill, Artifact, McpContent, McpModelHint, McpModelPreferences, McpPrompt, McpPromptArgument, McpPromptMessage, McpPromptResult, McpResource, McpResourceContent, McpSamplingMessage, McpSamplingRequest, McpSamplingResponse, McpServer, MessageSendConfig, Part, SendMessageResult, Task, TaskState, TaskStatus, agentMessage, extractText, taskText, textMessage, userMessage } from './mcp.cjs';
+export { ToolExample, ToolRegistry, ToolRegistryEntry, ToolSearchResult, ToolValidator } from './tools.cjs';
+export { version } from 'gauss-napi';
+
+/**
+ * Model Constants — Single Source of Truth
+ *
+ * Update these when new model versions are released.
+ * All examples, tests, and defaults reference this file.
+ */
+declare const OPENAI_DEFAULT = "gpt-5.2";
+declare const OPENAI_FAST = "gpt-4.1";
+declare const OPENAI_REASONING = "o4-mini";
+declare const OPENAI_IMAGE = "gpt-image-1";
+declare const ANTHROPIC_DEFAULT = "claude-sonnet-4-20250514";
+declare const ANTHROPIC_FAST = "claude-haiku-4-20250414";
+declare const ANTHROPIC_PREMIUM = "claude-opus-4-20250414";
+declare const GOOGLE_DEFAULT = "gemini-2.5-flash";
+declare const GOOGLE_PREMIUM = "gemini-2.5-pro";
+declare const GOOGLE_IMAGE = "gemini-2.0-flash";
+declare const OPENROUTER_DEFAULT = "openai/gpt-5.2";
+declare const DEEPSEEK_DEFAULT = "deepseek-chat";
+declare const DEEPSEEK_REASONING = "deepseek-reasoner";
+declare const TOGETHER_DEFAULT = "meta-llama/Llama-3.3-70B-Instruct-Turbo";
+declare const FIREWORKS_DEFAULT = "accounts/fireworks/models/llama-v3p1-70b-instruct";
+declare const MISTRAL_DEFAULT = "mistral-large-latest";
+declare const PERPLEXITY_DEFAULT = "sonar-pro";
+declare const XAI_DEFAULT = "grok-3-beta";
+declare const PROVIDER_DEFAULTS: Record<string, string>;
+/** Get the default model for a provider */
+declare function defaultModel(provider: string): string;
+
+interface EnterprisePresetOptions extends AgentConfig {
+    retries?: number;
+}
+/**
+ * Plug-and-play enterprise preset with production-safe defaults.
+ */
+declare function enterprisePreset(config?: EnterprisePresetOptions): Agent;
+/**
+ * One-liner enterprise run helper.
+ */
+declare function enterpriseRun(prompt: string, config?: EnterprisePresetOptions): Promise<string>;
+
+declare class ApprovalManager implements Disposable {
+    private readonly _handle;
+    private disposed;
+    constructor();
+    get handle(): Handle;
+    request(toolName: string, args: Record<string, unknown>, sessionId: string): string;
+    approve(requestId: string, modifiedArgs?: Record<string, unknown>): void;
+    deny(requestId: string, reason?: string): void;
+    listPending(): unknown;
+    destroy(): void;
+    [Symbol.dispose](): void;
+    private assertNotDisposed;
+}
+
+declare class CheckpointStore implements Disposable {
+    private readonly _handle;
+    private disposed;
+    constructor();
+    get handle(): Handle;
+    save(checkpoint: Record<string, unknown>): Promise<void>;
+    load(checkpointId: string): Promise<unknown>;
+    loadLatest(sessionId: string): Promise<unknown>;
+    destroy(): void;
+    [Symbol.dispose](): void;
+    private assertNotDisposed;
+}
+
+declare class EvalRunner implements Disposable {
+    private readonly _handle;
+    private disposed;
+    constructor(threshold?: number);
+    get handle(): Handle;
+    addScorer(scorerType: EvalScorerType): this;
+    destroy(): void;
+    [Symbol.dispose](): void;
+    private assertNotDisposed;
+    static loadDatasetJsonl(jsonl: string): unknown;
+    static loadDatasetJson(jsonStr: string): unknown;
+}
+
+declare class Telemetry implements Disposable {
+    private readonly _handle;
+    private disposed;
+    constructor();
+    get handle(): Handle;
+    /** Record a span. Pass a SpanRecord object or use the convenience overload. */
+    recordSpan(span: Record<string, unknown>): void;
+    recordSpan(name: string, durationMs: number, attributes?: Record<string, unknown>): void;
+    exportSpans(): unknown;
+    exportMetrics(): unknown;
+    clear(): void;
+    destroy(): void;
+    [Symbol.dispose](): void;
+    private assertNotDisposed;
+}
+
+/**
+ * Create a fallback provider that tries providers in order.
+ * Returns a provider handle usable with Agent constructor.
+ */
+declare function createFallbackProvider(providerHandles: Handle[]): Handle;
+/**
+ * Wrap a provider with a circuit breaker.
+ * Returns a provider handle usable with Agent constructor.
+ */
+declare function createCircuitBreaker(providerHandle: Handle, failureThreshold?: number, recoveryTimeoutMs?: number): Handle;
+/**
+ * Create a resilient provider with retry, circuit breaker, and fallbacks.
+ * Returns a provider handle usable with Agent constructor.
+ */
+declare function createResilientProvider(primaryHandle: Handle, fallbackHandles: Handle[], enableCircuitBreaker?: boolean): Handle;
+/**
+ * Convenience: create a resilient agent by wrapping its provider.
+ */
+declare function createResilientAgent(primary: Agent, fallbacks: Agent[], enableCircuitBreaker?: boolean): Handle;
+
+declare function countTokens(text: string): number;
+declare function countTokensForModel(text: string, model: string): number;
+declare function countMessageTokens(messages: JsMessage[]): number;
+declare function getContextWindowSize(model: string): number;
+declare function estimateCost(model: string, usage: {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}): CostEstimate;
+
+declare function parseAgentConfig(jsonStr: string): string;
+declare function resolveEnv(value: string): string;
+
+declare function parsePartialJson(text: string): string | null;
+
+/**
+ * Retry utilities — exponential backoff and configurable retry logic.
+ *
+ * @example
+ *   import { withRetry, RetryConfig } from "gauss-ts";
+ *
+ *   const result = await withRetry(() => agent.run("Hello"), {
+ *     maxRetries: 3,
+ *     backoff: "exponential",
+ *   });
+ *
+ *   // Or wrap an agent:
+ *   const resilientRun = retryable(agent, { maxRetries: 5 });
+ *   const result = await resilientRun("Hello");
+ */
+
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3). */
+    maxRetries?: number;
+    /** Backoff strategy (default: "exponential"). */
+    backoff?: "fixed" | "linear" | "exponential";
+    /** Base delay in ms (default: 1000). */
+    baseDelayMs?: number;
+    /** Maximum delay in ms (default: 30000). */
+    maxDelayMs?: number;
+    /** Jitter factor 0–1 (default: 0.1). Adds randomness to prevent thundering herd. */
+    jitter?: number;
+    /** Optional predicate — retry only if this returns true for the error. */
+    retryIf?: (error: Error, attempt: number) => boolean;
+    /** Called on each retry attempt, useful for logging. */
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+}
+/**
+ * Execute an async function with retry logic.
+ *
+ * @example
+ *   const data = await withRetry(async () => {
+ *     return await agent.run("Summarize this article");
+ *   }, { maxRetries: 3, backoff: "exponential" });
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Wrap an agent's run method with retry logic. Returns a function
+ * that accepts a prompt and returns an AgentResult.
+ *
+ * @example
+ *   const run = retryable(agent, { maxRetries: 5 });
+ *   const result = await run("Hello");
+ */
+declare function retryable(agent: Agent, config?: RetryConfig): (prompt: string | Message[]) => Promise<AgentResult>;
+
+/**
+ * Structured Output — validate and extract typed JSON from LLM responses.
+ *
+ * @example
+ *   import { structured, zodSchema } from "gauss-ts";
+ *
+ *   const result = await structured(agent, "List 3 fruits", {
+ *     schema: { type: "object", properties: { fruits: { type: "array", items: { type: "string" } } } },
+ *   });
+ *   console.log(result.data.fruits); // ["apple", "banana", "cherry"]
+ */
+
+/** JSON Schema subset for structured output. */
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    enum?: unknown[];
+    description?: string;
+    [key: string]: unknown;
+}
+interface StructuredConfig {
+    /** JSON schema the output must conform to. */
+    schema: JsonSchema;
+    /** Maximum parse retries if the model returns invalid JSON (default: 2). */
+    maxParseRetries?: number;
+    /** If true, include the raw AgentResult alongside parsed data. */
+    includeRaw?: boolean;
+}
+interface StructuredResult<T = unknown> {
+    /** Parsed and validated data. */
+    data: T;
+    /** Raw agent result (only if includeRaw was true). */
+    raw?: AgentResult;
+}
+/**
+ * Run an agent with structured output extraction.
+ *
+ * Automatically instructs the model to output JSON matching the schema,
+ * extracts and parses the JSON from the response, and retries on parse failure.
+ *
+ * @example
+ *   const { data } = await structured(agent, "List 3 programming languages", {
+ *     schema: {
+ *       type: "object",
+ *       properties: {
+ *         languages: { type: "array", items: { type: "string" } }
+ *       },
+ *       required: ["languages"]
+ *     }
+ *   });
+ *   console.log(data.languages);
+ */
+declare function structured<T = unknown>(agent: Agent, prompt: string | Message[], config: StructuredConfig): Promise<StructuredResult<T>>;
+
+/**
+ * Prompt Templates — composable, type-safe prompt construction.
+ *
+ * @example
+ *   import { template, PromptTemplate } from "gauss-ts";
+ *
+ *   const summarize = template("Summarize the following {{format}}:\n\n{{text}}");
+ *   const prompt = summarize({ format: "article", text: "Lorem ipsum..." });
+ *
+ *   // Composition:
+ *   const withTone = template("{{base}}\n\nUse a {{tone}} tone.");
+ *   const prompt = withTone({
+ *     base: summarize({ format: "article", text: "..." }),
+ *     tone: "professional",
+ *   });
+ */
+/** Extract variable names from a template string. */
+type ExtractVars<T extends string> = T extends `${string}{{${infer Var}}}${infer Rest}` ? Var | ExtractVars<Rest> : never;
+/** Variables object for a template. */
+type TemplateVars<T extends string> = Record<ExtractVars<T>, string>;
+/** A compiled prompt template function. */
+interface PromptTemplate<T extends string = string> {
+    /** Render the template with variables. */
+    (vars: TemplateVars<T>): string;
+    /** The raw template string. */
+    readonly raw: string;
+    /** List of variable names in the template. */
+    readonly variables: string[];
+}
+/**
+ * Create a reusable prompt template with `{{variable}}` placeholders.
+ *
+ * @example
+ *   const t = template("Hello {{name}}, you are {{age}} years old.");
+ *   t({ name: "Alice", age: "30" }); // "Hello Alice, you are 30 years old."
+ *   t.variables; // ["name", "age"]
+ */
+declare function template<T extends string>(templateStr: T): PromptTemplate<T>;
+/** Summarization template. */
+declare const summarize: PromptTemplate<"Summarize the following {{format}} in {{style}}:\n\n{{text}}">;
+/** Translation template. */
+declare const translate: PromptTemplate<"Translate the following text to {{language}}:\n\n{{text}}">;
+/** Code review template. */
+declare const codeReview: PromptTemplate<"Review this {{language}} code for bugs, security issues, and best practices:\n\n```{{language}}\n{{code}}\n```">;
+/** Classification template. */
+declare const classify: PromptTemplate<"Classify the following text into one of these categories: {{categories}}\n\nText: {{text}}\n\nRespond with only the category name.">;
+/** Extraction template. */
+declare const extract: PromptTemplate<"Extract the following information from the text: {{fields}}\n\nText: {{text}}\n\nRespond as JSON.">;
+
+/**
+ * AGENTS.MD and SKILL.MD parsers — parse agent/skill specifications from markdown.
+ *
+ * @example
+ * ```ts
+ * import { AgentSpec, SkillSpec, discoverAgents } from "gauss-ts";
+ *
+ * // Parse a single AGENTS.MD
+ * const spec = AgentSpec.fromMarkdown(content);
+ * console.log(spec.name, spec.tools);
+ *
+ * // Discover all agents in a directory tree
+ * const agents = await discoverAgents("./agents");
+ *
+ * // Parse a SKILL.MD
+ * const skill = SkillSpec.fromMarkdown(skillContent);
+ * console.log(skill.steps);
+ * ```
+ */
+/** Tool reference within an AGENTS.MD spec. */
+interface AgentToolSpec {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+/** Parsed agent specification from AGENTS.MD. */
+interface AgentSpecData {
+    name: string;
+    description: string;
+    model?: string;
+    provider?: string;
+    instructions?: string;
+    tools: AgentToolSpec[];
+    skills: string[];
+    capabilities: string[];
+    environment: Array<[string, string]>;
+    metadata: Record<string, unknown>;
+}
+/** Step within a SKILL.MD spec. */
+interface SkillStep {
+    description: string;
+    action?: string;
+}
+/** Input or output parameter in a SKILL.MD spec. */
+interface SkillParam {
+    name: string;
+    param_type: string;
+    description: string;
+    required: boolean;
+}
+/** Parsed skill specification from SKILL.MD. */
+interface SkillSpecData {
+    name: string;
+    description: string;
+    steps: SkillStep[];
+    inputs: SkillParam[];
+    outputs: SkillParam[];
+}
+/** Immutable parsed AGENTS.MD specification with a fluent API. */
+declare class AgentSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly model?: string;
+    readonly provider?: string;
+    readonly instructions?: string;
+    readonly tools: readonly AgentToolSpec[];
+    readonly skills: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly environment: ReadonlyMap<string, string>;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    private constructor();
+    /** Parse an AGENTS.MD markdown string into an AgentSpec. */
+    static fromMarkdown(content: string): AgentSpec;
+    /** Check whether a specific tool is declared in this spec. */
+    hasTool(name: string): boolean;
+    /** Check whether a specific capability is declared. */
+    hasCapability(name: string): boolean;
+    /** Serialize back to a plain object. */
+    toJSON(): AgentSpecData;
+}
+/** Immutable parsed SKILL.MD specification with a fluent API. */
+declare class SkillSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly steps: readonly SkillStep[];
+    readonly inputs: readonly SkillParam[];
+    readonly outputs: readonly SkillParam[];
+    private constructor();
+    /** Parse a SKILL.MD markdown string into a SkillSpec. */
+    static fromMarkdown(content: string): SkillSpec;
+    /** Get the total number of steps. */
+    get stepCount(): number;
+    /** Get all required inputs. */
+    get requiredInputs(): readonly SkillParam[];
+    /** Serialize back to a plain object. */
+    toJSON(): SkillSpecData;
+}
+/** Discover all AGENTS.MD files in a directory tree and parse them. */
+declare function discoverAgents(dir: string): AgentSpec[];
+
+/**
+ * Pipeline — compose agent operations into clean data flows.
+ *
+ * @example
+ *   import { pipe, map, filter, tap } from "gauss-ts";
+ *
+ *   const result = await pipe(
+ *     ["apple", "banana", "cherry"],
+ *     map(fruit => agent.run(`Describe ${fruit}`)),
+ *     filter(r => r.text.length > 50),
+ *     tap(r => console.log(r.text)),
+ *   );
+ */
+/** An async transform step in a pipeline. */
+type PipeStep<I, O> = (input: I) => Promise<O> | O;
+/**
+ * Compose async operations into a pipeline.
+ *
+ * @example
+ *   const result = await pipe(
+ *     "Hello",
+ *     (s) => agent.run(s),
+ *     (r) => r.text.toUpperCase(),
+ *   );
+ */
+declare function pipe<A>(input: A): Promise<A>;
+declare function pipe<A, B>(input: A, s1: PipeStep<A, B>): Promise<B>;
+declare function pipe<A, B, C>(input: A, s1: PipeStep<A, B>, s2: PipeStep<B, C>): Promise<C>;
+declare function pipe<A, B, C, D>(input: A, s1: PipeStep<A, B>, s2: PipeStep<B, C>, s3: PipeStep<C, D>): Promise<D>;
+declare function pipe<A, B, C, D, E>(input: A, s1: PipeStep<A, B>, s2: PipeStep<B, C>, s3: PipeStep<C, D>, s4: PipeStep<D, E>): Promise<E>;
+/**
+ * Map an async function over an array with concurrency control.
+ *
+ * @example
+ *   const results = await mapAsync(
+ *     ["a", "b", "c"],
+ *     (item) => agent.run(item),
+ *     { concurrency: 2 }
+ *   );
+ */
+declare function mapAsync<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, options?: {
+    concurrency?: number;
+}): Promise<R[]>;
+/**
+ * Filter items using an async predicate with concurrency control.
+ *
+ * @example
+ *   const valid = await filterAsync(items, async (item) => {
+ *     const result = await agent.run(`Is "${item}" valid?`);
+ *     return result.text.includes("yes");
+ *   });
+ */
+declare function filterAsync<T>(items: T[], predicate: (item: T, index: number) => Promise<boolean>, options?: {
+    concurrency?: number;
+}): Promise<T[]>;
+/**
+ * Reduce items using an async reducer (sequential).
+ *
+ * @example
+ *   const summary = await reduceAsync(
+ *     documents,
+ *     async (acc, doc) => {
+ *       const result = await agent.run(`Combine: ${acc}\n\nNew: ${doc}`);
+ *       return result.text;
+ *     },
+ *     ""
+ *   );
+ */
+declare function reduceAsync<T, R>(items: T[], reducer: (accumulator: R, item: T, index: number) => Promise<R>, initial: R): Promise<R>;
+/**
+ * Execute a side-effect for each item (sequential). Returns input unchanged.
+ * Useful in pipelines for logging or monitoring.
+ *
+ * @example
+ *   await tapAsync(results, async (r) => console.log(r.text));
+ */
+declare function tapAsync<T>(items: T[], fn: (item: T, index: number) => Promise<void> | void): Promise<T[]>;
+/**
+ * Compose multiple middleware-style functions into one.
+ *
+ * @example
+ *   const enhance = compose(
+ *     async (text) => `[System] ${text}`,
+ *     async (text) => text.trim(),
+ *   );
+ *   const result = await enhance("  hello  ");
+ *   // → "[System] hello"
+ */
+declare function compose<T>(...fns: PipeStep<T, T>[]): PipeStep<T, T>;
+
+export { ANTHROPIC_DEFAULT, ANTHROPIC_FAST, ANTHROPIC_PREMIUM, Agent, AgentConfig, AgentResult, AgentSpec, type AgentSpecData, type AgentToolSpec, ApprovalManager, CheckpointStore, CostEstimate, DEEPSEEK_DEFAULT, DEEPSEEK_REASONING, Disposable, type EnterprisePresetOptions, EvalRunner, EvalScorerType, FIREWORKS_DEFAULT, GOOGLE_DEFAULT, GOOGLE_IMAGE, GOOGLE_PREMIUM, Handle, JsMessage, type JsonSchema, MISTRAL_DEFAULT, Message, OPENAI_DEFAULT, OPENAI_FAST, OPENAI_IMAGE, OPENAI_REASONING, OPENROUTER_DEFAULT, PERPLEXITY_DEFAULT, PROVIDER_DEFAULTS, type PipeStep, type PromptTemplate, type RetryConfig, type SkillParam, SkillSpec, type SkillSpecData, type SkillStep, type StructuredConfig, type StructuredResult, TOGETHER_DEFAULT, Telemetry, XAI_DEFAULT, classify, codeReview, compose, countMessageTokens, countTokens, countTokensForModel, createCircuitBreaker, createFallbackProvider, createResilientAgent, createResilientProvider, defaultModel, discoverAgents, enterprisePreset, enterpriseRun, estimateCost, extract, filterAsync, getContextWindowSize, mapAsync, parseAgentConfig, parsePartialJson, pipe, reduceAsync, resolveEnv, retryable, structured, summarize, tapAsync, template, translate, withRetry };