import { Agent } from "./agent/index.js"; import type { AgentConfig, SchemaLike } from "./agent/types.js"; import { ArtifactsClient } from "./clients/artifacts.js"; import { EmbeddingsClient } from "./clients/embeddings.js"; import { FunctionsClient } from "./clients/functions.js"; import { GenerationsClient } from "./clients/generations.js"; import { KnowledgeClient } from "./clients/knowledge.js"; import { ModelsClient } from "./clients/models.js"; import { RealtimeClient } from "./clients/realtime.js"; import { SpansClient } from "./clients/spans.js"; import { SystemClient } from "./clients/system.js"; import { TracesClient } from "./clients/traces.js"; import { WebToolsClient } from "./clients/web-tools.js"; import type { GeneratedImage, GeneratedSpeech, GeneratedVideo, GenerateImageOptions, GenerateVideoOptions, MediaResponse, SpeechToTextOptions, TextToSpeechOptions, Transcription } from "./media.js"; import type { InferOutput, StandardSchemaV1 } from "./schema.js"; import type { ClientConfig, RequestOptions, RunRequest, RunResponse, SchemaRunRequest, SpanHandle, StreamChunk, TracedOptions } from "./types.js"; /** * Unified client for the Opper API. * * @param config - Optional configuration object: * - `apiKey` — API key (falls back to `OPPER_API_KEY` env var) * - `baseUrl` — API host URL (falls back to `OPPER_BASE_URL` env var, default: `https://api.opper.ai`). Do not include `/v3` — it is added automatically. * - `headers` — Additional headers to include in every request * * @example * ```typescript * // Uses OPPER_API_KEY env var * const client = new Opper(); * * // Explicit config * const client = new Opper({ apiKey: 'op-...', baseUrl: 'https://api.opper.ai' }); * ``` */ export declare class Opper { /** Client for function management and execution. */ readonly functions: FunctionsClient; /** Client for trace spans. */ readonly spans: SpansClient; /** Client for recorded generations. */ readonly generations: GenerationsClient; /** Client for listing available models. */ readonly models: ModelsClient; /** Client for OpenAI-compatible embeddings. */ readonly embeddings: EmbeddingsClient; /** Client for system health checks. */ readonly system: SystemClient; /** Client for trace operations. */ readonly traces: TracesClient; /** Client for async artifact status polling. */ readonly artifacts: ArtifactsClient; /** Beta API endpoints — these may change. */ readonly beta: { readonly web: WebToolsClient; }; /** Client for knowledge base operations (v2 API). */ readonly knowledge: KnowledgeClient; /** Client for the realtime WebSocket endpoint (`/v3/realtime`). */ readonly realtime: RealtimeClient; private readonly resolvedConfig; constructor(config?: ClientConfig); /** * Call a function by name and return the result. * * `output_schema` accepts either a Standard Schema (Zod, Valibot, etc.) or raw JSON Schema. * When a Standard Schema is provided, the response type is inferred automatically. * * @example * ```typescript * // With Zod schema (inferred output type) * import { z } from "zod"; * const result = await opper.call("summarize", { * output_schema: z.object({ summary: z.string() }), * input: { text: "Long article..." }, * }); * result.data.summary; // string — inferred! * * // With raw JSON Schema (manual generic) * const result = await opper.call<{ summary: string }>("summarize", { * output_schema: { type: "object", properties: { summary: { type: "string" } } }, * input: { text: "Long article..." }, * }); * ``` */ call(name: string, request: Omit & { output_schema: S; }, options?: RequestOptions): Promise>>; call(name: string, request: RunRequest, options?: RequestOptions): Promise>; /** * Stream a function execution by name, yielding chunks as they arrive. * * `output_schema` accepts either a Standard Schema (Zod, Valibot, etc.) or raw JSON Schema. * * @example * ```typescript * for await (const chunk of opper.stream("summarize", { ... })) { * if (chunk.type === "content") process.stdout.write(chunk.delta); * if (chunk.type === "done") console.log(chunk.usage); * } * ``` */ stream(name: string, request: Omit & { output_schema: S; }, options?: RequestOptions): AsyncGenerator>, void, undefined>; stream(name: string, request: RunRequest, options?: RequestOptions): AsyncGenerator, void, undefined>; /** * Wrap a block of code in a trace span. All `call()` and `stream()` calls * inside the callback automatically inherit the span as their parent. * * Supports three call signatures: * - `traced(fn)` — uses default name `"traced"` * - `traced("my-span", fn)` — uses the given name * - `traced({ name, input, meta, tags }, fn)` — full options * * The callback receives a {@link SpanHandle} for accessing the span/trace IDs * or passing them explicitly. Nesting is supported — inner `traced()` calls * create child spans of the outer one. * * @example * ```typescript * // Automatic context — no manual wiring * const result = await opper.traced("my-flow", async () => { * const r1 = await opper.call("step1", { input: "hello" }); * const r2 = await opper.call("step2", { input: r1.data }); * return r2; * }); * * // Explicit span handle for metadata * await opper.traced("my-flow", async (span) => { * console.log("trace:", span.traceId, "span:", span.id); * await opper.call("step1", { input: "hello" }); * }); * ``` */ traced(fn: (span: SpanHandle) => Promise): Promise; traced(name: string, fn: (span: SpanHandle) => Promise): Promise; traced(options: TracedOptions, fn: (span: SpanHandle) => Promise): Promise; /** * Generate an image from a text prompt. * * @example * ```typescript * // Generate from scratch * const result = await opper.generateImage({ prompt: "A sunset over a calm ocean" }); * writeFileSync("sunset.png", Buffer.from(result.data.image, "base64")); * * // With a reference image * const result = await opper.generateImage("edit-photo", { * prompt: "Add sunglasses and a party hat", * reference_image: { path: "./cat.png" }, * }); * * // With explicit function name and options * const result = await opper.generateImage("hero-image", { * prompt: "Product photo on white background", * model: "openai/dall-e-3", * size: "1792x1024", * quality: "hd", * }); * ``` */ generateImage(options: GenerateImageOptions, requestOptions?: RequestOptions): Promise>; generateImage(name: string, options: GenerateImageOptions, requestOptions?: RequestOptions): Promise>; /** * Generate a video from a text prompt. * * @example * ```typescript * const result = await opper.generateVideo({ * prompt: "A cat walking down a city street, cinematic", * model: "openai/sora-2", * aspect_ratio: "16:9", * }); * result.save("./cat"); // → "./cat.mp4" * ``` */ generateVideo(options: GenerateVideoOptions, requestOptions?: RequestOptions): Promise>; generateVideo(name: string, options: GenerateVideoOptions, requestOptions?: RequestOptions): Promise>; /** * Convert text to speech audio. * * @example * ```typescript * const result = await opper.textToSpeech({ * text: "Hello! Welcome to our platform.", * voice: "alloy", * }); * result.save("./welcome.mp3"); * ``` */ textToSpeech(options: TextToSpeechOptions, requestOptions?: RequestOptions): Promise>; textToSpeech(name: string, options: TextToSpeechOptions, requestOptions?: RequestOptions): Promise>; /** * Transcribe audio to text. * * @example * ```typescript * const result = await opper.transcribe({ * audio: { path: "./meeting.mp3" }, * language: "en", * }); * console.log(result.data.text, result.data.language); * ``` */ transcribe(options: SpeechToTextOptions, requestOptions?: RequestOptions): Promise>; transcribe(name: string, options: SpeechToTextOptions, requestOptions?: RequestOptions): Promise>; /** * Create an Agent with the client config from this Opper instance. * * The agent inherits the API key and base URL. Tracing is enabled by * default — agent runs, LLM calls, and tool executions appear as a * structured trace tree in the Opper dashboard. * * @example * ```typescript * const opper = new Opper(); * const agent = opper.agent({ * name: 'assistant', * instructions: 'Be helpful.', * tools: [myTool], * }); * const result = await agent.run('Hello!'); * // → trace visible in Opper dashboard * ``` */ agent(config: Omit, "client">): Agent; /** Resolve any Standard Schema fields (output_schema, input_schema, tools) to plain JSON Schema. */ private resolveRequest; private resolveMedia; } export { BaseClient } from "./client-base.js"; export { EmbeddingsClient } from "./clients/embeddings.js"; export { FunctionsClient } from "./clients/functions.js"; export { GenerationsClient } from "./clients/generations.js"; export { KnowledgeClient } from "./clients/knowledge.js"; export type { ListModelsParams } from "./clients/models.js"; export { ModelsClient } from "./clients/models.js"; export { SpansClient } from "./clients/spans.js"; export { SystemClient } from "./clients/system.js"; export { TracesClient } from "./clients/traces.js"; export { WebToolsClient } from "./clients/web-tools.js"; export type { Example, ListExamplesParams, } from "./clients/functions.js"; export type { DeleteGenerationResponse, Generation, GenerationsListMeta, GenerationsListResponse, ListGenerationsParams as GenerationsListParams, } from "./clients/generations.js"; export { RealtimeClient } from "./clients/realtime.js"; export type { HealthCheckResponse } from "./clients/system.js"; export type { InferOutput, StandardSchemaV1 } from "./schema.js"; export { isStandardSchema, jsonSchema } from "./schema.js"; export type { TraceContext } from "./context.js"; export { getTraceContext } from "./context.js"; export type { AddDocumentRequest, AddDocumentResponse, ArtifactStatus, ClientConfig, CompleteChunk, ContentChunk, CreateKnowledgeBaseRequest, CreateKnowledgeBaseResponse, CreateRealtimeSessionRequest, CreateSpanRequest, CreateSpanResponse, DeleteDocumentsRequest, DeleteDocumentsResponse, DocumentSegment, DoneChunk, EmbeddingsDataItem, EmbeddingsRequest, EmbeddingsResponse, EmbeddingsUsageInfo, ErrorChunk, ErrorDetail, ErrorResponse, FilterOp, FunctionDetails, FunctionInfo, FunctionRevision, GetDocumentResponse, GetKnowledgeBaseResponse, GetSpanResponse, GetTraceResponse, GetUploadUrlResponse, JsonSchema, JsonValue, KnowledgeBaseFilter, KnowledgeBaseInfo, ListFilesResponse, ListGenerationsParams, ListTracesItem, ListTracesParams, ListTracesResponse, Model, ModelConfig, ModelInfo, PaginatedResponse, PendingOperation, QueryKnowledgeBaseRequest, QueryKnowledgeBaseResponse, RealtimeSession, RealtimeSessionConfig, RealtimeTool, RealtimeTurnDetection, RegisterFileUploadRequest, RegisterFileUploadResponse, RequestOptions, ResponseMeta, RevisionInfo, RunRequest, RunResponse, SchemaLike, SchemaRunRequest, SpanHandle, StreamChunk, TextProcessingConfiguration, Tool, ToolCallDeltaChunk, ToolCallStartChunk, TracedOptions, TraceSpan, UpdateFunctionRequest, UpdateSpanRequest, UploadFileResponse, UsageInfo, WebFetchRequest, WebFetchResponse, WebSearchRequest, WebSearchResponse, WebSearchResult, } from "./types.js"; export { ApiError, AuthenticationError, BadRequestError, InternalServerError, NotFoundError, RateLimitError, } from "./types.js"; export type { GeneratedImage, GeneratedSpeech, GeneratedVideo, GenerateImageOptions, GenerateVideoOptions, MediaBaseOptions, MediaInput, MediaResponse, SpeechToTextOptions, TextToSpeechOptions, Transcription, } from "./media.js"; export { saveMedia } from "./media.js"; export type { AgentConfig, AgentStreamEvent, AgentTool, AggregatedUsage, Hooks, InferAgentOutput, MCPServerConfig, MCPSSEConfig, MCPStdioConfig, MCPStreamableHTTPConfig, ORInputItem, ORRequest, ORResponse, RunMeta, RunOptions, RunResult, ToolConfig, ToolProvider, } from "./agent/index.js"; export { AbortError, Agent, AgentError, AgentStream, Conversation, createToolTracingHooks, MaxIterationsError, MCPToolProvider, mcp, mergeHooks, tool, } from "./agent/index.js";