@soederpop/luca 0.0.28 → 0.0.29

package/docs/examples/structured-output-with-assistants.md

@@ -0,0 +1,144 @@
+---
+title: "Structured Output with Assistants"
+tags: [assistant, conversation, structured-output, zod, openai]
+lastTested: null
+lastTestPassed: null
+---
+
+# Structured Output with Assistants
+
+Get typed, schema-validated JSON responses from OpenAI instead of raw text strings.
+
+## Overview
+
+OpenAI's Structured Outputs feature constrains the model to return JSON that exactly matches a schema you provide. Combined with Zod, this means `ask()` can return parsed objects instead of strings — no regex parsing, no "please respond in JSON", no malformed output.
+
+Pass a `schema` option to `ask()` and the response comes back as a parsed object guaranteed to match your schema.
+
+## Basic: Extract Structured Data
+
+The simplest use case — ask a question and get structured data back.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful data extraction assistant.' }]
+})
+
+const result = await conversation.ask('The founders of Apple are Steve Jobs, Steve Wozniak, and Ronald Wayne. They started it in 1976 in Los Altos, California.', {
+  schema: z.object({
+    company: z.string(),
+    foundedYear: z.number(),
+    location: z.string(),
+    founders: z.array(z.string()),
+  }).describe('CompanyInfo')
+})
+
+console.log('Company:', result.company)
+console.log('Founded:', result.foundedYear)
+console.log('Location:', result.location)
+console.log('Founders:', result.founders)
+```
+
+The `.describe()` on the schema gives OpenAI the schema name — keep it short and descriptive.
+
+## Enums and Categorization
+
+Structured outputs work great for classification tasks where you want the model to pick from a fixed set of values.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful assistant.' }]
+})
+
+const sentiment = await conversation.ask('I absolutely love this product, it changed my life!', {
+  schema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral', 'mixed']),
+    confidence: z.number(),
+    reasoning: z.string(),
+  }).describe('SentimentAnalysis')
+})
+
+console.log('Sentiment:', sentiment.sentiment)
+console.log('Confidence:', sentiment.confidence)
+console.log('Reasoning:', sentiment.reasoning)
+```
+
+Because the model is constrained by the schema, `sentiment` will always be one of the four allowed values.
+
+## Nested Objects and Arrays
+
+Schemas can be as complex as you need. Here we extract a structured analysis with nested objects.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a technical analyst.' }]
+})
+
+const analysis = await conversation.ask(
+  'TypeScript 5.5 introduced inferred type predicates, which automatically narrow types in filter callbacks. It also added isolated declarations for faster builds in monorepos, and a new regex syntax checking feature.',
+  {
+    schema: z.object({
+      subject: z.string(),
+      version: z.string(),
+      features: z.array(z.object({
+        name: z.string(),
+        category: z.enum(['type-system', 'performance', 'developer-experience', 'syntax', 'other']),
+        summary: z.string(),
+      })),
+      featureCount: z.number(),
+    }).describe('ReleaseAnalysis')
+  }
+)
+
+console.log('Subject:', analysis.subject, analysis.version)
+console.log('Features:')
+for (const f of analysis.features) {
+  console.log(`  [${f.category}] ${f.name}: ${f.summary}`)
+}
+console.log('Total features:', analysis.featureCount)
+```
+
+Every level of nesting is validated — the model cannot return a feature without a category or skip required fields.
+
+## With an Assistant
+
+Structured outputs work the same way through the assistant API. The schema passes straight through to the underlying conversation.
+
+```ts
+const { z } = container
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a code review assistant. You analyze code snippets and provide structured feedback.',
+  model: 'gpt-4.1-mini',
+})
+
+const review = await assistant.ask(
+  'Review this: function add(a, b) { return a + b }',
+  {
+    schema: z.object({
+      issues: z.array(z.object({
+        severity: z.enum(['info', 'warning', 'error']),
+        message: z.string(),
+      })),
+      suggestion: z.string(),
+      score: z.number(),
+    }).describe('CodeReview')
+  }
+)
+
+console.log('Score:', review.score)
+console.log('Suggestion:', review.suggestion)
+console.log('Issues:')
+for (const issue of review.issues) {
+  console.log(`  [${issue.severity}] ${issue.message}`)
+}
+```
+
+## Summary
+
+This demo covered extracting structured data, classification with enums, nested schema validation, and using structured outputs through both the conversation and assistant APIs. The key is passing a Zod schema via `{ schema }` in the options to `ask()` — OpenAI guarantees the response matches, and you get a parsed object back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",

package/src/agi/features/assistant.ts

@@ -7,6 +7,7 @@ import type { AGIContainer } from '../container.server.js'
 import type { ContentDb } from '@soederpop/luca/node'
 import type { ConversationHistory, ConversationMeta } from './conversation-history'
 import hashObject from '../../hash-object.js'
+import { InterceptorChain, type InterceptorFn, type InterceptorPoints, type InterceptorPoint } from '../lib/interceptor-chain.js'
 
 declare module '@soederpop/luca/feature' {
 	interface AvailableFeatures {
@@ -113,6 +114,26 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	static { Feature.register(this, 'assistant') }
 
+	readonly interceptors = {
+		beforeAsk: new InterceptorChain<InterceptorPoints['beforeAsk']>(),
+		beforeTurn: new InterceptorChain<InterceptorPoints['beforeTurn']>(),
+		beforeToolCall: new InterceptorChain<InterceptorPoints['beforeToolCall']>(),
+		afterToolCall: new InterceptorChain<InterceptorPoints['afterToolCall']>(),
+		beforeResponse: new InterceptorChain<InterceptorPoints['beforeResponse']>(),
+	}
+
+	/**
+	 * Register an interceptor at a given point in the pipeline.
+	 *
+	 * @param point - The interception point
+	 * @param fn - Middleware function receiving (ctx, next)
+	 * @returns this, for chaining
+	 */
+	intercept<K extends InterceptorPoint>(point: K, fn: InterceptorFn<InterceptorPoints[K]>): this {
+		this.interceptors[point].add(fn as any)
+		return this
+	}
+
 	/** @returns Default state with the assistant not started, zero conversations, and the resolved folder path. */
 	override get initialState(): AssistantState {
 		return {
@@ -911,6 +932,38 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		this.conversation.on('toolResult', (name: string, result: any) => this.emit('toolResult', name, result))
 		this.conversation.on('toolError', (name: string, error: any) => this.emit('toolError', name, error))
 
+		// Install interceptor-aware tool executor on the conversation
+		this.conversation.toolExecutor = async (name: string, args: Record<string, any>, handler: (...a: any[]) => Promise<any>) => {
+			const ctx = { name, args, result: undefined as string | undefined, error: undefined, skip: false }
+
+			await this.interceptors.beforeToolCall.run(ctx, async () => {})
+
+			if (ctx.skip) {
+				const result = ctx.result ?? JSON.stringify({ skipped: true })
+				this.emit('toolResult', ctx.name, result)
+				return result
+			}
+
+			try {
+				this.emit('toolCall', ctx.name, ctx.args)
+				const output = await handler(ctx.args)
+				ctx.result = typeof output === 'string' ? output : JSON.stringify(output)
+			} catch (err: any) {
+				ctx.error = err
+				ctx.result = JSON.stringify({ error: err.message || String(err) })
+			}
+
+			await this.interceptors.afterToolCall.run(ctx, async () => {})
+
+			if (ctx.error && !ctx.result?.includes('"error"')) {
+				this.emit('toolError', ctx.name, ctx.error)
+			} else {
+				this.emit('toolResult', ctx.name, ctx.result!)
+			}
+
+			return ctx.result!
+		}
+
 		// Load conversation history for non-lifecycle modes
 		await this.loadConversationHistory()
 
@@ -961,7 +1014,23 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			question = this.prependTimestamp(question)
 		}
 
-		const result = await this.conversation.ask(question, options)
+		// Run beforeAsk interceptors — they can rewrite the question or short-circuit
+		if (this.interceptors.beforeAsk.hasInterceptors) {
+			const ctx = { question, options } as InterceptorPoints['beforeAsk']
+			await this.interceptors.beforeAsk.run(ctx, async () => {})
+			if (ctx.result !== undefined) return ctx.result
+			question = ctx.question
+			options = ctx.options
+		}
+
+		let result = await this.conversation.ask(question, options)
+
+		// Run beforeResponse interceptors — they can rewrite the final text
+		if (this.interceptors.beforeResponse.hasInterceptors) {
+			const ctx = { text: result }
+			await this.interceptors.beforeResponse.run(ctx, async () => {})
+			result = ctx.text
+		}
 
 		// Auto-save for non-lifecycle modes
 		if (this.options.historyMode !== 'lifecycle' && this.state.get('threadId')) {

package/src/agi/features/conversation.ts

@@ -125,6 +125,44 @@ export type ConversationState = z.infer<typeof ConversationStateSchema>
 
 export type AskOptions = {
 	maxTokens?: number
+	/**
+	 * When provided, enables OpenAI Structured Outputs. The model is constrained
+	 * to return JSON matching this Zod schema. The return value of ask() will be
+	 * the parsed object instead of a raw string.
+	 */
+	schema?: z.ZodType
+}
+
+/**
+ * Recursively set `additionalProperties: false` on every object-type node
+ * in a JSON Schema tree. OpenAI strict mode requires this at every level.
+ * Also ensures every object has a `required` array listing all its property keys.
+ */
+function strictifySchema(schema: Record<string, any>): Record<string, any> {
+	const clone = { ...schema }
+
+	if (clone.type === 'object' && clone.properties) {
+		clone.additionalProperties = false
+		clone.required = Object.keys(clone.properties)
+		const props: Record<string, any> = {}
+		for (const [key, val] of Object.entries(clone.properties)) {
+			props[key] = strictifySchema(val as Record<string, any>)
+		}
+		clone.properties = props
+	}
+
+	if (clone.items) {
+		clone.items = strictifySchema(clone.items)
+	}
+
+	// anyOf / oneOf / allOf
+	for (const combiner of ['anyOf', 'oneOf', 'allOf'] as const) {
+		if (Array.isArray(clone[combiner])) {
+			clone[combiner] = clone[combiner].map((s: Record<string, any>) => strictifySchema(s))
+		}
+	}
+
+	return clone
 }
 
 /**
@@ -151,6 +189,16 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 	static { Feature.register(this, 'conversation') }
 
+	/**
+	 * Pluggable tool executor. Called for each tool invocation with the tool
+	 * name, parsed args, and the default handler. Return the serialized result string.
+	 * The Assistant replaces this to wire in beforeToolCall/afterToolCall interceptors.
+	 */
+	toolExecutor: ((name: string, args: Record<string, any>, handler: (...args: any[]) => Promise<any>) => Promise<string>) | null = null
+
+	/** The active structured output schema for the current ask() call, if any. */
+	private _activeSchema: z.ZodType | null = null
+
 	/** Resolved max tokens: per-call override > options-level > undefined (no limit). */
 	private get maxTokens(): number | undefined {
 		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? undefined
@@ -419,6 +467,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	 */
 	async ask(content: string | ContentPart[], options?: AskOptions): Promise<string> {
 		this.state.set('callMaxTokens', options?.maxTokens ?? null)
+		this._activeSchema = options?.schema ?? null
 
 		// Auto-compact before adding the new message
 		if (this.options.autoCompact) {
@@ -436,6 +485,8 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.emit('userMessage', content)
 
 		try {
+			let raw: string
+
 			if (this.apiMode === 'responses') {
 				const previousResponseId = this.state.get('lastResponseId') || undefined
 				let input: OpenAI.Responses.ResponseInput
@@ -449,17 +500,31 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 					input = this.messagesToResponsesInput()
 				}
 
-				return await this.runResponsesLoop({
+				raw = await this.runResponsesLoop({
 					turn: 1,
 					accumulated: '',
 					input,
 					previousResponseId,
 				})
+			} else {
+				raw = await this.runChatCompletionLoop({ turn: 1, accumulated: '' })
 			}
 
-			return await this.runChatCompletionLoop({ turn: 1, accumulated: '' })
+			// When a structured output schema is active, parse the JSON response
+			if (this._activeSchema) {
+				try {
+					const parsed = JSON.parse(raw)
+					return parsed
+				} catch {
+					// Model returned something that isn't valid JSON — return raw
+					return raw
+				}
+			}
+
+			return raw
 		} finally {
 			this.state.set('callMaxTokens', null)
+			this._activeSchema = null
 		}
 	}
 
@@ -545,6 +610,28 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return input
 	}
 
+	/**
+	 * Build the OpenAI response_format / text.format config from the active Zod schema.
+	 * Returns undefined when no schema is active.
+	 */
+	private get structuredOutputConfig(): { name: string; schema: Record<string, any>; strict: true } | undefined {
+		if (!this._activeSchema) return undefined
+
+		const raw = (this._activeSchema as any).toJSONSchema() as Record<string, any>
+		const strict = strictifySchema(raw)
+
+		// Derive a name from the schema description or fall back to a default.
+		// OpenAI requires [a-zA-Z0-9_-] max 64 chars.
+		const desc = raw.description || 'structured_output'
+		const name = desc.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64)
+
+		return {
+			name,
+			schema: { type: strict.type || 'object', properties: strict.properties, required: strict.required, additionalProperties: false },
+			strict: true,
+		}
+	}
+
 	/** Returns the OpenAI client instance from the container. */
 	get openai() {
 		let baseURL = this.options.clientOptions?.baseURL ? this.options.clientOptions.baseURL : undefined
@@ -603,6 +690,40 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		})
 	}
 
+	/**
+	 * Execute a single tool call, routing through the pluggable toolExecutor
+	 * if one is set (e.g. by the Assistant's interceptor chain).
+	 */
+	private async executeTool(toolName: string, rawArgs: string): Promise<string> {
+		const tool = this.tools[toolName]
+		const callCount = (this.state.get('toolCalls') || 0) + 1
+		this.state.set('toolCalls', callCount)
+
+		if (!tool) {
+			const result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
+			this.emit('toolError', toolName, result)
+			return result
+		}
+
+		if (this.toolExecutor) {
+			const args = rawArgs ? JSON.parse(rawArgs) : {}
+			return this.toolExecutor(toolName, args, tool.handler)
+		}
+
+		try {
+			const args = rawArgs ? JSON.parse(rawArgs) : {}
+			this.emit('toolCall', toolName, args)
+			const output = await tool.handler(args)
+			const result = typeof output === 'string' ? output : JSON.stringify(output)
+			this.emit('toolResult', toolName, result)
+			return result
+		} catch (err: any) {
+			const result = JSON.stringify({ error: err.message || String(err) })
+			this.emit('toolError', toolName, err)
+			return result
+		}
+	}
+
 	/**
 	 * Runs the streaming Responses API loop. Handles local function calls by
 	 * executing handlers and submitting `function_call_output` items until
@@ -625,6 +746,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.state.set('streaming', true)
 		this.emit('turnStart', { turn, isFollowUp: turn > 1 })
 
+		const textFormat = this.structuredOutputConfig
+			? { text: { format: { type: 'json_schema' as const, ...this.structuredOutputConfig } } }
+			: {}
+
 		try {
 			const stream = await this.openai.raw.responses.create({
 				model: this.model as OpenAI.Responses.ResponseCreateParams['model'],
@@ -634,6 +759,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 				...(toolsParam ? { tools: toolsParam, tool_choice: 'auto', parallel_tool_calls: true } : {}),
 				...(this.responsesInstructions ? { instructions: this.responsesInstructions } : {}),
 				...(this.maxTokens ? { max_output_tokens: this.maxTokens } : {}),
+				...textFormat,
 			})
 
 			for await (const event of stream) {
@@ -690,27 +816,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 			const functionOutputs: OpenAI.Responses.ResponseInputItem.FunctionCallOutput[] = []
 			for (const call of functionCalls) {
-				const toolName = call.name
-				const tool = this.tools[toolName]
-				const callCount = (this.state.get('toolCalls') || 0) + 1
-				this.state.set('toolCalls', callCount)
-
-				let result: string
-				if (!tool) {
-					result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
-					this.emit('toolError', toolName, result)
-				} else {
-					try {
-						const args = call.arguments ? JSON.parse(call.arguments) : {}
-						this.emit('toolCall', toolName, args)
-						const output = await tool.handler(args)
-						result = typeof output === 'string' ? output : JSON.stringify(output)
-						this.emit('toolResult', toolName, result)
-					} catch (err: any) {
-						result = JSON.stringify({ error: err.message || String(err) })
-						this.emit('toolError', toolName, err)
-					}
-				}
+				const result = await this.executeTool(call.name, call.arguments || '{}')
 
 				this.pushMessage({
 					role: 'tool',
@@ -785,6 +891,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		let turnContent = ''
 		let toolCalls: Array<{ id: string; function: { name: string; arguments: string }; type: 'function' }> = []
 
+		const responseFormat = this.structuredOutputConfig
+			? { response_format: { type: 'json_schema' as const, json_schema: this.structuredOutputConfig } }
+			: {}
+
 		try {
 			const stream = await this.openai.raw.chat.completions.create({
 				model: this.model,
@@ -792,6 +902,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 				stream: true,
 				...(toolsParam ? { tools: toolsParam, tool_choice: 'auto' } : {}),
 				...(this.maxTokens ? { max_tokens: this.maxTokens } : {}),
+				...responseFormat,
 			})
 
 			for await (const chunk of stream) {
@@ -850,28 +961,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			this.emit('toolCallsStart', toolCalls)
 
 			for (const tc of toolCalls) {
-				const toolName = tc.function.name
-				const tool = this.tools[toolName]
-				const callCount = (this.state.get('toolCalls') || 0) + 1
-				this.state.set('toolCalls', callCount)
-
-				let result: string
-
-				if (!tool) {
-					result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
-					this.emit('toolError', toolName, result)
-				} else {
-					try {
-						const args = JSON.parse(tc.function.arguments)
-						this.emit('toolCall', toolName, args)
-						const output = await tool.handler(args)
-						result = typeof output === 'string' ? output : JSON.stringify(output)
-						this.emit('toolResult', toolName, result)
-					} catch (err: any) {
-						result = JSON.stringify({ error: err.message || String(err) })
-						this.emit('toolError', toolName, err)
-					}
-				}
+				const result = await this.executeTool(tc.function.name, tc.function.arguments)
 
 				const toolMessage: OpenAI.Chat.Completions.ChatCompletionToolMessageParam = {
 					role: 'tool',

package/src/agi/lib/interceptor-chain.ts

@@ -0,0 +1,79 @@
+/**
+ * A composable middleware chain. Each interceptor receives a mutable
+ * context and a `next` function. Calling `next()` continues the chain;
+ * skipping it short-circuits.
+ */
+
+export type InterceptorFn<T> = (ctx: T, next: () => Promise<void>) => Promise<void>
+
+export class InterceptorChain<T> {
+	private fns: InterceptorFn<T>[] = []
+
+	add(fn: InterceptorFn<T>): void {
+		this.fns.push(fn)
+	}
+
+	remove(fn: InterceptorFn<T>): void {
+		const idx = this.fns.indexOf(fn)
+		if (idx !== -1) this.fns.splice(idx, 1)
+	}
+
+	get hasInterceptors(): boolean {
+		return this.fns.length > 0
+	}
+
+	get size(): number {
+		return this.fns.length
+	}
+
+	async run(ctx: T, final: () => Promise<void>): Promise<void> {
+		let index = 0
+		const fns = this.fns
+
+		const next = async (): Promise<void> => {
+			if (index < fns.length) {
+				const fn = fns[index++]!
+				await fn(ctx, next)
+			} else {
+				await final()
+			}
+		}
+
+		await next()
+	}
+}
+
+export interface BeforeAskCtx {
+	question: string | any[]
+	options?: any
+	result?: string
+}
+
+export interface ToolCallCtx {
+	name: string
+	args: Record<string, any>
+	result?: string
+	error?: any
+	skip?: boolean
+}
+
+export interface BeforeResponseCtx {
+	text: string
+}
+
+export interface BeforeTurnCtx {
+	turn: number
+	isFollowUp: boolean
+	messages: any[]
+	skip?: boolean
+}
+
+export interface InterceptorPoints {
+	beforeAsk: BeforeAskCtx
+	beforeTurn: BeforeTurnCtx
+	beforeToolCall: ToolCallCtx
+	afterToolCall: ToolCallCtx
+	beforeResponse: BeforeResponseCtx
+}
+
+export type InterceptorPoint = keyof InterceptorPoints