simplai-sdk 0.1.0__py3-none-any.whl

billing/__init__.py

@@ -0,0 +1,6 @@
+from .client import get_billing_detail
+
+__all__ = [
+    "get_billing_detail",
+
+]

billing/api.py

@@ -0,0 +1,55 @@
+from .schema import BillingResponse
+
+from typing import Any, Dict, List
+import httpx
+
+from exceptions import APIException
+
+
+from constants import BILLING_BASE_URL as BASE_URL
+
+
+async def get_billing_detail_api(
+    trace_id: str,
+    api_key: str,
+) -> Dict[str, Any]:
+    """
+    Get the billing detail for a given trace ID.
+    """
+    url = f"{BASE_URL}/{trace_id}/detail"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get(
+                url,
+                headers=headers,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+
+            if(response.status_code == 204):
+                raise APIException(message="No Content", status_code=204)
+
+                
+            data = response.json()
+            
+            result = data.get("result", {})
+
+            return BillingResponse(
+                totalConsumption=result.get("totalConsumption", 0),
+                appName=result.get("appName", ""),
+                appType=result.get("appType", ""),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")

billing/client.py

@@ -0,0 +1,14 @@
+from .api import get_billing_detail_api
+from typing import Dict, Any
+
+
+async def get_billing_detail(
+    trace_id: str,
+    api_key: str,
+) -> Dict[str, Any]:
+    billing_detail = await get_billing_detail_api(trace_id, api_key)
+    return {
+        "totalConsumption": billing_detail.totalConsumption,
+        "appName": billing_detail.appName,
+        "appType": billing_detail.appType,
+    }

billing/schema.py

@@ -0,0 +1,15 @@
+"""Pydantic schemas for bulk workflow execution API requests and responses."""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+
+class BillingResponse(BaseModel):
+    """Response schema from bulk run API."""
+    totalConsumption: float = Field(..., description="The total consumption of the app")
+    appName: str = Field(..., description="The name of the app")
+    appType: str = Field(..., description="The type of the app")
+
+    class Config:
+        populate_by_name = True

constants/__init__.py

@@ -0,0 +1,90 @@
+"""Centralized constants for the SimplAI Python SDK.
+
+This module contains all shared constants including base URLs, API paths,
+and default configuration values used across the SDK.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Load .env file before reading environment variables
+def _load_env_file() -> None:
+    """Attempt to load .env file from common locations."""
+    try:
+        from dotenv import load_dotenv  # type: ignore[import]
+    except ImportError:
+        return
+
+    # Try to find .env file in common locations
+    current_dir = Path.cwd()
+    possible_env_paths = [
+        current_dir / ".env",
+        current_dir.parent / ".env",  # python-sdk/.env
+        Path(__file__).parent.parent.parent / ".env",  # python-sdk/.env from src/constants/__init__.py
+    ]
+
+    for env_path in possible_env_paths:
+        if env_path.exists():
+            load_dotenv(dotenv_path=env_path, override=False)
+            break
+    else:
+        # Fallback: try loading from current directory
+        load_dotenv(override=False)
+
+# Load .env file
+_load_env_file()
+
+# ============================================================================
+# Base URLs
+# ============================================================================
+
+# Get base URL from environment variable or use default
+DEFAULT_BASE_URL = os.getenv("SIMPAI_BASE_URL")
+
+# Service-specific base URLs
+WORKFLOW_BASE_URL = f"{DEFAULT_BASE_URL}/interact/api/v2/tool"
+BILLING_BASE_URL = f"{DEFAULT_BASE_URL}/billing/api/v1/bill"
+
+#Billing base URL
+BILLING_BASE_URL = f"{DEFAULT_BASE_URL}/billing/api/v1/bill"
+
+
+# ============================================================================
+# Agent API Paths
+# ============================================================================
+
+AGENT_CONVERSATION_PATH = "/interact/api/ve1/intract/conversation"
+AGENT_STREAM_PATH = "/interact/api/v1/intract/data/{key}/stream"
+AGENT_CONVERSATION_FETCH_PATH = "/interact/api/ve1/intract/conversation/fetch"  # SSE format
+AGENT_CONVERSATION_FETCH_DETAILS_PATH = "/interact/api/ve1/intract/conversation/fetchDetails"  # JSON format
+
+# ============================================================================
+# Trace API Paths
+# ============================================================================
+
+# Request-level trace endpoints (RAG traces)
+TRACE_V1_BASE_PATH = "/api/v1/trace"
+TRACE_V1_FETCH_PATH = "/api/v1/trace"
+TRACE_V1_DETAILS_PATH = "/api/v1/trace/details"
+TRACE_V1_EVALUATE_PATH = "/api/v1/trace/evaluate"
+
+# Tree-based trace endpoints
+TRACE_V2_BASE_PATH = "/api/v2/trace"
+TRACE_V2_FETCH_PATH = "/api/v2/trace"
+TRACE_V2_AGGREGATE_OUTPUT_PATH = "/api/v2/trace/aggregate-output"
+TRACE_V2_TREE_PATH = "/evaluation/api/v2/trace/tree"
+TRACE_V2_DETAILS_PATH = "/evaluation/api/v2/trace/details"
+TRACE_V2_DOWNLOAD_PATH = "/evaluation/api/v2/trace/download"
+
+# Metrics endpoints
+METRICS_V1_BASE_PATH = "/api/v1/metrics"
+METRICS_V1_AGENT_PATH = "/api/v1/metrics/agent"
+METRICS_V1_TOOL_PATH = "/api/v1/metrics/tool"
+
+# ============================================================================
+# Workflow Execution Constants
+# ============================================================================
+
+TERMINAL_STATES = {"COMPLETED", "FAILED", "CANCELLED"}

core/__init__.py

@@ -0,0 +1,53 @@
+from .workflows.tool_execution import (
+    execute_workflow,
+    get_tool_result,
+    execute_and_wait_workflow,
+    cancel_execution,
+)
+
+from .workflows.bulk import (
+    trigger_bulk_run,
+    get_bulk_run_status,
+    cancel_bulk_run,
+    download_bulk_run_result,
+)
+
+from .agents.execution import (
+    AgentClient,
+    AgentExecutionError,
+    AgentMessage,
+    AgentResult,
+    AgentStatus,
+    AgentStreamChunk,
+    agent_chat,
+    agent_chat_async,
+    agent_chat_stream,
+    agent_chat_stream_async,
+    get_agent_message_status,
+    get_agent_message_status_async,
+)
+
+__all__ = [
+    # Workflows
+    "execute_workflow",
+    "get_tool_result",
+    "execute_and_wait_workflow",
+    "cancel_execution",
+    "trigger_bulk_run",
+    "get_bulk_run_status",
+    "cancel_bulk_run",
+    "download_bulk_run_result",
+    # Agents
+    "AgentStatus",
+    "AgentResult",
+    "AgentMessage",
+    "AgentStreamChunk",
+    "AgentExecutionError",
+    "AgentClient",
+    "agent_chat",
+    "agent_chat_async",
+    "agent_chat_stream",
+    "agent_chat_stream_async",
+    "get_agent_message_status",
+    "get_agent_message_status_async",
+]

core/agents/__init__.py

@@ -0,0 +1,42 @@
+"""Backwards-compatibility shim for earlier imports.
+
+The implementation has been split into smaller modules for readability:
+
+- constants: low-level URLs and defaults
+- models:   AgentStatus / AgentResult / AgentExecutionError
+- client:   AgentClient HTTP and polling logic
+- api:      High-level helpers (agent_chat, agent_chat_stream, etc.)
+"""
+
+from .execution import (
+    DEFAULT_BASE_URL,
+    AgentClient,
+    AgentExecutionError,
+    AgentMessage,
+    AgentResult,
+    AgentStatus,
+    AgentStreamChunk,
+    agent_chat,
+    agent_chat_async,
+    agent_chat_stream,
+    agent_chat_stream_async,
+    get_agent_message_status,
+    get_agent_message_status_async,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AgentStatus",
+    "AgentResult",
+    "AgentMessage",
+    "AgentStreamChunk",
+    "AgentExecutionError",
+    "AgentClient",
+    "agent_chat",
+    "agent_chat_async",
+    "agent_chat_stream",
+    "agent_chat_stream_async",
+    "get_agent_message_status",
+    "get_agent_message_status_async",
+]
+

core/agents/execution/__init__.py

@@ -0,0 +1,49 @@
+"""Simplai Agent SDK
+==============
+
+High-level Python SDK for chatting with Simplai agents.
+
+Main entrypoints:
+
+- agent_chat(...)                    # synchronous helper (polls until completion)
+- agent_chat_async(...)             # async helper
+- agent_chat_stream(...)             # streaming with callback (sync)
+- agent_chat_stream_async(...)      # streaming with callback (async)
+- get_agent_message_status(...)     # one-off status check (sync)
+- get_agent_message_status_async(...) # one-off status check (async)
+"""
+
+from ..models import (
+    AgentExecutionError,
+    AgentMessage,
+    AgentResult,
+    AgentStatus,
+    AgentStreamChunk,
+)
+from .api import (
+    agent_chat,
+    agent_chat_async,
+    agent_chat_stream,
+    agent_chat_stream_async,
+    get_agent_message_status,
+    get_agent_message_status_async,
+)
+from .client import AgentClient
+from constants import DEFAULT_BASE_URL
+
+__all__ = [
+    "AgentClient",
+    "AgentStatus",
+    "AgentResult",
+    "AgentMessage",
+    "AgentStreamChunk",
+    "AgentExecutionError",
+    "DEFAULT_BASE_URL",
+    "agent_chat",
+    "agent_chat_async",
+    "agent_chat_stream",
+    "agent_chat_stream_async",
+    "get_agent_message_status",
+    "get_agent_message_status_async",
+]
+

core/agents/execution/api.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from utils.config import get_api_key, get_base_url
+
+from ..models import AgentMessage, AgentResult, AgentStreamChunk
+from .client import AgentClient
+from constants import DEFAULT_BASE_URL
+
+
+def agent_chat(
+    agent_id: str,
+    message: str,
+    *,
+    api_key: str,
+    chat_history: Optional[List[AgentMessage]] = None,
+    conversation_id: Optional[str] = None,
+    version_id: Optional[str] = None,
+    state_override: Optional[Dict[str, Any]] = None,
+    mode: str = "sync",
+    timeout: Optional[float] = None,
+    poll_interval: float = 2.0,
+    base_url: str = DEFAULT_BASE_URL,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+    seller_id: Optional[str] = None,
+    client_id: Optional[str] = None,
+    seller_profile_id: Optional[str] = None,
+) -> AgentResult | Dict[str, Any]:
+    """Unified helper for agent chat (synchronous wrapper).
+
+    Args:
+        agent_id: ID of the agent to chat with.
+        message: User message to send to the agent.
+        api_key: PIM-SID API key.
+        chat_history: Optional list of previous messages in the conversation.
+        conversation_id: Optional existing conversation ID to continue.
+        version_id: Optional agent version ID (defaults to "latest").
+        state_override: Optional state override dictionary.
+        mode: "sync" to poll until completion, "async" to return immediately.
+        timeout: Optional timeout (seconds) for sync mode.
+        poll_interval: Polling interval (seconds) for sync mode.
+        base_url: Override the default base URL if needed.
+        user_id: Optional user ID for the conversation.
+        tenant_id: Tenant ID (defaults to "1").
+        project_id: Optional project ID.
+        seller_id: Optional seller ID (X-SELLER-ID header).
+        client_id: Optional client ID (X-CLIENT-ID header).
+        seller_profile_id: Optional seller profile ID (X-SELLER-PROFILE-ID header).
+
+    Returns:
+        If mode == "sync": AgentResult.
+        If mode == "async": Response dict with conversation_id and message_id.
+    """
+    client = AgentClient(
+        api_key=api_key,
+        base_url=base_url,
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+        seller_id=seller_id,
+        client_id=client_id,
+        seller_profile_id=seller_profile_id,
+    )
+
+    mode_normalized = mode.lower()
+    if mode_normalized == "async":
+        response = client.chat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+        return response
+    if mode_normalized == "sync":
+        return client.chat_and_wait(
+            agent_id,
+            message,
+            chat_history,
+            conversation_id,
+            version_id,
+            state_override,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    raise ValueError("mode must be either 'sync' or 'async'")
+
+
+async def agent_chat_async(
+    agent_id: str,
+    message: str,
+    *,
+    api_key: str,
+    chat_history: Optional[List[AgentMessage]] = None,
+    conversation_id: Optional[str] = None,
+    version_id: Optional[str] = None,
+    state_override: Optional[Dict[str, Any]] = None,
+    mode: str = "sync",
+    timeout: Optional[float] = None,
+    poll_interval: float = 2.0,
+    base_url: str = DEFAULT_BASE_URL,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+    seller_id: Optional[str] = None,
+    client_id: Optional[str] = None,
+    seller_profile_id: Optional[str] = None,
+) -> AgentResult | Dict[str, Any]:
+    """Async variant of agent_chat."""
+    client = AgentClient(
+        api_key=api_key,
+        base_url=base_url,
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+        seller_id=seller_id,
+        client_id=client_id,
+        seller_profile_id=seller_profile_id,
+    )
+
+    mode_normalized = mode.lower()
+    if mode_normalized == "async":
+        response = await client.achat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+        return response
+    if mode_normalized == "sync":
+        return await client.achat_and_wait(
+            agent_id,
+            message,
+            chat_history,
+            conversation_id,
+            version_id,
+            state_override,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    raise ValueError("mode must be either 'sync' or 'async'")
+
+
+def agent_chat_stream(
+    agent_id: str,
+    message: str,
+    *,
+    api_key: str,
+    chat_history: Optional[List[AgentMessage]] = None,
+    conversation_id: Optional[str] = None,
+    version_id: Optional[str] = None,
+    state_override: Optional[Dict[str, Any]] = None,
+    on_chunk: Optional[Callable[[AgentStreamChunk], None]] = None,
+    base_url: str = DEFAULT_BASE_URL,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+    seller_id: Optional[str] = None,
+    client_id: Optional[str] = None,
+    seller_profile_id: Optional[str] = None,
+) -> AgentResult:
+    """Stream agent chat response with callback for each chunk (synchronous).
+
+    Args:
+        agent_id: ID of the agent to chat with.
+        message: User message to send to the agent.
+        api_key: PIM-SID API key.
+        chat_history: Optional list of previous messages in the conversation.
+        conversation_id: Optional existing conversation ID to continue.
+        version_id: Optional agent version ID.
+        on_chunk: Optional callback function called for each streamed chunk.
+        base_url: Override the default base URL if needed.
+        user_id: Optional user ID for the conversation.
+        tenant_id: Tenant ID (defaults to "1").
+        project_id: Optional project ID.
+
+    Returns:
+        AgentResult with the complete response.
+    """
+    client = AgentClient(
+        api_key=api_key,
+        base_url=base_url,
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+        seller_id=seller_id,
+        client_id=client_id,
+        seller_profile_id=seller_profile_id,
+    )
+
+    return client.stream_chat(
+        agent_id,
+        message,
+        chat_history,
+        conversation_id,
+        version_id,
+        state_override,
+        on_chunk=on_chunk,
+    )
+
+
+async def agent_chat_stream_async(
+    agent_id: str,
+    message: str,
+    *,
+    api_key: Optional[str] = None,
+    chat_history: Optional[List[AgentMessage]] = None,
+    conversation_id: Optional[str] = None,
+    version_id: Optional[str] = None,
+    state_override: Optional[Dict[str, Any]] = None,
+    on_chunk: Optional[Callable[[AgentStreamChunk], None]] = None,
+    base_url: Optional[str] = None,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+    seller_id: Optional[str] = None,
+    client_id: Optional[str] = None,
+    seller_profile_id: Optional[str] = None,
+) -> AgentResult:
+    """Async variant of agent_chat_stream."""
+    client = AgentClient(
+        api_key=get_api_key(api_key),
+        base_url=get_base_url(base_url),
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+        seller_id=seller_id,
+        client_id=client_id,
+        seller_profile_id=seller_profile_id,
+    )
+
+    return await client.astream_chat(
+        agent_id,
+        message,
+        chat_history,
+        conversation_id,
+        version_id,
+        state_override,
+        on_chunk=on_chunk,
+    )
+
+
+def get_agent_message_status(
+    conversation_id: str,
+    message_id: str,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+) -> Dict[str, Any]:
+    """One-off helper to fetch status for a given message (synchronous)."""
+    client = AgentClient(
+        api_key=get_api_key(api_key),
+        base_url=get_base_url(base_url),
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+    )
+    response, _, _ = client.fetch_message_once(conversation_id, message_id)
+    return response
+
+
+async def get_agent_message_status_async(
+    conversation_id: str,
+    message_id: str,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    user_id: Optional[str] = None,
+    tenant_id: str = "1",
+    project_id: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Async variant of get_agent_message_status."""
+    client = AgentClient(
+        api_key=get_api_key(api_key),
+        base_url=get_base_url(base_url),
+        user_id=user_id,
+        tenant_id=tenant_id,
+        project_id=project_id,
+    )
+    response, _, _ = await client.afetch_message_once(conversation_id, message_id)
+    return response
+