orionagent 0.2.5

A lightweight Python framework for building AI agents with tools, sessions, and flexible memory.

OrionAgent

The Sovereign Multi-Agent Orchestration Framework

An Industrially Robust, Minimalistic Multi-Agent System featuring Deterministic Persistence

OrionAgent is built for performance. Efficient by design, it minimizes the "abstraction tax" with Clean Brain optimization, reducing token overhead by up to 50%.

Quick Start  •  Master Skill Guide  •  Core Configuration  •  Architecture  •  Memory Tier  •  OrionAgent vs Others

[!TIP] Attention Vibe Coders / AI Assistants: For high-performance development, reference SKILL.md to master the framework's industrial patterns.

---

Overview

OrionAgent is a cutting-edge multi-agent orchestration framework designed to democratize professional-grade agentic workflows. Powered by the Orion Engine—a smart conversational core featuring Multi-Provider LLM Support (OpenAI, Gemini, Anthropic, Ollama)—OrionAgent offers real-time, actionable task execution for industrial-scale projects.

Whether you are building complex research swarms or precision-driven automation pipelines, the Orion Agent acts as your 24/7 technical companion, ensuring every output is persistent and token-efficient.

---

Philosophy

OrionAgent is designed to eliminate the black box complexity of modern agent frameworks. It provides a low-abstraction, high-control environment for building agents that are token-efficient (via Clean Brain context pruning) and persistent by default.

---

Installation

Install OrionAgent via pip for immediate industrial-grade orchestration:

pip install orionagent

Development Setup

If you are cloning the repository to run examples or contribute, install in editable mode to ensure all local resources are correctly mapped:

git clone https://github.com/Sam-Dev-AI/OrionAgent.git
cd OrionAgent
pip install -e .

---

Quick Start

Single Agent Integration

The Agent class provides a high-performance worker unit with integrated persistence and tool access.

from orionagent import Agent, Gemini, tool

@tool
def crypto_ticker(symbol: str):
    """Fetches real-time prices for crypto assets."""
    return f"Current {symbol} Price: $65,000"

agent = Agent(
    name="Vanguard",
    role="Research Analyst",
    model=Gemini("gemini-2.5-flash", verbose=True),
    memory="long_term",          # Automatic SQLite Knowledge Storage
    use_default_tools=True,      # Integrated Web, File, and OS tools
    tools=[crypto_ticker],
    temperature=0.7,             # Model Creativity Control
)

agent.chat("Analyze the current BTC trend.")

Multi-Agent Orchestration

The Manager coordinates specialized agents through recursive strategy loops.

from orionagent import Agent, Manager, Gemini

# 1. Define Model (Configure logging here)
llm = Gemini("gemini-2.5-flash", debug=True, verbose=True)

# 2. Define Specialized Agents
researcher = Agent(
    name="Researcher",
    role="Technical Scraper",
    system_instruction="Focus on deep technical data sets.",
    use_default_tools=True
)

writer = Agent(
    name="Writer",
    role="Content Strategist",
    system_instruction="Synthesize complex data into premium reports."
)

# 3. Link via Manager (Task Orchestrator)
manager = Manager(
    model=llm,
    agents=[researcher, writer],
    strategy="planning",           # Enable Structured Behavior Lock
)

# OrionAgent automatically detects task complexity.
# Simple greetings skip planning, while complex research triggers orchestration.
manager.chat("Research Gemini 1.5 Pro features and summarize why they matter.")

---

Core Configuration & Architecture

OrionAgent utilizes a granular, declarative configuration system built for industrial-scale reliability. Below is a deep dive into the core execution variables that power the framework.

1. Memory Levels (memory)

OrionAgent uses a Tiered Logic Engine to scale context. Select your ecosystem power level:

Level	Mode	Behavior	Power
1	none	No memory. Static responses only.	Static
2	session	Fast temporary conversation buffer.	Medium
3	long_term	Session + Persistent SQLite (Fact Recall).	High
4	chroma	Session + SQLite + Vector Knowledge (Semantic RAG).	Ultimate

# Initialize an agent with the 'Ultimate' level
from orionagent import Agent
agent = Agent(memory="chroma")

# Advanced configuration
from orionagent import MemoryConfig
agent = Agent(
    memory=MemoryConfig(
        mode="chroma",
        priority="high",            # Depth: 'low', 'medium', or 'high'
        extract_entities=True,      # Enable Knowledge Extraction
        importance_threshold=7      # Sync threshold (1-10)
    )
)

• Semantic Memory (Chroma): Level 4 allows for industrial-scale knowledge persistence using vector embeddings, enabling high-quality RAG.
• Structured Knowledge Vault: Automatically extracts facts (Names, Roles, Decisions) into a JSON schema, ensuring 100% accuracy.
• Priority Tiers: Control how deep the extraction goes with low (token-saving), medium (balanced), and high (exhaustive) tiers.

2. Strategic Orchestration (strategy)

The Manager employs recursive strategy loops to decompose and execute complex goals.

manager = Manager(
    agents=[researcher, analyst],
    strategy=["planning", "self_learn"], # Chain multiple strategies
    max_refinements=2,                   # Self-correction limit
    hitl=True                            # Enable Human-in-the-Loop Safety gate
)

• planning: Decomposes a goal into a roadmap of parallel tasks.
• self_learn: Executes the Verdict Loop—evaluating results and re-delegating with corrected context if quality fails.
• hitl (Safety Gate): When True, the Manager pauses for terminal approval (y/n).

Granular Safety Levels:

from orionagent import HitlConfig
manager = Manager(
    agents=[...],
    hitl=HitlConfig(
        permission_level="medium", # Ask only for risky tasks (delete, shell, etc.)
        ask_once=True,             # Single approval for complex plans
        plan_review=True           # Show full task breakdown
    )
)

Level	Behavior
low	Always asks for approval (Default if hitl=True).
medium	Asks only for high-impact actions (Risk-based).
high	Complete autonomy (Default if hitl=False).

3. Smart Strategy Radar (Planning Threshold)

OrionAgent uses a hybrid routing engine to balance intelligence and cost. Simple conversational tasks automatically bypass expensive orchestration.

Threshold Logic: OrionAgent employs Dynamic Intent Analysis. Instead of static word counts, a lightweight LLM call analyzes the task's complexity to decide the optimal execution path.

• Mode 1: Bypass: Simple tasks (greetings, one-shot questions) $\rightarrow$ Fast Direct Routing.
• Mode 2: Advanced: Complex, multi-step goals $\rightarrow$ Strategic Planning Triggered.

Complexity Keywords (Reference): research, browser, analyze, compare, summary, outline, first, then, finally, steps, plan, extract, find all.

4. High-Performance Execution Engine

OrionAgent is engineered for zero-latency. Control core performance variables directly:

• python_sandbox (New): An industrial-grade Dynamic Reasoning Engine. It executes complex Python logic in RAM ("Ghost Scripts") to verify math, process data, or run simulations without creating temporary files.

# 1. Enable token usage tracking and set logging (Industrial Logs)
llm = Gemini(model_name="gemini-2.5-flash", token_count=True, temperature=0.7, debug=True)

# 2. Control execution speed and streaming
agent = Agent(
    model=llm,
    async_mode=True, # Enable parallel tool calls & strategy steps
    temperature=0.3  # Override model default for this specific agent
)

# 3. Request-level override
agent.ask("What is the speed of light?", temperature=0.0)

• token_count=True: Tracks input/output tokens for precise cost monitoring.
• async_mode=True: Executes independent tasks in parallel (up to 60% faster).
• debug=True: Enables live [PLAN], [TOOL] tags in terminal (Set on the model provider).

---

Detailed Performance Usage

Professional Logging & Observability

OrionAgent offers two tiers of visibility:

1. Industrial Logs (debug=True): Real-time analysis (tags like [TOOL], [PLAN]). Use this to watch agents think and work live.
2. Trace Summary (verbose=True): Post-execution breakdown. Use this for clean, professional reports of timing and token usage.

# NEW Pattern: Enable logging on the LLM provider
llm = Gemini(model_name="gemini-2.5-flash", debug=True, verbose=True)

# Manager and Agents automatically use the provider's logic
manager = Manager(model=llm, agents=[...])
agent = Agent(name="Sentry", model=llm)

Concurrent Orchestration

OrionAgent leverages parallel orchestration to maximize throughput. When async_mode is active, the Manager executes independent task groups simultaneously.

# Explicitly control concurrency (Default: True)
manager = Manager(
    agents=[researcher, coder],
    async_mode=True 
)

• Parallel Tooling: If an agent needs to call 3 tools (e.g., searching 3 different sources), it will execute them in parallel, returning the results in the time of the single slowest call.
• Parallel Strategy: The planning strategy automatically groups tasks that don't depend on each other for simultaneous execution.

---

5. System-Level Token Optimization

OrionAgent minimizes operational overhead by pruning unnecessary context and optimizing prompt density:

• Sliding Window Session Memory: Automatically manages conversation history to prevent context window saturation and rising latency.
• Structured Entity Summarization: Replaces heavy text summaries with lean, categorized fact lists, reducing per-turn token usage by up to 85%.
• Hierarchical Knowledge Sync: Instead of feeding raw history, the long_term tier distills facts into an optimized SQLite DB, ensuring only relevant data is injected into the prompt.
• Priority-Driven Summarizer: Use low priority for casual chats to save tokens with minimalist one-sentence summaries.
• Compact Planning Prompt: The Strategy engine uses a specialized, ultra-lean prompt (~100 tokens) to decompose tasks, ensuring that the heavy lifting is done with minimal structural baggage.
• Precision Tool Routing: Agents only receive the context relevant to the specific step they are executing, preventing "prompt pollution" from unrelated task phases.

Knowledge Base Integration (RAG)

Teach your agent to read local PDFs and Markdown files for private knowledge retrieval.

from orionagent import Agent, Gemini

# Initialize with a knowledge collection
agent = Agent(
    name="Researcher",
    model=Gemini("gemini-2.0-flash"),
    knowledge="corporate_docs" # Creates a persistent index
)

# 1. Ingest content (Manual, File, or Raw Text)
agent.ask("Please read compliance_2024.pdf")
agent.ask("Ingest this raw documentation: [Detailed Protocol Specs...]")

# 2. Query it
answer = agent.ask("What are the new security protocols for 2024?")
print(answer)

---

Architecture Blueprints

Decoupled execution architecture for zero-latency orchestration.

       ┌───────────────────────────────┐
       │      USER MISSION / GOAL      │
       └──────────────┬────────────────┘
                      │
              ┌───────▼───────┐        ┌──────────────────────────┐
              │    MANAGER    │◄──────▶│   STRATEGY ENGINE        │
              │ (Architect)   │        │ (Planning & Self-Learn)  │
              └───────┬───────┘        └──────────────────────────┘
                      │
              ┌───────▼───────┐        ┌──────────────────────────┐
              │    AGENT      │───────▶│    MEMORY CORE           │
              │ (Worker)      │        │ (Hierarchical SQLite)    │
              └───────────────┘        └──────────────────────────┘

---

Memory Architecture & Patterns

Managed through a Hierarchical 3-Tier Synchronizer, OrionAgent maintains state across thousands of interactions without context saturation, enabling seamless multi-agent collaboration.

The 3-Tier Multi-Agent Memory

Tier	Owner	Storage	Purpose
Global Memory	Manager	SQLite + JSON	Cross-agent knowledge hub. Records all agent delegation results.
Local Memory	Each Agent	Session buffer (JSON)	Agent's own conversation history. Fully isolated per agent.
Shared Memory	Optional	ChromaDB (Vector)	Semantic RAG via KnowledgeBase. Shared across agents if configured.

Data Synchronization Flow (The Memory Engine)

graph TD
    User([User Signal]) --> Sync{Manager: Global Hub}
    
    subgraph Multi-Agent Swarm
        Sync -- 1. Record Result --> SQL[(SQLite Global Vault)]
        Sync -- 2. Inject Context --> AgentA[Agent A: Local Memory]
        Sync -- 2. Inject Context --> AgentB[Agent B: Local Memory]
    end
    
    subgraph Shared Level: Ultimate
        AgentA -- Query --> Chroma[(Chroma Vector DB)]
        AgentB -- Query --> Chroma
    end
    
    SQL -- Recall --> Hub[Intelligence Hub]
    Hub --> Final[Orchestrated Output]

State Storage Metrics

• Global Knowledge Briefing: The Manager builds a condensed summary (entities, summaries, history) from the Global Memory vault, injecting it as ### GLOBAL CONTEXT ### into every agent delegation.
• Isolated Local Context: Agents retain their own conversation buffers (Local Memory) so that task-specific details don't pollute the global state unless necessary.
• Semantic Recall (Chroma): Level 4 memory enables RAG-as-a-Service, where all swarm agents can query a shared knowledge base (Shared Memory).

---

---

Framework Comparison

Metric	OrionAgent	LangChain	AutoGen
Abstraction	Minimalist	Heavy	Moderate
Logic Control	Internal Safeguards	Custom Parsers	Limited
Memory	Native SQLite Briefing	Manual Pipeline	Basic Session
Setup Cost	Zero-Config	High Integration	Moderate

---

Contributing & Community

OrionAgent is an open ecosystem. We value contributions that maintain the framework's minimalistic core.

• Reporting Bugs: Use the GitHub Issue Tracker.
• Feature Requests: Open a Discussion thread for architectural review.
• Pull Requests: Ensure all new tools follow the @tool schema validation protocol.

---

Support & Roadmap

If you find OrionAgent valuable, consider starring the repository to support its development.

• Vitals Dashboard: Real-time telemetry Web UI.
• Human-in-the-Loop: Interactive approval gates for critical tool calls.
• Async Multi-Clusters: Parallelized strategy execution across processes.

---

License & Contact

Released under the MIT License. Created by Samir Lade.

OrionAgent: Build Agents That Actually Work.

GitHub  •  PyPI  •  Issue Tracker