Exosphere: Distributed AI Workflow Infrastructure

Exosphere is an open-source, Kubernetes-native infrastructure platform designed to run distributed AI workflows and autonomous agents at scale. Built with Python and based on a flexible node-based architecture, Exosphere enables developers to create, deploy, and manage robust AI workflows that can handle large-scale data processing and long-running operations.

🚀 What Exosphere Can Do

Exosphere provides a powerful foundation for building and orchestrating AI applications with these key capabilities:

Reliable AI Workflows at Scale

Infinite Parallel Agents: Run multiple AI agents simultaneously across distributed infrastructure
Dynamic State Management: Create and manage state at runtime with persistent storage
Fault Tolerance: Built-in failure handling and recovery mechanisms for production reliability
Core Concepts: Fanout, Unite, Signals, Retry Policy, Store, Triggers

Smooth Developer Experience

Plug-and-Play Nodes: Create reusable, atomic workflow components that can be mixed and matched
Python-First: Native Python support with Pydantic models for type-safe inputs/outputs
Interactive Dashboard: Visual workflow management, monitoring, and debugging tools

Production Ready Infrastructure

Kubernetes Native: Deploy seamlessly on Kubernetes clusters for enterprise-grade scalability
State Persistence: Maintain workflow state across restarts and failures
API Integration: Connect to external services and APIs through configurable nodes

Built for AI Agents

Autonomous Execution: Build agents that can make decisions and execute complex workflows
Data Processing: Handle large datasets with distributed processing capabilities
Long-Running Operations: Support for workflows that run for hours, days, or indefinitely

Whether you're building data pipelines, AI agents, or complex workflow orchestrations, Exosphere provides the infrastructure backbone to make your AI applications production-ready and scalable.

🎯 Use Cases & Applications

Exosphere is perfect for a wide range of AI and automation scenarios:

Data Processing & ETL Pipelines
AI Agent Orchestration
Content Generation & Analysis
API Integration & Automation

Architecture Overview

Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:

Core Components

Nodes: Atomic, reusable units of work that can be AI agents, API calls, data processors, or any custom logic
Runtime: The execution environment that manages and orchestrates your nodes
State Manager: Handles persistent state across workflow executions
Dashboard: Visual interface for monitoring and managing workflows
Graphs: Define the flow and dependencies between nodes

Key Concepts

Fanout: Distribute work across multiple parallel instances of a node
Unite: Combine results from multiple parallel executions
Signals: Inter-node communication and event handling
Retry Policy: Configurable failure handling and recovery
Store: Persistent storage for workflow state and data
Triggers: Automatic scheduling with cron expressions

⏰ Automatic Scheduling Example

Schedule your workflows to run automatically using cron expressions:

!!! info "Beta Feature" Available in beta-latest Docker tag and SDK version 0.0.3b1

from exospherehost import StateManager, GraphNodeModel, CronTrigger

# Define triggers for automatic execution
triggers = [
    CronTrigger(expression="0 9 * * 1-5"),  # Every weekday at 9 AM
    CronTrigger(expression="0 */6 * * *")   # Every 6 hours
]

# Create graph with automatic scheduling
result = await state_manager.upsert_graph(
    graph_name="data-pipeline",
    graph_nodes=graph_nodes,
    secrets={"api_key": "your-key"},
    triggers=triggers  # Enable automatic execution (Beta)
)

Deployment Options

Local Development: Run with Docker Compose for quick setup
Kubernetes: Production-ready deployment on K8s clusters
Cloud: Deploy on any cloud provider with Kubernetes support

🚀 Getting Started

Prerequisites

Python 3.12+
uv (recommended) or pip

Step 1: Installation

uv add exospherehost

Step 2: Create Your First Node

Each node is an atomic, reusable unit in Exosphere. Once registered, you can plug it into any workflow. Nodes can be AI agents, API calls, data processors, or any custom logic you want to execute.

from exospherehost import BaseNode
from pydantic import BaseModel

class CityAnalyzerNode(BaseNode):
    """A node that analyzes and describes a city using AI"""
    
    class Inputs(BaseModel):
        city: str
        analysis_type: str = "general"  # general, tourism, business, etc.

    class Outputs(BaseModel):
        description: str
        key_features: str
        score: str

    class Secrets(BaseModel):
        openai_api_key: str  # Optional: for AI-powered analysis

    async def execute(self) -> Outputs:
        # Your custom logic here - could be:
        # - AI agent calls
        # - API requests
        # - Data processing
        # - Database queries
        # - Any Python code!
        
        description = f"Analysis of {self.inputs.city}"
        features = ["culture", "economy", "lifestyle"]
        score = 8.5
        
        return self.Outputs(
            description=description,
            key_features=json.dumps(features),
            score=str(score)
        )

Step 3: Create and Start the Runtime

Create the runtime and register your nodes:

from exospherehost import Runtime

# Initialize the runtime with your nodes
runtime = Runtime(
    name="city-analysis-runtime",
    namespace="my-project",
    nodes=[CityAnalyzerNode]
)

# Start the runtime (this will block the main thread)
runtime.start()

Run your application:

uv run main.py

Your runtime is now running and ready to process workflows! 🎉

Step 4: Define Your First Graph

Graphs can be defined using JSON objects or with the new model-based Python SDK (beta) for better type safety and validation. See Graph definitions for more examples.

from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, RetryStrategyEnum

async def create_graph():
    state_manager = StateManager(namespace="hello-world")
    
    graph_nodes = [
        GraphNodeModel(
            node_name="MyFirstNode",
            namespace="hello-world", 
            identifier="describe_city",
            inputs={"city": "initial"},
            next_nodes=[]
        )
    ]
    
    # Optional: Define retry policy (beta)
    retry_policy = RetryPolicyModel(
        max_retries=3,
        strategy=RetryStrategyEnum.EXPONENTIAL,
        backoff_factor=2000
    )
    
    # Create graph with model-based approach (beta)
    result = await state_manager.upsert_graph(
        graph_name="my-first-graph",
        graph_nodes=graph_nodes,
        secrets={},
        retry_policy=retry_policy  # beta
    )

Quick Start with Docker Compose

Get Exosphere running locally in under 2 minutes:

# Option 1: With cloud MongoDB (recommended)
echo "MONGO_URI=your-mongodb-connection-string" > .env
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
docker compose up -d

# Option 2: With local MongoDB (development)
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
docker compose -f docker-compose-with-mongodb.yml up -d

Environment Configuration:

Docker Compose automatically loads .env files from the working directory
Create your .env file in the same directory as your docker-compose file

Access your services:

Dashboard: http://localhost:3000
API: http://localhost:8000

📝 Note: This configuration is for development and testing only. For production deployments, environment variable customization, and advanced configuration options, please read the complete Docker Compose Setup Guide.

📚 Documentation & Resources

Essential Guides

Getting Started Guide: Complete walkthrough for new users
Docker Compose Setup: Run Exosphere locally in minutes
Architecture Guide: Understand core concepts like fanout and unite
Youtube Walkthroughs: Step by step demos on Exosphere and how to build reliable flows with sample code.
Featured Exosphere Projects: Templates on common projects on Exosphere, pull and run!

Advanced Topics

State Manager Setup: Production deployment guide
Dashboard Guide: Visual workflow management
Graph Definitions: Building complex workflows

Community & Support

Official Documentation: Complete reference and tutorials
Discord Community: Get help and connect with other developers
GitHub Issues: Report bugs and request features
PyPI Package: Latest stable releases

🌟 Open Source Commitment

We believe that open source is the foundation of innovation and progress. Exosphere is our contribution to this movement, and we're committed to supporting the community in multiple ways:

Our Promise to the Community

🔄 Open Source First: The majority of our codebase is open source and available to everyone
💰 Giving Back: A portion of our profits goes directly to supporting open source projects and communities
🎓 Mentorship: We actively collaborate with student programs to mentor the next generation of developers
🤝 Community Driven: We welcome contributions, feedback, and collaboration from developers worldwide

Get Involved

Contributors: Help us build the future of AI infrastructure
Users: Your feedback shapes our roadmap and priorities
Students: Join our mentorship programs and grow your skills
Organizations: Partner with us to advance open source AI tools

Ready to make a difference? Reach out to us at nivedit@exosphere.host and let's push the boundaries of what's possible together! 🚀

🎯 Ready to Get Started?

Exosphere is designed to make AI workflow development accessible, scalable, and production-ready. Whether you're building your first AI agent or scaling to thousands of parallel workflows, Exosphere provides the infrastructure you need.

Next Steps:

⭐ Star this repository to show your support
🚀 Try the quick start with our Docker Compose setup
💬 Join our Discord community for help and discussions
📖 Read the docs for comprehensive guides and examples
🤝 Contribute to help us build the future of AI infrastructure

Contributing

We welcome community contributions. For guidelines, refer to our CONTRIBUTING.md.

FilesExpand file tree

README.md

Latest commit

History