@octavus/docs 0.0.8 → 1.0.0

package/content/04-protocol/06-handlers.md

@@ -0,0 +1,304 @@
+---
+title: Handlers
+description: Defining execution handlers with blocks.
+---
+
+# Handlers
+
+Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.
+
+## Handler Structure
+
+```yaml
+handlers:
+  trigger-name:
+    Block Name:
+      block: block-kind
+      # block-specific properties
+
+    Another Block:
+      block: another-kind
+      # ...
+```
+
+Each block has a human-readable name (shown in debug UI) and a `block` field that determines its behavior.
+
+## Block Kinds
+
+### next-message
+
+Generate a response from the LLM:
+
+```yaml
+handlers:
+  user-message:
+    Respond to user:
+      block: next-message
+      # Uses main conversation thread by default
+      # Display defaults to 'stream'
+```
+
+With options:
+
+```yaml
+Generate summary:
+  block: next-message
+  thread: summary # Use named thread
+  display: stream # Show streaming content
+  independent: true # Don't add to main chat
+  output: SUMMARY # Store output in variable
+  description: Generating summary # Shown in UI
+```
+
+For structured output (typed JSON response):
+
+```yaml
+Respond with suggestions:
+  block: next-message
+  responseType: ChatResponse # Type defined in types section
+  output: RESPONSE # Stores the parsed object
+```
+
+When `responseType` is specified:
+
+- The LLM generates JSON matching the type schema
+- The `output` variable receives the parsed object (not plain text)
+- The client receives a `UIObjectPart` for custom rendering
+
+See [Types](/docs/protocol/types#structured-output) for more details.
+
+### add-message
+
+Add a message to the conversation:
+
+```yaml
+Add user message:
+  block: add-message
+  role: user # user | assistant | system
+  prompt: user-message # Reference to prompt file
+  input: [USER_MESSAGE] # Variables to interpolate
+  display: hidden # Don't show in UI
+```
+
+For internal directives (LLM sees it, user doesn't):
+
+```yaml
+Add internal directive:
+  block: add-message
+  role: user
+  prompt: ticket-directive
+  input: [TICKET_DETAILS]
+  visible: false # LLM sees this, user doesn't
+```
+
+For structured user input (object shown in UI, prompt for LLM context):
+
+```yaml
+Add user message:
+  block: add-message
+  role: user
+  prompt: user-message # Rendered for LLM context (hidden from UI)
+  input: [USER_INPUT]
+  uiContent: USER_INPUT # Variable shown in UI (object → object part)
+  display: hidden
+```
+
+When `uiContent` is set:
+
+- The variable value is shown in the UI (string → text part, object → object part)
+- The prompt text is hidden from the UI but kept for LLM context
+- Useful for rich UI interactions where the visual differs from the LLM context
+
+### tool-call
+
+Call a tool deterministically:
+
+```yaml
+Create ticket:
+  block: tool-call
+  tool: create-support-ticket
+  input:
+    summary: SUMMARY # Variable reference
+    priority: medium # Literal value
+  output: TICKET # Store result
+```
+
+### set-resource
+
+Update a persistent resource:
+
+```yaml
+Save summary:
+  block: set-resource
+  resource: CONVERSATION_SUMMARY
+  value: SUMMARY # Variable to save
+  display: name # Show block name
+```
+
+### start-thread
+
+Create a named conversation thread:
+
+```yaml
+Start summary thread:
+  block: start-thread
+  thread: summary # Thread name
+  model: anthropic/claude-sonnet-4-5 # Optional: different model
+  thinking: low # Extended reasoning level
+  maxSteps: 1 # Tool call limit
+  system: escalation-summary # System prompt
+  input: [COMPANY_NAME] # Variables for prompt
+```
+
+### serialize-thread
+
+Convert conversation to text:
+
+```yaml
+Serialize conversation:
+  block: serialize-thread
+  thread: main # Which thread (default: main)
+  format: markdown # markdown | json
+  output: CONVERSATION_TEXT # Variable to store result
+```
+
+### generate-image
+
+Generate an image from a prompt variable:
+
+```yaml
+Generate image:
+  block: generate-image
+  prompt: OPTIMIZED_PROMPT # Variable containing the prompt
+  imageModel: google/gemini-2.5-flash-image # Required image model
+  size: 1024x1024 # 1024x1024 | 1792x1024 | 1024x1792
+  output: GENERATED_IMAGE # Store URL in variable
+  description: Generating your image... # Shown in UI
+```
+
+This block is for deterministic image generation pipelines where the prompt is constructed programmatically (e.g., via prompt engineering in a separate thread).
+
+For agentic image generation where the LLM decides when to generate, configure `imageModel` in the [agent config](/docs/protocol/agent-config#image-generation).
+
+## Display Modes
+
+Every block has a `display` property:
+
+| Mode          | Default For               | Behavior          |
+| ------------- | ------------------------- | ----------------- |
+| `hidden`      | add-message               | Not shown to user |
+| `name`        | set-resource              | Shows block name  |
+| `description` | tool-call, generate-image | Shows description |
+| `stream`      | next-message              | Streams content   |
+
+## Complete Example
+
+```yaml
+handlers:
+  user-message:
+    # Add the user's message to conversation
+    Add user message:
+      block: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+      display: hidden
+
+    # Generate response (LLM may call tools)
+    Respond to user:
+      block: next-message
+      # display: stream (default)
+
+  request-human:
+    # Step 1: Serialize conversation for summary
+    Serialize conversation:
+      block: serialize-thread
+      format: markdown
+      output: CONVERSATION_TEXT
+
+    # Step 2: Create separate thread for summarization
+    Start summary thread:
+      block: start-thread
+      thread: summary
+      model: anthropic/claude-sonnet-4-5
+      thinking: low
+      system: escalation-summary
+      input: [COMPANY_NAME]
+
+    # Step 3: Add request to summary thread
+    Add summarize request:
+      block: add-message
+      thread: summary
+      role: user
+      prompt: summarize-request
+      input:
+        - CONVERSATION: CONVERSATION_TEXT
+
+    # Step 4: Generate summary
+    Generate summary:
+      block: next-message
+      thread: summary
+      display: stream
+      description: Summarizing your conversation
+      independent: true
+      output: SUMMARY
+
+    # Step 5: Save to resource
+    Save summary:
+      block: set-resource
+      resource: CONVERSATION_SUMMARY
+      value: SUMMARY
+
+    # Step 6: Create support ticket
+    Create ticket:
+      block: tool-call
+      tool: create-support-ticket
+      input:
+        summary: SUMMARY
+        priority: medium
+      output: TICKET
+
+    # Step 7: Add directive for response
+    Add directive:
+      block: add-message
+      role: user
+      prompt: ticket-directive
+      input: [TICKET_DETAILS: TICKET]
+      visible: false
+
+    # Step 8: Respond to user
+    Respond:
+      block: next-message
+```
+
+## Block Input Mapping
+
+Map variables to block inputs:
+
+```yaml
+# Simple list (variable name = prompt variable)
+input: [USER_MESSAGE, COMPANY_NAME]
+
+# Mapping (different names)
+input:
+  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT
+  - TICKET_DETAILS: TICKET
+```
+
+## Independent Blocks
+
+Use `independent: true` for content that shouldn't go to the main chat:
+
+```yaml
+Generate summary:
+  block: next-message
+  thread: summary
+  independent: true # Output stored in variable, not main chat
+  output: SUMMARY
+```
+
+This is useful for:
+
+- Background processing
+- Summarization in separate threads
+- Generating content for tools

package/content/04-protocol/07-agent-config.md

@@ -0,0 +1,334 @@
+---
+title: Agent Config
+description: Configuring the agent model and behavior.
+---
+
+# Agent Config
+
+The `agent` section configures the LLM model, system prompt, tools, and behavior.
+
+## Basic Configuration
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system # References prompts/system.md
+  tools: [get-user-account] # Available tools
+  skills: [qr-code] # Available skills
+```
+
+## Configuration Options
+
+| Field         | Required | Description                                               |
+| ------------- | -------- | --------------------------------------------------------- |
+| `model`       | Yes      | Model identifier (provider/model-id)                      |
+| `system`      | Yes      | System prompt filename (without .md)                      |
+| `input`       | No       | Variables to interpolate in system prompt                 |
+| `tools`       | No       | List of tools the LLM can call                            |
+| `skills`      | No       | List of Octavus skills the LLM can use                    |
+| `imageModel`  | No       | Image generation model (enables agentic image generation) |
+| `agentic`     | No       | Allow multiple tool call cycles                           |
+| `maxSteps`    | No       | Maximum agentic steps (default: 10)                       |
+| `temperature` | No       | Model temperature (0-2)                                   |
+| `thinking`    | No       | Extended reasoning level                                  |
+| `anthropic`   | No       | Anthropic-specific options (tools, skills)                |
+
+## Models
+
+Specify models in `provider/model-id` format. Any model supported by the provider's SDK will work.
+
+### Supported Providers
+
+| Provider  | Format                 | Examples                                                     |
+| --------- | ---------------------- | ------------------------------------------------------------ |
+| Anthropic | `anthropic/{model-id}` | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`   |
+| Google    | `google/{model-id}`    | `gemini-3-pro-preview`, `gemini-3-flash`, `gemini-2.5-flash` |
+| OpenAI    | `openai/{model-id}`    | `gpt-5`, `gpt-4o`, `o4-mini`, `o3`, `o3-mini`, `o1`          |
+
+### Examples
+
+```yaml
+# Anthropic Claude 4.5
+agent:
+  model: anthropic/claude-sonnet-4-5
+
+# Google Gemini 3
+agent:
+  model: google/gemini-3-flash
+
+# OpenAI GPT-5
+agent:
+  model: openai/gpt-5
+
+# OpenAI reasoning models
+agent:
+  model: openai/o3-mini
+```
+
+> **Note**: Model IDs are passed directly to the provider SDK. Check the provider's documentation for the latest available models.
+
+## System Prompt
+
+The system prompt sets the agent's persona and instructions:
+
+```yaml
+agent:
+  system: system # Uses prompts/system.md
+  input:
+    - COMPANY_NAME
+    - PRODUCT_NAME
+```
+
+Example `prompts/system.md`:
+
+```markdown
+You are a friendly support agent for {{COMPANY_NAME}}.
+
+## Your Role
+
+Help users with questions about {{PRODUCT_NAME}}.
+
+## Guidelines
+
+- Be helpful and professional
+- If you can't help, offer to escalate
+- Never share internal information
+```
+
+## Agentic Mode
+
+Enable multi-step tool calling:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  tools: [get-user-account, search-docs, create-ticket]
+  agentic: true # LLM can call multiple tools
+  maxSteps: 10 # Limit cycles to prevent runaway
+```
+
+**How it works:**
+
+1. LLM receives user message
+2. LLM decides to call a tool
+3. Tool executes, result returned to LLM
+4. LLM decides if more tools needed
+5. Repeat until LLM responds or maxSteps reached
+
+## Extended Thinking
+
+Enable extended reasoning for complex tasks:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  thinking: medium # low | medium | high
+```
+
+| Level    | Token Budget | Use Case            |
+| -------- | ------------ | ------------------- |
+| `low`    | ~5,000       | Simple reasoning    |
+| `medium` | ~10,000      | Moderate complexity |
+| `high`   | ~20,000      | Complex analysis    |
+
+Thinking content streams to the UI and can be displayed to users.
+
+## Skills
+
+Enable Octavus skills for code execution and file generation:
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  skills: [qr-code] # Enable skills
+  agentic: true
+```
+
+Skills provide provider-agnostic code execution in isolated sandboxes. When enabled, the LLM can execute Python/Bash code, run skill scripts, and generate files.
+
+See [Skills](/docs/protocol/skills) for full documentation.
+
+## Image Generation
+
+Enable the LLM to generate images autonomously:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  imageModel: google/gemini-2.5-flash-image
+  agentic: true
+```
+
+When `imageModel` is configured, the `octavus_generate_image` tool becomes available. The LLM can decide when to generate images based on user requests.
+
+### Supported Image Providers
+
+| Provider | Model Types                             | Examples                                                  |
+| -------- | --------------------------------------- | --------------------------------------------------------- |
+| OpenAI   | Dedicated image models                  | `gpt-image-1`                                             |
+| Google   | Gemini native (contains "image")        | `gemini-2.5-flash-image`, `gemini-3-flash-image-generate` |
+| Google   | Imagen dedicated (starts with "imagen") | `imagen-4.0-generate-001`                                 |
+
+> **Note**: Google has two image generation approaches. Gemini "native" models (containing "image" in the ID) generate images using the language model API with `responseModalities`. Imagen models (starting with "imagen") use a dedicated image generation API.
+
+### Image Sizes
+
+The tool supports three image sizes:
+
+- `1024x1024` (default) — Square
+- `1792x1024` — Landscape (16:9)
+- `1024x1792` — Portrait (9:16)
+
+### Agentic vs Deterministic
+
+Use `imageModel` in agent config when:
+
+- The LLM should decide when to generate images
+- Users ask for images in natural language
+
+Use `generate-image` block (see [Handlers](/docs/protocol/handlers#generate-image)) when:
+
+- You want explicit control over image generation
+- Building prompt engineering pipelines
+- Images are generated at specific handler steps
+
+## Temperature
+
+Control response randomness:
+
+```yaml
+agent:
+  model: openai/gpt-4o
+  temperature: 0.7 # 0 = deterministic, 2 = creative
+```
+
+**Guidelines:**
+
+- `0 - 0.3`: Factual, consistent responses
+- `0.4 - 0.7`: Balanced (good default)
+- `0.8 - 1.2`: Creative, varied responses
+- `> 1.2`: Very creative (may be inconsistent)
+
+## Provider Options
+
+Enable provider-specific features like Anthropic's built-in tools and skills:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  anthropic:
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+    skills:
+      pdf:
+        type: anthropic
+        description: Processing PDF
+```
+
+Provider options are validated against the model—using `anthropic:` with a non-Anthropic model will fail validation.
+
+See [Provider Options](/docs/protocol/provider-options) for full documentation.
+
+## Thread-Specific Config
+
+Override config for named threads:
+
+```yaml
+handlers:
+  request-human:
+    Start summary thread:
+      block: start-thread
+      thread: summary
+      model: anthropic/claude-sonnet-4-5 # Different model
+      thinking: low # Different thinking
+      maxSteps: 1 # Limit tool calls
+      system: escalation-summary # Different prompt
+```
+
+## Full Example
+
+```yaml
+input:
+  COMPANY_NAME: { type: string }
+  PRODUCT_NAME: { type: string }
+  USER_ID: { type: string, optional: true }
+
+resources:
+  CONVERSATION_SUMMARY:
+    type: string
+    default: ''
+
+tools:
+  get-user-account:
+    description: Look up user account
+    parameters:
+      userId: { type: string }
+
+  search-docs:
+    description: Search help documentation
+    parameters:
+      query: { type: string }
+
+  create-support-ticket:
+    description: Create a support ticket
+    parameters:
+      summary: { type: string }
+      priority: { type: string } # low, medium, high
+
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  input:
+    - COMPANY_NAME
+    - PRODUCT_NAME
+  tools:
+    - get-user-account
+    - search-docs
+    - create-support-ticket
+  skills: [qr-code] # Octavus skills
+  agentic: true
+  maxSteps: 10
+  thinking: medium
+  # Anthropic-specific options
+  anthropic:
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+    skills:
+      pdf:
+        type: anthropic
+        description: Processing PDF
+
+triggers:
+  user-message:
+    input:
+      USER_MESSAGE: { type: string }
+
+handlers:
+  user-message:
+    Add message:
+      block: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+      display: hidden
+
+    Respond:
+      block: next-message
+```