soprano-sdk 0.2.10__py3-none-any.whl

soprano_sdk/__init__.py

@@ -0,0 +1,12 @@
+from .core.engine import WorkflowEngine, load_workflow
+from .core.constants import MFAConfig
+from .tools import WorkflowTool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WorkflowEngine",
+    "load_workflow",
+    "MFAConfig",
+    "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,90 @@
+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, only use this for clarification or asking for more information"))}
+
+    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/authenticators/mfa.py

@@ -0,0 +1,205 @@
+import requests
+from typing import TypedDict, Literal, NotRequired, Optional
+from soprano_sdk.core.constants import MFAConfig
+
+
+class MFAChallenge(TypedDict):
+    value: str
+
+
+class MFAState(TypedDict):
+    challengeType: Literal['OTP', 'dob']
+    post_payload: dict[str, str]
+    post_headers: NotRequired[dict[str, str]]
+    otpValue: NotRequired[str]
+    status: Literal['IN_PROGRESS', 'COMPLETED', 'ERRORED', 'FAILED'] | None
+    message: str
+    retry_count: int
+
+
+
+def get_response(response: requests.Response):
+    if response.ok:
+        return response.json(), None
+    else:
+        return None, response.json()
+
+
+def build_path(base_url: str, path: str):
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def enforce_mfa_if_required(state: dict, mfa_config: Optional[MFAConfig] = None):
+    if mfa_config is None:
+        mfa_config = state.get('_mfa_config') or MFAConfig()
+
+    _mfa : MFAState = state['_mfa']
+    if _mfa['status'] == 'COMPLETED':
+        return True
+
+    # Use custom headers if provided, otherwise empty dict
+    headers = _mfa.get('post_headers', {})
+
+    generate_token_response = requests.post(
+        build_path(
+            base_url=mfa_config.generate_token_base_url,
+            path=mfa_config.generate_token_path
+        ),
+        json=_mfa['post_payload'],
+        timeout=mfa_config.api_timeout,
+        headers=headers
+    )
+    _, error = get_response(generate_token_response)
+
+    challenge_type = error['additionalData']['challengeType']
+    _mfa['challengeType'] = challenge_type
+    _mfa['status'] = 'IN_PROGRESS'
+    _mfa['retry_count'] = 0
+    _mfa['message'] = f"Please enter the {challenge_type}"
+    if delivery_methods := error['additionalData'].get(f"{challenge_type.lower()}SentTo"):
+        _mfa['message'] += f" sent via {','.join(delivery_methods)}"
+    return False
+
+
+def mfa_validate_user_input(mfa_config: Optional[MFAConfig] = None, **state: dict):
+    if mfa_config is None:
+        mfa_config = state.get('_mfa_config') or MFAConfig()
+
+    _mfa : MFAState = state['_mfa']
+    input_field_name = state['_active_input_field']
+    if not state[input_field_name]:
+        return False
+
+    # Use custom headers if provided, otherwise empty dict
+    headers = _mfa.get('post_headers', {})
+
+    post_payload = _mfa['post_payload']
+    challenge_field_name = f"{_mfa['challengeType'].lower()}Challenge"
+    post_payload.update({challenge_field_name: {"value": state[input_field_name]}})
+    validate_token_response = requests.post(
+        build_path(
+            base_url=mfa_config.validate_token_base_url,
+            path=mfa_config.validate_token_path
+        ),
+        json=post_payload,
+        timeout=mfa_config.api_timeout,
+        headers=headers
+    )
+    _mfa['retry_count'] += 1
+    response, error = get_response(validate_token_response)
+    if error:
+        if _mfa['retry_count'] == 1:
+            _mfa['status'] = 'ERRORED'
+        return False, f"You Have Entered Invalid {_mfa['challengeType']}. {_mfa['message']}"
+
+    if response and 'token' in response:
+        token = response['token']
+        post_payload['token'] = token
+
+        authorize = requests.post(
+            build_path(
+                base_url=mfa_config.authorize_token_base_url,
+                path=mfa_config.authorize_token_path
+            ),
+            json=post_payload,
+            timeout=mfa_config.api_timeout,
+            headers=headers
+        )
+        if authorize.status_code == 204:
+            _mfa['status'] = 'COMPLETED'
+            return True, None
+        else:
+            _mfa['status'] = 'FAILED'
+            return False, f"You Have Entered Invalid {_mfa['challengeType']}. {_mfa['message']}"
+
+
+class MFANodeConfig:
+
+    @classmethod
+    def get_call_function_template(cls, source_node: str, next_node: str, mfa: dict):
+        return dict(
+            id=f"{source_node}_mfa_start",
+            action="call_function",
+            function="soprano_sdk.authenticators.mfa.enforce_mfa_if_required",
+            output=f"{source_node}_mfa_start",
+            mfa=mfa,
+            transitions=[
+                dict(
+                    condition=True,
+                    next=source_node,
+                ),
+                dict(
+                    condition=False,
+                    next=next_node,
+                ),
+            ]
+        )
+
+    @classmethod
+    def get_validate_user_input(cls, source_node: str, next_node: str, mfa_config: dict):
+        model_name = mfa_config['model']
+        max_attempts = mfa_config.get('max_attempts', 3)
+        on_max_attempts_reached = mfa_config.get('on_max_attempts_reached')
+
+        input_field_name = f"{source_node}_mfa_input"
+        node_config = dict(
+            id=f"{source_node}_mfa_validate",
+            action="collect_input_with_agent",
+            description="Collect Input for MFA value",
+            field=input_field_name,
+            max_attempts=max_attempts,
+            validator="soprano_sdk.authenticators.mfa.mfa_validate_user_input",
+            agent=dict(
+                name="MFA Input Data Collector",
+                model=model_name,
+                initial_message="{{_mfa.message}}",
+                instructions="""
+                    You are an authentication value extractor. Your job is to identify and extract MFA codes from user input, or detect if the user wants to cancel the authentication flow.
+
+                    **Task:**
+                    - Read the user's message carefully
+                    - First, check if the user wants to cancel, stop, or exit the authentication process
+                    - If they want to cancel, output: MFA_CANCELLED:
+                    - Otherwise, extract ONLY the OTP/MFA code value and output in the format shown below
+
+                    **Cancellation Detection:**
+                    If the user expresses any intent to cancel, stop, exit, abort, or quit the authentication process, respond with: MFA_CANCELLED
+
+                    Examples of cancellation phrases:
+                    * "cancel" → MFA_CANCELLED:
+                    * "I want to stop" → MFA_CANCELLED:
+                    * "exit" → MFA_CANCELLED:
+                    * "nevermind" → MFA_CANCELLED:
+                    * "I don't want to continue" → MFA_CANCELLED:
+                    * "stop this" → MFA_CANCELLED:
+                    * "forget it" → MFA_CANCELLED:
+                    * "abort" → MFA_CANCELLED:
+                    * "quit" → MFA_CANCELLED:
+
+                    **OTP Capture Examples:**
+                    * "1234" → MFA_CAPTURED:1234
+                    * "2345e" → MFA_CAPTURED:2345e
+                    * "the code is 567890" → MFA_CAPTURED:567890
+                    * "my otp is 123456" → MFA_CAPTURED:123456
+
+                    **Output Format:**
+                    - For OTP/MFA codes: MFA_CAPTURED:<otp_value>
+                    - For cancellation: MFA_CANCELLED:
+
+            """),
+            transitions=[
+                dict(
+                    pattern="MFA_CAPTURED:",
+                    next=next_node
+                ),
+                dict(
+                    pattern="MFA_CANCELLED:",
+                    next="mfa_cancelled"
+                )
+            ]
+        )
+
+        if on_max_attempts_reached:
+            node_config['on_max_attempts_reached'] = on_max_attempts_reached
+
+        return node_config