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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soe-ai
-Version: 0.1.0
+Version: 0.1.1
 Summary: Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine
 Author-email: Pedro Garcia <pedro@example.com>
 License-Expression: MIT
@@ -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(
@@ -158,8 +221,8 @@ 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 |
+| **Engineers** (infrastructure) | [Infrastructure Guide](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.1}/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(
@@ -122,8 +185,8 @@ 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 |
+| **Engineers** (infrastructure) | [Infrastructure Guide](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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soe-ai"
-version = "0.1.0"
+version = "0.1.1"
 description = "Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine"
 readme = "README.md"
 requires-python = ">=3.8"

{soe_ai-0.1.0 → soe_ai-0.1.1}/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, {})