fix: refactor and add structured output support (#85)

Author: gitcommitshow

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [Unreleased]
+
+### Breaking Changes
+* `ResilientLLM.chat()` now always returns a consistent envelope object: `{ content, toolCalls?, metadata }` (metadata is no longer gated by `returnOperationMetadata`).
+
 ## [1.7.1](https://github.com/gitcommitshow/resilient-llm/compare/v1.7.0...v1.7.1) (2026-03-16)
 
 

README.md

@@ -53,8 +53,8 @@ const conversationHistory = [
 
 (async () => {
   try {
-    const response = await llm.chat(conversationHistory);
-    console.log('LLM response:', response);
+    const { content, toolCalls, metadata } = await llm.chat(conversationHistory);
+    console.log('LLM response:', content);
   } catch (err) {
     console.error('Error:', err);
   }
@@ -92,6 +92,37 @@ import { ProviderRegistry } from 'resilient-llm';
 
 See the [full API reference](./docs/reference.md) for complete documentation.
 
+## Structured output (JSON + schema)
+
+Use `llm.chat(..., { responseFormat })` when you need the assistant to return **machine-readable JSON**, optionally matching a **specific JSON Schema**.
+
+```javascript
+// JSON mode (single JSON object)
+const { content: obj } = await llm.chat(messages, { responseFormat: { type: 'json_object' } });
+
+// Schema mode (validate required keys/types)
+const { content: result } = await llm.chat(messages, {
+  responseFormat: {
+    type: 'json_schema',
+    json_schema: {
+      name: 'answer_payload',
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { answer: { type: 'string' } },
+        required: ['answer']
+      }
+    }
+  }
+});
+
+// `result` is a parsed JS object (not a string).
+// If the model returns invalid JSON or fails schema validation,
+// `llm.chat(...)` throws a StructuredOutputError with `code` and `validation` details.
+```
+
+For all supported shapes (including plain schema objects) and parsing/validation behavior, see [`responseFormat` docs](./docs/reference.md#responseformat-json-mode--schema-mode).
+
 ## Supported LLM Providers
 
 ResilientLLM comes with built-in support for all text models provided by **OpenAI**, **Anthropic**, **Google/Gemini**, **Ollama** API, etc.

docs/reference.md

@@ -52,7 +52,6 @@ new ResilientLLM(options?: ResilientLLMOptions)
 | `backoffFactor` | `number` | No | `2` | Exponential backoff multiplier between retries |
 | `onRateLimitUpdate` | `Function` | No | `undefined` | Callback function called when rate limit information is updated |
 | `onError` | `Function` | No | `undefined` | Currently not used (reserved for future use) |
-| `returnOperationMetadata` | `boolean` | No | `false` | When `true`, `chat()` returns a [ChatResponse](#chatresponse) with `metadata` populated instead of a plain string (see [OperationMetadata](#operationmetadata)) |
 
 **RateLimitConfig:**
 
@@ -79,12 +78,6 @@ const llm = new ResilientLLM({
 
 ---
 
-### ResilientLLM Static Properties
-
-_No static properties currently available. Use `ProviderRegistry.getDefaultModels()` to get default models for all providers._
-
----
-
 ### ResilientLLM Instance Methods
 
 #### `chat(conversationHistory, llmOptions?)`
@@ -93,7 +86,7 @@ Sends a chat completion request to the configured LLM provider.
 
 **Signature:**
 ```typescript
-chat(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<string | ChatResponse>
+chat(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<ChatResponse>
 ```
 
 **Parameters:**
@@ -124,8 +117,15 @@ chat(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<string |
 | `reasoningEffort` | `string` | Reasoning effort level: `"low"`, `"medium"`, or `"high"` (for reasoning models) |
 | `apiKey` | `string` | Override API key for this request (takes precedence over ProviderRegistry) |
 | `tools` | `Tool[]` | Array of tool definitions for function calling |
-| `responseFormat` | `Object` | Response format specification (e.g., `{ type: "json_object" }`) |
-| `returnOperationMetadata` | `boolean` | When `true`, this request returns a [ChatResponse](#chatresponse) with `metadata`; overrides the constructor default for this call only |
+| `responseFormat` | `Object \| string` | Response format specification (`json_object`/`json_schema` object shapes, plain schema-like object, or JSON aliases: `"json"`, `"object"`, `"json_object"`) |
+| `outputConfig` | `Object` | **Legacy/migration support**. Anthropic-style alternative structured-output input shape, normalized internally via `responseFormat`. _Prefer `responseFormat` for all new usage._ |
+| `response_format` | `Object \| string` | **Legacy/migration support**. Snake_case alias for `responseFormat`; passthrough-friendly for provider-native payloads. _Prefer `responseFormat` for all new usage._ |
+| `output_config` | `Object` | **Legacy/migration support**. Snake_case alias for `outputConfig`; passed through as-is when provided. _Prefer `responseFormat` for all new usage._ |
+
+Use one naming style per field to avoid ambiguity:
+- Prefer camelCase (`responseFormat` or its alias `outputConfig`) in app code.
+- Prefer snake_case (`response_format`, `output_config`) when reusing raw provider payload snippets.
+- Do not send both aliases for the same field in one request; conflicting info may result in error.
 
 **Tool:**
 
@@ -138,33 +138,37 @@ chat(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<string |
 | `function.parameters` | `Object` | Function parameters schema (OpenAI format) |
 | `function.input_schema` | `Object` | Function input schema (Anthropic format) |
 
-**Returns:** `Promise<string | ChatResponse>`
+**Returns:** `Promise<ChatResponse>`
 
-- If `tools` are provided, returns `ChatResponse` with `content` and `toolCalls`; otherwise returns a `string` (the assistant's reply).
-- If `returnOperationMetadata` is set to `true` (constructor or `llmOptions`): Returns a `ChatResponse` with `content` and `metadata` ([OperationMetadata](#operationmetadata))
-- Otherwise: Returns `string` containing 
-the assistant's response.
+- Always returns a predictable envelope:
+  - `response.content` is the assistant output (string in text mode, parsed object in JSON/schema mode)
+  - `response.toolCalls` is included when tool calls are returned
+- `response.metadata` is always included
 
 **ChatResponse:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `content` | `string \| null` | The text content of the response |
+| `content` | `string \| Object \| null` | The assistant content (text by default, normalized JSON object in JSON modes) |
 | `toolCalls` | `Array` | Array of tool call objects (if tools were used) |
-| `metadata` | `OperationMetadata` | Present when `returnOperationMetadata` is `true` (request id, config, timing, retries, rate limiting, usage, etc.) |
+| `metadata` | `OperationMetadata` | Always included (request id, config, timing, retries, rate limiting, usage, etc.) |
 
 **Throws:**
 
 - `Error` - If input tokens exceed `maxInputTokens`
 - `Error` - If API key is not set for the selected service (unless auth is optional)
 - `Error` - If the AI service/provider is invalid
 - `Error` - If API request fails
+- `Error` - If JSON mode parsing fails (`code: "JSON_PARSE_ERROR"`, `rawResponse`)
+- `Error` - If JSON response is not an object (`code: "JSON_MODE_FAILURE"`, `rawResponse`)
+- `Error` - If schema validation fails (`code: "SCHEMA_MISMATCH"`, `rawResponse`, `validation: SchemaValidationIssue`)
 
 **Notes:**
 
 - API keys can be provided via `llmOptions.apiKey`, `ProviderRegistry.configure()`, or environment variables
 - The implementation uses `ProviderRegistry` to manage providers and their configurations
 - Response parsing is handled generically using provider-specific `chatConfig` settings
+- For schema mode, validation checks top-level required fields and primitive types (`string`, `number`, `boolean`, `integer`). Schema mismatch errors include a `validation` object with `missingFields`, `extraFields`, and `typeMismatches` arrays
 
 **Example:**
 ```javascript
@@ -173,8 +177,8 @@ const conversationHistory = [
   { role: 'user', content: 'What is the capital of France?' }
 ];
 
-const response = await llm.chat(conversationHistory);
-console.log(response); // "The capital of France is Paris."
+const { content } = await llm.chat(conversationHistory);
+console.log(content); // "The capital of France is Paris."
 ```
 
 **Example with tools:**
@@ -212,14 +216,13 @@ const response = await llm.chat(conversationHistory, {
 const llm = new ResilientLLM({
   aiService: 'openai',
   model: 'gpt-4o-mini',
-  returnOperationMetadata: true
 });
 
 const { content, metadata } = await llm.chat(conversationHistory);
 console.log(content);           // Assistant reply text
-console.log(metadata.requestId);
-console.log(metadata.timing.totalTimeMs);
-console.log(metadata.usage);    // prompt_tokens, completion_tokens, total_tokens
+console.log(metadata?.requestId);
+console.log(metadata?.timing?.totalTimeMs);
+console.log(metadata?.usage);    // prompt_tokens, completion_tokens, total_tokens
 ```
 
 ---
@@ -430,7 +433,7 @@ Retries the chat request with an alternate AI service when the current service r
 
 **Signature:**
 ```typescript
-retryChatWithAlternateService(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<string | ChatResponse>
+retryChatWithAlternateService(conversationHistory: Message[], llmOptions?: ChatOptions): Promise<ChatResponse>
 ```
 
 **Parameters:**
@@ -440,7 +443,7 @@ retryChatWithAlternateService(conversationHistory: Message[], llmOptions?: ChatO
 | `conversationHistory` | `Message[]` | Yes | Array of message objects |
 | `llmOptions` | `ChatOptions` | No | LLM options for the request |
 
-**Returns:** `Promise<string | ChatResponse>` - Response from the alternate service
+**Returns:** `Promise<ChatResponse>` - Response from the alternate service
 
 **Throws:**
 
@@ -507,25 +510,32 @@ interface Message {
 
 ### ChatResponse
 
-Response object returned by `chat()` when tools are used and/or `returnOperationMetadata` is `true`. Otherwise `chat()` returns a plain `string`.
+Response envelope returned by `chat()` on every call.
+
+- `content` is the assistant output:
+  - text mode -> `string`
+  - JSON/schema mode -> parsed JS object
+- `toolCalls` is present when tool calls were returned
+- `metadata` is always included
 
 ```typescript
 interface ChatResponse {
-  content: string | null;
+  content: string | Object | null;
   toolCalls?: Array<any>;
-  metadata?: OperationMetadata;  // present when returnOperationMetadata is true
+  metadata: OperationMetadata;
 }
 ```
 
 ### OperationMetadata
 
-Operation metadata attached to `ChatResponse.metadata` when `returnOperationMetadata` is `true` (constructor or per-call). Used for observability, logging, and debugging.
+Operation metadata attached to `ChatResponse.metadata` on every call. Used for observability, logging, and debugging.
 
 ```typescript
 interface OperationMetadata {
   requestId: string;
   operationId: string;
   startTime: number;
+  finishReason?: string | null;
   config: {
     aiService: string;
     model: string;
@@ -594,7 +604,6 @@ interface ResilientLLMOptions {
   backoffFactor?: number;
   onRateLimitUpdate?: (info: RateLimitInfo) => void;
   onError?: (error: Error) => void;
-  returnOperationMetadata?: boolean;
 }
 ```
 
@@ -615,10 +624,137 @@ interface ChatOptions {
   apiKey?: string;
   tools?: Tool[];
   responseFormat?: Object;
-  returnOperationMetadata?: boolean;
+  outputConfig?: Object;
+}
+```
+
+#### `responseFormat` (JSON mode + schema mode)
+
+Use `responseFormat` when you need the assistant response as **JSON**, optionally matching a **particular schema**.
+
+- **JSON mode (no schema)**: ensures the reply is a single JSON object (library parses it for you).
+- **Schema mode**: provides a JSON Schema so the library can validate the parsed object and throw `SCHEMA_MISMATCH` when required keys/types don’t match.
+
+**Supplying a schema**
+
+You can supply a schema in any of these equivalent shapes (pick one and stick to it):
+
+- **OpenAI-style wrapper** (recommended when you want to be explicit):
+
+```typescript
+responseFormat: {
+  type: 'json_schema',
+  json_schema: {
+    name: 'my_payload',
+    schema: {
+      type: 'object',
+      properties: {
+        answer: { type: 'string' },
+        citations: { type: 'array', items: { type: 'string' } }
+      },
+      required: ['answer']
+    }
+  }
+}
+```
+
+- **Short wrapper** (schema directly on the object):
+
+```typescript
+responseFormat: {
+  type: 'json_schema',
+  schema: {
+    type: 'object',
+    properties: { answer: { type: 'string' } },
+    required: ['answer']
+  }
+}
+```
+
+- **Plain schema-like object** (auto-detected as a schema):
+
+```typescript
+responseFormat: {
+  type: 'object',
+  properties: { answer: { type: 'string' } },
+  required: ['answer']
 }
 ```
 
+**End-to-end example (schema mode)**
+
+```typescript
+const llm = new ResilientLLM({ aiService: 'openai', model: 'gpt-4o-mini' });
+
+const result = await llm.chat(
+  [{ role: 'user', content: 'Return an answer and citations.' }],
+  {
+    responseFormat: {
+      type: 'json_schema',
+      json_schema: {
+        name: 'answer_payload',
+        schema: {
+          type: 'object',
+          properties: {
+            answer: { type: 'string' },
+            citations: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['answer']
+        }
+      }
+    }
+  }
+);
+
+// `result.content` is a parsed JS object when `responseFormat` requests JSON/schema mode.
+```
+
+**Validation scope (important)**
+
+The built-in validator is intentionally lightweight: it checks **required keys**, **extra keys**, and **primitive types** at the top level (`string`, `number`, `boolean`, `integer`).
+
+- Extra keys are enforced only when your schema sets `additionalProperties: false` (and the schema has `properties`).
+- For deeper validation needs (nested objects, enums, regex, oneOf/anyOf, etc.), run your own schema validator after the call.
+
+**Example: `additionalProperties: false` + `required`**
+
+```typescript
+const result = await llm.chat(messages, {
+  responseFormat: {
+    type: 'json_schema',
+    json_schema: {
+      name: 'answer_payload',
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          answer: { type: 'string' }
+        },
+        required: ['answer']
+      }
+    }
+  }
+});
+
+// `result.content` is { answer: string } when the model output matches the schema.
+// If the model returns invalid JSON or extra keys, `llm.chat(...)` throws StructuredOutputError (e.g. `SCHEMA_MISMATCH`).
+```
+
+#### `responseFormat` examples (quick)
+
+```typescript
+// JSON alias strings (equivalent to { type: 'json_object' })
+'json'
+'object'
+'json_object'
+
+// OpenAI-compatible JSON mode
+{ type: 'json_object' }
+
+// When `responseFormat` requests JSON, `llm.chat(...)` resolves to a response envelope
+// where `.content` is the parsed JS object.
+```
+
 ### Tool
 
 Tool definition for function calling.