orchestral-ai 1.3.1

Production-ready AI framework for building LLM-powered applications with unified tool calling across multiple providers

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

pip install orchestral-ai

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

---

🔒 Important Security Information

⚠️ CRITICAL: This framework is a development tool that enables AI agents to interact with your local system.

What This Package Does

Orchestral AI is an AI agent development framework designed for software developers. It provides tools that allow LLM-powered agents to:

• Execute shell commands (when explicitly authorized by the user)
• Read and modify files within a designated workspace (with user confirmation)
• Run Python code in isolated environments
• Search the web for information

User Control and Safety

All potentially dangerous operations require explicit user approval:

1. UserApprovalHook - Prompts the user to approve or deny each command before execution
2. SafeguardHook - LLM-based safety analysis before executing operations
3. DangerousCommandHook - Pattern-based detection and warnings for risky commands
4. Workspace Sandboxing - All file operations are restricted to a designated directory

By default, the web interface includes UserApprovalHook, which means:

• The AI cannot execute commands without your explicit permission
• Each potentially dangerous operation shows a confirmation prompt
• You can review exactly what will be executed before it runs
• You maintain full control over your system

Intended Use

This package is intended for:

• ✅ Software development - Building applications with AI assistance
• ✅ Automation workflows - Creating AI-powered development tools
• ✅ Research and experimentation - Exploring LLM capabilities in controlled environments
• ✅ Educational purposes - Learning about AI agent frameworks

This package is NOT intended for:

• ❌ Malicious purposes or unauthorized access to systems
• ❌ Running on untrusted or production systems without proper safeguards
• ❌ Unattended operation without user supervision

Best Practices

1. Always use approval hooks when working with file system or command execution tools
2. Review commands before approving them
3. Use dedicated workspaces - Don't point agents at critical system directories
4. Run in isolated environments - Use virtual machines or containers when experimenting
5. Keep API keys secure - Store them in .env files, never commit them to version control

Transparency

We believe in complete transparency about what this framework does:

• All source code is readable Python (no obfuscation)
• Tool implementations are straightforward and auditable
• Security hooks are clearly documented
• Users maintain full control through approval mechanisms

---

💡 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 workspace
base_directory = "workspace"
os.makedirs(base_directory, exist_ok=True)

# Configure tools
tools = [
    RunCommandTool(base_directory=base_directory),
    RunPythonTool(base_directory=base_directory),
    WriteFileTool(base_directory=base_directory),
    ReadFileTool(base_directory=base_directory, show_line_numbers=True),
    EditFileTool(base_directory=base_directory),
    FindFilesTool(base_directory=base_directory),
    FileSearchTool(base_directory=base_directory),
    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
llm = Claude()
agent = Agent(
    llm=llm,
    tools=tools,
    tool_hooks=hooks,
    system_prompt=BASIC_APP_PROMPT
)

# 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:

📧 [e-mail]

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: [e-mail]

---

Built with ❤️ by the Orchestral AI team