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

soe/docs/builtins/identity.md

@@ -0,0 +1,139 @@
+
+# Built-in: Identity Management
+
+## Runtime Identity Control
+
+These built-in tools enable workflows to **manage identities at runtime**. Identities define the system prompts for LLM personas—querying, adding, and removing them enables dynamic personality switching and self-evolving agents.
+
+---
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `soe_get_identities` | Query current identity definitions |
+| `soe_inject_identity` | Add or update an identity |
+| `soe_remove_identity` | Remove an identity |
+
+---
+
+## soe_get_identities
+
+Query identity definitions from the current execution.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `identity_name` | `Optional[str]` | `None` | Get a specific identity |
+| `list_only` | `bool` | `False` | Return only identity names |
+
+### Return Values
+
+- **No parameters**: Returns full dict of `identity_name -> system_prompt`
+- **`list_only=True`**: Returns `{"identity_names": ["assistant", "expert", ...]}`
+- **`identity_name` provided**: Returns `{"identity_name": "...", "system_prompt": "..."}`
+- **Not found**: Returns `{"error": "...", "available": [...]}`
+
+### Use Cases
+
+- **Introspection** — Let LLMs see available personas
+- **Decision making** — Choose identity based on task
+- **Debugging** — Inspect identity configuration
+
+---
+
+## soe_inject_identity
+
+Add or update a single identity definition.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `identity_name` | `str` | Name/key for the identity |
+| `system_prompt` | `str` | The system prompt text |
+
+### Return Value
+
+```python
+{
+    "success": True,
+    "identity_name": "expert",
+    "action": "created",  # or "updated"
+    "message": "Successfully created identity 'expert'"
+}
+```
+
+### Use Cases
+
+- **Dynamic personas** — Create identities based on user needs
+- **Self-evolution** — Workflows define their own personas
+- **Specialization** — Add domain-specific identities at runtime
+
+---
+
+## soe_remove_identity
+
+Remove a single identity definition.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `identity_name` | `str` | Name of identity to remove |
+
+### Return Value
+
+```python
+{
+    "removed": True,
+    "identity_name": "old_persona",
+    "message": "Successfully removed identity 'old_persona'"
+}
+```
+
+Raises `ValueError` if identity not found.
+
+### Use Cases
+
+- **Cleanup** — Remove unused personas
+- **Reset** — Clear identities before reconfiguration
+- **Evolution** — Replace outdated personas
+
+---
+
+## Identity Patterns
+
+### Dynamic Persona Selection
+
+A workflow that chooses its identity based on task:
+
+
+```yaml
+dynamic_persona:
+  AnalyzeTask:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Analyze this task and suggest a persona: {{ context.task }}"
+    output_field: suggested_persona
+    event_emissions:
+      - signal_name: PERSONA_SUGGESTED
+
+  CreatePersona:
+    node_type: tool
+    event_triggers: [PERSONA_SUGGESTED]
+    tool_name: soe_inject_identity
+    context_parameter_field: persona_config
+    output_field: identity_result
+    event_emissions:
+      - signal_name: PERSONA_READY
+```
+
+
+---
+
+## Related
+
+- [Built-in Tools Overview](../guide_11_builtins.md) — All available built-ins
+- [Identity Guide](../guide_07_identity.md) — Identity fundamentals

soe/docs/guide_01_tool.md

@@ -39,6 +39,58 @@ example_workflow:
 3.  **`output_field`**: Where to store the result in context.
 4.  **`event_emissions`**: Signals to emit after execution (conditions evaluate `result`).
 
+## Passing Parameters to Tools
+
+There are two ways to pass parameters to a tool: **inline parameters** (hardcoded in YAML) or **context parameters** (dynamic from context).
+
+### Option 1: Inline Parameters (Static)
+
+Use `parameters` to specify tool arguments directly in the workflow YAML:
+
+```yaml
+example_workflow:
+  ReadToolDocs:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    parameters:
+      path: "soe/docs/guide_01_tool.md"
+      action: "read"
+    output_field: tool_documentation
+    event_emissions:
+      - signal_name: DOCS_READY
+```
+
+**Jinja templates work in parameters:**
+
+```yaml
+example_workflow:
+  FetchUserData:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: fetch_data
+    parameters:
+      user_id: "{{ context.current_user_id }}"
+      include_history: true
+    output_field: user_data
+    event_emissions:
+      - signal_name: DATA_FETCHED
+```
+
+### Option 2: Context Parameters (Dynamic)
+
+Use `context_parameter_field` when the parameters come from another node's output or initial context:
+
+```yaml
+example_workflow:
+  SendEmail:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: send_email
+    context_parameter_field: email_data
+    output_field: email_result
+```
+
 ### Understanding context_parameter_field
 
 The `context_parameter_field` specifies which context field contains the parameters to pass to your tool. This field must contain a dictionary that will be unpacked as keyword arguments.

soe/docs/guide_02_llm.md

@@ -79,7 +79,7 @@ This pattern is incredibly useful for:
 
 ## LLM Signal Selection (Resolution Step)
 
-When an LLM node has multiple signals with **conditions** (plain text, not Jinja), the LLM itself decides which signal to emit.
+When an LLM node has multiple signals with **conditions** (plain text, not Jinja), the LLM itself decides which signals to emit.
 
 ### The Workflow
 
@@ -103,8 +103,8 @@ example_workflow:
 
 1. The LLM analyzes the sentiment
 2. SOE sees multiple signals with plain-text conditions (no `{{ }}`)
-3. SOE asks the LLM: "Based on your analysis, which signal should be emitted?" using the conditions as descriptions
-4. The LLM returns the appropriate signal (POSITIVE, NEGATIVE, or NEUTRAL)
+3. SOE asks the LLM: "Select ALL signals that apply" using the conditions as descriptions
+4. The LLM returns a list of matching signals (can be none, one, or multiple)
 
 This is called the **resolution step** - it lets the LLM make routing decisions based on its understanding.
 
@@ -115,7 +115,7 @@ The `condition` field controls how signals are emitted:
 | Condition | Behavior |
 |-----------|----------|
 | **No condition** | Signal is always emitted |
-| **Plain text** | Semantic—LLM selects which signal to emit based on the description |
+| **Plain text** | Semantic—LLM selects any/all signals that apply based on the descriptions |
 | **Jinja template (`{{ }}`)** | Programmatic—evaluated against `context`, emits if truthy |
 
 **How SOE decides:**
@@ -123,7 +123,7 @@ The `condition` field controls how signals are emitted:
 1. **No conditions**: All signals emit unconditionally after node execution
 2. **Has conditions**: SOE checks if they contain `{{ }}`:
    - **Yes (Jinja)**: Evaluate expression against `context`—emit if result is truthy
-   - **No (plain text)**: Ask LLM to choose which signal best matches its output
+   - **No (plain text)**: Ask LLM to select which signals apply (multi-select)
 
 ## Testing LLM Nodes
 

soe/docs/guide_11_builtins.md

@@ -57,19 +57,25 @@ Unlike custom tools that need a `tools_registry`, built-ins work immediately. SO
 
 | Built-in | Purpose | Documentation |
 |----------|---------|---------------|
-| `soe_explore_docs` | Make SOE self-aware by exploring its documentation | [explore_docs](builtins/explore_docs.md) |
+| `soe_explore_docs` | Make SOE self-aware by exploring its documentation | [explore_docs](builtins/soe_explore_docs.md) |
 | `soe_get_workflows` | Query registered workflow definitions | [workflows](builtins/workflows.md) |
 | `soe_inject_workflow` | Add new workflows at runtime | [workflows](builtins/workflows.md) |
 | `soe_inject_node` | Add or modify nodes in workflows | [workflows](builtins/workflows.md) |
 | `soe_remove_workflow` | Remove workflows from registry | [workflows](builtins/workflows.md) |
 | `soe_remove_node` | Remove nodes from workflows | [workflows](builtins/workflows.md) |
+| `soe_add_signal` | Add signals to node configurations | [workflows](builtins/workflows.md) |
 | `soe_get_context` | Read execution context | [context](builtins/context.md) |
 | `soe_update_context` | Modify execution context | [context](builtins/context.md) |
 | `soe_copy_context` | Clone context for parallel execution | [context](builtins/context.md) |
 | `soe_list_contexts` | Discover available contexts | [context](builtins/context.md) |
+| `soe_get_identities` | Query identity definitions | [identity](builtins/identity.md) |
+| `soe_inject_identity` | Add or update an identity | [identity](builtins/identity.md) |
+| `soe_remove_identity` | Remove an identity | [identity](builtins/identity.md) |
+| `soe_get_context_schema` | Query context schema | [context_schema](builtins/context_schema.md) |
+| `soe_inject_context_schema_field` | Add or update a schema field | [context_schema](builtins/context_schema.md) |
+| `soe_remove_context_schema_field` | Remove a schema field | [context_schema](builtins/context_schema.md) |
 | `soe_get_available_tools` | List all registered tools | [tools](builtins/tools.md) |
 | `soe_call_tool` | Invoke a tool by name dynamically | [tools](builtins/tools.md) |
-| `soe_add_signal` | Emit signals programmatically | [workflows](builtins/workflows.md) |
 
 ---
 
@@ -105,9 +111,11 @@ This pattern is the foundation for metacognitive workflows that can reason about
 
 Explore each built-in category in detail:
 
-- **[explore_docs](builtins/explore_docs.md)** — Self-awareness through documentation
+- **[explore_docs](builtins/soe_explore_docs.md)** — Self-awareness through documentation
 - **[workflows](builtins/workflows.md)** — Runtime workflow modification
 - **[context](builtins/context.md)** — Execution state management
+- **[identity](builtins/identity.md)** — Runtime identity management
+- **[context_schema](builtins/context_schema.md)** — Runtime schema management
 - **[tools](builtins/tools.md)** — Dynamic tool discovery and invocation
 
 ---

soe/docs/index.md

@@ -81,10 +81,12 @@ Built-in tools enable granular runtime modifications:
 
 | Built-in | Description |
 |----------|-------------|
-| [explore_docs](builtins/explore_docs.md) | Make SOE self-aware by exploring its documentation |
+| [soe_explore_docs](builtins/soe_explore_docs.md) | Make SOE self-aware by exploring its documentation |
 | [workflows](builtins/workflows.md) | Query, inject, and modify workflows at runtime |
 | [context](builtins/context.md) | Read, update, and copy execution context |
 | [tools](builtins/tools.md) | Discover and dynamically call registered tools |
+| [identity](builtins/identity.md) | Query, inject, and remove identity definitions |
+| [context_schema](builtins/context_schema.md) | Query, inject, and remove context schema fields |
 
 ---
 

soe/docs/primitives/node_reference.md

@@ -44,6 +44,7 @@ Complete reference for all node configuration parameters across all node types.
 |-----------|------|--------|-----|-------|------|-------|-------------|
 | `tool_name` | `str` | ✗ | ✗ | ✗ | **R** | ✗ | Tool to execute from registry |
 | `tools` | `List[str]` | ✗ | ✗ | **O** | ✗ | ✗ | Tool names available to agent |
+| `parameters` | `Dict` | ✗ | ✗ | ✗ | **O** | ✗ | Inline tool kwargs (supports Jinja) |
 | `context_parameter_field` | `str` | ✗ | ✗ | ✗ | **O** | ✗ | Context field containing tool kwargs |
 
 ### Child Workflow Parameters

soe/docs/primitives/signals.md

@@ -122,7 +122,7 @@ example_workflow:
 
 Both `PROCESSING_DONE` and `LOG_EVENT` emit every time the node runs.
 
-> **Note**: For Router nodes, multiple unconditional signals all emit simultaneously (fan-out pattern). For LLM/Agent nodes with multiple signals, the LLM must select one - use Jinja conditions like `{{ true }}` if you want all signals to emit.
+> **Note**: For Router nodes, multiple unconditional signals all emit simultaneously (fan-out pattern). For LLM/Agent nodes with multiple signals, the LLM can select any/all that apply—including none.
 
 ### Mode 2: Jinja Template (Programmatic)
 
@@ -207,8 +207,9 @@ The behavior depends on the node type:
 │     └─ Zero signals? → Nothing emitted                       │
 │     └─ Single signal? → Emit unconditionally                 │
 │     └─ Multiple signals?                                     │
-│         └─ LLM selects ONE signal                            │
+│         └─ LLM selects ANY/ALL that apply                    │
 │            (uses conditions as semantic descriptions)        │
+│            (can select none, one, or multiple)               │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 
@@ -300,7 +301,7 @@ example_workflow:
         condition: "The message is factual, neutral, or emotionally ambiguous"
 ```
 
-**LLM Selection Mechanism**: SOE adds a `selected_signal` field to the response model, forcing the LLM to choose from the options. The condition text serves as the description.
+**LLM Selection Mechanism**: SOE adds a `selected_signals` field to the response model, allowing the LLM to select any/all signals that apply. The condition text serves as the description.
 
 ---
 
@@ -627,26 +628,26 @@ When the child updates these keys, they're automatically copied to the parent's
 
 ## LLM Signal Selection: Under the Hood
 
-When the LLM selects a signal, SOE:
+When the LLM selects signals, SOE:
 
-1. **Builds a response model** with a `selected_signal` field:
+1. **Builds a response model** with a `selected_signals` field (list):
    ```python
    class Response(BaseModel):
        response: str
-       selected_signal: Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]
+       selected_signals: List[Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]] = []
    ```
 
 2. **Provides descriptions** from the `condition` field:
    ```
-   Select one of these signals based on your response:
+   Select ALL signals that apply (can be none, one, or multiple):
    - POSITIVE: The message expresses positive sentiment
    - NEGATIVE: The message expresses negative sentiment
    - NEUTRAL: The message is neutral
    ```
 
-3. **Extracts the selection** and emits that signal.
+3. **Extracts the selection** and emits all selected signals (can be empty).
 
-This is why plain-text conditions are called "semantic"—the LLM understands the description and makes a judgment call.
+This is why plain-text conditions are called "semantic"—the LLM understands the descriptions and selects all that apply.
 
 ---