allos-agent-sdk 0.0.1

The LLM-Agnostic Agentic Framework

Allos Agent SDK

🚀 The LLM-Agnostic Agentic Framework

Build powerful AI agents without vendor lock-in

Documentation • Roadmap • Contributing

---

🎯 What is Allos?

Allos is an open-source, provider-agnostic agentic SDK that gives you the power to build production-ready AI agents that work with any LLM provider. Inspired by Anthropic's Claude Code, Allos delivers the same outstanding capabilities without locking you into a single ecosystem.

The Problem: Most agentic frameworks force you to choose between vendors, making it expensive and risky to switch models.

The Solution: Allos provides a unified interface across OpenAI, Anthropic, Ollama, Google, and more—so you can use the best model for each task without rewriting your code.

✨ Key Features

🔄 Provider Agnostic

Switch seamlessly between OpenAI, Anthropic, Ollama, and other LLM providers. Use GPT-4 for one task, Claude for another, or run models locally—all with the same code.

🛠️ Rich Tool Ecosystem

Built-in tools for:

• 📁 File operations (read, write, edit)
• 💻 Shell command execution
• 🌐 Web search and fetching (coming soon)
• 🔌 MCP (Model Context Protocol) extensibility (coming soon)

🎛️ Advanced Capabilities

• ⚡ Context Management: Automatic context window optimization
• 🔐 Fine-grained Permissions: Control what your agent can and cannot do
• 💾 Session Management: Save and resume conversations
• 📊 Production Ready: Built-in error handling, logging, and monitoring
• 🎨 Extensible: Easy to add custom tools and providers

🚀 Developer Experience

# Create your own Claude Code in 5 minutes
uv pip install allos-agent-sdk
export OPENAI_API_KEY=your_key
allos "Create a REST API for a todo app"

🆚 Why Allos?

Feature	Allos	Anthropic Agent SDK	LangChain Agents
Provider Agnostic	✅	❌ (Anthropic only)	⚠️ (Complex)
Local Models Support	✅	❌	⚠️
Simple API	✅	✅	❌
Built-in Tools	✅	✅	⚠️
MCP Support	🚧	✅	❌
Production Ready	✅	✅	⚠️
Open Source	✅ MIT	⚠️ Limited	✅

🚀 Quick Start

See the full workflow in action by running our CLI demo script:

bash <(curl -s https://raw.githubusercontent.com/Undiluted7027/allos-agent-sdk/main/examples/cli_workflow.sh)

Installation

We recommend using uv, a fast Python package manager.

# Basic installation
uv pip install allos-agent-sdk

# With specific providers
uv pip install "allos-agent-sdk[openai]"
uv pip install "allos-agent-sdk[anthropic]"
uv pip install "allos-agent-sdk[all]"  # All providers

CLI Usage

The allos CLI is the quickest way to use the agent.

# Set your API key (or use a .env file)
export OPENAI_API_KEY="your_key_here"

# Run a single task
allos "Create a FastAPI hello world app in a file named main.py and then run it."

# Start an interactive session for a conversation
allos -i
# >>> Create a file named 'app.py' with a simple Flask app.
# >>> Now, add a route to it that returns the current time.

# Switch providers and save your session
export ANTHROPIC_API_KEY="your_key_here"
allos -p anthropic -s my_project.json "Refactor the 'app.py' file to be more modular."

Python API

from allos import Agent, AgentConfig

# Simple agent
agent = Agent(AgentConfig(
    provider="openai",
    model="gpt-4",
    tools=["read_file", "write_file", "shell_exec"]
))

result = agent.run("Fix the bug in main.py and add tests")
print(result)

Provider Switching Example

# Start with OpenAI
agent_openai = Agent(AgentConfig(
    provider="openai",
    model="gpt-4",
    tools=["read_file", "write_file"]
))

# Switch to Anthropic for complex reasoning
agent_claude = Agent(AgentConfig(
    provider="anthropic",
    model="claude-sonnet-4-5",
    tools=["read_file", "write_file"]
))

# Or use local models with Ollama (COMING SOON!)
agent_local = Agent(AgentConfig(
    provider="ollama",
    model="qwen2.5-coder",
    tools=["read_file", "write_file"]
))

# Same interface, different providers!
result = agent_openai.run("Create a FastAPI app")

Custom Tools

from allos.tools import BaseTool, tool, ToolParameter

@tool
class DatabaseQueryTool(BaseTool):
    name = "query_database"
    description = "Execute SQL queries"
    parameters = [
        ToolParameter(
            name="query",
            type="string",
            description="SQL query to execute",
            required=True
        )
    ]

    def execute(self, **kwargs: Dict[str, Any]) -> Dict[str, Any]:
        query = kwargs.get("query")
        if not query:
            return {"success": False, "error": "Query parameter is required."}
        # Your implementation
        # In a real scenario, you would connect to a DB.
        # result = your_db.execute(query)
        # For this example, we'll return a mock result.
        return {"status": "success", "result": f"Query '{query}' executed."}

# Use it
agent = Agent(AgentConfig(
    provider="openai",
    model="gpt-4",
    tools=["query_database", "read_file"]
))

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                      CLI Layer                          │
│              (User-friendly interface)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│                   Agent Core                            │
│        (Orchestration & Agentic Loop)                   │
└─────┬──────────────────┬──────────────────┬────────────-┘
      │                  │                  │
┌─────▼────────┐  ┌──────▼───────┐  ┌───────▼──────┐
│  Providers   │  │    Tools     │  │   Context    │
│              │  │              │  │              │
│ • OpenAI     │  │ • FileSystem │  │ • History    │
│ • Anthropic  │  │ • Shell      │  │ • Compactor  │
│ • Ollama     │  │ • Web        │  │ • Cache      │
│ • Google     │  │ • Custom     │  │ • Manager    │
└──────────────┘  └──────────────┘  └──────────────┘

Core Components

1. Provider Layer: Unified interface for all LLM providers
2. Tool System: Extensible toolkit with built-in and custom tools
3. Agent Core: Main agentic loop with planning and execution
4. Context Manager: Automatic context window optimization
5. CLI: User-friendly command-line interface

📊 Provider Support

Provider	Status	Models	Features
OpenAI	✅ Ready	GPT-5, GPT-4, GPT-4o	Tool calling, streaming
Anthropic	✅ Ready	Claude 3, Claude 4 (Opus, Sonnet, Haiku)	Tool calling, streaming
Ollama	🚧 Coming Soon	Llama, Mistral, Qwen, etc.	Local models
Google	🚧 Coming Soon	Gemini Pro, Gemini Ultra	Tool calling
Cohere	📋 Planned	Command R, Command R+	Tool calling
Custom	✅ Ready	Any OpenAI-compatible API	Extensible

🛠️ Built-in Tools

Tool	Description	Permission
read_file	Read file contents	Always Allow
write_file	Write/create files	Ask User
edit_file	Edit files (string replace)	Ask User
list_directory	List directory contents	Always Allow
shell_exec	Execute shell commands	Ask User
web_search	Search the web	📋 Planned
web_fetch	Fetch web page content	📋 Planned

🎯 Use Cases

Coding Agents

# SRE Agent - Diagnose and fix production issues (Web Search COMING SOON!)
sre_agent = Agent(AgentConfig(
    provider="anthropic",
    model="claude-4-opus",
    tools=["read_file", "shell_exec", "web_search"]
))
sre_agent.run("Investigate why the API latency spiked at 3pm")

# Code Review Agent
review_agent = Agent(AgentConfig(
    provider="openai",
    model="gpt-4",
    tools=["read_file", "write_file"]
))
review_agent.run("Review PR #123 for security issues and best practices")

Business Automation

# Data Analysis Agent
data_agent = Agent(AgentConfig(
    provider="openai",
    model="gpt-4",
    tools=["read_file", "write_file", "query_database"]
))
data_agent.run("Analyze Q4 sales data and create a summary report")

# Content Creation Agent (Web Search COMING SOON!)
content_agent = Agent(AgentConfig(
    provider="anthropic",
    model="claude-sonnet-4-5",
    tools=["web_search", "read_file", "write_file"]
))
content_agent.run("Research AI trends and write a blog post")

📚 Documentation

• Getting Started - Installation and first steps
• Quickstart Guide - 5-minute tutorial
• Providers - Provider configuration
• Tools - Using built-in tools
• Custom Tools - Creating your own tools
• CLI Reference - Command-line options
• API Reference - Python API documentation
• Architecture - System design

🗺️ Roadmap

✅ Phase 1: MVP (Current)

• Initial architecture design
• Directory structure
• Provider layer (OpenAI, Anthropic)
• Tool system (filesystem, shell) with user-approval permissions
• Agent core with agentic loop and session management
• CLI interface
• Comprehensive unit, integration, and E2E test suites
• Final documentation and launch prep

See MVP_ROADMAP.md for detailed MVP timeline.

🚧 Phase 2: Enhanced Features

• Ollama integration (local models)
• Google Gemini support
• Web search and fetch tools
• Advanced context management
• Plugin system
• Configuration files (YAML/JSON)
• Session management improvements

🔮 Phase 3: Advanced Capabilities

• MCP (Model Context Protocol) support
• Subagents and delegation
• Pydantic AI integration
• Smolagents compatibility
• Multi-modal support
• Advanced monitoring and observability
• Cloud deployment support

🚧 Known Limitations (MVP)

The current MVP of the Allos Agent SDK is focused on providing a robust foundation. It intentionally excludes some advanced features that are planned for future releases:

• No Streaming Support: The agent currently waits for the full response from the LLM and tools. Real-time streaming of responses is a post-MVP feature.
• Limited Context Management: The agent performs a basic check to prevent exceeding the context window but does not yet implement advanced context compaction or summarization for very long conversations.
• No Async Support: The core Agent and Tool classes are synchronous. An async-first version is planned for a future release.
• Limited Provider Support: The MVP includes openai and anthropic. Support for ollama, google, and others is on the roadmap.
• No Web Tools: Built-in tools for web search (web_search) and fetching URLs (web_fetch) are planned but not yet implemented.
• Basic Error Recovery: While the agent can recover from tool execution errors (like permission denied), it does not yet have sophisticated strategies for retrying failed API calls or self-correcting flawed plans.

Please see our full ROADMAP.md for more details on our plans for these and other features.

🚦 Current Status

🔵 MVP Development is almost complete

All major features for the MVP are implemented and tested.

• ✅ Providers: OpenAI and Anthropic are fully supported.
• ✅ Tools: Secure filesystem and shell tools are included.
• ✅ Agent Core: The agentic loop, permissions, and session management are functional.
• ✅ CLI: A polished and powerful CLI is the primary user interface.
• ✅ Python API: The underlying Python API is stable and ready for use.

Expected MVP Release: 6-8 weeks from project start

We welcome early contributors! See Contributing below.

🤝 Contributing

We're building Allos in the open and would love your help! Whether you're:

• 🐛 Reporting bugs
• 💡 Suggesting features
• 📖 Improving documentation
• 🔧 Submitting PRs
• ⭐ Starring the repo (helps a lot!)

All contributions are welcome! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/Undiluted7027/allos-agent-sdk.git
cd allos-agent-sdk

Python Environment

With pip

# Create virtual environment
python -m venv venv
# For: Mac OS/Linux
source venv/bin/activate
# On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Make the test script executable
chmod +x scripts/run_tests.sh

# Run the default test suite (unit + e2e, no API keys required)
./scripts/run_tests.sh

# Run ONLY integration tests (requires API keys in a .env file)
uv run pytest --run-integration

# Format code
black allos tests
ruff check allos tests --fix

With uv

Ensure you have uv installed. Check out UV Installation Instructions for more information.

# Create virtual environment
uv venv

# Activate environment
# For: MacOS/Linux
source .venv/bin/activate
# For: Windows (Powershell)
# .venv\Scripts\activate

# Install in development mode
uv pip install -e ".[dev]"

# Make the test script executable
chmod +x scripts/run_tests.sh

# Run the default test suite (unit + e2e, no API keys required)
./scripts/run_tests.sh

# Run ONLY integration tests (requires API keys in a .env file)
uv run pytest --run-integration

# Format code
black allos tests
ruff check allos tests --fix

🌟 Stargazers Hall of Fame

A huge thank you to our first 100 stargazers! You're helping build the future of AI agent development. 🚀

No stargazers yet. Be the first! ⭐

Not featured yet? ⭐ Star us on GitHub to join the Hall of Fame!

---

🌟 Why "Allos"?

Allos (Greek: ἄλλος) means "other" or "different" - representing our core philosophy of choice and flexibility. Just as the word implies alternatives and options, Allos gives you the freedom to choose any LLM provider without constraints.

📄 License

Allos is open source and available under the MIT License.

🙏 Acknowledgments

Inspired by:

• Anthropic's Claude Code - For showing what's possible with agentic coding
• LangChain - For pioneering LLM frameworks
• AutoGPT - For autonomous agent patterns

📬 Contact & Community

• GitHub Issues: Report bugs or request features
• Discussions: Join the conversation
• Twitter: @allos_sdk (coming soon)
• Discord: Join our community (coming soon)

---

Built with ❤️ by the open source community

⭐ Star us on GitHub • 🐦 Follow on X