soe-ai 0.1.0__py3-none-any.whl

soe/init.py

@@ -0,0 +1,165 @@
+"""
+Convenience initialization for SOE.
+
+This module provides easy setup functions for common use cases.
+Use these to quickly get started without manually wiring nodes and backends.
+"""
+
+import copy
+from typing import Callable, Dict, Any, Tuple, Optional, List, Union
+from .broker import broadcast_signals, orchestrate
+from .nodes.router.factory import create_router_node_caller
+from .nodes.llm.factory import create_llm_node_caller
+from .nodes.agent.factory import create_agent_node_caller
+from .nodes.tool.factory import create_tool_node_caller
+from .nodes.child.factory import create_child_node_caller
+from .lib.yaml_parser import parse_yaml
+from .types import CallLlm, Backends
+from .local_backends import create_in_memory_backends, create_local_backends
+
+
+def create_all_nodes(
+    backends: Backends,
+    call_llm: Optional[CallLlm] = None,
+    tools_registry: Optional[Dict[str, Callable]] = None,
+) -> Tuple[Dict[str, Callable], Callable]:
+    """
+    Create all node types with automatic wiring.
+
+    This is the recommended way to set up nodes for orchestration.
+    Returns both the nodes dictionary and the broadcast_signals_caller.
+
+    Args:
+        backends: Backend services (use create_in_memory_backends or create_local_backends)
+        call_llm: Optional LLM caller function for LLM/Agent nodes
+        tools_registry: Optional dict mapping tool name -> callable for Tool/Agent nodes
+
+    Returns:
+        Tuple of (nodes dict, broadcast_signals_caller function)
+
+    Example:
+        backends = create_in_memory_backends()
+        nodes, broadcast = create_all_nodes(backends, call_llm=my_llm, tools_registry=my_tools)
+
+        execution_id = orchestrate(
+            config=workflow_yaml,
+            initial_workflow_name="my_workflow",
+            initial_signals=["START"],
+            initial_context={"user_input": "Hello"},
+            backends=backends,
+            broadcast_signals_caller=broadcast,
+        )
+    """
+    nodes = {}
+
+    def broadcast_signals_caller(id: str, signals: List[str]):
+        broadcast_signals(id, signals, nodes, backends)
+
+    nodes["router"] = create_router_node_caller(backends, broadcast_signals_caller)
+
+    if call_llm is not None:
+        nodes["llm"] = create_llm_node_caller(backends, call_llm, broadcast_signals_caller)
+
+        tools_list = []
+        if tools_registry:
+            tools_list = [{"function": func, "max_retries": 0} for func in tools_registry.values()]
+        nodes["agent"] = create_agent_node_caller(backends, tools_list, call_llm, broadcast_signals_caller)
+
+    if tools_registry is not None:
+        nodes["tool"] = create_tool_node_caller(backends, tools_registry, broadcast_signals_caller)
+
+    def orchestrate_caller(
+        config: Union[str, Dict[str, Any]],
+        initial_workflow_name: str,
+        initial_signals: List[str],
+        initial_context: Dict[str, Any],
+        backends: Backends,
+    ) -> str:
+        """Start a child workflow execution."""
+        if isinstance(config, str):
+            parsed_config = parse_yaml(config)
+        else:
+            parsed_config = copy.deepcopy(config)
+
+        def child_broadcast(execution_id: str, signals: List[str]):
+            broadcast_signals(execution_id, signals, nodes, backends)
+
+        return orchestrate(
+            config=parsed_config,
+            initial_workflow_name=initial_workflow_name,
+            initial_signals=initial_signals,
+            initial_context=initial_context,
+            backends=backends,
+            broadcast_signals_caller=child_broadcast,
+        )
+
+    nodes["child"] = create_child_node_caller(backends, orchestrate_caller)
+
+    return nodes, broadcast_signals_caller
+
+
+def setup_orchestration(
+    call_llm: Optional[CallLlm] = None,
+    tools_registry: Optional[Dict[str, Callable]] = None,
+    use_local_storage: bool = False,
+    storage_dir: str = "./orchestration_data",
+) -> Tuple[Backends, Callable]:
+    """
+    One-line setup for SOE orchestration.
+
+    Creates backends and nodes with automatic wiring.
+    Returns the backends and broadcast_signals_caller ready to use.
+
+    Args:
+        call_llm: Optional LLM caller function for LLM/Agent nodes
+        tools_registry: Optional dict mapping tool name -> callable
+        use_local_storage: If True, use file-based storage. If False, use in-memory.
+        storage_dir: Directory for local storage (only used if use_local_storage=True)
+
+    Returns:
+        Tuple of (backends, broadcast_signals_caller)
+
+    Example:
+        # Minimal setup (router-only workflows)
+        backends, broadcast = setup_orchestration()
+
+        # Full setup with LLM and tools
+        backends, broadcast = setup_orchestration(
+            call_llm=my_llm_function,
+            tools_registry={"search": search_fn, "calculate": calc_fn},
+        )
+
+        execution_id = orchestrate(
+            config=workflow_yaml,
+            initial_workflow_name="my_workflow",
+            initial_signals=["START"],
+            initial_context={},
+            backends=backends,
+            broadcast_signals_caller=broadcast,
+        )
+    """
+    if use_local_storage:
+        backends = create_local_backends(
+            context_storage_dir=f"{storage_dir}/contexts",
+            workflow_storage_dir=f"{storage_dir}/workflows",
+            telemetry_storage_dir=f"{storage_dir}/telemetry",
+            conversation_history_storage_dir=f"{storage_dir}/conversations",
+            context_schema_storage_dir=f"{storage_dir}/schemas",
+            identity_storage_dir=f"{storage_dir}/identities",
+        )
+    else:
+        backends = create_in_memory_backends()
+
+    _, broadcast_signals_caller = create_all_nodes(
+        backends=backends,
+        call_llm=call_llm,
+        tools_registry=tools_registry,
+    )
+
+    return backends, broadcast_signals_caller
+
+
+__all__ = [
+    "create_all_nodes",
+    "setup_orchestration",
+]

soe/types.py

@@ -0,0 +1,197 @@
+"""
+Types for orchestration system
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Optional, Any, Dict, List
+
+
+class TelemetryBackend(Protocol):
+    """Protocol for telemetry backend"""
+
+    def log_event(self, execution_id: str, event_type: str, **event_data) -> None:
+        ...
+
+
+class ContextBackend(Protocol):
+    """Protocol for context backend"""
+
+    def save_context(self, id: str, context: dict) -> None:
+        ...
+
+    def get_context(self, id: str) -> dict:
+        ...
+
+
+class WorkflowBackend(Protocol):
+    """Protocol for workflow backend"""
+
+    def save_workflows_registry(self, id: str, workflows: Dict[str, Any]) -> None:
+        ...
+
+    def soe_get_workflows_registry(self, id: str) -> Any:
+        ...
+
+    def save_current_workflow_name(self, id: str, name: str) -> None:
+        ...
+
+    def get_current_workflow_name(self, id: str) -> str:
+        ...
+
+
+class OrchestrateCaller(Protocol):
+    """Protocol for orchestrate caller function"""
+
+    def __call__(self, execution_id: str, signals: List[str]) -> None:
+        ...
+
+
+class BroadcastSignalsCaller(Protocol):
+    """Protocol for broadcast signals caller function"""
+
+    def __call__(self, execution_id: str, signals: List[str]) -> None:
+        ...
+
+
+class RouterNodeCaller(Protocol):
+    """Protocol for router node caller function"""
+
+    def __call__(self, execution_id: str, node_config: Dict[str, Any]) -> None:
+        ...
+
+
+class AgentNodeCaller(Protocol):
+    """Protocol for agent node caller function"""
+
+    def __call__(self, execution_id: str, node_config: Dict[str, Any]) -> None:
+        ...
+
+
+class ToolNodeCaller(Protocol):
+    """Protocol for tool node caller function"""
+
+    def __call__(self, execution_id: str, node_config: Dict[str, Any]) -> None:
+        ...
+
+
+class ChildNodeCaller(Protocol):
+    """Protocol for child node caller function"""
+
+    def __call__(self, execution_id: str, node_config: Dict[str, Any]) -> None:
+        ...
+
+
+class OrchestrateCaller(Protocol):
+    """Protocol for starting child workflows (wrapper around orchestrate).
+
+    Supports optional inheritance parameters:
+    - inherit_config_from_id: Inherit workflows, identities, schema from existing execution
+    - inherit_context_from_id: Inherit context from existing execution (resets operational)
+    """
+
+    def __call__(
+        self,
+        config: Any,
+        initial_workflow_name: str,
+        initial_signals: List[str],
+        initial_context: Dict[str, Any],
+        backends: "Backends",
+        inherit_config_from_id: Optional[str] = None,
+        inherit_context_from_id: Optional[str] = None,
+    ) -> str:
+        ...
+
+
+class CallLlm(Protocol):
+    """Protocol for LLM caller function"""
+
+    def __call__(self, prompt: str, config: Dict[str, Any]) -> str:
+        ...
+
+
+class ConversationHistoryBackend(Protocol):
+    """Protocol for conversation history backend"""
+
+    def get_conversation_history(self, identity: str) -> List[Dict[str, Any]]:
+        ...
+
+    def append_to_conversation_history(self, identity: str, entry: Dict[str, Any]) -> None:
+        ...
+
+    def save_conversation_history(self, identity: str, history: List[Dict[str, Any]]) -> None:
+        ...
+
+    def delete_conversation_history(self, identity: str) -> None:
+        ...
+
+
+class ContextSchemaBackend(Protocol):
+    """Protocol for context schema backend - stores workflow context field schemas.
+
+    Context schemas define the structure and types of context fields used in workflows.
+    These are keyed by execution_id (main_execution_id) so children can access parent's schemas.
+    """
+
+    def save_context_schema(self, execution_id: str, schema: Dict[str, Any]) -> None:
+        """Save context schema for an execution."""
+        ...
+
+    def get_context_schema(self, execution_id: str) -> Optional[Dict[str, Any]]:
+        """Get context schema for an execution."""
+        ...
+
+    def delete_context_schema(self, execution_id: str) -> bool:
+        """Delete context schema for an execution."""
+        ...
+
+
+class IdentityBackend(Protocol):
+    """Protocol for identity backend - stores workflow identity definitions.
+
+    Identities define the participating personas/roles in a workflow.
+    These are used as the initial system prompt for conversation history.
+    Keyed by execution_id (main_execution_id) so children can access parent's identities.
+
+    Identity format is simple: identity_name -> system_prompt (string)
+    Example:
+        assistant: "You are a helpful assistant."
+        coding_expert: "You are an expert programmer."
+    """
+
+    def save_identities(self, execution_id: str, identities: Dict[str, str]) -> None:
+        """Save identity definitions for an execution."""
+        ...
+
+    def get_identities(self, execution_id: str) -> Optional[Dict[str, str]]:
+        """Get all identity definitions for an execution."""
+        ...
+
+    def get_identity(self, execution_id: str, identity_name: str) -> Optional[str]:
+        """Get a specific identity's system prompt."""
+        ...
+
+    def delete_identities(self, execution_id: str) -> bool:
+        """Delete identity definitions for an execution."""
+        ...
+
+
+class Backends(Protocol):
+    """Protocol for orchestration backends"""
+
+    context: ContextBackend
+    workflow: WorkflowBackend
+    telemetry: Optional[TelemetryBackend]
+    conversation_history: Optional[ConversationHistoryBackend]
+    context_schema: Optional[ContextSchemaBackend]
+    identity: Optional[IdentityBackend]
+
+
+class SoeError(Exception):
+    """Base class for all SOE exceptions"""
+    pass
+
+
+class WorkflowValidationError(SoeError):
+    """Raised when workflow or node configuration is invalid (static/startup)"""
+    pass

soe/validation.py

@@ -0,0 +1,8 @@
+"""
+DEPRECATED: This module has been moved to soe/validation/ folder.
+This file is kept temporarily but will be removed.
+
+Import from soe.validation instead:
+    from soe.validation import validate_config, validate_operational
+"""
+# This file should be deleted - Python will import from soe/validation/ folder instead

soe_ai-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: soe-ai
+Version: 0.1.0
+Summary: Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine
+Author-email: Pedro Garcia <pedro@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pgarcia14180/soe
+Project-URL: Documentation, https://github.com/pgarcia14180/soe/tree/master/docs
+Project-URL: Repository, https://github.com/pgarcia14180/soe
+Project-URL: Issues, https://github.com/pgarcia14180/soe/issues
+Keywords: orchestration,agent,workflow,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: jinja2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: integration
+Requires-Dist: openai>=1.0.0; extra == "integration"
+Requires-Dist: requests>=2.28.0; extra == "integration"
+Dynamic: license-file
+
+# SOE — Signal-driven Orchestration Engine
+
+**A protocol for orchestrating AI workflows through signals.**
+
+---
+
+## What SOE Is
+
+SOE is an orchestration engine where nodes communicate through **signals** rather than direct function calls. You define workflows in YAML, and the engine handles execution.
+
+| Approach | How It Works | Trade-off |
+|----------|--------------|-----------|
+| Chain-based | `Step A → B → C → D` | Simple but rigid |
+| SOE Signal-based | `[SIGNAL] → all listeners respond` | Flexible, requires understanding signals |
+
+**The C++ analogy**: Like C++ gives you control over memory and execution (compared to higher-level languages), SOE gives you control over orchestration primitives. You decide how state is stored, how LLMs are called, and how signals are broadcast. This requires more setup but means no vendor lock-in and full observability.
+
+---
+
+## What SOE Does
+
+SOE orchestrates workflows through **signals**. Nodes don't call each other—they emit signals that other nodes listen for.
+
+```yaml
+example_workflow:
+  ValidateInput:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: VALID
+        condition: "{{ context.data is defined }}"
+      - signal_name: INVALID
+
+  ProcessData:
+    node_type: llm
+    event_triggers: [VALID]
+    prompt: "Process this: {{ context.data }}"
+    output_field: result
+    event_emissions:
+      - signal_name: DONE
+```
+
+**That's the entire workflow definition.** No SDK, no decorators, no base classes.
+
+---
+
+## Why SOE
+
+### 1. Infrastructure-Agnostic
+SOE defines **protocols**, not implementations. Swap PostgreSQL for DynamoDB. Replace OpenAI with a local LLM. Deploy to Lambda, Kubernetes, or a single Python script. Your workflow YAML stays the same.
+
+### 2. Context-Driven with Jinja
+All workflow state flows through **context**—a shared dictionary accessible via Jinja2 templates. This means:
+- Conditions like `{{ context.user_validated }}` are readable and debuggable
+- LLM prompts can interpolate any context field
+- No hidden state—everything is inspectable
+
+### 3. Deterministic + Agentic
+Mix hard-coded logic with LLM-driven behavior in the same workflow. Router nodes are pure conditionals. Agent nodes can call tools. Use what you need.
+
+### 4. Portable
+Workflows are YAML. Run them locally, in CI, in production. Extract them, version them, share them.
+
+---
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv add soe-ai
+
+# With pip
+pip install soe-ai
+
+# From source
+git clone https://github.com/pgarcia14180/soe.git
+cd soe && uv sync
+```
+
+---
+
+## Quick Start
+
+```python
+from soe import orchestrate, create_all_nodes
+from soe.local_backends import create_local_backends
+
+# Your workflow (can also be loaded from file or database)
+workflow = """
+example_workflow:
+  Start:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: DONE
+"""
+
+# Create backends (storage for context, workflows, etc.)
+backends = create_local_backends("./data")
+
+# Create all node handlers
+nodes, broadcast = create_all_nodes(backends)
+
+# Run the workflow
+execution_id = orchestrate(
+    config=workflow,
+    initial_workflow_name="example_workflow",
+    initial_signals=["START"],
+    initial_context={"user": "alice"},
+    backends=backends,
+    broadcast_signals_caller=broadcast,
+)
+# When orchestrate() returns, the workflow is complete
+```
+
+**For product managers and less technical users**: The Quick Start above is all you need to run a workflow. The `config` parameter accepts YAML defining your workflow structure. The `initial_context` is where you pass input data (like user IDs, requests, etc.).
+
+---
+
+## Documentation
+
+| Audience | Start Here |
+|----------|------------|
+| **Builders** (workflow authors) | [Documentation](docs/index.md) — Step-by-step chapters |
+| **Engineers** (infrastructure) | [ARCHITECTURE.md](ai_docs/ARCHITECTURE.md) — Design philosophy |
+| **Researchers** (advanced patterns) | [Advanced Patterns](docs/advanced_patterns/index.md) — Swarm, hybrid, self-evolving |
+
+---
+
+## Node Types
+
+| Node | Purpose |
+|------|---------|
+| `router` | Conditional signal emission (no LLM) |
+| `llm` | Single LLM call with output |
+| `agent` | Multi-turn LLM with tool access |
+| `tool` | Execute Python functions |
+| `child` | Spawn sub-workflows |
+
+---
+
+## Backend Protocols
+
+Implement these to plug SOE into your infrastructure:
+
+| Protocol | Purpose |
+|----------|---------|
+| `ContextBackend` | Workflow state storage |
+| `WorkflowBackend` | Workflow definitions |
+| `ContextSchemaBackend` | Output validation (optional) |
+| `IdentityBackend` | LLM system prompts (optional) |
+| `ConversationHistoryBackend` | Agent memory (optional) |
+| `TelemetryBackend` | Observability (optional) |
+
+**Recommendation**: Use the same database for context, workflows, identities, and context_schema—just separate tables. The backend methods handle table creation.
+
+See [Infrastructure Guide](docs/guide_10_infrastructure.md) for PostgreSQL, DynamoDB, and Lambda examples.
+
+---
+
+## License
+
+MIT

soe_ai-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+soe/__init__.py,sha256=4g0b-2C4wlr3Aq9eSmISxEMeWRCI4fim_I1v4nfW_Cs,1131
+soe/broker.py,sha256=R5s5GvgmwgBQK9FyI-UAMVb7nf14tMdXpeEZ-t8d3rE,5987
+soe/docs_index.py,sha256=mDnQ-LVyPgF25_8yCuD04j2PxiQCR_6Si_NMkfJyk-0,3055071
+soe/init.py,sha256=Fzw7MDoEOlZLfCwH-kL0evUjc3WHmLEVOaeR2-dgwWs,5876
+soe/types.py,sha256=xSmkRcKehYW2pesnzB0qCZHjpm_IoDTBbQcb1SwV-8o,5712
+soe/validation.py,sha256=SeBfGaaGjUi73ejnHNqVLTv7LYtU_gFHX8OJ3iytJMo,318
+soe_ai-0.1.0.dist-info/licenses/LICENSE,sha256=SvEn330zvSOu83Vi4lDCX2QHgr6bmSSXOV1YClLGk1Y,1069
+soe_ai-0.1.0.dist-info/METADATA,sha256=bWjq5DC6W9NenF18lKAgVkK-xZE_9cYGYJOOCQCoHSM,6558
+soe_ai-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+soe_ai-0.1.0.dist-info/top_level.txt,sha256=TUufXyVAQnzN6iT6zRb4dRHdfBSiWXuAL8EoyvugZuY,4
+soe_ai-0.1.0.dist-info/RECORD,,

soe_ai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

soe_ai-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soe_ai-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+soe