Skip to content

Commit f3a732b

Browse files
NiveditJainNiveditJain
committed
2 parents 0d3870c + 2d43d51 commit f3a732b

17 files changed

Lines changed: 365 additions & 68 deletions

File tree

‎README.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Exosphere provides a powerful foundation for building and orchestrating AI appli
2828
- **Infinite Parallel Agents**: Run multiple AI agents simultaneously across distributed infrastructure
2929
- **Dynamic State Management**: Create and manage state at runtime with persistent storage
3030
- **Fault Tolerance**: Built-in failure handling and recovery mechanisms for production reliability
31-
- **Core Concepts**: Fanout, Unite, Signals, Retry Policy, Store
31+
- **Core Concepts**: Fanout, Unite, Signals, Retry Policy, Store, Triggers
3232

3333
### **Smooth Developer Experience**
3434
- **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
7979
- **Signals**: Inter-node communication and event handling
8080
- **Retry Policy**: Configurable failure handling and recovery
8181
- **Store**: Persistent storage for workflow state and data
82+
- **Triggers**: Automatic scheduling with cron expressions
83+
84+
## ⏰ Automatic Scheduling Example
85+
86+
Schedule your workflows to run automatically using cron expressions:
87+
88+
!!! info "Beta Feature"
89+
Available in `beta-latest` Docker tag and SDK version `0.0.3b1`
90+
91+
```python
92+
from exospherehost import StateManager, GraphNodeModel, CronTrigger
93+
94+
# Define triggers for automatic execution
95+
triggers = [
96+
CronTrigger(expression="0 9 * * 1-5"), # Every weekday at 9 AM
97+
CronTrigger(expression="0 */6 * * *") # Every 6 hours
98+
]
99+
100+
# Create graph with automatic scheduling
101+
result = await state_manager.upsert_graph(
102+
graph_name="data-pipeline",
103+
graph_nodes=graph_nodes,
104+
secrets={"api_key": "your-key"},
105+
triggers=triggers # Enable automatic execution (Beta)
106+
)
107+
```
82108

83109
### **Deployment Options**
84110

‎dashboard/package-lock.json‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/docs/exosphere/concepts.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,12 @@ graph TB
5353
- **Runtime Access**: All nodes can read and write to the shared store
5454
- **Automatic Cleanup**: Store data is automatically cleaned up when workflows complete
5555

56+
### 7. **Automatic Triggers**
57+
- **Cron Scheduling**: Schedule automatic graph execution using standard cron expressions
58+
- **Unattended Operation**: Workflows run automatically without manual intervention
59+
- **Multiple Schedules**: Each graph can have multiple triggers with different schedules
60+
- **Beta**: Available in `beta-latest` Docker tag and SDK version `0.0.3b1`
61+
5662
## How They Work Together
5763

5864
These concepts combine to create a powerful workflow system:
@@ -63,6 +69,7 @@ These concepts combine to create a powerful workflow system:
6369
4. **Signals** give nodes control over execution flow and error handling
6470
5. **Retry policies** ensure resilience against transient failures
6571
6. **Store** provides persistent state across workflow executions
72+
7. **Triggers** enable automatic, scheduled execution for unattended operations
6673

6774
## Benefits
6875

@@ -80,4 +87,5 @@ Explore each concept in detail:
8087
- **[Unite](./unite.md)** - Understand synchronization of parallel paths
8188
- **[Signals](./signals.md)** - Control workflow execution flow
8289
- **[Retry Policy](./retry-policy.md)** - Build resilient workflows
83-
- **[Store](./store.md)** - Persist data across workflow execution
90+
- **[Store](./store.md)** - Persist data across workflow execution
91+
- **[Triggers](./triggers.md)** - Schedule automatic graph execution

‎docs/docs/exosphere/create-graph.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ A graph template consists of:
1111
- **Input Mapping**: How data flows between nodes using `${{ ... }}` syntax
1212
- **Retry Policy**: `Optional` failure handling configuration
1313
- **Store Configuration**: `Optional` graph-level key-value store
14+
- **Triggers**: `Optional` cron-based automatic execution scheduling
1415

1516
## Basic Example of a Graph Template
1617

‎docs/docs/exosphere/graph-components.md‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,10 +97,47 @@ Graph-level key-value storage for shared state:
9797
- `required_keys`: Keys that must be present in the store
9898
- `default_values`: Default values for store keys
9999

100+
## 6. Triggers
101+
102+
Schedule automatic graph execution using cron expressions:
103+
104+
!!! info "Beta Feature"
105+
Available in `beta-latest` Docker tag and SDK version `0.0.3b1`
106+
107+
```json
108+
{
109+
"triggers": [
110+
{
111+
"type": "CRON",
112+
"value": {
113+
"expression": "0 9 * * 1-5"
114+
}
115+
},
116+
{
117+
"type": "CRON",
118+
"value": {
119+
"expression": "0 */6 * * *"
120+
}
121+
}
122+
]
123+
}
124+
```
125+
126+
**Fields:**
127+
- `type`: Currently only "CRON" is supported
128+
- `value.expression`: Standard cron expression (5-field format)
129+
130+
**Common Cron Expressions:**
131+
- `"0 9 * * 1-5"` - Every weekday at 9:00 AM
132+
- `"0 */6 * * *"` - Every 6 hours
133+
- `"0 0 * * 0"` - Every Sunday at midnight
134+
- `"*/15 * * * *"` - Every 15 minutes
135+
100136
## Next Steps
101137

102138
- **[Create Graph](./create-graph.md)** - Return to main guide
103-
- **[Graph Models](./python-sdk-graph.md)** - Use Python SDK for type-safe graph creation.
139+
- **[Graph Models](./python-sdk-graph.md)** - Use Python SDK for type-safe graph creation
140+
- **[Triggers](./triggers.md)** - Schedule automatic graph execution
104141

105142
## Related Concepts
106143

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Use the Exosphere Python SDK with Pydantic models for type-safe graph creation.
55
## Basic Usage
66

77
```python hl_lines="42-48"
8-
from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, StoreConfigModel, RetryStrategyEnum
8+
from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, StoreConfigModel, CronTrigger, RetryStrategyEnum
99

1010
async def create_graph():
1111
state_manager = StateManager(
@@ -46,12 +46,18 @@ async def create_graph():
4646
}
4747
)
4848

49+
triggers = [
50+
CronTrigger(expression="0 9 * * 1-5"), # Every weekday at 9 AM
51+
CronTrigger(expression="0 */6 * * *") # Every 6 hours
52+
]
53+
4954
result = await state_manager.upsert_graph(
5055
graph_name="my-workflow",
5156
graph_nodes=graph_nodes,
5257
secrets={"api_key": "your-key"},
5358
retry_policy=retry_policy,
54-
store_config=store_config
59+
store_config=store_config,
60+
triggers=triggers # Beta: SDK version 0.0.3b1
5561
)
5662
return result
5763
```

‎docs/docs/exosphere/triggers.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Triggers
2+
3+
!!! warning "Beta Feature"
4+
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.
5+
6+
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.
7+
8+
## Overview
9+
10+
Triggers provide **scheduled execution** for your workflows, enabling automation for:
11+
12+
- **Regular data processing** (daily reports, hourly syncs)
13+
- **Maintenance tasks** (cleanup jobs, backups)
14+
- **Monitoring workflows** (health checks, alerts)
15+
- **Business processes** (invoice generation, notifications)
16+
17+
```mermaid
18+
graph TB
19+
A[Cron Trigger] --> B[Scheduled Time Reached]
20+
B --> C[Graph Execution Triggered]
21+
C --> D[Workflow Runs Automatically]
22+
23+
E[Multiple Triggers] -.->|Different schedules| A
24+
25+
style A fill:#e8f5e8
26+
style E fill:#e8f5e8
27+
```
28+
29+
## How Triggers Work
30+
31+
### Trigger Lifecycle
32+
33+
1. **Definition**: Triggers are defined when creating/updating a graph template
34+
2. **Scheduling**: Exosphere schedules the next execution based on cron expression
35+
3. **Execution**: At the scheduled time, the graph is triggered automatically
36+
4. **Rescheduling**: After execution, the next occurrence is automatically scheduled
37+
38+
### Trigger Types
39+
40+
Currently, **CRON** is the only supported trigger type, using standard 5-field cron expressions:
41+
42+
```
43+
* * * * *
44+
│ │ │ │ │
45+
│ │ │ │ └── Day of Week (0-7, Sunday = 0 or 7)
46+
│ │ │ └──── Month (1-12)
47+
│ │ └────── Day of Month (1-31)
48+
│ └──────── Hour (0-23)
49+
└────────── Minute (0-59)
50+
```
51+
52+
## Implementation
53+
54+
### JSON Configuration
55+
56+
Define triggers in your graph template:
57+
58+
```json
59+
{
60+
"triggers": [
61+
{
62+
"type": "CRON",
63+
"value": {
64+
"expression": "0 9 * * 1-5"
65+
}
66+
},
67+
{
68+
"type": "CRON",
69+
"value": {
70+
"expression": "0 0 * * 0"
71+
}
72+
}
73+
],
74+
"nodes": [
75+
// ... your graph nodes
76+
]
77+
}
78+
```
79+
80+
### Python SDK Example
81+
82+
```python
83+
from exospherehost import StateManager, GraphNodeModel, CronTrigger
84+
85+
async def create_scheduled_graph():
86+
state_manager = StateManager(
87+
namespace="DataPipeline",
88+
state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
89+
key=EXOSPHERE_API_KEY
90+
)
91+
92+
# Define your graph nodes
93+
graph_nodes = [
94+
GraphNodeModel(
95+
node_name="DataExtractorNode",
96+
namespace="DataPipeline",
97+
identifier="extractor",
98+
inputs={"source": "initial"},
99+
next_nodes=["processor"]
100+
),
101+
GraphNodeModel(
102+
node_name="DataProcessorNode",
103+
namespace="DataPipeline",
104+
identifier="processor",
105+
inputs={"raw_data": "${{ extractor.outputs.data }}"},
106+
next_nodes=[]
107+
)
108+
]
109+
110+
# Define triggers for automatic execution
111+
triggers = [
112+
CronTrigger(expression="0 2 * * *"), # Daily at 2:00 AM
113+
CronTrigger(expression="0 */4 * * *") # Every 4 hours
114+
]
115+
116+
# Create the graph with triggers
117+
result = await state_manager.upsert_graph(
118+
graph_name="data-pipeline",
119+
graph_nodes=graph_nodes,
120+
secrets={"api_key": "your-api-key"},
121+
triggers=triggers
122+
)
123+
124+
print(f"Graph created with {len(triggers)} triggers")
125+
return result
126+
127+
# Run the function
128+
import asyncio
129+
asyncio.run(create_scheduled_graph())
130+
```
131+
132+
## Common Cron Expressions
133+
134+
### Basic Patterns
135+
136+
| Expression | Description | Example Use Case |
137+
|------------|-------------|------------------|
138+
| `"0 9 * * 1-5"` | Every weekday at 9:00 AM | Business reports |
139+
| `"0 */6 * * *"` | Every 6 hours | Data synchronization |
140+
| `"0 0 * * 0"` | Every Sunday at midnight | Weekly cleanup |
141+
| `"*/15 * * * *"` | Every 15 minutes | Health checks |
142+
| `"0 2 * * *"` | Daily at 2:00 AM | Nightly batch jobs |
143+
| `"0 0 1 * *"` | First day of every month | Monthly reports |
144+
145+
### Advanced Patterns
146+
147+
| Expression | Description |
148+
|------------|-------------|
149+
| `"0 9-17 * * 1-5"` | Every hour from 9 AM to 5 PM, weekdays only |
150+
| `"0 0 * * 1,3,5"` | Monday, Wednesday, Friday at midnight |
151+
| `"30 8 * * 1-5"` | Weekdays at 8:30 AM |
152+
| `"0 12 1,15 * *"` | 1st and 15th of each month at noon |
153+
| `"0 0 1 1,7 *"` | January 1st and July 1st at midnight |
154+
155+
## Best Practices
156+
157+
### Scheduling Considerations
158+
159+
1. **Avoid Peak Times**: Schedule resource-intensive workflows during off-peak hours
160+
2. **Stagger Executions**: If you have multiple graphs, stagger their execution times
161+
3. **Consider Time Zones**: Cron expressions use server time (UTC by default)
162+
4. **Resource Planning**: Ensure your infrastructure can handle scheduled workloads
163+
164+
### Error Handling
165+
166+
- **Retry Policies**: Combine triggers with retry policies for resilient automation
167+
- **Monitoring**: Set up alerts for failed scheduled executions
168+
- **Logging**: Ensure adequate logging for troubleshooting scheduled runs
169+
170+
### Example with Retry Policy
171+
172+
```python
173+
from exospherehost import RetryPolicyModel, RetryStrategyEnum
174+
175+
# Define retry policy for scheduled executions
176+
retry_policy = RetryPolicyModel(
177+
max_retries=3,
178+
strategy=RetryStrategyEnum.EXPONENTIAL,
179+
backoff_factor=2000,
180+
exponent=2
181+
)
182+
183+
# Create graph with both triggers and retry policy
184+
result = await state_manager.upsert_graph(
185+
graph_name="robust-pipeline",
186+
# Assuming `graph_nodes`, `secrets`, and `triggers` are defined as in previous examples
187+
graph_nodes=graph_nodes,
188+
secrets=secrets,
189+
triggers=triggers,
190+
retry_policy=retry_policy # Handles failures in scheduled runs
191+
)
192+
```
193+
194+
## Limitations
195+
196+
- **CRON Only**: Currently only cron-based scheduling is supported
197+
- **No Manual Override**: Scheduled executions cannot be manually cancelled once triggered
198+
- **Time Zone**: All cron expressions are evaluated in server time (UTC)
199+
- **Minimum Interval**: Avoid scheduling more frequently than every minute
200+
201+
## Next Steps
202+
203+
- **[Create Graph](./create-graph.md)** - Learn about graph creation
204+
- **[Retry Policy](./retry-policy.md)** - Add resilience to scheduled executions
205+
- **[Store](./store.md)** - Persist data across scheduled runs
206+
- **[Dashboard](./dashboard.md)** - Monitor scheduled executions
207+
208+
## Related Concepts
209+
210+
- **[Graph Components](./graph-components.md)** - Complete overview of graph features
211+
- **[Python SDK](./python-sdk-graph.md)** - Type-safe graph creation with triggers

‎docs/mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,8 @@ nav:
150150
- Unite: exosphere/unite.md
151151
- Signals: exosphere/signals.md
152152
- Retry Policy: exosphere/retry-policy.md
153-
- Store: exosphere/store.md
153+
- Store: exosphere/store.md
154+
- Triggers: exosphere/triggers.md
154155
- Local Setup:
155156
- Overview: exosphere/local-setup.md
156157
- Docker Compose: docker-compose-setup.md

0 commit comments

Comments
 (0)