# AI text API reference

> Current emitted signatures and options for @db3.ai/app/ai.

- Package: `@db3.ai/app/ai`
- Canonical page: [https://db3.ai/docs/ai-api](https://db3.ai/docs/ai-api)
- Markdown: [https://db3.ai/docs/ai-api.md](https://db3.ai/docs/ai-api.md)
- Framework source of truth: `packages/app/src/ai/README.md`

<a id="start"></a>

## Imports and examples

Import supported APIs from `@db3.ai/app/ai`. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

- [Guide, examples and testing](https://db3.ai/docs/ai.md)

<a id="client"></a>

## Stateless text client

### Stateless text client

```typescript
import type * as ai from './contracts/index.js';
/** Stateless, server-only text generation. No automatic retries or application billing policy. */
export declare class OpenAIText {
    #private;
    /** Creates a client with explicit credentials and bounded, non-retrying requests. */
    constructor(options: ai.OpenAITextOptions);
    /**
     * Runs one bounded text task. Partial, refused and empty responses are not success.
     *
     * @param request - Trusted instructions and untrusted input for this task.
     * @returns Completed text with provider-reported usage.
     * @example
     * const result = await ai.generate({ instructions: 'Summarise this note.', input: note.body, maxOutputTokens: 400 });
     */
    generate(request: ai.TextRequest): Promise<ai.TextResult>;
}
```

<a id="options"></a>

## Server-owned client options

### Server-owned client options

```typescript
/** Server-owned configuration for a stateless OpenAI text client. */
export interface OpenAITextOptions {
    /** Developer-supplied secret. Never expose this option to browser code. */
    apiKey: string;
    /** Explicit Responses-compatible model selected by the application. */
    model: string;
    /** Maximum time for one provider request; defaults to 30 seconds. */
    timeoutMs?: number;
    /** External HTTP transport override, primarily for deterministic provider tests. */
    fetch?: typeof globalThis.fetch;
}
```

<a id="request"></a>

## Bounded request

### Bounded request

```typescript
/** One stateless text task. Applications own authorization and prompt policy. */
export interface TextRequest {
    /** Untrusted source text, separate from the application instruction. */
    input: string;
    /** Trusted application instruction, never derived from user-controlled roles. */
    instructions: string;
    /** Required upper bound on generated tokens, including reasoning tokens. */
    maxOutputTokens: number;
    /** Optional cancellation signal. Cancellation does not guarantee zero provider cost. */
    signal?: AbortSignal;
}
```

<a id="result"></a>

## Completed text and usage

### Completed text and usage

```typescript
/** Completed provider text and measured usage, not a price or billing record. */
export interface TextResult {
    text: string;
    model: string;
    /** Provider response identifier, useful for support without recording the prompt. */
    id: string;
    /** Null when the provider did not return usage; never assume missing means free. */
    usage: {
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
    } | null;
}
```

<a id="errors"></a>

## Safe failure codes

### Safe failure codes

```typescript
/** Safe failure classification. Provider bodies and credentials are deliberately omitted. */
export declare class TextGenerationError extends Error {
    readonly code: 'configuration' | 'invalid_input' | 'cancelled' | 'timeout' | 'rate_limit' | 'provider' | 'incomplete';
    /** Creates a safe application-facing error without retaining provider payloads. */
    constructor(code: 'configuration' | 'invalid_input' | 'cancelled' | 'timeout' | 'rate_limit' | 'provider' | 'incomplete');
}
```

## Related documentation
- [Add a bounded AI text feature](https://db3.ai/docs/ai.md): Start with one useful task: summarise an owned note. Keep the key, permissions and limits on the server.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/ai` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.