solwyn 0.1.0__py3-none-any.whl

solwyn/__init__.py

@@ -0,0 +1,33 @@
+"""Solwyn -- AI Agent Control Plane SDK.
+
+Drop-in wrapper for ``openai.OpenAI`` and ``anthropic.Anthropic`` clients
+that adds hard spending caps, automatic provider failover, and per-agent
+cost attribution -- without ever seeing customer prompts.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("solwyn")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+from solwyn.client import AsyncSolwyn, Solwyn
+from solwyn.config import SolwynConfig
+from solwyn.exceptions import (
+    BudgetExceededError,
+    ConfigurationError,
+    ProviderUnavailableError,
+    SolwynError,
+)
+
+__all__ = [
+    "__version__",
+    "Solwyn",
+    "AsyncSolwyn",
+    "SolwynConfig",
+    "SolwynError",
+    "BudgetExceededError",
+    "ProviderUnavailableError",
+    "ConfigurationError",
+]

solwyn/_base.py

@@ -0,0 +1,133 @@
+"""Shared sans-I/O logic for Solwyn clients.
+
+Contains _SolwynBase with config, budget logic, metadata formatting,
+and pricing calculations. No I/O -- sync and async clients inherit
+from this and add their own HTTP layer.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from solwyn._token_details import TokenDetails
+from solwyn._types import CallStatus, MetadataEvent, ProviderName
+from solwyn.circuit_breaker import CircuitBreaker
+from solwyn.config import SolwynConfig
+from solwyn.exceptions import ProviderUnavailableError
+from solwyn.tokenizer import TokenizerManager
+
+
+class _SolwynBase:
+    """Shared sans-I/O base class for Solwyn sync and async clients.
+
+    Provides:
+    - Token estimation and cost calculation
+    - Metadata event construction
+    - Budget request construction
+    - Circuit breaker management and provider selection
+    - SDK instance identity
+    """
+
+    def __init__(self, config: SolwynConfig) -> None:
+        self._config = config
+        self._sdk_instance_id = str(uuid.uuid4())
+        self._tokenizer = TokenizerManager()
+
+        # One circuit breaker per configured provider
+        self._circuit_breakers: dict[str, CircuitBreaker] = {}
+        self._circuit_breakers[config.primary_provider.value] = CircuitBreaker(
+            failure_threshold=config.circuit_breaker_failure_threshold,
+            recovery_timeout=config.circuit_breaker_recovery_timeout,
+            success_threshold=config.circuit_breaker_success_threshold,
+        )
+        if config.fallback_provider is not None:
+            self._circuit_breakers[config.fallback_provider.value] = CircuitBreaker(
+                failure_threshold=config.circuit_breaker_failure_threshold,
+                recovery_timeout=config.circuit_breaker_recovery_timeout,
+                success_threshold=config.circuit_breaker_success_threshold,
+            )
+
+    def _build_metadata_event(
+        self,
+        *,
+        project_id: str,
+        model: str,
+        provider: str,
+        input_tokens: int,
+        output_tokens: int,
+        token_details: TokenDetails | None,
+        latency_ms: float,
+        status: CallStatus,
+        is_failover: bool,
+        sdk_instance_id: str | None = None,
+        timestamp: datetime | None = None,
+    ) -> MetadataEvent:
+        """Build a MetadataEvent for reporting to the cloud API."""
+        return MetadataEvent(
+            project_id=project_id,
+            model=model,
+            provider=ProviderName(provider),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            token_details=token_details,
+            latency_ms=latency_ms,
+            status=status,
+            is_failover=is_failover,
+            sdk_instance_id=sdk_instance_id or self._sdk_instance_id,
+            timestamp=timestamp or datetime.now(UTC),
+        )
+
+    def _get_circuit_breaker(self, provider: str) -> CircuitBreaker:
+        """Get the circuit breaker for a provider.
+
+        Lazily creates a circuit breaker if one doesn't exist for this provider.
+        """
+        if provider not in self._circuit_breakers:
+            self._circuit_breakers[provider] = CircuitBreaker(
+                failure_threshold=self._config.circuit_breaker_failure_threshold,
+                recovery_timeout=self._config.circuit_breaker_recovery_timeout,
+                success_threshold=self._config.circuit_breaker_success_threshold,
+            )
+        return self._circuit_breakers[provider]
+
+    def _select_provider(self) -> str:
+        """Select the best available provider via circuit breaker checks.
+
+        Checks the primary provider first. If its circuit is open and a
+        fallback is configured, checks the fallback. If both are open,
+        raises ProviderUnavailableError.
+
+        Returns:
+            The selected provider name (e.g. "openai" or "anthropic").
+
+        Raises:
+            ProviderUnavailableError: If all providers have open circuits.
+        """
+        primary = self._config.primary_provider.value
+        primary_cb = self._get_circuit_breaker(primary)
+
+        if primary_cb.can_proceed():
+            return primary
+
+        # Primary is open -- try fallback
+        if self._config.fallback_provider is not None:
+            fallback = self._config.fallback_provider.value
+            fallback_cb = self._get_circuit_breaker(fallback)
+
+            if fallback_cb.can_proceed():
+                return fallback
+
+            # Both open
+            raise ProviderUnavailableError(
+                f"All providers unavailable: {primary} and {fallback} circuits are open",
+                provider=primary,
+                circuit_state=primary_cb.state.value,
+            )
+
+        # No fallback configured, primary is open
+        raise ProviderUnavailableError(
+            f"Provider {primary} is unavailable and no fallback is configured",
+            provider=primary,
+            circuit_state=primary_cb.state.value,
+        )

solwyn/_privacy.py

@@ -0,0 +1,93 @@
+"""Private, privacy-sensitive helpers — PRIVACY CRITICAL.
+
+PRIVACY
+=======
+This module is the only place in the SDK that touches customer prompt
+content directly. Code here must obey three rules:
+
+  1. NEVER pass prompt content to a logger (`logger.*`) — not even in
+     a formatted string, not even at DEBUG level. CI enforces this
+     with `tests/unit/test_privacy_firewall.py`.
+  2. NEVER store prompt content on a long-lived object — compute and
+     discard within the current function call.
+  3. NEVER include prompt content in exception arguments. If a
+     computation fails, log `type(exc).__name__` only.
+
+If you add a new helper here, add a corresponding enforcement test.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def estimate_content_length(kwargs: dict[str, Any]) -> int:
+    """Return the total character length of prompt content in kwargs.
+
+    Walks messages/system/contents and sums string lengths WITHOUT
+    concatenating them into a joined string. The returned integer is
+    safe to log — it is not reversible to prompt content.
+
+    Args:
+        kwargs: The LLM call kwargs dict. Handles OpenAI/Anthropic
+            messages, Anthropic system prompt, and Google contents.
+
+    Returns:
+        Total character count (0 if no recognizable content keys).
+    """
+    total = 0
+
+    messages = kwargs.get("messages", [])
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            total += len(content)
+        elif isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict):
+                    text = block.get("text", "")
+                    if isinstance(text, str):
+                        total += len(text)
+
+    system = kwargs.get("system")
+    if isinstance(system, str):
+        total += len(system)
+
+    contents = kwargs.get("contents")
+    if isinstance(contents, str):
+        total += len(contents)
+    elif isinstance(contents, list):
+        for item in contents:
+            if isinstance(item, str):
+                total += len(item)
+            elif isinstance(item, dict):
+                text = item.get("text", "")
+                if isinstance(text, str):
+                    total += len(text)
+
+    return total
+
+
+def estimate_tokens_from_length(char_count: int, provider: str) -> int:
+    """Convert a character count to a token estimate using per-provider ratios.
+
+    These are heuristic ratios that match tiktoken's observed behavior.
+    They are NOT tiktoken-exact — the exact path is intentionally removed
+    because it required materializing the joined prompt text.
+
+    Args:
+        char_count: Number of characters in the prompt content.
+        provider: One of "openai", "anthropic", "google".
+
+    Returns:
+        Estimated token count.
+    """
+    ratio_by_provider = {
+        "openai": 4.0,
+        "anthropic": 3.8,
+        "google": 4.0,
+    }
+    ratio = ratio_by_provider.get(provider, 4.0)
+    return max(1, int(char_count / ratio))

solwyn/_proxies.py

@@ -0,0 +1,165 @@
+"""Provider-specific proxy classes for LLM API interception.
+
+These thin delegation wrappers let ``Solwyn.chat.completions.create()``
+(and the Anthropic/Google equivalents) route through ``_intercepted_call``
+while passing everything else through to the underlying client.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from solwyn._types import ProviderName
+
+if TYPE_CHECKING:
+    from solwyn.client import AsyncSolwyn, Solwyn
+
+
+# ---------------------------------------------------------------------------
+# Sync proxies
+# ---------------------------------------------------------------------------
+
+
+class _SyncChatCompletionsProxy:
+    """Proxy for client.chat.completions that intercepts create()."""
+
+    def __init__(self, solwyn: Solwyn) -> None:
+        self._solwyn = solwyn
+
+    def create(self, **kwargs: Any) -> Any:
+        """Intercept chat.completions.create() with budget/circuit/reporting."""
+        return self._solwyn._intercepted_call(**kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """Pass through non-create attributes to OpenAI's chat.completions."""
+        return getattr(self._solwyn._client.chat.completions, name)
+
+
+class _SyncChatProxy:
+    """Proxy for client.chat that provides .completions.create()."""
+
+    def __init__(self, solwyn: Solwyn) -> None:
+        self._solwyn = solwyn
+        self.completions = _SyncChatCompletionsProxy(solwyn)
+
+    def __getattr__(self, name: str) -> Any:
+        """Pass through non-completions attributes (OpenAI only).
+
+        This proxy is only constructed for OpenAI clients. Any attribute
+        that is not ``completions`` (set in __init__) falls through here.
+        """
+        if self._solwyn._detected_provider == ProviderName.OPENAI:
+            return getattr(self._solwyn._client.chat, name)
+        raise AttributeError(
+            f"'chat.{name}' is not supported. "
+            f"The Solwyn chat proxy is OpenAI-specific; Anthropic uses "
+            f"'messages' and Google uses 'models'."
+        )
+
+
+class _SyncMessagesProxy:
+    """Proxy for client.messages that intercepts create().
+
+    Enables ``client.messages.create()`` (Anthropic's documented API)
+    to go through _intercepted_call instead of __getattr__ pass-through.
+    """
+
+    def __init__(self, solwyn: Solwyn) -> None:
+        self._solwyn = solwyn
+
+    def create(self, **kwargs: Any) -> Any:
+        return self._solwyn._intercepted_call(**kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._solwyn._client.messages, name)
+
+
+class _SyncModelsProxy:
+    """Proxy for client.models that intercepts generate_content() and generate_content_stream().
+
+    Enables ``client.models.generate_content()`` (Google's documented API)
+    to go through _intercepted_call. The generate_content_stream() method
+    passes _force_stream=True so _intercepted_call dispatches to the correct
+    underlying SDK method.
+    """
+
+    def __init__(self, solwyn: Solwyn) -> None:
+        self._solwyn = solwyn
+
+    def generate_content(self, **kwargs: Any) -> Any:
+        return self._solwyn._intercepted_call(**kwargs)
+
+    def generate_content_stream(self, **kwargs: Any) -> Any:
+        return self._solwyn._intercepted_call(_force_stream=True, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._solwyn._client.models, name)
+
+
+# ---------------------------------------------------------------------------
+# Async proxies
+# ---------------------------------------------------------------------------
+
+
+class _AsyncChatCompletionsProxy:
+    """Async proxy for client.chat.completions that intercepts create()."""
+
+    def __init__(self, solwyn: AsyncSolwyn) -> None:
+        self._solwyn = solwyn
+
+    async def create(self, **kwargs: Any) -> Any:
+        """Intercept chat.completions.create() with budget/circuit/reporting."""
+        return await self._solwyn._intercepted_call(**kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """Pass through non-create attributes to OpenAI's chat.completions."""
+        return getattr(self._solwyn._client.chat.completions, name)
+
+
+class _AsyncChatProxy:
+    """Async proxy for client.chat that provides .completions.create()."""
+
+    def __init__(self, solwyn: AsyncSolwyn) -> None:
+        self._solwyn = solwyn
+        self.completions = _AsyncChatCompletionsProxy(solwyn)
+
+    def __getattr__(self, name: str) -> Any:
+        if self._solwyn._detected_provider == ProviderName.OPENAI:
+            return getattr(self._solwyn._client.chat, name)
+        raise AttributeError(
+            f"'chat.{name}' is not supported. "
+            f"The Solwyn chat proxy is OpenAI-specific; Anthropic uses "
+            f"'messages' and Google uses 'models'."
+        )
+
+
+class _AsyncMessagesProxy:
+    """Async proxy for client.messages that intercepts create()."""
+
+    def __init__(self, solwyn: AsyncSolwyn) -> None:
+        self._solwyn = solwyn
+
+    async def create(self, **kwargs: Any) -> Any:
+        return await self._solwyn._intercepted_call(**kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._solwyn._client.messages, name)
+
+
+class _AsyncModelsProxy:
+    """Async proxy for client.models.
+
+    Intercepts generate_content() and generate_content_stream().
+    """
+
+    def __init__(self, solwyn: AsyncSolwyn) -> None:
+        self._solwyn = solwyn
+
+    async def generate_content(self, **kwargs: Any) -> Any:
+        return await self._solwyn._intercepted_call(**kwargs)
+
+    async def generate_content_stream(self, **kwargs: Any) -> Any:
+        return await self._solwyn._intercepted_call(_force_stream=True, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._solwyn._client.models, name)

solwyn/_token_details.py

@@ -0,0 +1,45 @@
+"""TokenDetails — normalized token usage breakdown.
+
+Normalized token usage breakdown for one LLM call.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TokenDetails(BaseModel):
+    """Normalized token usage breakdown for one LLM call.
+
+    Provider adapters populate whichever fields their API exposes; the rest
+    stay at 0.  The API uses this struct to compute exact costs rather than
+    trusting SDK-side estimates.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    input_tokens: int = Field(default=0, ge=0, description="Total input tokens (normalized)")
+    output_tokens: int = Field(default=0, ge=0, description="Total output tokens (normalized)")
+    cached_input_tokens: int = Field(
+        default=0, ge=0, description="Input tokens served from prompt cache"
+    )
+    cache_creation_tokens: int = Field(
+        default=0, ge=0, description="Input tokens written to prompt cache (Anthropic)"
+    )
+    reasoning_tokens: int = Field(
+        default=0, ge=0, description="Tokens used for chain-of-thought / thinking"
+    )
+    audio_input_tokens: int = Field(default=0, ge=0, description="Audio input tokens (OpenAI)")
+    audio_output_tokens: int = Field(default=0, ge=0, description="Audio output tokens (OpenAI)")
+    accepted_prediction_tokens: int = Field(
+        default=0, ge=0, description="Predicted output tokens accepted (OpenAI)"
+    )
+    rejected_prediction_tokens: int = Field(
+        default=0, ge=0, description="Predicted output tokens rejected (OpenAI)"
+    )
+    tool_use_input_tokens: int = Field(
+        default=0, ge=0, description="Tokens used for tool/function definitions (Google)"
+    )
+
+    @property
+    def total_tokens(self) -> int:
+        """Input plus output tokens.  Excluded from serialization."""
+        return self.input_tokens + self.output_tokens

solwyn/_types.py

@@ -0,0 +1,122 @@
+"""Vendored enums and wire-format models for SDK <-> API contracts.
+
+Pydantic models for API request/response contracts.
+Excludes API-internal types: ProjectConfig, ProviderHealth,
+NotificationEventType, Environment, BudgetPeriod.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# TokenDetails lives in a separate module to avoid a circular import:
+# _types -> TokenDetails -> (if merged here) _types.
+from solwyn._token_details import TokenDetails
+
+# ── Enums ────────────────────────────────────────────────────────────────
+
+
+class BudgetMode(StrEnum):
+    """How the SDK reacts when a budget limit is reached."""
+
+    ALERT_ONLY = "alert_only"
+    HARD_DENY = "hard_deny"
+
+
+class CircuitState(StrEnum):
+    """Circuit breaker states for provider health tracking."""
+
+    CLOSED = "closed"  # Normal operation — requests flow through
+    OPEN = "open"  # Failing — reject requests, try fallback
+    HALF_OPEN = "half_open"  # Testing recovery — allow probe requests
+
+
+class ProviderName(StrEnum):
+    """Supported LLM provider identifiers."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+
+
+class CallStatus(StrEnum):
+    """Outcome status for LLM call metadata events."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    BUDGET_DENIED = "budget_denied"
+
+
+# ── Wire-format models ──────────────────────────────────────────────────
+
+
+class MetadataEvent(BaseModel):
+    """Telemetry event sent from SDK to API after each LLM call.
+
+    Contains token/latency metadata only — never prompts, responses, or
+    SDK-computed costs.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    project_id: str = Field(..., description="Project identifier (proj_...)")
+    model: str = Field(..., max_length=100, description="LLM model name (e.g. gpt-4o)")
+    provider: ProviderName = Field(..., description="LLM provider")
+    input_tokens: int = Field(..., ge=0, description="Input token count")
+    output_tokens: int = Field(..., ge=0, description="Output token count")
+    token_details: TokenDetails | None = Field(
+        None, description="Full token breakdown from provider adapter"
+    )
+    latency_ms: float = Field(..., description="End-to-end call latency in ms")
+    status: CallStatus = Field(..., description="Call outcome")
+    is_failover: bool = Field(..., description="Whether this call used a fallback provider")
+    sdk_instance_id: str = Field(..., description="Unique SDK instance identifier")
+    timestamp: datetime = Field(..., description="When the LLM call completed (UTC)")
+
+
+class BudgetCheckRequest(BaseModel):
+    """Pre-flight budget check sent before an LLM call."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    project_id: str = Field(..., description="Project identifier (proj_...)")
+    estimated_input_tokens: int = Field(
+        ..., ge=0, description="Estimated input token count for the pending call"
+    )
+    model: str = Field(..., max_length=100, description="LLM model name")
+    provider: ProviderName = Field(..., description="Target provider")
+
+
+class BudgetCheckResponse(BaseModel):
+    """API response to a budget check request."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    allowed: bool = Field(..., description="Whether the call is within budget")
+    remaining_budget: float = Field(..., description="Remaining budget in USD for current period")
+    reservation_id: str | None = Field(
+        None, description="Budget reservation ID (for cost reconciliation)"
+    )
+    mode: BudgetMode = Field(..., description="Current budget enforcement mode")
+    budget_limit: float = Field(..., description="Total budget limit for current period in USD")
+    current_usage: float = Field(..., description="Current spend in USD for this period")
+    denied_by_period: str | None = Field(
+        ..., description="Which budget period triggered denial (e.g. 'daily')"
+    )
+
+
+class BudgetConfirmRequest(BaseModel):
+    """Post-call budget confirmation sent after an LLM call completes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    reservation_id: str = Field(
+        ..., description="Budget reservation ID returned by BudgetCheckResponse"
+    )
+    model: str = Field(..., max_length=100, description="LLM model name used for the call")
+    token_details: TokenDetails = Field(
+        ..., description="Actual token breakdown from the provider adapter"
+    )

solwyn/_validation.py

@@ -0,0 +1,60 @@
+"""Project ID and API key validation.
+
+API key and project ID format validation.
+
+Security features applied to every validator:
+- Unicode NFC normalization to prevent homograph attacks
+- ASCII-only enforcement to prevent encoding exploits
+- Regex pattern validation for allowed characters
+- Path traversal prevention (reject ``..``, ``/``, ``\\``)
+"""
+
+import re
+import unicodedata
+from typing import Final
+
+PROJECT_ID_PATTERN: Final = re.compile(r"^proj_[a-zA-Z0-9]{8,32}$")
+API_KEY_PATTERN: Final = re.compile(r"^sk_solwyn_[a-zA-Z0-9]{32,64}$")
+
+
+def _security_checks(value: str, label: str) -> str:
+    """Common security checks shared by all validators."""
+    if not value:
+        raise ValueError(f"{label} cannot be empty")
+
+    value = unicodedata.normalize("NFC", value)
+
+    if not value.isascii():
+        raise ValueError(f"Invalid {label}: must contain only ASCII characters")
+
+    if ".." in value or "/" in value or "\\" in value:
+        raise ValueError(f"Invalid {label}: path traversal patterns not allowed")
+
+    return value
+
+
+def validate_project_id(project_id: str) -> str:
+    """Validate and return a project ID (canonical implementation)."""
+    project_id = _security_checks(project_id, "project ID")
+
+    if not PROJECT_ID_PATTERN.match(project_id):
+        display = f"{project_id[:20]}..." if len(project_id) > 20 else project_id
+        raise ValueError(
+            f"Invalid project ID: must match proj_<8-32 alphanumeric chars>. Got: {display}"
+        )
+
+    return project_id
+
+
+def validate_api_key_format(api_key: str) -> str:
+    """Validate and return an API key (format check only — not authentication)."""
+    api_key = _security_checks(api_key, "API key")
+
+    if not API_KEY_PATTERN.match(api_key):
+        display = f"{api_key[:12]}..." if len(api_key) > 12 else "<too short>"
+        raise ValueError(
+            f"Invalid API key format: must match sk_solwyn_<32-64 alphanumeric chars>. "
+            f"Got: {display}"
+        )
+
+    return api_key