soprano-sdk 0.1.94__py3-none-any.whl → 0.1.96__py3-none-any.whl

soprano_sdk/tools.py

@@ -0,0 +1,219 @@
+"""
+Workflow Tools - Wraps workflows as callable tools for agent frameworks
+"""
+
+import uuid
+from typing import Optional, Dict, Any
+
+from langgraph.graph.state import CompiledStateGraph
+
+from .utils.logger import logger
+
+from langfuse.langchain import CallbackHandler
+
+from .core.engine import load_workflow
+
+
+class WorkflowTool:
+    """Wraps a conversational workflow as a tool for agent orchestration
+
+    This allows workflows to be used as tools in LangGraph, CrewAI, or other
+    agent frameworks. The supervisor agent can decide which workflow to invoke
+    based on user intent.
+    """
+
+    def __init__(
+        self,
+        yaml_path: str,
+        name: str,
+        description: str,
+        checkpointer=None,
+        config: Optional[Dict]=None
+    ):
+        """Initialize workflow tool
+
+        Args:
+            yaml_path: Path to workflow YAML file
+            name: Tool name (used by agents to reference this tool)
+            description: Tool description (helps agent decide when to use it)
+            checkpointer: Optional checkpointer for persistence
+        """
+        self.yaml_path = yaml_path
+        self.name = name
+        self.description = description
+        self.checkpointer = checkpointer
+
+        # Load workflow
+        self.graph, self.engine = load_workflow(yaml_path, checkpointer=checkpointer, config=config)
+
+    def execute(
+        self,
+        thread_id: Optional[str] = None,
+        user_message: Optional[str] = None,
+        initial_context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Execute the workflow with automatic state detection
+
+        Checks workflow state and automatically resumes if interrupted,
+        or starts fresh if not started/completed.
+
+        Args:
+            thread_id: Thread ID for state tracking
+            user_message: User's message (used for resume if workflow is interrupted)
+            initial_context: Context to inject for fresh starts (e.g., {"order_id": "123"})
+
+        Returns:
+            Final outcome message or interrupt prompt
+        """
+        from langgraph.types import Command
+        from soprano_sdk.utils.tracing import trace_workflow_execution
+        
+        if thread_id is None:
+            thread_id = str(uuid.uuid4())
+        
+        with trace_workflow_execution(
+            workflow_name=self.engine.workflow_name,
+            thread_id=thread_id,
+            has_initial_context=initial_context is not None
+        ) as span:
+            callback_handler = CallbackHandler()
+            config = {"configurable": {"thread_id": thread_id}, "callbacks": [callback_handler]}
+            
+            update_context = {}
+            engine_context_data = {}
+            for key, value in initial_context.items():
+                if key in self.engine.collect_input_fields:
+                    engine_context_data[key] = value
+                    continue
+                if  value:
+                    update_context[key] = value
+
+            if engine_context_data:
+                self.engine.update_context(engine_context_data)
+                span.add_event("context.updated", {"fields": list(engine_context_data.keys())})
+
+            state = self.graph.get_state(config)
+
+            if state.next:
+                # Workflow is interrupted and waiting for input
+                span.set_attribute("workflow.resumed", True)
+                logger.info(f"[WorkflowTool] Resuming interrupted workflow {self.name} (thread: {thread_id})")
+                result = self.graph.invoke(
+                    Command(resume=user_message or "", update=update_context),
+                    config=config
+                )
+            else:
+                # Workflow is fresh or completed, start/restart
+                span.set_attribute("workflow.resumed", False)
+                logger.info(f"[WorkflowTool] Starting fresh workflow {self.name} (thread: {thread_id})")
+                result = self.graph.invoke(update_context, config=config)
+            
+            final_state = self.graph.get_state(config)
+            if not final_state.next and self.checkpointer:
+                self.checkpointer.delete_thread(thread_id)
+
+            # If workflow needs user input, return structured interrupt data
+            if "__interrupt__" in result and result["__interrupt__"]:
+                span.set_attribute("workflow.status", "interrupted")
+                prompt = result["__interrupt__"][0].value
+                return f"__WORKFLOW_INTERRUPT__|{thread_id}|{self.name}|{prompt}"
+
+            # Workflow completed without interrupting
+            span.set_attribute("workflow.status", "completed")
+            return self.engine.get_outcome_message(result)
+
+    def resume(self, thread_id: str, user_message: str) -> str:
+        """Resume an interrupted workflow with user input
+
+        Args:
+            thread_id: Thread ID of the interrupted workflow
+            user_message: User's response to the interrupt prompt
+
+        Returns:
+            Either another interrupt prompt or final outcome message
+        """
+        from langgraph.types import Command
+
+        config = {"configurable": {"thread_id": thread_id}}
+        result = self.graph.invoke(Command(resume=user_message), config=config)
+
+        # Check if workflow needs more input
+        if "__interrupt__" in result and result["__interrupt__"]:
+            prompt = result["__interrupt__"][0].value
+            return f"__WORKFLOW_INTERRUPT__|{thread_id}|{self.name}|{prompt}"
+
+        # Workflow completed
+        return self.engine.get_outcome_message(result)
+
+    def to_langchain_tool(self):
+        """Convert to LangChain tool format
+
+        Returns:
+            LangChain Tool that can be used by LangGraph agents
+        """
+        from langchain_core.tools import tool
+
+        # Create function with proper name and docstring
+        def workflow_tool(context: str = "") -> str:
+            """Execute workflow with optional context"""
+            # Parse context if provided (simple key=value format)
+            initial_context = {}
+            if context:
+                for pair in context.split(","):
+                    if "=" in pair:
+                        key, value = pair.split("=", 1)
+                        initial_context[key.strip()] = value.strip()
+
+            return self.execute(initial_context=initial_context)
+
+        # Set function name and docstring from tool definition
+        workflow_tool.__name__ = self.name
+        workflow_tool.__doc__ = self.description
+
+        # Decorate and return
+        return tool(workflow_tool)
+
+    def to_crewai_tool(self):
+        """Convert to CrewAI tool format
+
+        Returns:
+            CrewAI BaseTool that can be used by CrewAI agents
+        """
+        from crewai.tools import BaseTool
+
+        # Capture self in closure
+        workflow_tool = self
+
+        # Create a custom CrewAI tool class
+        class WorkflowCrewAITool(BaseTool):
+            name: str = workflow_tool.name
+            description: str = workflow_tool.description
+
+            def _run(self, context: str = "") -> str:
+                """Execute workflow with optional context"""
+                # Parse context if provided (simple key=value format)
+                initial_context = {}
+                if context:
+                    for pair in context.split(","):
+                        if "=" in pair:
+                            key, value = pair.split("=", 1)
+                            initial_context[key.strip()] = value.strip()
+
+                return workflow_tool.execute(initial_context=initial_context)
+
+        # Return an instance of the tool
+        return WorkflowCrewAITool()
+
+    def get_mermaid_diagram(self) -> str:
+        return self.graph.get_graph().draw_mermaid()
+
+    def __call__(self, **kwargs) -> str:
+        """Allow tool to be called directly
+
+        Args:
+            **kwargs: Context to pass to workflow
+
+        Returns:
+            Workflow result
+        """
+        return self.execute(initial_context=kwargs)

soprano_sdk/utils/function.py

@@ -0,0 +1,35 @@
+import importlib
+from typing import Callable, Dict
+
+from ..utils.logger import logger
+
+
+class FunctionRepository:
+    def __init__(self):
+        self._cache: Dict[str, Callable] = {}
+
+    def load(self, function_path: str) -> Callable:
+        if function_path in self._cache:
+            logger.info(f"Loading function from cache: {function_path}")
+            return self._cache[function_path]
+
+        logger.info(f"Loading function: {function_path}")
+
+        try:
+            module_name, function_name = function_path.rsplit('.', 1)
+            module = importlib.import_module(module_name)
+
+            if not hasattr(module, function_name):
+                raise RuntimeError(f"Module '{module_name}' has no function '{function_name}'")
+
+            func = getattr(module, function_name)
+
+            if not callable(func):
+                raise RuntimeError(f"'{function_path}' is not callable (type: {type(func).__name__})")
+
+            self._cache[function_path] = func
+            logger.info(f"Successfully loaded and cached function: {function_path}")
+            return func
+
+        except Exception as e:
+            raise RuntimeError(f"Unexpected error loading function '{function_path}': {e}")

soprano_sdk/utils/logger.py

@@ -0,0 +1,6 @@
+import logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger()

soprano_sdk/utils/template.py

@@ -0,0 +1,27 @@
+from typing import Any
+from jinja2 import Template, TemplateError, UndefinedError
+import ast
+
+
+def get_nested_value(data: Any, path: str) -> Any:
+    if not path:
+        return data
+
+    if not path.strip().startswith('{{'):
+        template_str = f'{{{{ {path} }}}}'
+    else:
+        template_str = path
+
+    try:
+        template = Template(template_str)
+        result = template.render(result=data)
+        
+        if not result or result == '':
+            return None
+            
+        try:
+            return ast.literal_eval(result)
+        except (ValueError, SyntaxError):
+            return result
+    except (TemplateError, UndefinedError):
+        return None

soprano_sdk/utils/tool.py

@@ -0,0 +1,60 @@
+import importlib
+from typing import Dict, Any
+import functools
+
+from .logger import logger
+
+TYPE_MAP = {
+    "string": str,
+    "number": float,
+    "integer": int,
+    "boolean": bool,
+    "array": list,
+    "object": dict
+}
+
+def wrap_state(state: Dict[str, Any]):
+    def wrapper(func):
+
+        @functools.wraps(func)
+        def inner(*args, **kwargs):
+            return func(*args, **kwargs, **state)
+        return inner
+    return wrapper
+
+
+class ToolRepository:
+    def __init__(self, tool_config):
+        self._cache: Dict[str, Any] = {}
+        self.tool_config = tool_config
+
+    def load(self, tool_name, state):
+        if tool_name in self._cache:
+            logger.info(f"Tool '{tool_name}' found in cache")
+            return self._cache[tool_name]
+
+        tool_info = next((t for t in self.tool_config.get('tools') if t['name']==tool_name), None)
+        if not tool_info:
+            raise RuntimeError(f"Tool '{tool_name}' not found in tool config")
+
+        tool_description = tool_info.get("description", "")
+        function_path = tool_info.get("callable")
+
+        module_name, function_name = function_path.rsplit('.', 1)
+
+        try:
+            module = importlib.import_module(module_name)
+        except ImportError as e:
+            raise RuntimeError(f"Failed to import module '{module_name}': {e}")
+
+        if not hasattr(module, function_name):
+            raise RuntimeError(f"Module '{module_name}' has no function '{function_name}'")
+
+        func = getattr(module, function_name)
+
+        if not callable(func):
+            raise RuntimeError(f"'{function_path}' is not callable (type: {type(func).__name__})")
+
+        self._cache[function_path] = (tool_name, tool_description, func)
+        logger.info(f"Successfully loaded and cached function: {function_path}")
+        return tool_name, tool_description, wrap_state(state)(func)

soprano_sdk/utils/tracing.py

@@ -0,0 +1,71 @@
+from opentelemetry import trace
+from typing import Optional, Dict, Any
+from contextlib import contextmanager
+import logging
+
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.trace import Link
+
+from ..utils.logger import logger
+
+tracer = trace.get_tracer(__name__)
+propagator = TraceContextTextMapPropagator()
+
+
+@contextmanager
+def trace_node_execution(node_id: str, node_type: str, **attributes):
+    span_attributes = {
+        "node.id": node_id,
+        "node.type": node_type,
+    }
+    span_attributes.update(attributes)
+    
+    with tracer.start_as_current_span(
+        f"node.{node_id}",
+        attributes=span_attributes
+    ) as span:
+        logger.info(f"Started tracing node: {node_id} ({node_type})")
+        yield span
+        logger.info(f"Finished tracing node: {node_id}")
+
+
+@contextmanager
+def trace_agent_invocation(agent_name: str, model: str, **attributes):
+    span_attributes = {
+        "agent.name": agent_name,
+        "agent.model": model,
+    }
+    span_attributes.update(attributes)
+    
+    with tracer.start_as_current_span(
+        "agent.invoke",
+        attributes=span_attributes
+    ) as span:
+        yield span
+
+
+@contextmanager
+def trace_workflow_execution(workflow_name: str, **attributes):
+    span_attributes = {
+        "workflow.name": workflow_name,
+    }
+    span_attributes.update(attributes)
+    
+    with tracer.start_as_current_span(
+        "workflow.execute",
+        attributes=span_attributes
+    ) as span:
+        yield span
+
+
+def add_node_result(span, field: str, value: Any, status: str):
+    if span and span.is_recording():
+        span.set_attribute(f"field.{field}", str(value) if value is not None else "None")
+        span.set_attribute("node.status", status)
+
+
+def add_agent_result(span, response_length: int, tool_calls: int = 0):
+    if span and span.is_recording():
+        span.set_attribute("agent.response.length", response_length)
+        if tool_calls > 0:
+            span.set_attribute("agent.tool_calls.count", tool_calls)

soprano_sdk/validation/__init__.py

@@ -0,0 +1,13 @@
+"""
+Workflow validation module
+"""
+
+from .validator import WorkflowValidator, ValidationResult, validate_workflow
+from .schema import WORKFLOW_SCHEMA
+
+__all__ = [
+    'WorkflowValidator',
+    'ValidationResult',
+    'validate_workflow',
+    'WORKFLOW_SCHEMA',
+]