soe-ai 0.1.0__tar.gz

soe_ai-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,163 @@
+# 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/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soe-ai"
+version = "0.1.0"
+description = "Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    {name = "Pedro Garcia", email = "pedro@example.com"}
+]
+keywords = ["orchestration", "agent", "workflow", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "pyyaml>=6.0",
+    "pydantic>=2.0.0",
+    "jinja2>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+]
+integration = [
+    "openai>=1.0.0",
+    "requests>=2.28.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pgarcia14180/soe"
+Documentation = "https://github.com/pgarcia14180/soe/tree/master/docs"
+Repository = "https://github.com/pgarcia14180/soe"
+Issues = "https://github.com/pgarcia14180/soe/issues"
+
+[tool.setuptools]
+packages = ["soe"]
+
+[tool.setuptools.package-data]
+soe = ["py.typed"]
+
+[tool.black]
+line-length = 88
+target-version = ['py38', 'py39', 'py310', 'py311']
+
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.uv.workspace]
+members = [
+    "usage_demo",
+    ".",
+]

soe_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soe_ai-0.1.0/soe/__init__.py

@@ -0,0 +1,50 @@
+"""
+Orchestration Engine - MVP
+Agent orchestration with event-driven workflow engine
+"""
+
+from .broker import orchestrate, broadcast_signals
+from .nodes import (
+    AgentRequest,
+    AgentResponse,
+    ToolNodeConfigurationError,
+    ToolParameterError,
+)
+from .types import (
+    # Backend protocols - for building custom backends
+    Backends,
+    ContextBackend,
+    WorkflowBackend,
+    TelemetryBackend,
+    ConversationHistoryBackend,
+    ContextSchemaBackend,
+    IdentityBackend,
+    # LLM protocol - for integrating custom LLM providers
+    CallLlm,
+)
+from .init import create_all_nodes, setup_orchestration
+
+__all__ = [
+    # Core functions
+    "orchestrate",
+    "broadcast_signals",
+    # Easy setup
+    "create_all_nodes",
+    "setup_orchestration",
+    # Agent types
+    "AgentRequest",
+    "AgentResponse",
+    # Tool errors
+    "ToolNodeConfigurationError",
+    "ToolParameterError",
+    # Backend protocols
+    "Backends",
+    "ContextBackend",
+    "WorkflowBackend",
+    "TelemetryBackend",
+    "ConversationHistoryBackend",
+    "ContextSchemaBackend",
+    "IdentityBackend",
+    # LLM protocol
+    "CallLlm",
+]

soe_ai-0.1.0/soe/broker.py

@@ -0,0 +1,169 @@
+from uuid import uuid4
+from typing import Dict, List, Any, Union, Callable, Optional
+from .types import Backends, BroadcastSignalsCaller
+from .local_backends import EventTypes
+from .lib.register_event import register_event
+from .lib.yaml_parser import parse_yaml
+from .lib.operational import add_operational_state
+from .lib.context_fields import set_field
+from .lib.parent_sync import get_signals_for_parent
+from .lib.inheritance import (
+    inherit_config,
+    inherit_context,
+    extract_and_save_config_sections,
+)
+from .validation import validate_config, validate_operational, validate_orchestrate_params
+from .types import WorkflowValidationError
+
+
+def orchestrate(
+    config: Optional[Union[str, Dict[str, Any]]],
+    initial_workflow_name: str,
+    initial_signals: List[str],
+    initial_context: Dict[str, Any],
+    backends: Backends,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+    inherit_config_from_id: Optional[str] = None,
+    inherit_context_from_id: Optional[str] = None,
+) -> str:
+    """
+    Initialize orchestration with config and trigger initial signals.
+
+    Config can be either:
+
+    1. Workflows only (legacy format):
+       config = {
+           "workflow_name": {
+               "node_name": {...}
+           }
+       }
+
+    2. Combined config with workflows, context_schema, and identities:
+       config = {
+           "workflows": {...},
+           "context_schema": {...},  # optional
+           "identities": {...}       # optional
+       }
+
+    3. Inherited config (config=None, inherit_config_from_id provided):
+       Inherits workflows, identities, and context_schema from an existing
+       execution. Useful for workflow chaining and continuation.
+
+    Inheritance options:
+
+    - inherit_config_from_id: Copy workflows, identities, and context_schema
+      from the specified execution ID. When provided, config is optional.
+
+    - inherit_context_from_id: Copy context from the specified execution ID,
+      but ALWAYS reset __operational__ state. Useful for continuing work
+      with existing context data.
+
+    When context_schema and identities are present (either from config or
+    inherited), they are automatically saved to their respective backends,
+    keyed by the main execution ID so children can access them.
+    """
+    validate_orchestrate_params(initial_workflow_name, initial_signals)
+
+    if config is None and inherit_config_from_id is None:
+        raise WorkflowValidationError(
+            "Either 'config' or 'inherit_config_from_id' must be provided"
+        )
+
+    id = str(uuid4())
+
+    if inherit_config_from_id:
+        register_event(
+            backends, id, EventTypes.CONFIG_INHERITANCE_START,
+            {"source_execution_id": inherit_config_from_id}
+        )
+        parsed_registry = inherit_config(inherit_config_from_id, id, backends)
+        if config:
+            validate_config(config)
+            parsed_config = parse_yaml(config)
+            parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
+    else:
+        validate_config(config)
+        parsed_config = parse_yaml(config)
+        parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
+
+    register_event(
+        backends, id, EventTypes.ORCHESTRATION_START,
+        {"workflow_name": initial_workflow_name}
+    )
+
+    backends.workflow.save_workflows_registry(id, parsed_registry)
+
+    if initial_workflow_name not in parsed_registry:
+        available = list(parsed_registry.keys())
+        raise WorkflowValidationError(
+            f"Workflow '{initial_workflow_name}' not found in config. "
+            f"Available workflows: {available}"
+        )
+
+    backends.workflow.save_current_workflow_name(id, initial_workflow_name)
+
+    if inherit_context_from_id:
+        register_event(
+            backends, id, EventTypes.CONTEXT_INHERITANCE_START,
+        )
+        context = inherit_context(inherit_context_from_id, backends)
+        if initial_context:
+            register_event(
+                backends, id, EventTypes.CONTEXT_MERGE,
+                {"fields": list(initial_context.keys())}
+            )
+            for field, value in initial_context.items():
+                set_field(context, field, value)
+    else:
+        context = {
+            k: [v] if not k.startswith("__") else v
+            for k, v in initial_context.items()
+        }
+
+    context = add_operational_state(id, context)
+    backends.context.save_context(id, context)
+
+    broadcast_signals_caller(id, initial_signals)
+
+    return id
+
+
+def broadcast_signals(
+    id: str,
+    signals: List[str],
+    nodes: Dict[str, Callable[[str, Dict[str, Any]], None]],
+    backends: Backends,
+) -> None:
+    """Broadcast signals to matching nodes in the current workflow"""
+    context = validate_operational(id, backends)
+
+    register_event(backends, id, EventTypes.SIGNALS_BROADCAST, {"signals": signals})
+
+    workflows_registry = backends.workflow.soe_get_workflows_registry(id)
+
+    workflow_name = backends.workflow.get_current_workflow_name(id)
+    workflow = workflows_registry.get(workflow_name, {})
+
+    for node_name, node_config in workflow.items():
+        triggers = node_config.get("event_triggers", [])
+        if set(triggers) & set(signals):
+            node_type = node_config["node_type"]
+            node_executor = nodes[node_type]
+
+            register_event(
+                backends, id, EventTypes.NODE_EXECUTION,
+                {"node_name": node_name, "node_type": node_type}
+            )
+
+            node_config["name"] = node_name
+            node_executor(id, node_config)
+
+    context = backends.context.get_context(id)
+    parent_id, signals_to_sync = get_signals_for_parent(signals, context)
+
+    if parent_id and signals_to_sync:
+        register_event(
+            backends, id, EventTypes.SIGNALS_TO_PARENT,
+            {"signals": signals_to_sync, "parent_id": parent_id}
+        )
+        broadcast_signals(parent_id, signals_to_sync, nodes, backends)