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

soprano_sdk/__init__.py

@@ -0,0 +1,10 @@
+from .core.engine import WorkflowEngine, load_workflow
+from .tools import WorkflowTool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WorkflowEngine",
+    "load_workflow",
+    "WorkflowTool",
+]

soprano_sdk/agents/__init__.py

@@ -0,0 +1,30 @@
+"""Agent module for managing different agent frameworks."""
+
+from .factory import (
+    AgentAdapter,
+    AgentCreator,
+    AgentFactory,
+    LangGraphAgentAdapter,
+    LangGraphAgentCreator,
+    CrewAIAgentAdapter,
+    CrewAIAgentCreator,
+    AgnoAgentAdapter,
+    AgnoAgentCreator,
+    PydanticAIAgentAdapter,
+    PydanticAIAgentCreator,
+)
+
+__all__ = [
+    "AgentAdapter",
+    "AgentCreator",
+    "AgentFactory",
+    "LangGraphAgentAdapter",
+    "LangGraphAgentCreator",
+    "CrewAIAgentAdapter",
+    "CrewAIAgentCreator",
+    "AgnoAgentAdapter",
+    "AgnoAgentCreator",
+    "PydanticAIAgentAdapter",
+    "PydanticAIAgentCreator",
+]
+

soprano_sdk/agents/adaptor.py

@@ -0,0 +1,91 @@
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+from langgraph.graph.state import CompiledStateGraph
+from agno.agent import Agent as AgnoAgent
+from pydantic import BaseModel
+from pydantic_ai.agent import Agent as PydanticAIAgent
+from crewai.agent import Agent as CrewAIAgent
+from ..utils.logger import logger
+
+class AgentAdapter(ABC):
+    
+    @abstractmethod
+    def invoke(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        pass
+
+
+class LangGraphAgentAdapter(AgentAdapter):
+    
+    def __init__(self, agent: CompiledStateGraph):
+        self.agent = agent
+    
+    def invoke(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        logger.info("Invoking LangGraph agent with messages")
+        response = self.agent.invoke({"messages": messages})
+        
+        if structured_response := response.get('structured_response'):
+            return structured_response.model_dump()
+        
+        if not response or "messages" not in response:
+            raise ValueError("Agent response missing 'messages'")
+        
+        response_messages = response.get("messages")
+        if not response_messages:
+            raise ValueError("Agent response 'messages' list is empty")
+        
+        return response_messages[-1].content
+
+
+class CrewAIAgentAdapter(AgentAdapter):
+    
+    def __init__(self, agent: CrewAIAgent, output_schema: BaseModel):
+        self.agent = agent
+        self.output_schema=output_schema
+    
+    def invoke(self, messages: List[Dict[str, str]]) -> Any:
+        try:
+            logger.info("Invoking LangGraph agent with messages")
+            result = self.agent.kickoff(messages, response_format=self.output_schema)
+
+            if structured_response := getattr(result, 'pydantic', None) :
+                return structured_response.model_dump()
+
+            if agent_response := getattr(result, 'raw', None) :
+                return agent_response
+            
+            return str(result)
+        except Exception as e:
+            raise RuntimeError(f"CrewAI agent invocation failed: {e}")
+
+
+class AgnoAgentAdapter(AgentAdapter):
+    
+    def __init__(self, agent: AgnoAgent):
+        self.agent = agent
+    
+    def invoke(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        try:
+            logger.info("Invoking LangGraph agent with messages")
+            response = self.agent.run(messages)
+            agent_response = response.content if hasattr(response, 'content') else str(response)
+            
+            return agent_response
+        except Exception as e:
+            raise RuntimeError(f"Agno agent invocation failed: {e}")
+
+
+class PydanticAIAgentAdapter(AgentAdapter):
+    
+    def __init__(self, agent: PydanticAIAgent):
+        self.agent = agent
+    
+    def invoke(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        try:
+            logger.info("Invoking LangGraph agent with messages")
+            result = self.agent.run_sync(messages)
+            agent_response = result.output if hasattr(result, 'output') else str(result)
+            
+            return agent_response
+        except Exception as e:
+            raise RuntimeError(f"Pydantic-AI agent invocation failed: {e}")

soprano_sdk/agents/factory.py

@@ -0,0 +1,228 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Literal, Tuple, Callable
+
+from agno.models.openai import OpenAIChat
+from crewai import LLM
+from langchain_openai import ChatOpenAI
+from pydantic import SecretStr, BaseModel
+from typing import Optional
+
+from .adaptor import (
+    AgentAdapter,
+    LangGraphAgentAdapter,
+    CrewAIAgentAdapter,
+    AgnoAgentAdapter,
+    PydanticAIAgentAdapter
+)
+
+
+def get_model(config: Dict[str, Any], framework: Literal['langgraph', 'crewai', 'agno', 'pydantic-ai'] = "langgraph", output_schema: Optional[BaseModel] = None, tools: Optional[List] = None):
+    errors = []
+    
+    model_name: str = config.get("model_name", "")
+    if not model_name:
+        errors.append("Model name is required in model_config")
+    
+    base_url = config.get("base_url")
+    if not base_url:
+        errors.append("Base url for model is required in model_config")
+    
+    api_key = config.get("api_key", "")
+    if not api_key:
+        if auth_callback := config.get("auth_callback"):
+            api_key = auth_callback()
+        if not api_key:
+            errors.append("API key/Auth callback for model is required in model_config")
+    
+    if errors:
+        raise ValueError("; ".join(errors))
+    
+    if framework == "agno" :
+        return OpenAIChat(
+            id=model_name,
+            api_key=api_key,
+            base_url=base_url
+        )
+
+    if framework == "crewai" :
+        return LLM(
+            api_key=api_key,
+            model=f"openai/{model_name}",
+            base_url=base_url,
+            temperature=0.1,
+            top_p=0.7
+        )
+
+    llm = ChatOpenAI(
+        model=model_name,
+        api_key=SecretStr(api_key),
+        base_url=base_url,
+    )
+    
+    if output_schema:
+        return llm.with_structured_output(output_schema)
+
+    if tools:
+        llm = llm.bind_tools(tools)
+
+    return llm
+
+
+class AgentCreator(ABC):
+    @abstractmethod
+    def create_agent(
+        self,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Any],
+        system_prompt: str,
+        structured_output_model: Any = None
+    ) -> AgentAdapter:
+        pass
+
+
+class LangGraphAgentCreator(AgentCreator):
+    def create_agent(
+        self,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Any],
+        system_prompt: str,
+        structured_output_model: Any = None,
+    ) -> LangGraphAgentAdapter:
+        from langchain.agents import create_agent
+        from langchain.tools import tool
+        from langchain.agents.structured_output import ProviderStrategy
+
+        tools = [tool(tool_name, description=description)(tool_callable) for tool_name, description, tool_callable in tools]
+
+        output_parser = None
+        if structured_output_model:
+            output_parser = ProviderStrategy(structured_output_model)
+
+        agent = create_agent(
+            name=name,
+            model=get_model(model_config, 'langgraph', tools=tools),
+            tools=tools,
+            system_prompt=system_prompt,
+            response_format=output_parser
+        )
+        return LangGraphAgentAdapter(agent)
+
+
+class CrewAIAgentCreator(AgentCreator):
+    def create_agent(
+        self,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Any],
+        system_prompt: str,
+        structured_output_model: Any = None
+    ) -> CrewAIAgentAdapter:
+        from crewai.agent import Agent
+        from crewai.tools import tool
+
+        def create_crewai_tool(tool_name: str, description: str, tool_callable: Callable) -> Any:
+            tool_callable.__doc__ = description
+            return tool(tool_name)(tool_callable)
+        
+        tools = [create_crewai_tool(tn, desc, tc) for tn, desc, tc in tools]
+
+        agent = Agent(
+            role=name,
+            backstory=system_prompt,
+            goal="Collect the required data from user messages using the available tools.",
+            tools=tools,
+            llm=get_model(model_config, 'crewai'),
+            max_retry_limit=2
+        )
+        
+        return CrewAIAgentAdapter(agent, output_schema=structured_output_model)
+
+
+class AgnoAgentCreator(AgentCreator):
+    def create_agent(
+        self,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Any],
+        system_prompt: str,
+        structured_output_model: Any = None
+    ) -> AgnoAgentAdapter:
+        from agno.agent import Agent
+        from agno.tools import tool
+
+        tools = [tool(name=tool_name, description=description)(tool_callable) for tool_name, description, tool_callable in tools]
+
+        agent = Agent(
+            name=name,
+            model=get_model(model_config, 'agno'),
+            tools=tools,
+            instructions=[system_prompt]
+        )
+        
+        return AgnoAgentAdapter(agent)
+
+
+class PydanticAIAgentCreator(AgentCreator):
+    def create_agent(
+        self,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Tuple[str, str, Callable]],
+        system_prompt: str,
+        structured_output_model: Any = None
+    ) -> PydanticAIAgentAdapter:
+        from pydantic_ai import Agent
+
+        agent = Agent(
+            model=get_model(model_config, 'pydantic-ai'),
+            system_prompt=system_prompt,
+        )
+
+        for tool_name, description, tool_callable in tools:
+            agent.tool(name=tool_name, description=description)(tool_callable)
+
+        return PydanticAIAgentAdapter(agent)
+
+
+class AgentFactory:
+    _CREATORS = {
+        "langgraph": LangGraphAgentCreator,
+        "crewai": CrewAIAgentCreator,
+        "agno": AgnoAgentCreator,
+        "pydantic-ai": PydanticAIAgentCreator,
+    }
+    
+    @classmethod
+    def get_creator(cls, framework: str) -> AgentCreator:
+        framework_lower = framework.lower()
+        
+        if framework_lower not in cls._CREATORS:
+            supported = ", ".join(cls._CREATORS.keys())
+            raise ValueError(
+                f"Unsupported agent framework: '{framework}'. "
+                f"Supported frameworks: {supported}"
+            )
+        
+        creator_class = cls._CREATORS[framework_lower]
+        return creator_class()
+    
+    @classmethod
+    def create_agent(
+        cls,
+        framework: str,
+        name: str,
+        model_config: Dict[str, Any],
+        tools: List[Any],
+        system_prompt: str,
+        structured_output_model: Any
+    ) -> Any:
+        creator = cls.get_creator(framework)
+        return creator.create_agent(
+            name=name,
+            model_config=model_config,
+            tools=tools,
+            system_prompt=system_prompt,
+            structured_output_model=structured_output_model
+        )

soprano_sdk/agents/structured_output.py

@@ -0,0 +1,97 @@
+from typing import Any, Dict, List, Optional, Type
+from pydantic import BaseModel, Field, create_model
+
+
+TYPE_MAP = {
+    "text": str,
+    "number": int,
+    "double": float,
+    "boolean": bool,
+    "list": list,
+    "dict": dict,
+}
+
+
+def create_structured_output_model(
+    fields: List[Dict[str, Any]],
+    model_name: str = "StructuredOutput",
+    needs_intent_change: bool = False,
+) -> Type[BaseModel]:
+    if not fields:
+        raise ValueError("At least one field definition is required")
+    
+    field_definitions = {"bot_response": (Optional[str], Field(None, description="bot response for the user query"))}
+
+    if needs_intent_change:
+        field_definitions["intent_change"] = (Optional[str], Field(None, description="node name for handling new intent"))
+
+    for field_def in fields:
+        field_name = field_def.get("name")
+        field_type = field_def.get("type")
+        field_description = field_def.get("description", "")
+        is_required = field_def.get("required", True)
+        
+        if not field_name:
+            raise ValueError("Field definition missing 'name'")
+        
+        if not field_type:
+            raise ValueError(f"Field '{field_name}' missing 'type'")
+        
+        python_type = TYPE_MAP.get(field_type)
+        if python_type is None:
+            raise ValueError(
+                f"Unknown type '{field_type}' for field '{field_name}'. "
+                f"Supported types: {list(TYPE_MAP.keys())}"
+            )
+        
+        if is_required:
+            field_definitions[field_name] = (
+                python_type,
+                Field(..., description=field_description)
+            )
+        else:
+            python_type = Optional[python_type]
+            field_definitions[field_name] = (
+                python_type,
+                Field(default=None, description=field_description)
+            )
+    
+    try:
+        model = create_model(model_name, **field_definitions)
+        return model
+    except Exception as e:
+        raise ValueError(f"Failed to create model '{model_name}': {e}")
+
+
+def validate_field_definitions(fields: List[Dict[str, Any]]) -> bool:
+    if not isinstance(fields, list):
+        raise ValueError("Field definitions must be a list")
+    
+    if not fields:
+        raise ValueError("At least one field definition is required")
+    
+    field_names = set()
+    
+    for i, field_def in enumerate(fields):
+        if not isinstance(field_def, dict):
+            raise ValueError(f"Field definition at index {i} must be a dictionary")
+        
+        required_keys = ["name", "type", "description"]
+        for key in required_keys:
+            if key not in field_def:
+                raise ValueError(f"Field definition at index {i} missing required key '{key}'")
+        
+        field_name = field_def["name"]
+        
+        if field_name in field_names:
+            raise ValueError(f"Duplicate field name '{field_name}' found")
+        field_names.add(field_name)
+        
+        field_type = field_def["type"]
+        if field_type not in TYPE_MAP:
+            raise ValueError(
+                f"Invalid type '{field_type}' for field '{field_name}'. "
+                f"Supported types: {list(TYPE_MAP.keys())}"
+            )
+    
+    return True

soprano_sdk/core/constants.py

@@ -0,0 +1,59 @@
+from enum import Enum
+
+
+class WorkflowKeys:
+    STEP_ID = '_step_id'
+    STATUS = '_status'
+    OUTCOME_ID = '_outcome_id'
+    MESSAGES = '_messages'
+    CONVERSATIONS = '_conversations'
+    STATE_HISTORY = '_state_history'
+    COLLECTOR_NODES = '_collector_nodes'
+    ATTEMPT_COUNTS = '_attempt_counts'
+    NODE_EXECUTION_ORDER = '_node_execution_order'
+    NODE_FIELD_MAP = '_node_field_map'
+    COMPUTED_FIELDS = '_computed_fields'
+    ERROR = 'error'
+
+
+class ActionType(Enum):
+    COLLECT_INPUT_WITH_AGENT = 'collect_input_with_agent'
+    CALL_FUNCTION = 'call_function'
+
+
+class DataType(Enum):
+    TEXT = 'text'
+    NUMBER = 'number'
+    DOUBLE = 'double'
+    BOOLEAN = 'boolean'
+    LIST = 'list'
+    DICT = 'dict'
+    ANY = "any"
+
+
+class OutcomeType(Enum):
+    SUCCESS = 'success'
+    FAILURE = 'failure'
+
+
+class StatusPattern:
+    COLLECTING = '{step_id}_collecting'
+    MAX_ATTEMPTS = '{step_id}_max_attempts'
+    NEXT_STEP = '{step_id}_{next_step}'
+    SUCCESS = '{step_id}_success'
+    FAILED = '{step_id}_failed'
+    INTENT_CHANGE = '{step_id}_{target_node}'
+
+
+class TransitionPattern:
+    CAPTURED = '{field}_CAPTURED:'
+    FAILED = '{field}_FAILED:'
+    INTENT_CHANGE = 'INTENT_CHANGE:'
+
+
+DEFAULT_MAX_ATTEMPTS = 3
+DEFAULT_MODEL = 'gpt-4o-mini'
+DEFAULT_TIMEOUT = 300
+
+MAX_ATTEMPTS_MESSAGE = "I'm having trouble understanding your {field}. Please contact customer service for assistance."
+WORKFLOW_COMPLETE_MESSAGE = "Workflow completed."