recursive-llm-ts 3.0.1 → 4.0.0

package/README.md

@@ -11,7 +11,8 @@ TypeScript/JavaScript package for [Recursive Language Models (RLM)](https://gith
 💾 **3x Less Memory** - Efficient Go implementation  
 📦 **Single Binary** - Easy distribution and deployment  
 🔄 **Unbounded Context** - Process 10M+ tokens without degradation  
-🎯 **Provider Agnostic** - Works with OpenAI, Anthropic, Azure, Bedrock, local models
+🎯 **Provider Agnostic** - Works with OpenAI, Anthropic, Azure, Bedrock, local models  
+🔍 **Structured Outputs** - Extract typed data with Zod schemas and parallel execution
 
 ## Installation
 
@@ -71,6 +72,83 @@ console.log(result.result);
 console.log('Stats:', result.stats);
 ```
 
+### Structured Outputs with Zod Schemas
+
+Extract structured, typed data from any context using Zod schemas. Supports complex nested objects, arrays, enums, and automatic parallel execution for performance.
+
+```typescript
+import { RLM } from 'recursive-llm-ts';
+import { z } from 'zod';
+
+const rlm = new RLM('gpt-4o-mini', {
+  api_key: process.env.OPENAI_API_KEY
+});
+
+// Define your schema
+const sentimentSchema = z.object({
+  sentimentValue: z.number().min(1).max(5),
+  sentimentExplanation: z.string(),
+  keyPhrases: z.array(z.object({
+    phrase: z.string(),
+    sentiment: z.number()
+  })),
+  topics: z.array(z.enum(['pricing', 'features', 'support', 'competition']))
+});
+
+// Extract structured data
+const result = await rlm.structuredCompletion(
+  'Analyze the sentiment and extract key information',
+  callTranscript,
+  sentimentSchema
+);
+
+// result.result is fully typed!
+console.log(result.result.sentimentValue); // number
+console.log(result.result.keyPhrases); // Array<{phrase: string, sentiment: number}>
+```
+
+**Key Benefits:**
+- ✅ **Type-safe** - Full TypeScript types from your Zod schema
+- ✅ **Automatic validation** - Retries with error feedback if schema doesn't match
+- ✅ **Parallel execution** - Complex schemas processed in parallel with goroutines (3-5x faster)
+- ✅ **Deep nesting** - Supports arbitrarily nested objects and arrays
+- ✅ **Enum support** - Validates enum values automatically
+
+**Performance Options:**
+```typescript
+// Enable/disable parallel execution
+const result = await rlm.structuredCompletion(
+  query,
+  context,
+  schema,
+  { 
+    parallelExecution: true,  // default: true for complex schemas
+    maxRetries: 3              // default: 3
+  }
+);
+```
+
+### Agent Coordinator (Advanced)
+
+For complex multi-field schemas, use the coordinator API:
+
+```typescript
+import { RLMAgentCoordinator } from 'recursive-llm-ts';
+
+const coordinator = new RLMAgentCoordinator(
+  'gpt-4o-mini',
+  { api_key: process.env.OPENAI_API_KEY },
+  'auto',
+  { parallelExecution: true }
+);
+
+const result = await coordinator.processComplex(
+  'Extract comprehensive call analysis',
+  transcript,
+  complexSchema
+);
+```
+
 ### Bridge Selection
 
 The package automatically uses the Go binary by default (if available). You can explicitly specify a bridge if needed:
@@ -123,6 +201,28 @@ Process a query with the given context using recursive language models.
 **Returns:**
 - `Promise<RLMResult>`: Result containing the answer and statistics
 
+#### `structuredCompletion<T>(query: string, context: string, schema: ZodSchema<T>, options?): Promise<StructuredRLMResult<T>>`
+
+Extract structured, typed data from context using a Zod schema.
+
+**Parameters:**
+- `query`: The extraction task to perform
+- `context`: The context/document to process
+- `schema`: Zod schema defining the output structure
+- `options`: Optional configuration
+  - `parallelExecution?: boolean` - Enable parallel processing (default: true)
+  - `maxRetries?: number` - Max validation retries (default: 3)
+
+**Returns:**
+- `Promise<StructuredRLMResult<T>>`: Typed result matching your schema
+
+**Example:**
+```typescript
+const schema = z.object({ score: z.number(), summary: z.string() });
+const result = await rlm.structuredCompletion('Analyze', doc, schema);
+// result.result is typed as { score: number, summary: string }
+```
+
 #### `cleanup(): Promise<void>`
 
 Clean up the bridge and free resources.

package/dist/bridge-interface.d.ts

@@ -4,8 +4,9 @@ export interface RLMStats {
     depth: number;
 }
 export interface RLMResult {
-    result: string;
+    result: string | any;
     stats: RLMStats;
+    structured_result?: boolean;
 }
 export interface RLMConfig {
     recursive_model?: string;

package/dist/coordinator.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { RLMConfig } from './bridge-interface';
+import { BridgeType } from './bridge-factory';
+import { StructuredRLMResult, CoordinatorConfig } from './structured-types';
+export declare class RLMAgentCoordinator {
+    private rlm;
+    private config;
+    constructor(model: string, rlmConfig?: RLMConfig, bridgeType?: BridgeType, coordinatorConfig?: CoordinatorConfig);
+    /**
+     * Process a complex query with structured output using schema decomposition
+     */
+    processComplex<T>(query: string, context: string, schema: z.ZodSchema<T>): Promise<StructuredRLMResult<T>>;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}

package/dist/coordinator.js

@@ -0,0 +1,45 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMAgentCoordinator = void 0;
+const rlm_1 = require("./rlm");
+class RLMAgentCoordinator {
+    constructor(model, rlmConfig = {}, bridgeType = 'auto', coordinatorConfig = {}) {
+        var _a, _b, _c;
+        this.rlm = new rlm_1.RLM(model, rlmConfig, bridgeType);
+        this.config = {
+            parallelExecution: (_a = coordinatorConfig.parallelExecution) !== null && _a !== void 0 ? _a : true,
+            maxRetries: (_b = coordinatorConfig.maxRetries) !== null && _b !== void 0 ? _b : 3,
+            progressiveValidation: (_c = coordinatorConfig.progressiveValidation) !== null && _c !== void 0 ? _c : true
+        };
+    }
+    /**
+     * Process a complex query with structured output using schema decomposition
+     */
+    processComplex(query, context, schema) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Delegate to RLM which now handles everything in Go
+            return this.rlm.structuredCompletion(query, context, schema, {
+                maxRetries: this.config.maxRetries,
+                parallelExecution: this.config.parallelExecution
+            });
+        });
+    }
+    /**
+     * Clean up resources
+     */
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rlm.cleanup();
+        });
+    }
+}
+exports.RLMAgentCoordinator = RLMAgentCoordinator;

package/dist/go-bridge.js

@@ -57,7 +57,7 @@ exports.GoBridge = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
-const DEFAULT_BINARY_NAME = process.platform === 'win32' ? 'rlm.exe' : 'rlm';
+const DEFAULT_BINARY_NAME = process.platform === 'win32' ? 'rlm-go.exe' : 'rlm-go';
 function resolveBinaryPath(rlmConfig) {
     const configuredPath = rlmConfig.go_binary_path || process.env.RLM_GO_BINARY;
     if (configuredPath) {
@@ -65,8 +65,8 @@ function resolveBinaryPath(rlmConfig) {
     }
     // Try multiple locations
     const possiblePaths = [
-        path.join(__dirname, '..', 'go', DEFAULT_BINARY_NAME), // Development
-        path.join(__dirname, '..', 'bin', DEFAULT_BINARY_NAME), // NPM package
+        path.join(__dirname, '..', 'bin', DEFAULT_BINARY_NAME), // NPM package (primary)
+        path.join(__dirname, '..', 'go', DEFAULT_BINARY_NAME), // Development fallback
     ];
     for (const p of possiblePaths) {
         if (fs.existsSync(p)) {
@@ -82,19 +82,21 @@ function assertBinaryExists(binaryPath) {
     }
 }
 function sanitizeConfig(config) {
-    const { pythonia_timeout, go_binary_path } = config, sanitized = __rest(config, ["pythonia_timeout", "go_binary_path"]);
-    return sanitized;
+    const { pythonia_timeout, go_binary_path, structured } = config, sanitized = __rest(config, ["pythonia_timeout", "go_binary_path", "structured"]);
+    return { config: sanitized, structured };
 }
 class GoBridge {
     completion(model_1, query_1, context_1) {
         return __awaiter(this, arguments, void 0, function* (model, query, context, rlmConfig = {}) {
             const binaryPath = resolveBinaryPath(rlmConfig);
             assertBinaryExists(binaryPath);
+            const { config, structured } = sanitizeConfig(rlmConfig);
             const payload = JSON.stringify({
                 model,
                 query,
                 context,
-                config: sanitizeConfig(rlmConfig)
+                config,
+                structured
             });
             return new Promise((resolve, reject) => {
                 const child = (0, child_process_1.spawn)(binaryPath, [], { stdio: ['pipe', 'pipe', 'pipe'] });

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { RLM } from './rlm';
 export { RLMConfig, RLMResult, RLMStats } from './bridge-interface';
 export { BridgeType } from './bridge-factory';
+export { StructuredRLMResult } from './structured-types';
+export { RLMAgentCoordinator } from './coordinator';

package/dist/index.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RLM = void 0;
+exports.RLMAgentCoordinator = exports.RLM = void 0;
 var rlm_1 = require("./rlm");
 Object.defineProperty(exports, "RLM", { enumerable: true, get: function () { return rlm_1.RLM; } });
+var coordinator_1 = require("./coordinator");
+Object.defineProperty(exports, "RLMAgentCoordinator", { enumerable: true, get: function () { return coordinator_1.RLMAgentCoordinator; } });

package/dist/rlm.d.ts

@@ -1,5 +1,7 @@
 import { RLMConfig, RLMResult } from './bridge-interface';
 import { BridgeType } from './bridge-factory';
+import { z } from 'zod';
+import { StructuredRLMResult } from './structured-types';
 export declare class RLM {
     private bridge;
     private model;
@@ -8,5 +10,10 @@ export declare class RLM {
     constructor(model: string, rlmConfig?: RLMConfig, bridgeType?: BridgeType);
     private ensureBridge;
     completion(query: string, context: string): Promise<RLMResult>;
+    structuredCompletion<T>(query: string, context: string, schema: z.ZodSchema<T>, options?: {
+        maxRetries?: number;
+        parallelExecution?: boolean;
+    }): Promise<StructuredRLMResult<T>>;
+    private zodToJsonSchema;
     cleanup(): Promise<void>;
 }

package/dist/rlm.js

@@ -32,6 +32,82 @@ class RLM {
             return bridge.completion(this.model, query, context, this.rlmConfig);
         });
     }
+    structuredCompletion(query_1, context_1, schema_1) {
+        return __awaiter(this, arguments, void 0, function* (query, context, schema, options = {}) {
+            var _a, _b;
+            const bridge = yield this.ensureBridge();
+            const jsonSchema = this.zodToJsonSchema(schema);
+            const structuredConfig = {
+                schema: jsonSchema,
+                parallelExecution: (_a = options.parallelExecution) !== null && _a !== void 0 ? _a : true,
+                maxRetries: (_b = options.maxRetries) !== null && _b !== void 0 ? _b : 3
+            };
+            const result = yield bridge.completion(this.model, query, context, Object.assign(Object.assign({}, this.rlmConfig), { structured: structuredConfig }));
+            // Validate result against Zod schema for type safety
+            const validated = schema.parse(result.result);
+            return {
+                result: validated,
+                stats: result.stats
+            };
+        });
+    }
+    zodToJsonSchema(schema) {
+        const def = schema._def;
+        // Check for object type by presence of shape
+        if (def.shape) {
+            const shape = def.shape;
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(shape)) {
+                properties[key] = this.zodToJsonSchema(value);
+                if (!value.isOptional()) {
+                    required.push(key);
+                }
+            }
+            return {
+                type: 'object',
+                properties,
+                required: required.length > 0 ? required : undefined
+            };
+        }
+        // Check for array type - Zod arrays have an 'element' property (or 'type' in older versions)
+        if (def.type === 'array' && (def.element || def.type)) {
+            const itemSchema = def.element || def.type;
+            return {
+                type: 'array',
+                items: this.zodToJsonSchema(itemSchema)
+            };
+        }
+        // Check for enum - Zod enums have a 'type' of 'enum' and 'entries' object
+        if (def.type === 'enum' && def.entries) {
+            return {
+                type: 'string',
+                enum: Object.keys(def.entries)
+            };
+        }
+        // Check for legacy enum with values array
+        if (def.values && Array.isArray(def.values)) {
+            return {
+                type: 'string',
+                enum: def.values
+            };
+        }
+        // Check for optional/nullable
+        if (def.innerType) {
+            const inner = this.zodToJsonSchema(def.innerType);
+            return def.typeName === 'ZodNullable' ? Object.assign(Object.assign({}, inner), { nullable: true }) : inner;
+        }
+        // Detect primitive types
+        const defType = def.type;
+        if (defType === 'string')
+            return { type: 'string' };
+        if (defType === 'number')
+            return { type: 'number' };
+        if (defType === 'boolean')
+            return { type: 'boolean' };
+        // Default fallback
+        return { type: 'string' };
+    }
     cleanup() {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.bridge) {

package/dist/structured-types.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export interface StructuredRLMResult<T> {
+    result: T;
+    stats: {
+        llm_calls: number;
+        iterations: number;
+        depth: number;
+        parsing_retries?: number;
+    };
+}
+export interface SubTask {
+    id: string;
+    query: string;
+    schema: z.ZodSchema<any>;
+    dependencies: string[];
+    path: string[];
+}
+export interface CoordinatorConfig {
+    parallelExecution?: boolean;
+    maxRetries?: number;
+    progressiveValidation?: boolean;
+}
+export interface SchemaDecomposition {
+    subTasks: SubTask[];
+    dependencyGraph: Map<string, string[]>;
+}

package/dist/structured-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/go/cmd/rlm/main.go

@@ -10,15 +10,23 @@ import (
 )
 
 type requestPayload struct {
-	Model   string                 `json:"model"`
-	Query   string                 `json:"query"`
-	Context string                 `json:"context"`
-	Config  map[string]interface{} `json:"config"`
+	Model      string                 `json:"model"`
+	Query      string                 `json:"query"`
+	Context    string                 `json:"context"`
+	Config     map[string]interface{} `json:"config"`
+	Structured *structuredRequest     `json:"structured,omitempty"`
+}
+
+type structuredRequest struct {
+	Schema            *rlm.JSONSchema `json:"schema"`
+	ParallelExecution bool            `json:"parallelExecution"`
+	MaxRetries        int             `json:"maxRetries"`
 }
 
 type responsePayload struct {
-	Result string      `json:"result"`
-	Stats  rlm.RLMStats `json:"stats"`
+	Result           interface{}  `json:"result"`
+	Stats            rlm.RLMStats `json:"stats"`
+	StructuredResult bool         `json:"structured_result,omitempty"`
 }
 
 func main() {
@@ -42,15 +50,39 @@ func main() {
 	config := rlm.ConfigFromMap(req.Config)
 	engine := rlm.New(req.Model, config)
 
-	result, stats, err := engine.Completion(req.Query, req.Context)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
+	var resp responsePayload
+
+	// Handle structured completion if requested
+	if req.Structured != nil {
+		structuredConfig := &rlm.StructuredConfig{
+			Schema:            req.Structured.Schema,
+			ParallelExecution: req.Structured.ParallelExecution,
+			MaxRetries:        req.Structured.MaxRetries,
+		}
+
+		result, stats, err := engine.StructuredCompletion(req.Query, req.Context, structuredConfig)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+
+		resp = responsePayload{
+			Result:           result,
+			Stats:            stats,
+			StructuredResult: true,
+		}
+	} else {
+		// Regular completion
+		result, stats, err := engine.Completion(req.Query, req.Context)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
 
-	resp := responsePayload{
-		Result: result,
-		Stats:  stats,
+		resp = responsePayload{
+			Result: result,
+			Stats:  stats,
+		}
 	}
 
 	payload, err := json.Marshal(resp)

package/go/internal/rlm/structured.go

@@ -0,0 +1,403 @@
+package rlm
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"sync"
+)
+
+// StructuredCompletion executes a structured completion with schema validation
+func (r *RLM) StructuredCompletion(query string, context string, config *StructuredConfig) (map[string]interface{}, RLMStats, error) {
+	if config == nil || config.Schema == nil {
+		return nil, RLMStats{}, fmt.Errorf("structured config and schema are required")
+	}
+
+	// Set defaults
+	if config.MaxRetries == 0 {
+		config.MaxRetries = 3
+	}
+
+	// Decompose schema into sub-tasks
+	subTasks := decomposeSchema(config.Schema)
+
+	// If simple schema or parallel disabled, use direct method
+	if len(subTasks) <= 2 || !config.ParallelExecution {
+		return r.structuredCompletionDirect(query, context, config)
+	}
+
+	// Execute with parallel goroutines
+	return r.structuredCompletionParallel(query, context, config, subTasks)
+}
+
+// structuredCompletionDirect performs a single structured completion
+func (r *RLM) structuredCompletionDirect(query string, context string, config *StructuredConfig) (map[string]interface{}, RLMStats, error) {
+	schemaJSON, _ := json.Marshal(config.Schema)
+	
+	// Build comprehensive prompt with context and schema
+	constraints := generateSchemaConstraints(config.Schema)
+	prompt := fmt.Sprintf(
+		"You are a data extraction assistant. Extract information from the context and return it as JSON.\n\n"+
+		"Context:\n%s\n\n"+
+		"Task: %s\n\n"+
+		"Required JSON Schema:\n%s\n\n"+
+		"%s"+
+		"CRITICAL INSTRUCTIONS:\n"+
+		"1. Return ONLY valid JSON - no explanations, no markdown, no code blocks\n"+
+		"2. The JSON must match the schema EXACTLY\n"+
+		"3. Include ALL required fields\n"+
+		"4. Use correct data types (strings in quotes, numbers without quotes, arrays in [], objects in {})\n"+
+		"5. For arrays, return actual JSON arrays [] not objects\n"+
+		"6. For enum fields, use ONLY the EXACT values listed - do not paraphrase or substitute\n"+
+		"7. Start your response directly with { or [ depending on the schema\n\n"+
+		"JSON Response:",
+		context, query, string(schemaJSON), constraints,
+	)
+
+	var lastErr error
+	stats := RLMStats{Depth: r.currentDepth}
+	
+	for attempt := 0; attempt < config.MaxRetries; attempt++ {
+		// Call LLM directly without REPL
+		messages := []Message{
+			{Role: "system", Content: "You are a data extraction assistant. Respond only with valid JSON objects."},
+			{Role: "user", Content: prompt},
+		}
+		
+		result, err := r.callLLM(messages)
+		stats.LlmCalls++
+		stats.Iterations++
+		
+		if err != nil {
+			lastErr = err
+			continue
+		}
+
+		parsed, err := parseAndValidateJSON(result, config.Schema)
+		if err != nil {
+			lastErr = err
+			if attempt < config.MaxRetries-1 {
+				// Retry with error feedback
+				prompt = fmt.Sprintf(
+					"%s\n\nPrevious attempt failed: %s\n"+
+					"Please fix the error and provide a valid JSON object.",
+					prompt, err.Error(),
+				)
+			}
+			continue
+		}
+
+		stats.ParsingRetries = attempt
+		return parsed, stats, nil
+	}
+
+	return nil, stats, fmt.Errorf("failed to get valid structured output after %d attempts: %v", config.MaxRetries, lastErr)
+}
+
+// structuredCompletionParallel executes sub-tasks in parallel
+func (r *RLM) structuredCompletionParallel(query string, context string, config *StructuredConfig, subTasks []SubTask) (map[string]interface{}, RLMStats, error) {
+	results := make(map[string]interface{})
+	var resultsMutex sync.Mutex
+	
+	var wg sync.WaitGroup
+	errChan := make(chan error, len(subTasks))
+	
+	totalStats := RLMStats{}
+	var statsMutex sync.Mutex
+
+	for _, task := range subTasks {
+		wg.Add(1)
+		go func(t SubTask) {
+			defer wg.Done()
+
+			taskQuery := fmt.Sprintf("%s\n\nSpecific focus: %s", query, t.Query)
+			taskConfig := &StructuredConfig{
+				Schema:            t.Schema,
+				ParallelExecution: false, // Disable nested parallelization
+				MaxRetries:        config.MaxRetries,
+			}
+
+			result, stats, err := r.structuredCompletionDirect(taskQuery, context, taskConfig)
+			if err != nil {
+				errChan <- fmt.Errorf("task %s failed: %w", t.ID, err)
+				return
+			}
+
+			resultsMutex.Lock()
+			fieldName := strings.TrimPrefix(t.ID, "field_")
+			// If result has the __value__ wrapper (non-object type), unwrap it
+			if val, ok := result["__value__"]; ok {
+				results[fieldName] = val
+			} else {
+				results[fieldName] = result
+			}
+			resultsMutex.Unlock()
+
+			statsMutex.Lock()
+			totalStats.LlmCalls += stats.LlmCalls
+			totalStats.Iterations += stats.Iterations
+			if stats.Depth > totalStats.Depth {
+				totalStats.Depth = stats.Depth
+			}
+			totalStats.ParsingRetries += stats.ParsingRetries
+			statsMutex.Unlock()
+		}(task)
+	}
+
+	wg.Wait()
+	close(errChan)
+
+	// Check for errors
+	if len(errChan) > 0 {
+		return nil, totalStats, <-errChan
+	}
+
+	// Validate merged result against full schema
+	if err := validateAgainstSchema(results, config.Schema); err != nil {
+		return nil, totalStats, fmt.Errorf("merged result validation failed: %w", err)
+	}
+
+	return results, totalStats, nil
+}
+
+// decomposeSchema breaks down a schema into independent sub-tasks
+func decomposeSchema(schema *JSONSchema) []SubTask {
+	var subTasks []SubTask
+
+	if schema.Type != "object" || schema.Properties == nil {
+		return subTasks
+	}
+
+	for fieldName, fieldSchema := range schema.Properties {
+		taskID := fmt.Sprintf("field_%s", fieldName)
+		query := generateFieldQuery(fieldName, fieldSchema)
+
+		subTasks = append(subTasks, SubTask{
+			ID:           taskID,
+			Query:        query,
+			Schema:       fieldSchema,
+			Dependencies: []string{},
+			Path:         []string{fieldName},
+		})
+	}
+
+	return subTasks
+}
+
+// generateSchemaConstraints creates human-readable constraint descriptions
+func generateSchemaConstraints(schema *JSONSchema) string {
+	var constraints []string
+	
+	if schema.Type == "object" && schema.Properties != nil {
+		for fieldName, fieldSchema := range schema.Properties {
+			if fieldSchema.Type == "number" {
+				if strings.Contains(strings.ToLower(fieldName), "sentiment") {
+					constraints = append(constraints, fmt.Sprintf("- %s must be a number between 1 and 5 (inclusive)", fieldName))
+				}
+			}
+			if fieldSchema.Enum != nil && len(fieldSchema.Enum) > 0 {
+				constraints = append(constraints, fmt.Sprintf("- %s must be EXACTLY one of these values: %s (use these exact strings, do not modify)", fieldName, strings.Join(fieldSchema.Enum, ", ")))
+			}
+			if fieldSchema.Type == "array" {
+				constraints = append(constraints, fmt.Sprintf("- %s must be a JSON array []", fieldName))
+			}
+		}
+	}
+	
+	// Check nested array items for constraints
+	if schema.Type == "array" && schema.Items != nil {
+		if schema.Items.Type == "object" && schema.Items.Properties != nil {
+			for fieldName, fieldSchema := range schema.Items.Properties {
+				if fieldSchema.Type == "number" && strings.Contains(strings.ToLower(fieldName), "sentiment") {
+					constraints = append(constraints, fmt.Sprintf("- Each item's %s must be between 1 and 5", fieldName))
+				}
+				if fieldSchema.Enum != nil && len(fieldSchema.Enum) > 0 {
+					constraints = append(constraints, fmt.Sprintf("- Each item's %s must be EXACTLY one of these values: %s (copy exactly, do not modify these strings)", fieldName, strings.Join(fieldSchema.Enum, ", ")))
+				}
+			}
+		}
+	}
+	
+	if len(constraints) > 0 {
+		return "CONSTRAINTS:\n" + strings.Join(constraints, "\n") + "\n\n"
+	}
+	return ""
+}
+
+// generateFieldQuery creates a focused query for a specific field
+func generateFieldQuery(fieldName string, schema *JSONSchema) string {
+	fieldQueries := map[string]string{
+		"sentiment":             "Analyze the overall sentiment of this conversation. Provide a sentiment score from 1-5 and a detailed explanation.",
+		"sentimentValue":        "What is the overall sentiment score (1-5) of this conversation?",
+		"sentimentExplanation":  "Explain in 2-3 sentences why the conversation has this sentiment score.",
+		"phrases":               "Extract key phrases that significantly impacted the sentiment, excluding neutral (3-value) phrases. For each phrase, include the sentiment value and the phrase itself (1 sentence).",
+		"keyMoments":            "Identify key moments in the conversation such as churn mentions, personnel changes, competitive mentions, etc. For each moment, provide the phrase and categorize the type.",
+	}
+
+	if query, exists := fieldQueries[fieldName]; exists {
+		return query
+	}
+
+	return fmt.Sprintf("Extract the %s from the conversation.", fieldName)
+}
+
+// parseAndValidateJSON extracts JSON from response and validates against schema  
+func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interface{}, error) {
+	// Remove markdown code blocks if present
+	result = strings.TrimSpace(result)
+	if strings.HasPrefix(result, "```") {
+		// Extract content between ``` markers
+		lines := strings.Split(result, "\n")
+		if len(lines) > 2 {
+			// Remove first line (```json or ```) and last line (```)
+			result = strings.Join(lines[1:len(lines)-1], "\n")
+			result = strings.TrimSpace(result)
+		}
+	}
+	
+	// For non-object schemas (arrays, primitives), handle special cases
+	if schema.Type != "object" {
+		// Try parsing as direct value first
+		var value interface{}
+		parseErr := json.Unmarshal([]byte(result), &value)
+		if parseErr == nil {
+			// Check if it's a map (LLM wrapped the value in an object)
+			if valueMap, ok := value.(map[string]interface{}); ok {
+				// If it's a single-key object, extract the value
+				if len(valueMap) == 1 {
+					for _, v := range valueMap {
+						value = v
+						break
+					}
+				}
+			}
+			
+			// Validate the unwrapped value
+			if err := validateValue(value, schema); err != nil {
+				return nil, err
+			}
+			
+			// Wrap in a map with a temp key
+			return map[string]interface{}{"__value__": value}, nil
+		}
+		
+		return nil, fmt.Errorf("failed to parse JSON: %v", parseErr)
+	}
+	
+	// Try to find the outermost JSON object
+	var parsed map[string]interface{}
+	
+	// First, try to parse the entire trimmed string
+	if err := json.Unmarshal([]byte(result), &parsed); err == nil {
+		if err := validateAgainstSchema(parsed, schema); err != nil {
+			return nil, err
+		}
+		return parsed, nil
+	}
+	
+	// If that fails, try to extract JSON with regex
+	re := regexp.MustCompile(`\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}`)
+	matches := re.FindAllString(result, -1)
+	
+	if len(matches) == 0 {
+		return nil, fmt.Errorf("no JSON object found in response: %s", result)
+	}
+	
+	// Try each match until we find one that validates
+	for _, match := range matches {
+		var candidate map[string]interface{}
+		if err := json.Unmarshal([]byte(match), &candidate); err == nil {
+			if err := validateAgainstSchema(candidate, schema); err == nil {
+				return candidate, nil
+			}
+		}
+	}
+	
+	return nil, fmt.Errorf("no valid JSON object matching schema found in response")
+}
+
+// validateAgainstSchema validates data against a JSON schema
+func validateAgainstSchema(data map[string]interface{}, schema *JSONSchema) error {
+	if schema.Type != "object" {
+		return nil // Only validate object types for now
+	}
+
+	// Check required fields
+	for _, required := range schema.Required {
+		if _, exists := data[required]; !exists {
+			return fmt.Errorf("missing required field: %s", required)
+		}
+	}
+
+	// Validate properties
+	if schema.Properties != nil {
+		for key, fieldSchema := range schema.Properties {
+			value, exists := data[key]
+			if !exists && contains(schema.Required, key) {
+				return fmt.Errorf("missing required field: %s", key)
+			}
+			if exists {
+				if err := validateValue(value, fieldSchema); err != nil {
+					return fmt.Errorf("field %s: %w", key, err)
+				}
+			}
+		}
+	}
+
+	return nil
+}
+
+// validateValue validates a value against a schema
+func validateValue(value interface{}, schema *JSONSchema) error {
+	if value == nil && schema.Nullable {
+		return nil
+	}
+
+	switch schema.Type {
+	case "string":
+		if _, ok := value.(string); !ok {
+			return fmt.Errorf("expected string, got %T", value)
+		}
+	case "number":
+		switch value.(type) {
+		case float64, float32, int, int32, int64:
+			return nil
+		default:
+			return fmt.Errorf("expected number, got %T", value)
+		}
+	case "boolean":
+		if _, ok := value.(bool); !ok {
+			return fmt.Errorf("expected boolean, got %T", value)
+		}
+	case "array":
+		arr, ok := value.([]interface{})
+		if !ok {
+			return fmt.Errorf("expected array, got %T", value)
+		}
+		if schema.Items != nil {
+			for i, item := range arr {
+				if err := validateValue(item, schema.Items); err != nil {
+					return fmt.Errorf("array item %d: %w", i, err)
+				}
+			}
+		}
+	case "object":
+		obj, ok := value.(map[string]interface{})
+		if !ok {
+			return fmt.Errorf("expected object, got %T", value)
+		}
+		return validateAgainstSchema(obj, schema)
+	}
+
+	return nil
+}
+
+func contains(arr []string, item string) bool {
+	for _, v := range arr {
+		if v == item {
+			return true
+		}
+	}
+	return false
+}

package/go/internal/rlm/types.go

@@ -6,9 +6,33 @@ import (
 )
 
 type RLMStats struct {
-	LlmCalls   int `json:"llm_calls"`
-	Iterations int `json:"iterations"`
-	Depth      int `json:"depth"`
+	LlmCalls       int `json:"llm_calls"`
+	Iterations     int `json:"iterations"`
+	Depth          int `json:"depth"`
+	ParsingRetries int `json:"parsing_retries,omitempty"`
+}
+
+type JSONSchema struct {
+	Type       string                 `json:"type"`
+	Properties map[string]*JSONSchema `json:"properties,omitempty"`
+	Items      *JSONSchema            `json:"items,omitempty"`
+	Required   []string               `json:"required,omitempty"`
+	Enum       []string               `json:"enum,omitempty"`
+	Nullable   bool                   `json:"nullable,omitempty"`
+}
+
+type SubTask struct {
+	ID           string
+	Query        string
+	Schema       *JSONSchema
+	Dependencies []string
+	Path         []string
+}
+
+type StructuredConfig struct {
+	Schema            *JSONSchema
+	ParallelExecution bool
+	MaxRetries        int
 }
 
 type Config struct {
@@ -20,6 +44,7 @@ type Config struct {
 	TimeoutSeconds    int
 	Parallel          bool // Enable parallel recursive calls with goroutines
 	UseMetacognitive  bool // Enable step-by-step reasoning guidance in prompts
+	Structured        *StructuredConfig
 	ExtraParams       map[string]interface{}
 }
 
@@ -62,8 +87,8 @@ func ConfigFromMap(config map[string]interface{}) Config {
 			if v, ok := value.(bool); ok {
 				parsed.UseMetacognitive = v
 			}
-		case "pythonia_timeout", "go_binary_path", "bridge":
-			// ignore bridge-only config
+		case "pythonia_timeout", "go_binary_path", "bridge", "structured":
+			// ignore bridge-only config and structured (handled separately)
 		default:
 			parsed.ExtraParams[key] = value
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "recursive-llm-ts",
-  "version": "3.0.1",
-  "description": "TypeScript bridge for recursive-llm: Recursive Language Models for unbounded context processing",
+  "version": "4.0.0",
+  "description": "TypeScript bridge for recursive-llm: Recursive Language Models for unbounded context processing with structured outputs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -24,7 +24,11 @@
     "recursive",
     "context",
     "nlp",
-    "language-model"
+    "language-model",
+    "structured-output",
+    "zod",
+    "schema",
+    "extraction"
   ],
   "author": "",
   "license": "MIT",
@@ -36,7 +40,9 @@
     "url": "https://github.com/jbeck018/recursive-llm-ts/issues"
   },
   "homepage": "https://github.com/jbeck018/recursive-llm-ts#readme",
-  "dependencies": {},
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
   "devDependencies": {
     "@types/node": "^20.11.19",
     "dotenv": "^16.4.5",