Orchestral AI

Production-ready AI framework for building LLM-powered applications

Unified tool calling across multiple providers • Web-based interface • Real-time streaming

Quick Start

Installation

To use the web interface (the orchestral CLI app) — most users:

pip install 'orchestral-ai[ui]'

To use Orchestral as a library in your own code (no web UI):

pip install orchestral-ai

The lite default ships with Anthropic, OpenAI, Groq, and Ollama support. Other providers are opt-in extras:

pip install 'orchestral-ai[google]'        # Google Gemini
pip install 'orchestral-ai[bedrock]'       # AWS Bedrock
pip install 'orchestral-ai[mistral]'       # Mistral AI
pip install 'orchestral-ai[all-providers]' # every provider SDK
pip install 'orchestral-ai[full]'          # all-providers + UI

Extras compose: pip install 'orchestral-ai[ui,google]' is fine, and you can re-run pip install later to add extras to an existing install.

Setup API Keys

Create a .env file in your project directory:

ANTHROPIC_API_KEY=sk-ant-...     # Get from https://console.anthropic.com/
OPENAI_API_KEY=sk-proj-...       # Get from https://platform.openai.com/api-keys
GOOGLE_API_KEY=AIza...           # Get from https://aistudio.google.com/app/apikey
GROQ_API_KEY=gsk_...             # Get from https://console.groq.com/

At least one API key is required. We recommend starting with Anthropic's Claude.

Run the Web Interface

orchestral

The app will launch at http://127.0.0.1:8000

Security

Orchestral AI is a development tool: it enables AI agents to execute shell commands, run Python code, and read and modify files on your machine. All potentially dangerous operations require explicit user approval — the web interface ships with UserApprovalHook enabled by default, and file operations are scoped to a designated workspace directory.

Only run it in trusted environments, and review operations before approving them. See SECURITY.md for the full security model, the available safety hooks, intended use, and best practices.

Minimum Working Example

Create powerful AI agents with just a few lines of code:

import os
from orchestral import Agent
from orchestral.tools import (
    RunCommandTool, RunPythonTool, WebSearchTool,
    WriteFileTool, ReadFileTool, EditFileTool,
    FileSearchTool, FindFilesTool, TodoWrite, TodoRead
)
from orchestral.tools.hooks import DangerousCommandHook, SafeguardHook, UserApprovalHook
from orchestral.llm import Claude
from orchestral.prompts import BASIC_APP_PROMPT
import orchestral.ui.app.server as app_server

# Set up the workspace directory the agent operates in
base_directory = "workspace"
os.makedirs(base_directory, exist_ok=True)

# Configure tools
tools = [
    RunCommandTool(),
    RunPythonTool(),
    WriteFileTool(),
    ReadFileTool(show_line_numbers=True),
    EditFileTool(),
    FindFilesTool(),
    FileSearchTool(),
    WebSearchTool(),
    TodoRead(),
    TodoWrite(),
]

# Add safety hooks (REQUIRED for production use)
hooks = [
    UserApprovalHook(),  # Requires user confirmation for dangerous operations
    SafeguardHook(),     # LLM-based safety analysis
    DangerousCommandHook(),  # Pattern-based danger detection
]

# Create agent. Shared state like base_directory is passed once via
# tool_config; the Agent injects it into every tool that needs it.
llm = Claude()
agent = Agent(
    llm=llm,
    tools=tools,
    tool_hooks=hooks,
    system_prompt=BASIC_APP_PROMPT,
    tool_config={"base_directory": base_directory},
)

# Launch web interface
app_server.run_server(agent, host="127.0.0.1", port=8000, open_browser=True)

Features

Multi-Provider Support

• Anthropic (Claude Sonnet, Haiku, Opus)
• OpenAI (GPT-4, GPT-3.5)
• Google (Gemini Pro)
• Groq (Llama, Mixtral)
• Mistral AI
• AWS Bedrock
• Ollama (local models)

Web-Based Interface

• Beautiful, responsive chat interface
• Real-time streaming responses
• Conversation management (create, rename, duplicate, delete)
• Persistent conversation history
• Cost tracking across all providers
• Undo/redo functionality
• Keyboard shortcuts (Shift+Enter for new line, Esc to interrupt)

Powerful Tool System

Built-in tools for common tasks:

• RunCommandTool - Execute shell commands safely
• RunPythonTool - Run Python code in isolated environment
• WriteFileTool - Create and modify files
• ReadFileTool - Read file contents with line numbers
• EditFileTool - Smart file editing with find/replace
• FileSearchTool - Search file contents (ripgrep)
• FindFilesTool - Find files by name/pattern
• WebSearchTool - Search the web for real-time information
• TodoWrite/TodoRead - Task management
• DisplayImageTool - Show images in the interface

All file operations are scoped to a workspace directory for safety.

Safety & Security

• DangerousCommandHook - Warns about potentially harmful commands
• SafeguardHook - Prevents dangerous operations
• UserApprovalHook - Requires confirmation for sensitive actions
• TruncateLinesHook - Limits output size
• Sandboxed file operations

Developer Experience

• Simple, intuitive API
• Extensible tool system - create custom tools easily
• Hook system for pre/post-processing
• Streaming support for real-time responses
• Automatic cost tracking
• Rich formatting (Markdown, LaTeX, code highlighting)
• Context management with automatic summarization

Documentation

Visit orchestral-ai.com/docs for comprehensive documentation, tutorials, and API reference.

Requirements

• Python 3.12 or higher
• At least one LLM provider API key

License

Business Source License 1.1 with Research Use Grant

Orchestral AI is source-available software that is free to use for:

• Academic research and education - Universities, research institutions, and educational purposes
• Government and national laboratory R&D - Research, development, prototyping, and experimentation
• Nonprofit research organizations - Scientific and technological research activities
• Evaluation and testing - Assessing the software at any scale
• Personal learning and experimentation - Individual skill development and projects

Contractors and affiliates working on behalf of eligible academic, nonprofit, or government entities are covered under the same terms.

Publications are unrestricted - Use in academic or scientific publications is fully permitted.

When You Need a Commercial License

A commercial license is required for Commercial Purpose, meaning:

• Providing products or services to external third parties for compensation
• Offering the software (or services based on it) as a commercial service
• Embedding the software in products for commercial sale or distribution

Research and internal development remain free, even at large scale.

License Transition

On February 9, 2030, this software automatically becomes available under the Apache License 2.0.

Version-Specific Licensing

Each version of Orchestral AI has its own license terms. This license applies to version 1.3.0 and later releases unless otherwise specified.

Commercial Licensing Inquiries

For commercial licenses, support agreements, or indemnity arrangements, contact:

alex@orchestral.ai

Full License Text

See the LICENSE file for complete legal terms.

Copyright © 2026 Alex Roman. All rights reserved.

Support

• Documentation: orchestral-ai.com/docs
• Issues: orchestral-ai.com/support
• Email: alex@orchestral.ai