Updated readme #640
Updated readme #640
Conversation
…here - Revised project description to emphasize Exosphere as a runtime for AI agents and workflows. - Enhanced sections on reliability, developer experience, and production readiness. - Added details on autonomous execution and scalable agent lifecycles. - Removed outdated examples and streamlined content for clarity.
- Expanded the "Plug-and-Play Nodes" section to highlight the new marketplace for community-contributed tools. - Added a new section detailing the release cycle and roadmap, including monthly releases and issue labeling for better project tracking.
…start section - Unified agent/workflow runtime description for clarity and conciseness - Enhanced feature bullet points for reliability, developer experience, and infrastructure sections - Added clear quick-start sample for faster onboarding - Improved badge organization and external resource links - Applied minor copy editing, structure, and layout alignment across readme variants
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughREADME and site docs were extensively rewritten to rebrand Exosphere as a reliability runtime for AI agents, restructure content (features, architecture, roadmap, contributing), remove long-form deployment tutorials, add new layout/HTML snippets, and update CSS and mkdocs navigation/extensions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @NiveditJain, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request refines the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly overhauls the README.md to present a more polished and comprehensive overview of Exosphere. The descriptions of key features are now more benefit-oriented and detailed. A new section on the release cycle and roadmap has been added, which is a great addition for transparency. My review includes a few suggestions to further improve the user experience by re-introducing a concise 'Use Cases' section, adding a visual element back, and improving navigation to the documentation for key concepts like 'Triggers'.
| **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. | ||
|
|
||
|  | ||
|
|
There was a problem hiding this comment.
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.
README.md
Outdated
| - **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. |
There was a problem hiding this comment.
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**
README.md
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
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.
| - **Triggers**: Automatic scheduling with cron expressions | |
| - **[Triggers](https://docs.exosphere.host/exosphere/triggers)**: Automatic scheduling with cron expressions |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
README.md
🧰 Additional context used
🪛 LanguageTool
README.md
[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)
README.md
24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
40-40: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔇 Additional comments (1)
README.md (1)
17-45: Excellent narrative rewrite—clear, cohesive, and well-executed.The repositioning from a Kubernetes-native platform to a scalable runtime for AI agents and workflows is comprehensive and consistent throughout. The new feature descriptions (Autonomous & Self-Improving Execution, Safe Control Flow, Scalable Agent Lifecycles) and the multi-platform emphasis align well with modern AI infrastructure positioning. The new Release Cycle & Roadmap section adds transparency and the Contributing section strengthens community engagement.
Also applies to: 274-287
README.md
Outdated
| Exosphere provides a powerful foundation for building and orchestrating AI applications with these key capabilities: | ||
|
|
||
| ### **Reliable AI Workflows at Scale** | ||
| ### **Reliability at Scale** |
There was a problem hiding this comment.
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.
README.md
Outdated
| - **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** |
There was a problem hiding this comment.
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.
| ### **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.
- Updated the project description to emphasize Exosphere as a reliability runtime for AI agents. - Reorganized feature sections into a table format for better readability and accessibility. - Enhanced the "Why Exosphere?" section to highlight key capabilities and benefits. - Added a new image asset to illustrate functionality. - Improved navigation structure in documentation and added new markdown extensions for better formatting. - Streamlined content across various sections for consistency and clarity.
- Updated the project title from "Reliablity" to "Reliability" to ensure accurate representation of Exosphere's purpose as a runtime for AI agents.
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
assets/how.pngis excluded by!**/*.png
📒 Files selected for processing (5)
README.mddocs/docs/exosphere/concepts.mddocs/docs/index.mddocs/docs/stylesheets/extra.cssdocs/mkdocs.yml
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-03T04:26:00.148Z
Learnt from: NiveditJain
Repo: exospherehost/exospherehost PR: 131
File: state-manager/app/models/executed_models.py:0-0
Timestamp: 2025-08-03T04:26:00.148Z
Learning: The exospherehost project is currently in beta phase, so breaking changes in APIs are acceptable and don't require versioning or migration strategies.
Applied to files:
docs/docs/index.md
🪛 LanguageTool
docs/docs/index.md
[grammar] ~54-~54: Use a hyphen to join words.
Context: ...ion designed for agentic flows with node based control of execution. <d...
(QB_NEW_EN_HYPHEN)
[grammar] ~80-~80: Use a hyphen to join words.
Context: ...ady and scalable. --- Watch the Step by Step Demo: <a href="https://www.yo...
(QB_NEW_EN_HYPHEN)
[grammar] ~80-~80: Use a hyphen to join words.
Context: ... and scalable. --- Watch the Step by Step Demo: <a href="https://www.youtu...
(QB_NEW_EN_HYPHEN)
[uncategorized] ~128-~128: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... visual dashboard. ## Open Source Commitment We believe that humanity wo...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[style] ~131-~131: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...we want to be a part of this movement! Please feel free to reach out to us at [nivedit@exosphere.h...
(FEEL_FREE_TO_STYLE_ME)
README.md
[uncategorized] ~105-~105: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...t/) | Latest stable releases | --- ## Open Source Commitment We believe that humanity wo...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[style] ~108-~108: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...We want to be a part of this movement. Please feel free to reach out to us at [nivedit@exosphere.h...
(FEEL_FREE_TO_STYLE_ME)
🪛 markdownlint-cli2 (0.18.1)
docs/docs/exosphere/concepts.md
1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
README.md
54-54: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🔇 Additional comments (11)
docs/docs/stylesheets/extra.css (2)
117-177: LGTM! Well-structured responsive card system.The feature grid and card styling is well-implemented with:
- Responsive grid layout using
minmax(280px, 1fr)- Performant hover transitions on
transformandbox-shadow- Proper theme-specific overrides for dark/light modes
- Consistent use of CSS variables
113-115: Body text on ultra-wide displays will exceed comfortable reading line-length without max-width constraints.Removing
max-width: 100%on.md-gridallows body paragraphs to span the full viewport width. Material Design's default constraints exist to maintain ~60-80 character line lengths for readability. While the.feature-griditself uses responsive constraints (minmax(280px, 1fr)), body text like the introduction paragraph will be difficult to read on displays wider than ~1400px. Consider either:
- Setting a reasonable
max-widthon.md-grid(e.g.,1200pxor1400px) for body content while allowing feature-cards to adapt responsively, or- Applying the responsive grid constraints to the page layout itself rather than removing all width limits
README.md (2)
25-79: LGTM! Clear table-based content structure.The transformation from prose to structured tables significantly improves scannability and makes key features, components, and concepts easy to reference. The consistent linking to documentation sections helps users navigate to detailed information.
113-121: LGTM! Clear and transparent release process.The calendar-based release cycle with GitHub label tracking (
YYYY:Mon) provides excellent transparency for users and contributors. This makes the roadmap easily accessible and sets clear expectations.docs/docs/exosphere/concepts.md (1)
1-3: LGTM! Title and positioning align with documentation restructure.The simplified title works well with the navigation changes in
mkdocs.ymlwhere this page is now under "Why Exosphere?" → "Concepts Overview". The updated positioning statement reinforces the reliability/agent orchestration narrative.docs/mkdocs.yml (2)
124-125: LGTM! Extensions enable the new card-based layout.Adding
attr_listandmd_in_htmlmarkdown extensions is necessary to support the HTML/markdown hybrid feature cards introduced indocs/docs/index.md. These extensions are part of the Python-Markdown ecosystem and are well-supported by Material for MkDocs.
149-168: LGTM! Navigation restructure improves information architecture.The navigation changes effectively support the rebranding:
- "Why Exosphere?" → "Concepts Overview" provides better context for new users
- "Graph Components" and "Graph Validation" are clearer than generic "Components" and "Validation"
These changes align with the content updates across the documentation.
docs/docs/index.md (4)
1-3: LGTM! HTML logo centering aligns with new layout.Using HTML for the logo with centered alignment works well with the mkdocs extensions enabled in
docs/mkdocs.yml(attr_listandmd_in_html). This provides better control over the logo sizing and positioning.
24-74: LGTM! Feature card grid implementation is consistent.The HTML/markdown hybrid feature cards properly utilize:
- The
.feature-gridand.feature-cardclasses defined inextra.css- The
markdownattribute on divs (enabled byattr_listextension)- Proper nesting and closing of divs
The structure should render correctly with the Material for MkDocs configuration.
82-84: LGTM! Effective use of visual demo content.The YouTube video link with thumbnail image provides an engaging way for users to see Exosphere in action. This addresses previous feedback about the value of visual aids in documentation.
89-125: LGTM! Clear getting-started workflow.The four-card layout for "Run your first agent" provides a logical progression: Getting Started → Run Node → Trigger → Deploy & Monitor. The 2-column grid (specified in inline style) works well for this smaller set of cards.
| ### [Dynamic Execution Graphs](./exosphere/concepts.md) | ||
|
|
||
| ### Create | ||
| Durable execution designed for agentic flows with node based control of execution. |
There was a problem hiding this comment.
Hyphenate compound adjective.
The phrase "node based control" should be "node-based control" when used as a compound adjective modifying "execution".
🔎 Proposed fix
-Durable execution designed for agentic flows with node based control of execution.
+Durable execution designed for agentic flows with node-based control of execution.📝 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.
| Durable execution designed for agentic flows with node based control of execution. | |
| Durable execution designed for agentic flows with node-based control of execution. |
🧰 Tools
🪛 LanguageTool
[grammar] ~54-~54: Use a hyphen to join words.
Context: ...ion designed for agentic flows with node based control of execution. <d...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/docs/index.md around line 54, the phrase "node based control of
execution" uses "node based" as a compound adjective and should be hyphenated;
change it to "node-based control of execution" so the compound adjective is
correctly formatted.
| --- | ||
|
|
||
| Your runtime is now running and ready to process workflows! | ||
| **Watch the Step by Step Demo**: |
There was a problem hiding this comment.
Hyphenate compound adjective in heading.
"Step by Step" should be hyphenated as "Step-by-Step" when used as a compound adjective before "Demo".
🔎 Proposed fix
-**Watch the Step by Step Demo**:
+**Watch the Step-by-Step Demo**:📝 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.
| **Watch the Step by Step Demo**: | |
| **Watch the Step-by-Step Demo**: |
🧰 Tools
🪛 LanguageTool
[grammar] ~80-~80: Use a hyphen to join words.
Context: ...ady and scalable. --- Watch the Step by Step Demo: <a href="https://www.yo...
(QB_NEW_EN_HYPHEN)
[grammar] ~80-~80: Use a hyphen to join words.
Context: ... and scalable. --- Watch the Step by Step Demo: <a href="https://www.youtu...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/docs/index.md around line 80, the heading "Watch the Step by Step Demo"
uses "Step by Step" as a compound adjective and should be hyphenated; update the
heading to "Watch the Step-by-Step Demo" to correct punctuation and follow
compound adjective rules.
| ## Architecture Overview | ||
| ## Architecture Overview | ||
|
|
||
| Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows: |
There was a problem hiding this comment.
Remove trailing space.
Line 54 has a trailing space. Clean this up to comply with markdown linting rules.
🔎 Proposed fix
-Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:
+Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:📝 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.
| Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows: | |
| Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows: |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
54-54: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🤖 Prompt for AI Agents
In README.md around line 54, remove the single trailing space at the end of the
line "Exosphere is built on a flexible, node-based architecture that makes it
easy to create complex workflows:" so the line ends cleanly with the colon;
update the file to trim that trailing whitespace (or run a trim-whitespace/lint
fix) and save the file to satisfy markdown linting rules.
No description provided.