soe-ai 0.2.0b1__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/context_schema.md

@@ -0,0 +1,158 @@
+
+# Built-in: Context Schema Management
+
+## Runtime Schema Control
+
+These built-in tools enable workflows to **manage context schemas at runtime**. Context schemas define the structure and types of context fields—querying, adding, and removing fields enables self-evolving data structures.
+
+---
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `soe_get_context_schema` | Query current context schema |
+| `soe_inject_context_schema_field` | Add or update a schema field |
+| `soe_remove_context_schema_field` | Remove a schema field |
+
+---
+
+## soe_get_context_schema
+
+Query the context schema for the current execution.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `field_name` | `Optional[str]` | `None` | Get a specific field's definition |
+
+### Return Values
+
+- **No parameters**: Returns full schema dict of `field_name -> field_definition`
+- **`field_name` provided**: Returns `{"field_name": "...", "definition": {...}}`
+- **Not found**: Returns `{"error": "...", "available": [...]}`
+
+### Use Cases
+
+- **Introspection** — Let LLMs understand expected data structure
+- **Validation** — Check schema before writing context
+- **Documentation** — Generate field descriptions dynamically
+
+---
+
+## soe_inject_context_schema_field
+
+Add or update a single field in the context schema.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `field_name` | `str` | Name of the field to add/update |
+| `field_definition` | `str` | JSON or YAML string with field definition |
+
+### Field Definition Format
+
+```json
+{
+    "type": "string",
+    "description": "User's preferred language",
+    "required": false,
+    "default": "en"
+}
+```
+
+Or in YAML:
+
+```yaml
+type: object
+description: User preferences
+properties:
+  theme: string
+  language: string
+```
+
+### Return Value
+
+```python
+{
+    "success": True,
+    "field_name": "user_preferences",
+    "action": "created",  # or "updated"
+    "message": "Successfully created field 'user_preferences' in context schema"
+}
+```
+
+### Use Cases
+
+- **Dynamic schemas** — Add fields based on workflow needs
+- **Self-evolution** — Workflows define their own data structures
+- **Extension** — Add domain-specific fields at runtime
+
+---
+
+## soe_remove_context_schema_field
+
+Remove a single field from the context schema.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `field_name` | `str` | Name of field to remove |
+
+### Return Value
+
+```python
+{
+    "removed": True,
+    "field_name": "deprecated_field",
+    "message": "Successfully removed field 'deprecated_field' from context schema"
+}
+```
+
+Raises `ValueError` if field not found.
+
+### Use Cases
+
+- **Cleanup** — Remove unused schema fields
+- **Refactoring** — Remove deprecated fields
+- **Evolution** — Replace outdated field definitions
+
+---
+
+## Schema Patterns
+
+### Self-Documenting Workflows
+
+A workflow that describes its own data requirements:
+
+
+```yaml
+self_documenting:
+  DescribeNeeds:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Based on task {{ context.task }}, what data fields do we need?"
+    output_field: needed_fields
+    event_emissions:
+      - signal_name: NEEDS_DESCRIBED
+
+  CreateSchema:
+    node_type: tool
+    event_triggers: [NEEDS_DESCRIBED]
+    tool_name: soe_inject_context_schema_field
+    context_parameter_field: schema_field_config
+    output_field: schema_result
+    event_emissions:
+      - signal_name: SCHEMA_READY
+```
+
+
+---
+
+## Related
+
+- [Built-in Tools Overview](../guide_11_builtins.md) — All available built-ins
+- [Context Schema Guide](../guide_06_schema.md) — Schema fundamentals

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/builtins/soe_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