amigo_sdk 0.1.1__py3-none-any.whl

amigo_sdk/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

amigo_sdk/auth.py

@@ -0,0 +1,30 @@
+import httpx
+
+from amigo_sdk.config import AmigoConfig
+from amigo_sdk.errors import AuthenticationError
+from amigo_sdk.generated.model import UserSignInWithApiKeyResponse
+
+
+async def sign_in_with_api_key(
+    cfg: AmigoConfig,
+) -> UserSignInWithApiKeyResponse:
+    """
+    Sign in with API key.
+    """
+    async with httpx.AsyncClient() as client:
+        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,
+        }
+        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
+
+        try:
+            return UserSignInWithApiKeyResponse.model_validate_json(response.text)
+        except Exception as e:
+            raise AuthenticationError(f"Invalid response format: {e}") from e

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,
+        )