@mochabug/adapt-sdk 0.4.0 → 0.4.2

package/dist/gemini/index.d.ts

@@ -1,5 +1,13 @@
 import type { JTDSchemaJson, SignalDescriptorJson } from '../api';
-/** JSON Schema subset supported by Gemini 3+ structured output. */
+/**
+ * JSON Schema subset accepted by the Gemini structured-output API.
+ *
+ * This is the provider-specific representation produced by {@link GeminiConversion}.
+ * It covers the keywords that Gemini 3+ actually inspects when constraining
+ * model output: `type`, `properties`, `required`, `enum`, `items`,
+ * `additionalProperties`, `format`, `minimum`/`maximum`, `title`, and
+ * `description`.
+ */
 export interface GeminiSchema {
     type?: string | string[];
     title?: string;
@@ -13,40 +21,199 @@ export interface GeminiSchema {
     minimum?: number;
     maximum?: number;
 }
-export interface ConvertSuccess {
+/**
+ * Successful conversion result for a JTD format.
+ *
+ * Returned when the raw LLM output has been coerced to match the JTD schema
+ * and passes JTD validation. `data` contains the deserialized, coerced, and
+ * JTD-validated JSON value.
+ */
+export interface ConvertSuccessJson {
     success: true;
+    kind: 'json';
+    /** The deserialized, coerced, and JTD-validated JSON value. */
     data: unknown;
 }
+/**
+ * Successful conversion result for a MIME (binary) format.
+ *
+ * Returned when the raw LLM output matches a MIME format. The base64 string
+ * produced by the model is decoded into raw binary bytes.
+ */
+export interface ConvertSuccessBinary {
+    success: true;
+    kind: 'binary';
+    /** The concrete MIME type of the binary content (e.g. `"image/png"`). */
+    mimeType: string;
+    /** The raw binary data decoded from the base64 string returned by the LLM. */
+    data: Uint8Array;
+    /** Optional filename, provided by the caller if available. */
+    filename?: string;
+}
+/**
+ * Failed conversion result.
+ *
+ * `errors` contains one or more human-readable strings describing validation
+ * or coercion failures. Each entry uses a JSON Pointer path prefix
+ * (e.g. `"/foo/bar: ..."`) to locate the problem within the data.
+ */
 export interface ConvertFailure {
     success: false;
+    /** Array of human-readable error messages with JSON Pointer path prefixes. */
     errors: string[];
 }
-export type ConvertResult = ConvertSuccess | ConvertFailure;
-export interface GeminiConversionResult {
-    /** Gemini 3+ compatible JSON Schema for structured output. */
-    schema: GeminiSchema;
-    /** Convert Gemini JSON output back to JTD-conforming JSON. */
-    convert: (geminiJson: unknown) => ConvertResult;
-}
 /**
- * Convert a JTD schema to a Gemini 3+ compatible JSON Schema, with a
- * converter function that transforms and validates Gemini output against
- * the original JTD schema.
+ * Discriminated union of conversion outcomes.
  *
- * @throws {Error} if the JTD schema contains forms that cannot be represented.
+ * Check `success` first, then narrow on `kind` (`'json'` or `'binary'`)
+ * for successful results.
  */
-export declare function convertToGeminiSchema(jtdSchema: JTDSchemaJson): GeminiConversionResult;
+export type ConvertResult = ConvertSuccessJson | ConvertSuccessBinary | ConvertFailure;
 /**
- * Convert a SignalDescriptorJson to a Gemini 3+ compatible JSON Schema.
+ * Converts JTD schemas or Adapt signal descriptors into Gemini-compatible
+ * JSON Schema, 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`. Optional
+ *   properties are included but not listed in `required`.
+ * - **values** -- mapped to `type: "object"` with `additionalProperties` set
+ *   to the value schema (Gemini supports free-form object keys natively).
+ * - **discriminator** -- mapped to a wrapper object: a `type: "string"` enum
+ *   property for the discriminator tag, plus one property per variant. The
+ *   LLM is instructed via `description` to populate only the property
+ *   matching the chosen tag. (Gemini does not support `anyOf`.)
+ *
+ * ### 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).
  *
- * Handles single and multi-format signals:
- * - Single format: schema is the converted format directly.
- * - Multiple formats: schema is a wrapper object with `format_0`, `format_1`, etc.
- *   as optional properties. The convert function extracts the selected format.
+ * ```ts
+ * const conv = GeminiConversion.fromJTD(jtdSchema);
+ * conv.schema;           // Gemini JSON Schema to pass to the LLM
+ * conv.convert(output);  // coerce + validate -> ConvertResult
  *
- * MIME type formats are mapped to base64 strings.
+ * // Serialize & restore
+ * const cached = JSON.stringify(conv);
+ * const restored = GeminiConversion.fromJSON(cached);
+ * ```
+ */
+export declare class GeminiConversion {
+    /** The Gemini-specific JSON Schema to pass to the Gemini API as the response schema. */
+    readonly schema: GeminiSchema;
+    /**
+     * 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;
+    /**
+     * Build a conversion from a JTD schema.
+     *
+     * Recursively converts every JTD form into the equivalent Gemini JSON Schema
+     * node. Definitions (`jtdSchema.definitions`) are resolved inline because
+     * Gemini does not support `$ref`.
+     *
+     * @param jtdSchema - A valid JTD schema (RFC 8927).
+     * @returns A new {@link GeminiConversion} with `jtdSchema` set.
+     * @throws If the schema contains an unknown JTD type, an unresolved `ref`,
+     *         or circular / excessively deep refs (exceeding 32 levels).
+     */
+    static fromJTD(jtdSchema: JTDSchemaJson): GeminiConversion;
+    /**
+     * 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 -- the LLM must
+     * populate exactly one. MIME formats become base64 string schemas.
+     *
+     * @param descriptor - An Adapt signal descriptor with one or more formats.
+     * @returns A new {@link GeminiConversion} with `descriptor` set.
+     * @throws If the descriptor has no formats, or a format has neither
+     *         `jtdSchema` nor `mimeType`.
+     */
+    static fromSignal(descriptor: SignalDescriptorJson): GeminiConversion;
+    /**
+     * Restore a {@link GeminiConversion} from its serialized form.
+     *
+     * Accepts either the JSON string produced by `JSON.stringify(conv)` or the
+     * already-parsed plain object. The original `jtdSchema` or `descriptor` 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 GeminiConversion}.
+     * @throws If the serialized data contains neither `jtdSchema` nor `descriptor`.
+     */
+    static fromJSON(data: string | Record<string, unknown>): GeminiConversion;
+    private constructor();
+    /**
+     * Convert raw LLM output into a validated result.
+     *
+     * For JTD-based conversions, the value is coerced (e.g. non-integer numbers
+     * are rounded for integer types, discriminator wrapper objects are unwrapped
+     * into flat tagged unions), then validated against the original 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} on
+     * success.
+     *
+     * For multi-format signals, the first non-null `format_N` property is
+     * selected and converted individually.
+     *
+     * @param json - The raw value returned by the Gemini API (typically parsed JSON).
+     * @returns A {@link ConvertResult} indicating success or failure with errors.
+     */
+    convert: (json: unknown) => ConvertResult;
+    /**
+     * Produce a JSON-serializable representation of this conversion.
+     *
+     * The output includes the Gemini `schema` 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(): {
+        schema: GeminiSchema;
+        descriptor: SignalDescriptorJson;
+        jtdSchema?: undefined;
+    } | {
+        schema: GeminiSchema;
+        jtdSchema: JTDSchemaJson | undefined;
+        descriptor?: undefined;
+    };
+}
+/**
+ * Convenience alias for {@link GeminiConversion.fromJTD}.
+ *
+ * @param jtdSchema - A valid JTD schema (RFC 8927).
+ * @returns A new {@link GeminiConversion}.
+ */
+export declare function convertToGeminiSchema(jtdSchema: JTDSchemaJson): GeminiConversion;
+/**
+ * Convenience alias for {@link GeminiConversion.fromSignal}.
  *
- * @throws {Error} if the descriptor has no formats.
+ * @param descriptor - An Adapt signal descriptor.
+ * @returns A new {@link GeminiConversion}.
  */
-export declare function convertSignalToGeminiSchema(descriptor: SignalDescriptorJson): GeminiConversionResult;
+export declare function convertSignalToGeminiSchema(descriptor: SignalDescriptorJson): GeminiConversion;
 //# sourceMappingURL=index.d.ts.map

package/dist/gemini/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gemini/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9C,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,MAAM,EAAE,YAAY,CAAC;IACrB,8DAA8D;IAC9D,OAAO,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,aAAa,CAAC;CACjD;AAmYD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,sBAAsB,CAiBxB;AAmCD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,sBAAsB,CA0FxB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gemini/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9C,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,cAAc,CAAC;AA0TnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,gBAAgB;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAI3C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;IAK1D;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB;IAKrE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAezE,OAAO;IAYP;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,GAAI,MAAM,OAAO,KAAG,aAAa,CAQtC;IAIF;;;;;;;;OAQG;IACH,MAAM;;;;;;;;;CAMP;AA4KD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CAElB"}

package/dist/openai/index.d.ts

@@ -1,5 +1,13 @@
 import type { JTDSchemaJson, SignalDescriptorJson } from '../api';
-/** JSON Schema subset supported by OpenAI structured output (strict mode). */
+/**
+ * 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;
@@ -15,41 +23,231 @@ export interface OpenAISchema {
     $defs?: Record<string, OpenAISchema>;
     $ref?: string;
 }
-export interface ConvertSuccess {
+/**
+ * Successful conversion result for a JTD format.
+ *
+ * Returned when the raw LLM output has been coerced to match the JTD schema
+ * and passes JTD validation. `data` contains the deserialized, coerced, and
+ * JTD-validated JSON value.
+ */
+export interface ConvertSuccessJson {
     success: true;
+    kind: 'json';
+    /** The deserialized, coerced, and JTD-validated JSON value. */
     data: unknown;
 }
+/**
+ * Successful conversion result for a MIME (binary) format.
+ *
+ * Returned when the raw LLM output matches a MIME format. The base64 string
+ * produced by the model is decoded into raw binary bytes.
+ */
+export interface ConvertSuccessBinary {
+    success: true;
+    kind: 'binary';
+    /** The concrete MIME type of the binary content (e.g. `"image/png"`). */
+    mimeType: string;
+    /** The raw binary data decoded from the base64 string returned by the LLM. */
+    data: Uint8Array;
+    /** Optional filename, provided by the caller if available. */
+    filename?: string;
+}
+/**
+ * Failed conversion result.
+ *
+ * `errors` contains one or more human-readable strings describing validation
+ * or coercion failures. Each entry uses a JSON Pointer path prefix
+ * (e.g. `"/foo/bar: ..."`) to locate the problem within the data.
+ */
 export interface ConvertFailure {
     success: false;
+    /** Array of human-readable error messages with JSON Pointer path prefixes. */
     errors: string[];
 }
-export type ConvertResult = ConvertSuccess | ConvertFailure;
-export interface OpenAIConversionResult {
-    /** OpenAI strict mode compatible JSON Schema. */
-    schema: OpenAISchema;
-    /** Whether the schema supports strict mode. False for unstructured (empty) schemas. */
-    strict: boolean;
-    /** Convert OpenAI JSON output back to JTD-conforming JSON. */
-    convert: (openaiJson: unknown) => ConvertResult;
-}
 /**
- * Convert a JTD schema to an OpenAI strict mode compatible JSON Schema, with a
- * converter function that transforms and validates OpenAI output against
- * the original JTD schema.
+ * Discriminated union of conversion outcomes.
  *
- * @throws {Error} if the JTD schema contains forms that cannot be represented.
+ * Check `success` first, then narrow on `kind` (`'json'` or `'binary'`)
+ * for successful results.
  */
-export declare function convertToOpenAISchema(jtdSchema: JTDSchemaJson): OpenAIConversionResult;
+export type ConvertResult = ConvertSuccessJson | ConvertSuccessBinary | ConvertFailure;
 /**
- * Convert a SignalDescriptorJson to an OpenAI strict mode compatible JSON Schema.
+ * 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
  *
- * Handles single and multi-format signals:
- * - Single format: schema is the converted format directly.
- * - Multiple formats: wrapper object with `format_0`, `format_1`, etc.
- *   All format properties are required and nullable (OAI strict mode).
- *   The model sets exactly one to a value and the rest to null.
+ * // Serialize & restore
+ * const cached = JSON.stringify(conv);
+ * const restored = OpenAIConversion.fromJSON(cached);
+ * ```
+ */
+export declare class OpenAIConversion {
+    /** 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;
+    /**
+     * 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(jtdSchema: JTDSchemaJson): OpenAIConversion;
+    /**
+     * 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): OpenAIConversion;
+    /**
+     * 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` or `descriptor` 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` nor `descriptor`.
+     */
+    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 json - The raw value returned by the OpenAI API (typically parsed JSON).
+     * @returns A {@link ConvertResult} indicating success or failure with errors.
+     */
+    convert: (json: unknown) => ConvertResult;
+    /**
+     * 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(): {
+        schema: OpenAISchema;
+        strict: boolean;
+        descriptor: SignalDescriptorJson;
+        jtdSchema?: undefined;
+    } | {
+        schema: OpenAISchema;
+        strict: boolean;
+        jtdSchema: JTDSchemaJson | undefined;
+        descriptor?: undefined;
+    };
+}
+/**
+ * Convenience alias for {@link OpenAIConversion.fromJTD}.
+ *
+ * @param jtdSchema - A valid JTD schema (RFC 8927).
+ * @returns A new {@link OpenAIConversion}.
+ */
+export declare function convertToOpenAISchema(jtdSchema: JTDSchemaJson): OpenAIConversion;
+/**
+ * Convenience alias for {@link OpenAIConversion.fromSignal}.
  *
- * @throws {Error} if the descriptor has no formats.
+ * @param descriptor - An Adapt signal descriptor.
+ * @returns A new {@link OpenAIConversion}.
  */
-export declare function convertSignalToOpenAISchema(descriptor: SignalDescriptorJson): OpenAIConversionResult;
+export declare function convertSignalToOpenAISchema(descriptor: SignalDescriptorJson): OpenAIConversion;
 //# sourceMappingURL=index.d.ts.map

package/dist/openai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,KAAK,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,MAAM,EAAE,YAAY,CAAC;IACrB,uFAAuF;IACvF,MAAM,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,aAAa,CAAC;CACjD;AA8jBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,sBAAsB,CAkCxB;AAqCD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,sBAAsB,CAiGxB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,KAAK,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,cAAc,CAAC;AA0jBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAI3C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;IAyB1D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB;IAKrE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAezE,OAAO;IAcP;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,GAAI,MAAM,OAAO,KAAG,aAAa,CAQtC;IAIF;;;;;;;;;OASG;IACH,MAAM;;;;;;;;;;;CAcP;AAqMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CAElB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mochabug/adapt-sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "The API toolkit to facilitate mochabug adapt plugin development",
   "publishConfig": {
     "access": "public"