Final changes for trigger beta 0.0.3b1

README.md

@@ -28,7 +28,7 @@ Exosphere provides a powerful foundation for building and orchestrating AI appli
 - **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
+- **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
@@ -79,6 +79,32 @@ Exosphere is built on a flexible, node-based architecture that makes it easy to
 - **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`
+
+```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**
 

docs/docs/exosphere/concepts.md

@@ -53,6 +53,12 @@ graph TB
 - **Runtime Access**: All nodes can read and write to the shared store
 - **Automatic Cleanup**: Store data is automatically cleaned up when workflows complete
 
+### 7. **Automatic Triggers**
+- **Cron Scheduling**: Schedule automatic graph execution using standard cron expressions
+- **Unattended Operation**: Workflows run automatically without manual intervention
+- **Multiple Schedules**: Each graph can have multiple triggers with different schedules
+- **Beta**: Available in `beta-latest` Docker tag and SDK version `0.0.3b1`
+
 ## How They Work Together
 
 These concepts combine to create a powerful workflow system:
@@ -63,6 +69,7 @@ These concepts combine to create a powerful workflow system:
 4. **Signals** give nodes control over execution flow and error handling
 5. **Retry policies** ensure resilience against transient failures
 6. **Store** provides persistent state across workflow executions
+7. **Triggers** enable automatic, scheduled execution for unattended operations
 
 ## Benefits
 
@@ -80,4 +87,5 @@ Explore each concept in detail:
 - **[Unite](./unite.md)** - Understand synchronization of parallel paths
 - **[Signals](./signals.md)** - Control workflow execution flow
 - **[Retry Policy](./retry-policy.md)** - Build resilient workflows
-- **[Store](./store.md)** - Persist data across workflow execution 
+- **[Store](./store.md)** - Persist data across workflow execution
+- **[Triggers](./triggers.md)** - Schedule automatic graph execution 

docs/docs/exosphere/create-graph.md

@@ -11,6 +11,7 @@ A graph template consists of:
 - **Input Mapping**: How data flows between nodes using `${{ ... }}` syntax
 - **Retry Policy**: `Optional` failure handling configuration 
 - **Store Configuration**: `Optional` graph-level key-value store
+- **Triggers**: `Optional` cron-based automatic execution scheduling
 
 ## Basic Example of a Graph Template
 

docs/docs/exosphere/graph-components.md

@@ -97,10 +97,47 @@ Graph-level key-value storage for shared state:
 - `required_keys`: Keys that must be present in the store
 - `default_values`: Default values for store keys
 
+## 6. Triggers
+
+Schedule automatic graph execution using cron expressions:
+
+!!! info "Beta Feature"
+ Available in `beta-latest` Docker tag and SDK version `0.0.3b1`
+
+```json
+{
+ "triggers": [
+ {
+ "type": "CRON",
+ "value": {
+ "expression": "0 9 * * 1-5"
+ }
+ },
+ {
+ "type": "CRON",
+ "value": {
+ "expression": "0 */6 * * *"
+ }
+ }
+ ]
+}
+```
+
+**Fields:**
+- `type`: Currently only "CRON" is supported
+- `value.expression`: Standard cron expression (5-field format)
+
+**Common Cron Expressions:**
+- `"0 9 * * 1-5"` - Every weekday at 9:00 AM
+- `"0 */6 * * *"` - Every 6 hours
+- `"0 0 * * 0"` - Every Sunday at midnight
+- `"*/15 * * * *"` - Every 15 minutes
+
 ## Next Steps
 
 - **[Create Graph](./create-graph.md)** - Return to main guide
-- **[Graph Models](./python-sdk-graph.md)** - Use Python SDK for type-safe graph creation.
+- **[Graph Models](./python-sdk-graph.md)** - Use Python SDK for type-safe graph creation
+- **[Triggers](./triggers.md)** - Schedule automatic graph execution
 
 ## Related Concepts
 

docs/docs/exosphere/python-sdk-graph.md

@@ -5,7 +5,7 @@ Use the Exosphere Python SDK with Pydantic models for type-safe graph creation.
 ## Basic Usage
 
 ```python hl_lines="42-48"
-from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, StoreConfigModel, RetryStrategyEnum
+from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, StoreConfigModel, CronTrigger, RetryStrategyEnum
 
 async def create_graph():
  state_manager = StateManager(
@@ -46,12 +46,18 @@ async def create_graph():
  }
  )
 
+ triggers = [
+ CronTrigger(expression="0 9 * * 1-5"), # Every weekday at 9 AM
+ CronTrigger(expression="0 */6 * * *") # Every 6 hours
+ ]
+
  result = await state_manager.upsert_graph(
  graph_name="my-workflow",
  graph_nodes=graph_nodes,
  secrets={"api_key": "your-key"},
  retry_policy=retry_policy,
- store_config=store_config
+ store_config=store_config,
+ triggers=triggers # Beta: SDK version 0.0.3b1
  )
  return result
 ```

docs/docs/exosphere/triggers.md

@@ -0,0 +1,211 @@
+# Triggers
+
+!!! warning "Beta Feature"
+ Triggers functionality is currently in beta and available under the `beta-latest` Docker tag and SDK version `0.0.3b1`. The API may change in future versions.
+
+Triggers allow you to schedule automatic execution of your graphs using cron expressions. When a trigger is defined, Exosphere will automatically execute your graph at the specified times without requiring manual intervention.
+
+## Overview
+
+Triggers provide **scheduled execution** for your workflows, enabling automation for:
+
+- **Regular data processing** (daily reports, hourly syncs)
+- **Maintenance tasks** (cleanup jobs, backups)
+- **Monitoring workflows** (health checks, alerts)
+- **Business processes** (invoice generation, notifications)
+
+```mermaid
+graph TB
+ A[Cron Trigger] --> B[Scheduled Time Reached]
+ B --> C[Graph Execution Triggered]
+ C --> D[Workflow Runs Automatically]
+
+ E[Multiple Triggers] -.->|Different schedules| A
+
+ style A fill:#e8f5e8
+ style E fill:#e8f5e8
+```
+
+## How Triggers Work
+
+### Trigger Lifecycle
+
+1. **Definition**: Triggers are defined when creating/updating a graph template
+2. **Scheduling**: Exosphere schedules the next execution based on cron expression
+3. **Execution**: At the scheduled time, the graph is triggered automatically
+4. **Rescheduling**: After execution, the next occurrence is automatically scheduled
+
+### Trigger Types
+
+Currently, **CRON** is the only supported trigger type, using standard 5-field cron expressions:
+
+```
+* * * * *
+│ │ │ │ │
+│ │ │ │ └── Day of Week (0-7, Sunday = 0 or 7)
+│ │ │ └──── Month (1-12)
+│ │ └────── Day of Month (1-31)
+│ └──────── Hour (0-23)
+└────────── Minute (0-59)
+```
+
+## Implementation
+
+### JSON Configuration
+
+Define triggers in your graph template:
+
+```json
+{
+ "triggers": [
+ {
+ "type": "CRON",
+ "value": {
+ "expression": "0 9 * * 1-5"
+ }
+ },
+ {
+ "type": "CRON",
+ "value": {
+ "expression": "0 0 * * 0"
+ }
+ }
+ ],
+ "nodes": [
+ // ... your graph nodes
+ ]
+}
+```
+
+### Python SDK Example
+
+```python
+from exospherehost import StateManager, GraphNodeModel, CronTrigger
+
+async def create_scheduled_graph():
+ state_manager = StateManager(
+ namespace="DataPipeline",
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY
+ )
+
+ # Define your graph nodes
+ graph_nodes = [
+ GraphNodeModel(
+ node_name="DataExtractorNode",
+ namespace="DataPipeline",
+ identifier="extractor",
+ inputs={"source": "initial"},
+ next_nodes=["processor"]
+ ),
+ GraphNodeModel(
+ node_name="DataProcessorNode",
+ namespace="DataPipeline", 
+ identifier="processor",
+ inputs={"raw_data": "${{ extractor.outputs.data }}"},
+ next_nodes=[]
+ )
+ ]
+
+ # Define triggers for automatic execution
+ triggers = [
+ CronTrigger(expression="0 2 * * *"), # Daily at 2:00 AM
+ CronTrigger(expression="0 */4 * * *") # Every 4 hours
+ ]
+
+ # Create the graph with triggers
+ result = await state_manager.upsert_graph(
+ graph_name="data-pipeline",
+ graph_nodes=graph_nodes,
+ secrets={"api_key": "your-api-key"},
+ triggers=triggers
+ )
+
+ print(f"Graph created with {len(triggers)} triggers")
+ return result
+
+# Run the function
+import asyncio
+asyncio.run(create_scheduled_graph())
+```
+
+## Common Cron Expressions
+
+### Basic Patterns
+
+| Expression | Description | Example Use Case |
+|------------|-------------|------------------|
+| `"0 9 * * 1-5"` | Every weekday at 9:00 AM | Business reports |
+| `"0 */6 * * *"` | Every 6 hours | Data synchronization |
+| `"0 0 * * 0"` | Every Sunday at midnight | Weekly cleanup |
+| `"*/15 * * * *"` | Every 15 minutes | Health checks |
+| `"0 2 * * *"` | Daily at 2:00 AM | Nightly batch jobs |
+| `"0 0 1 * *"` | First day of every month | Monthly reports |
+
+### Advanced Patterns
+
+| Expression | Description |
+|------------|-------------|
+| `"0 9-17 * * 1-5"` | Every hour from 9 AM to 5 PM, weekdays only |
+| `"0 0 * * 1,3,5"` | Monday, Wednesday, Friday at midnight |
+| `"30 8 * * 1-5"` | Weekdays at 8:30 AM |
+| `"0 12 1,15 * *"` | 1st and 15th of each month at noon |
+| `"0 0 1 1,7 *"` | January 1st and July 1st at midnight |
+
+## Best Practices
+
+### Scheduling Considerations
+
+1. **Avoid Peak Times**: Schedule resource-intensive workflows during off-peak hours
+2. **Stagger Executions**: If you have multiple graphs, stagger their execution times
+3. **Consider Time Zones**: Cron expressions use server time (UTC by default)
+4. **Resource Planning**: Ensure your infrastructure can handle scheduled workloads
+
+### Error Handling
+
+- **Retry Policies**: Combine triggers with retry policies for resilient automation
+- **Monitoring**: Set up alerts for failed scheduled executions
+- **Logging**: Ensure adequate logging for troubleshooting scheduled runs
+
+### Example with Retry Policy
+
+```python
+from exospherehost import RetryPolicyModel, RetryStrategyEnum
+
+# Define retry policy for scheduled executions
+retry_policy = RetryPolicyModel(
+ max_retries=3,
+ strategy=RetryStrategyEnum.EXPONENTIAL,
+ backoff_factor=2000,
+ exponent=2
+)
+
+# Create graph with both triggers and retry policy
+result = await state_manager.upsert_graph(
+ graph_name="robust-pipeline",
+ # Assuming `graph_nodes`, `secrets`, and `triggers` are defined as in previous examples
+ graph_nodes=graph_nodes,
+ secrets=secrets,
+ triggers=triggers,
+ retry_policy=retry_policy # Handles failures in scheduled runs
+)
+```
+
+## Limitations
+
+- **CRON Only**: Currently only cron-based scheduling is supported
+- **No Manual Override**: Scheduled executions cannot be manually cancelled once triggered
+- **Time Zone**: All cron expressions are evaluated in server time (UTC)
+- **Minimum Interval**: Avoid scheduling more frequently than every minute
+
+## Next Steps
+
+- **[Create Graph](./create-graph.md)** - Learn about graph creation
+- **[Retry Policy](./retry-policy.md)** - Add resilience to scheduled executions
+- **[Store](./store.md)** - Persist data across scheduled runs
+- **[Dashboard](./dashboard.md)** - Monitor scheduled executions
+
+## Related Concepts
+
+- **[Graph Components](./graph-components.md)** - Complete overview of graph features
+- **[Python SDK](./python-sdk-graph.md)** - Type-safe graph creation with triggers

docs/mkdocs.yml

@@ -150,7 +150,8 @@ nav:
  - Unite: exosphere/unite.md
  - Signals: exosphere/signals.md
  - Retry Policy: exosphere/retry-policy.md
- - Store: exosphere/store.md 
+ - Store: exosphere/store.md
+ - Triggers: exosphere/triggers.md 
  - Local Setup:
  - Overview: exosphere/local-setup.md
  - Docker Compose: docker-compose-setup.md