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

soe/docs/builtins/context.md

@@ -0,0 +1,164 @@
+
+# Built-in: Context Management
+
+## Execution State Control
+
+These built-in tools enable workflows to **manage execution context**. Context is the shared state that flows through nodes—reading, updating, and copying it enables sophisticated patterns like parallel execution, state persistence, and dynamic behavior.
+
+---
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `soe_get_context` | Read the current execution context |
+| `soe_update_context` | Modify context fields |
+| `soe_copy_context` | Clone context for parallel execution |
+| `soe_list_contexts` | Discover available contexts |
+
+---
+
+## soe_get_context
+
+Read the current execution context snapshot.
+
+```yaml
+example_workflow:
+  GetContext:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_context
+    output_field: current_context
+    event_emissions:
+      - signal_name: CONTEXT_RETRIEVED
+```
+
+Returns the full context dictionary including all fields and `__operational__` state.
+
+### Use Cases
+
+- **Introspection** — Let LLMs see full workflow state
+- **Debugging** — Inspect context during development
+- **Decision making** — Base routing on complete state
+
+---
+
+## soe_update_context
+
+Modify context fields programmatically.
+
+```yaml
+example_workflow:
+  UpdateContext:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_update_context
+    context_parameter_field: context_updates
+    output_field: update_result
+    event_emissions:
+      - signal_name: CONTEXT_UPDATED
+```
+
+### Context Setup
+
+The `context_updates` field should contain key-value pairs:
+
+```python
+{
+    "new_field": "new_value",
+    "counter": 42,
+    "nested": {"key": "value"}
+}
+```
+
+### Use Cases
+
+- **State injection** — Add computed values to context
+- **Reset/clear** — Modify state for retry patterns
+- **Enrichment** — Add metadata or derived values
+
+---
+
+## soe_copy_context
+
+Clone context for parallel execution or branching.
+
+```yaml
+example_workflow:
+  CopyContext:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_copy_context
+    context_parameter_field: copy_params
+    output_field: copy_result
+    event_emissions:
+      - signal_name: CONTEXT_COPIED
+```
+
+### Context Setup
+
+The `copy_params` field specifies target:
+
+```python
+{
+    "target_execution_id": "new_execution_123",
+    "fields_to_copy": ["user_data", "config"]  # Optional: copy specific fields only
+}
+```
+
+### Use Cases
+
+- **Parallel workers** — Each worker gets its own context copy
+- **Branching** — Create alternative execution paths
+- **Snapshotting** — Save state before risky operations
+
+---
+
+## soe_list_contexts
+
+Discover available contexts (useful for multi-execution patterns).
+
+```yaml
+example_workflow:
+  ListAllContexts:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_list_contexts
+    output_field: available_contexts
+    event_emissions:
+      - signal_name: CONTEXTS_LISTED
+```
+
+Returns a list of execution IDs with contexts.
+
+### Use Cases
+
+- **Orchestration** — Manage multiple parallel executions
+- **Cleanup** — Find old contexts to archive
+- **Aggregation** — Collect results from multiple executions
+
+---
+
+## Context Patterns
+
+### Context Inspection for LLMs
+
+Let an LLM reason about full state:
+
+```yaml
+reflective_workflow:
+  GatherState:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_context
+    output_field: full_state
+    event_emissions:
+      - signal_name: STATE_GATHERED
+```
+
+---
+
+## Related
+
+- [Built-in Tools Overview](../guide_11_builtins.md) — All available built-ins
+- [Operational Features](../advanced_patterns/operational.md) — Context structure details

soe/docs/builtins/explore_docs.md

@@ -0,0 +1,135 @@
+
+# Built-in: soe_explore_docs
+
+## Making SOE Self-Aware
+
+The `soe_explore_docs` built-in tool enables workflows to **explore their own documentation**. This is the foundation for self-awareness—a workflow can discover what SOE is capable of, understand its own structure, and reason about available patterns.
+
+---
+
+## Why Self-Awareness Matters
+
+Self-awareness transforms a static workflow into an intelligent system that can:
+
+- **Discover capabilities** — Find out what node types, patterns, and features exist
+- **Learn from examples** — Read documentation to understand how to use features
+- **Adapt behavior** — Make decisions based on available functionality
+- **Evolve intelligently** — Create new nodes based on documented patterns
+
+Without `soe_explore_docs`, an LLM in a workflow would be "blind"—it couldn't know what SOE can do. With it, the LLM becomes a partner that understands the orchestration engine itself.
+
+---
+
+## Basic Usage
+
+### List Documentation Structure
+
+```yaml
+example_workflow:
+  ExploreDocs:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    context_parameter_field: explore_params
+    output_field: docs_list
+    event_emissions:
+      - signal_name: DOCS_LISTED
+```
+
+Returns entries like:
+```
+[DIR] advanced_patterns/
+[FILE] guide_01_tool.md
+[FILE] guide_02_llm.md
+```
+
+### Search Documentation
+
+```yaml
+example_workflow:
+  SearchDocs:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    context_parameter_field: explore_params
+    output_field: search_results
+    event_emissions:
+      - signal_name: SEARCH_COMPLETE
+```
+
+Search finds relevant paths matching the query.
+
+### Read Documentation Content
+
+```yaml
+example_workflow:
+  ReadGuide:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    context_parameter_field: explore_params
+    output_field: guide_content
+    event_emissions:
+      - signal_name: GUIDE_READ
+```
+
+Returns the full markdown content of the file.
+
+---
+
+## Actions Reference
+
+| Action | Description | Required Args |
+|--------|-------------|---------------|
+| `list` | Show children at path (files, dirs, sections) | `path` |
+| `read` | Get content of file or section | `path` |
+| `tree` | Recursive structure from path | `path` |
+| `search` | Find docs matching query/tag | `query` or `tag` |
+| `get_tags` | List all available tags | none |
+
+---
+
+## Path Navigation
+
+The `path` argument navigates the documentation hierarchy:
+
+| Path | What It Returns |
+|------|-----------------|
+| `/` | Root documentation listing |
+| `soe/docs/guide_01_tool.md` | File content or sections within |
+| `soe/docs/guide_01_tool.md/Your First Tool Node` | Specific section content |
+| `soe/docs/advanced_patterns/` | Directory contents |
+
+---
+
+## Integration with LLM Nodes
+
+The power of `soe_explore_docs` comes from combining it with LLM reasoning:
+
+```yaml
+metacognitive_workflow:
+  DiscoverCapabilities:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    context_parameter_field: explore_params
+    output_field: soe_capabilities
+    event_emissions:
+      - signal_name: CAPABILITIES_DISCOVERED
+
+  ReadRelevantGuide:
+    node_type: tool
+    event_triggers: [READ_GUIDE]
+    tool_name: soe_explore_docs
+    context_parameter_field: guide_params
+    output_field: guide_content
+    event_emissions:
+      - signal_name: KNOWLEDGE_ACQUIRED
+```
+
+---
+
+## Related
+
+- [Built-in Tools Overview](../guide_11_builtins.md) — All available built-ins
+- [Self-Evolving Workflows](../advanced_patterns/self_evolving_workflows.md) — Using soe_explore_docs for evolution

soe/docs/builtins/tools.md

@@ -0,0 +1,164 @@
+
+# Built-in: Tool Management
+
+## Dynamic Tool Discovery and Invocation
+
+These built-in tools enable workflows to **discover and invoke tools dynamically**. Rather than hardcoding tool references, workflows can query available capabilities and invoke tools by name at runtime—enabling truly flexible, self-evolving systems.
+
+---
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `soe_get_available_tools` | List all registered tools |
+| `soe_call_tool` | Invoke a tool by name dynamically |
+
+---
+
+## soe_get_available_tools
+
+Discover all tools registered in the current orchestration context.
+
+```yaml
+example_workflow:
+  ListTools:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_available_tools
+    output_field: available_tools
+    event_emissions:
+      - signal_name: TOOLS_LISTED
+```
+
+Returns a list of tool names that can be invoked with `soe_call_tool`.
+
+### Use Cases
+
+- **Self-awareness** — Let LLMs understand available capabilities
+- **Dynamic routing** — Choose tools based on current needs
+- **Validation** — Check if a required tool exists before invoking
+
+---
+
+## soe_call_tool
+
+Invoke any registered tool by name with JSON arguments.
+
+```yaml
+example_workflow:
+  CallDynamicTool:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_call_tool
+    context_parameter_field: tool_invocation
+    output_field: tool_result
+    event_emissions:
+      - signal_name: TOOL_CALLED
+```
+
+### Context Setup
+
+The node expects `tool_invocation` in context with:
+
+```python
+{
+    "tool_name": "name_of_tool",
+    "arguments": '{"arg1": "value1", "arg2": "value2"}'
+}
+```
+
+### Return Value
+
+Returns a result dictionary:
+
+```python
+{
+    "success": True,
+    "result": { ... }  # Tool's return value
+}
+```
+
+Or on error:
+
+```python
+{
+    "success": False,
+    "error": "Error message"
+}
+```
+
+### Use Cases
+
+- **LLM-driven tool selection** — Let LLMs choose and invoke tools
+- **Dynamic dispatch** — Route to tools based on runtime conditions
+- **Tool orchestration** — Build meta-tools that compose other tools
+
+---
+
+## Dynamic Tool Pattern
+
+Combine discovery and invocation for fully dynamic behavior:
+
+```yaml
+dynamic_tool_workflow:
+  DiscoverTools:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_available_tools
+    output_field: available_tools
+    event_emissions:
+      - signal_name: TOOLS_DISCOVERED
+
+  InvokeTool:
+    node_type: tool
+    event_triggers: [TOOLS_DISCOVERED]
+    tool_name: soe_call_tool
+    context_parameter_field: tool_invocation
+    output_field: invocation_result
+    event_emissions:
+      - signal_name: INVOCATION_COMPLETE
+```
+
+This pattern enables:
+
+1. **Discovery** — First, query available tools
+2. **Decision** — LLM or router selects appropriate tool
+3. **Invocation** — Execute the chosen tool dynamically
+
+---
+
+## When to Use
+
+### Use Dynamic Invocation When:
+
+- Tool selection depends on runtime context
+- LLMs need to choose from available capabilities
+- Building meta-tools that orchestrate other tools
+- Creating plugin-like architectures
+
+### Use Direct Tool Nodes When:
+
+- Tool is always the same
+- No runtime decision needed
+- Performance is critical (direct is faster)
+
+---
+
+## Security Considerations
+
+`soe_call_tool` can only invoke tools in the `tools_registry`. It cannot:
+
+- Execute arbitrary code
+- Access tools not explicitly registered
+- Bypass tool retry/error handling
+
+The registry acts as a whitelist—only tools you register are available.
+
+---
+
+## Related
+
+- [Context Management](context.md) — Managing execution state
+- [Workflow Management](workflows.md) — Runtime workflow modification
+- [Self-Evolving Workflows](../advanced_patterns/self_evolving_workflows.md) — Building autonomous systems

soe/docs/builtins/workflows.md

@@ -0,0 +1,199 @@
+
+# Built-in: Workflow Modification
+
+## Runtime Workflow Evolution
+
+These built-in tools enable workflows to **modify themselves at runtime**. This is the core capability for self-evolution—a workflow can inspect its structure, add new nodes, inject new workflows, and remove obsolete components.
+
+---
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `soe_get_workflows` | Query registered workflow definitions |
+| `soe_inject_workflow` | Add new workflows to the registry |
+| `soe_inject_node` | Add or modify nodes in existing workflows |
+| `soe_remove_workflow` | Remove workflows from registry |
+| `soe_remove_node` | Remove nodes from workflows |
+
+---
+
+## soe_get_workflows
+
+Query the current workflow registry to see all registered workflows and their structure.
+
+```yaml
+example_workflow:
+  GetWorkflows:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_workflows
+    output_field: workflows_list
+    event_emissions:
+      - signal_name: WORKFLOWS_RETRIEVED
+```
+
+Returns a dictionary of all registered workflows with their node configurations.
+
+### Use Cases
+
+- **Introspection** — See what workflows are available
+- **Validation** — Check if a workflow exists before spawning it
+- **Evolution planning** — Understand current structure before modifying
+
+---
+
+## soe_inject_workflow
+
+Add a completely new workflow to the registry at runtime.
+
+```yaml
+example_workflow:
+  InjectNew:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_inject_workflow
+    context_parameter_field: workflow_to_inject
+    output_field: injection_result
+    event_emissions:
+      - signal_name: WORKFLOW_INJECTED
+        condition: "{{ result.status == 'success' }}"
+      - signal_name: INJECTION_FAILED
+        condition: "{{ result.status != 'success' }}"
+```
+
+### Context Setup
+
+The `workflow_to_inject` context field should contain:
+
+```python
+{
+    "workflow_name": "new_workflow",
+    "workflow_definition": {
+        "StartNode": {
+            "node_type": "router",
+            "event_triggers": ["START"],
+            "event_emissions": [{"signal_name": "READY"}]
+        }
+    }
+}
+```
+
+### Use Cases
+
+- **Dynamic workflow creation** — LLM designs new workflows
+- **Plugin systems** — Load workflows based on configuration
+- **A/B testing** — Inject alternative workflow versions
+
+---
+
+## soe_inject_node
+
+Add or modify a single node in an existing workflow.
+
+```yaml
+example_workflow:
+  InjectNode:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_inject_node
+    context_parameter_field: node_to_inject
+    output_field: node_injection_result
+    event_emissions:
+      - signal_name: NODE_INJECTED
+        condition: "{{ result.status == 'success' }}"
+```
+
+### Context Setup
+
+The `node_to_inject` context field should contain:
+
+```python
+{
+    "workflow_name": "example_workflow",
+    "node_name": "NewProcessor",
+    "node_configuration": {
+        "node_type": "tool",
+        "event_triggers": ["PROCESS"],
+        "tool_name": "process_data",
+        "output_field": "result",
+        "event_emissions": [{"signal_name": "PROCESSED"}]
+    }
+}
+```
+
+### Use Cases
+
+- **Incremental evolution** — Add nodes one at a time
+- **Patching** — Modify existing node behavior
+- **Extension** — Add new capabilities to existing workflows
+
+---
+
+## soe_remove_workflow
+
+Remove a workflow from the registry.
+
+```yaml
+example_workflow:
+  RemoveOldWorkflow:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_remove_workflow
+    context_parameter_field: remove_params
+    output_field: removal_result
+    event_emissions:
+      - signal_name: WORKFLOW_REMOVED
+```
+
+---
+
+## soe_remove_node
+
+Remove a specific node from a workflow.
+
+```yaml
+example_workflow:
+  RemoveNode:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_remove_node
+    context_parameter_field: remove_params
+    output_field: node_removal_result
+    event_emissions:
+      - signal_name: NODE_REMOVED
+```
+
+---
+
+## Evolution Pattern
+
+Combine these tools for full self-evolution:
+
+```yaml
+evolving_workflow:
+  AnalyzeState:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_get_workflows
+    output_field: current_state
+    event_emissions:
+      - signal_name: STATE_ANALYZED
+
+  ApplyImprovement:
+    node_type: tool
+    event_triggers: [STATE_ANALYZED]
+    tool_name: soe_inject_node
+    context_parameter_field: designed_node
+    output_field: injection_result
+    event_emissions:
+      - signal_name: EVOLVED
+```
+
+---
+
+## Related
+
+- [Built-in Tools Overview](../guide_11_builtins.md) — All available built-ins
+- [Self-Evolving Workflows](../advanced_patterns/self_evolving_workflows.md) — Complete evolution patterns