orion-core 0.1.0
A powerful multi-agent orchestration framework for LLMs
License: MIT
Requires Python: >=3.9
Keywords: llm, multi-agent, framework, openai, gemini

# Orion

**THIS README WAS GENERATED BY CHATGPT BECAUSE I AM TOO LAZY**

**Orion** is a highly flexible, extensible, and dynamic multi-agent orchestration framework designed for building and deploying applications powered by large language models (LLMs). With Orion, you can create complex, self-configuring multi-agent systems using a declarative, type‑safe Domain Specific Language (DSL).

> **Owner:**  
> Ashish Kumar Singh  
> This is a hobby project, built with passion and commitment to exploring the cutting edge of multi-agent orchestration.

---

## Table of Contents

- [Vision & Objectives](#vision--objectives)
- [Features](#features)
- [User Experience](#user-experience)
- [Project Architecture & Components](#project-architecture--components)
- [Installation & Setup](#installation--setup)
- [Usage Examples](#usage-examples)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

---

## Vision & Objectives

**Orion** is built on the vision of enabling developers to define, manage, and deploy powerful multi-agent systems with minimal friction and maximum flexibility. The key objectives are **WIP**:

- **Dynamic Agent Orchestration:** Automatically spawn and manage agents based on declarative blueprints and role policies.
- **Declarative DSL:** Define your multi-agent architecture with simple, type‑safe declarations using `ArchitectureBlueprint` and `RolePolicy` constructs.
- **Auto-Generation of Agents:** Under the hood, Orion uses an intelligent `AutoAgentFactory` to automatically determine the best agent configuration—selecting agent types, models, prompts, and even generating custom tools—from a high-level task description, itself generated by some other agent.
- **Plug-and-Play Integration:** Support multiple LLM backends (such as OpenAI and Gemini) and allow agents to communicate seamlessly via a unified messaging layer.
- **Scalability & Extensibility:** Designed to scale from simple applications to complex, large-scale systems (100,000+ lines of code) by using a modular architecture with clearly separated concerns.

---

## Features

- **LLM Client Layer:**  
  - Unified `BaseLLMClient` abstraction with support for streaming and non-streaming predictions.
  - Concrete implementations such as `OpenAIClient` that support function calling, structured outputs, and tool integration.

- **Agents & Tools:**  
  - Abstract `BaseAgent` and concrete implementations like `NormalAgent` for managing conversation history, concurrency, and cancellation.
  - Built-in tool generation using Python functions and dynamic code execution.
  - Specialized agentic tools (e.g., `UseAgenticTool`, `SpawnAgenticTool`, `AutoAgenticTool`) for agent-to-agent communication and dynamic orchestration.

- **Declarative DSL & Orchestration:**  
  - **RolePolicy:** Define roles (e.g., CEO, MANAGER, WORKER) with strict access control, allowed tool sets, and spawn conditions.
  - **ArchitectureBlueprint:** Declaratively specify the hierarchical structure of your multi-agent system.
  - **OrionSystem:** Automatically instantiates and orchestrates agents based on the blueprint and policies.

- **Auto Agent Factory:**  
  - The `AutoAgentFactory` leverages a meta LLM to analyze task descriptions and automatically determine:
    - The best agent type (class) to spawn.
    - The LLM model to use.
    - A detailed system prompt for the agent.
    - Custom tools (with auto-generated Python code) that the agent should have access to.

- **Concurrency & Streaming:**  
  - Built-in support for asynchronous, streaming responses using Python’s concurrency primitives.
  - Real-time handling of tool invocations and cancellation of tasks.

---

## User Experience

Imagine a developer who wishes to build a sophisticated multi-agent system for planning a marketing campaign. With Orion, the process is as simple as writing a few declarative lines:

```python
from orion.dsl.role_policy import Roles, RolePolicy, spawn_condition
from orion.dsl.architecture import ArchitectureBlueprint, OrionSystem
from orion.llm_clients.openai_client import OpenAIClient
from orion.agent_factory.auto import AutoAgentFactory
from orion.agents.normal_agent import NormalAgent  # Our default agent type

# Define role policies
CEO_POLICY = RolePolicy(
    role=Roles.CEO,
    allowed_tools=[],  # Define any tools as needed
    spawnable_roles=[Roles.MANAGER, Roles.WORKER],
    controllable_roles=[Roles.MANAGER, Roles.WORKER],
    spawn_condition=spawn_condition(lambda ctx: ctx.get("complexity", 0) > 7)
)

MANAGER_POLICY = RolePolicy(
    role=Roles.MANAGER,
    allowed_tools=[],
    spawnable_roles=[Roles.WORKER],
    controllable_roles=[Roles.WORKER],
    spawn_condition=spawn_condition(lambda ctx: True)
)

WORKER_POLICY = RolePolicy(
    role=Roles.WORKER,
    allowed_tools=[],
    spawnable_roles=[],
    controllable_roles=[],
    spawn_condition=spawn_condition(lambda ctx: True)
)

# Define the multi-agent architecture blueprint
blueprint = ArchitectureBlueprint(
    roles=[CEO_POLICY, MANAGER_POLICY, WORKER_POLICY],
    initial_structure={
        "root": Roles.CEO,
        "hierarchy": {
            Roles.CEO: [Roles.MANAGER, Roles.WORKER],
            Roles.MANAGER: [Roles.WORKER],
            Roles.WORKER: []
        }
    }
)

# Create an LLM client (using OpenAI as an example)
llm_client = OpenAIClient(api_key="YOUR_API_KEY", model="gpt-4")

# Create an AutoAgentFactory for dynamic agent creation
agent_factory = AutoAgentFactory(
    meta_llm=llm_client,
    default_agent_class=NormalAgent,
    default_model="gpt-4"
)

# Initialize the Orion system
orion_system = OrionSystem(
    blueprint=blueprint,
    llm_client=llm_client,
    agent_factory=agent_factory
)

# Submit a high-level task to the system
result = orion_system.submit_task(
    "Plan a marketing campaign for our new SaaS product",
    context={"complexity": 9}
)

print("Final Result:", result)
```

In this simplified user experience:
- You define **roles** and **hierarchical relationships** with `RolePolicy` and `ArchitectureBlueprint`.
- Orion automatically creates a **root agent** and spawns other agents as needed.
- The **AutoAgentFactory** intelligently configures new agents based on task descriptions.
- You submit tasks with a single call (`submit_task`), and the system handles all the complex orchestration behind the scenes.

---

## Usage Examples of stuff that have been implemented

### Simple Agent Interaction

```python
from orion.agents.normal_agent import NormalAgent
from orion.llm_clients.openai_client import OpenAIClient
from orion.config import config

# Create an LLM client instance
client = OpenAIClient(api_key=config.OPENAI_API_KEY, model="gpt-4o")

# Instantiate a NormalAgent
agent = NormalAgent(
    name="SimpleAgent1",
    role="assistant",
    description="You are a helpful assistant.",
    model_name="gpt-4o",
    api_key=config.OPENAI_API_KEY,
    tools=[]
)

# Interact with the agent (streaming mode)
for chunk in agent.chat("Hello, who are you?", background=False):
    print(chunk, end="")
```

### Using the AutoAgentFactory

```python
from orion.agent_factory.auto import AutoAgentFactory
from orion.llm_clients.openai_client import OpenAIClient
from orion.agents.normal_agent import NormalAgent

# Create an LLM client
client = OpenAIClient(api_key="YOUR_API_KEY", model="gpt-4")

# Instantiate the AutoAgentFactory
auto_factory = AutoAgentFactory(
    meta_llm=client,
    default_agent_class=NormalAgent,
    default_model="gpt-4"
)

# Create a new agent based on a high-level task description
new_agent = auto_factory.create_agent("Plan a comprehensive marketing strategy for a SaaS product.")

print(f"New agent created: {new_agent.name} with prompt: {new_agent.description}")
```

## Roadmap

Orion’s journey is just beginning. The current implementation includes:

- **LLM Client Layer:**  
  - A unified interface (`BaseLLMClient`) and a concrete `OpenAIClient` supporting streaming, function calling, and structured outputs.

- **Agent Layer:**  
  - An abstract `BaseAgent` and a concrete `NormalAgent` with concurrency, streaming, and cancellation support.

- **Tool Integration:**  
  - Mechanisms for function calling and dynamic tool generation.
  
- **Auto Agent Factory:**  
  - `AutoAgentFactory` that uses a meta LLM to automatically determine agent configuration from task descriptions.

### Future Enhancements

- **Declarative DSL:**  
  - `RolePolicy` and `ArchitectureBlueprint` for describing multi-agent systems.
  
- **Advanced Orchestration:**  
  - Develop a comprehensive orchestrator for dynamic agent spawning, task routing, and inter-agent communication.

- **Enhanced Access Control:**  
  - Implement robust role-based and attribute-based policies with a dedicated policy manager.

- **Memory & State Management:**  
  - Integrate long-term memory modules (e.g., vector stores, databases) to enhance agent context and persistence.

- **Distributed Architecture:**  
  - Support for distributed message buses and databases to scale Orion to enterprise-grade deployments.

- **Extended DSL Features:**  
  - Expand the DSL for more granular control of agent behavior, task dependencies, and dynamic reconfiguration.

- **GUI & Monitoring:**  
  - Develop dashboards for real-time monitoring and management of multi-agent systems.

- **Additional LLM Clients & Tools:**  
  - Integrate more LLM backends (e.g., Gemini, Anthropic) and a wider array of built-in tools.

---

## Contributing

Since Orion is a hobby project maintained solely by Ashish Kumar Singh, contributions, feedback, and discussions are welcome. If you find a bug or have ideas for improvements, please open an issue or submit a pull request.

---

## License

This project is provided under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Acknowledgments

A special thanks to all the open-source contributors and communities in the AI and LLM space. Orion is built on the shoulders of giants, and your work continues to inspire and empower new innovations.

---

*Ashish Kumar Singh – Sole Owner & Developer*

Visit the project at: [https://github.com/AshishKumar4/Orion](https://github.com/AshishKumar4/Orion)