purra-openai 0.5.0 → 1.0.0

package/dist/chat.d.ts

@@ -14,6 +14,7 @@ export declare class OpenAIChatCompletionsGateway implements ModelGateway {
     #private;
     readonly capabilities: ModelCapabilitySnapshot;
     constructor(options: OpenAIChatCompletionsOptions);
+    validateOutputContract(request: ModelRequest): string | undefined;
     invoke(request: ModelRequest, signal?: AbortSignal): Promise<ModelTurn>;
     stream(request: ModelRequest, signal?: AbortSignal): Promise<ModelStream>;
 }

package/dist/chat.js

@@ -1,3 +1,4 @@
+import { validateOutput } from "./structured.js";
 import OpenAI from "openai";
 import { AgentCanceledError, AgentError } from "purra";
 function text(value) {
@@ -64,11 +65,18 @@ export class OpenAIChatCompletionsGateway {
         this.#options = { ...options };
         this.#client = (options.client ?? new OpenAI()).withOptions({ maxRetries: 0, timeout: options.timeoutMs ?? 60000 });
     }
+    validateOutputContract(request) {
+        return validateOutput(request, this.capabilities);
+    }
     #request(request) {
+        this.validateOutputContract(request);
         if (!request.outputBudget)
             throw new TypeError("OpenAI gateway requires a resolved generation budget");
         const o = this.#options;
         return { model: o.model, messages: messages(request.messages), store: false, max_completion_tokens: request.outputBudget.maxGenerationTokens,
+            ...(request.outputContract?.mode === "native_required" ? { response_format: { type: "json_schema", json_schema: {
+                        name: "purra_output", strict: true, schema: JSON.parse(JSON.stringify(request.outputContract.schema)),
+                    } } } : {}),
             ...(o.reasoningEffort === undefined ? {} : { reasoning_effort: o.reasoningEffort }),
             ...(o.temperature === undefined ? {} : { temperature: o.temperature }),
             ...(o.topP === undefined ? {} : { top_p: o.topP }),

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export declare class OpenAIResponsesGateway implements ModelGateway {
     #private;
     readonly capabilities: ModelCapabilitySnapshot;
     constructor(options: OpenAIResponsesOptions);
+    validateOutputContract(request: ModelRequest): string | undefined;
     invoke(request: ModelRequest, signal?: AbortSignal): Promise<ModelTurn>;
     stream(request: ModelRequest, signal?: AbortSignal): Promise<ModelStream>;
 }

package/dist/index.js

@@ -1,3 +1,4 @@
+import { validateOutput } from "./structured.js";
 import OpenAI from "openai";
 export { OpenAIChatCompletionsGateway } from "./chat.js";
 import { AgentCanceledError, AgentError } from "purra";
@@ -77,7 +78,11 @@ export class OpenAIResponsesGateway {
         this.#reasoning = options.reasoning;
         this.#client = (options.client ?? new OpenAI()).withOptions({ maxRetries: 0, timeout: options.timeoutMs ?? 60000 });
     }
+    validateOutputContract(request) {
+        return validateOutput(request, this.capabilities);
+    }
     #request(request) {
+        this.validateOutputContract(request);
         if (!request.outputBudget)
             throw new TypeError("OpenAI gateway requires a resolved generation budget");
         return { model: this.#model, input: input(request.messages), store: false, include: ["reasoning.encrypted_content"],
@@ -85,6 +90,9 @@ export class OpenAIResponsesGateway {
             tools: request.tools.map(t => ({ type: "function", name: t.name, description: t.description,
                 parameters: JSON.parse(JSON.stringify(t.inputSchema)), strict: false })),
             tool_choice: request.tools.length ? "auto" : "none",
+            ...(request.outputContract?.mode === "native_required" ? { text: { format: {
+                        type: "json_schema", name: "purra_output", strict: true, schema: JSON.parse(JSON.stringify(request.outputContract.schema)),
+                    } } } : {}),
             ...(this.#reasoning === undefined ? {} : { reasoning: this.#reasoning }), };
     }
     async invoke(request, signal) {

package/dist/structured.d.ts

@@ -0,0 +1,2 @@
+import type { ModelCapabilitySnapshot, ModelRequest } from "purra";
+export declare function validateOutput(request: ModelRequest, capabilities: ModelCapabilitySnapshot): string | undefined;

package/dist/structured.js

@@ -0,0 +1,49 @@
+import { StructuredOutputError } from "purra";
+const allowed = new Set(["type", "properties", "required", "additionalProperties", "items", "enum", "description", "title"]);
+export function validateOutput(request, capabilities) {
+    const output = request.outputContract;
+    if (output === undefined || output.mode === "local")
+        return undefined;
+    function reject() { throw new StructuredOutputError("structured_output_mode_unsupported", "nativeDialect"); }
+    if (request.tools.length || capabilities.protocol.jsonSchemaLevel !== "json_schema"
+        || request.capabilitySnapshot?.protocol.jsonSchemaLevel !== "json_schema")
+        reject();
+    let enumCount = 0, propertyCount = 0;
+    function visit(node, depth) {
+        if (depth > 8 || Object.keys(node).some(key => !allowed.has(key)))
+            reject();
+        let kind = node.type;
+        if (typeof kind !== "string") {
+            if (!Array.isArray(kind) || kind.length !== 2 || !kind.includes("null"))
+                reject();
+            kind = kind.find(t => t !== "null");
+        }
+        if (kind === "object") {
+            const props = (node.properties ?? {});
+            propertyCount += Object.keys(props).length;
+            const required = (node.required ?? []);
+            if (propertyCount > 100 || node.additionalProperties !== false || !Array.isArray(required)
+                || required.length !== Object.keys(props).length
+                || Object.keys(props).some(key => !required.includes(key)))
+                reject();
+            for (const child of Object.values(props))
+                visit(child, depth + 1);
+        }
+        else if (["properties", "required", "additionalProperties"].some(key => key in node))
+            reject();
+        if (kind === "array") {
+            if (!node.items || typeof node.items !== "object" || Array.isArray(node.items))
+                reject();
+            visit(node.items, depth + 1);
+        }
+        else if ("items" in node)
+            reject();
+        if (Array.isArray(node.enum)) {
+            enumCount += node.enum.length;
+            if (enumCount > 100 || node.enum.some(v => v !== null && typeof v === "object"))
+                reject();
+        }
+    }
+    visit(output.schema, 0);
+    return "purra.openai-json-schema/v1";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purra-openai",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "type": "module",
   "license": "MIT",
   "description": "Official OpenAI Responses and Chat Completions SDK adapter for PurrA",
@@ -20,7 +20,7 @@
     "openai": "7.9.0"
   },
   "peerDependencies": {
-    "purra": "0.5.0"
+    "purra": "1.0.0"
   },
   "devDependencies": {
     "purra": "file:../../../typescript",