xerus-ai 0.0.7

CLI agent for for running CodeAct agents, built with Huggingface Smolagents

Xerus

A powerful command-line interface for running CodeAct AI agents powered by Huggingface's Smolagents. Xerus is an open-source alternative to OpenAI Codex and Claude Code that leverages cheaper open-source models like Deepseek-R1 to generate and execute Python code for your data science, machine learning, and analytics workflows.

🎯 Designed for Remote Servers: Xerus is primarily intended for use on your remote development servers, providing a seamless way to perform complex Python tasks, data analysis, and ML operations through natural language commands.

🔬 CodeAct Methodology: Built on the CodeAct research (first implemented by Manus AI), Xerus agents generate executable Python code as their primary action space, enabling more flexible and powerful automation compared to traditional tool-based approaches.

🚀 Quick Start

Installation

pip install xerus-ai

Initialize with AI Provider

xerus init

Try It Out!

# Data analysis and visualization
xerus run --prompt "Load my CSV dataset and create correlation heatmaps"

# Machine learning workflows  
xerus run --prompt "Train a random forest classifier on my dataset and evaluate performance"

# Start interactive coding session
xerus chat

# Python development and debugging
xerus run --prompt "Optimize this pandas dataframe operation for better performance"

# Search for latest ML techniques
xerus run --prompt "Find the latest research on transformer architectures and summarize"

📋 Table of Contents

• Installation
• Quick Start
• Why Xerus
• Features
• Configuration
• Commands
• Examples
• Development
• License

🤔 Why Xerus?

💰 Cost-Effective Alternative

• Use cheaper open-source models instead of expensive proprietary APIs
• Mix and match different models for different tools based on your needs
• Support for providers like Nebius, Novita, GMI Cloud with competitive pricing

🏗️ CodeAct Architecture

• Agents generate executable Python code rather than just text responses
• More flexible than pre-defined tool schemas used by other frameworks
• Can compose complex workflows by chaining multiple code executions
• Self-debugging capabilities through iterative code refinement

🎛️ Multi-Model Flexibility

• Use different models for different tasks (e.g., powerful model for complex reasoning, lightweight model for simple operations)
• Connect MCP (Model Context Protocol) servers for extended functionality
• Leverage Huggingface Smolagents for robust agent orchestration

🖥️ Remote Server Optimized

• Designed specifically for headless server environments
• Perfect for data science workstations, ML training servers, and cloud instances
• Terminal-based interface that works seamlessly over SSH

📦 Requirements

• Python 3.10+
• An API key from a supported AI provider

✨ Features

• 🤖 CodeAct Agents: Advanced agents that generate and execute Python code
• 💬 Interactive Chat: Persistent coding sessions with conversation history
• 🔍 Web Search: Built-in research capabilities for latest techniques and documentation
• 🐍 Python Execution: Direct code generation and execution in your environment
• 🔧 Multi-Model Support: Use different models for different tools and tasks
• 🌐 Multiple Providers: Support for Nebius, Novita, GMI Cloud, and more open-source model providers
• 📊 Rich Output: Beautiful terminal output with progress indicators and code syntax highlighting
• 💾 Session Management: Save and restore your coding sessions
• 🔌 MCP Integration: Connect Model Context Protocol servers for extended functionality (MCP Setup Guide)

🏁 Getting Started

Step 1: Install Xerus

Using pip (recommended):

pip install xerus-ai

Using uv:

uv add xerus-ai

Step 2: Initialize Xerus

Before using Xerus, initialize it with an AI provider:

xerus init

This will:

1. Present you with available AI providers
2. Prompt you to enter your API key securely
3. Create configuration files in ~/.xerus/
4. Set secure permissions on sensitive files

Step 3: Start Using Xerus

# Interactive chat
xerus chat

# One-time prompt
xerus run --prompt "Your question here"

Step 4: Customize Your Setup (Optional)

• 🔧 Advanced Configuration: See the Config Customization Guide to customize models, tools, and providers
• 🔌 Add MCP Tools: Follow the MCP Setup Guide to extend capabilities with file system access, GitHub integration, and more

🌟 Supported AI Providers

Provider	Website	Environment Variable
Nebius	studio.nebius.com	NEBIUS_API_KEY
Novita	novita.ai	NOVITA_API_KEY
GMI Cloud	gmicloud.ai	GMI_CLOUD_API_KEY

See LiteLLM providers for the complete list of supported providers.

🛠️ Built-in Tools

Xerus comes with powerful built-in tools:

• web_search - Search the web for real-time information
• python_interpreter - Execute Python code
• duckduckgo_search - Search using DuckDuckGo
• visit_webpage - Load and extract content from URLs
• final_answer - Provide definitive answers
• user_input - Request additional information

📖 Example Use Cases

Data Science & Analytics

# Exploratory data analysis
xerus run --prompt "Load my sales data, identify trends, and create interactive dashboards"

# Statistical analysis and hypothesis testing
xerus run --prompt "Perform A/B testing analysis on my conversion data with statistical significance tests"

# Time series forecasting
xerus run --prompt "Build ARIMA and Prophet models to forecast next quarter's revenue"

Machine Learning & AI

# Model development and training
xerus run --prompt "Create and train a neural network for image classification using my dataset"

# Hyperparameter optimization  
xerus run --prompt "Set up Optuna hyperparameter tuning for my XGBoost model"

# Model deployment preparation
xerus run --prompt "Convert my PyTorch model to ONNX and create a FastAPI serving endpoint"

# MLOps and monitoring
xerus run --prompt "Set up MLflow experiment tracking and model versioning for my project"

Python Development & Optimization

# Code optimization and profiling
xerus run --prompt "Profile my pandas pipeline and optimize for memory efficiency"

# Testing and validation
xerus run --prompt "Generate comprehensive unit tests for my data processing functions"

# Documentation and analysis
xerus run --prompt "Analyze my codebase and generate API documentation with usage examples"

Research & Learning

# Stay updated with latest research
xerus run --prompt "Find and summarize recent papers on transformer efficiency techniques"

# Implementation of research papers
xerus run --prompt "Implement the attention mechanism from the 'Attention Is All You Need' paper"

# Comparative analysis
xerus run --prompt "Compare different optimization algorithms on my dataset and benchmark performance"

🎯 Command Reference

Initialize Xerus

xerus init [--provider PROVIDER] [--api-key KEY] [--force]

Run a Single Prompt

xerus run --prompt "Your prompt" [--save-session] [--session-name NAME]

Interactive Chat

xerus chat [--session-name NAME] [--no-history]

Session Management

xerus sessions          # List all sessions
xerus load SESSION_FILE # Load a session

Model Parameters

You can pass custom parameters to control model behavior:

xerus run --prompt "Write a story" temperature=0.9 top_p=0.95 max_tokens=1000

⚙️ Configuration

Xerus uses ~/.xerus/config.json for configuration. After running xerus init, you can customize:

• Manager agent settings (model, parameters)
• Tool configurations (each tool can use different models/providers)
• Custom tools (add your own tools)
• MCP servers (connect external tools and services)

For detailed configuration options, see the Config Customization Guide.

🔒 Python Library Import Configuration

⚠️ Important Security Note: Xerus CodeAct agents execute Python code directly on your machine's operating system using your local Python runtime. This provides powerful capabilities but requires careful security configuration.

🛡️ Authorized Imports Security

The python_interpreter_agent controls which Python libraries can be imported and executed. This is configured in your ~/.xerus/config.json:

"python_interpreter_agent": {
  "parameters": {
    "authorized_imports": ["math", "random", "datetime", "json", "re"]
  }
}

📚 Configuration Options

🔐 Restricted Mode (Default - Recommended for Local Development)

"authorized_imports": ["math", "pandas", "numpy", "sklearn", "matplotlib"]

• Safe for local development machines
• Limits imports to specific, trusted libraries
• Prevents execution of potentially dangerous system operations

⚠️ Full Access Mode (Use with Extreme Caution)

"authorized_imports": ["*"]

• ⚠️ WARNING: Use ONLY on remote servers or Docker containers
• Allows importing ANY Python library available in your environment
• Enables full system access, file operations, network requests

🏗️ Runtime Environment

Xerus CodeAct agents execute code using:

• Your machine's operating system (Linux, macOS, Windows)
• Your local Python installation and all installed packages
• Your user permissions and file system access
• Your network connection and environment variables

📖 For comprehensive security guidelines and configuration examples, see the Security & Import Configuration Guide.

Example Configuration

{
  "manager_agent": {
    "model_id": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "api_key": "${NEBIUS_API_KEY}",
    "api_base": "https://api.studio.nebius.ai/v1"
  },
  "tools": {
    "web_search_agent": {
      "model_id": "meta-llama/Meta-Llama-3.1-8B-Instruct",
      "api_key": "${NOVITA_API_KEY}",
      "api_base": "https://api.novita.ai/v3/openai"
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/projects"],
      "description": "File system access"
    }
  }
}

💡 Tips

• Save important sessions: Use --save-session or --session-name to keep track of your work
• Use specific prompts: More detailed prompts generally yield better results
• Try different providers: Each provider has different strengths and pricing
• Experiment with parameters: Adjust temperature, top_p, etc. for different behavior
• Configure for your needs: Use the Config Guide to optimize your setup
• Extend with MCP: Add powerful external tools with MCP servers

🔒 Security

• API keys are stored securely with 600 permissions
• Environment variables are supported for CI/CD
• Hidden input when entering sensitive information
• Configuration files are created in your home directory

🚧 Development

From Source

git clone https://github.com/ylankgz/xerus.git
cd xerus
uv sync --dev  # or pip install -e .

Running Tests

uv run pytest  # or pytest

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Documentation

• Config Customization Guide - Detailed configuration options
• MCP Setup Guide - Setting up external tools and services

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions