@octavus/docs 0.0.9 → 1.0.0

package/package.json

@@ -1,14 +1,24 @@
 {
   "name": "@octavus/docs",
-  "version": "0.0.9",
+  "version": "1.0.0",
   "description": "Documentation content for Octavus SDKs",
   "license": "MIT",
   "author": "Octavus AI <dev@octavus.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octavus-ai/js-sdk.git",
+    "directory": "packages/docs"
+  },
+  "homepage": "https://octavus.ai",
+  "bugs": {
+    "url": "https://github.com/octavus-ai/js-sdk/issues"
+  },
   "keywords": [
     "octavus",
     "ai",
     "agents",
-    "documentation"
+    "documentation",
+    "docs"
   ],
   "type": "module",
   "exports": {

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

@@ -1,251 +0,0 @@
----
-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:
-      type: block-type
-      # block-specific properties
-    
-    Another Block:
-      type: another-type
-      # ...
-```
-
-Each block has a human-readable name (shown in debug UI) and a type that determines its behavior.
-
-## Block Types
-
-### next-message
-
-Generate a response from the LLM:
-
-```yaml
-handlers:
-  user-message:
-    Respond to user:
-      type: next-message
-      # Uses main conversation thread by default
-      # Display defaults to 'stream'
-```
-
-With options:
-
-```yaml
-Generate summary:
-  type: 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
-```
-
-### add-message
-
-Add a message to the conversation:
-
-```yaml
-Add user message:
-  type: 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:
-  type: add-message
-  role: user
-  prompt: ticket-directive
-  input: [TICKET_DETAILS]
-  visible: false            # LLM sees this, user doesn't
-```
-
-### tool-call
-
-Call a tool deterministically:
-
-```yaml
-Create ticket:
-  type: 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:
-  type: 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:
-  type: 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:
-  type: serialize-thread
-  thread: main              # Which thread (default: main)
-  format: markdown          # markdown | json
-  output: CONVERSATION_TEXT # Variable to store result
-```
-
-## 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 | Shows description |
-| `stream` | next-message | Streams content |
-
-## Complete Example
-
-```yaml
-handlers:
-  user-message:
-    # Add the user's message to conversation
-    Add user message:
-      type: add-message
-      role: user
-      prompt: user-message
-      input: [USER_MESSAGE]
-      display: hidden
-    
-    # Generate response (LLM may call tools)
-    Respond to user:
-      type: next-message
-      # display: stream (default)
-
-  request-human:
-    # Step 1: Serialize conversation for summary
-    Serialize conversation:
-      type: serialize-thread
-      format: markdown
-      output: CONVERSATION_TEXT
-    
-    # Step 2: Create separate thread for summarization
-    Start summary thread:
-      type: 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:
-      type: add-message
-      thread: summary
-      role: user
-      prompt: summarize-request
-      input:
-        - CONVERSATION: CONVERSATION_TEXT
-    
-    # Step 4: Generate summary
-    Generate summary:
-      type: next-message
-      thread: summary
-      display: stream
-      description: Summarizing your conversation
-      independent: true
-      output: SUMMARY
-    
-    # Step 5: Save to resource
-    Save summary:
-      type: set-resource
-      resource: CONVERSATION_SUMMARY
-      value: SUMMARY
-    
-    # Step 6: Create support ticket
-    Create ticket:
-      type: tool-call
-      tool: create-support-ticket
-      input:
-        summary: SUMMARY
-        priority: medium
-      output: TICKET
-    
-    # Step 7: Add directive for response
-    Add directive:
-      type: add-message
-      role: user
-      prompt: ticket-directive
-      input: [TICKET_DETAILS: TICKET]
-      visible: false
-    
-    # Step 8: Respond to user
-    Respond:
-      type: 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:
-  type: 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/06-agent-config.md

@@ -1,242 +0,0 @@
----
-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
-```
-
-## 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 |
-| `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:
-
-```yaml
-# Anthropic
-agent:
-  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet
-  model: anthropic/claude-opus-4       # Claude 4 Opus
-
-# OpenAI
-agent:
-  model: openai/gpt-4o                 # GPT-4o
-  model: openai/gpt-4o-mini            # GPT-4o Mini
-  model: openai/o1                     # O1
-  model: openai/o3-mini                # O3 Mini
-```
-
-## 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.
-
-## 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:
-      type: 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
-
-agent:
-  model: anthropic/claude-sonnet-4-5
-  system: system
-  input:
-    - COMPANY_NAME
-    - PRODUCT_NAME
-  tools:
-    - get-user-account
-    - search-docs
-    - create-support-ticket
-  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:
-      type: add-message
-      role: user
-      prompt: user-message
-      input: [USER_MESSAGE]
-      display: hidden
-
-    Respond:
-      type: next-message
-```
-