Skip to content

API.md

Latest commit

 

History

History
249 lines (188 loc) · 6.02 KB

API.md

File metadata and controls

249 lines (188 loc) · 6.02 KB
Raw

CHAD API Documentation

CHAD exposes a comprehensive API to the Open WebUI frontend for interacting with the AI cluster and tool framework.

Architecture Overview

User Request
    ↓
Open WebUI (Frontend)
    ↓
IPC Bridge (window.chad)
    ↓
Orchestrator
    ↓
┌─────────────┬──────────────┐
│ AI Cluster  │  Tool Registry│
├─────────────┼──────────────┤
│ • Planner   │  • Filesystem│
│ • Coder     │  • Terminal  │
│ • Architect │  • Web       │
│ • Vision    │  • ...more   │
└─────────────┴──────────────┘

Chat API

window.chad.chat(request: string)

Send a request to the CHAD orchestrator. The planner will analyze the request, execute tools, and delegate to appropriate AIs.

const response = await window.chad.chat("Create a new React component for user profiles");
console.log(response);
// { success: true, response: "..." }

Model API

window.chad.model.list()

Get all available AI models in the cluster.

const models = await window.chad.model.list();
// [
//   { name: "planner", role: "Reasoning, planning, and tool orchestration", ... },
//   { name: "coder", role: "Fast implementation", ... },
//   ...
// ]

window.chad.model.chat(modelName: string, messages: ChatMessage[])

Directly chat with a specific model, bypassing the orchestrator.

const response = await window.chad.model.chat("coder", [
  { role: "user", content: "Write a function to sort an array" }
]);

Tools API

window.chad.tools.list()

Get all available tools.

const tools = await window.chad.tools.list();
// [
//   { name: "fs_read", description: "Read a file", ... },
//   { name: "terminal_powershell", description: "Execute PowerShell", ... },
//   ...
// ]

window.chad.tools.schema()

Get the tool schema with parameter definitions.

const schema = await window.chad.tools.schema();
// {
//   "fs_read": {
//     description: "Read the contents of a file",
//     parameters: { ... },
//     requiresApproval: false
//   },
//   ...
// }

window.chad.tools.execute(toolName: string, params: any)

Execute a tool directly. If the tool requires approval, an approval request will be emitted.

const result = await window.chad.tools.execute("fs_read", {
  path: "C:\\Users\\example\\file.txt"
});

window.chad.tools.onApprovalRequest(callback)

Listen for tool approval requests.

window.chad.tools.onApprovalRequest((data) => {
  console.log(`Approval required for: ${data.tool}`);
  console.log("Params:", data.params);
  
  // Show UI to user...
  const approved = confirm(`Allow ${data.tool}?`);
  
  window.chad.tools.approve({
    taskId: data.taskId,
    toolName: data.tool,
    params: data.params,
    approved
  });
});

Tasks API

window.chad.tasks.list()

Get all active tasks.

const tasks = await window.chad.tasks.list();
// [
//   {
//     id: "task_1234",
//     userRequest: "...",
//     status: "executing",
//     activeModel: "coder",
//     ...
//   }
// ]

window.chad.tasks.get(taskId: string)

Get a specific task by ID.

const task = await window.chad.tasks.get("task_1234");

Health API

window.chad.health()

Check system health and get available models/tools.

const health = await window.chad.health();
// {
//   status: "healthy",
//   models: ["planner", "coder", "architect", "vision"],
//   tools: ["fs_read", "fs_write", "terminal_powershell", ...]
// }

AI Cluster Design

Planner (mistral-small)

  • Role: Central coordinator
  • Responsibilities: Planning, tool selection, task delegation
  • Does NOT: Write code directly

Coder (qwen2.5-coder:14b)

  • Role: Fast implementation
  • Responsibilities: Day-to-day coding tasks
  • Best for: React, TypeScript, Node, utilities

Architect (qwen2.5-coder:32b)

  • Role: Deep reasoning
  • Responsibilities: Large refactors, architecture decisions
  • Use when: Complex changes, multi-file reasoning

Vision (llava)

  • Role: Visual understanding
  • Responsibilities: Screenshot analysis, UI reconstruction
  • Use when: Working with images or UI mockups

Tool Framework

All tools are:

  • Explicit: AIs request tools, don't execute them directly
  • Permission-based: Destructive tools require user approval
  • Auditable: All tool calls are logged
  • Extensible: New tools can be added without changing AI roles

Available Tool Categories

  1. Filesystem (fs_*)

    • Read, write, list, search, patch files
    • Write operations require approval

  2. Terminal (terminal_*)

    • PowerShell and WSL execution
    • All commands require approval

  3. Web (web_*)

    • Search (Exa API)
    • Fetch URLs

Adding Custom Tools

See /src/tools/README.md for tool development guide.

Example: Complex Workflow

// 1. User makes a request
const response = await window.chad.chat(
  "Refactor the authentication system to use JWT instead of sessions"
);

// Behind the scenes:
// - Planner analyzes the request
// - Planner requests fs_search to find auth-related files
// - Planner delegates to @architect for architectural analysis
// - Architect analyzes files and proposes changes
// - Planner delegates to @coder for implementation
// - Coder uses fs_patch to modify files
// - User approves each file modification
// - Response returned to user

console.log(response);
// {
//   success: true,
//   response: "Authentication system successfully refactored to use JWT..."
// }

Integration with Open WebUI

CHAD's API is available in the Open WebUI context. You can:

  1. Add custom chat handlers that route to CHAD
  2. Create UI components for tool approval
  3. Display task progress in the UI
  4. Show model selection/status

See /docs/OPEN_WEBUI_INTEGRATION.md for integration examples.