Orchestral

AI agent framework with unified tool calling across multiple LLM providers

Features

• Web-based conversation interface with persistence
• Support for Anthropic (Claude), OpenAI (GPT), and Google (Gemini)
• Extensible tool system for file operations, code execution, and web search
• Real-time streaming responses with cost tracking
• Conversation management (rename, duplicate, delete, undo)

Quick Start

Prerequisites

• Python 3.12 or higher
• OpenAI API key (required for core functions)
• Additional provider keys optional (Anthropic, Google)

Installation

Mac/Linux:

git clone https://github.com/orchestralAI/orchestral-core.git
cd orchestral-core
./setup.sh

Windows:

git clone https://github.com/orchestralAI/orchestral-core.git
cd orchestral-core
setup.bat

The setup script will install dependencies and prompt you to configure API keys interactively.

Running the App

Activate the virtual environment:

source orchestral-env/bin/activate  # Mac/Linux
orchestral-env\Scripts\activate     # Windows

Start the web interface:

python demos/app_demo.py

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

API Keys

The setup script will guide you through adding API keys. You can also edit .env manually:

OPENAI_API_KEY=sk-proj-...        # Required
ANTHROPIC_API_KEY=sk-ant-...      # Optional
GOOGLE_API_KEY=AIza...            # Optional

Get your keys:

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/
• Google: https://aistudio.google.com/app/apikey

Using the Interface

• Send messages - Type and press Enter (Shift+Enter for new line)
• New conversation - Click "+" in sidebar
• Manage conversations - Click "⋯" to rename, duplicate, or delete
• Track costs - Click "Cost" button
• Undo - Remove last message
• Interrupt - Press Esc while agent is processing

Available Tools

• RunCommandTool - Execute shell commands
• RunPythonTool - Run Python code
• WriteFileTool - Create and modify files
• ReadFileTool - Read file contents
• WebSearchTool - Search the web

File operations are scoped to app/workspace/ for safety.

Project Structure

orchestral_core/
├── orchestral/              # Core framework
│   ├── agent/              # Agent orchestration
│   ├── llm/                # LLM provider clients
│   ├── tools/              # Tool system
│   └── ui/                 # UI components
├── app/                    # Web application
│   ├── server.py           # Web server
│   ├── workspace/          # Agent workspace
│   └── conversations/      # Saved conversations
└── demos/                  # Demo scripts

Documentation

• CONTRIBUTING.md - Development guidelines
• orchestral_core/CLAUDE.md - Framework overview
• app/README.md - Web app architecture

Troubleshooting

Module not found:

cd orchestral_core && pip install -e .

API key errors:

• Verify .env exists and contains your keys
• Check for extra spaces or quotes

Port 8000 in use: Edit demos/app_demo.py and change the port number

Windows activation issues:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

License

All code contained in this repository is the property of Orchestral AI. Unauthorized reproduction, use, or distribution of this code, in whole or in part, is strictly prohibited without prior written permission from Alex Roman or an authorized representative of Orchestral AI.