luca 3.0.0 → 3.1.0

package/docs/apis/features/agi/conversation.md

@@ -1,548 +0,0 @@
-# Conversation (features.conversation)
-
-A self-contained conversation with OpenAI that supports streaming, tool calling, and message state management.
-
-## Usage
-
-```ts
-container.feature('conversation', {
-  // A unique identifier for the conversation
-  id,
-  // A human-readable title for the conversation
-  title,
-  // A unique identifier for threads, an arbitrary grouping mechanism
-  thread,
-  // Any available OpenAI model
-  model,
-  // Initial message history to seed the conversation
-  history,
-  // Tools the model can call during conversation
-  tools,
-  // Remote MCP servers keyed by server label
-  mcpServers,
-  // Completion API mode. auto uses Responses unless local=true
-  api,
-  // Tags for categorizing and searching this conversation
-  tags,
-  // Arbitrary metadata to attach to this conversation
-  metadata,
-  // Options for the OpenAI client
-  clientOptions,
-  // Whether to use the local ollama models instead of the remote OpenAI models
-  local,
-  // Maximum number of output tokens per completion (default 512)
-  maxTokens,
-  // Sampling temperature (0-2). Higher = more random, lower = more deterministic
-  temperature,
-  // Nucleus sampling cutoff (0-1). Lower = more focused
-  topP,
-  // Top-K sampling. Only supported by local/Anthropic models
-  topK,
-  // Frequency penalty (-2 to 2). Positive = discourage repetition
-  frequencyPenalty,
-  // Presence penalty (-2 to 2). Positive = encourage new topics
-  presencePenalty,
-  // Stop sequences — generation halts when any of these strings is produced
-  stop,
-  // Enable automatic compaction when input tokens approach the context limit
-  autoCompact,
-  // Fraction of context window at which auto-compact triggers (default 0.8)
-  compactThreshold,
-  // Override the inferred context window size for this model
-  contextWindow,
-  // Number of recent messages to preserve after compaction (default 4)
-  compactKeepRecent,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | A unique identifier for the conversation |
-| `title` | `string` | A human-readable title for the conversation |
-| `thread` | `string` | A unique identifier for threads, an arbitrary grouping mechanism |
-| `model` | `string` | Any available OpenAI model |
-| `history` | `array` | Initial message history to seed the conversation |
-| `tools` | `object` | Tools the model can call during conversation |
-| `mcpServers` | `object` | Remote MCP servers keyed by server label |
-| `api` | `string` | Completion API mode. auto uses Responses unless local=true |
-| `tags` | `array` | Tags for categorizing and searching this conversation |
-| `metadata` | `object` | Arbitrary metadata to attach to this conversation |
-| `clientOptions` | `object` | Options for the OpenAI client |
-| `local` | `boolean` | Whether to use the local ollama models instead of the remote OpenAI models |
-| `maxTokens` | `number` | Maximum number of output tokens per completion (default 512) |
-| `temperature` | `number` | Sampling temperature (0-2). Higher = more random, lower = more deterministic |
-| `topP` | `number` | Nucleus sampling cutoff (0-1). Lower = more focused |
-| `topK` | `number` | Top-K sampling. Only supported by local/Anthropic models |
-| `frequencyPenalty` | `number` | Frequency penalty (-2 to 2). Positive = discourage repetition |
-| `presencePenalty` | `number` | Presence penalty (-2 to 2). Positive = encourage new topics |
-| `stop` | `array` | Stop sequences — generation halts when any of these strings is produced |
-| `autoCompact` | `boolean` | Enable automatic compaction when input tokens approach the context limit |
-| `compactThreshold` | `number` | Fraction of context window at which auto-compact triggers (default 0.8) |
-| `contextWindow` | `number` | Override the inferred context window size for this model |
-| `compactKeepRecent` | `number` | Number of recent messages to preserve after compaction (default 4) |
-
-## Methods
-
-### addTool
-
-Add or replace a single tool by name. Uses the same format as tools passed at construction time.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | Parameter name |
-| `tool` | `ConversationTool` | ✓ | Parameter tool |
-
-`ConversationTool` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `handler` | `(...args: any[]) => Promise<any>` |  |
-| `description` | `string` |  |
-| `parameters` | `Record<string, any>` |  |
-
-**Returns:** `this`
-
-
-
-### removeTool
-
-Remove a tool by name.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | Parameter name |
-
-**Returns:** `this`
-
-
-
-### updateTools
-
-Merge new tools into the conversation, replacing any with the same name. Accepts the same Record<string, ConversationTool> format used at construction time.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `tools` | `Record<string, ConversationTool>` | ✓ | Parameter tools |
-
-**Returns:** `this`
-
-
-
-### stub
-
-Register a hardcoded stub response that bypasses the API when the user's message matches. Streaming is still simulated — chunk/preview events fire word-by-word.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `matcher` | `string | RegExp` | ✓ | Exact string match, substring, or RegExp tested against user input |
-| `response` | `string | (() => string)` | ✓ | The text to stream back, or a zero-arg function that returns it |
-
-**Returns:** `this`
-
-```ts
-conversation.stub('hello', 'Hi there!')
-conversation.stub(/weather/i, () => 'Sunny and 72°F.')
-```
-
-
-
-### estimateTokens
-
-Estimate the input token count for the current messages array using the js-tiktoken tokenizer. Updates state.
-
-**Returns:** `number`
-
-
-
-### summarize
-
-Generate a summary of the conversation so far using the LLM. Read-only — does not modify messages.
-
-**Returns:** `Promise<string>`
-
-
-
-### compact
-
-Compact the conversation by summarizing old messages and replacing them with a summary message. Keeps the system message (if any) and the most recent N messages.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `options` | `{ keepRecent?: number }` |  | Parameter options |
-
-**Returns:** `Promise<{ summary: string; removedCount: number; estimatedTokens: number }>`
-
-
-
-### ask
-
-Send a message and get a streamed response. Automatically handles tool calls by invoking the registered handlers and feeding results back to the model until a final text response is produced.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `content` | `string | ContentPart[]` | ✓ | The user message, either a string or array of content parts (text + images) |
-| `options` | `AskOptions` |  | Parameter options |
-
-`AskOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `maxTokens` | `number` |  |
-| `schema` | `z.ZodType` | 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. |
-
-**Returns:** `Promise<string>`
-
-```ts
-const reply = await conversation.ask("What's the weather in SF?")
-// With image:
-const reply = await conversation.ask([
- { type: 'text', text: 'What is in this diagram?' },
- { type: 'image_url', image_url: { url: 'data:image/png;base64,...' } }
-])
-```
-
-
-
-### save
-
-Persist this conversation to disk via conversationHistory. Creates a new record if this conversation hasn't been saved before, or updates the existing one.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `opts` | `{ title?: string; tags?: string[]; thread?: string; metadata?: Record<string, any> }` |  | Optional overrides for title, tags, thread, or metadata |
-
-**Returns:** `void`
-
-
-
-### pushMessage
-
-Append a message to the conversation state.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `message` | `Message` | ✓ | The message to append |
-
-**Returns:** `void`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `tools` | `Record<string, ConversationTool>` | Returns the registered tools available for the model to call. |
-| `availableTools` | `any` |  |
-| `mcpServers` | `Record<string, ConversationMCPServer>` | Returns configured remote MCP servers keyed by server label. |
-| `messages` | `Message[]` | Returns the full message history of the conversation. |
-| `model` | `string` | Returns the OpenAI model name being used for completions. |
-| `apiMode` | `'responses' | 'chat'` | Returns the active completion API mode after resolving auto/local behavior. |
-| `isStreaming` | `boolean` | Whether a streaming response is currently in progress. |
-| `contextWindow` | `number` | The context window size for the current model (from options override or auto-detected). |
-| `isNearContextLimit` | `boolean` | Whether the conversation is approaching the context limit. |
-| `openai` | `any` | Returns the OpenAI client instance from the container. |
-| `history` | `ConversationHistory` | Returns the conversationHistory feature for persistence. |
-
-## Events (Zod v4 schema)
-
-### summarizeStart
-
-Fired before generating a conversation summary
-
-
-
-### summarizeEnd
-
-Fired after the summary is generated
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | The generated summary text |
-
-
-
-### compactStart
-
-Fired before compacting the conversation history
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `messageCount` | `number` |  |
-| `keepRecent` | `number` |  |
-
-
-
-### compactEnd
-
-Fired after compaction completes
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `summary` | `string` |  |
-| `removedCount` | `number` |  |
-| `estimatedTokens` | `number` |  |
-| `compactionCount` | `number` |  |
-
-
-
-### autoCompactTriggered
-
-Fired when auto-compact kicks in because tokens exceeded the threshold
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `estimated` | `number` |  |
-| `limit` | `number` |  |
-| `contextWindow` | `number` |  |
-
-
-
-### userMessage
-
-Fired when a user message is added to the conversation
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | The user message content (string or ContentPart[]) |
-
-
-
-### toolError
-
-Fired when a tool handler throws or the tool is unknown
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Error object or message |
-
-
-
-### toolCall
-
-Fired before invoking a single tool handler
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Parsed arguments object |
-
-
-
-### toolResult
-
-Fired after a tool handler returns successfully
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `string` | Serialized result |
-
-
-
-### turnStart
-
-Fired at the start of each completion turn
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `turn` | `number` |  |
-| `isFollowUp` | `boolean` |  |
-
-
-
-### chunk
-
-Fired for each streaming text delta
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Text delta from the stream |
-
-
-
-### preview
-
-Fired after each chunk with the full accumulated text
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Accumulated text so far |
-
-
-
-### turnEnd
-
-Fired at the end of each completion turn
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `turn` | `number` |  |
-| `hasToolCalls` | `boolean` |  |
-
-
-
-### response
-
-Fired when the final text response is produced
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Final accumulated response text |
-
-
-
-### rawEvent
-
-Fired for every raw event from the Responses API stream
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | Raw stream event from the API |
-
-
-
-### mcpEvent
-
-Fired for MCP-related events from the Responses API
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | MCP-related stream event |
-
-
-
-### responseCompleted
-
-Fired when the Responses API stream completes
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | The completed OpenAI Response object |
-
-
-
-### toolCallsStart
-
-Fired when the model begins a batch of tool calls
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | Array of tool call objects from the model |
-
-
-
-### toolCallsEnd
-
-Fired after all tool calls in a turn have been executed
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `id` | `string` | Unique identifier for this conversation instance |
-| `thread` | `string` | Thread identifier for grouping conversations |
-| `model` | `string` | The OpenAI model being used |
-| `messages` | `array` | Full message history of the conversation |
-| `streaming` | `boolean` | Whether a streaming response is currently in progress |
-| `lastResponse` | `string` | The last assistant response text |
-| `toolCalls` | `number` | Total number of tool calls made in this conversation |
-| `api` | `string` | Which completion API is active for this conversation |
-| `lastResponseId` | `any` | Most recent OpenAI Responses API response ID for continuing conversation state |
-| `tokenUsage` | `object` | Cumulative token usage statistics |
-| `estimatedInputTokens` | `number` | Estimated input token count for the current messages array |
-| `compactionCount` | `number` | Number of times compact() has been called |
-| `contextWindow` | `number` | The context window size for the current model |
-| `tools` | `object` | Active tools map including any runtime overrides |
-| `callMaxTokens` | `any` | Per-call max tokens override, cleared after each ask() |
-
-## Examples
-
-**features.conversation**
-
-```ts
-const conversation = container.feature('conversation', {
- model: 'gpt-4.1',
- tools: myToolMap,
- history: [{ role: 'system', content: 'You are a helpful assistant.' }]
-})
-const reply = await conversation.ask('What is the meaning of life?')
-```
-
-
-
-**stub**
-
-```ts
-conversation.stub('hello', 'Hi there!')
-conversation.stub(/weather/i, () => 'Sunny and 72°F.')
-```
-
-
-
-**ask**
-
-```ts
-const reply = await conversation.ask("What's the weather in SF?")
-// With image:
-const reply = await conversation.ask([
- { type: 'text', text: 'What is in this diagram?' },
- { type: 'image_url', image_url: { url: 'data:image/png;base64,...' } }
-])
-```
-

package/docs/apis/features/agi/docs-reader.md

@@ -1,99 +0,0 @@
-# DocsReader (features.docsReader)
-
-The DocsReader feature is an AI Assisted wrapper around a ContentDB feature. You can ask it questions about the content, and it will use the ContentDB to find the answers from the documents.
-
-## Usage
-
-```ts
-container.feature('docsReader', {
-  // Either the contentDb instance or the path to the contentDb you want to load
-  contentDb,
-  // The model to use for the conversation
-  model,
-  // Whether to use a local model for the conversation
-  local,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `contentDb` | `any` | Either the contentDb instance or the path to the contentDb you want to load |
-| `model` | `string` | The model to use for the conversation |
-| `local` | `boolean` | Whether to use a local model for the conversation |
-
-## Methods
-
-### calculateCacheKeyForQuestion
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `question` | `string` | ✓ | Parameter question |
-
-**Returns:** `void`
-
-
-
-### ask
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `question` | `string` | ✓ | Parameter question |
-
-**Returns:** `void`
-
-
-
-### askCached
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `question` | `string` | ✓ | Parameter question |
-
-**Returns:** `void`
-
-
-
-### start
-
-Start the docs reader by loading the contentDb and wiring its tools into an assistant.
-
-**Returns:** `Promise<DocsReader>`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isStarted` | `boolean` | Whether the docs reader has been started. |
-| `answerCache` | `any` |  |
-| `contentDb` | `ContentDb` |  |
-
-## Events (Zod v4 schema)
-
-### started
-
-Event emitted by DocsReader
-
-
-
-### loaded
-
-Fired after the docs reader has been started
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `started` | `boolean` | Whether the docs reader has been started |