@octavus/docs 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Octavus AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/content/01-getting-started/01-introduction.md

@@ -0,0 +1,93 @@
+---
+title: Introduction
+description: Overview of Octavus AI - an agent orchestration platform for developers.
+---
+
+# Introduction to Octavus
+
+Octavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can focus on their agent logic and business requirements.
+
+## What is Octavus?
+
+Building and managing AI agents is complex. Developers face challenges with:
+
+- **Fragmented tooling** — No unified way to define, manage, and deploy agents
+- **Prompt management** — Prompts are scattered across codebases, hard to version and iterate
+- **Integration complexity** — Connecting agents to tools, resources, and other agents requires significant custom work
+- **Observability** — Difficult to debug, monitor, and understand agent behavior in production
+- **Infrastructure overhead** — Teams rebuild the same agent infrastructure repeatedly
+
+Octavus solves these problems by providing:
+
+- A **protocol-based approach** to defining agent behavior
+- **Server and client SDKs** for easy integration
+- **Built-in streaming** support for real-time responses
+- **Tool execution** that runs on your servers with your data
+- **Session management** for stateful conversations
+
+## Core Concepts
+
+### Agents
+
+An **Agent** is the main entity in Octavus — a self-contained unit that defines how an AI agent behaves. Agents are defined using YAML protocols that specify:
+
+- Input variables the agent accepts
+- Triggers that invoke the agent (user messages, button clicks, API calls)
+- Tools the agent can use
+- Handlers that define execution flow
+
+### Sessions
+
+A **Session** represents a conversation with an agent. Sessions:
+
+- Store conversation history
+- Track resources and variables
+- Enable stateful interactions across multiple messages
+
+### Triggers
+
+**Triggers** define how an agent is invoked:
+
+- **User Message** — Respond to a text message in a chat interface
+- **User Action** — Respond to UI actions (button clicks, form submissions)
+- **API Call** — Direct invocation via SDK
+
+### Tools
+
+**Tools** extend what agents can do:
+
+- **External Tools** — Consumer-defined tools that call back to your systems
+- **Internal Tools** — Built-in capabilities (web search, code execution)
+
+Tools execute on your server, not on Octavus, giving you full control over data and authentication.
+
+## Architecture Overview
+
+```mermaid
+sequenceDiagram
+    participant App as Your App
+    participant API as Octavus API
+    participant LLM as LLM Provider
+
+    App->>API: 1. Trigger action
+    API->>LLM: 2. Execute protocol
+    LLM-->>API: Response
+    API-->>App: 3. Stream events
+    
+    Note over App: Tool request received
+    API-->>App: 4. Tool request
+    Note over App: 5. Execute tool locally
+    App->>API: 6. Return results
+    
+    API->>LLM: 7. Continue
+    LLM-->>API: Response
+    API-->>App: 8. Stream response
+```
+
+## Next Steps
+
+- [Quick Start](/docs/getting-started/quickstart) — Get your first agent running in minutes
+- [Server SDK](/docs/server-sdk/overview) — Learn about backend integration
+- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React
+- [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols
+

package/content/01-getting-started/02-quickstart.md

@@ -0,0 +1,268 @@
+---
+title: Quick Start
+description: Get your first Octavus agent running in minutes.
+---
+
+# Quick Start
+
+This guide will walk you through integrating Octavus into your application in under 10 minutes.
+
+## Prerequisites
+
+- Node.js 18+
+- An Octavus account with API key
+- A Next.js application (or any Node.js backend)
+
+## Installation
+
+Install the Octavus SDKs in your project:
+
+```bash
+# Server SDK for backend
+npm install @octavus/server-sdk
+
+# Client SDK for frontend (React)
+npm install @octavus/client-sdk
+```
+
+## Backend Setup
+
+### 1. Initialize the Client
+
+Create an Octavus client instance in your backend:
+
+```typescript
+// lib/octavus.ts
+import { OctavusClient } from '@octavus/server-sdk';
+
+export const octavus = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+```
+
+### 2. Create a Session Endpoint
+
+Create an API endpoint that creates sessions and returns the session ID:
+
+```typescript
+// app/api/chat/create/route.ts
+import { NextResponse } from 'next/server';
+import { octavus } from '@/lib/octavus';
+
+export async function POST(request: Request) {
+  const { agentId, input } = await request.json();
+
+  // Create a new session
+  const sessionId = await octavus.agentSessions.create(agentId, input);
+
+  return NextResponse.json({ sessionId });
+}
+```
+
+### 3. Create a Trigger Endpoint
+
+Create an endpoint that handles triggers and streams responses:
+
+```typescript
+// app/api/trigger/route.ts
+import { octavus } from '@/lib/octavus';
+
+export async function POST(request: Request) {
+  const { sessionId, triggerName, input } = await request.json();
+
+  // Attach to session with tool handlers
+  const session = octavus.agentSessions.attach(sessionId, {
+    tools: {
+      // Define tool handlers that run on your server
+      'get-user-account': async (args) => {
+        const userId = args.userId as string;
+        // Fetch from your database
+        return {
+          name: 'Demo User',
+          email: 'demo@example.com',
+          plan: 'pro',
+        };
+      },
+      'create-support-ticket': async (args) => {
+        // Create ticket in your system
+        return {
+          ticketId: 'TICKET-123',
+          estimatedResponse: '24 hours',
+        };
+      },
+    },
+  });
+
+  // Trigger the action and get the stream
+  const { stream } = session.trigger(triggerName, input);
+
+  // Return as streaming response
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}
+```
+
+## Frontend Setup
+
+### 1. Create a Chat Component
+
+Use the `useOctavusChat` hook to build a chat interface:
+
+```tsx
+// components/chat.tsx
+'use client';
+
+import { useOctavusChat } from '@octavus/client-sdk';
+import { useState } from 'react';
+
+interface ChatProps {
+  sessionId: string;
+}
+
+export function Chat({ sessionId }: ChatProps) {
+  const [inputValue, setInputValue] = useState('');
+
+  const {
+    messages,
+    status,
+    isLoading,
+    streamingText,
+    addUserMessage,
+    triggerAction,
+  } = useOctavusChat({
+    onTrigger: async (triggerName, input) => {
+      return fetch('/api/trigger', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId, triggerName, input }),
+      });
+    },
+  });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!inputValue.trim() || isLoading) return;
+
+    const message = inputValue.trim();
+    setInputValue('');
+
+    // Add user message to UI
+    addUserMessage(message);
+
+    // Trigger the agent
+    await triggerAction('user-message', { USER_MESSAGE: message });
+  };
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Messages */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4">
+        {messages.map((msg) => (
+          <div
+            key={msg.id}
+            className={`p-3 rounded-lg ${
+              msg.role === 'user'
+                ? 'bg-blue-500 text-white ml-auto max-w-xs'
+                : 'bg-gray-100 max-w-md'
+            }`}
+          >
+            {msg.content}
+          </div>
+        ))}
+
+        {/* Streaming text */}
+        {streamingText && (
+          <div className="bg-gray-100 p-3 rounded-lg max-w-md">
+            {streamingText}
+          </div>
+        )}
+      </div>
+
+      {/* Input */}
+      <form onSubmit={handleSubmit} className="p-4 border-t">
+        <div className="flex gap-2">
+          <input
+            type="text"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            placeholder="Type a message..."
+            className="flex-1 px-4 py-2 border rounded-lg"
+            disabled={isLoading}
+          />
+          <button
+            type="submit"
+            disabled={isLoading}
+            className="px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50"
+          >
+            Send
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+```
+
+### 2. Create Session and Render Chat
+
+```tsx
+// app/chat/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Chat } from '@/components/chat';
+
+export default function ChatPage() {
+  const [sessionId, setSessionId] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function createSession() {
+      const response = await fetch('/api/chat/create', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          agentId: 'support-chat',
+          input: {
+            COMPANY_NAME: 'Acme Corp',
+            PRODUCT_NAME: 'Widget Pro',
+          },
+        }),
+      });
+      const { sessionId } = await response.json();
+      setSessionId(sessionId);
+    }
+
+    createSession();
+  }, []);
+
+  if (!sessionId) {
+    return <div>Loading...</div>;
+  }
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```bash
+OCTAVUS_API_URL=https://octavus.ai
+OCTAVUS_API_KEY=your-api-key-here
+```
+
+## What's Next?
+
+Now that you have a basic integration working:
+
+- [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior
+- [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features
+- [Build rich UIs](/docs/client-sdk/overview) with the Client SDK
+

package/content/01-getting-started/_meta.md

@@ -0,0 +1,4 @@
+---
+title: Getting Started
+description: Learn the basics of Octavus and how to integrate AI agents into your application.
+---

package/content/02-server-sdk/01-overview.md

@@ -0,0 +1,133 @@
+---
+title: Overview
+description: Introduction to the Octavus Server SDK for backend integration.
+---
+
+# Server SDK Overview
+
+The `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation loop.
+
+## Installation
+
+```bash
+npm install @octavus/server-sdk
+```
+
+## Basic Usage
+
+```typescript
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: 'your-api-key',
+});
+```
+
+## Key Features
+
+### Session Management
+
+Create and manage agent sessions:
+
+```typescript
+// Create a new session
+const sessionId = await client.agentSessions.create('support-chat', {
+  COMPANY_NAME: 'Acme Corp',
+  PRODUCT_NAME: 'Widget Pro',
+});
+
+// Get session state
+const state = await client.agentSessions.get(sessionId);
+```
+
+### Tool Handlers
+
+Tools run on your server with your data:
+
+```typescript
+const session = client.agentSessions.attach(sessionId, {
+  tools: {
+    'get-user-account': async (args) => {
+      // Access your database, APIs, etc.
+      return await db.users.findById(args.userId);
+    },
+  },
+});
+```
+
+### Streaming
+
+All responses stream in real-time:
+
+```typescript
+const { stream } = session.trigger('user-message', { 
+  USER_MESSAGE: 'Hello!' 
+});
+
+// Use as a streaming response
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/event-stream' },
+});
+```
+
+## API Reference
+
+### OctavusClient
+
+The main entry point for interacting with Octavus.
+
+```typescript
+interface OctavusClientConfig {
+  baseUrl: string;  // Octavus API URL
+  apiKey?: string;  // Your API key
+}
+
+class OctavusClient {
+  readonly agents: AgentsApi;
+  readonly agentSessions: AgentSessionsApi;
+  
+  constructor(config: OctavusClientConfig);
+}
+```
+
+### AgentSessionsApi
+
+Manages agent sessions.
+
+```typescript
+class AgentSessionsApi {
+  // Create a new session
+  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;
+  
+  // Get session state
+  async get(sessionId: string): Promise<SessionState>;
+  
+  // Attach to a session for triggering
+  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;
+}
+```
+
+### AgentSession
+
+Handles triggering and streaming for a specific session.
+
+```typescript
+class AgentSession {
+  // Trigger an action and stream the response
+  trigger(
+    triggerName: string,
+    input?: Record<string, unknown>
+  ): { stream: ReadableStream<Uint8Array> };
+  
+  // Get the session ID
+  getSessionId(): string;
+}
+```
+
+## Next Steps
+
+- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management
+- [Tools](/docs/server-sdk/tools) — Implementing tool handlers
+- [Streaming](/docs/server-sdk/streaming) — Understanding stream events
+

package/content/02-server-sdk/02-sessions.md

@@ -0,0 +1,164 @@
+---
+title: Sessions
+description: Managing agent sessions with the Server SDK.
+---
+
+# Sessions
+
+Sessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.
+
+## Creating Sessions
+
+Create a session by specifying the agent ID and initial input variables:
+
+```typescript
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+// Create a session with the support-chat agent
+const sessionId = await client.agentSessions.create('support-chat', {
+  COMPANY_NAME: 'Acme Corp',
+  PRODUCT_NAME: 'Widget Pro',
+  USER_ID: 'user-123', // Optional inputs
+});
+
+console.log('Session created:', sessionId);
+```
+
+## Session State
+
+Retrieve the current state of a session:
+
+```typescript
+const state = await client.agentSessions.get(sessionId);
+
+console.log({
+  id: state.id,
+  agentId: state.agentId,
+  messages: state.messages.length,
+  resources: state.resources,
+  variables: state.variables,
+  createdAt: state.createdAt,
+  updatedAt: state.updatedAt,
+});
+```
+
+### SessionState Interface
+
+```typescript
+interface SessionState {
+  id: string;
+  agentId: string;
+  input: Record<string, unknown>;      // Initial input (immutable)
+  variables: Record<string, unknown>;  // Mutable session variables
+  resources: Record<string, unknown>;  // Resources (synced to consumer)
+  messages: ChatMessage[];             // Conversation history
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+## Attaching to Sessions
+
+To trigger actions on a session, you need to attach to it first:
+
+```typescript
+const session = client.agentSessions.attach(sessionId, {
+  tools: {
+    // Tool handlers (see Tools documentation)
+  },
+  resources: [
+    // Resource watchers (optional)
+  ],
+});
+```
+
+## Triggering Actions
+
+Once attached, trigger actions on the session:
+
+```typescript
+const { stream } = session.trigger('user-message', {
+  USER_MESSAGE: 'How do I reset my password?',
+});
+
+// Return the stream to your frontend
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/event-stream' },
+});
+```
+
+## Session Lifecycle
+
+```mermaid
+flowchart TD
+    A[1. CREATE] --> B[2. ATTACH]
+    B --> C[3. TRIGGER]
+    C --> C
+    C --> D[4. RETRIEVE]
+    D --> C
+    C --> E[5. EXPIRE]
+
+    A -.- A1["`**client.agentSessions.create()**
+    Returns sessionId
+    Initializes state`"]
+    
+    B -.- B1["`**client.agentSessions.attach()**
+    Configure tool handlers
+    Configure resource watchers`"]
+    
+    C -.- C1["`**session.trigger()**
+    Execute handler
+    Stream events
+    Update state`"]
+    
+    D -.- D1["`**client.agentSessions.get()**
+    Get current state
+    Restore conversation`"]
+    
+    E -.- E1["`Sessions expire after
+    24 hours (configurable)`"]
+```
+
+## Restoring Sessions
+
+When a user returns to your app, restore their session:
+
+```typescript
+// On page load
+const state = await client.agentSessions.get(sessionId);
+
+// Pass messages to frontend to restore UI
+return {
+  sessionId,
+  messages: state.messages,
+  resources: state.resources,
+};
+```
+
+The `messages` array includes all conversation history with proper content ordering (text, tool calls, thinking blocks), enabling accurate UI restoration.
+
+## Error Handling
+
+```typescript
+import { ApiError } from '@octavus/server-sdk';
+
+try {
+  const state = await client.agentSessions.get(sessionId);
+} catch (error) {
+  if (error instanceof ApiError) {
+    if (error.status === 404) {
+      // Session not found or expired
+      console.log('Session expired, create a new one');
+    } else {
+      console.error('API Error:', error.message);
+    }
+  }
+  throw error;
+}
+```
+