synth-ai 0.2.14__py3-none-any.whl → 0.4.1__py3-none-any.whl

synth_ai/sdk/usage/client.py

@@ -0,0 +1,171 @@
+"""Usage client for fetching org usage and limits.
+
+This module provides the UsageClient class that communicates with the
+Synth backend to fetch usage data and check limits.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from synth_ai.core.errors import UsageLimitError
+from synth_ai.core.http import AsyncHttpClient, http_request
+
+from .models import OrgUsage, UsageMetric
+
+
+def _get_base_url() -> str:
+    """Get the backend base URL from environment."""
+    return os.getenv("BACKEND_BASE_URL", "https://api.usesynth.ai")
+
+
+def _get_api_key() -> str:
+    """Get the API key from environment."""
+    return os.getenv("SYNTH_API_KEY", "")
+
+
+class UsageClient:
+    """Client for fetching org usage and limits.
+
+    Usage:
+        # Sync usage
+        client = UsageClient()
+        usage = client.get()
+        print(usage.tier)
+        print(usage.apis.inference.tokens_per_day.remaining)
+
+        # Async usage
+        async with UsageClient() as client:
+            usage = await client.get_async()
+
+        # Check a specific limit
+        client.check("prompt_opt", "jobs_per_day")  # raises UsageLimitError if exhausted
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        """Initialize the usage client.
+
+        Args:
+            base_url: Backend URL (defaults to BACKEND_BASE_URL env var)
+            api_key: API key (defaults to SYNTH_API_KEY env var)
+        """
+        self._base_url = base_url or _get_base_url()
+        self._api_key = api_key or _get_api_key()
+        self._async_client: AsyncHttpClient | None = None
+
+    async def __aenter__(self) -> UsageClient:
+        """Enter async context."""
+        self._async_client = AsyncHttpClient(self._base_url, self._api_key)
+        await self._async_client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: Any,
+    ) -> None:
+        """Exit async context."""
+        if self._async_client is not None:
+            await self._async_client.__aexit__(exc_type, exc, tb)
+            self._async_client = None
+
+    def get(self) -> OrgUsage:
+        """Fetch current usage (synchronous).
+
+        Returns:
+            OrgUsage object with all usage metrics and limits
+
+        Raises:
+            HTTPError: If the API request fails
+        """
+        url = f"{self._base_url}/api/v1/usage"
+        headers = {"authorization": f"Bearer {self._api_key}"}
+        status, data = http_request("GET", url, headers=headers)
+
+        if status != 200:
+            from synth_ai.core.errors import HTTPError
+            raise HTTPError(
+                status=status,
+                url=url,
+                message="Failed to fetch usage",
+                detail=data if isinstance(data, dict) else None,
+            )
+
+        if isinstance(data, dict):
+            return OrgUsage.from_dict(data)
+        raise ValueError(f"Unexpected response type: {type(data)}")
+
+    async def get_async(self) -> OrgUsage:
+        """Fetch current usage (asynchronous).
+
+        Returns:
+            OrgUsage object with all usage metrics and limits
+
+        Raises:
+            HTTPError: If the API request fails
+        """
+        if self._async_client is None:
+            raise RuntimeError("Must use as async context manager")
+
+        data = await self._async_client.get("/api/v1/usage")
+        return OrgUsage.from_dict(data)
+
+    def check(self, api: str, metric: str) -> UsageMetric:
+        """Check if a specific limit has capacity remaining.
+
+        Args:
+            api: API name (inference, judges, prompt_opt, rl, sft, research)
+            metric: Metric name (e.g., requests_per_min, jobs_per_day)
+
+        Returns:
+            The UsageMetric if capacity is available
+
+        Raises:
+            UsageLimitError: If the limit is exhausted
+            ValueError: If the api/metric combination is invalid
+        """
+        usage = self.get()
+        return self._check_metric(usage, api, metric)
+
+    async def check_async(self, api: str, metric: str) -> UsageMetric:
+        """Check if a specific limit has capacity remaining (async).
+
+        Args:
+            api: API name (inference, judges, prompt_opt, rl, sft, research)
+            metric: Metric name (e.g., requests_per_min, jobs_per_day)
+
+        Returns:
+            The UsageMetric if capacity is available
+
+        Raises:
+            UsageLimitError: If the limit is exhausted
+            ValueError: If the api/metric combination is invalid
+        """
+        usage = await self.get_async()
+        return self._check_metric(usage, api, metric)
+
+    def _check_metric(self, usage: OrgUsage, api: str, metric: str) -> UsageMetric:
+        """Internal method to check a metric and raise if exhausted."""
+        m = usage.get_metric(api, metric)
+        if m is None:
+            raise ValueError(f"Unknown api/metric: {api}/{metric}")
+
+        if m.is_exhausted:
+            raise UsageLimitError(
+                limit_type=metric,
+                api=api,
+                current=m.used,
+                limit=m.limit,
+                tier=usage.tier,
+            )
+
+        return m
+
+
+__all__ = ["UsageClient"]

synth_ai/sdk/usage/models.py

@@ -0,0 +1,261 @@
+"""Data models for usage tracking.
+
+These dataclasses represent the usage and limits data returned by the
+GET /api/v1/usage endpoint.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class UsageMetric:
+    """A single usage metric with its limit and remaining capacity.
+
+    Attributes:
+        used: Current usage value
+        limit: Maximum allowed value
+        remaining: Remaining capacity (limit - used)
+    """
+
+    used: int | float
+    limit: int | float
+    remaining: int | float
+
+    @property
+    def percent_used(self) -> float:
+        """Return percentage of limit used (0-100)."""
+        if self.limit == 0:
+            return 0.0
+        return (self.used / self.limit) * 100
+
+    @property
+    def is_exhausted(self) -> bool:
+        """Return True if the limit has been reached."""
+        return self.remaining <= 0
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> UsageMetric:
+        """Create from API response dict."""
+        return cls(
+            used=data.get("used", 0),
+            limit=data.get("limit", 0),
+            remaining=data.get("remaining", 0),
+        )
+
+
+@dataclass
+class UsagePeriod:
+    """Time period for usage tracking."""
+
+    daily_start: datetime
+    monthly_start: datetime
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> UsagePeriod:
+        """Create from API response dict."""
+        return cls(
+            daily_start=datetime.fromisoformat(data["daily_start"].replace("Z", "+00:00")),
+            monthly_start=datetime.fromisoformat(data["monthly_start"].replace("Z", "+00:00")),
+        )
+
+
+@dataclass
+class InferenceUsage:
+    """Usage metrics for the inference API."""
+
+    requests_per_min: UsageMetric
+    tokens_per_day: UsageMetric
+    spend_cents_per_month: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> InferenceUsage:
+        """Create from API response dict."""
+        return cls(
+            requests_per_min=UsageMetric.from_dict(data.get("requests_per_min", {})),
+            tokens_per_day=UsageMetric.from_dict(data.get("tokens_per_day", {})),
+            spend_cents_per_month=UsageMetric.from_dict(data.get("spend_cents_per_month", {})),
+        )
+
+
+@dataclass
+class JudgesUsage:
+    """Usage metrics for the judges API."""
+
+    evaluations_per_day: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> JudgesUsage:
+        """Create from API response dict."""
+        return cls(
+            evaluations_per_day=UsageMetric.from_dict(data.get("evaluations_per_day", {})),
+        )
+
+
+@dataclass
+class PromptOptUsage:
+    """Usage metrics for prompt optimization (GEPA/MIPRO)."""
+
+    jobs_per_day: UsageMetric
+    rollouts_per_day: UsageMetric
+    spend_cents_per_day: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PromptOptUsage:
+        """Create from API response dict."""
+        return cls(
+            jobs_per_day=UsageMetric.from_dict(data.get("jobs_per_day", {})),
+            rollouts_per_day=UsageMetric.from_dict(data.get("rollouts_per_day", {})),
+            spend_cents_per_day=UsageMetric.from_dict(data.get("spend_cents_per_day", {})),
+        )
+
+
+@dataclass
+class RLUsage:
+    """Usage metrics for RL training."""
+
+    jobs_per_month: UsageMetric
+    gpu_hours_per_month: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RLUsage:
+        """Create from API response dict."""
+        return cls(
+            jobs_per_month=UsageMetric.from_dict(data.get("jobs_per_month", {})),
+            gpu_hours_per_month=UsageMetric.from_dict(data.get("gpu_hours_per_month", {})),
+        )
+
+
+@dataclass
+class SFTUsage:
+    """Usage metrics for SFT training."""
+
+    jobs_per_month: UsageMetric
+    gpu_hours_per_month: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SFTUsage:
+        """Create from API response dict."""
+        return cls(
+            jobs_per_month=UsageMetric.from_dict(data.get("jobs_per_month", {})),
+            gpu_hours_per_month=UsageMetric.from_dict(data.get("gpu_hours_per_month", {})),
+        )
+
+
+@dataclass
+class ResearchUsage:
+    """Usage metrics for research agents."""
+
+    jobs_per_month: UsageMetric
+    agent_spend_cents_per_month: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ResearchUsage:
+        """Create from API response dict."""
+        return cls(
+            jobs_per_month=UsageMetric.from_dict(data.get("jobs_per_month", {})),
+            agent_spend_cents_per_month=UsageMetric.from_dict(data.get("agent_spend_cents_per_month", {})),
+        )
+
+
+@dataclass
+class TotalUsage:
+    """Total usage across all APIs."""
+
+    spend_cents_per_month: UsageMetric
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TotalUsage:
+        """Create from API response dict."""
+        return cls(
+            spend_cents_per_month=UsageMetric.from_dict(data.get("spend_cents_per_month", {})),
+        )
+
+
+@dataclass
+class APIUsage:
+    """Container for all API usage metrics."""
+
+    inference: InferenceUsage
+    judges: JudgesUsage
+    prompt_opt: PromptOptUsage
+    rl: RLUsage
+    sft: SFTUsage
+    research: ResearchUsage
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> APIUsage:
+        """Create from API response dict."""
+        return cls(
+            inference=InferenceUsage.from_dict(data.get("inference", {})),
+            judges=JudgesUsage.from_dict(data.get("judges", {})),
+            prompt_opt=PromptOptUsage.from_dict(data.get("prompt_opt", {})),
+            rl=RLUsage.from_dict(data.get("rl", {})),
+            sft=SFTUsage.from_dict(data.get("sft", {})),
+            research=ResearchUsage.from_dict(data.get("research", {})),
+        )
+
+
+@dataclass
+class OrgUsage:
+    """Complete org usage report.
+
+    This is the top-level object returned by UsageClient.get().
+
+    Attributes:
+        org_id: The organization ID
+        tier: The org's tier (free, starter, growth, enterprise)
+        period: Time period info for daily/monthly resets
+        apis: Per-API usage metrics
+        totals: Aggregate totals across all APIs
+    """
+
+    org_id: str
+    tier: str
+    period: UsagePeriod
+    apis: APIUsage
+    totals: TotalUsage
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OrgUsage:
+        """Create from API response dict."""
+        return cls(
+            org_id=data.get("org_id", ""),
+            tier=data.get("tier", "free"),
+            period=UsagePeriod.from_dict(data.get("period", {})),
+            apis=APIUsage.from_dict(data.get("apis", {})),
+            totals=TotalUsage.from_dict(data.get("totals", {})),
+        )
+
+    def get_metric(self, api: str, metric: str) -> UsageMetric | None:
+        """Get a specific metric by API and metric name.
+
+        Args:
+            api: API name (inference, judges, prompt_opt, rl, sft, research)
+            metric: Metric name (e.g., requests_per_min, jobs_per_day)
+
+        Returns:
+            UsageMetric if found, None otherwise
+        """
+        api_usage = getattr(self.apis, api, None)
+        if api_usage is None:
+            return None
+        return getattr(api_usage, metric, None)
+
+
+__all__ = [
+    "UsageMetric",
+    "UsagePeriod",
+    "InferenceUsage",
+    "JudgesUsage",
+    "PromptOptUsage",
+    "RLUsage",
+    "SFTUsage",
+    "ResearchUsage",
+    "TotalUsage",
+    "APIUsage",
+    "OrgUsage",
+]

synth_ai/utils/__init__.py

@@ -0,0 +1,213 @@
+"""
+Backward compatibility re-exports for synth_ai.utils.
+
+All utilities have been reorganized:
+- Core utilities → synth_ai.core.*
+- CLI utilities → synth_ai.cli.lib.*
+
+This module provides lazy imports to avoid circular import issues.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Direct imports from core (no circular dependency risk)
+from synth_ai.core import task_app_state
+from synth_ai.core.env import PROD_BASE_URL_DEFAULT, get_backend_from_env
+from synth_ai.core.http import AsyncHttpClient, HTTPError, http_request
+from synth_ai.core.json import create_and_write_json, load_json_to_dict, strip_json_comments
+from synth_ai.core.paths import (
+    REPO_ROOT,
+    cleanup_paths,
+    configure_import_paths,
+    find_config_path,
+    get_bin_path,
+    get_env_file_paths,
+    get_home_config_file_paths,
+    is_hidden_path,
+)
+from synth_ai.core.process import (
+    ensure_local_port_available,
+    popen_capture,
+    popen_stream,
+    popen_stream_capture,
+)
+from synth_ai.core.task_app_state import (
+    DEFAULT_TASK_APP_SECRET_NAME,
+    current_task_app_id,
+    load_demo_dir,
+    load_template_id,
+    now_iso,
+    persist_api_key,
+    persist_demo_dir,
+    persist_env_api_key,
+    persist_task_url,
+    persist_template_id,
+    read_task_app_config,
+    record_task_app,
+    resolve_task_app_entry,
+    task_app_config_path,
+    task_app_id_from_path,
+    update_task_app_entry,
+    write_task_app_config,
+)
+from synth_ai.core.telemetry import (
+    flush_logger,
+    log_batch,
+    log_error,
+    log_event,
+    log_info,
+    log_warning,
+)
+from synth_ai.core.user_config import (
+    USER_CONFIG_PATH,
+    load_user_config,
+    load_user_env,
+    save_user_config,
+    update_user_config,
+)
+
+# Lazy imports for CLI utilities to avoid circular imports
+_CLI_IMPORTS = {
+    # From cli.lib.agents
+    "write_agents_md": ("synth_ai.cli.lib.agents", "write_agents_md"),
+    # From core.apps.common
+    "extract_routes_from_app": ("synth_ai.core.apps.common", "extract_routes_from_app"),
+    "get_asgi_app": ("synth_ai.core.apps.common", "get_asgi_app"),
+    "load_module": ("synth_ai.core.apps.common", "load_module"),
+    # From cli.lib.bin
+    "install_bin": ("synth_ai.cli.lib.bin", "install_bin"),
+    "verify_bin": ("synth_ai.cli.lib.bin", "verify_bin"),
+    # From cli.lib.env
+    "mask_str": ("synth_ai.cli.lib.env", "mask_str"),
+    "read_env_var_from_file": ("synth_ai.cli.lib.env", "read_env_var_from_file"),
+    "resolve_env_var": ("synth_ai.cli.lib.env", "resolve_env_var"),
+    "write_env_var_to_dotenv": ("synth_ai.cli.lib.env", "write_env_var_to_dotenv"),
+    "write_env_var_to_json": ("synth_ai.cli.lib.env", "write_env_var_to_json"),
+    # From cli.lib.modal
+    "ensure_modal_installed": ("synth_ai.cli.lib.modal", "ensure_modal_installed"),
+    "ensure_task_app_ready": ("synth_ai.cli.lib.modal", "ensure_task_app_ready"),
+    "find_asgi_apps": ("synth_ai.cli.lib.modal", "find_asgi_apps"),
+    "is_local_demo_url": ("synth_ai.cli.lib.modal", "is_local_demo_url"),
+    "is_modal_public_url": ("synth_ai.cli.lib.modal", "is_modal_public_url"),
+    "normalize_endpoint_url": ("synth_ai.cli.lib.modal", "normalize_endpoint_url"),
+    # From cli.lib.prompts
+    "PromptedChoiceOption": ("synth_ai.cli.lib.prompts", "PromptedChoiceOption"),
+    "PromptedChoiceType": ("synth_ai.cli.lib.prompts", "PromptedChoiceType"),
+    "PromptedPathOption": ("synth_ai.cli.lib.prompts", "PromptedPathOption"),
+    "ctx_print": ("synth_ai.cli.lib.prompts", "ctx_print"),
+    "prompt_choice": ("synth_ai.cli.lib.prompts", "prompt_choice"),
+    "prompt_for_path": ("synth_ai.cli.lib.prompts", "prompt_for_path"),
+    # From cli.lib.sqld
+    "SQLD_VERSION": ("synth_ai.cli.lib.sqld", "SQLD_VERSION"),
+    "find_sqld_binary": ("synth_ai.cli.lib.sqld", "find_sqld_binary"),
+    "install_sqld": ("synth_ai.cli.lib.sqld", "install_sqld"),
+    # From cli.lib.task_app_discovery
+    "AppChoice": ("synth_ai.cli.lib.task_app_discovery", "AppChoice"),
+    "discover_eval_config_paths": ("synth_ai.cli.lib.task_app_discovery", "discover_eval_config_paths"),
+    "select_app_choice": ("synth_ai.cli.lib.task_app_discovery", "select_app_choice"),
+    # From cli.lib.task_app_env
+    "ensure_env_credentials": ("synth_ai.cli.lib.task_app_env", "ensure_env_credentials"),
+    "ensure_port_free": ("synth_ai.cli.lib.task_app_env", "ensure_port_free"),
+    "preflight_env_key": ("synth_ai.cli.lib.task_app_env", "preflight_env_key"),
+    # From core.integrations.mcp.claude
+    "ClaudeConfig": ("synth_ai.core.integrations.mcp.claude", "ClaudeConfig"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _CLI_IMPORTS:
+        module_name, attr_name = _CLI_IMPORTS[name]
+        import importlib
+        module = importlib.import_module(module_name)
+        return getattr(module, attr_name)
+    raise AttributeError(f"module 'synth_ai.utils' has no attribute '{name}'")
+
+
+__all__ = [
+    # Core
+    "AsyncHttpClient",
+    "ClaudeConfig",
+    "DEFAULT_TASK_APP_SECRET_NAME",
+    "HTTPError",
+    "PROD_BASE_URL_DEFAULT",
+    "REPO_ROOT",
+    "USER_CONFIG_PATH",
+    "cleanup_paths",
+    "configure_import_paths",
+    "create_and_write_json",
+    "current_task_app_id",
+    "ensure_local_port_available",
+    "find_config_path",
+    "flush_logger",
+    "get_backend_from_env",
+    "get_bin_path",
+    "get_env_file_paths",
+    "get_home_config_file_paths",
+    "http_request",
+    "is_hidden_path",
+    "load_demo_dir",
+    "load_json_to_dict",
+    "load_template_id",
+    "load_user_config",
+    "load_user_env",
+    "log_batch",
+    "log_error",
+    "log_event",
+    "log_info",
+    "log_warning",
+    "now_iso",
+    "persist_api_key",
+    "persist_demo_dir",
+    "persist_env_api_key",
+    "persist_task_url",
+    "persist_template_id",
+    "popen_capture",
+    "popen_stream",
+    "popen_stream_capture",
+    "read_task_app_config",
+    "record_task_app",
+    "resolve_task_app_entry",
+    "save_user_config",
+    "strip_json_comments",
+    "task_app_config_path",
+    "task_app_id_from_path",
+    "task_app_state",
+    "update_task_app_entry",
+    "update_user_config",
+    "write_task_app_config",
+    # CLI (lazy)
+    "AppChoice",
+    "PromptedChoiceOption",
+    "PromptedChoiceType",
+    "PromptedPathOption",
+    "SQLD_VERSION",
+    "ctx_print",
+    "discover_eval_config_paths",
+    "ensure_env_credentials",
+    "ensure_modal_installed",
+    "ensure_port_free",
+    "ensure_task_app_ready",
+    "extract_routes_from_app",
+    "find_asgi_apps",
+    "find_sqld_binary",
+    "get_asgi_app",
+    "install_bin",
+    "install_sqld",
+    "is_local_demo_url",
+    "is_modal_public_url",
+    "load_module",
+    "mask_str",
+    "normalize_endpoint_url",
+    "preflight_env_key",
+    "prompt_choice",
+    "prompt_for_path",
+    "read_env_var_from_file",
+    "resolve_env_var",
+    "select_app_choice",
+    "verify_bin",
+    "write_agents_md",
+    "write_env_var_to_dotenv",
+    "write_env_var_to_json",
+]