gauss-ts 1.1.0

package/dist/agent-CHrSUkPz.d.ts

@@ -0,0 +1,485 @@
+import { H as Handle, T as ToolDef, M as Message, A as AgentOptions, a as ToolExecutor, b as AgentResult, D as Disposable, P as ProviderType, c as ProviderOptions, C as CodeExecutionOptions, d as ProviderCapabilities, S as StreamCallback } from './types-BkwC4s1P.js';
+
+/**
+ * A single event emitted during agent streaming.
+ *
+ * @description Represents a parsed streaming event such as a text delta, tool call,
+ * or other provider-specific event. The `type` field discriminates the event kind.
+ *
+ * @example
+ * ```ts
+ * const event: StreamEvent = { type: "text_delta", text: "Hello" };
+ * if (event.type === "text_delta") process.stdout.write(event.text ?? "");
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface StreamEvent {
+    /** The event type discriminator (e.g. `"text_delta"`, `"tool_call"`, `"raw"`). */
+    type: string;
+    /** Text content for text-delta events. */
+    text?: string;
+    /** Tool call payload for tool-call events. */
+    toolCall?: {
+        name: string;
+        arguments: string;
+    };
+    /** Additional provider-specific fields. */
+    [key: string]: unknown;
+}
+/**
+ * Async iterable wrapper over the native agent streaming callback.
+ *
+ * @description Bridges the native callback-based streaming API into an `AsyncIterable<StreamEvent>`.
+ * Use with `for await ... of` to consume events as they arrive. After iteration completes,
+ * the final {@link AgentResult} is available via the {@link AgentStream.result} getter.
+ *
+ * @example
+ * ```ts
+ * const stream = agent.streamIter("Tell me a story");
+ * for await (const event of stream) {
+ *   if (event.type === "text_delta") process.stdout.write(event.text ?? "");
+ * }
+ * console.log(stream.result?.text);
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare class AgentStream implements AsyncIterable<StreamEvent> {
+    private readonly agentName;
+    private readonly providerHandle;
+    private readonly tools;
+    private readonly messages;
+    private readonly options;
+    private readonly toolExecutor;
+    private _result;
+    /**
+     * Create a new `AgentStream`.
+     *
+     * @description Typically not called directly — use {@link Agent.streamIter} instead.
+     *
+     * @param agentName - Name of the agent for logging/identification.
+     * @param providerHandle - Native provider handle.
+     * @param tools - Tool definitions available during the stream.
+     * @param messages - Conversation messages to send.
+     * @param options - Agent options for the agentic loop.
+     * @param toolExecutor - Async callback for executing tool calls.
+     *
+     * @since 1.0.0
+     */
+    constructor(agentName: string, providerHandle: Handle, tools: ToolDef[], messages: Message[], options: AgentOptions, toolExecutor: ToolExecutor);
+    /**
+     * The final aggregated result, available after async iteration completes.
+     *
+     * @description Returns `undefined` while iteration is still in progress. Once the
+     * `for await` loop finishes, this contains the full {@link AgentResult} with response
+     * text, token counts, and other metadata.
+     *
+     * @returns The completed {@link AgentResult} or `undefined` if iteration hasn't finished.
+     *
+     * @example
+     * ```ts
+     * const stream = agent.streamIter("Hello");
+     * for await (const event of stream) { /* consume events *\/ }
+     * console.log(stream.result?.text);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    get result(): AgentResult | undefined;
+    /**
+     * Async iterator implementation — yields {@link StreamEvent} objects as they arrive.
+     *
+     * @description Starts the native streaming call and yields parsed events. The iterator
+     * completes when the underlying stream finishes and all buffered events have been yielded.
+     *
+     * @returns An async iterator of {@link StreamEvent} objects.
+     *
+     * @since 1.0.0
+     */
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+}
+
+/**
+ * Configuration object for creating an {@link Agent} instance.
+ *
+ * @description All fields are optional — sensible defaults are applied and the provider is auto-detected from environment variables when omitted.
+ *
+ * @example
+ * ```ts
+ * const config: AgentConfig = {
+ *   provider: "anthropic",
+ *   model: "claude-sonnet-4-20250514",
+ *   instructions: "You are a helpful assistant.",
+ *   temperature: 0.7,
+ * };
+ * const agent = new Agent(config);
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface AgentConfig {
+    /** Agent name (default: `"agent"`). Used for logging and identification. */
+    name?: string;
+    /** LLM provider. Auto-detected from env if omitted. */
+    provider?: ProviderType;
+    /** Model identifier (e.g. `"gpt-4o"`, `"claude-sonnet-4-20250514"`). Auto-selected if omitted. */
+    model?: string;
+    /** Provider connection options. API key auto-resolved from env if omitted. */
+    providerOptions?: ProviderOptions;
+    /** System instructions prepended to every conversation. */
+    instructions?: string;
+    /** Tool definitions available to the agent. */
+    tools?: ToolDef[];
+    /** Sampling temperature (0–2). Higher values produce more creative output. */
+    temperature?: number;
+    /** Maximum number of agentic loop iterations before stopping. */
+    maxSteps?: number;
+    /** Top-p (nucleus) sampling threshold. */
+    topP?: number;
+    /** Maximum number of output tokens per response. */
+    maxTokens?: number;
+    /** Deterministic seed for reproducible outputs. */
+    seed?: number;
+    /** Stop the agentic loop when this tool name is called. */
+    stopOnTool?: string;
+    /** JSON schema for structured output. The model will conform its response to this schema. */
+    outputSchema?: Record<string, unknown>;
+    /** Extended thinking budget (Anthropic). Number of tokens for internal reasoning. */
+    thinkingBudget?: number;
+    /** Reasoning effort for OpenAI o-series models. Controls how much reasoning to use. */
+    reasoningEffort?: "low" | "medium" | "high";
+    /** Enable prompt caching (Anthropic). Auto-annotates system messages and tools. */
+    cacheControl?: boolean;
+    /** Enable code execution runtimes. Pass `true` for all defaults, or configure individually. */
+    codeExecution?: boolean | CodeExecutionOptions;
+    /** Enable Google Search grounding (Gemini only). */
+    grounding?: boolean;
+    /** Enable native code execution / Gemini code interpreter. */
+    nativeCodeExecution?: boolean;
+    /** Response modalities (e.g. `["TEXT", "IMAGE"]` for Gemini image generation). */
+    responseModalities?: string[];
+}
+/**
+ * Core agent class that wraps a native LLM provider and manages the agentic loop.
+ *
+ * @description `Agent` is the primary entry-point for interacting with language models in Gauss.
+ * It supports single-shot completions, multi-step tool-use loops, streaming, and raw generation.
+ * Each instance owns a native provider handle that **must** be released via {@link Agent.destroy}
+ * (or the `using` pattern) to avoid resource leaks.
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({
+ *   provider: "openai",
+ *   model: "gpt-4o",
+ *   instructions: "You are a helpful assistant.",
+ * });
+ * const result = await agent.run("What is the meaning of life?");
+ * console.log(result.text);
+ * agent.destroy();
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare class Agent implements Disposable {
+    private readonly providerHandle;
+    private readonly _name;
+    private readonly _provider;
+    private readonly _model;
+    private readonly _instructions;
+    private _tools;
+    private _options;
+    private disposed;
+    /**
+     * Create a new Agent.
+     *
+     * @description Initialises the native provider connection and configures the agentic
+     * loop options. The provider and model are auto-detected from environment variables
+     * when not explicitly set.
+     *
+     * @param config - Agent configuration. All fields are optional.
+     * @throws {Error} If the native provider cannot be created (e.g. invalid API key).
+     *
+     * @example
+     * ```ts
+     * const agent = new Agent({ instructions: "Be concise." });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    constructor(config?: AgentConfig);
+    /**
+     * @description The agent's name.
+     * @since 1.0.0
+     */
+    get name(): string;
+    /**
+     * @description The resolved LLM provider type.
+     * @since 1.0.0
+     */
+    get provider(): ProviderType;
+    /**
+     * @description The resolved model identifier.
+     * @since 1.0.0
+     */
+    get model(): string;
+    /**
+     * @description The system instructions string.
+     * @since 1.0.0
+     */
+    get instructions(): string;
+    /**
+     * @description Native provider handle. Used internally by Network, Graph, and other subsystems.
+     * @since 1.0.0
+     * @internal
+     */
+    get handle(): Handle;
+    /**
+     * @description Query what features this provider/model combination supports.
+     * @returns The capability flags for the current provider and model.
+     * @since 1.0.0
+     */
+    get capabilities(): ProviderCapabilities;
+    /**
+     * Register a single tool definition. Chainable.
+     *
+     * @description Appends a tool to the agent's tool list so the LLM can invoke it during the agentic loop.
+     *
+     * @param tool - The tool definition to add.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * agent.addTool({ name: "search", description: "Web search", parameters: { query: { type: "string" } } });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    addTool(tool: ToolDef): this;
+    /**
+     * Register multiple tool definitions at once. Chainable.
+     *
+     * @description Appends all provided tools to the agent's tool list.
+     *
+     * @param tools - Array of tool definitions to add.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * agent.addTools([
+     *   { name: "search", description: "Web search", parameters: { query: { type: "string" } } },
+     *   { name: "calculate", description: "Math calculator", parameters: { expr: { type: "string" } } },
+     * ]);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    addTools(tools: ToolDef[]): this;
+    /**
+     * Merge additional agent options into the current configuration. Chainable.
+     *
+     * @description Shallow-merges the provided options with the existing ones. Later calls override earlier values.
+     *
+     * @param options - Partial agent options to merge.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * agent.setOptions({ temperature: 0.5, maxTokens: 1024 });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    setOptions(options: Partial<AgentOptions>): this;
+    /**
+     * Run the agentic loop to completion.
+     *
+     * @description Sends the input through the full agentic loop (tool calls, multi-step reasoning)
+     * and returns the final result. Accepts either a plain string prompt or a pre-built message array.
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @returns The completed {@link AgentResult} containing the response text, token counts, and optional structured output.
+     * @throws {Error} If the agent has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const result = await agent.run("Explain quantum computing");
+     * console.log(result.text);
+     * console.log(`Tokens: ${result.inputTokens} in / ${result.outputTokens} out`);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    run(input: string | Message[]): Promise<AgentResult>;
+    /**
+     * Run the agentic loop with a JavaScript-side tool executor.
+     *
+     * @description Like {@link Agent.run}, but delegates tool invocations to the provided
+     * `toolExecutor` callback. Use this when tools need access to the Node.js runtime
+     * (file system, network, databases, etc.).
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @param toolExecutor - Async callback that receives a JSON-encoded tool call and returns a JSON-encoded result.
+     * @returns The completed {@link AgentResult}.
+     * @throws {Error} If the agent has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const result = await agent.runWithTools("Search for cats", async (callJson) => {
+     *   const call = JSON.parse(callJson);
+     *   return JSON.stringify({ results: ["cat1", "cat2"] });
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    runWithTools(input: string | Message[], toolExecutor: ToolExecutor): Promise<AgentResult>;
+    /**
+     * Stream agent responses with real-time events via a callback.
+     *
+     * @description Runs the agentic loop while invoking `onEvent` for each streaming event
+     * (text deltas, tool calls, etc.). Returns the final aggregated result after the stream ends.
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @param onEvent - Callback invoked with each JSON-encoded stream event.
+     * @param toolExecutor - Optional async callback for handling tool invocations.
+     * @returns The completed {@link AgentResult}.
+     * @throws {Error} If the agent has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const result = await agent.stream("Tell me a joke", (eventJson) => {
+     *   const event = JSON.parse(eventJson);
+     *   if (event.type === "text_delta") process.stdout.write(event.text ?? "");
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    stream(input: string | Message[], onEvent: StreamCallback, toolExecutor?: ToolExecutor): Promise<AgentResult>;
+    /**
+     * Stream as an async iterable — use with `for await`.
+     *
+     * @description Returns an {@link AgentStream} that yields {@link StreamEvent} objects.
+     * After iteration completes, the final {@link AgentResult} is available via
+     * `stream.result`.
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @param toolExecutor - Optional async callback for handling tool invocations.
+     * @returns An {@link AgentStream} async iterable of {@link StreamEvent} objects.
+     * @throws {Error} If the agent has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const stream = agent.streamIter("Tell me a story");
+     * for await (const event of stream) {
+     *   if (event.type === "text_delta") process.stdout.write(event.text ?? "");
+     * }
+     * console.log(stream.result?.text);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    streamIter(input: string | Message[], toolExecutor?: ToolExecutor): AgentStream;
+    /**
+     * Perform a single raw LLM call without the agentic loop.
+     *
+     * @description Bypasses the multi-step agent loop and sends the input directly to the model
+     * for a one-shot completion. Useful when you need a simple generation without tool use.
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @param options - Optional generation parameters.
+     * @param options.temperature - Sampling temperature override.
+     * @param options.maxTokens - Maximum output tokens override.
+     * @returns The raw provider response.
+     *
+     * @example
+     * ```ts
+     * const response = await agent.generate("Translate 'hello' to French", { temperature: 0 });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    generate(input: string | Message[], options?: {
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<unknown>;
+    /**
+     * Perform a single raw LLM call with tool definitions (no agentic loop).
+     *
+     * @description Like {@link Agent.generate}, but also passes tool definitions to the model.
+     * The model may return tool-call requests in its response, but the caller is responsible
+     * for executing them — no automatic loop is performed.
+     *
+     * @param input - A string prompt or an array of {@link Message} objects.
+     * @param tools - Tool definitions to make available to the model.
+     * @param options - Optional generation parameters.
+     * @param options.temperature - Sampling temperature override.
+     * @param options.maxTokens - Maximum output tokens override.
+     * @returns The raw provider response, potentially containing tool call requests.
+     *
+     * @example
+     * ```ts
+     * const response = await agent.generateWithTools(
+     *   "What's the weather?",
+     *   [{ name: "get_weather", description: "Get weather", parameters: { city: { type: "string" } } }],
+     * );
+     * ```
+     *
+     * @since 1.0.0
+     */
+    generateWithTools(input: string | Message[], tools: ToolDef[], options?: {
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<unknown>;
+    /**
+     * Release all native resources held by this agent.
+     *
+     * @description Destroys the underlying native provider handle. Safe to call multiple times;
+     * subsequent calls are no-ops. After calling `destroy()`, any further method calls on this
+     * agent will throw.
+     *
+     * @since 1.0.0
+     */
+    destroy(): void;
+    /**
+     * Alias for {@link Agent.destroy} — enables the TC39 `using` pattern.
+     *
+     * @example
+     * ```ts
+     * {
+     *   using agent = new Agent({ instructions: "Be helpful." });
+     *   const result = await agent.run("Hi!");
+     * } // agent is automatically destroyed here
+     * ```
+     *
+     * @since 1.0.0
+     */
+    [Symbol.dispose](): void;
+    private assertNotDisposed;
+}
+/**
+ * One-liner convenience function — create an agent, run a prompt, and return the text.
+ *
+ * @description Creates a temporary {@link Agent}, sends the prompt through the agentic loop,
+ * and returns just the response text. The agent is automatically destroyed after the call.
+ * Ideal for quick, single-turn interactions.
+ *
+ * @param prompt - The user prompt to send to the agent.
+ * @param config - Optional agent configuration (everything except `name`).
+ * @returns The agent's response text.
+ * @throws {Error} If the provider cannot be initialised or the call fails.
+ *
+ * @example
+ * ```ts
+ * import { gauss } from "gauss-ts";
+ * const answer = await gauss("What is the meaning of life?");
+ * console.log(answer);
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function gauss(prompt: string, config?: Omit<AgentConfig, "name">): Promise<string>;
+
+export { type AgentConfig as A, type StreamEvent as S, Agent as a, AgentStream as b, gauss as g };