soe-ai 0.1.3__tar.gz → 0.2.0b1__tar.gz

{soe_ai-0.1.3 → soe_ai-0.2.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soe-ai
-Version: 0.1.3
+Version: 0.2.0b1
 Summary: Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine
 Author-email: Pedro Garcia <pgarcia14180@gmail.com>
 License-Expression: MIT

{soe_ai-0.1.3 → soe_ai-0.2.0b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soe-ai"
-version = "0.1.3"
+version = "0.2.0b1"
 description = "Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine"
 readme = "README.md"
 requires-python = ">=3.8"

{soe_ai-0.1.3 → soe_ai-0.2.0b1}/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_ai-0.2.0b1/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_ai-0.2.0b1/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_ai-0.2.0b1/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_ai-0.2.0b1/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_ai-0.2.0b1/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_ai-0.2.0b1/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_ai-0.2.0b1/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