Metadata-Version: 2.4
Name: orchestral-ai
Version: 1.6.3
Summary: Production-ready AI framework for building LLM-powered applications with unified tool calling across multiple providers
Author-email: Alex Roman <alex@orchestral.ai>
License: Business Source License 1.1
Project-URL: Homepage, https://orchestral.ai
Project-URL: Documentation, https://orchestral.ai/docs
Project-URL: Issues, https://orchestral.ai/support
Keywords: ai,llm,agent,anthropic,openai,claude,gpt,chatbot,assistant,framework,tool-calling,multi-provider
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: requests>=2.28.0
Requires-Dist: anthropic>=0.64.0
Requires-Dist: openai>=1.102.0
Requires-Dist: groq>=0.22.0
Requires-Dist: ollama>=0.5.1
Requires-Dist: pexpect>=4.8.0; sys_platform != "win32"
Requires-Dist: wexpect>=4.0.0; sys_platform == "win32"
Requires-Dist: setuptools<81; sys_platform == "win32"
Provides-Extra: google
Requires-Dist: google-genai>=1.56.0; extra == "google"
Requires-Dist: google-api-core>=2.28.0; extra == "google"
Provides-Extra: mistral
Requires-Dist: mistralai>=1.2.0; extra == "mistral"
Provides-Extra: bedrock
Requires-Dist: boto3>=1.35.0; extra == "bedrock"
Provides-Extra: vllm
Requires-Dist: openai>=1.102.0; extra == "vllm"
Provides-Extra: ui
Requires-Dist: rich>=13.0.0; extra == "ui"
Requires-Dist: fastapi>=0.100.0; extra == "ui"
Requires-Dist: uvicorn>=0.23.0; extra == "ui"
Requires-Dist: websockets>=11.0.3; extra == "ui"
Provides-Extra: all-providers
Requires-Dist: orchestral-ai[bedrock,google,mistral]; extra == "all-providers"
Provides-Extra: full
Requires-Dist: orchestral-ai[all-providers,ui]; extra == "full"
Provides-Extra: tools-only
Dynamic: license-file

<div align="center">
  <img src="https://orchestral-ai.com/logo.png" alt="Orchestral AI" width="120">
  <h1>Orchestral AI</h1>
  <p><strong>Production-ready AI framework for building LLM-powered applications</strong></p>
  <p>Unified tool calling across multiple providers • Web-based interface • Real-time streaming</p>
</div>

---

## Quick Start

### Installation

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

```bash
pip install 'orchestral-ai[ui]'
```

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

```bash
pip install orchestral-ai
```

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

```bash
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:

```env
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

```bash
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](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:

```python
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](https://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](LICENSE) file for complete legal terms.

Copyright © 2026 Alex Roman. All rights reserved.

---

## Support

- **Documentation**: [orchestral-ai.com/docs](https://orchestral-ai.com/docs)
- **Issues**: [orchestral-ai.com/support](https://orchestral-ai.com/support)
- **Email**: alex@orchestral.ai

---

<div align="center">
  <p>Built by the Orchestral AI team</p>
</div>
