amigo_sdk 0.1.1__py3-none-any.whl

amigo_sdk/http_client.py

@@ -0,0 +1,228 @@
+import asyncio
+import datetime as dt
+import random
+from collections.abc import AsyncIterator
+from email.utils import parsedate_to_datetime
+from typing import Any, Optional
+
+import httpx
+
+from amigo_sdk.auth import sign_in_with_api_key
+from amigo_sdk.config import AmigoConfig
+from amigo_sdk.errors import (
+    AuthenticationError,
+    get_error_class_for_status_code,
+    raise_for_status,
+)
+from amigo_sdk.generated.model import UserSignInWithApiKeyResponse
+
+
+class AmigoHttpClient:
+    def __init__(
+        self,
+        cfg: AmigoConfig,
+        *,
+        retry_max_attempts: int = 3,
+        retry_backoff_base: float = 0.25,
+        retry_max_delay_seconds: float = 30.0,
+        retry_on_status: set[int] | None = None,
+        retry_on_methods: set[str] | None = None,
+        **httpx_kwargs: Any,
+    ) -> None:
+        self._cfg = cfg
+        self._token: Optional[UserSignInWithApiKeyResponse] = None
+        self._client = httpx.AsyncClient(
+            base_url=cfg.base_url,
+            **httpx_kwargs,
+        )
+        # Retry configuration
+        self._retry_max_attempts = max(1, retry_max_attempts)
+        self._retry_backoff_base = retry_backoff_base
+        self._retry_max_delay_seconds = max(0.0, retry_max_delay_seconds)
+        self._retry_on_status = retry_on_status or {408, 429, 500, 502, 503, 504}
+        # Default to GET only; POST is handled specially for 429 + Retry-After
+        self._retry_on_methods = {m.upper() for m in (retry_on_methods or {"GET"})}
+
+    def _is_retryable_method(self, method: str) -> bool:
+        return method.upper() in self._retry_on_methods
+
+    def _is_retryable_response(self, method: str, resp: httpx.Response) -> bool:
+        status = resp.status_code
+        # Allow POST retry only for 429 when Retry-After header is present
+        if (
+            method.upper() == "POST"
+            and status == 429
+            and resp.headers.get("Retry-After")
+        ):
+            return True
+        return self._is_retryable_method(method) and status in self._retry_on_status
+
+    def _parse_retry_after_seconds(self, resp: httpx.Response) -> float | None:
+        retry_after = resp.headers.get("Retry-After")
+        if not retry_after:
+            return None
+        # Numeric seconds
+        try:
+            seconds = float(retry_after)
+            return max(0.0, seconds)
+        except ValueError:
+            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 _retry_delay_seconds(self, attempt: int, resp: httpx.Response | None) -> float:
+        # Honor Retry-After when present (numeric or HTTP-date), clamped by max delay
+        if resp is not None:
+            ra_seconds = self._parse_retry_after_seconds(resp)
+            if ra_seconds is not None:
+                return min(self._retry_max_delay_seconds, ra_seconds)
+        # Exponential backoff with full jitter: U(0, min(cap, base * 2^(attempt-1)))
+        window = self._retry_backoff_base * (2 ** (attempt - 1))
+        window = min(window, self._retry_max_delay_seconds)
+        return random.uniform(0.0, window)
+
+    async def _ensure_token(self) -> str:
+        """Fetch or refresh bearer token ~5 min before expiry."""
+        if not self._token or dt.datetime.now(
+            dt.UTC
+        ) > self._token.expires_at - dt.timedelta(minutes=5):
+            try:
+                self._token = await sign_in_with_api_key(self._cfg)
+            except Exception as e:
+                raise AuthenticationError(
+                    "API-key exchange failed",
+                ) from e
+
+        return self._token.id_token
+
+    async def request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        kwargs.setdefault("headers", {})
+        attempt = 1
+
+        while True:
+            kwargs["headers"]["Authorization"] = f"Bearer {await self._ensure_token()}"
+
+            resp: httpx.Response | None = None
+            try:
+                resp = await self._client.request(method, path, **kwargs)
+
+                # On 401 refresh token once and retry immediately
+                if resp.status_code == 401:
+                    self._token = None
+                    kwargs["headers"]["Authorization"] = (
+                        f"Bearer {await self._ensure_token()}"
+                    )
+                    resp = await self._client.request(method, path, **kwargs)
+
+            except (httpx.TimeoutException, httpx.TransportError):
+                # Retry only if method is allowed (e.g., GET); POST not retried for transport/timeouts
+                if (
+                    not self._is_retryable_method(method)
+                    or attempt >= self._retry_max_attempts
+                ):
+                    raise
+                await asyncio.sleep(self._retry_delay_seconds(attempt, None))
+                attempt += 1
+                continue
+
+            # Retry on configured HTTP status codes
+            if (
+                self._is_retryable_response(method, resp)
+                and attempt < self._retry_max_attempts
+            ):
+                await asyncio.sleep(self._retry_delay_seconds(attempt, resp))
+                attempt += 1
+                continue
+
+            # Check response status and raise appropriate errors
+            raise_for_status(resp)
+            return resp
+
+    async def stream_lines(
+        self,
+        method: str,
+        path: str,
+        abort_event: asyncio.Event | None = None,
+        **kwargs,
+    ) -> AsyncIterator[str]:
+        """Stream response lines without buffering the full body.
+
+        - Adds Authorization and sensible streaming headers
+        - Retries once on 401 by refreshing the token
+        - Raises mapped errors for non-2xx without consuming the body
+        """
+        kwargs.setdefault("headers", {})
+        headers = kwargs["headers"]
+        headers["Authorization"] = f"Bearer {await self._ensure_token()}"
+        headers.setdefault("Accept", "application/x-ndjson")
+
+        async def _raise_status_with_body(resp: httpx.Response) -> None:
+            """Ensure response body is buffered, then raise mapped error with details."""
+            if 200 <= resp.status_code < 300:
+                return
+            # Fully buffer the body so raise_for_status() can extract JSON/text safely
+            try:
+                await resp.aread()
+            except Exception:
+                pass
+            # If this is a real httpx.Response, use our rich raise_for_status
+            if hasattr(resp, "is_success"):
+                raise_for_status(resp)
+            # Otherwise, fall back to lightweight error mapping used in tests' mock responses
+            error_class = get_error_class_for_status_code(
+                getattr(resp, "status_code", 0)
+            )
+            raise error_class(
+                f"HTTP {getattr(resp, 'status_code', 'unknown')} error",
+                status_code=getattr(resp, "status_code", None),
+            )
+
+        async def _yield_from_response(resp: httpx.Response) -> AsyncIterator[str]:
+            await _raise_status_with_body(resp)
+            if abort_event and abort_event.is_set():
+                return
+            async for line in resp.aiter_lines():
+                if abort_event and abort_event.is_set():
+                    return
+                line_stripped = line.strip()
+                if not line_stripped:
+                    continue
+                yield line_stripped
+
+        # First attempt
+        if abort_event and abort_event.is_set():
+            return
+        async with self._client.stream(method, path, **kwargs) as resp:
+            if resp.status_code == 401:
+                # Refresh token and retry once
+                self._token = None
+                headers["Authorization"] = f"Bearer {await self._ensure_token()}"
+                if abort_event and abort_event.is_set():
+                    return
+                async with self._client.stream(method, path, **kwargs) as retry_resp:
+                    async for ln in _yield_from_response(retry_resp):
+                        yield ln
+                return
+
+            async for ln in _yield_from_response(resp):
+                yield ln
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # async-context-manager sugar
+    async def __aenter__(self):  # → async with AmigoHTTPClient(...) as http:
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()

amigo_sdk/resources/conversation.py

@@ -0,0 +1,208 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import AnyUrl, BaseModel
+
+from amigo_sdk.generated.model import (
+    ConversationCreateConversationRequest,
+    ConversationCreateConversationResponse,
+    ConversationGenerateConversationStarterRequest,
+    ConversationGenerateConversationStarterResponse,
+    ConversationGetConversationMessagesResponse,
+    ConversationGetConversationsResponse,
+    ConversationGetInteractionInsightsResponse,
+    ConversationInteractWithConversationResponse,
+    ConversationRecommendResponsesForInteractionResponse,
+    CreateConversationParametersQuery,
+    Format,
+    GetConversationMessagesParametersQuery,
+    GetConversationsParametersQuery,
+    InteractWithConversationParametersQuery,
+)
+from amigo_sdk.http_client import AmigoHttpClient
+
+
+class GetMessageSourceResponse(BaseModel):
+    """
+    Response model for the `get_message_source` endpoint.
+    TODO: Remove once the OpenAPI spec contains the correct response model for this endpoint.
+    """
+
+    url: AnyUrl
+    expires_at: datetime
+    content_type: Literal["audio/mpeg", "audio/wav"]
+
+
+class ConversationResource:
+    """Conversation resource for Amigo API operations."""
+
+    def __init__(self, http_client: AmigoHttpClient, organization_id: str) -> None:
+        self._http = http_client
+        self._organization_id = organization_id
+
+    async def create_conversation(
+        self,
+        body: ConversationCreateConversationRequest,
+        params: CreateConversationParametersQuery,
+        abort_event: asyncio.Event | None = None,
+    ) -> "AsyncGenerator[ConversationCreateConversationResponse, None]":
+        """Create a new conversation and stream NDJSON events.
+
+        Returns an async generator yielding `ConversationCreateConversationResponse` events.
+        """
+
+        async def _generator():
+            async for line in self._http.stream_lines(
+                "POST",
+                f"/v1/{self._organization_id}/conversation/",
+                params=params.model_dump(mode="json", exclude_none=True),
+                json=body.model_dump(mode="json", exclude_none=True),
+                headers={"Accept": "application/x-ndjson"},
+                abort_event=abort_event,
+            ):
+                # Each line is a JSON object representing a discriminated union event
+                yield ConversationCreateConversationResponse.model_validate_json(line)
+
+        return _generator()
+
+    async def interact_with_conversation(
+        self,
+        conversation_id: str,
+        params: InteractWithConversationParametersQuery,
+        abort_event: asyncio.Event | None = None,
+        *,
+        text_message: str | None = None,
+        audio_bytes: bytes | None = None,
+        audio_content_type: Literal["audio/mpeg", "audio/wav"] | None = None,
+    ) -> "AsyncGenerator[ConversationInteractWithConversationResponse, None]":
+        """Interact with a conversation and stream NDJSON events.
+
+        Returns an async generator yielding `ConversationInteractWithConversationResponse` events.
+        """
+
+        async def _generator():
+            request_kwargs: dict[str, Any] = {
+                "params": params.model_dump(mode="json", exclude_none=True),
+                "abort_event": abort_event,
+                "headers": {"Accept": "application/x-ndjson"},
+            }
+            # Route based on requested format
+            req_format = getattr(params, "request_format", None)
+            if req_format == Format.text:
+                if text_message is None:
+                    raise ValueError(
+                        "text_message is required when request_format is 'text'"
+                    )
+                text_bytes = text_message.encode("utf-8")
+                request_kwargs["files"] = {
+                    "recorded_message": (
+                        "message.txt",
+                        text_bytes,
+                        "text/plain; charset=utf-8",
+                    )
+                }
+            elif req_format == Format.voice:
+                if audio_bytes is None or audio_content_type is None:
+                    raise ValueError(
+                        "audio_bytes and audio_content_type are required when request_format is 'voice'"
+                    )
+                # Send raw bytes with appropriate content type
+                request_kwargs["content"] = audio_bytes
+                request_kwargs.setdefault("headers", {})
+                request_kwargs["headers"]["Content-Type"] = audio_content_type
+            else:
+                raise ValueError("Unsupported or missing request_format in params")
+
+            async for line in self._http.stream_lines(
+                "POST",
+                f"/v1/{self._organization_id}/conversation/{conversation_id}/interact",
+                **request_kwargs,
+            ):
+                # Each line is a JSON object representing a discriminated union event
+                yield ConversationInteractWithConversationResponse.model_validate_json(
+                    line
+                )
+
+        return _generator()
+
+    async def finish_conversation(self, conversation_id: str) -> None:
+        """Finish a conversation."""
+        await self._http.request(
+            "POST",
+            f"/v1/{self._organization_id}/conversation/{conversation_id}/finish/",
+        )
+
+    async def get_conversations(
+        self, params: GetConversationsParametersQuery
+    ) -> ConversationGetConversationsResponse:
+        """Get conversations."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/conversation/",
+            params=params.model_dump(mode="json", exclude_none=True),
+        )
+        return ConversationGetConversationsResponse.model_validate_json(response.text)
+
+    async def get_conversation_messages(
+        self, conversation_id: str, params: GetConversationMessagesParametersQuery
+    ) -> ConversationGetConversationMessagesResponse:
+        """Get conversation messages."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/conversation/{conversation_id}/messages/",
+            params=params.model_dump(
+                mode="json", exclude_none=True, exclude_defaults=True
+            ),
+        )
+        return ConversationGetConversationMessagesResponse.model_validate_json(
+            response.text
+        )
+
+    async def recommend_responses_for_interaction(
+        self, conversation_id: str, interaction_id: str
+    ) -> ConversationRecommendResponsesForInteractionResponse:
+        """Recommend responses for an interaction."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses",
+        )
+        return ConversationRecommendResponsesForInteractionResponse.model_validate_json(
+            response.text
+        )
+
+    async def get_interaction_insights(
+        self, conversation_id: str, interaction_id: str
+    ) -> ConversationGetInteractionInsightsResponse:
+        """Get insights for an interaction."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/conversation/{conversation_id}/interaction/{interaction_id}/insights",
+        )
+        return ConversationGetInteractionInsightsResponse.model_validate_json(
+            response.text
+        )
+
+    async def get_message_source(
+        self, conversation_id: str, message_id: str
+    ) -> GetMessageSourceResponse:
+        """Get the source of a message."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/conversation/{conversation_id}/messages/{message_id}/source",
+        )
+        return GetMessageSourceResponse.model_validate_json(response.text)
+
+    async def generate_conversation_starters(
+        self, body: ConversationGenerateConversationStarterRequest
+    ) -> ConversationGenerateConversationStarterResponse:
+        """Generate conversation starters."""
+        response = await self._http.request(
+            "POST",
+            f"/v1/{self._organization_id}/conversation/conversation_starter",
+            json=body.model_dump(mode="json", exclude_none=True),
+        )
+        return ConversationGenerateConversationStarterResponse.model_validate_json(
+            response.text
+        )

amigo_sdk/resources/organization.py

@@ -0,0 +1,22 @@
+from amigo_sdk.generated.model import (
+    OrganizationGetOrganizationResponse,
+)
+from amigo_sdk.http_client import AmigoHttpClient
+
+
+class OrganizationResource:
+    """Organization resource for Amigo API operations."""
+
+    def __init__(self, http_client: AmigoHttpClient, organization_id: str) -> None:
+        self._http = http_client
+        self._organization_id = organization_id
+
+    async def get(self) -> OrganizationGetOrganizationResponse:
+        """
+        Get the details of an organization.
+        """
+        response = await self._http.request(
+            "GET", f"/v1/{self._organization_id}/organization/"
+        )
+
+        return OrganizationGetOrganizationResponse.model_validate_json(response.text)

amigo_sdk/resources/service.py

@@ -0,0 +1,30 @@
+from typing import Optional
+
+from amigo_sdk.generated.model import (
+    GetServicesParametersQuery,
+    ServiceGetServicesResponse,
+)
+from amigo_sdk.http_client import AmigoHttpClient
+
+
+class ServiceResource:
+    """Service resource for Amigo API operations."""
+
+    def __init__(
+        self, http_client: AmigoHttpClient, organization_id: str
+    ) -> ServiceGetServicesResponse:
+        self._http = http_client
+        self._organization_id = organization_id
+
+    async def get_services(
+        self, params: Optional[GetServicesParametersQuery] = None
+    ) -> ServiceGetServicesResponse:
+        """Get all services."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/service/",
+            params=params.model_dump(mode="json", exclude_none=True)
+            if params
+            else None,
+        )
+        return ServiceGetServicesResponse.model_validate_json(response.text)

amigo_sdk/resources/user.py

@@ -0,0 +1,57 @@
+from typing import Optional
+
+from amigo_sdk.generated.model import (
+    GetUsersParametersQuery,
+    UserCreateInvitedUserRequest,
+    UserCreateInvitedUserResponse,
+    UserGetUsersResponse,
+    UserUpdateUserInfoRequest,
+)
+from amigo_sdk.http_client import AmigoHttpClient
+
+
+class UserResource:
+    """User resource for Amigo API operations."""
+
+    def __init__(self, http_client: AmigoHttpClient, organization_id: str) -> None:
+        self._http = http_client
+        self._organization_id = organization_id
+
+    async def get_users(
+        self, params: Optional[GetUsersParametersQuery] = None
+    ) -> UserGetUsersResponse:
+        """Get a list of users in the organization."""
+        response = await self._http.request(
+            "GET",
+            f"/v1/{self._organization_id}/user/",
+            params=params.model_dump(mode="json", exclude_none=True)
+            if params
+            else None,
+        )
+        return UserGetUsersResponse.model_validate_json(response.text)
+
+    async def create_user(
+        self, body: UserCreateInvitedUserRequest
+    ) -> UserCreateInvitedUserResponse:
+        """Create (invite) a new user to the organization."""
+        response = await self._http.request(
+            "POST",
+            f"/v1/{self._organization_id}/user/invite",
+            json=body.model_dump(mode="json", exclude_none=True),
+        )
+        return UserCreateInvitedUserResponse.model_validate_json(response.text)
+
+    async def delete_user(self, user_id: str) -> None:
+        """Delete a user by ID. Returns None on success (e.g., 204)."""
+        await self._http.request(
+            "DELETE",
+            f"/v1/{self._organization_id}/user/{user_id}",
+        )
+
+    async def update_user(self, user_id: str, body: UserUpdateUserInfoRequest) -> None:
+        """Update user information. Returns None on success (e.g., 204)."""
+        await self._http.request(
+            "POST",
+            f"/v1/{self._organization_id}/user/{user_id}/user",
+            json=body.model_dump(mode="json", exclude_none=True),
+        )

amigo_sdk/sdk_client.py

@@ -0,0 +1,105 @@
+from typing import Any, Optional
+
+from amigo_sdk.config import AmigoConfig
+from amigo_sdk.http_client import AmigoHttpClient
+from amigo_sdk.resources.conversation import ConversationResource
+from amigo_sdk.resources.organization import OrganizationResource
+from amigo_sdk.resources.service import ServiceResource
+from amigo_sdk.resources.user import UserResource
+
+
+class AmigoClient:
+    """
+    Amigo API client
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        api_key_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        config: Optional[AmigoConfig] = None,
+        **httpx_kwargs: Any,
+    ):
+        """
+        Initialize the Amigo SDK client.
+
+        Args:
+            api_key: API key for authentication (or set AMIGO_API_KEY env var)
+            api_key_id: API key ID for authentication (or set AMIGO_API_KEY_ID env var)
+            user_id: User ID for API requests (or set AMIGO_USER_ID env var)
+            organization_id: Organization ID for API requests (or set AMIGO_ORGANIZATION_ID env var)
+            base_url: Base URL for the API (or set AMIGO_BASE_URL env var)
+            config: Pre-configured AmigoConfig instance (overrides individual params)
+            **httpx_kwargs: Additional arguments passed to httpx.AsyncClient
+        """
+        if config:
+            self._cfg = config
+        else:
+            # Build config from individual parameters, falling back to env vars
+            cfg_dict: dict[str, Any] = {
+                k: v
+                for k, v in [
+                    ("api_key", api_key),
+                    ("api_key_id", api_key_id),
+                    ("user_id", user_id),
+                    ("organization_id", organization_id),
+                    ("base_url", base_url),
+                ]
+                if v is not None
+            }
+
+            try:
+                self._cfg = AmigoConfig(**cfg_dict)
+            except Exception as e:
+                raise ValueError(
+                    "AmigoClient configuration incomplete. "
+                    "Provide api_key, api_key_id, user_id, organization_id, base_url "
+                    "either as kwargs or environment variables."
+                ) from e
+
+        # Initialize HTTP client and resources
+        self._http = AmigoHttpClient(self._cfg, **httpx_kwargs)
+        self._organization = OrganizationResource(self._http, self._cfg.organization_id)
+        self._service = ServiceResource(self._http, self._cfg.organization_id)
+        self._conversation = ConversationResource(self._http, self._cfg.organization_id)
+        self._users = UserResource(self._http, self._cfg.organization_id)
+
+    @property
+    def config(self) -> AmigoConfig:
+        """Access the configuration object."""
+        return self._cfg
+
+    @property
+    def organization(self) -> OrganizationResource:
+        """Access organization resource."""
+        return self._organization
+
+    @property
+    def service(self) -> ServiceResource:
+        """Access service resource."""
+        return self._service
+
+    @property
+    def conversation(self) -> ConversationResource:
+        """Access conversation resource."""
+        return self._conversation
+
+    @property
+    def users(self) -> UserResource:
+        """Access user resource."""
+        return self._users
+
+    async def aclose(self) -> None:
+        """Close the HTTP client."""
+        await self._http.aclose()
+
+    # async-context-manager sugar
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()