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

soe/broker.py

@@ -4,15 +4,18 @@ from .types import Backends, BroadcastSignalsCaller, NodeCaller, EventTypes, Wor
 from .lib.register_event import register_event
 from .lib.yaml_parser import parse_yaml
 from .lib.operational import add_operational_state
-from .lib.context_fields import set_field
 from .lib.parent_sync import get_signals_for_parent
 from .lib.inheritance import (
     inherit_config,
-    inherit_context,
     extract_and_save_config_sections,
+    prepare_initial_context,
+)
+from .validation import (
+    validate_config,
+    validate_operational,
+    validate_orchestrate_params,
+    validate_initial_workflow,
 )
-from .validation import validate_config, validate_operational, validate_orchestrate_params
-from .types import WorkflowValidationError
 
 
 def orchestrate(
@@ -70,17 +73,15 @@ def orchestrate(
 
     id = str(uuid4())
 
+    parsed_registry = {}
     if inherit_config_from_id:
         register_event(
             backends, id, EventTypes.CONFIG_INHERITANCE_START,
             {"source_execution_id": inherit_config_from_id}
         )
         parsed_registry = inherit_config(inherit_config_from_id, id, backends)
-        if config:
-            validate_config(config)
-            parsed_config = parse_yaml(config)
-            parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
-    else:
+
+    if config:
         validate_config(config)
         parsed_config = parse_yaml(config)
         parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
@@ -92,32 +93,13 @@ def orchestrate(
 
     backends.workflow.save_workflows_registry(id, parsed_registry)
 
-    if initial_workflow_name not in parsed_registry:
-        available = list(parsed_registry.keys())
-        raise WorkflowValidationError(
-            f"Workflow '{initial_workflow_name}' not found in config. "
-            f"Available workflows: {available}"
-        )
+    validate_initial_workflow(initial_workflow_name, parsed_registry)
 
     backends.workflow.save_current_workflow_name(id, initial_workflow_name)
 
-    if inherit_context_from_id:
-        register_event(
-            backends, id, EventTypes.CONTEXT_INHERITANCE_START,
-        )
-        context = inherit_context(inherit_context_from_id, backends)
-        if initial_context:
-            register_event(
-                backends, id, EventTypes.CONTEXT_MERGE,
-                {"fields": list(initial_context.keys())}
-            )
-            for field, value in initial_context.items():
-                set_field(context, field, value)
-    else:
-        context = {
-            k: [v] if not k.startswith("__") else v
-            for k, v in initial_context.items()
-        }
+    context = prepare_initial_context(
+        id, initial_context, backends, inherit_context_from_id
+    )
 
     context = add_operational_state(id, context)
     backends.context.save_context(id, context)

soe/builtin_tools/__init__.py

@@ -15,6 +15,12 @@ from .soe_copy_context import create_soe_copy_context_tool
 from .soe_list_contexts import create_soe_list_contexts_tool
 from .soe_add_signal import create_soe_add_signal_tool
 from .soe_call_tool import create_soe_call_tool_tool
+from .soe_get_identities import create_soe_get_identities_tool
+from .soe_inject_identity import create_soe_inject_identity_tool
+from .soe_remove_identity import create_soe_remove_identity_tool
+from .soe_get_context_schema import create_soe_get_context_schema_tool
+from .soe_inject_context_schema_field import create_soe_inject_context_schema_field_tool
+from .soe_remove_context_schema_field import create_soe_remove_context_schema_field_tool
 
 # Registry of all available built-in tools
 BUILTIN_TOOLS = {
@@ -31,6 +37,12 @@ BUILTIN_TOOLS = {
     "soe_list_contexts": create_soe_list_contexts_tool,
     "soe_add_signal": create_soe_add_signal_tool,
     "soe_call_tool": create_soe_call_tool_tool,
+    "soe_get_identities": create_soe_get_identities_tool,
+    "soe_inject_identity": create_soe_inject_identity_tool,
+    "soe_remove_identity": create_soe_remove_identity_tool,
+    "soe_get_context_schema": create_soe_get_context_schema_tool,
+    "soe_inject_context_schema_field": create_soe_inject_context_schema_field_tool,
+    "soe_remove_context_schema_field": create_soe_remove_context_schema_field_tool,
 }
 
 

soe/builtin_tools/soe_get_context_schema.py

@@ -0,0 +1,56 @@
+"""Built-in context schema retrieval tool."""
+
+from typing import Dict, Any, Callable, Optional
+
+
+def create_soe_get_context_schema_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_get_context_schema tool.
+
+    Args:
+        execution_id: ID to access context schema data via backends
+        backends: Backend services to fetch context schema
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_get_context_schema function
+    """
+
+    def soe_get_context_schema(
+        field_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get context schema information from the current execution.
+
+        Args:
+            field_name: If provided, get only this specific field's definition.
+                       If None, returns the full schema.
+
+        Returns:
+            If field_name provided: {"field_name": "...", "definition": {...}}
+            Otherwise: Full schema dict of field_name -> field_definition
+        """
+        schema = backends.context_schema.get_context_schema(execution_id)
+
+        if schema is None:
+            schema = {}
+
+        if field_name:
+            if field_name in schema:
+                return {
+                    "field_name": field_name,
+                    "definition": schema[field_name],
+                }
+            else:
+                return {
+                    "error": f"Field '{field_name}' not found in context schema",
+                    "available": list(schema.keys()),
+                }
+
+        return schema
+
+    return soe_get_context_schema

soe/builtin_tools/soe_get_identities.py

@@ -0,0 +1,63 @@
+"""Built-in identity retrieval tool."""
+
+from typing import Dict, Any, Callable, Optional
+
+
+def create_soe_get_identities_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_get_identities tool.
+
+    Args:
+        execution_id: ID to access identity data via backends
+        backends: Backend services to fetch identities
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_get_identities function
+    """
+
+    def soe_get_identities(
+        identity_name: Optional[str] = None,
+        list_only: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Get identity information from the current execution.
+
+        Args:
+            identity_name: If provided, get only this specific identity's system prompt.
+                          If None, returns info about all identities.
+            list_only: If True, only return identity names (not full system prompts).
+                      Default is False.
+
+        Returns:
+            If list_only=True: {"identity_names": ["assistant", "expert", ...]}
+            If identity_name provided: {"identity_name": "...", "system_prompt": "..."}
+            Otherwise: Full dict of identity_name -> system_prompt
+        """
+        identities = backends.identity.get_identities(execution_id)
+
+        if identities is None:
+            identities = {}
+
+        if list_only:
+            return {"identity_names": list(identities.keys())}
+
+        if identity_name:
+            if identity_name in identities:
+                return {
+                    "identity_name": identity_name,
+                    "system_prompt": identities[identity_name],
+                }
+            else:
+                return {
+                    "error": f"Identity '{identity_name}' not found",
+                    "available": list(identities.keys()),
+                }
+
+        return identities
+
+    return soe_get_identities

soe/builtin_tools/soe_inject_context_schema_field.py

@@ -0,0 +1,80 @@
+"""Built-in context schema field injection tool."""
+
+import json
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+from ..lib.yaml_parser import parse_yaml
+
+
+def create_soe_inject_context_schema_field_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_inject_context_schema_field tool.
+
+    Args:
+        execution_id: ID to access context schema data via backends
+        backends: Backend services to fetch/update context schema
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_inject_context_schema_field function
+    """
+
+    def soe_inject_context_schema_field(
+        field_name: str,
+        field_definition: str,
+    ) -> Dict[str, Any]:
+        """
+        Add or update a field in the context schema.
+
+        Args:
+            field_name: Name of the field to add/update
+            field_definition: JSON or YAML string with field definition
+                             (e.g., {"type": "string", "description": "..."})
+
+        Returns:
+            Success confirmation with field info and action taken
+        """
+        parsed_definition = None
+
+        try:
+            parsed_definition = json.loads(field_definition)
+        except json.JSONDecodeError:
+            parsed_definition = parse_yaml(field_definition)
+
+        if not isinstance(parsed_definition, dict):
+            raise ValueError("Field definition must be a dictionary/object")
+
+        schema = backends.context_schema.get_context_schema(execution_id)
+
+        if schema is None:
+            schema = {}
+
+        action = "updated" if field_name in schema else "created"
+
+        schema[field_name] = parsed_definition
+        backends.context_schema.save_context_schema(execution_id, schema)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_inject_context_schema_field",
+                "field_name": field_name,
+                "action": action,
+            },
+        )
+
+        return {
+            "success": True,
+            "field_name": field_name,
+            "action": action,
+            "message": f"Successfully {action} field '{field_name}' in context schema",
+        }
+
+    return soe_inject_context_schema_field

soe/builtin_tools/soe_inject_identity.py

@@ -0,0 +1,64 @@
+"""Built-in identity injection tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_inject_identity_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_inject_identity tool.
+
+    Args:
+        execution_id: ID to access identity data via backends
+        backends: Backend services to fetch/update identities
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_inject_identity function that can add/update identities
+    """
+
+    def soe_inject_identity(identity_name: str, system_prompt: str) -> Dict[str, Any]:
+        """
+        Add or update an identity definition.
+
+        Args:
+            identity_name: Name/key for the identity
+            system_prompt: The system prompt text for this identity
+
+        Returns:
+            Success confirmation with identity info and action taken
+        """
+        identities = backends.identity.get_identities(execution_id)
+
+        if identities is None:
+            identities = {}
+
+        action = "updated" if identity_name in identities else "created"
+
+        identities[identity_name] = system_prompt
+        backends.identity.save_identities(execution_id, identities)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_inject_identity",
+                "identity_name": identity_name,
+                "action": action,
+            },
+        )
+
+        return {
+            "success": True,
+            "identity_name": identity_name,
+            "action": action,
+            "message": f"Successfully {action} identity '{identity_name}'",
+        }
+
+    return soe_inject_identity

soe/builtin_tools/soe_remove_context_schema_field.py

@@ -0,0 +1,61 @@
+"""Built-in context schema field removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_context_schema_field_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_context_schema_field tool.
+
+    Args:
+        execution_id: ID to access context schema data via backends
+        backends: Backend services to fetch/update context schema
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_context_schema_field function
+    """
+
+    def soe_remove_context_schema_field(field_name: str) -> Dict[str, Any]:
+        """
+        Remove a field from the context schema.
+
+        Args:
+            field_name: Name of the field to remove
+
+        Returns:
+            Success confirmation with removed field info
+        """
+        schema = backends.context_schema.get_context_schema(execution_id)
+
+        if schema is None or field_name not in schema:
+            raise ValueError(
+                f"Field '{field_name}' not found in context schema"
+            )
+
+        del schema[field_name]
+        backends.context_schema.save_context_schema(execution_id, schema)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_context_schema_field",
+                "field_name": field_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "field_name": field_name,
+            "message": f"Successfully removed field '{field_name}' from context schema",
+        }
+
+    return soe_remove_context_schema_field

soe/builtin_tools/soe_remove_identity.py

@@ -0,0 +1,61 @@
+"""Built-in identity removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_identity_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_identity tool.
+
+    Args:
+        execution_id: ID to access identity data via backends
+        backends: Backend services to fetch/update identities
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_identity function that can remove identities
+    """
+
+    def soe_remove_identity(identity_name: str) -> Dict[str, Any]:
+        """
+        Remove an identity definition.
+
+        Args:
+            identity_name: Name of the identity to remove
+
+        Returns:
+            Success confirmation with removed identity info
+        """
+        identities = backends.identity.get_identities(execution_id)
+
+        if identities is None or identity_name not in identities:
+            raise ValueError(
+                f"Identity '{identity_name}' not found"
+            )
+
+        del identities[identity_name]
+        backends.identity.save_identities(execution_id, identities)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_identity",
+                "identity_name": identity_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "identity_name": identity_name,
+            "message": f"Successfully removed identity '{identity_name}'",
+        }
+
+    return soe_remove_identity

soe/builtin_tools/soe_update_context.py

@@ -5,6 +5,8 @@ Allows agents to write context fields dynamically.
 
 from typing import Any, Dict
 
+from ..lib.context_fields import set_field
+
 
 def create_soe_update_context_tool(backends, execution_id: str, tools_registry=None):
     """
@@ -41,9 +43,10 @@ def create_soe_update_context_tool(backends, execution_id: str, tools_registry=N
         if not filtered_updates:
             return {"status": "no valid updates (operational fields cannot be updated)"}
 
-        # Get current context and update
+        # Get current context and update using set_field for proper list wrapping
         context = backends.context.get_context(execution_id)
-        context.update(filtered_updates)
+        for field, value in filtered_updates.items():
+            set_field(context, field, value)
         backends.context.save_context(execution_id, context)
 
         return {

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