@soederpop/luca 0.0.28 → 0.0.29

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-23T07:45:58.711Z
+// Generated at: 2026-03-24T01:41:40.771Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -1633,6 +1633,151 @@ for (const raw of commands) {
 ## Summary
 
 This demo covered the three main methods of the \`nlp\` feature: \`parse()\` for quick structural extraction from voice commands, \`analyze()\` for detailed POS tagging and entity recognition, and \`understand()\` for a combined view of both. The feature is well suited for building voice command interpreters, chatbot intent classifiers, and text analysis pipelines.
+`,
+  "structured-output-with-assistants.md": `---
+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.
 `,
   "networking.md": `---
 title: "networking"

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
 export const BUILD_SHA = 'c1e466d'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-23T07:45:58Z'
+export const BUILD_DATE = '2026-03-24T01:41:40Z'

package/src/introspection/generated.agi.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-23T07:45:57.079Z
+// Generated at: 2026-03-24T01:41:39.242Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -5773,6 +5773,32 @@ setBuildTimeData('features.fs', {
         }
       ]
     },
+    "isSymlink": {
+      "description": "Checks if a path is a symbolic link.",
+      "parameters": {
+        "path": {
+          "type": "string",
+          "description": "The path to check"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "returns": "boolean"
+    },
+    "realpath": {
+      "description": "Resolves a symlink to its real path. Returns the resolved path as-is if not a symlink.",
+      "parameters": {
+        "path": {
+          "type": "string",
+          "description": "The path to resolve"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "returns": "string"
+    },
     "stat": {
       "description": "Synchronously returns the stat object for a file or directory.",
       "parameters": {
@@ -11690,6 +11716,10 @@ setBuildTimeData('features.conversation', {
             "maxTokens": {
               "type": "number",
               "description": ""
+            },
+            "schema": {
+              "type": "z.ZodType",
+              "description": "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."
             }
           }
         }
@@ -11807,6 +11837,21 @@ setBuildTimeData('features.conversation', {
       "description": "Event emitted by Conversation",
       "arguments": {}
     },
+    "toolError": {
+      "name": "toolError",
+      "description": "Event emitted by Conversation",
+      "arguments": {}
+    },
+    "toolCall": {
+      "name": "toolCall",
+      "description": "Event emitted by Conversation",
+      "arguments": {}
+    },
+    "toolResult": {
+      "name": "toolResult",
+      "description": "Event emitted by Conversation",
+      "arguments": {}
+    },
     "turnStart": {
       "name": "turnStart",
       "description": "Event emitted by Conversation",
@@ -11842,21 +11887,6 @@ setBuildTimeData('features.conversation', {
       "description": "Event emitted by Conversation",
       "arguments": {}
     },
-    "toolError": {
-      "name": "toolError",
-      "description": "Event emitted by Conversation",
-      "arguments": {}
-    },
-    "toolCall": {
-      "name": "toolCall",
-      "description": "Event emitted by Conversation",
-      "arguments": {}
-    },
-    "toolResult": {
-      "name": "toolResult",
-      "description": "Event emitted by Conversation",
-      "arguments": {}
-    },
     "toolCallsEnd": {
       "name": "toolCallsEnd",
       "description": "Event emitted by Conversation",
@@ -12276,6 +12306,24 @@ setBuildTimeData('features.assistant', {
   "shortcut": "features.assistant",
   "className": "Assistant",
   "methods": {
+    "intercept": {
+      "description": "Register an interceptor at a given point in the pipeline.",
+      "parameters": {
+        "point": {
+          "type": "K",
+          "description": "The interception point"
+        },
+        "fn": {
+          "type": "InterceptorFn<InterceptorPoints[K]>",
+          "description": "Middleware function receiving (ctx, next)"
+        }
+      },
+      "required": [
+        "point",
+        "fn"
+      ],
+      "returns": "this"
+    },
     "afterInitialize": {
       "description": "Called immediately after the assistant is constructed. Synchronously loads the system prompt, tools, and hooks, then binds hooks as event listeners so every emitted event automatically invokes its corresponding hook.",
       "parameters": {},
@@ -20191,6 +20239,32 @@ export const introspectionData = [
           }
         ]
       },
+      "isSymlink": {
+        "description": "Checks if a path is a symbolic link.",
+        "parameters": {
+          "path": {
+            "type": "string",
+            "description": "The path to check"
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "returns": "boolean"
+      },
+      "realpath": {
+        "description": "Resolves a symlink to its real path. Returns the resolved path as-is if not a symlink.",
+        "parameters": {
+          "path": {
+            "type": "string",
+            "description": "The path to resolve"
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "returns": "string"
+      },
       "stat": {
         "description": "Synchronously returns the stat object for a file or directory.",
         "parameters": {
@@ -26081,6 +26155,10 @@ export const introspectionData = [
               "maxTokens": {
                 "type": "number",
                 "description": ""
+              },
+              "schema": {
+                "type": "z.ZodType",
+                "description": "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."
               }
             }
           }
@@ -26198,6 +26276,21 @@ export const introspectionData = [
         "description": "Event emitted by Conversation",
         "arguments": {}
       },
+      "toolError": {
+        "name": "toolError",
+        "description": "Event emitted by Conversation",
+        "arguments": {}
+      },
+      "toolCall": {
+        "name": "toolCall",
+        "description": "Event emitted by Conversation",
+        "arguments": {}
+      },
+      "toolResult": {
+        "name": "toolResult",
+        "description": "Event emitted by Conversation",
+        "arguments": {}
+      },
       "turnStart": {
         "name": "turnStart",
         "description": "Event emitted by Conversation",
@@ -26233,21 +26326,6 @@ export const introspectionData = [
         "description": "Event emitted by Conversation",
         "arguments": {}
       },
-      "toolError": {
-        "name": "toolError",
-        "description": "Event emitted by Conversation",
-        "arguments": {}
-      },
-      "toolCall": {
-        "name": "toolCall",
-        "description": "Event emitted by Conversation",
-        "arguments": {}
-      },
-      "toolResult": {
-        "name": "toolResult",
-        "description": "Event emitted by Conversation",
-        "arguments": {}
-      },
       "toolCallsEnd": {
         "name": "toolCallsEnd",
         "description": "Event emitted by Conversation",
@@ -26663,6 +26741,24 @@ export const introspectionData = [
     "shortcut": "features.assistant",
     "className": "Assistant",
     "methods": {
+      "intercept": {
+        "description": "Register an interceptor at a given point in the pipeline.",
+        "parameters": {
+          "point": {
+            "type": "K",
+            "description": "The interception point"
+          },
+          "fn": {
+            "type": "InterceptorFn<InterceptorPoints[K]>",
+            "description": "Middleware function receiving (ctx, next)"
+          }
+        },
+        "required": [
+          "point",
+          "fn"
+        ],
+        "returns": "this"
+      },
       "afterInitialize": {
         "description": "Called immediately after the assistant is constructed. Synchronously loads the system prompt, tools, and hooks, then binds hooks as event listeners so every emitted event automatically invokes its corresponding hook.",
         "parameters": {},