@db3.ai/app 0.1.0-beta.1

package/dist/ai/Ai.d.ts

@@ -0,0 +1,375 @@
+/// <reference path="./sdkNodeCompatibility.d.ts" preserve="true" />
+import { type ModelProvider } from '@openai/agents';
+import { AI_PROVIDER } from './contracts/AI.js';
+import { type AIProviderAttempt } from './AIProviders.js';
+import { AIRateLimiter, type AIProviderResponseMetadata, type AIRateLimitLease } from './AIRateLimiter.js';
+import type { AIAllowanceCheckInput, AIRecordIdentity, AIModels, AIConfig, AIOptions, AIProviderSelection, AIResponseLogOptions, GenerateEmbeddingResult, GenerateImageInput, GenerateImageOptions, GenerateImageResult, GenerateStructuredInput, GenerateTextInput, GenerateTextResult, RequestLogOptions } from './contracts/AI.js';
+/**
+ * Raised when exact provider usage could not be made durable after bounded retries.
+ *
+ * This is deliberately distinct from provider and transport failures so callers
+ * must not issue another paid provider request in response to a database error.
+ */
+export declare class AIUsagePersistenceError extends Error {
+    readonly aiRequestId: string | null;
+    readonly persistenceCause: unknown;
+    /** Indicates that provider execution already occurred and must not be replayed. */
+    readonly providerExecuted = true;
+    /**
+     * Creates a terminal AI usage persistence failure.
+     *
+     * @param aiRequestId - Stable tracked request whose assigned outcome was not saved.
+     * @param persistenceCause - Last database error returned by the bounded save attempts.
+     */
+    constructor(aiRequestId: string | null, persistenceCause: unknown);
+}
+/**
+ * Small application-level wrapper around OpenAI's Responses API.
+ *
+ * The service supports plain text generation, structured Zod-backed generation,
+ * and persistence of conversations, messages, provider payloads, token usage,
+ * and estimated request cost.
+ */
+export declare class Ai {
+    protected readonly options: AIOptions;
+    private readonly modelConfig;
+    /** Configured model constructors for app-owned schema extensions. */
+    readonly models: AIModels;
+    /** Logical ownership field used by this application. */
+    readonly scopeField: string;
+    private readonly rateLimiter;
+    /**
+     * Create an AI service instance.
+     *
+     * Pass options to override environment configuration or to inject a test
+     * fetch implementation.
+     */
+    constructor(options?: AIOptions, modelConfig?: AIConfig);
+    /**
+     * Returns a named model from application config.
+     *
+     * Concrete agents use their class name as the key and keep a colocated
+     * fallback for configurations that omit the named override.
+     *
+     * @param name - Stable model configuration name.
+     * @param fallback - Model to use when the named entry is absent or empty.
+     * @returns Configured named model or the supplied fallback.
+     *
+     * @example
+     * protected readonly model = app().ai.config(
+     * 	'ArticleGenerationAgent',
+     * 	'gpt-5.6-sol',
+     * );
+     */
+    config(name: string, fallback: string): string;
+    /**
+     * Default model used when a call does not provide its own model.
+     *
+     * @returns Injected model override or the application config default.
+     */
+    get model(): string;
+    /**
+     * Whether the service has an API key available.
+     */
+    isConfigured(): boolean;
+    /**
+     * Checks application/customer allowance before a provider call starts.
+     *
+     * The default implementation is a no-op. Apps can inject an allowance hook
+     * through AIOptions to enforce user, team, website, or billing-period limits
+     * without leaking billing concerns into prompt code.
+     *
+     * @param input - Request context used by the allowance policy.
+     */
+    checkAllowance(input: AIAllowanceCheckInput): Promise<void>;
+    /**
+     * Resolves a provider selection into an ordered failover attempt chain.
+     *
+     * Precedence: the explicit selection, then the app-level default from
+     * AIOptions.provider or AI_PROVIDER_CHAIN, then OpenAI alone. The OpenAI
+     * entry uses this service's resolved key, base URL, and model so single
+     * provider behavior is unchanged.
+     *
+     * @param selection - Selection from a call or agent, or null for defaults.
+     * @param model - Model for the OpenAI entry, or null for the app default.
+     * @returns Ordered configured attempts.
+     * @throws AIConfigurationError when no provider in the chain is usable.
+     */
+    resolveProviders(selection?: AIProviderSelection | null, model?: string | null): AIProviderAttempt[];
+    /**
+     * Generate text and return only the assistant's text.
+     *
+     * Requests are tracked by default. Pass `saveAiResponse: false` in options
+     * for one-off calls that should not create conversation, request, or message
+     * rows. Use {@link generateTextWithResponse} when callers need persisted ids.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     */
+    generateText(input: GenerateTextInput, options?: AIResponseLogOptions): Promise<string>;
+    /**
+     * Generate text and return the assistant text plus tracking ids.
+     *
+     * Creates or appends to an AI conversation, stores system/user messages before
+     * sending the provider request, then stores the assistant message, raw response,
+     * usage metrics, and estimated cost after completion unless
+     * `saveAiResponse: false` is provided.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     */
+    generateTextWithResponse(input: GenerateTextInput, options?: AIResponseLogOptions): Promise<GenerateTextResult>;
+    /**
+     * Generate structured JSON that must satisfy the supplied Zod schema.
+     *
+     * The schema is sent to the Responses API as a text format, the raw provider
+     * response is logged, and the returned text is parsed and validated locally
+     * before the typed value is returned.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     * @throws z.ZodError when the provider output does not match the schema.
+     */
+    generateStructured<TValue>(input: GenerateStructuredInput<TValue>, options?: AIResponseLogOptions): Promise<{
+        data: TValue;
+        aiRequestId: string | null;
+        aiResponseId: string | null;
+        conversationId: string | null;
+    }>;
+    /**
+     * Send a Responses API request through the resolved provider chain and
+     * optionally track it in application tables.
+     *
+     * Tracking is intentionally started before the provider call so failed or slow
+     * requests still leave an auditable pending/failed row with the prompt that was
+     * sent. One stable logical AiRequest is retargeted to the provider that settles
+     * the call. Provider-executed intermediate failures are appended as child rows
+     * with their own usage/cost and summarized in `metadata.providerAttempts`.
+     *
+     * Failover moves to the next provider only for failoverable failures such as
+     * rate limits, overload, 5xx, network errors, and exhausted quota. The final
+     * attempt keeps the existing single-provider error contract, including queue
+     * rate-limit deferrals.
+     */
+    private generateTextResult;
+    /**
+     * Points an existing tracked request at the provider attempt now being tried.
+     *
+     * @param tracked - Tracked request created by an earlier attempt.
+     * @param attempt - Provider attempt about to run.
+     * @param request - Provider request payload for this attempt.
+     */
+    private retargetTrackedRequest;
+    /**
+     * Appends one failed provider execution beneath the stable logical request.
+     *
+     * Failover retargets the logical request to the provider that ultimately
+     * settles it. Keeping prior provider executions as children prevents their
+     * returned usage and cost from being overwritten while preserving the public
+     * logical request id used by callers and application records.
+     *
+     * @param tracked - Stable logical request that owns the failover chain.
+     * @param input - Failed provider execution payload, usage, and audit metadata.
+     */
+    private appendTrackedProviderAttempt;
+    /**
+     * Create the conversation, pending request row, and initial system/user
+     * messages for a tracked provider call.
+     */
+    private startTrackedRequest;
+    /**
+     * Marks a tracked text request completed with exact provider usage and cost.
+     *
+     * Assistant-message persistence happens only after this terminal request update
+     * succeeds, allowing the caller to protect completed usage from ancillary errors.
+     *
+     * @param tracked - Tracked logical request state.
+     * @param response - Provider response payload containing terminal usage.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     */
+    private completeTrackedRequest;
+    /**
+     * Mark a tracked request failed with the provider error code, when available.
+     *
+     * @param tracked - Tracked logical request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to persist.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    private failTrackedRequest;
+    /**
+     * Resolve the target conversation for a tracked request.
+     *
+     * Existing conversations can be supplied by record or id; otherwise a new
+     * conversation is created using the provided context.
+     */
+    private resolveConversation;
+    /**
+     * Resolves an optional conversation without creating a new one.
+     *
+     * @param conversation - Optional conversation record or id.
+     * @returns Existing conversation record, or null when omitted.
+     */
+    private resolveOptionalConversation;
+    /**
+     * Return the next message sequence number for a saved conversation.
+     */
+    private nextMessageSequence;
+    /**
+     * Persist one conversation message and return the following sequence number.
+     */
+    private saveMessage;
+    /**
+     * Create a pending request row for an embedding call.
+     */
+    private startTrackedEmbeddingRequest;
+    /**
+     * Mark an embedding request completed with normalized token usage.
+     */
+    private completeTrackedEmbeddingRequest;
+    /**
+     * Mark an embedding request failed and keep a compact provider payload.
+     *
+     * @param tracked - Tracked embedding request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to persist.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    private failTrackedEmbeddingRequest;
+    /**
+     * Create a pending request row for an image generation call.
+     *
+     * @param request - Provider request payload.
+     * @param options - Logging context with a required operation.
+     * @param model - Image model used for the request.
+     * @returns Tracked image request state.
+     */
+    private startTrackedImageRequest;
+    /**
+     * Mark an image request completed with its app-owned storage reference.
+     *
+     * @param tracked - Tracked image request state.
+     * @param storedResponse - Storage path, id, or record returned by the caller.
+     * @param providerResponse - Provider payload used to normalize token usage.
+     * @param metadata - Parsed provider response headers.
+     * @param lease - Active rate-limit lease.
+     */
+    private completeTrackedImageRequest;
+    /**
+     * Mark an image request failed and keep compact provider metadata.
+     *
+     * @param tracked - Tracked image request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to store.
+     * @param metadata - Parsed provider response headers.
+     * @param lease - Active rate-limit lease.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    private failTrackedImageRequest;
+    /**
+     * Best-effort lookup of the authenticated application user.
+     */
+    protected activeUser(): AIRecordIdentity | null;
+    /**
+     * API key from explicit options or OPENAI_API_KEY.
+     */
+    apiKey(): string;
+    /**
+     * Return the configured API key or fail with the public configuration error.
+     */
+    private requireApiKey;
+    /**
+     * Creates an SDK adapter that observes and releases capacity for each HTTP request.
+     *
+     * @param attempt - Resolved provider connection and model.
+     * @param initialLease - Optional preflight reservation consumed by the first request.
+     * @returns SDK provider using the service's transport and rate-limit lifecycle.
+     */
+    createAgentProvider(attempt: AIProviderAttempt, initialLease?: AIRateLimitLease | null): ModelProvider;
+    /**
+     * Reserves each SDK model turn and observes headers before streaming or tool execution.
+     *
+     * The agent's preflight lease covers only its first HTTP request. Releasing it
+     * when headers arrive lets nested tools and concurrent agents use the bucket,
+     * including providers that omit capacity headers. Later turns reserve again.
+     * Transport and persistence failures still release their active reservation.
+     *
+     * @param attempt - Provider and model selected for this SDK attempt.
+     * @param initialLease - First-request reservation, if acquired by the agent.
+     * @returns Transport that maintains provider capacity and request diagnostics.
+     */
+    private agentFetcher;
+    /**
+     * Fetch implementation used by provider calls.
+     */
+    private fetcher;
+    /**
+     * Responses API base URL with trailing slashes removed.
+     */
+    private baseUrl;
+    /**
+     * Full Embeddings API endpoint URL.
+     */
+    private embeddingsUrl;
+    /**
+     * Full Images API generations endpoint URL.
+     */
+    private imagesUrl;
+    /**
+     * Reserves provider capacity when rate limiting is enabled.
+     *
+     * @param input - Endpoint, model, operation, and estimated token cost.
+     * @returns Active rate-limit lease, or null when no limiter is configured.
+     */
+    acquireRateLimit(input: Parameters<AIRateLimiter['acquire']>[0]): Promise<AIRateLimitLease | null>;
+    /**
+     * Applies provider header metadata to the bucket and releases the lease.
+     *
+     * @param lease - Active rate-limit lease.
+     * @param metadata - Parsed provider response headers.
+     */
+    observeRateLimit(lease: AIRateLimitLease | null, metadata: AIProviderResponseMetadata): Promise<void>;
+    /**
+     * Attaches a saved request row to an existing reservation.
+     *
+     * @param lease - Active rate-limit lease.
+     * @param aiRequest - Saved request row to link.
+     */
+    private attachRateLimitRequest;
+    /**
+     * Releases a rate-limit reservation after local failures.
+     *
+     * @param lease - Active rate-limit lease.
+     */
+    releaseRateLimit(lease: AIRateLimitLease | null): Promise<void>;
+    /**
+     * Generate one image and track the provider request by default.
+     *
+     * Callers can provide a storage callback to save the returned image bytes.
+     * The callback result is stored on `AiRequest.response`, which keeps the
+     * audit row pointed at the app-owned file id/path without persisting raw
+     * image bytes in the database.
+     *
+     * @param input - Prompt and image generation settings.
+     * @param options - Optional request context and storage callback.
+     * @returns Generated image bytes, model, tracking id, and storage reference.
+     */
+    generateImage<TStored = unknown>(input: GenerateImageInput, options?: GenerateImageOptions<TStored>): Promise<GenerateImageResult<TStored>>;
+    /**
+     * Generate an embedding vector and track provider usage by default.
+     *
+     * @param input - Text to embed.
+     * @param model - OpenAI embedding model to use.
+     * @param options - Optional AI request logging context.
+     * @returns Embedding vector, model, and saved request id when tracking is enabled.
+     */
+    generateEmbedding(input: string, model?: string, options?: RequestLogOptions): Promise<GenerateEmbeddingResult>;
+}
+export { AIAllowanceExceededError, AIConfigurationError, AIRequestError } from './AIErrors.js';
+export { AI_PROVIDER };
+export type { AIAllowanceChecker, AIAllowanceCheckInput, AIRecordIdentity, AIModels, AIConfig, AIOptions, AIProvider, AIProviderSelection, AIResponseLogOptions, GenerateEmbeddingResult, GenerateImageInput, GenerateImageOptions, GenerateImageResult, GenerateImageStoreInput, GenerateStructuredInput, GenerateTextInput, GenerateTextResult, } from './contracts/AI.js';