BelArabyAI SDK

A comprehensive Python SDK that enables you to create, manage, and interact with autonomous AI Workers on BelArabyAI. Build powerful AI applications with built-in tools for file operations, web search, image processing, data analysis, and more.

🌟 Features

• 🤖 Autonomous AI Workers - Create intelligent agents that can perform complex tasks
• 🛠️ Built-in Tools - 9 powerful AgentPress tools for common operations
• 🔌 Custom MCP Tools - Integrate your own tools via Model Context Protocol
• 💬 Conversation Management - Handle multi-turn conversations with context
• 📊 Data Analysis - Built-in tools for data collection, analysis, and visualization
• 🖼️ Image Processing - Analyze and edit images with AI
• 🌐 Web Operations - Search the web, browse websites, and deploy applications
• ⚡ Real-time Streaming - Stream responses in real-time for better UX
• 🔒 Production Ready - Comprehensive error handling and robust architecture

🚀 What You Can Build

• Content Creation Bots - Automated writing, research, and content generation
• Data Analysis Pipelines - Automated data collection, processing, and reporting
• Development Assistants - Code generation, debugging, and deployment automation
• Customer Support Agents - Intelligent chatbots with file and web access
• Research Assistants - Automated research with web search and data analysis
• Image Processing Workflows - Automated image analysis and editing
• Business Intelligence - Automated reporting and data visualization

📦 Installation

From PyPI (Recommended)

pip install belaraby-ai-sdk

From GitHub (Development)

pip install "belaraby-ai-sdk @ git+https://github.com/rhkiswani/BelArabyAI-python-sdk"

Or using uv:

uv add belaraby-ai-sdk

🔧 Quick Start

Basic Usage

import asyncio
from belaraby_ai_sdk import BelArabyAI, AgentPressTools

async def main():
    # Initialize the client
    client = BelArabyAI(api_key="your-api-key")

    # Create an agent with built-in tools
    agent = await client.Agent.create(
        name="My Assistant",
        system_prompt="You are a helpful AI assistant.",
        mcp_tools=[AgentPressTools.SB_FILES_TOOL, AgentPressTools.WEB_SEARCH_TOOL],
        allowed_tools=["sb_files_tool", "web_search_tool"]
    )

    # Create a conversation thread
    thread = await client.Thread.create("My Conversation")

    # Run the agent
    run = await agent.run("Hello, how are you?", thread)

    # Stream the response
    stream = await run.get_stream()
    async for chunk in stream:
        print(chunk, end="")

if __name__ == "__main__":
    asyncio.run(main())

Using Custom MCP Tools

import asyncio
from belaraby_ai_sdk import BelArabyAI, MCPTools

async def main():
    # Initialize custom MCP tools
    weather_tools = MCPTools(
        endpoint="http://localhost:4000/mcp/",
        name="weather-service",
        allowed_tools=["get_weather", "get_forecast"]
    )
    await weather_tools.initialize()

    # Initialize the client
    client = BelArabyAI(api_key="your-api-key")

    # Create an agent with custom tools
    agent = await client.Agent.create(
        name="Weather Assistant",
        system_prompt="You are a weather assistant that can provide weather information.",
        mcp_tools=[weather_tools],
        allowed_tools=["get_weather", "get_forecast"]
    )

    # Create a conversation thread
    thread = await client.Thread.create()

    # Run the agent
    run = await agent.run("What's the weather like today?", thread)

    # Stream the response
    stream = await run.get_stream()
    async for chunk in stream:
        print(chunk, end="")

if __name__ == "__main__":
    asyncio.run(main())

Managing Conversations

import asyncio
from belaraby_ai_sdk import BelArabyAI, AgentPressTools

async def main():
    client = BelArabyAI(api_key="your-api-key")

    # Create an agent
    agent = await client.Agent.create(
        name="File Assistant",
        system_prompt="You can help with file operations.",
        mcp_tools=[AgentPressTools.SB_FILES_TOOL]
    )

    # Create a thread
    thread = await client.Thread.create("File Operations")

    # Add multiple messages
    await thread.add_message("Create a new file called 'hello.txt'")
    
    # Run the agent
    run1 = await agent.run("Create a new file called 'hello.txt'", thread)
    
    # Stream the first response
    stream1 = await run1.get_stream()
    async for chunk in stream1:
        print(chunk, end="")
    
    print("\n" + "="*50 + "\n")
    
    # Add another message
    await thread.add_message("Now write 'Hello, World!' to the file")
    
    # Run the agent again
    run2 = await agent.run("Now write 'Hello, World!' to the file", thread)
    
    # Stream the second response
    stream2 = await run2.get_stream()
    async for chunk in stream2:
        print(chunk, end="")

if __name__ == "__main__":
    asyncio.run(main())

🔑 Environment Setup

1. Get your API key from https://belaraby.ai/settings/api-keys
2. Set it as an environment variable:

export BELARABYAI_API_KEY="your-api-key-here"

Or use it directly in your code:

client = BelArabyAI(api_key="your-api-key-here")

🛠️ Available Tools

Built-in AgentPress Tools

• AgentPressTools.SB_FILES_TOOL - Read, write, and edit files
• AgentPressTools.SB_SHELL_TOOL - Execute shell commands
• AgentPressTools.SB_DEPLOY_TOOL - Deploy web applications
• AgentPressTools.SB_EXPOSE_TOOL - Expose local services to the internet
• AgentPressTools.SB_VISION_TOOL - Analyze and understand images
• AgentPressTools.BROWSER_TOOL - Browse websites and interact with web pages
• AgentPressTools.WEB_SEARCH_TOOL - Search the web for information
• AgentPressTools.SB_IMAGE_EDIT_TOOL - Edit and manipulate images
• AgentPressTools.DATA_PROVIDERS_TOOL - Access structured data from various providers

Custom MCP Tools

You can also use custom MCP (Model Context Protocol) tools by providing an HTTP endpoint:

custom_tools = MCPTools(
    endpoint="http://your-mcp-server:4000/mcp/",
    name="your-service",
    allowed_tools=["tool1", "tool2"]  # Optional: filter specific tools
)
await custom_tools.initialize()

📖 Documentation

• Getting Started Guide - Quick start tutorial
• API Reference - Complete API documentation
• Examples Guide - Comprehensive examples

📚 Examples

The SDK comes with comprehensive examples covering various use cases:

🎯 Basic Examples

• basic_usage.py - Simple agent creation and execution
• demo_basic_usage.py - Interactive demo without API key
• error_handling.py - Comprehensive error handling patterns

🔧 Tool-Specific Examples

• file_operations_example.py - File system operations
• web_search_example.py - Web search and browsing
• image_processing_example.py - Image analysis and editing
• data_analysis_example.py - Data collection and analysis
• mcp_tools_example.py - Custom MCP tool integration

🚀 Advanced Examples

• advanced_agent_management.py - Multiple agent management
• conversation_management.py - Thread and message management
• development_workflow_example.py - Full development pipeline
• integration_example.py - External service integration

🛠️ Utility Examples

• kv.py - Local key-value store for agent/thread IDs
• mcp_server.py - Sample MCP server implementation

Running Examples

# Clone the repository
git clone https://github.com/rhkiswani/BelArabyAI-python-sdk.git
cd BelArabyAI-python-sdk

# Install dependencies
pip install -e .

# Set your API key
export BELARABYAI_API_KEY="your-api-key-here"

# Run examples
python examples/basic_usage.py
python examples/file_operations_example.py
python examples/data_analysis_example.py

🧪 Testing

Run the test suite:

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=ba --cov-report=html

# Run specific test categories
pytest tests/test_agent.py -v
pytest tests/test_thread.py -v
pytest tests/test_tools.py -v

📚 API Reference

BelArabyAI Client

client = BelArabyAI(api_key="your-key", api_url="https://belaraby.ai")

Agent Management

# Create an agent
agent = await client.Agent.create(
    name="Agent Name",
    system_prompt="System prompt",
    mcp_tools=[...],  # List of tools
    allowed_tools=[...]  # Optional: filter tools
)

# Get an existing agent
agent = await client.Agent.get("agent-id")

# Update an agent
await agent.update(
    name="New Name",
    system_prompt="New prompt",
    mcp_tools=[...],
    allowed_tools=[...]
)

Thread Management

# Create a thread
thread = await client.Thread.create("Thread Name")

# Get an existing thread
thread = await client.Thread.get("thread-id")

# Delete a thread
await client.Thread.delete("thread-id")

# Add a message to thread
message_id = await thread.add_message("Hello!")

# Delete a message
await thread.delete_message("message-id")

# Get all messages
messages = await thread.get_messages()

# Get agent runs
runs = await thread.get_agent_runs()

Agent Execution

# Run an agent
run = await agent.run("Your prompt", thread)

# Stream the response
stream = await run.get_stream()
async for chunk in stream:
    print(chunk, end="")

🔧 Best Practices

Error Handling

Always wrap your agent operations in try-catch blocks:

try:
    agent = await client.Agent.create(
        name="My Agent",
        system_prompt="You are helpful.",
        mcp_tools=[AgentPressTools.SB_FILES_TOOL]
    )
except Exception as e:
    print(f"Failed to create agent: {e}")
    # Handle error appropriately

Resource Management

Use context managers for proper cleanup:

async with client:
    agent = await client.Agent.create(...)
    thread = await client.Thread.create(...)
    # Your operations here
# Automatic cleanup when exiting context

Performance Optimization

• Stream responses for better user experience
• Reuse agents instead of creating new ones for each task
• Batch operations when possible
• Handle rate limits gracefully

Security Considerations

• Never commit API keys to version control
• Use environment variables for sensitive data
• Validate user inputs before passing to agents
• Implement proper authentication for production apps

🐛 Troubleshooting

Common Issues

1. Authentication Errors

❌ Authentication required. Please check your API key.

Solution: Verify your API key is correct and active at https://belaraby.ai/settings/api-keys

2. Agent Limit Exceeded

❌ Maximum of 2 agents allowed for your current plan.

Solution: Upgrade your plan or delete unused agents

3. Model Access Issues

❌ Your current subscription plan does not include access to anthropic/claude-sonnet-4-20250514

Solution: Upgrade your plan or configure agents to use available models

4. MCP Connection Failures

❌ Client failed to connect: All connection attempts failed

Solution: Ensure your MCP server is running on the specified endpoint

5. Import Errors

❌ ModuleNotFoundError: No module named 'belaraby_ai_sdk'

Solution: Install the package: pip install belaraby-ai-sdk

Debug Mode

Enable debug logging for detailed error information:

import logging
logging.basicConfig(level=logging.DEBUG)

# Your BelArabyAI code here

Getting Help

1. Check the examples - Most common use cases are covered
2. Read the error messages - They often contain helpful guidance
3. Enable debug logging - Get detailed information about failures
4. Check your plan limits - Ensure you have sufficient quota

🚀 Production Deployment

Environment Setup

# Production environment variables
export BELARABYAI_API_KEY="your-production-key"
export BELARABYAI_API_URL="https://belaraby.ai"
export LOG_LEVEL="INFO"

Docker Deployment

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "your_app.py"]

Monitoring

• Monitor API usage and rate limits
• Log agent performance and response times
• Track error rates and failure patterns
• Set up alerts for critical failures

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/BelArabyAI-python-sdk.git
cd BelArabyAI-python-sdk

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

# Run tests
pytest

# Run linting
ruff check .
black --check .

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper tests
4. Run the test suite (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Follow PEP 8 guidelines
• Use type hints for all functions
• Write comprehensive tests for new features
• Update documentation for API changes
• Use descriptive commit messages

📄 License

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

🆘 Support

• 💬 Discord Community: https://discord.gg/qAncfHmYUm - Join our community for discussions, help, and updates
• 🐛 Issues: https://github.com/rhkiswani/BelArabyAI-python-sdk/issues
• 💬 GitHub Discussions: https://github.com/rhkiswani/BelArabyAI-python-sdk/discussions
• 📧 Email: mk@belaraby.com
• 💼 Enterprise: mk@belaraby.com

🙏 Acknowledgments

• Built with ❤️ by the BelArabyAI team
• Powered by advanced AI models and cutting-edge technology
• Special thanks to our community contributors and beta testers