synth-ai 0.2.8.dev2__py3-none-any.whl → 0.4.3__py3-none-any.whl

synth_ai/cli/local/session/constants.py

@@ -0,0 +1,63 @@
+"""Constants for agent session usage tracking.
+
+Shared constants used by both SDK and backend.
+"""
+
+from __future__ import annotations
+
+# Session status values
+SESSION_STATUS_ACTIVE = "active"  # Currently active session (only one per org/user)
+SESSION_STATUS_ENDED = "ended"
+SESSION_STATUS_LIMIT_EXCEEDED = "limit_exceeded"
+SESSION_STATUS_EXPIRED = "expired"
+
+# Limit types
+LIMIT_TYPE_HARD = "hard"
+LIMIT_TYPE_SOFT = "soft"
+LIMIT_TYPE_ROLLING_WINDOW = "rolling_window"
+
+# Metric types
+METRIC_TYPE_TOKENS = "tokens"
+METRIC_TYPE_COST_USD = "cost_usd"
+METRIC_TYPE_GPU_HOURS = "gpu_hours"
+METRIC_TYPE_API_CALLS = "api_calls"
+
+# Session types
+SESSION_TYPE_API_CALL = "api_call"
+SESSION_TYPE_JOB = "job"
+SESSION_TYPE_TRACING_SESSION = "tracing_session"
+
+# Reference types for usage records
+REFERENCE_TYPE_WALL_CLOCK_EVENT = "wall_clock_event"
+REFERENCE_TYPE_LLM_CALL = "llm_call"
+REFERENCE_TYPE_API_CALL = "api_call"
+REFERENCE_TYPE_CUSTOM = "custom"
+
+# Valid values sets (for validation)
+VALID_SESSION_STATUSES = {
+    SESSION_STATUS_ACTIVE,
+    SESSION_STATUS_ENDED,
+    SESSION_STATUS_LIMIT_EXCEEDED,
+    SESSION_STATUS_EXPIRED,
+}
+
+VALID_LIMIT_TYPES = {
+    LIMIT_TYPE_HARD,
+    LIMIT_TYPE_SOFT,
+    LIMIT_TYPE_ROLLING_WINDOW,
+}
+
+VALID_METRIC_TYPES = {
+    METRIC_TYPE_TOKENS,
+    METRIC_TYPE_COST_USD,
+    METRIC_TYPE_GPU_HOURS,
+    METRIC_TYPE_API_CALLS,
+}
+
+VALID_REFERENCE_TYPES = {
+    REFERENCE_TYPE_WALL_CLOCK_EVENT,
+    REFERENCE_TYPE_LLM_CALL,
+    REFERENCE_TYPE_API_CALL,
+    REFERENCE_TYPE_CUSTOM,
+}
+

synth_ai/cli/local/session/exceptions.py

@@ -0,0 +1,105 @@
+"""Shared exceptions for agent session usage tracking.
+
+These exceptions are used by both the SDK (synth-ai) and backend (monorepo).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+
+class SessionUsageError(Exception):
+    """Base exception for session usage errors."""
+
+    pass
+
+
+class LimitExceededError(SessionUsageError):
+    """Raised when a session limit is exceeded."""
+
+    def __init__(
+        self,
+        session_id: str,
+        metric_type: str,
+        limit_value: Decimal,
+        current_usage: Decimal,
+        attempted_usage: Decimal,
+        reason: str | None = None,
+    ):
+        self.session_id = session_id
+        self.metric_type = metric_type
+        self.limit_value = limit_value
+        self.current_usage = current_usage
+        self.attempted_usage = attempted_usage
+        self.reason = reason or "Hard limit exceeded"
+        
+        # Format metric type for display
+        metric_display = {
+            "cost_usd": "cost",
+            "gpu_hours": "GPU hours",
+            "api_calls": "API calls",
+        }.get(metric_type, metric_type)
+        
+        # Calculate what would have been the new total
+        projected_total = current_usage + attempted_usage
+        remaining = limit_value - current_usage
+        
+        message = (
+            f"Session '{session_id}' {metric_display} limit exceeded. "
+            f"Limit: {limit_value}, Current usage: {current_usage}, "
+            f"Attempted: {attempted_usage} (would be {projected_total} total). "
+            f"Remaining budget: {remaining}. "
+            f"To continue, end this session and create a new one with a higher limit, "
+            f"or increase the limit using client.increase_limit()"
+        )
+        super().__init__(message)
+
+
+class SessionNotFoundError(SessionUsageError):
+    """Raised when a session is not found."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        message = (
+            f"Session '{session_id}' not found. "
+            f"This session may have been deleted, or you may not have access to it. "
+            f"Verify the session ID is correct and belongs to your organization. "
+            f"List your sessions using client.list()"
+        )
+        super().__init__(message)
+
+
+class SessionNotActiveError(SessionUsageError):
+    """Raised when attempting to use an inactive session."""
+
+    def __init__(self, session_id: str, status: str):
+        self.session_id = session_id
+        self.status = status
+        
+        status_messages = {
+            "ended": "has been ended",
+            "limit_exceeded": "has exceeded its limit",
+            "expired": "has expired",
+        }
+        status_desc = status_messages.get(status, f"has status '{status}'")
+        
+        message = (
+            f"Session '{session_id}' is not active - it {status_desc}. "
+            f"To use this session, you must create a new active session using client.create()"
+        )
+        super().__init__(message)
+
+
+class InvalidLimitError(SessionUsageError):
+    """Raised when limit configuration is invalid."""
+
+    def __init__(self, message: str):
+        self.message = message
+        full_message = (
+            f"Invalid limit configuration: {message}. "
+            f"Valid limit types: 'hard', 'soft', 'rolling_window'. "
+            f"Valid metric types: 'tokens', 'cost_usd', 'gpu_hours', 'api_calls'. "
+            f"Limit value must be positive (> 0)."
+        )
+        super().__init__(full_message)
+

synth_ai/cli/local/session/manager.py

@@ -0,0 +1,139 @@
+"""High-level AgentSession manager for SDK."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Optional
+from uuid import UUID
+
+from .client import AgentSessionClient
+from .exceptions import LimitExceededError, SessionNotFoundError
+from .models import AgentSession
+
+
+class AgentSessionManager:
+    """High-level manager for agent sessions.
+
+    Provides convenient methods for common operations and context managers
+    for automatic session lifecycle management.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        org_id: Optional[UUID] = None,
+        default_limits: Optional[list[dict[str, Any]]] = None,
+    ):
+        self.client = AgentSessionClient(base_url, api_key)
+        self.org_id = org_id
+        self.default_limits = default_limits or []
+        self._current_session: Optional[AgentSession] = None
+
+    @asynccontextmanager
+    async def session(
+        self,
+        session_id: Optional[str] = None,
+        limits: Optional[list[dict[str, Any]]] = None,
+        tracing_session_id: Optional[str] = None,
+        expires_at: Optional[datetime] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        auto_end: bool = True,
+    ):
+        """Context manager for agent session lifecycle.
+
+        Example:
+            async with manager.session(limits=[...]) as session:
+                # Use session.session_id in API calls
+                await manager.record_usage(session.session_id, ...)
+        """
+        if not self.org_id:
+            raise ValueError(
+                "org_id is required for session creation. "
+                "Either provide org_id explicitly, or ensure the client can fetch it from /api/v1/me endpoint."
+            )
+
+        limits = limits or self.default_limits
+        session = await self.client.create(
+            org_id=self.org_id,
+            limits=limits,
+            tracing_session_id=tracing_session_id,
+            expires_at=expires_at,
+            metadata=metadata,
+            session_id=session_id,
+        )
+
+        self._current_session = session
+        try:
+            yield session
+        finally:
+            if auto_end:
+                await self.client.end(session.session_id)
+            self._current_session = None
+
+    async def ensure_session(
+        self,
+        session_id: Optional[str] = None,
+    ) -> AgentSession:
+        """Get existing session or create new one.
+
+        Useful for CLI where session might already exist.
+        """
+        if session_id:
+            try:
+                return await self.client.get(session_id)
+            except SessionNotFoundError:
+                pass
+
+        # Create new session
+        if not self.org_id:
+            raise ValueError(
+                "org_id is required for session creation. "
+                "Either provide org_id explicitly, or ensure the client can fetch it from /api/v1/me endpoint."
+            )
+
+        return await self.client.create(
+            org_id=self.org_id,
+            limits=self.default_limits,
+        )
+
+    @property
+    def current_session(self) -> Optional[AgentSession]:
+        """Get current active session (if any)."""
+        return self._current_session
+
+    async def check_and_record(
+        self,
+        session_id: str,
+        metric_type: str,
+        estimated_value: Decimal,
+        actual_value: Decimal,
+        reference_type: Optional[str] = None,
+        reference_id: Optional[str] = None,
+    ) -> None:
+        """Check limit, record usage, handle errors.
+
+        Convenience method that:
+        1. Checks limit with estimated value
+        2. Records actual usage (if limit check endpoint exists)
+        3. Raises LimitExceededError if limit hit
+
+        Note: Actual usage recording would need to be implemented via API endpoint.
+        """
+        # Check limit
+        check = await self.client.check_limit(session_id, metric_type, estimated_value)
+        if not check.allowed:
+            raise LimitExceededError(
+                session_id=session_id,
+                metric_type=metric_type,
+                limit_value=check.limit_value,
+                current_usage=check.current_usage,
+                attempted_usage=estimated_value,
+                reason=check.reason,
+            )
+
+        # Note: Usage recording would need an API endpoint
+        # For now, this is a placeholder
+

synth_ai/cli/local/session/models.py

@@ -0,0 +1,89 @@
+"""Agent session data models for SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Optional
+from uuid import UUID
+
+
+@dataclass
+class AgentSessionLimit:
+    """Limit configuration for an agent session."""
+
+    limit_type: str  # 'hard', 'soft', 'rolling_window'
+    metric_type: str  # 'tokens', 'cost_usd', 'gpu_hours', 'api_calls'
+    limit_value: Decimal
+    current_usage: Decimal = Decimal("0")
+    warning_threshold: Optional[Decimal] = None
+    window_seconds: Optional[int] = None
+    limit_id: Optional[UUID] = None
+    exceeded_at: Optional[datetime] = None
+    exceeded_reason: Optional[str] = None
+    created_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+    @property
+    def remaining(self) -> Decimal:
+        """Calculate remaining limit."""
+        return self.limit_value - self.current_usage
+
+
+@dataclass
+class AgentSessionUsage:
+    """Current usage summary for a session."""
+
+    tokens: Decimal = Decimal("0")
+    cost_usd: Decimal = Decimal("0")
+    gpu_hours: Decimal = Decimal("0")
+    api_calls: int = 0
+
+
+@dataclass
+class LimitCheckResult:
+    """Result of a limit check."""
+
+    allowed: bool
+    limit_value: Decimal
+    current_usage: Decimal
+    remaining: Decimal
+    reason: Optional[str] = None
+
+
+@dataclass
+class AgentSession:
+    """Agent session representation."""
+
+    session_id: str
+    org_id: UUID
+    created_at: datetime
+    user_id: Optional[UUID] = None
+    api_key_id: Optional[UUID] = None
+    expires_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None
+    status: str = "active"  # 'active', 'ended', 'limit_exceeded', 'expired'
+    limit_exceeded_reason: Optional[str] = None
+    usage: AgentSessionUsage = field(default_factory=AgentSessionUsage)
+    limits: list[AgentSessionLimit] = field(default_factory=list)
+    tracing_session_id: Optional[str] = None
+    session_type: str = "api_call"  # 'api_call', 'job', 'tracing_session'
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SessionUsageRecord:
+    """Individual usage event within a session."""
+
+    id: UUID
+    session_id: str
+    metric_type: str
+    metric_value: Decimal
+    org_id: UUID
+    created_at: datetime
+    reference_type: Optional[str] = None
+    reference_id: Optional[str] = None
+    user_id: Optional[UUID] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+

synth_ai/cli/local/session/query.py

@@ -0,0 +1,110 @@
+"""Query builder for agent sessions (SDK)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID
+
+from .client import AgentSessionClient
+from .models import AgentSession
+
+
+class AgentSessionQuery:
+    """Fluent query builder for agent sessions."""
+
+    def __init__(self, client: AgentSessionClient):
+        self._client = client
+        self._filters: dict[str, Any] = {}
+        self._order_by: Optional[str] = None
+        self._limit: Optional[int] = None
+        self._offset: int = 0
+
+    def org_id(self, org_id: UUID) -> AgentSessionQuery:
+        """Filter by organization ID."""
+        self._filters["org_id"] = org_id
+        return self
+
+    def user_id(self, user_id: UUID) -> AgentSessionQuery:
+        """Filter by user ID."""
+        self._filters["user_id"] = user_id
+        return self
+
+    def status(self, status: str) -> AgentSessionQuery:
+        """Filter by status."""
+        self._filters["status"] = status
+        return self
+
+    def created_after(self, after: datetime) -> AgentSessionQuery:
+        """Filter sessions created after date."""
+        self._filters["created_after"] = after
+        return self
+
+    def created_before(self, before: datetime) -> AgentSessionQuery:
+        """Filter sessions created before date."""
+        self._filters["created_before"] = before
+        return self
+
+    def has_limit_exceeded(self) -> AgentSessionQuery:
+        """Filter sessions that exceeded limits."""
+        self._filters["limit_exceeded"] = True
+        return self
+
+    def tracing_session_id(self, tracing_session_id: str) -> AgentSessionQuery:
+        """Filter by tracing session ID."""
+        self._filters["tracing_session_id"] = tracing_session_id
+        return self
+
+    def order_by(self, field: str, desc: bool = True) -> AgentSessionQuery:
+        """Order results."""
+        self._order_by = f"{field} {'DESC' if desc else 'ASC'}"
+        return self
+
+    def limit(self, limit: int) -> AgentSessionQuery:
+        """Limit number of results."""
+        self._limit = limit
+        return self
+
+    def offset(self, offset: int) -> AgentSessionQuery:
+        """Offset for pagination."""
+        self._offset = offset
+        return self
+
+    async def execute(self) -> list[AgentSession]:
+        """Execute query and return results."""
+        params: dict[str, Any] = {}
+        
+        if "org_id" in self._filters:
+            # org_id is implicit from API key, so we don't need to pass it
+            pass
+        if "user_id" in self._filters:
+            params["user_id"] = str(self._filters["user_id"])
+        if "status" in self._filters:
+            params["status"] = self._filters["status"]
+        if "created_after" in self._filters:
+            params["created_after"] = self._filters["created_after"].isoformat()
+        if "created_before" in self._filters:
+            params["created_before"] = self._filters["created_before"].isoformat()
+        if "limit_exceeded" in self._filters and self._filters["limit_exceeded"]:
+            params["status"] = "limit_exceeded"
+        if "tracing_session_id" in self._filters:
+            params["tracing_session_id"] = self._filters["tracing_session_id"]
+        
+        if self._limit:
+            params["limit"] = self._limit
+        if self._offset:
+            params["offset"] = self._offset
+        
+        # Use client's list method
+        return await self._client.list(**params)
+
+    async def count(self) -> int:
+        """Get count of matching sessions."""
+        results = await self.execute()
+        return len(results)
+
+    async def first(self) -> Optional[AgentSession]:
+        """Get first matching session."""
+        results = await self.limit(1).execute()
+        return results[0] if results else None
+