simplai-sdk 0.1.0__py3-none-any.whl

traces/agents/models.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class EvalMetrics:
+    """Evaluation metrics for a trace."""
+    metric: str
+    score: Optional[float] = None
+    status: Optional[str] = None
+    passing_threshold: Optional[float] = None
+    desc: Optional[str] = None
+    failed_remark: Optional[str] = None
+    evaluated_at: Optional[datetime] = None
+
+
+@dataclass
+class RagTrace:
+    """Request-level trace (RAG trace) representing an agent conversation."""
+    id: Optional[str] = None
+    request_id: Optional[str] = None
+    conversation_id: Optional[str] = None
+    user_id: Optional[int] = None
+    username: Optional[str] = None
+    tenant_id: Optional[int] = None
+    workflow_id: Optional[str] = None
+    workflow_name: Optional[str] = None
+    agent_id: Optional[str] = None
+    agent_name: Optional[str] = None
+    kb_id: Optional[int] = None
+    kb_name: Optional[str] = None
+    model_id: Optional[str] = None
+    model_name: Optional[str] = None
+    model_input_tokens: Optional[int] = None
+    model_output_tokens: Optional[int] = None
+    kb_query_tokens: Optional[int] = None
+    context_tokens: Optional[int] = None
+    query: Optional[str] = None
+    prompt: Optional[str] = None
+    context: Optional[List[str]] = None
+    response: Optional[str] = None
+    response_time: Optional[int] = None
+    model_response_time: Optional[int] = None
+    kb_response_time: Optional[int] = None
+    user_feedback: Optional[bool] = None
+    source: List[str] = field(default_factory=list)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    evaluation_started_by: Optional[int] = None
+    evaluation_started_by_name: Optional[str] = None
+    eval_metrics: Optional[List[EvalMetrics]] = None
+    status: Optional[str] = None
+    ground_truth: Optional[str] = None
+    payload: Optional[Dict[str, Any]] = None  # Full API response
+
+
+@dataclass
+class TraceData:
+    """Data payload for a trace node."""
+    input: Optional[Dict[str, Any]] = None
+    output: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class ChildInfo:
+    """Information about a child node."""
+    node_id: str
+    name: str
+    entity_type: Optional[str] = None
+
+
+@dataclass
+class TraceNode:
+    """Tree-based trace node representing a step in agent/workflow execution."""
+    id: Optional[str] = None
+    tenant_id: Optional[int] = None
+    project_id: Optional[int] = None
+    user_id: Optional[int] = None
+    source: Optional[str] = None
+    is_bulk_run_parent: Optional[bool] = None
+    node_id: Optional[str] = None  # span id
+    name: Optional[str] = None  # step name (tool name, agent name, etc.)
+    entity_type: Optional[str] = None  # agent, tool, step, model, kb
+    entity_id: Optional[str] = None
+    tree_id: Optional[str] = None
+    parent_id: Optional[str] = None
+    parent_span_id: Optional[str] = None
+    children: Optional[List[TraceNode]] = None
+    descendants: Optional[List[ChildInfo]] = None
+    path: Optional[str] = None  # ancestor chain based on node name
+    data: Optional[TraceData] = None
+    has_children: Optional[bool] = None
+    created_at: Optional[datetime] = None
+    execution_time: Optional[datetime] = None
+    profile_id: Optional[str] = None
+    profile: Optional[str] = None
+    is_root: Optional[bool] = None
+    sub_entity_id: Optional[str] = None
+    completion_tokens: Optional[int] = None
+    prompt_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    latency: Optional[float] = None
+    context_window_utilization: Optional[float] = None
+    status: Optional[str] = None
+    origin: Optional[str] = None
+    app_id: Optional[str] = None
+    child_count: Optional[int] = None
+    payload: Optional[Dict[str, Any]] = None  # Full API response
+
+
+@dataclass
+class FetchTraceFilters:
+    """Filters for fetching request-level traces (RAG traces)."""
+    tenant_id: Optional[int] = None
+    user_id: Optional[int] = None
+    request_id: Optional[str] = None
+    query: Optional[str] = None
+    workflow_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    is_agent: Optional[bool] = None
+    kb_id: Optional[int] = None
+    model_id: Optional[str] = None
+    search_filter: Optional[str] = None
+    created_at_from: Optional[datetime] = None
+    created_at_to: Optional[datetime] = None
+
+    def to_query_params(self) -> Dict[str, Any]:
+        """Convert filters to query parameters."""
+        params: Dict[str, Any] = {}
+        if self.user_id is not None:
+            params["userId"] = str(self.user_id)
+        if self.request_id:
+            params["requestId"] = self.request_id
+        if self.query:
+            params["query"] = self.query
+        if self.workflow_id:
+            params["workflowId"] = self.workflow_id
+        if self.agent_id:
+            params["agentId"] = self.agent_id
+        if self.is_agent is not None:
+            params["isAgent"] = str(self.is_agent).lower()
+        if self.kb_id is not None:
+            params["kbId"] = str(self.kb_id)
+        if self.model_id:
+            params["modelId"] = self.model_id
+        if self.search_filter:
+            params["searchFilter"] = self.search_filter
+        if self.created_at_from:
+            params["createdAtFrom"] = self.created_at_from.strftime("%Y-%m-%d %H:%M:%S")
+        if self.created_at_to:
+            params["createdAtTo"] = self.created_at_to.strftime("%Y-%m-%d %H:%M:%S")
+        return params
+
+
+@dataclass
+class TraceFilters:
+    """Filters for fetching tree-based traces."""
+    tenant_id: Optional[int] = None
+    user_id: Optional[int] = None
+    project_id: Optional[int] = None
+    path: Optional[str] = None
+    name: Optional[str] = None
+    source: Optional[List[str]] = None
+    is_get_all: bool = False
+    profile: Optional[str] = None
+    profile_id: Optional[str] = None
+    entity_id: Optional[str] = None
+    sub_entity_id: Optional[str] = None
+    version: Optional[str] = None
+    status: Optional[List[str]] = None
+    origin: Optional[List[str]] = None
+    created_at_from: Optional[datetime] = None
+    created_at_to: Optional[datetime] = None
+
+    def to_query_params(self) -> Dict[str, Any]:
+        """Convert filters to query parameters."""
+        params: Dict[str, Any] = {}
+        if self.user_id is not None:
+            params["userId"] = str(self.user_id)
+        if self.path:
+            params["path"] = self.path
+        if self.name:
+            params["name"] = self.name
+        if self.source:
+            params["source"] = ",".join(self.source)
+        if self.is_get_all:
+            params["isGetAll"] = "true"
+        if self.profile:
+            params["profile"] = self.profile
+        if self.profile_id:
+            params["profileId"] = self.profile_id
+        if self.entity_id:
+            params["entityId"] = self.entity_id
+        if self.sub_entity_id:
+            params["subEntityId"] = self.sub_entity_id
+        if self.version:
+            params["version"] = self.version
+        if self.status:
+            params["status"] = ",".join(self.status)
+        if self.origin:
+            params["origin"] = ",".join(self.origin)
+        if self.created_at_from:
+            params["createdAtFrom"] = self.created_at_from.strftime("%Y-%m-%d %H:%M:%S")
+        if self.created_at_to:
+            params["createdAtTo"] = self.created_at_to.strftime("%Y-%m-%d %H:%M:%S")
+        return params
+
+
+@dataclass
+class MetricsRequestDto:
+    """Request DTO for fetching metrics."""
+    tenant_id: Optional[int] = None
+    project_id: Optional[int] = None
+    app_id: Optional[str] = None
+    from_date: Optional[datetime] = None
+    to_date: Optional[datetime] = None
+
+    def to_query_params(self) -> Dict[str, Any]:
+        """Convert to query parameters."""
+        params: Dict[str, Any] = {}
+        if self.app_id:
+            params["appId"] = self.app_id
+        if self.from_date:
+            params["fromDate"] = self.from_date.strftime("%Y-%m-%d %H:%M:%S")
+        if self.to_date:
+            params["toDate"] = self.to_date.strftime("%Y-%m-%d %H:%M:%S")
+        return params
+
+
+@dataclass
+class PageableResponse:
+    """Paginated response wrapper."""
+    success: bool
+    status: str
+    data: Any  # Can be Page[RagTrace] or Page[TraceNode]
+    total_elements: Optional[int] = None
+    total_pages: Optional[int] = None
+    page_number: Optional[int] = None
+    page_size: Optional[int] = None
+
+
+class TraceError(Exception):
+    """Raised when a trace operation fails."""
+

utils/config.py

@@ -0,0 +1,117 @@
+"""Configuration utilities for loading API keys and base URLs.
+
+This module provides utilities to load configuration values with the following priority:
+1. User-provided parameter
+2. Environment variable
+3. .env file (if python-dotenv is available)
+4. Default value (for base_url) or error (for api_key)
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def _load_env_file() -> None:
+    """Attempt to load .env file from common locations."""
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        # python-dotenv not installed, skip loading .env
+        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/utils
+    ]
+
+    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)
+
+
+def get_api_key(api_key: Optional[str] = None) -> str:
+    """
+    Get API key with fallback priority:
+    1. User-provided api_key parameter
+    2. API_KEY from environment variable
+    3. API_KEY from .env file
+    4. Raise error if not found
+
+    Args:
+        api_key: Optional API key provided by user
+
+    Returns:
+        API key string
+
+    Raises:
+        ValueError: If API key is not found in any source
+    """
+    # First priority: user-provided API key
+    if api_key:
+        return api_key
+
+    # Second priority: check environment variable (may already be set)
+    env_api_key = os.getenv("SIMPAI_API_KEY")
+    if env_api_key:
+        return env_api_key
+
+    # Third priority: try to load from .env file
+    _load_env_file()
+
+    # Check environment variable again after loading .env
+    env_api_key = os.getenv("SIMPAI_API_KEY")
+    if env_api_key:
+        return env_api_key
+
+    # Fourth priority: raise error
+    raise ValueError(
+        "API key is required. Provide it using one of the following methods:\n"
+        "  1. As a parameter: SimplAI(api_key='your-key')\n"
+        "  2. As environment variable: export API_KEY=your-key\n"
+        "  3. In a .env file: API_KEY=your-key"
+    )
+
+
+def get_base_url(base_url: Optional[str] = None) -> str:
+    """
+    Get base URL with fallback priority:
+    1. User-provided base_url parameter
+    2. BASE_URL from environment variable
+    3. BASE_URL from .env file
+    4. Default base URL constant
+
+    Args:
+        base_url: Optional base URL provided by user
+
+    Returns:
+        Base URL string
+    """
+    # First priority: user-provided base URL
+    if base_url:
+        return base_url.rstrip("/")
+
+    # Second priority: check environment variable (may already be set)
+    env_base_url = os.getenv("SIMPAI_BASE_URL")
+    if env_base_url:
+        return env_base_url.rstrip("/")
+
+    # Third priority: try to load from .env file
+    _load_env_file()
+
+    # Check environment variable again after loading .env
+    env_base_url = os.getenv("SIMPAI_BASE_URL")
+    if env_base_url:
+        return env_base_url.rstrip("/")
+
+    # Fourth priority: default base URL
+    from constants import DEFAULT_BASE_URL
+
+    return DEFAULT_BASE_URL