soe-ai 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

soe/docs/primitives/node_reference.md

@@ -0,0 +1,259 @@
+
+# Appendix B: Node Configuration Reference
+
+Complete reference for all node configuration parameters across all node types.
+
+## Node Types Overview
+
+| Node Type | Purpose | LLM Required |
+|-----------|---------|--------------|
+| `router` | Evaluate conditions and emit signals | No |
+| `llm` | Single LLM call with structured output | Yes |
+| `agent` | Multi-turn LLM with tool calling | Yes |
+| `tool` | Execute Python function | No |
+| `child` | Start sub-orchestration | No |
+
+## Configuration Parameters
+
+### Legend
+
+- ✓ = Supported
+- ✗ = Not supported
+- **R** = Required
+- **O** = Optional
+
+### Core Parameters
+
+| Parameter | Type | Router | LLM | Agent | Tool | Child | Description |
+|-----------|------|--------|-----|-------|------|-------|-------------|
+| `node_type` | `str` | **R** | **R** | **R** | **R** | **R** | Node type identifier |
+| `event_triggers` | `List[str]` | **R** | **R** | **R** | **R** | **R** | Signals that activate this node |
+| `event_emissions` | `List[dict]` | **R** | **O** | **O** | **O** | **O** | Signals to emit (with optional conditions) |
+
+### Prompt & Output Parameters
+
+| Parameter | Type | Router | LLM | Agent | Tool | Child | Description |
+|-----------|------|--------|-----|-------|------|-------|-------------|
+| `prompt` | `str` | ✗ | **R** | **R** | ✗ | ✗ | Jinja template for LLM prompt |
+| `output_field` | `str` | ✗ | **O** | **O** | **O** | ✗ | Context field to store result |
+| `identity` | `str` | ✗ | **O** | **O** | ✗ | ✗ | Key for conversation history persistence |
+
+### Tool Parameters
+
+| Parameter | Type | Router | LLM | Agent | Tool | Child | Description |
+|-----------|------|--------|-----|-------|------|-------|-------------|
+| `tool_name` | `str` | ✗ | ✗ | ✗ | **R** | ✗ | Tool to execute from registry |
+| `tools` | `List[str]` | ✗ | ✗ | **O** | ✗ | ✗ | Tool names available to agent |
+| `context_parameter_field` | `str` | ✗ | ✗ | ✗ | **O** | ✗ | Context field containing tool kwargs |
+
+### Child Workflow Parameters
+
+| Parameter | Type | Router | LLM | Agent | Tool | Child | Description |
+|-----------|------|--------|-----|-------|------|-------|-------------|
+| `child_workflow_name` | `str` | ✗ | ✗ | ✗ | ✗ | **R** | Workflow to start as child |
+| `child_initial_signals` | `List[str]` | ✗ | ✗ | ✗ | ✗ | **R** | Signals to start child with |
+| `signals_to_parent` | `List[str]` | ✗ | ✗ | ✗ | ✗ | **O** | Child signals that propagate to parent |
+| `context_updates_to_parent` | `List[str]` | ✗ | ✗ | ✗ | ✗ | **O** | Context keys that sync to parent |
+| `input_fields` | `List[str]` | ✗ | ✗ | ✗ | ✗ | **O** | Context fields to pass to child |
+| `fan_out_field` | `str` | ✗ | ✗ | ✗ | ✗ | **O** | Spawn one child per item in field's history |
+| `child_input_field` | `str` | ✗ | ✗ | ✗ | ✗ | **O** | Field in child context for each fan-out item |
+| `spawn_interval` | `float` | ✗ | ✗ | ✗ | ✗ | **O** | Seconds to sleep between fan-out spawns |
+
+### Retry & Failure Parameters
+
+| Parameter | Type | Router | LLM | Agent | Tool | Child | Description |
+|-----------|------|--------|-----|-------|------|-------|-------------|
+| `retries` | `int` | ✗ | **O** | **O** | ✗ | ✗ | Max LLM validation retries (default: 3) |
+| `llm_failure_signal` | `str` | ✗ | **O** | **O** | ✗ | ✗ | Signal when LLM retries exhausted |
+
+## Tool Registry Configuration
+
+Tools are registered with optional configuration:
+
+```python
+# Simple format
+tools_registry = {
+    "send_email": send_email_function,
+}
+
+# Extended format
+tools_registry = {
+    "send_email": {
+        "function": send_email_function,
+        "max_retries": 3,
+        "failure_signal": "EMAIL_FAILED",
+    },
+}
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `function` | `Callable` | Yes | - | The Python function to execute |
+| `max_retries` | `int` | No | 1 | Execution retries on failure |
+| `failure_signal` | `str` | No | None | Signal when all retries exhausted |
+| `process_accumulated` | `bool` | No | False | Pass full history list instead of last value |
+
+## Event Emissions Format
+
+The `event_emissions` parameter accepts a list of signal definitions:
+
+
+```yaml
+event_emissions:
+  - signal_name: SUCCESS
+  - signal_name: NEEDS_REVIEW
+    condition: "{{ result.confidence < 0.8 }}"  # Jinja: evaluated programmatically
+  - signal_name: POSITIVE
+    condition: "User sentiment is positive"  # Plain text: for LLM signal selection
+```
+
+
+| Field | Type | Required | Description |
+|-------|------|----------|-----------|
+| `signal_name` | `str` | Yes | Signal to emit |
+| `condition` | `str` | No | Plain text = LLM selects signal; Jinja (`{{ }}`) = evaluated programmatically |
+
+## Parameter Details
+
+### `event_triggers`
+
+Signals that activate the node. Uses OR logic by default.
+
+```yaml
+event_triggers: [START, RETRY, MANUAL_TRIGGER]
+```
+
+### `event_emissions`
+
+Signals to emit after node execution. Behavior varies by node type:
+
+| Node Type | Condition Context | Default Behavior |
+|-----------|-------------------|------------------|
+| Router | `context` | Emits first matching condition |
+| LLM | N/A (uses `description` for LLM selection) | Emits all if no descriptions |
+| Agent | N/A (uses `description` for LLM selection) | Emits all if no descriptions |
+| Tool | `result` and `context` | Emits all on success |
+| Child | `context` | Emits all after child starts |
+
+### `prompt`
+
+Jinja template with access to `context`:
+
+
+```yaml
+prompt: "Analyze the following: {{ context.user_input }}"
+```
+
+
+### `identity`
+
+Enables conversation history persistence. Same identity = shared history.
+
+
+```yaml
+identity: "user_session_123"
+# Or dynamic:
+identity: "{{ context.session_id }}"
+```
+
+
+### `retries`
+
+Controls LLM validation retry attempts when response doesn't match expected schema.
+
+```yaml
+retries: 5  # Default is 3
+```
+
+### `llm_failure_signal`
+
+Emit signal instead of raising exception when LLM retries are exhausted:
+
+```yaml
+llm_failure_signal: LLM_FAILED
+```
+
+## Quick Reference by Node Type
+
+### Router Node
+
+
+```yaml
+MyRouter:
+  node_type: router
+  event_triggers: [START]           # Required
+  event_emissions:                   # Required
+    - signal_name: VALID
+      condition: "{{ context.input }}"
+    - signal_name: INVALID
+```
+
+
+### LLM Node
+
+
+```yaml
+MyLLM:
+  node_type: llm
+  event_triggers: [START]           # Required
+  prompt: "Process: {{ context.data }}"  # Required
+  output_field: result              # Optional
+  identity: session_123             # Optional
+  retries: 3                        # Optional (default: 3)
+  llm_failure_signal: LLM_FAILED    # Optional
+  event_emissions:                   # Optional
+    - signal_name: DONE
+```
+
+
+### Agent Node
+
+
+```yaml
+MyAgent:
+  node_type: agent
+  event_triggers: [START]           # Required
+  prompt: "Help with: {{ context.task }}"  # Required
+  tools: [search, calculate]        # Optional
+  output_field: result              # Optional
+  identity: agent_session           # Optional
+  retries: 3                        # Optional (default: 3)
+  llm_failure_signal: AGENT_FAILED  # Optional
+  event_emissions:                   # Optional
+    - signal_name: DONE
+```
+
+
+### Tool Node
+
+
+```yaml
+MyTool:
+  node_type: tool
+  event_triggers: [START]           # Required
+  tool_name: send_email             # Required
+  context_parameter_field: email_data  # Optional
+  output_field: email_result        # Optional
+  event_emissions:                   # Optional
+    - signal_name: SENT
+    - signal_name: NEEDS_RETRY
+      condition: "{{ result.status == 'pending' }}"
+    - signal_name: HIGH_PRIORITY
+      condition: "{{ result.sent and context.email_data.priority == 'high' }}"
+```
+
+
+### Child Node
+
+```yaml
+MyChild:
+  node_type: child
+  event_triggers: [START]           # Required
+  child_workflow_name: sub_workflow # Required
+  child_initial_signals: [BEGIN]    # Required
+  input_fields: [user_data]         # Optional
+  signals_to_parent: [CHILD_DONE]   # Optional
+  context_updates_to_parent: [result]  # Optional
+  event_emissions:                   # Optional
+    - signal_name: CHILD_STARTED
+```

soe/docs/primitives/primitives.md

@@ -0,0 +1,331 @@
+# SOE Concepts: The 7 Primitives
+
+SOE is built on **7 core primitives**. Understanding these gives you complete mastery of the system.
+
+| Primitive | Purpose |
+|-----------|---------|
+| **Signals** | Communication between nodes |
+| **Context** | Shared state dictionary |
+| **Workflows** | YAML definitions of nodes |
+| **Backends** | Pluggable storage |
+| **Nodes** | Execution units |
+| **Identities** | System prompts for LLMs |
+| **Context Schema** | Type validation for outputs |
+
+---
+
+## 1. Signals
+
+**What:** Named events that flow through the system.
+
+**Purpose:** Communication between nodes. Signals are the *only* way nodes interact.
+
+
+```yaml
+event_emissions:
+  - signal_name: USER_VALIDATED
+    condition: "{{ context.user_id is defined }}"
+```
+
+
+**Key Properties:**
+- Signals are strings (e.g., `START`, `COMPLETE`, `ERROR`)
+- Multiple signals can be emitted at once
+- Signals trigger nodes via `event_triggers`
+- Signals are stateless—they carry no payload (use Context for data)
+
+**Examples:**
+- `START` — Initial trigger for a workflow
+- `TOOL_SUCCESS` — A tool completed successfully
+- `AGENT_NEEDS_INPUT` — Agent requires user interaction
+
+---
+
+## 2. Context
+
+**What:** A shared dictionary of data for the current execution.
+
+**Purpose:** State management. All nodes read from and write to Context.
+
+```python
+context = backends.context.get_context(execution_id)
+# {"user_id": "123", "validated": True, "result": "Hello!"}
+```
+
+**Key Properties:**
+- One Context per execution ID
+- Persisted via `ContextBackend`
+- LLM/Agent/Tool nodes can update Context via `output_field`
+- Jinja2 templates access Context: `{{ context.user_id }}`
+
+**Examples:**
+```yaml
+# LLM/Agent nodes store results via output_field
+output_field: result
+```
+
+---
+
+## 3. Workflows
+
+**What:** YAML definitions that describe node configurations and their relationships.
+
+**Purpose:** The blueprint for orchestration. Defines *what* happens, not *how*.
+
+
+```yaml
+my_workflow:
+  ValidateInput:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: VALID
+        condition: "{{ context.data is defined }}"
+
+  ProcessData:
+    node_type: tool
+    event_triggers: [VALID]
+    tool_name: process
+    input_fields: [data]
+    output_field: result
+```
+
+
+**Key Properties:**
+- Multiple workflows can exist in one registry
+- Workflows are parsed at runtime (Jinja2 + YAML)
+- Workflows are portable—same YAML runs on any infrastructure
+- Child nodes can spawn sub-workflows
+
+---
+
+## 4. Backends
+
+**What:** Pluggable persistence implementations.
+
+**Purpose:** Store state, workflows, telemetry, and history. Infrastructure-agnostic.
+
+```python
+from soe.local_backends import create_in_memory_backends
+
+backends = create_in_memory_backends()
+```
+
+**The 5 Backend Types:**
+
+| Backend | Interface | Purpose |
+|---------|-----------|---------|
+| `context` | `ContextBackend` | Execution state |
+| `workflow` | `WorkflowBackend` | Workflow definitions |
+| `telemetry` | `TelemetryBackend` | Logs and events |
+| `conversation_history` | `ConversationHistoryBackend` | LLM chat history |
+| `schema` | `SchemaBackend` | Context validation schemas |
+
+**Key Properties:**
+- Follow Python `Protocol` (structural typing)
+- Built-in: In-Memory, Local Files
+- Custom: PostgreSQL, DynamoDB, Redis, etc.
+
+See [Chapter 10: Infrastructure](../guide_10_infrastructure.md) for implementation details.
+
+---
+
+## 5. Nodes
+
+**What:** Execution units that perform work when triggered by signals.
+
+**Purpose:** The building blocks of workflows. Each node type has a specific role.
+
+**The 3 Core Node Types:**
+
+| Node Type | Purpose | Does Work? |
+|-----------|---------|-----------|
+| `tool` | Execute Python functions | ✅ Yes |
+| `llm` | Generate text via LLM | ✅ Yes |
+| `router` | Evaluate conditions, emit signals | ❌ Pure routing |
+
+With these three core nodes, you can build any workflow pattern—including custom agent loops.
+
+**Additional Node Types (Convenience):**
+
+| Node Type | Purpose | Description |
+|-----------|---------|-------------|
+| `agent` | Autonomous reasoning with tools | Built-in ReAct loop |
+| `child` | Spawn sub-workflows | Sub-orchestration |
+
+**Key Properties:**
+- Nodes are stateless—all state lives in Context
+- Nodes communicate only via Signals
+- Nodes are created by factory functions
+- Multiple instances of the same type can exist
+
+```yaml
+ValidateUser:
+  node_type: router
+  event_triggers: [START]
+  ...
+
+ValidatePayment:
+  node_type: router
+  event_triggers: [USER_VALID]
+  ...
+```
+
+---
+
+## 6. Callers
+
+**What:** Functions that control how signals are broadcast.
+
+**Purpose:** The communication layer. Enables distribution without changing workflows.
+
+```python
+def broadcast_signals_caller(id: str, signals: List[str]) -> None:
+    broadcast_signals(id, signals, nodes, backends)
+```
+
+**Key Properties:**
+- The default caller is synchronous and in-process
+- Custom callers enable distribution (HTTP, Lambda, SQS, etc.)
+- Callers wrap `broadcast_signals` with additional behavior
+- The same workflow works with any caller
+
+**Distribution Examples:**
+- **HTTP Caller:** Signals become webhook POSTs
+- **Lambda Caller:** Signals trigger AWS Lambda functions
+- **SQS Caller:** Signals become queue messages
+
+See [Chapter 10: Infrastructure](../guide_10_infrastructure.md) for implementation details.
+
+---
+
+## 6. Identities
+
+**What:** System prompts for LLM and Agent nodes.
+
+**Purpose:** Define roles and consistent behavior for LLM calls without repeating in every prompt.
+
+```yaml
+identities:
+  analyst: |
+    You are a senior data analyst. Be thorough and precise.
+    Always cite sources when making claims.
+  reviewer: |
+    You are a code reviewer. Focus on correctness and maintainability.
+```
+
+**Key Properties:**
+- Defined in config YAML alongside workflows
+- Referenced by `identity` field in LLM/Agent nodes
+- Stored by `IdentityBackend`
+- Keyed by `main_execution_id` (child workflows access parent's identities)
+- Removes the need to specify role in every prompt
+
+**Usage in Nodes:**
+```yaml
+Analyzer:
+  node_type: llm
+  identity: analyst  # References identity defined above
+  prompt: "Analyze: {{ context.input }}"
+```
+
+See [Chapter 7: Identity](../guide_07_identity.md) for details.
+
+---
+
+## 7. Context Schema
+
+**What:** Type definitions for context fields.
+
+**Purpose:** Validate LLM output matches expected types before downstream use.
+
+```yaml
+context_schema:
+  summary:
+    type: string
+    description: A one-sentence summary
+  result:
+    type: object
+    description: The workflow result
+```
+
+**Key Properties:**
+- Defined in config YAML alongside workflows
+- Validates LLM `output_field` values
+- Stored by `ContextSchemaBackend`
+- Keyed by `main_execution_id` (child workflows access parent's schema)
+- Removes the need to specify output format in every prompt
+
+**Available Types:**
+| Type | Python Type |
+|------|-------------|
+| `string` | `str` |
+| `integer` | `int` |
+| `number` | `float` |
+| `boolean` | `bool` |
+| `object` | `dict` |
+| `list` | `list` |
+
+See [Chapter 6: Context Schema](../guide_06_schema.md) for details.
+
+---
+
+## How Primitives Interact
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CONFIG (YAML)                          │
+│  workflows, identities, context_schema                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     ORCHESTRATION                           │
+│  Parses config, initializes backends, broadcasts signals    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        SIGNALS                              │
+│  Flow through the system: START → VALID → COMPLETE          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         NODES                               │
+│  Triggered by signals, read/write Context, emit signals     │
+│  router | tool | llm | agent | child                        │
+│  LLM/Agent nodes use: Identities + Context Schema           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        CONTEXT                              │
+│  Shared state: {"user": "alice", "result": "..."}           │
+│  Accessible via Jinja: {{ context.user }}                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       BACKENDS                              │
+│  context | workflow | identity | context_schema | telemetry │
+└─────────────────────────────────────────────────────────────┘
+```
+
+See [Chapter 9: Ecosystem](../guide_09_ecosystem.md) for multi-workflow patterns.
+
+---
+
+## Summary Table
+
+| Primitive | What | Where Defined | Stored By |
+|-----------|------|---------------|-----------|
+| **Signals** | Named events | YAML `event_emissions` | — (transient) |
+| **Context** | Shared state | Runtime | `ContextBackend` |
+| **Workflows** | Node blueprints | YAML files | `WorkflowBackend` |
+| **Backends** | Persistence | Python classes | — |
+| **Nodes** | Execution units | YAML + factories | — |
+| **Identities** | System prompts | Config YAML | `IdentityBackend` |
+| **Context Schema** | Type validation | Config YAML | `ContextSchemaBackend` |
+
+Master these 7 primitives, and you can build anything with SOE.