agentfootprint/dist/esm/classify/typesafe.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * classify/typesafe — the TypeSafe "System One" adapter (model `jev`).
 *
 * Pattern: adapter over the `Classifier` port (the `AnthropicProvider`
 *          shape: key from the environment, retries, a timeout, errors
 *          wrapped by name). No SDK: one `fetch` against
 *          `POST {baseUrl}/v1/systemone` with a bearer key.
 * Role:    the one shipped classifier that scores. Verified 2026-09-17 by
 *          one real call (docs/design/2026-09-scored-choice.md § Track); the
 *          wire below is that probe's, quoted, not guessed.
 *
 * THE WIRE (request)
 *   { model, state, questions: { [id]: { type: 'choice', instructions, criteria: { option: description } }
 *                               | { type: 'noul', instructions, criteria?: { true, false } }
 *                               | { type: 'score', instructions, criteria: string[] } } }
 * THE WIRE (response)
 *   { model: 'jev-1.13.0',
 *     answers: { [id]: { type: 'choice', choice, confidence, probabilities }
 *                     | { type: 'noul', noul }
 *                     | { type: 'score', score, confidence, probabilities, legend? } },
 *     usage: { input_tokens, output_tokens } }
 * Errors: 401 bad key · 422 validation · 429 rate limit · 529 overloaded.
 * 429 and 529 are retried with exponential backoff up to `maxRetries`; every
 * other status is final on the first reply.
 *
 * LAWS. The response is mapped field for field: `probabilities` is the
 * provider's object as sent (never renormalised, never rounded), `model` is
 * the provider's resolved string, `usage` is renamed to the port's camelCase
 * and dropped when absent. `latencyMs` is measured around the WHOLE call —
 * retries and their waits included — because that is what the judgment cost
 * the run. The key is read once at construction and appears in the
 * `Authorization` header only: never in an error, never in a log.
 */
import { type Classifier } from './types.js';
export interface TypesafeClassifierOptions {
    /** API key. Defaults to the `TYPESAFE_API_KEY` environment variable. */
    readonly apiKey?: string;
    /** The model alias sent on every request. Default `'jev-latest'`. */
    readonly model?: string;
    /** Origin of the API. Default `'https://api.typesafe.ai'`. */
    readonly baseUrl?: string;
    /** Per-attempt timeout in milliseconds. Default 30000. */
    readonly timeout?: number;
    /** Retries on 429 / 529 after the first attempt. Default 2 (three attempts). */
    readonly maxRetries?: number;
    /**
     * The first backoff wait in milliseconds; each retry doubles it. Default
     * 250. A test that stubs `fetch` sets it to 0 so a backoff case is not a
     * slow case.
     */
    readonly retryDelayMs?: number;
}
/**
 * Build the TypeSafe classifier. Throws at construction — not at the first
 * call — when no key is in reach, naming the variable, so a misconfigured
 * agent fails at build rather than filing an error row per tool result.
 */
export declare function typesafe(options?: TypesafeClassifierOptions): Classifier;