import { type Schema as JTDSchemaJson } from '../jtd/index.js';
import type { SignalDescriptorJson } from '../proto/index.js';
import { type ConvertFailure, type ConvertSuccess, type ConvertSuccessBinary, type ConvertSuccessJson, type ConvertSuccessSignals } from '../schema-utils.js';
/**
 * JSON Schema subset accepted by the OpenAI structured-output API (strict mode).
 *
 * This is the provider-specific representation produced by {@link OpenAIConversion}.
 * It covers the keywords that OpenAI inspects when constraining model output in
 * strict mode: `type`, `properties`, `required`, `additionalProperties`, `enum`,
 * `format`, `items`, `minimum`/`maximum`, `anyOf`, `$defs`, `$ref`, and
 * `description`.
 */
export interface OpenAISchema {
    type?: string | string[];
    description?: string;
    properties?: Record<string, OpenAISchema>;
    required?: string[];
    additionalProperties?: false;
    enum?: (string | number | null)[];
    format?: string;
    items?: OpenAISchema;
    minimum?: number;
    maximum?: number;
    anyOf?: OpenAISchema[];
    $defs?: Record<string, OpenAISchema>;
    $ref?: string;
}
export type { ConvertFailure, ConvertResult, ConvertSuccess, ConvertSuccessBinary, ConvertSuccessJson, ConvertSuccessSignals } from '../schema-utils.js';
/**
 * Converts JTD schemas or Adapt signal descriptors into OpenAI-compatible
 * JSON Schema (strict mode), and converts raw LLM output back into
 * validated data.
 *
 * ### JTD form mapping
 * - **type** -- mapped to the corresponding JSON Schema `type` (`string`,
 *   `number`, `integer`, `boolean`). Integer sub-types (int8 .. uint32) add
 *   `minimum`/`maximum` bounds. `timestamp` becomes `string` with
 *   `format: "date-time"`.
 * - **enum** -- mapped to `type: "string"` with an `enum` array.
 * - **elements** -- mapped to `type: "array"` with `items`.
 * - **properties / optionalProperties** -- mapped to `type: "object"` with
 *   `properties`, `required`, and `additionalProperties: false`. OpenAI
 *   strict mode requires all properties to be present, so **optional
 *   properties are made required and nullable** (their schemas are wrapped
 *   with a `"null"` type variant). During {@link convert}, null values for
 *   optional properties are stripped back out.
 * - **values** -- mapped to an array of `{key, value}` objects because
 *   OpenAI strict mode does not support `additionalProperties`. During
 *   {@link convert}, the array is coerced back into a plain `Record`.
 * - **discriminator** -- mapped to `anyOf` with one variant per mapping
 *   entry. Each variant is a flat object containing the discriminator key
 *   (with a single-value `enum`) plus the variant's own properties.
 *
 * ### Unstructured schemas
 * Empty JTD schemas or schemas with only `additionalProperties: true` are
 * considered unstructured. They produce an empty `{}` JSON Schema with
 * `strict: false`, and during {@link convert} the raw string output is
 * parsed via `JSON.parse` back into an arbitrary value.
 *
 * ### MIME formats
 * MIME signal formats become `type: "string"` with a description requesting
 * base64-encoded content. On {@link convert}, the base64 string is decoded
 * into a {@link ConvertSuccessBinary} result.
 *
 * ### Serialization
 * `JSON.stringify(conv)` produces a JSON-safe object via {@link toJSON}.
 * Use {@link fromJSON} to restore a fully functional instance from the
 * serialized form (string or parsed object).
 *
 * ```ts
 * const conv = OpenAIConversion.fromJTD(jtdSchema);
 * conv.schema;           // OpenAI JSON Schema to pass to the LLM
 * conv.strict;           // whether strict mode applies
 * conv.convert(output);  // coerce + validate -> ConvertResult
 *
 * // Serialize & restore
 * const cached = JSON.stringify(conv);
 * const restored = OpenAIConversion.fromJSON(cached);
 * ```
 */
export declare class OpenAIConversion<T extends ConvertSuccess = ConvertSuccess> {
    /** The OpenAI-specific JSON Schema to pass to the OpenAI API as the response format. */
    readonly schema: OpenAISchema;
    /**
     * Whether the schema qualifies for OpenAI strict structured-output mode.
     *
     * This is `false` when the root JTD schema is empty or unstructured (e.g.
     * the empty schema `{}` or a properties form with no real properties and
     * `additionalProperties: true`). In that case `schema` is `{}` and the
     * model output is unconstrained.
     */
    readonly strict: boolean;
    /**
     * The original JTD schema used to build this conversion.
     * Set when created via {@link fromJTD}; `undefined` when created via {@link fromSignal}.
     */
    readonly jtdSchema?: JTDSchemaJson;
    /**
     * The original signal descriptor used to build this conversion.
     * Set when created via {@link fromSignal}; `undefined` when created via {@link fromJTD}.
     */
    readonly descriptor?: SignalDescriptorJson;
    /**
     * The original signal descriptors used to build this conversion.
     * Set when created via {@link fromSignals}; `undefined` otherwise.
     */
    readonly descriptors?: SignalDescriptorJson[];
    /**
     * When true, MIME-format signals expect blob reference strings instead of
     * base64-encoded data objects. Mixed signals (JTD + MIME) use a discriminated
     * anyOf with `kind: "value" | "reference"`.
     */
    readonly referenceMode: boolean;
    /**
     * Build a conversion from a JTD schema.
     *
     * Recursively converts every JTD form into the equivalent OpenAI JSON Schema
     * node. Definitions (`jtdSchema.definitions`) are emitted as `$defs` at the
     * root level, and references become `$ref` pointers.
     *
     * If the root schema is unstructured, the result has an empty `schema` and
     * `strict: false`.
     *
     * @param jtdSchema - A valid JTD schema (RFC 8927).
     * @returns A new {@link OpenAIConversion} with `jtdSchema` set.
     * @throws If the schema contains an unknown JTD type, an unresolved `ref`,
     *         or nesting exceeding 32 levels.
     */
    static fromJTD(input: unknown): OpenAIConversion<ConvertSuccessJson>;
    /**
     * Build a conversion from an Adapt signal descriptor.
     *
     * If the descriptor has a single format, its schema is used directly
     * (unwrapped). If it has multiple formats, a wrapper object schema is
     * produced with `format_0`, `format_1`, ... properties -- each made
     * required and nullable so the LLM populates exactly one and sets the
     * rest to `null`.
     *
     * @param descriptor - An Adapt signal descriptor with one or more formats.
     * @returns A new {@link OpenAIConversion} with `descriptor` set.
     * @throws If the descriptor has no formats, or a format has neither
     *         `jtdSchema` nor `mimeType`.
     */
    static fromSignal(descriptor: SignalDescriptorJson, sharedDefs?: Record<string, JTDSchemaJson>, referenceMode?: boolean): OpenAIConversion<ConvertSuccessJson | ConvertSuccessBinary>;
    /**
     * Build a conversion from multiple signal descriptors.
     *
     * Produces an object schema with one property per signal, suitable for
     * use as structured output parameters. Each signal's schema is built via
     * {@link fromSignal} internally.
     *
     * For OpenAI strict mode, optional signals are made nullable and all
     * properties are added to `required`.
     *
     * If there is only one signal with a single format, the schema is
     * unwrapped to avoid unnecessary nesting — the signal's format schema
     * is used directly as the object property value.
     *
     * Receiver/transceiver compatible:
     * ```ts
     * const conv = OpenAIConversion.fromSignals(
     *   receiver.signals!,
     *   receiver.description,
     *   receiver.name
     * );
     * ```
     *
     * @param signals - Array of signal descriptors.
     * @param description - Optional description for the compound schema.
     * @param label - Optional label (not used by OpenAI, reserved for other providers).
     * @returns A new {@link OpenAIConversion} with `descriptors` set.
     * @throws If any signal has no formats or an invalid format.
     */
    static fromSignals(signals: SignalDescriptorJson[], description?: string, label?: string, referenceMode?: boolean): OpenAIConversion<ConvertSuccessSignals>;
    /**
     * Restore an {@link OpenAIConversion} from its serialized form.
     *
     * Accepts either the JSON string produced by `JSON.stringify(conv)` or the
     * already-parsed plain object. The original `jtdSchema`, `descriptor`, or
     * `descriptors` is re-processed through the corresponding factory, so the
     * restored instance is fully functional.
     *
     * @param data - A JSON string or parsed object previously produced by {@link toJSON}.
     * @returns A fully reconstructed {@link OpenAIConversion}.
     * @throws If the serialized data contains neither `jtdSchema`, `descriptor`, nor `descriptors`.
     */
    static fromJSON(data: string | Record<string, unknown>): OpenAIConversion;
    private constructor();
    /**
     * Convert raw LLM output into a validated result.
     *
     * For JTD-based conversions, the value is coerced to conform to the original
     * JTD schema:
     * - Non-integer numbers are rounded for integer types.
     * - Null values on optional properties are stripped (OpenAI required+nullable
     *   encoding is reversed).
     * - `{key, value}` arrays from the values form are reassembled into Records.
     * - Unstructured/empty schemas parse the raw JSON string via `JSON.parse`.
     *
     * The coerced value is then validated against the JTD schema. Returns
     * {@link ConvertSuccessJson} on success.
     *
     * For MIME-based conversions, the value is expected to be a base64 string
     * which is decoded into raw bytes. Returns {@link ConvertSuccessBinary}.
     *
     * For multi-format signals, the first non-null `format_N` property is
     * selected and converted individually.
     *
     * @param value - The value to convert. JSON for JTD, or `{ data, mimeType, filename }` for MIME.
     * @returns A {@link ConvertResult} indicating success or failure with errors.
     */
    convert: (value: unknown) => T | ConvertFailure;
    /**
     * Produce a JSON-serializable representation of this conversion.
     *
     * The output includes the OpenAI `schema`, `strict` flag, and either the
     * original `jtdSchema` or `descriptor` (whichever was used to create this
     * instance), which is sufficient to fully restore the conversion via
     * {@link fromJSON}.
     *
     * Called automatically by `JSON.stringify(conv)`.
     */
    toJSON(): Record<string, unknown>;
}
/**
 * Convenience alias for {@link OpenAIConversion.fromJTD}.
 *
 * @param jtdSchema - A valid JTD schema (RFC 8927).
 * @returns A new {@link OpenAIConversion}.
 */
export declare function convertToOpenAISchema(jtdSchema: unknown): OpenAIConversion;
/**
 * Convenience alias for {@link OpenAIConversion.fromSignal}.
 *
 * @param descriptor - An Adapt signal descriptor.
 * @returns A new {@link OpenAIConversion}.
 */
export declare function convertSignalToOpenAISchema(descriptor: SignalDescriptorJson): OpenAIConversion;
//# sourceMappingURL=index.d.ts.map