soe-ai 0.2.0b1__py3-none-any.whl

soe/nodes/lib/identity.py

@@ -0,0 +1,64 @@
+"""
+Shared identity utilities for LLM and Agent nodes.
+
+This module handles identity retrieval and system prompt generation
+for nodes that support identity-based persona/role configuration.
+
+Identities are stored per execution (main_execution_id) and define the initial
+system prompt that will be used when conversation history starts.
+
+Identity format is simple: identity_name -> system_prompt (string)
+Example:
+    assistant: "You are a helpful assistant."
+    coding_expert: "You are an expert programmer."
+"""
+
+from typing import Dict, Any, Optional
+from ...types import Backends
+
+
+def get_system_prompt_from_identity(
+    identity: Optional[str],
+    main_execution_id: str,
+    backends: Backends,
+) -> Optional[str]:
+    """
+    Get the system prompt for an identity.
+
+    Looks up the identity's system prompt from the identity backend using the
+    main_execution_id and identity key.
+
+    Args:
+        identity: The identity key (e.g., "assistant", "coding_assistant")
+        main_execution_id: Main execution ID for identity lookup
+        backends: Backend services
+
+    Returns:
+        System prompt string or None if not found
+    """
+    if not identity or not backends.identity:
+        return None
+
+    if hasattr(backends.identity, 'get_identity'):
+        return backends.identity.get_identity(main_execution_id, identity)
+
+    identities = backends.identity.get_identities(main_execution_id)
+    if not identities:
+        return None
+
+    return identities.get(identity)
+
+
+def format_system_prompt_for_history(system_prompt: Optional[str]) -> str:
+    """
+    Format the system prompt for inclusion in conversation history.
+
+    Args:
+        system_prompt: The system prompt string
+
+    Returns:
+        Formatted system prompt or empty string
+    """
+    if not system_prompt:
+        return ""
+    return f"[system]: {system_prompt}"

soe/nodes/lib/llm_resolver.py

@@ -0,0 +1,142 @@
+"""
+Shared LLM Resolver and Parser.
+
+Handles the orchestration of LLM calls, including:
+1. Parsing text responses into Pydantic models
+2. Removing thinking tags
+3. Extracting JSON from markdown
+4. Retrying on validation errors
+
+Used by LLM and Agent nodes.
+"""
+
+import json
+import re
+from typing import Type, Dict, Any, TypeVar
+from pydantic import BaseModel, ValidationError
+from ...types import CallLlm
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def resolve_llm_call(
+    call_llm: CallLlm,
+    input_data: BaseModel,
+    config: Dict[str, Any],
+    response_model: Type[T],
+    max_retries: int = 3,
+) -> T:
+    """
+    Execute the LLM call loop:
+    1. Convert input_data to JSON string
+    2. Augment with format instructions for response_model
+    3. Call LLM
+    4. Parse and Validate
+    5. Retry on failure
+    """
+    try:
+        prompt_base = input_data.model_dump_json()
+    except Exception as e:
+        raise ValueError(f"Failed to serialize input model: {e}")
+
+    instructions = _get_format_instructions(response_model)
+    current_prompt = f"{prompt_base}\n\n{instructions}"
+
+    last_error = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            response_text = call_llm(current_prompt, config)
+        except Exception as e:
+            raise e
+
+        try:
+            return _parse_response(response_text, response_model)
+        except (ValidationError, ValueError) as e:
+            last_error = e
+            if attempt == max_retries:
+                break
+
+            error_msg = _format_validation_error(e)
+            current_prompt += f"\n\nPrevious response: {response_text}{error_msg}"
+
+    raise Exception(f"Max retries ({max_retries}) exceeded. Last error: {last_error}")
+
+
+def _get_format_instructions(model: Type[BaseModel]) -> str:
+    """Generate instructions for JSON output based on the model schema."""
+    schema = model.model_json_schema()
+    return (
+        f"Respond ONLY with a valid JSON object matching this schema:\n"
+        f"{json.dumps(schema)}\n"
+        f"Do not return the schema itself. Return a JSON instance of the schema."
+    )
+
+
+def _format_validation_error(error: Exception) -> str:
+    """Format validation errors with specific field information."""
+    if isinstance(error, ValidationError):
+        field_errors = [
+            f"  - {'.'.join(str(loc) for loc in err['loc'])}: {err['msg']}"
+            for err in error.errors()
+        ]
+        return (
+            "\n\nValidation failed. Fix these fields:\n"
+            + "\n".join(field_errors)
+            + "\n\nRespond with valid JSON."
+        )
+    return f"\n\nJSON parse error: {error}. Output valid JSON."
+
+
+def _parse_response(text: str, model: Type[T]) -> T:
+    """
+    Parse text response into a Pydantic model.
+    Removes <think> tags and extracts JSON from markdown blocks if present.
+    """
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
+    json_str = _extract_json(text)
+    return model.model_validate_json(json_str)
+
+
+def _extract_json(text: str) -> str:
+    """Extract JSON from text, handling nested objects and arrays."""
+    text = text.strip()
+
+    match = re.search(r"```(?:json)?\s*([\[\{].*?[\]\}])\s*```", text, re.DOTALL)
+    if match:
+        return match.group(1)
+
+    for i, char in enumerate(text):
+        if char in "{[":
+            return _extract_balanced(text, i)
+    return text
+
+
+def _extract_balanced(text: str, start: int) -> str:
+    """Extract balanced JSON from start position."""
+    open_char = text[start]
+    close_char = "}" if open_char == "{" else "]"
+    depth = 0
+    in_string = False
+    escape = False
+
+    for i in range(start, len(text)):
+        c = text[i]
+        if escape:
+            escape = False
+            continue
+        if c == "\\":
+            escape = True
+            continue
+        if c == '"':
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if c == open_char:
+            depth += 1
+        elif c == close_char:
+            depth -= 1
+            if depth == 0:
+                return text[start:i + 1]
+    return text[start:]

soe/nodes/lib/output.py

@@ -0,0 +1,68 @@
+"""
+Shared LLM output utilities for LLM and Agent nodes.
+"""
+
+from typing import Dict, Any, List, Optional, Type
+from pydantic import BaseModel
+
+from .signals import has_jinja_conditions
+from ...lib.schema_validation import schema_to_root_model
+from ...lib.register_event import register_event
+from ...types import EventTypes
+
+
+def needs_llm_signal_selection(event_emissions: List[Dict[str, Any]]) -> bool:
+    """Check if LLM should select which signal to emit."""
+    if not event_emissions:
+        return False
+    if has_jinja_conditions(event_emissions):
+        return False
+
+    signal_count = sum(1 for e in event_emissions if e.get("signal_name"))
+    return signal_count > 1
+
+
+def get_signal_options(event_emissions: List[Dict[str, Any]]) -> Optional[List[Dict[str, str]]]:
+    """
+    Get signal options if LLM should select which signal to emit.
+
+    Returns list of {name, description} dicts if multiple signals available.
+    Uses 'condition' field as description (when it's plain text, not jinja).
+    Returns None if no selection needed (single signal, jinja conditions, or empty).
+    """
+    if needs_llm_signal_selection(event_emissions):
+        return [
+            {
+                "name": e.get("signal_name"),
+                "description": e.get("condition", ""),
+            }
+            for e in event_emissions
+            if e.get("signal_name")
+        ]
+    return None
+
+
+def get_output_model(
+    backends,
+    main_execution_id: str,
+    output_field: Optional[str]
+) -> Optional[Type[BaseModel]]:
+    """Get RootModel for flat output validation if schema exists."""
+    if not output_field or not backends.context_schema:
+        return None
+
+    schema = backends.context_schema.get_context_schema(main_execution_id)
+    if not schema or output_field not in schema:
+        register_event(
+            backends,
+            main_execution_id,
+            EventTypes.CONTEXT_WARNING,
+            {
+                "message": f"Output field '{output_field}' not found in context schema",
+                "output_field": output_field,
+            },
+        )
+        return None
+
+    field_def = schema.get(output_field)
+    return schema_to_root_model(field_def, f"{output_field.title()}Root")

soe/nodes/lib/response_builder.py

@@ -0,0 +1,91 @@
+"""
+Dynamic Pydantic response model builder.
+"""
+
+from typing import Type, Any, Optional, List, Dict, Literal
+from pydantic import RootModel
+from pydantic import BaseModel, Field, create_model
+from typing import Type, Any, Optional, List, Dict, Literal
+
+from pydantic import RootModel
+def build_response_model(
+    output_field: Optional[str] = None,
+    output_schema: Optional[Type[BaseModel]] = None,
+    signal_options: Optional[List[Dict[str, str]]] = None,
+) -> Type[BaseModel]:
+    """Dynamically build a Pydantic response model based on requirements."""
+    fields: Dict[str, Any] = {}
+
+    root_schema = None
+    if output_schema and isinstance(output_schema, type) and issubclass(output_schema, RootModel):
+        # Use RootModel directly if no signal selection is needed (standard case for single output)
+        if not signal_options or len(signal_options) <= 1:
+            return output_schema
+        root_schema = output_schema
+    if output_field:
+        if root_schema:
+            root_type = root_schema.model_fields["root"].annotation
+            fields[output_field] = (
+                root_type,
+                Field(..., description=f"The {output_field} value matching the expected schema")
+            )
+        else:
+            fields[output_field] = (
+                Any,
+                Field(..., description=f"The {output_field} value")
+            )
+    else:
+        fields["output"] = (
+            str,
+            Field(..., description="The final output/result")
+        )
+
+    if signal_options and len(signal_options) > 1:
+        signal_names = [s["name"] for s in signal_options]
+        signal_literal = Literal[tuple(signal_names)]
+
+        descriptions = []
+        for s in signal_options:
+            if s.get("description"):
+                descriptions.append(f"- {s['name']}: {s['description']}")
+            else:
+                descriptions.append(f"- {s['name']}")
+
+        desc_text = "Select the most appropriate signal:\n" + "\n".join(descriptions)
+
+        fields["selected_signal"] = (
+            signal_literal,
+            Field(..., description=desc_text)
+        )
+
+    model_name = "DynamicResponse"
+    if output_field:
+        model_name = f"{output_field.title()}Response"
+
+    return create_model(model_name, **fields)
+
+
+def extract_output_from_response(
+    response: BaseModel,
+    output_field: Optional[str],
+) -> Any:
+    """Extract the output value from a dynamic response model."""
+    if isinstance(response, RootModel):
+        value = response.root
+        if isinstance(value, BaseModel):
+            return value.model_dump()
+        return value
+    data = response.model_dump()
+    if output_field and output_field in data:
+        return data[output_field]
+    return data.get("output")
+
+
+def extract_signal_from_response(response: BaseModel) -> Optional[str]:
+    """
+    Extract the selected signal from a dynamic response model.
+    """
+    data = response.model_dump()
+    if isinstance(data, dict):
+        return data.get("selected_signal")
+    return None

soe/nodes/lib/signal_emission.py

@@ -0,0 +1,79 @@
+"""
+Shared signal emission utilities for LLM-based nodes.
+
+Provides common logic for emitting signals after node completion,
+handling both LLM-selected signals and jinja-conditioned emissions.
+"""
+
+from typing import Dict, List, Any, Optional, Protocol
+
+from ...types import BroadcastSignalsCaller, Backends, EventTypes
+from ...lib.register_event import register_event
+from .signals import has_jinja_conditions, handle_signal_emission
+
+
+class OperationalState(Protocol):
+    """Protocol for operational state objects that can emit signals."""
+    context: Dict[str, Any]
+    event_emissions: List[Dict[str, Any]]
+
+
+def handle_llm_failure(
+    failure_signal: Optional[str],
+    error_message: str,
+    node_type: str,
+    execution_id: str,
+    backends: Backends,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+) -> None:
+    """Handle LLM/Agent node failure by logging and emitting failure signal or raising."""
+    register_event(
+        backends, execution_id, EventTypes.NODE_ERROR,
+        {"node_type": node_type, "error": error_message}
+    )
+
+    if failure_signal:
+        broadcast_signals_caller(execution_id, [failure_signal])
+    else:
+        raise RuntimeError(error_message)
+
+
+def emit_completion_signals(
+    selected_signal: Optional[str],
+    node_config: Dict[str, Any],
+    operational_state: OperationalState,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+    execution_id: str,
+) -> None:
+    """
+    Emit signals after successful node completion.
+
+    Signal emission priority:
+    1. LLM-selected signal (when multiple signals with plain-text conditions)
+    2. Jinja-conditioned emissions (evaluate {{ }} templates)
+    3. Single unconditional signal (emit it)
+    4. Multiple signals without selection → error (shouldn't happen)
+
+    The 'condition' field has dual purpose:
+    - Plain text: used as description for LLM signal selection
+    - Jinja template ({{ }}): evaluated to determine if signal should emit
+    """
+    if selected_signal:
+        broadcast_signals_caller(execution_id, [selected_signal])
+    elif operational_state.event_emissions:
+        if has_jinja_conditions(operational_state.event_emissions):
+            handle_signal_emission(
+                [], node_config, operational_state.context,
+                broadcast_signals_caller, execution_id
+            )
+        else:
+            signals = [
+                e.get("signal_name") for e in operational_state.event_emissions
+                if e.get("signal_name")
+            ]
+            if len(signals) == 1:
+                broadcast_signals_caller(execution_id, signals)
+            elif len(signals) > 1:
+                raise RuntimeError(
+                    f"Multiple signals defined but no selection made: {signals}"
+                )

soe/nodes/lib/signals.py

@@ -0,0 +1,54 @@
+"""
+Signal handling utilities for LLM-based nodes.
+"""
+
+import re
+from typing import Dict, List, Any, Callable
+
+from .conditions import evaluate_conditions
+from ...lib.context_fields import get_field
+
+
+def has_jinja_conditions(event_emissions: List[Dict[str, Any]]) -> bool:
+    """Check if any event emission has jinja template conditions."""
+    return any(
+        e.get("condition") and re.search(r"\{\{.*\}\}", e.get("condition", ""))
+        for e in event_emissions
+    )
+
+
+def _evaluate_emission_conditions(
+    emitted_signals: List[str], node_config: Dict[str, Any], context: Dict[str, Any]
+) -> List[str]:
+    """Evaluate jinja conditions and filter signals against allowed emissions."""
+    event_emissions = node_config.get("event_emissions", [])
+
+    has_jinja = any(
+        e.get("condition") and re.search(r"\{\{.*\}\}", e.get("condition", ""))
+        for e in event_emissions
+    )
+
+    if not has_jinja:
+        allowed = {e.get("signal_name") for e in event_emissions if e.get("signal_name")}
+        return [s for s in emitted_signals if s in allowed]
+
+    unwrapped = {k: get_field(context, k) for k in context if not k.startswith("__")}
+    for k, v in context.items():
+        if k.startswith("__"):
+            unwrapped[k] = v
+    return evaluate_conditions(event_emissions, {"context": unwrapped}, context)
+
+
+def handle_signal_emission(
+    emitted_signals: List[str],
+    node_config: Dict[str, Any],
+    context: Dict[str, Any],
+    broadcast_signals_caller: Callable[[str, List[str]], None],
+    execution_id: str,
+) -> None:
+    """Evaluate signal conditions and emit via broadcast_signals_caller."""
+    filtered_signals = _evaluate_emission_conditions(
+        emitted_signals, node_config, context
+    )
+    if filtered_signals:
+        broadcast_signals_caller(execution_id, filtered_signals)

soe/nodes/lib/tools.py

@@ -0,0 +1,100 @@
+"""
+Shared tool utilities for nodes that work with callable tools.
+
+Used by Agent node and Tool node for introspection and registry lookup.
+"""
+
+import inspect
+from typing import Dict, Any, Callable, Type, Optional, Union
+from pydantic import BaseModel, create_model
+
+from ...types import Backends
+from ...builtin_tools import get_builtin_tool_factory
+
+
+DEFAULT_MAX_RETRIES = 0
+
+
+def get_tool_signature(tool_func: Callable) -> str:
+    """Extract function signature and docstring for prompt."""
+    sig = inspect.signature(tool_func)
+    params = []
+    for name, param in sig.parameters.items():
+        param_type = (
+            param.annotation if param.annotation != inspect.Parameter.empty else "Any"
+        )
+        params.append(f"{name}: {param_type}")
+
+    func_name = tool_func.__name__
+    params_str = ", ".join(params)
+    doc = inspect.getdoc(tool_func) or "No description"
+
+    return f"{func_name}({params_str})\n  {doc}"
+
+
+def create_tool_schema(tool_func: Callable) -> Type[BaseModel]:
+    """Dynamically create a Pydantic model from a function signature."""
+    sig = inspect.signature(tool_func)
+    fields: Dict[str, Any] = {}
+
+    for name, param in sig.parameters.items():
+        annotation = param.annotation
+        if annotation == inspect.Parameter.empty:
+            annotation = Any
+
+        default = param.default
+        if default == inspect.Parameter.empty:
+            field_info = (annotation, ...)
+        else:
+            field_info = (annotation, default)
+
+        fields[name] = field_info
+
+    return create_model(f"{tool_func.__name__}Schema", **fields)
+
+
+def _normalize_registry_entry(
+    entry: Union[Callable, Dict[str, Any]],
+) -> tuple[Callable, int, Optional[str], bool]:
+    """Normalize a tool registry entry to extract function and configuration."""
+    if callable(entry):
+        return entry, DEFAULT_MAX_RETRIES, None, False
+
+    return (
+        entry["function"],
+        entry.get("max_retries", DEFAULT_MAX_RETRIES),
+        entry.get("failure_signal"),
+        entry.get("process_accumulated", False),
+    )
+
+
+def get_tool_from_registry(
+    tool_name: str,
+    tools_registry: Dict[str, Any],
+    execution_id: str,
+    backends: Backends,
+) -> tuple[Callable, int, Optional[str], bool]:
+    """
+    Get tool function from registry or builtin tools, normalizing the entry.
+
+    Caches builtin tools in registry after creation.
+
+    Returns:
+        Tuple of (tool_function, max_retries, failure_signal, process_accumulated)
+    """
+    entry = tools_registry.get(tool_name)
+
+    if entry is not None:
+        return _normalize_registry_entry(entry)
+
+    builtin_factory = get_builtin_tool_factory(tool_name)
+    if builtin_factory:
+        tool_function = builtin_factory(
+            execution_id=execution_id,
+            backends=backends,
+            tools_registry=tools_registry,
+        )
+        tools_registry[tool_name] = {"function": tool_function, "max_retries": DEFAULT_MAX_RETRIES}
+        return tool_function, DEFAULT_MAX_RETRIES, None, False
+
+    raise ValueError(f"Tool '{tool_name}' not found in registry or builtins")

soe/nodes/llm/__init__.py

@@ -0,0 +1,7 @@
+"""
+LLM node - Simple direct LLM call with conversation history support
+"""
+
+from .factory import create_llm_node_caller
+
+__all__ = ["create_llm_node_caller"]