bimpeai 0.1.0.dev3__py3-none-any.whl

bimpeai/__init__.py

@@ -0,0 +1,82 @@
+from ._async_client import AsyncBimpeAI
+from ._client import BimpeAI
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APINotImplementedError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    BimpeAIError,
+    ConflictError,
+    ErrorCode,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UserError,
+    ValidationError,
+)
+from ._models import ApiResponse, PaginationMeta
+from ._version import __version__
+from .pagination import AsyncPage, Page
+from .types.agents import (
+    Agent,
+    AgentAction,
+    AgentDetail,
+    Channel,
+    ConversationFlow,
+    Integration,
+    KnowledgeBase,
+    Rule,
+)
+from .types.calls import Call
+from .types.conversations import (
+    Conversation,
+    Message,
+    StreamHeartbeatEvent,
+    StreamMessageEvent,
+    StreamTicket,
+)
+from .types.workflows import Workflow, WorkflowSummary
+
+__all__ = [
+    "AsyncBimpeAI",
+    "AsyncPage",
+    "Agent",
+    "AgentAction",
+    "AgentDetail",
+    "ApiResponse",
+    "APIConnectionError",
+    "APIError",
+    "APINotImplementedError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "BimpeAI",
+    "BimpeAIError",
+    "Call",
+    "Channel",
+    "ConflictError",
+    "Conversation",
+    "ConversationFlow",
+    "ErrorCode",
+    "Integration",
+    "InternalServerError",
+    "KnowledgeBase",
+    "Message",
+    "NotFoundError",
+    "Page",
+    "PaginationMeta",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Rule",
+    "StreamHeartbeatEvent",
+    "StreamMessageEvent",
+    "StreamTicket",
+    "UserError",
+    "ValidationError",
+    "Workflow",
+    "WorkflowSummary",
+    "__version__",
+]

bimpeai/_async_client.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+
+from ._base_client import BaseClient, safe_json
+from ._exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    BimpeAIError,
+    RateLimitError,
+    map_api_error,
+)
+from ._idempotency import resolve_idempotency_key
+from ._models import ApiResponse
+from ._request import RequestSpec, StreamSpec
+from ._request_id import generate_request_id
+from ._retries import compute_backoff, should_retry
+from .resources.agents import AsyncAgents
+from .resources.calls import AsyncCalls
+from .resources.conversations import AsyncConversations
+from .resources.workflows import AsyncWorkflows
+
+_WRITE_METHODS = frozenset({"POST", "PATCH", "PUT", "DELETE"})
+
+
+class AsyncBimpeAI(BaseClient):
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        default_headers: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        self._owns_http = http_client is None
+        self.agents = AsyncAgents(self)
+        self.workflows = AsyncWorkflows(self)
+        self.conversations = AsyncConversations(self)
+        self.calls = AsyncCalls(self)
+
+    async def request(self, spec: RequestSpec) -> ApiResponse[Any]:
+        url = self.build_url(spec.path)
+        params = self.clean_params(spec.query)
+        options = spec.options
+        max_retries = self._max_retries if options.max_retries is None else options.max_retries
+        timeout = self._timeout if options.timeout is None else options.timeout
+        idempotency_key = (
+            resolve_idempotency_key(options.idempotency_key, max_retries)
+            if spec.method in _WRITE_METHODS
+            else None
+        )
+        request_id = _resolve_request_id(options.headers)
+
+        attempt = 0
+        while True:
+            try:
+                return await self._send(spec, url, params, idempotency_key, request_id, timeout)
+            except BimpeAIError as error:
+                if not should_retry(error, attempt, max_retries):
+                    raise
+                retry_after = error.retry_after if isinstance(error, RateLimitError) else None
+                await asyncio.sleep(compute_backoff(attempt, retry_after_s=retry_after))
+                attempt += 1
+
+    async def _send(
+        self,
+        spec: RequestSpec,
+        url: str,
+        params: dict[str, str],
+        idempotency_key: str | None,
+        request_id: str,
+        timeout: float,
+    ) -> ApiResponse[Any]:
+        headers = self.build_headers(
+            has_body=spec.body is not None,
+            idempotency_key=idempotency_key,
+            request_id=request_id,
+            extra=spec.options.headers,
+        )
+        try:
+            response = await self._http.request(
+                spec.method,
+                url,
+                params=params or None,
+                json=spec.body if spec.body is not None else None,
+                headers=headers,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(cause=exc) from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("network error", cause=exc) from exc
+        return self.parse_response(response, request_id)
+
+    @asynccontextmanager
+    async def stream(self, spec: StreamSpec) -> AsyncGenerator[httpx.Response, None]:
+        url = self.build_url(spec.path)
+        params = self.clean_params(spec.query)
+        headers = httpx.Headers(self._default_headers)
+        headers["Accept"] = "text/event-stream"
+        headers["User-Agent"] = self._user_agent
+        if spec.headers:
+            for key, value in spec.headers.items():
+                headers[key] = value
+        try:
+            async with self._http.stream(
+                "GET", url, params=params or None, headers=headers, timeout=spec.timeout
+            ) as response:
+                if not response.is_success:
+                    body = await response.aread()
+                    raise map_api_error(
+                        response.status_code, safe_json(body.decode() or ""), response.headers
+                    )
+                yield response
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(cause=exc) from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("stream aborted", cause=exc) from exc
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncBimpeAI:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+def _resolve_request_id(extra: dict[str, str] | None) -> str:
+    if extra:
+        for key, value in extra.items():
+            if key.lower() == "x-request-id":
+                return value
+    return generate_request_id()

bimpeai/_base_client.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import platform
+from typing import Any
+
+import httpx
+
+from ._exceptions import UserError, map_api_error
+from ._models import ApiResponse, unwrap_envelope
+from ._version import __version__
+
+API_PATH_PREFIX = "/api/v1/console"
+DEFAULT_BASE_URL = "https://api.bimpe.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+class BaseClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        if not api_key:
+            raise UserError("api_key is required")
+        self._api_key = api_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+        self._user_agent = _build_user_agent()
+
+    def build_url(self, path: str) -> str:
+        return f"{self._base_url}{API_PATH_PREFIX}{path}"
+
+    def clean_params(self, query: dict[str, Any] | None) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for key, value in (query or {}).items():
+            if value is None:
+                continue
+            out[key] = "true" if value is True else "false" if value is False else str(value)
+        return out
+
+    def build_headers(
+        self,
+        *,
+        has_body: bool,
+        idempotency_key: str | None,
+        request_id: str,
+        extra: dict[str, str] | None,
+    ) -> httpx.Headers:
+        headers = httpx.Headers(self._default_headers)
+        headers["Authorization"] = f"Bearer {self._api_key}"
+        headers["Accept"] = "application/json"
+        headers["User-Agent"] = self._user_agent
+        headers["X-Request-Id"] = request_id
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        if extra:
+            for key, value in extra.items():
+                headers[key] = value
+        return headers
+
+    def parse_response(self, response: httpx.Response, request_id: str) -> ApiResponse[Any]:
+        text = response.text
+        parsed = safe_json(text) if text else None
+        if not response.is_success:
+            raise map_api_error(response.status_code, parsed, response.headers)
+        unwrapped = unwrap_envelope(parsed)
+        return ApiResponse(
+            data=unwrapped.data,
+            meta=unwrapped.meta,
+            request_id=response.headers.get("x-request-id") or request_id,
+            status=response.status_code,
+            headers=response.headers,
+        )
+
+
+def _build_user_agent() -> str:
+    return f"bimpeai-python/{__version__} (Python/{platform.python_version()}; {platform.system()})"
+
+
+def safe_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None

bimpeai/_client.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+
+from ._base_client import BaseClient, safe_json
+from ._exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    BimpeAIError,
+    RateLimitError,
+    map_api_error,
+)
+from ._idempotency import resolve_idempotency_key
+from ._models import ApiResponse
+from ._request import RequestSpec, StreamSpec
+from ._request_id import generate_request_id
+from ._retries import compute_backoff, should_retry
+from .resources.agents import Agents
+from .resources.calls import Calls
+from .resources.conversations import Conversations
+from .resources.workflows import Workflows
+
+_WRITE_METHODS = frozenset({"POST", "PATCH", "PUT", "DELETE"})
+
+
+class BimpeAI(BaseClient):
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        default_headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._owns_http = http_client is None
+        self.agents = Agents(self)
+        self.workflows = Workflows(self)
+        self.conversations = Conversations(self)
+        self.calls = Calls(self)
+
+    def request(self, spec: RequestSpec) -> ApiResponse[Any]:
+        url = self.build_url(spec.path)
+        params = self.clean_params(spec.query)
+        options = spec.options
+        max_retries = self._max_retries if options.max_retries is None else options.max_retries
+        timeout = self._timeout if options.timeout is None else options.timeout
+        idempotency_key = (
+            resolve_idempotency_key(options.idempotency_key, max_retries)
+            if spec.method in _WRITE_METHODS
+            else None
+        )
+        request_id = _resolve_request_id(options.headers)
+
+        attempt = 0
+        while True:
+            try:
+                return self._send(spec, url, params, idempotency_key, request_id, timeout)
+            except BimpeAIError as error:
+                if not should_retry(error, attempt, max_retries):
+                    raise
+                retry_after = error.retry_after if isinstance(error, RateLimitError) else None
+                time.sleep(compute_backoff(attempt, retry_after_s=retry_after))
+                attempt += 1
+
+    def _send(
+        self,
+        spec: RequestSpec,
+        url: str,
+        params: dict[str, str],
+        idempotency_key: str | None,
+        request_id: str,
+        timeout: float,
+    ) -> ApiResponse[Any]:
+        headers = self.build_headers(
+            has_body=spec.body is not None,
+            idempotency_key=idempotency_key,
+            request_id=request_id,
+            extra=spec.options.headers,
+        )
+        try:
+            response = self._http.request(
+                spec.method,
+                url,
+                params=params or None,
+                json=spec.body if spec.body is not None else None,
+                headers=headers,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(cause=exc) from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("network error", cause=exc) from exc
+        return self.parse_response(response, request_id)
+
+    @contextmanager
+    def stream(self, spec: StreamSpec) -> Generator[httpx.Response, None, None]:
+        url = self.build_url(spec.path)
+        params = self.clean_params(spec.query)
+        headers = httpx.Headers(self._default_headers)
+        headers["Accept"] = "text/event-stream"
+        headers["User-Agent"] = self._user_agent
+        if spec.headers:
+            for key, value in spec.headers.items():
+                headers[key] = value
+        try:
+            with self._http.stream(
+                "GET", url, params=params or None, headers=headers, timeout=spec.timeout
+            ) as response:
+                if not response.is_success:
+                    body = response.read()
+                    raise map_api_error(
+                        response.status_code, safe_json(body.decode() or ""), response.headers
+                    )
+                yield response
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(cause=exc) from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("stream aborted", cause=exc) from exc
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> BimpeAI:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _resolve_request_id(extra: dict[str, str] | None) -> str:
+    if extra:
+        for key, value in extra.items():
+            if key.lower() == "x-request-id":
+                return value
+    return generate_request_id()

bimpeai/_exceptions.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from typing import Any, Literal, cast
+
+import httpx
+
+ErrorCode = Literal[
+    "validation_error",
+    "bad_request",
+    "unauthorized",
+    "api_key_missing",
+    "api_key_invalid",
+    "api_key_expired",
+    "insufficient_scope",
+    "forbidden",
+    "not_found",
+    "conflict",
+    "rate_limited",
+    "too_many_requests",
+    "not_implemented",
+    "agent_limit_reached",
+    "internal_error",
+]
+
+
+class BimpeAIError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class UserError(BimpeAIError):
+    """The SDK was used or configured incorrectly (e.g. missing api_key)."""
+
+
+class APIConnectionError(BimpeAIError):
+    def __init__(
+        self, message: str = "connection error", *, cause: BaseException | None = None
+    ) -> None:
+        super().__init__(message)
+        if cause is not None:
+            self.__cause__ = cause
+
+
+class APITimeoutError(APIConnectionError):
+    def __init__(
+        self, message: str = "request timed out", *, cause: BaseException | None = None
+    ) -> None:
+        super().__init__(message, cause=cause)
+
+
+class APIError(BimpeAIError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None,
+        request_id: str | None,
+        headers: httpx.Headers,
+        body: Any,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.headers = headers
+        self.body = body
+
+
+class BadRequestError(APIError):
+    pass
+
+
+class ValidationError(BadRequestError):
+    def __init__(self, message: str, *, field_errors: list[dict[str, str]], **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.field_errors = field_errors
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None,
+        limit: int | None,
+        remaining: int | None,
+        reset_at: int | None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+        self.limit = limit
+        self.remaining = remaining
+        self.reset_at = reset_at
+
+
+class InternalServerError(APIError):
+    pass
+
+
+class APINotImplementedError(APIError):
+    pass
+
+
+def map_api_error(status: int, body: Any, headers: httpx.Headers) -> APIError:
+    err_body: dict[str, Any] = cast("dict[str, Any]", body) if isinstance(body, dict) else {}
+    message = _normalise_message(err_body.get("message")) or f"HTTP {status}"
+    code = err_body.get("code")
+    request_id = headers.get("x-request-id") or err_body.get("request_id")
+    base: dict[str, Any] = {
+        "status": status,
+        "code": code,
+        "request_id": request_id,
+        "headers": headers,
+        "body": body,
+    }
+
+    if status == 400:
+        if code == "validation_error":
+            return ValidationError(
+                message, field_errors=_parse_field_errors(err_body.get("message")), **base
+            )
+        return BadRequestError(message, **base)
+    if status == 401:
+        return AuthenticationError(message, **base)
+    if status == 403:
+        return PermissionDeniedError(message, **base)
+    if status == 404:
+        return NotFoundError(message, **base)
+    if status == 409:
+        return ConflictError(message, **base)
+    if status == 429:
+        return RateLimitError(
+            message,
+            retry_after=_int_or_none(headers.get("retry-after")),
+            limit=_int_or_none(headers.get("x-ratelimit-limit")),
+            remaining=_int_or_none(headers.get("x-ratelimit-remaining")),
+            reset_at=_int_or_none(headers.get("x-ratelimit-reset")),
+            **base,
+        )
+    if status == 501:
+        return APINotImplementedError(message, **base)
+    if status >= 500:
+        return InternalServerError(message, **base)
+    return APIError(message, **base)
+
+
+def _normalise_message(message: Any) -> str | None:
+    if isinstance(message, list):
+        parts = cast("list[Any]", message)
+        return "; ".join(str(m) for m in parts)
+    if isinstance(message, str):
+        return message
+    return None
+
+
+def _parse_field_errors(message: Any) -> list[dict[str, str]]:
+    if not isinstance(message, list):
+        return []
+    items = cast("list[Any]", message)
+    out: list[dict[str, str]] = []
+    for entry in items:
+        if not isinstance(entry, str):
+            continue
+        path, sep, rest = entry.partition(":")
+        if sep:
+            out.append({"path": path.strip(), "message": rest.strip()})
+        else:
+            out.append({"path": "", "message": entry})
+    return out
+
+
+def _int_or_none(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None

bimpeai/_idempotency.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from ._request_id import generate_request_id
+
+
+def resolve_idempotency_key(supplied: str | None, max_retries: int) -> str | None:
+    if supplied:
+        return supplied
+    if max_retries > 0:
+        return generate_request_id()
+    return None