@soederpop/luca 0.0.2

package/docs/tutorials/12-assistants.md

@@ -0,0 +1,215 @@
+---
+title: Building Assistants
+tags: [assistants, ai, openai, tools, hooks, conversation, CORE.md]
+---
+
+# Building Assistants
+
+Assistants are AI-powered conversational agents defined by a file-based convention. Each assistant lives in its own folder with a system prompt, tools, hooks, and documentation.
+
+## Directory Structure
+
+```
+assistants/my-assistant/
+├── CORE.md           # System prompt (required)
+├── tools.ts          # Tool definitions with Zod schemas
+├── hooks.ts          # Lifecycle event handlers
+└── docs/             # Internal documentation the assistant can search
+    ├── guide.md
+    └── faq.md
+```
+
+## CORE.md -- The System Prompt
+
+This is the assistant's personality and instructions. It's a markdown file that becomes the system message:
+
+```markdown
+# Customer Support Assistant
+
+You are a helpful customer support agent for Acme Corp. You help users with
+billing questions, account issues, and product information.
+
+Always research internal docs before answering product questions.
+Be polite and concise.
+```
+
+## tools.ts -- Tool Definitions
+
+Define functions that the assistant can call. Each tool has a Zod schema describing its parameters:
+
+```typescript
+const { z } = require('zod')
+
+async function lookupOrder({ orderId }) {
+  // In a real app, query your database
+  return {
+    orderId,
+    status: 'shipped',
+    trackingNumber: 'ABC123',
+    estimatedDelivery: '2024-01-20',
+  }
+}
+
+async function createTicket({ subject, priority, description }) {
+  // Create a support ticket
+  const ticketId = `TICKET-${Date.now()}`
+  return {
+    ticketId,
+    subject,
+    priority,
+    message: `Ticket ${ticketId} created successfully`,
+  }
+}
+
+async function searchProducts({ query, category }) {
+  // Search product catalog
+  return {
+    results: [
+      { name: 'Widget Pro', price: 29.99, inStock: true },
+      { name: 'Widget Lite', price: 19.99, inStock: false },
+    ],
+  }
+}
+
+const schemas = {
+  lookupOrder: z.object({
+    orderId: z.string().describe('The order ID to look up'),
+  }).describe('Look up an order by its ID to get status and tracking info'),
+
+  createTicket: z.object({
+    subject: z.string().describe('Brief ticket subject line'),
+    priority: z.enum(['low', 'medium', 'high']).describe('Ticket priority'),
+    description: z.string().describe('Detailed description of the issue'),
+  }).describe('Create a new support ticket'),
+
+  searchProducts: z.object({
+    query: z.string().describe('Search terms'),
+    category: z.string().optional().describe('Product category filter'),
+  }).describe('Search the product catalog'),
+}
+
+module.exports = { lookupOrder, createTicket, searchProducts, schemas }
+```
+
+**Important:** The function name must match the key in the `schemas` object. The `.describe()` on the schema object itself becomes the tool description that the AI model sees.
+
+## hooks.ts -- Lifecycle Hooks
+
+React to assistant events:
+
+```typescript
+function started() {
+  console.log('[assistant] Session started')
+}
+
+function response(text) {
+  // Called when the assistant produces a text response
+  console.log(`[assistant] ${text.slice(0, 100)}...`)
+}
+
+function toolCall(name, args) {
+  // Called before a tool is executed
+  console.log(`[assistant] Calling tool: ${name}`, args)
+}
+
+function error(err) {
+  console.error('[assistant] Error:', err.message)
+}
+
+module.exports = { started, response, toolCall, error }
+```
+
+## docs/ -- Internal Documentation
+
+The `docs/` folder contains markdown files that the assistant can search using the built-in `researchInternalDocs` tool. This is automatically injected -- you don't need to define it in tools.ts.
+
+```
+docs/
+├── billing-faq.md
+├── product-catalog.md
+├── return-policy.md
+└── troubleshooting.md
+```
+
+In CORE.md, instruct the assistant to use it:
+
+```markdown
+When asked about products, billing, or policies, always use the
+researchInternalDocs tool first to find accurate information before answering.
+```
+
+## Using the Assistant
+
+### In a Script
+
+```typescript
+import container from '@soederpop/luca'
+
+const assistant = container.feature('assistant', {
+  folder: 'assistants/my-assistant',
+  model: 'gpt-4o',
+})
+
+// Ask a question
+const answer = await assistant.ask('What is the return policy?')
+console.log(answer)
+
+// Multi-turn conversation
+const follow = await assistant.ask('And how long does the refund take?')
+console.log(follow)
+
+// Save the conversation
+await assistant.save({ title: 'Return policy inquiry' })
+```
+
+### In an Endpoint
+
+Expose the assistant as an API:
+
+```typescript
+// endpoints/ask.ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+
+export const path = '/api/ask'
+export const description = 'Ask the support assistant a question'
+export const tags = ['assistant']
+
+export const postSchema = z.object({
+  question: z.string().describe('Your question'),
+})
+
+export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+  const assistant = ctx.container.feature('assistant', {
+    folder: 'assistants/my-assistant',
+    model: 'gpt-4o',
+  })
+
+  const answer = await assistant.ask(params.question)
+  return { answer }
+}
+```
+
+### Streaming Responses
+
+```typescript
+const assistant = container.feature('assistant', {
+  folder: 'assistants/my-assistant',
+  model: 'gpt-4o',
+})
+
+// Listen for chunks as they arrive
+assistant.on('chunk', (text) => {
+  process.stdout.write(text)
+})
+
+await assistant.ask('Explain quantum computing')
+```
+
+## Best Practices
+
+1. **Write focused CORE.md prompts** -- tell the assistant exactly what it is and what it should/shouldn't do
+2. **Keep tools simple** -- each tool should do one thing. The AI model is better at composing simple tools than using complex ones
+3. **Use docs/ liberally** -- put all reference material in docs/ so the assistant can look things up rather than relying on the model's training data
+4. **Use Zod `.describe()`** -- the descriptions on schemas and fields are what the model sees to decide when and how to call tools
+5. **Test with real questions** -- ask the assistant the kinds of things real users will ask

package/docs/tutorials/13-introspection.md

@@ -0,0 +1,147 @@
+---
+title: Introspection and Discovery
+tags: [introspection, runtime, discovery, documentation, describe, inspect]
+---
+
+# Introspection and Discovery
+
+One of Luca's defining features is that everything is discoverable at runtime. You don't need to read documentation to learn what's available -- you can ask the system itself.
+
+## Why Introspection Matters
+
+Introspection serves two audiences:
+
+1. **Developers** -- discover APIs while coding, without leaving the REPL or editor
+2. **AI Agents** -- learn the full API surface dynamically, enabling them to use features they weren't explicitly trained on
+
+## Container-Level Introspection
+
+```typescript
+// Structured data about the entire container
+const info = container.inspect()
+// Returns: registries, enabled features, state schema, available helpers
+
+// Human-readable markdown
+const docs = container.inspectAsText()
+```
+
+## Registry-Level Discovery
+
+```typescript
+// What's available?
+container.features.available
+// => ['fs', 'git', 'proc', 'vm', 'ui', 'diskCache', 'contentDb', ...]
+
+// Describe one
+container.features.describe('diskCache')
+// => Markdown documentation for diskCache feature
+
+// Describe everything
+container.features.describeAll()
+// => Full documentation for all registered features
+
+// Structured introspection data
+container.features.introspect('fs')
+// => { methods, getters, state, options, events, ... }
+```
+
+Same API for all registries:
+
+```typescript
+container.servers.available
+container.servers.describe('express')
+
+container.clients.available
+container.clients.describe('rest')
+
+container.commands.available
+container.commands.describe('serve')
+```
+
+## Helper-Level Introspection
+
+Every helper instance can describe itself:
+
+```typescript
+const fs = container.feature('fs')
+
+// Structured data
+const info = fs.introspect()
+// => { className, methods: [...], getters: [...], state: {...}, events: [...] }
+
+// Human-readable markdown
+const docs = fs.introspectAsText()
+```
+
+### What's in the Introspection Data?
+
+- **Class name** and description (from JSDoc)
+- **Methods** -- name, description, parameters, return type
+- **Getters** -- name, description, type
+- **State schema** -- all observable state fields with descriptions
+- **Options schema** -- all configuration options with descriptions and defaults
+- **Events** -- known event names with descriptions
+
+## How It Works
+
+Introspection comes from two sources:
+
+1. **Build-time extraction** -- Luca's build step parses JSDoc comments, method signatures, and getter types from source code using AST analysis. Run `bun run build:introspection` to update this.
+
+2. **Runtime Zod schemas** -- State, options, and events schemas provide descriptions, types, and defaults at runtime via Zod's `.describe()` method.
+
+## Practical Example: Dynamic Tool Generation
+
+An AI agent can use introspection to generate tool definitions for any feature:
+
+```typescript
+// Agent discovers available features
+const available = container.features.available
+
+// Agent learns about a specific feature
+const fsInfo = container.features.introspect('fs')
+
+// fsInfo.methods tells the agent:
+// - readFile(path: string): string
+// - writeFile(path: string, content: string): Promise<string>
+// - walk(basePath: string, options?: WalkOptions): { files: string[], directories: string[] }
+// etc.
+
+// The agent can now use these methods without prior training on the fs feature
+```
+
+## Using Introspection in Your Features
+
+Make your custom features introspectable by:
+
+1. Writing JSDoc on the class, methods, and getters
+2. Using Zod `.describe()` on schema fields
+3. Running `bun run build:introspection` after changes
+
+```typescript
+/**
+ * Manages a pool of database connections with automatic health checking.
+ * Connections are recycled when they become stale or unhealthy.
+ */
+export class ConnectionPool extends Feature<PoolState, PoolOptions> {
+  /**
+   * Acquire a connection from the pool.
+   * Blocks until a connection is available or the timeout is reached.
+   */
+  async acquire(timeout?: number): Promise<Connection> {
+    // ...
+  }
+
+  /** The number of idle connections currently in the pool */
+  get idleCount(): number {
+    // ...
+  }
+
+  /** The number of active connections currently checked out */
+  get activeCount(): number {
+    // ...
+  }
+}
+```
+
+Now `container.features.describe('connectionPool')` returns rich documentation, and `container.features.introspect('connectionPool')` returns structured data -- all extracted from what you already wrote.

package/docs/tutorials/14-type-system.md

@@ -0,0 +1,174 @@
+---
+title: Type System and Module Augmentation
+tags: [types, typescript, zod, module-augmentation, schemas, type-safety]
+---
+
+# Type System and Module Augmentation
+
+Luca's type system ensures that as you add features, clients, servers, and commands, the container's factory methods stay fully typed. This is powered by Zod schemas and TypeScript module augmentation.
+
+## The Pattern
+
+When you register a new helper, you augment the corresponding interface so TypeScript knows about it:
+
+```typescript
+import { Feature, features, FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
+import { z } from 'zod'
+
+// 1. Define your feature
+export class MyCache extends Feature<MyCacheState, MyCacheOptions> {
+  // ...
+}
+
+// 2. Register it
+features.register('myCache', MyCache)
+
+// 3. Augment the interface
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    myCache: typeof MyCache
+  }
+}
+
+// 4. Now fully typed everywhere:
+const cache = container.feature('myCache', { ttl: 3600 })
+//    ^-- TypeScript knows this is MyCache
+//                                  ^-- autocomplete for MyCache options
+```
+
+## Zod Schemas = Types + Runtime Validation
+
+Every schema you define gives you both compile-time types and runtime validation:
+
+```typescript
+// Define once with Zod
+export const UserOptionsSchema = FeatureOptionsSchema.extend({
+  apiKey: z.string().describe('API key for authentication'),
+  timeout: z.number().default(5000).describe('Request timeout in ms'),
+  retries: z.number().default(3).describe('Max retry attempts'),
+})
+
+// Extract the type
+export type UserOptions = z.infer<typeof UserOptionsSchema>
+
+// Use for static typing
+export class UserService extends Feature<UserState, UserOptions> {
+  static override optionsSchema = UserOptionsSchema
+
+  connect() {
+    // this.options is typed: { apiKey: string, timeout: number, retries: number }
+    const { apiKey, timeout } = this.options
+  }
+}
+```
+
+The schema also powers:
+- **Runtime validation** when options are passed to the factory
+- **Introspection** -- `.describe()` text appears in `helper.introspect()`
+- **Documentation** -- field descriptions appear in `container.features.describe('userService')`
+
+## State Typing
+
+```typescript
+const TaskStateSchema = FeatureStateSchema.extend({
+  tasks: z.array(z.object({
+    id: z.string(),
+    title: z.string(),
+    done: z.boolean(),
+  })).default([]),
+  filter: z.enum(['all', 'active', 'done']).default('all'),
+})
+
+type TaskState = z.infer<typeof TaskStateSchema>
+
+class TaskManager extends Feature<TaskState> {
+  static override stateSchema = TaskStateSchema
+
+  addTask(title: string) {
+    const tasks = this.state.get('tasks')
+    //    ^-- typed as Array<{ id: string, title: string, done: boolean }>
+
+    this.state.set('tasks', [...(tasks || []), { id: '1', title, done: false }])
+    //                       ^-- TypeScript validates the shape
+  }
+}
+```
+
+## Module Augmentation for All Helper Types
+
+The pattern is the same for features, clients, servers, and commands:
+
+```typescript
+// Features
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    myFeature: typeof MyFeature
+  }
+}
+
+// Clients
+declare module '@soederpop/luca' {
+  interface AvailableClients {
+    myClient: typeof MyClient
+  }
+}
+
+// Servers
+declare module '@soederpop/luca' {
+  interface AvailableServers {
+    myServer: typeof MyServer
+  }
+}
+
+// Commands
+declare module '@soederpop/luca' {
+  interface AvailableCommands {
+    myCommand: typeof MyCommand
+  }
+}
+```
+
+## Using .describe() Effectively
+
+```typescript
+const ConfigSchema = z.object({
+  host: z.string().describe('Database hostname or IP address'),
+  port: z.number().default(5432).describe('Database port'),
+  database: z.string().describe('Database name to connect to'),
+  ssl: z.boolean().default(false).describe('Whether to use SSL/TLS for the connection'),
+  pool: z.object({
+    min: z.number().default(2).describe('Minimum connections to keep open'),
+    max: z.number().default(10).describe('Maximum connections allowed'),
+  }).describe('Connection pool configuration'),
+})
+```
+
+These descriptions are not just for humans reading the code -- they show up in:
+- `container.features.describe('db')` output
+- `container.features.introspect('db')` data
+- OpenAPI specs when used in endpoint schemas
+- AI agent tool descriptions
+
+## The Full Typed Flow
+
+```typescript
+// 1. You define a feature with schemas
+export class Analytics extends Feature<AnalyticsState, AnalyticsOptions> { ... }
+
+// 2. You register + augment
+features.register('analytics', Analytics)
+declare module '@soederpop/luca' {
+  interface AvailableFeatures { analytics: typeof Analytics }
+}
+
+// 3. Now every interaction is typed:
+const a = container.feature('analytics', { trackingId: 'UA-123' })
+//    ^-- Analytics instance     ^-- autocomplete: 'analytics'
+//                                         ^-- type error if wrong options
+
+a.state.get('pageViews')  // typed by AnalyticsState
+a.on('pageView', ...)     // typed by event definitions
+a.track('click', { ... }) // typed by Analytics methods
+```
+
+This is the core principle: **never break the type system.** Every step of `container.feature('name', options)` should give you autocomplete, type checking, and documentation.