Skip to content

Updated readme #640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NiveditJain merged 5 commits into from
Jan 2, 2026
Merged

Updated readme #640

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a274361
docs: update README to reflect new features and capabilities of Exosp…
NiveditJain Jan 1, 2026
e82ad79
docs: update README to include marketplace feature and release cycle
NiveditJain Jan 1, 2026
0d94661
Update README to improve introduction, feature highlights, and quick …
NiveditJain Jan 1, 2026
4fadd9b
Refactor README and documentation for clarity and structure
nk-ag Jan 2, 2026
a7b581d
fix: correct spelling in project title for consistency
nk-ag Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 22 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,47 +14,36 @@

---

# Exosphere: Distributed AI Workflow Infrastructure
# Exosphere: Runtime for building and managing AI agents and Workflows

**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.
**Exosphere** is an open-source runtime for creating, orchestrating, and managing the full life-cycle of AI agents and workflows. It is quick to learn, lightning-fast to build with, fault-tolerant by design, and ships with an intuitive, production-ready UI. From tiny single-node scripts to massive distributed systems, whether running locally or in the cloud, Exosphere scales effortlessly across every level of complexity, size, and latency requirement.

![Example Workflow Run](/assets/workflow-run.png)

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Example Workflow Run image was removed. Visual aids like screenshots of a workflow or the dashboard can be very effective in conveying what the project does at a glance and can make the README more engaging. Consider adding an updated image or a GIF in this area to showcase the UI or a workflow in action.

## 🚀 What Exosphere Can Do

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

### **Reliable AI Workflows at Scale**
### **Reliability at Scale**
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add blank lines above subheadings for markdown compliance.

Lines 24, 30, 35, and 40 are subheadings that lack blank lines above them, violating the MD022 (blanks-around-headings) rule. Add a blank line above each of these subheadings to ensure proper markdown formatting and readability.

🔎 Proposed fix 
## 🚀 What Exosphere Can Do

+
### **Reliability 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
 - **Automatic Autoscaling & Back-Pressure**: Elastically scales resources and throttles workloads to maintain SLAs under heavy demand

+
### **Smooth Developer Experience**
 - **Interactive Dashboard**: Visual workflow and agent creation, management, monitoring, and debugging tools
 - **Python-First**: Native Python support with Pydantic models for type-safe inputs/outputs
 - **Plug-and-Play Nodes & Marketplace**: Mix and match reusable atomic components or grab community-contributed tools from the built-in marketplace

+
### **Production-Ready Infrastructure**
 - **Run Anywhere**: Deploy to any compute platform—including Kubernetes, VMs, bare metal, or serverless—with one-click hosting available on Exosphere Cloud
 - **State Persistence & Observability**: Persist every state change and let you query and monitor each step of your AI agents and workflows, even across restarts and failures
 - **API Integration**: Connect to external services and APIs through configurable nodes

+
### **Built for AI Agents**
 - **Autonomous & Self-Improving Execution**: Agents can plan, act, automatically evaluate outcomes, refine their own prompts, and improve over time.
 - **Safe Control Flow**: Blend deterministic logic with non-deterministic reasoning, complete with fallbacks and rollback mechanisms to recover from failed paths.
 - **Scalable Agent Lifecycles**: Sustain stateful agents of any scale-from single-function helpers to sprawling multi-agent collectives—over minutes, months, or more.

Also applies to: 30-30, 35-35, 40-40

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents 
In README.md around lines 24, 30, 35, and 40, several subheadings violate MD022
(no blank line above headings); insert a single blank line directly above each
of those subheading lines so there is an empty line separating the previous
content and the heading, ensuring proper Markdown formatting and compliance.

- **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
- **Automatic Autoscaling & Back-Pressure**: Elastically scales resources and throttles workloads to maintain SLAs under heavy demand

### **Smooth Developer Experience**
- **Plug-and-Play Nodes**: Create reusable, atomic workflow components that can be mixed and matched
- **Interactive Dashboard**: Visual workflow and agent creation, management, monitoring, and debugging tools
- **Python-First**: Native Python support with Pydantic models for type-safe inputs/outputs
- **Interactive Dashboard**: Visual workflow management, monitoring, and debugging tools
- **Plug-and-Play Nodes & Marketplace**: Mix and match reusable atomic components or grab community-contributed tools from the built-in marketplace

### **Production Ready Infrastructure**
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Hyphenate compound adjective before noun.

Line 35 should read ### **Production-Ready Infrastructure** rather than ### **Production Ready Infrastructure** to comply with English grammar conventions for compound adjectives.

🔎 Proposed fix 
-### **Production Ready Infrastructure**
+### **Production-Ready Infrastructure**
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### **Production Ready Infrastructure**
### **Production-Ready Infrastructure**
🧰 Tools
🪛 LanguageTool

[grammar] ~35-~35: Use a hyphen to join words.
Context: ...e built-in marketplace ### Production Ready Infrastructure - *Run Anywhere...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents 
In README.md around line 35, the heading uses "Production Ready Infrastructure"
but the compound adjective should be hyphenated; update the heading to
"Production-Ready Infrastructure" to correct grammar.

- **Kubernetes Native**: Deploy seamlessly on Kubernetes clusters for enterprise-grade scalability
- **State Persistence**: Maintain workflow state across restarts and failures
- **Run Anywhere**: Deploy to any compute platform—including Kubernetes, VMs, bare metal, or serverless—with one-click hosting available on Exosphere Cloud
- **State Persistence & Observability**: Persist every state change and let you query and monitor each step of your AI agents and workflows, even 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
- **Autonomous & Self-Improving Execution**: Agents can plan, act, automatically evaluate outcomes, refine their own prompts, and improve over time.
- **Safe Control Flow**: Blend deterministic logic with non-deterministic reasoning, complete with fallbacks and rollback mechanisms to recover from failed paths.
- **Scalable Agent Lifecycles**: Sustain stateful agents of any scale-from single-function helpers to sprawling multi-agent collectives—over minutes, months, or more.

Exosphere is perfect for a wide range of AI and automation scenarios:
Whether you’re wiring up a simple helper, orchestrating a fleet of cooperative agents, or chaining together complex workflows, Exosphere gives you the rock-solid runtime to ship confidently at any scale.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'Use Cases & Applications' section was removed. This section was very helpful for new users to quickly understand if Exosphere is a good fit for their needs. While the new detailed descriptions are great, a concise list of use cases is highly effective for onboarding. Consider re-adding a similar section before the 'Architecture Overview'. For example:

## 🎯 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**


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

## Architecture Overview

Expand All @@ -81,36 +70,6 @@ Exosphere is built on a flexible, node-based architecture that makes it easy to
- **Store**: Persistent storage for workflow state and data
- **Triggers**: Automatic scheduling with cron expressions
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'Automatic Scheduling Example' was removed from the README. While 'Triggers' are still listed as a key concept, removing the code example makes it harder for users to quickly grasp how to use this feature. To improve discoverability, consider making the 'Triggers' item a direct link to its documentation page.

Suggested change
- **Triggers**: Automatic scheduling with cron expressions
- **[Triggers](https://docs.exosphere.host/exosphere/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`

```python
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

Expand Down Expand Up @@ -311,13 +270,19 @@ Exosphere is designed to make AI workflow development accessible, scalable, and
4. **📖 Read the docs** for comprehensive guides and examples
5. **🤝 Contribute** to help us build the future of AI infrastructure

---

## Contributing
## Release Cycle & Roadmap

We welcome community contributions. For guidelines, refer to our [CONTRIBUTING.md](https://github.com/exospherehost/exospherehost/blob/main/CONTRIBUTING.md).
Exosphere follows a predictable, calendar-based release process:

![exosphere.host Contributors](https://contrib.rocks/image?repo=exospherehost/exospherehost)
- **Monthly Releases**: A new stable version ships at the end of every month.
- **Issue & PR Labelling**: Work intended for a release is tagged `YYYY:Mon` — for example, `2026:Jan`. Filter by this label in GitHub to see exactly what is planned.
- **Living Roadmap**: The collection of items carrying the current month’s label is our public roadmap. Follow along in GitHub Projects to track progress in real time.



## Contributing

We welcome community contributions. For guidelines, refer to our [CONTRIBUTING.md](https://github.com/exospherehost/exospherehost/blob/main/CONTRIBUTING.md).

![exosphere.host Contributors](https://contrib.rocks/image?repo=exospherehost/exospherehost)