soe-ai 0.1.0__tar.gz → 0.1.2__tar.gz

{soe_ai-0.1.0 → soe_ai-0.1.2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: soe-ai
-Version: 0.1.0
+Version: 0.1.2
 Summary: Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine
-Author-email: Pedro Garcia <pedro@example.com>
+Author-email: Pedro Garcia <pgarcia14180@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/pgarcia14180/soe
 Project-URL: Documentation, https://github.com/pgarcia14180/soe/tree/master/docs
@@ -91,12 +91,44 @@ All workflow state flows through **context**—a shared dictionary accessible vi
 - 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.
+### 3. Purely Deterministic or Hybrid Agentic
+SOE is a complete orchestration solution. You can use it as a purely deterministic engine for standard business logic, or mix in LLM-driven "Agentic" behavior.
+- **Deterministic**: Use `router` and `tool` nodes for 100% predictable workflows.
+- **Agentic**: Add `llm` and `agent` nodes for creative, reasoning-based tasks.
+You get the safety of code with the flexibility of AI in a single, unified system.
 
 ### 4. Portable
 Workflows are YAML. Run them locally, in CI, in production. Extract them, version them, share them.
 
+### 5. Self-Evolving
+Workflows can modify themselves at runtime. Built-in tools like `inject_workflow`, `inject_node_configuration`, and `add_signal` allow agents to:
+- Create new workflows dynamically
+- Add or modify nodes in existing workflows
+- Update signal routing on the fly
+
+This enables **meta-programming**: an AI system that can extend its own capabilities without human intervention.
+
+---
+
+## What SOE Unlocks
+
+SOE is a **Protocol for Intelligence** that unlocks new forms of intelligent behavior:
+
+### Self-Evolving Intelligence
+AI systems that can rewrite and improve themselves at runtime - the ultimate evolution of software.
+
+### Swarm Intelligence
+Efficient collective decision-making among multiple agents through signal-based consensus.
+
+### Hybrid Intelligence
+Seamless combination of deterministic logic and AI creativity with programmatic safety rails.
+
+### Fractal Intelligence
+Hierarchical agent organizations that scale complexity while remaining manageable.
+
+### Infrastructure Intelligence
+AI orchestration that works everywhere - from edge devices to cloud platforms.
+
 ---
 
 ## Installation
@@ -117,6 +149,37 @@ cd soe && uv sync
 
 ## Quick Start
 
+### 1. Provide Your LLM
+
+SOE is LLM-agnostic. You must provide a `call_llm` function that matches this signature:
+
+```python
+def call_llm(
+    prompt: str,
+    config: dict,
+) -> str:
+    """
+    Called by SOE when a node needs LLM processing.
+
+    Args:
+        prompt: The rendered prompt string (includes instructions, context, and schemas)
+        config: The full node configuration from YAML (useful for model parameters)
+
+    Returns:
+        The raw text response from the LLM.
+    """
+    # Example with OpenAI:
+    from openai import OpenAI
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model=config.get("model", "gpt-4o"),
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.choices[0].message.content
+```
+
+### 2. Run a Workflow
+
 ```python
 from soe import orchestrate, create_all_nodes
 from soe.local_backends import create_local_backends
@@ -134,8 +197,8 @@ example_workflow:
 # Create backends (storage for context, workflows, etc.)
 backends = create_local_backends("./data")
 
-# Create all node handlers
-nodes, broadcast = create_all_nodes(backends)
+# Create all node handlers (pass your call_llm function)
+nodes, broadcast = create_all_nodes(backends, call_llm=call_llm)
 
 # Run the workflow
 execution_id = orchestrate(
@@ -157,9 +220,9 @@ execution_id = orchestrate(
 
 | 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 |
+| **Builders** (workflow authors) | [Documentation](soe/docs/index.md) — Step-by-step chapters |
+| **Engineers** (infrastructure) | [Infrastructure Guide](soe/docs/guide_10_infrastructure.md) — Backend protocols |
+| **Researchers** (advanced patterns) | [Advanced Patterns](docs/advanced_patterns/) — Swarm, hybrid, self-evolving |
 
 ---
 

{soe_ai-0.1.0 → soe_ai-0.1.2}/README.md

@@ -55,12 +55,44 @@ All workflow state flows through **context**—a shared dictionary accessible vi
 - 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.
+### 3. Purely Deterministic or Hybrid Agentic
+SOE is a complete orchestration solution. You can use it as a purely deterministic engine for standard business logic, or mix in LLM-driven "Agentic" behavior.
+- **Deterministic**: Use `router` and `tool` nodes for 100% predictable workflows.
+- **Agentic**: Add `llm` and `agent` nodes for creative, reasoning-based tasks.
+You get the safety of code with the flexibility of AI in a single, unified system.
 
 ### 4. Portable
 Workflows are YAML. Run them locally, in CI, in production. Extract them, version them, share them.
 
+### 5. Self-Evolving
+Workflows can modify themselves at runtime. Built-in tools like `inject_workflow`, `inject_node_configuration`, and `add_signal` allow agents to:
+- Create new workflows dynamically
+- Add or modify nodes in existing workflows
+- Update signal routing on the fly
+
+This enables **meta-programming**: an AI system that can extend its own capabilities without human intervention.
+
+---
+
+## What SOE Unlocks
+
+SOE is a **Protocol for Intelligence** that unlocks new forms of intelligent behavior:
+
+### Self-Evolving Intelligence
+AI systems that can rewrite and improve themselves at runtime - the ultimate evolution of software.
+
+### Swarm Intelligence
+Efficient collective decision-making among multiple agents through signal-based consensus.
+
+### Hybrid Intelligence
+Seamless combination of deterministic logic and AI creativity with programmatic safety rails.
+
+### Fractal Intelligence
+Hierarchical agent organizations that scale complexity while remaining manageable.
+
+### Infrastructure Intelligence
+AI orchestration that works everywhere - from edge devices to cloud platforms.
+
 ---
 
 ## Installation
@@ -81,6 +113,37 @@ cd soe && uv sync
 
 ## Quick Start
 
+### 1. Provide Your LLM
+
+SOE is LLM-agnostic. You must provide a `call_llm` function that matches this signature:
+
+```python
+def call_llm(
+    prompt: str,
+    config: dict,
+) -> str:
+    """
+    Called by SOE when a node needs LLM processing.
+
+    Args:
+        prompt: The rendered prompt string (includes instructions, context, and schemas)
+        config: The full node configuration from YAML (useful for model parameters)
+
+    Returns:
+        The raw text response from the LLM.
+    """
+    # Example with OpenAI:
+    from openai import OpenAI
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model=config.get("model", "gpt-4o"),
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.choices[0].message.content
+```
+
+### 2. Run a Workflow
+
 ```python
 from soe import orchestrate, create_all_nodes
 from soe.local_backends import create_local_backends
@@ -98,8 +161,8 @@ example_workflow:
 # Create backends (storage for context, workflows, etc.)
 backends = create_local_backends("./data")
 
-# Create all node handlers
-nodes, broadcast = create_all_nodes(backends)
+# Create all node handlers (pass your call_llm function)
+nodes, broadcast = create_all_nodes(backends, call_llm=call_llm)
 
 # Run the workflow
 execution_id = orchestrate(
@@ -121,9 +184,9 @@ execution_id = orchestrate(
 
 | 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 |
+| **Builders** (workflow authors) | [Documentation](soe/docs/index.md) — Step-by-step chapters |
+| **Engineers** (infrastructure) | [Infrastructure Guide](soe/docs/guide_10_infrastructure.md) — Backend protocols |
+| **Researchers** (advanced patterns) | [Advanced Patterns](docs/advanced_patterns/) — Swarm, hybrid, self-evolving |
 
 ---
 

{soe_ai-0.1.0 → soe_ai-0.1.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soe-ai"
-version = "0.1.0"
+version = "0.1.2"
 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"}
+    {name = "Pedro Garcia", email = "pgarcia14180@gmail.com"}
 ]
 keywords = ["orchestration", "agent", "workflow", "automation"]
 classifiers = [
@@ -49,11 +49,12 @@ 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.packages.find]
+include = ["soe*"]
+exclude = ["tests*"]
 
 [tool.setuptools.package-data]
-soe = ["py.typed"]
+soe = ["py.typed", "docs/**/*"]
 
 [tool.black]
 line-length = 88

{soe_ai-0.1.0 → soe_ai-0.1.2}/soe/broker.py

@@ -1,7 +1,6 @@
 from uuid import uuid4
-from typing import Dict, List, Any, Union, Callable, Optional
-from .types import Backends, BroadcastSignalsCaller
-from .local_backends import EventTypes
+from typing import Dict, List, Any, Union, Optional
+from .types import Backends, BroadcastSignalsCaller, NodeCaller, EventTypes, WorkflowValidationError
 from .lib.register_event import register_event
 from .lib.yaml_parser import parse_yaml
 from .lib.operational import add_operational_state
@@ -131,7 +130,7 @@ def orchestrate(
 def broadcast_signals(
     id: str,
     signals: List[str],
-    nodes: Dict[str, Callable[[str, Dict[str, Any]], None]],
+    nodes: Dict[str, NodeCaller],
     backends: Backends,
 ) -> None:
     """Broadcast signals to matching nodes in the current workflow"""
@@ -139,7 +138,7 @@ def broadcast_signals(
 
     register_event(backends, id, EventTypes.SIGNALS_BROADCAST, {"signals": signals})
 
-    workflows_registry = backends.workflow.soe_get_workflows_registry(id)
+    workflows_registry = backends.workflow.get_workflows_registry(id)
 
     workflow_name = backends.workflow.get_current_workflow_name(id)
     workflow = workflows_registry.get(workflow_name, {})

soe_ai-0.1.2/soe/builtin_tools/__init__.py

@@ -0,0 +1,39 @@
+"""
+Built-in tools registry
+"""
+
+from .soe_inject_workflow import create_soe_inject_workflow_tool
+from .soe_inject_node import create_soe_inject_node_tool
+from .soe_get_workflows import create_soe_get_workflows_tool
+from .soe_get_available_tools import create_soe_get_available_tools_tool
+from .soe_explore_docs import create_soe_explore_docs_tool
+from .soe_remove_workflow import create_soe_remove_workflow_tool
+from .soe_remove_node import create_soe_remove_node_tool
+from .soe_get_context import create_soe_get_context_tool
+from .soe_update_context import create_soe_update_context_tool
+from .soe_copy_context import create_soe_copy_context_tool
+from .soe_list_contexts import create_soe_list_contexts_tool
+from .soe_add_signal import create_soe_add_signal_tool
+from .soe_call_tool import create_soe_call_tool_tool
+
+# Registry of all available built-in tools
+BUILTIN_TOOLS = {
+    "soe_inject_workflow": create_soe_inject_workflow_tool,
+    "soe_inject_node": create_soe_inject_node_tool,
+    "soe_get_workflows": create_soe_get_workflows_tool,
+    "soe_get_available_tools": create_soe_get_available_tools_tool,
+    "soe_explore_docs": create_soe_explore_docs_tool,
+    "soe_remove_workflow": create_soe_remove_workflow_tool,
+    "soe_remove_node": create_soe_remove_node_tool,
+    "soe_get_context": create_soe_get_context_tool,
+    "soe_update_context": create_soe_update_context_tool,
+    "soe_copy_context": create_soe_copy_context_tool,
+    "soe_list_contexts": create_soe_list_contexts_tool,
+    "soe_add_signal": create_soe_add_signal_tool,
+    "soe_call_tool": create_soe_call_tool_tool,
+}
+
+
+def get_builtin_tool_factory(tool_name: str):
+    """Get factory function for built-in tool"""
+    return BUILTIN_TOOLS.get(tool_name)

soe_ai-0.1.2/soe/builtin_tools/soe_add_signal.py

@@ -0,0 +1,82 @@
+"""Built-in tool to add a signal to a node's event emissions."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_add_signal_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create add_signal tool.
+    """
+
+    def add_signal(
+        workflow_name: str, node_name: str, signal_name: str, condition: str
+    ) -> Dict[str, Any]:
+        """
+        Add a signal to a node's event_emissions list.
+
+        Args:
+            workflow_name: Name of the workflow
+            node_name: Name of the node
+            signal_name: Name of the signal to add
+            condition: Jinja condition for the signal
+
+        Returns:
+            Success confirmation
+        """
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+
+        if workflow_name not in workflows_registry:
+            raise ValueError(f"Workflow '{workflow_name}' not found")
+
+        workflow = workflows_registry[workflow_name]
+        if node_name not in workflow:
+            raise ValueError(f"Node '{node_name}' not found in workflow '{workflow_name}'")
+
+        node_config = workflow[node_name]
+
+        if "event_emissions" not in node_config:
+            node_config["event_emissions"] = []
+
+        # Check if signal already exists
+        for emission in node_config["event_emissions"]:
+            if emission.get("signal_name") == signal_name:
+                # Update existing
+                emission["condition"] = condition
+                backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+                return {
+                    "status": "updated",
+                    "message": f"Updated signal '{signal_name}' in node '{node_name}'"
+                }
+
+        # Add new signal
+        node_config["event_emissions"].append({
+            "signal_name": signal_name,
+            "condition": condition
+        })
+
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "add_signal",
+                "workflow_name": workflow_name,
+                "node_name": node_name,
+                "signal": signal_name
+            },
+        )
+
+        return {
+            "status": "added",
+            "message": f"Added signal '{signal_name}' to node '{node_name}'"
+        }
+
+    return add_signal

soe_ai-0.1.2/soe/builtin_tools/soe_call_tool.py

@@ -0,0 +1,111 @@
+"""
+Built-in dynamic tool invocation.
+
+Allows LLMs to call any registered tool by name at runtime.
+This enables meta-level tool orchestration.
+"""
+
+import json
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_call_tool_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict,
+) -> Callable:
+    """
+    Factory function to create call_tool with access to tools registry.
+
+    Args:
+        execution_id: Current execution ID
+        backends: Backend services
+        tools_registry: Registry of available tools {name: {"function": callable, ...}}
+
+    Returns:
+        Configured call_tool function
+    """
+
+    def call_tool(tool_name: str, arguments: str = "{}") -> Dict[str, Any]:
+        """
+        Dynamically invoke a registered tool by name.
+
+        This is a meta-tool that allows calling any other tool at runtime.
+        Useful for dynamic workflows where the tool to call is determined
+        by context or user input.
+
+        Args:
+            tool_name: Name of the tool to invoke (must be registered)
+            arguments: JSON string of arguments to pass to the tool
+
+        Returns:
+            The result from the invoked tool, or an error dict
+
+        Example:
+            call_tool("get_secret", '{"key": "password"}')
+            call_tool("write_file", '{"path": "test.txt", "content": "hello"}')
+        """
+        # Parse arguments
+        try:
+            args = json.loads(arguments) if arguments else {}
+        except json.JSONDecodeError as e:
+            return {
+                "error": f"Invalid JSON arguments: {e}",
+                "tool_name": tool_name,
+            }
+
+        # Check if tool exists
+        if tool_name not in tools_registry:
+            available = list(tools_registry.keys())
+            return {
+                "error": f"Tool '{tool_name}' not found",
+                "available_tools": available[:20],  # Limit to avoid huge responses
+            }
+
+        # Get tool function
+        tool_entry = tools_registry[tool_name]
+        if isinstance(tool_entry, dict):
+            tool_func = tool_entry.get("function")
+        elif callable(tool_entry):
+            tool_func = tool_entry
+        else:
+            return {"error": f"Invalid tool registry entry for '{tool_name}'"}
+
+        if not callable(tool_func):
+            return {"error": f"Tool '{tool_name}' is not callable"}
+
+        # Log the dynamic invocation
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.TOOL_CALL,
+            {
+                "meta_tool": "call_tool",
+                "invoked_tool": tool_name,
+                "arguments": args,
+            },
+        )
+
+        # Invoke the tool
+        try:
+            result = tool_func(**args)
+            return {
+                "success": True,
+                "tool_name": tool_name,
+                "result": result,
+            }
+        except TypeError as e:
+            # Argument mismatch
+            return {
+                "error": f"Argument error for '{tool_name}': {e}",
+                "tool_name": tool_name,
+            }
+        except Exception as e:
+            return {
+                "error": f"Tool '{tool_name}' failed: {e}",
+                "tool_name": tool_name,
+            }
+
+    return call_tool

soe_ai-0.1.2/soe/builtin_tools/soe_copy_context.py

@@ -0,0 +1,80 @@
+"""
+Built-in tool: copy_context
+Allows agents to copy context fields between executions or within the same execution.
+"""
+
+from typing import Dict, Any, Optional
+
+
+def create_soe_copy_context_tool(backends, execution_id: str, tools_registry=None):
+    """
+    Factory that creates a copy_context tool bound to the current execution.
+
+    Args:
+        backends: Backend instances (needs context backend)
+        execution_id: Current execution ID
+        tools_registry: Tool registry (unused, for interface compatibility)
+
+    Returns:
+        Configured tool function
+    """
+
+    def copy_context(
+        source_execution_id: Optional[str] = None,
+        fields: Optional[Dict[str, str]] = None,
+        all_fields: bool = False,
+        target_execution_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Copy context fields between executions or within the same execution.
+
+        Args:
+            source_execution_id: Execution ID to copy from (default: current)
+            fields: Dict of {source_field: target_field} to copy
+            all_fields: If True, copy all non-operational fields
+            target_execution_id: Execution ID to copy to (default: current)
+
+        Returns:
+            Dict with copy results
+        """
+        source_id = source_execution_id or execution_id
+        target_id = target_execution_id or execution_id
+
+        # Get source context
+        source_context = backends.context.get_context(source_id)
+
+        # Filter out operational fields
+        source_filtered = {k: v for k, v in source_context.items() if not k.startswith("__")}
+
+        # Get target context
+        target_context = backends.context.get_context(target_id)
+
+        copied_fields = {}
+
+        if all_fields:
+            # Copy all non-operational fields
+            for field, value in source_filtered.items():
+                target_context[field] = value
+                copied_fields[field] = field
+        elif fields:
+            # Copy specific field mappings
+            for source_field, target_field in fields.items():
+                if source_field in source_filtered:
+                    target_context[target_field] = source_filtered[source_field]
+                    copied_fields[source_field] = target_field
+                else:
+                    return {"error": f"Source field '{source_field}' not found in execution {source_id}"}
+        else:
+            return {"error": "Must specify either 'fields' mapping or 'all_fields=True'"}
+
+        # Save target context
+        backends.context.save_context(target_id, target_context)
+
+        return {
+            "status": "copied",
+            "source_execution": source_id,
+            "target_execution": target_id,
+            "fields_copied": copied_fields,
+        }
+
+    return copy_context