Adding Store and cleaning Trigger APIs and Create State APIs

docs/docs/exosphere/create-graph.md

@@ -176,7 +176,7 @@ async def create_graph_template():
     }
 
     try:
-        # Create or update the graph template
+        # Create or update the graph template (with optional store, beta)
         result = await state_manager.upsert_graph(
             graph_name="my-workflow",
             graph_nodes=graph_nodes,
@@ -186,6 +186,9 @@ async def create_graph_template():
                 "strategy": "EXPONENTIAL",
                 "backoff_factor": 2000,
                 "exponent": 2
+            },
+            store_config={  # beta
+                "ttl": 7200  # seconds to keep key/values
             }
         )
         print("Graph template created successfully!")

docs/docs/exosphere/trigger-graph.md

@@ -16,20 +16,14 @@ The recommended way to trigger graphs is using the Exosphere Python SDK, which p
             state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
             key=EXOSPHERE_API_KEY
         )
-
-        # Create trigger state
-        trigger_state = TriggerState(
-            identifier="data_loader",  # Must match a node identifier in your graph
-            inputs={
-                "source": "/path/to/data.csv",
-                "format": "csv",
-                "batch_size": "1000"
-            }
-        )
-
+
         try:
-            # Trigger the graph
-            result = await state_manager.trigger("my-graph", state=trigger_state)
+            # Trigger the graph with optional store (beta)
+            result = await state_manager.trigger(
+                "my-graph",
+                inputs={"user_id": "123"},
+                store={"cursor": "0"}  # persisted across nodes (beta)
+            )
             print(f"Graph triggered successfully!")
             print(f"Run ID: {result['run_id']}")
             return result

python-sdk/README.md

@@ -77,6 +77,7 @@ export EXOSPHERE_API_KEY="your-api-key"
 - **Async Support**: Native async/await support for high-performance operations
 - **Error Handling**: Built-in retry mechanisms and error recovery
 - **Scalability**: Designed for high-volume batch processing and workflows
+- **Graph Store (beta)**: Strings-only key-value store with per-run scope for sharing data across nodes (not durable across separate runs or clusters)
 
 ## Architecture
 
@@ -241,95 +242,29 @@ trigger_state = TriggerState(
     }
 )
 
-# Trigger a single state
-result = await state_manager.trigger("my-graph", state=trigger_state)
-
-# Or trigger multiple states
-trigger_states = [
-    TriggerState(identifier="trigger1", inputs={"key1": "value1"}),
-    TriggerState(identifier="trigger2", inputs={"key2": "value2"})
-]
-
-result = await state_manager.trigger("my-graph", states=trigger_states)
-```
-
-**Parameters:**
-- `graph_name` (str): The name of the graph to trigger
-- `state` (TriggerState, optional): A single trigger state
-- `states` (list[TriggerState], optional): A list of trigger states
-
-**Returns:**
-- `dict`: The JSON response from the state manager API
-
-**Raises:**
-- `ValueError`: If neither `state` nor `states` is provided, if both are provided, or if `states` is an empty list
-- `Exception`: If the API request fails with a non-200 status code
-
-### TriggerState Class
-
-The `TriggerState` class represents a trigger state for graph execution. It contains an identifier and a set of input parameters that will be passed to the graph when it is triggered.
-
-#### Creating Trigger States
-
-```python
-from exospherehost import TriggerState
-
-# Basic trigger state
-trigger_state = TriggerState(
-    identifier="data-processing",
-    inputs={
-        "file_path": "/path/to/data.csv",
-        "batch_size": "1000",
-        "priority": "high"
-    }
-)
-
-# Trigger state with complex data (serialized as JSON)
-import json
-
-complex_data = {
-    "filters": ["active", "verified"],
-    "date_range": {"start": "2024-01-01", "end": "2024-01-31"},
-    "options": {"include_metadata": True, "format": "json"}
-}
-
-trigger_state = TriggerState(
-    identifier="complex-processing",
+# Trigger the graph (beta store support)
+result = await state_manager.trigger(
+    "my-graph",
     inputs={
-        "config": json.dumps(complex_data),
-        "user_id": "12345"
+        "user_id": "12345",
+        "session_token": "abc123def456"
+    },
+    store={
+        "cursor": "0"  # persisted across nodes (beta)
     }
 )
 ```
 
-**Attributes:**
-- `identifier` (str): A unique identifier for this trigger state. Used to distinguish between different trigger states and may be used by the graph to determine how to process the trigger
-- `inputs` (dict[str, str]): A dictionary of input parameters that will be passed to the graph. The keys are parameter names and values are parameter values, both as strings
-
-## Integration with ExosphereHost Platform
-
-The Python SDK integrates seamlessly with the ExosphereHost platform, providing:
-
-- **Performance**: Optimized execution with intelligent resource allocation and parallel processing
-- **Reliability**: Built-in fault tolerance, automatic recovery, and failover capabilities
-- **Scalability**: Automatic scaling based on workload demands
-- **Monitoring**: Integrated logging and monitoring capabilities
-
-## Documentation
-
-For more detailed information, visit our [documentation](https://docs.exosphere.host).
-
-## Contributing
+**Parameters:**
 
-We welcome contributions! Please see our [contributing guidelines](https://github.com/exospherehost/exospherehost/blob/main/CONTRIBUTING.md) for details.
+- `graph_name` (str): Name of the graph to execute
+- `inputs` (dict[str, str] | None): Key/value inputs for the first node (strings only)
+- `store` (dict[str, str] | None): Graph-level key/value store (beta) persisted across nodes
 
-## Support
+**Returns:**
 
-For support and questions:
-- **Email**: [nivedit@exosphere.host](mailto:nivedit@exosphere.host)
-- **Documentation**: [https://docs.exosphere.host](https://docs.exosphere.host)
-- **GitHub Issues**: [https://github.com/exospherehost/exospherehost/issues](https://github.com/exospherehost/exospherehost/issues)
+- `dict`: JSON payload from the state manager
 
-## License
+**Raises:**
 
-This Python SDK is licensed under the MIT License. The main ExosphereHost project is licensed under the Elastic License 2.0.
+- `Exception`: If the HTTP request fails

python-sdk/exospherehost/_version.py

@@ -1 +1 @@
-version = "0.0.2b2"
+version = "0.0.2b3"

python-sdk/exospherehost/statemanager.py

@@ -67,60 +67,49 @@ def _get_upsert_graph_endpoint(self, graph_name: str):
     def _get_get_graph_endpoint(self, graph_name: str):
         return f"{self._state_manager_uri}/{self._state_manager_version}/namespace/{self._namespace}/graph/{graph_name}"
 
-    async def trigger(self, graph_name: str, state: TriggerState | None = None, states: list[TriggerState] | None = None):
+    async def trigger(self, graph_name: str, inputs: dict[str, str] | None = None, store: dict[str, str] | None = None):
         """
-        Trigger a graph execution with one or more trigger states.
+        Trigger execution of a graph.
 
-        This method sends trigger states to the specified graph endpoint to initiate
-        graph execution. It accepts either a single trigger state or a list of trigger
-        states, but not both simultaneously.
+        Beta: This method now supports an optional **store** parameter that lets you
+        pass a key-value map that is persisted for the lifetime of the graph run. All
+        keys **and** values must be strings in the current beta release – the schema
+        may change in future versions.
 
         Args:
-            graph_name (str): The name of the graph to trigger execution for.
-            state (TriggerState | None, optional): A single trigger state to send.
-                Must be provided if `states` is None.
-            states (list[TriggerState] | None, optional): A list of trigger states to send.
-                Must be provided if `state` is None. Cannot be an empty list.
+            graph_name (str): Name of the graph you want to run.
+            inputs (dict[str, str] | None): Optional inputs for the first node in the
+                graph. Strings only.
+            store (dict[str, str] | None): Optional key-value store that will be merged
+                into the graph-level store before execution (beta).
 
         Returns:
-            dict: The JSON response from the state manager API containing the
-                result of the trigger operation.
+            dict: JSON payload returned by the state-manager API.
 
         Raises:
-            ValueError: If neither `state` nor `states` is provided, if both are provided,
-                or if `states` is an empty list.
-            Exception: If the API request fails with a non-200 status code. The exception
-                message includes the HTTP status code and response text for debugging.
+            Exception: If the request fails.
 
         Example:
             ```python
-            # Trigger with a single state
-            state = TriggerState(identifier="my-trigger", inputs={"key": "value"})
-            result = await state_manager.trigger("my-graph", state=state)
-
-            # Trigger with multiple states
-            states = [
-                TriggerState(identifier="trigger1", inputs={"key1": "value1"}),
-                TriggerState(identifier="trigger2", inputs={"key2": "value2"})
-            ]
-            result = await state_manager.trigger("my-graph", states=states)
+            # Trigger with inputs only
+            await state_manager.trigger("my-graph", inputs={"user_id": "123"})
+
+            # Trigger with inputs **and** a beta store
+            await state_manager.trigger(
+                "my-graph",
+                inputs={"user_id": "123"},
+                store={"cursor": "0"}  # beta
+            )
             ```
         """
-        if state is None and states is None:
-            raise ValueError("Either state or states must be provided")
-        if state is not None and states is not None:
-            raise ValueError("Only one of state or states must be provided")
-        if states is not None and len(states) == 0:
-            raise ValueError("States must be a non-empty list")
+        if inputs is None: 
+            inputs = {}
+        if store is None:
+            store = {}
 
-        states_list = []
-        if state is not None:
-            states_list.append(state)
-        if states is not None:
-            states_list.extend(states)
-
         body = {
-            "states": [state.model_dump() for state in states_list]
+            "inputs": inputs,
+            "store": store
         }
         headers = {
             "x-api-key": self._key
@@ -167,35 +156,32 @@ async def get_graph(self, graph_name: str):
                     raise Exception(f"Failed to get graph: {response.status} {await response.text()}")
                 return await response.json()
 
-    async def upsert_graph(self, graph_name: str, graph_nodes: list[dict[str, Any]], secrets: dict[str, str], validation_timeout: int = 60, polling_interval: int = 1):
+    async def upsert_graph(self, graph_name: str, graph_nodes: list[dict[str, Any]], secrets: dict[str, str], retry_policy: dict[str, Any] | None = None, store_config: dict[str, Any] | None = None, validation_timeout: int = 60, polling_interval: int = 1):
         """
-        Create or update a graph in the state manager with validation.
+        Create or update a graph definition.
+
+        Beta: `store_config` is a new field that allows you to configure a
+        namespaced key-value store that lives for the duration of a graph run. The
+        feature is in beta and the shape of `store_config` may change.
 
-        This method sends a graph definition to the state manager API for creation
-        or update. After submission, it polls the API to wait for graph validation
-        to complete, ensuring the graph is properly configured before returning.
+        After submitting the graph, this helper polls the state-manager until the
+        graph has been validated (or the timeout is hit).
 
         Args:
-            graph_name (str): The name of the graph to create or update.
-            graph_nodes (list[dict[str, Any]]): A list of node definitions that make up
-                the graph. Each node should contain the necessary configuration for
-                the graph execution engine.
-            secrets (dict[str, str]): A dictionary of secret values that will be
-                available to the graph during execution. Keys are secret names and
-                values are the secret values.
-            validation_timeout (int, optional): Maximum time in seconds to wait for
-                graph validation to complete. Defaults to 60.
-            polling_interval (int, optional): Time in seconds between validation
-                status checks. Defaults to 1.
-
+            graph_name (str): Graph identifier.
+            graph_nodes (list[dict[str, Any]]): Graph node list.
+            secrets (dict[str, str]): Secrets available to all nodes.
+            retry_policy (dict[str, Any] | None): Optional per-node retry policy.
+            store_config (dict[str, Any] | None): Beta configuration for the
+                graph-level store (schema is subject to change).
+            validation_timeout (int): Seconds to wait for validation (default 60).
+            polling_interval (int): Polling interval in seconds (default 1).
+
         Returns:
-            dict: The JSON response from the state manager API containing the
-                validated graph information.
-
+            dict: Validated graph object returned by the API.
+
         Raises:
-            Exception: If the API request fails with a non-201 status code, if graph
-                validation times out, or if validation fails. The exception message
-                includes relevant error details for debugging.
+            Exception: If validation fails or times out.
         """
         endpoint = self._get_upsert_graph_endpoint(graph_name)
         headers = {
@@ -205,6 +191,12 @@ async def upsert_graph(self, graph_name: str, graph_nodes: list[dict[str, Any]],
             "secrets": secrets,
             "nodes": graph_nodes
         }
+
+        if retry_policy is not None:
+            body["retry_policy"] = retry_policy
+        if store_config is not None:
+            body["store_config"] = store_config
+
         async with aiohttp.ClientSession() as session:
             async with session.put(endpoint, json=body, headers=headers) as response: # type: ignore
                 if response.status not in [200, 201]: