amigo_sdk 0.62.0__py3-none-any.whl

amigo_sdk/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "0.62.0"
+from .sdk_client import AmigoClient, AsyncAmigoClient
+
+__all__ = ["__version__", "AmigoClient", "AsyncAmigoClient"]

amigo_sdk/_retry_utils.py

@@ -0,0 +1,70 @@
+import datetime as dt
+import random
+from email.utils import parsedate_to_datetime
+from typing import Optional
+
+DEFAULT_RETRYABLE_STATUS: set[int] = {429, 500, 502, 503, 504}
+
+
+def parse_retry_after_seconds(retry_after: Optional[str]) -> float | None:
+    """Parse Retry-After header into seconds.
+
+    Supports both numeric seconds and HTTP-date formats. Returns None when
+    header is missing or invalid.
+    """
+    if not retry_after:
+        return None
+    # Numeric seconds
+    try:
+        seconds = float(retry_after)
+        return max(0.0, seconds)
+    except Exception:
+        pass
+    # HTTP-date format
+    try:
+        target_dt = parsedate_to_datetime(retry_after)
+        if target_dt is None:
+            return None
+        if target_dt.tzinfo is None:
+            target_dt = target_dt.replace(tzinfo=dt.UTC)
+        now = dt.datetime.now(dt.UTC)
+        delta_seconds = (target_dt - now).total_seconds()
+        return max(0.0, delta_seconds)
+    except Exception:
+        return None
+
+
+def is_retryable_response(
+    method: str,
+    status_code: int,
+    headers: dict,
+    retry_on_methods: set[str],
+    retry_on_status: set[int],
+) -> bool:
+    """Determine if the response is retryable under our policy.
+
+    Special case: allow POST retry only on 429 when Retry-After is present.
+    """
+    method_upper = method.upper()
+    if method_upper == "POST" and status_code == 429 and headers.get("Retry-After"):
+        return True
+    return method_upper in retry_on_methods and status_code in retry_on_status
+
+
+def compute_retry_delay_seconds(
+    attempt: int,
+    backoff_base: float,
+    max_delay_seconds: float,
+    retry_after_header: Optional[str],
+) -> float:
+    """Compute delay for a given retry attempt.
+
+    If Retry-After is present, honor it (clamped by max). Otherwise, use
+    exponential backoff with full jitter.
+    """
+    ra_seconds = parse_retry_after_seconds(retry_after_header)
+    if ra_seconds is not None:
+        return min(max_delay_seconds, ra_seconds)
+    window = backoff_base * (2 ** (attempt - 1))
+    window = min(window, max_delay_seconds)
+    return random.uniform(0.0, window)

amigo_sdk/auth.py

@@ -0,0 +1,48 @@
+import httpx
+
+from amigo_sdk.config import AmigoConfig
+from amigo_sdk.errors import AuthenticationError
+from amigo_sdk.generated.model import UserSignInWithApiKeyResponse
+
+
+def _signin_url_headers(cfg: AmigoConfig) -> tuple[str, dict[str, str]]:
+    url = f"{cfg.base_url}/v1/{cfg.organization_id}/user/signin_with_api_key"
+    headers = {
+        "x-api-key": cfg.api_key,
+        "x-api-key-id": cfg.api_key_id,
+        "x-user-id": cfg.user_id,
+    }
+    return url, headers
+
+
+def _parse_signin_response_text(
+    response: httpx.Response,
+) -> UserSignInWithApiKeyResponse:
+    try:
+        return UserSignInWithApiKeyResponse.model_validate_json(response.text)
+    except Exception as e:
+        raise AuthenticationError(f"Invalid response format: {e}") from e
+
+
+def sign_in_with_api_key(cfg: AmigoConfig) -> UserSignInWithApiKeyResponse:
+    """Sign in with API key (sync)."""
+    url, headers = _signin_url_headers(cfg)
+    with httpx.Client() as client:
+        try:
+            response = client.post(url, headers=headers)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise AuthenticationError(f"Sign in with API key failed: {e}") from e
+        return _parse_signin_response_text(response)
+
+
+async def sign_in_with_api_key_async(cfg: AmigoConfig) -> UserSignInWithApiKeyResponse:
+    """Sign in with API key (async)."""
+    url, headers = _signin_url_headers(cfg)
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(url, headers=headers)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise AuthenticationError(f"Sign in with API key failed: {e}") from e
+        return _parse_signin_response_text(response)

amigo_sdk/config.py

@@ -0,0 +1,48 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class AmigoConfig(BaseSettings):
+    """
+    Configuration for the Amigo API client.
+
+    Can be configured via three methods (in order of precedence):
+    1. Constructor parameters (highest precedence)
+    2. Environment variables with AMIGO_ prefix
+    3. .env file in the current working directory (lowest precedence)
+
+    Environment variables:
+    - AMIGO_API_KEY
+    - AMIGO_API_KEY_ID
+    - AMIGO_USER_ID
+    - AMIGO_BASE_URL
+    - AMIGO_ORGANIZATION_ID
+
+    Example .env file:
+    ```
+    AMIGO_API_KEY=your_api_key_here
+    AMIGO_API_KEY_ID=your_api_key_id_here
+    AMIGO_USER_ID=your_user_id_here
+    AMIGO_ORGANIZATION_ID=your_org_id_here
+    AMIGO_BASE_URL=https://api.amigo.ai
+    ```
+    """
+
+    api_key: str = Field(..., description="API key for authentication")
+    api_key_id: str = Field(..., description="API key ID for authentication")
+    user_id: str = Field(..., description="User ID for API requests")
+    organization_id: str = Field(..., description="Organization ID for API requests")
+    base_url: str = Field(
+        default="https://api.amigo.ai",
+        description="Base URL for the Amigo API",
+    )
+
+    model_config = {
+        "env_prefix": "AMIGO_",
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "case_sensitive": False,
+        "validate_assignment": True,
+        "frozen": True,
+        "extra": "ignore",  # Ignore extra fields in .env file
+    }

amigo_sdk/errors.py

@@ -0,0 +1,163 @@
+from typing import Any, Optional
+
+
+class AmigoError(Exception):
+    """
+    Base class for Amigo API errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        response_body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        return " ".join(parts)
+
+
+# ---- 4xx client errors ------------------------------------------------------
+class BadRequestError(AmigoError):  # 400
+    pass
+
+
+class AuthenticationError(AmigoError):  # 401
+    pass
+
+
+class PermissionError(AmigoError):  # 403
+    pass
+
+
+class NotFoundError(AmigoError):  # 404
+    pass
+
+
+class ConflictError(AmigoError):  # 409
+    pass
+
+
+class RateLimitError(AmigoError):  # 429
+    pass
+
+
+# ---- Validation / semantic errors ------------------------------------------
+class ValidationError(BadRequestError):  # 422 or 400 with `errors` list
+    def __init__(self, *args, field_errors: Optional[dict[str, str]] = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.field_errors = field_errors or {}
+
+
+# ---- 5xx server errors ------------------------------------------------------
+class ServerError(AmigoError):  # 500
+    pass
+
+
+class ServiceUnavailableError(ServerError):  # 503 / maintenance
+    pass
+
+
+# ---- Internal SDK issues ----------------------------------------------------
+class SDKInternalError(AmigoError):
+    """JSON decoding failure, Pydantic model mismatch, etc."""
+
+
+# ---- Status code mapping ----------------------------------------------------
+def get_error_class_for_status_code(status_code: int) -> type[AmigoError]:
+    """Map HTTP status codes to appropriate AmigoError classes."""
+    error_map = {
+        400: BadRequestError,
+        401: AuthenticationError,
+        403: PermissionError,
+        404: NotFoundError,
+        409: ConflictError,
+        422: ValidationError,
+        429: RateLimitError,
+        500: ServerError,
+        503: ServiceUnavailableError,
+    }
+
+    # Default to appropriate base class for status code ranges
+    if status_code in error_map:
+        return error_map[status_code]
+    elif 400 <= status_code < 500:
+        return BadRequestError
+    elif 500 <= status_code < 600:
+        return ServerError
+    else:
+        return AmigoError
+
+
+def raise_for_status(response, message: str = None) -> None:
+    """
+    Raise an appropriate AmigoError for non-2xx status codes.
+
+    Args:
+        response: httpx.Response object
+        message: Optional custom error message
+    """
+    if response.is_success:
+        return
+
+    status_code = response.status_code
+    error_class = get_error_class_for_status_code(status_code)
+
+    # Try to extract error details from response
+    error_code = None
+    response_body = None
+
+    try:
+        response_body = response.json()
+        # Try to extract error code if it exists in response
+        if isinstance(response_body, dict):
+            error_code = response_body.get("error_code") or response_body.get("code")
+    except Exception:
+        # If JSON parsing fails, use text content
+        try:
+            response_body = response.text
+        except Exception:
+            response_body = None
+
+    # Use provided message or generate default
+    if not message:
+        message = f"HTTP {status_code} error"
+        if isinstance(response_body, dict):
+            # Prefer common API error fields, including FastAPI's "detail"
+            for key in ("message", "error", "detail"):
+                api_message = response_body.get(key)
+                if api_message:
+                    message = str(api_message)
+                    break
+        elif isinstance(response_body, str) and response_body.strip():
+            # If the server returned a plain-text or JSON string body, surface it
+            message = response_body.strip()
+
+    # Handle ValidationError special case for field errors
+    if error_class == ValidationError and isinstance(response_body, dict):
+        field_errors = response_body.get("errors") or response_body.get("field_errors")
+        raise error_class(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            response_body=response_body,
+            field_errors=field_errors,
+        )
+    else:
+        raise error_class(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            response_body=response_body,
+        )