agentum-cloud-sdk 0.1.62__py3-none-any.whl

agentum_cloud/__init__.py

@@ -0,0 +1,51 @@
+"""agentum-cloud SDK — типизированный async-клиент над REST API ``/v1``.
+
+Один контракт для всех клиентов (бот, MCP, сторонние проекты). Пример::
+
+    async with AgentumClient(base_url="http://host:8083", api_key="...") as cloud:
+        obj = await cloud.upload("doc.pdf", data, owner_id="tg:42")
+        ready = await cloud.wait_until_ready(obj.id, owner_id="tg:42")
+        answer = await cloud.ask("когда отпуск?", owner_id="tg:42")
+"""
+
+from __future__ import annotations
+
+from agentum_cloud.client import AgentumClient
+from agentum_cloud.errors import AgentumAPIError, AgentumError, AgentumTimeoutError
+from agentum_cloud.models import (
+    AskAnswer,
+    Citation,
+    Collection,
+    ContentUrl,
+    Enrichment,
+    MeterCost,
+    ObjectDetail,
+    ObjectSummary,
+    OwnerUsage,
+    SearchHit,
+    SummaryOut,
+    UploadResult,
+    UsageBreakdown,
+    UsageSummary,
+)
+
+__all__ = [
+    "AgentumClient",
+    "AgentumError",
+    "AgentumAPIError",
+    "AgentumTimeoutError",
+    "AskAnswer",
+    "Citation",
+    "Collection",
+    "ContentUrl",
+    "Enrichment",
+    "MeterCost",
+    "ObjectDetail",
+    "ObjectSummary",
+    "OwnerUsage",
+    "SearchHit",
+    "SummaryOut",
+    "UploadResult",
+    "UsageBreakdown",
+    "UsageSummary",
+]

agentum_cloud/client.py

@@ -0,0 +1,373 @@
+"""Async-клиент над agentum-cloud ``/v1``.
+
+Тонкая обёртка httpx: Bearer-ключ, опциональный ``owner_id`` (X-Owner-Id, бот мапит
+tg-юзера), ретраи на 429/5xx с экспоненциальным backoff, типизированные ответы.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from agentum_cloud.errors import AgentumAPIError, AgentumTimeoutError
+from agentum_cloud.models import (
+    AskAnswer,
+    Collection,
+    ContentUrl,
+    ObjectDetail,
+    ObjectSummary,
+    SearchHit,
+    SummaryOut,
+    UploadResult,
+    UsageBreakdown,
+    UsageSummary,
+)
+
+# 504 НЕ ретраим: это дедлайн сервера /ask (ask_deadline_seconds) — повтор лишь сожжёт
+# токены и время на том же запросе; пользователю показываем сообщение «не успел».
+_RETRY_STATUSES = frozenset({429, 500, 502, 503})
+_BACKOFF_BASE = 0.5
+_BACKOFF_CAP = 8.0
+_TERMINAL_STATUSES = frozenset({"ready", "failed"})
+# read=75 заведомо больше серверного дедлайна /ask (settings.ask_deadline_seconds=60):
+# клиент не отваливается раньше, чем сервер вернёт корректный ответ/типизированную 504.
+_DEFAULT_TIMEOUT = httpx.Timeout(connect=5.0, read=75.0, write=10.0, pool=5.0)
+# Транспортные ошибки «соединение не установлено» — запрос гарантированно не дошёл
+# до сервера, поэтому ретраить безопасно даже неидемпотентный POST.
+_CONNECT_ERRORS = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+# Тот же контракт, что и сервер (deps._OWNER_RE) — ловим мусор до отправки заголовка.
+_OWNER_RE = re.compile(r"\A[A-Za-z0-9_:.-]{1,64}\Z")
+
+
+class AgentumClient:
+    """Клиент REST API. Используй как async-контекст-менеджер."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        owner_id: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_attempts: int = 4,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._owner_id = owner_id
+        self._max_attempts = max(1, max_attempts)
+        # Внешний client (для тестов/переиспользования) не закрываем сами.
+        # trust_env=False — детерминированный SDK: не подхватываем прокси из окружения
+        # (HTTP_PROXY/ALL_PROXY); нужен прокси — передай готовый httpx.AsyncClient.
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout if timeout is not None else _DEFAULT_TIMEOUT,
+            trust_env=False,
+        )
+
+    async def __aenter__(self) -> AgentumClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    def _headers(self, owner_id: str | None) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        effective = owner_id or self._owner_id
+        if effective:
+            if not _OWNER_RE.fullmatch(effective):
+                raise ValueError(f"Некорректный owner_id: {effective!r}")
+            headers["X-Owner-Id"] = effective
+        return headers
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        owner_id: str | None = None,
+        idempotent: bool = False,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        last_exc: Exception | None = None
+        for attempt in range(1, self._max_attempts + 1):
+            try:
+                resp = await self._client.request(method, path, headers=self._headers(owner_id), **kwargs)
+            except httpx.TransportError as exc:
+                last_exc = exc
+                # Соединение не установлено → запрос не дошёл, ретраим любой метод. Иначе
+                # (read/write — байты уже могли уйти) ретраим только идемпотентные: дорогой
+                # неидемпотентный POST (/ask, /objects) по таймауту ответа НЕ перезапускаем.
+                connect_failed = isinstance(exc, _CONNECT_ERRORS)
+                if (not connect_failed and not idempotent) or attempt == self._max_attempts:
+                    raise AgentumAPIError(0, f"Сеть недоступна: {exc}") from exc
+                await asyncio.sleep(_backoff(attempt))
+                continue
+
+            if resp.status_code in _RETRY_STATUSES and attempt < self._max_attempts:
+                await asyncio.sleep(_backoff(attempt, resp.headers.get("Retry-After")))
+                continue
+            if resp.status_code >= 400:
+                raise AgentumAPIError(resp.status_code, _error_message(resp), body=resp.text[:500])
+            return resp
+
+        # Недостижимо при max_attempts>=1, но успокаиваем тайпчекер.
+        raise AgentumAPIError(0, f"Запрос не удался: {last_exc}")
+
+    async def upload(
+        self,
+        filename: str,
+        data: bytes,
+        *,
+        mime: str | None = None,
+        owner_id: str | None = None,
+    ) -> UploadResult:
+        files = {"file": (filename, data, mime or "application/octet-stream")}
+        # idempotent=False (по умолчанию): не плодим дубли загрузки по read-timeout.
+        resp = await self._request("POST", "/v1/objects", owner_id=owner_id, files=files)
+        return UploadResult.from_dict(resp.json())
+
+    async def get_object(self, object_id: str, *, owner_id: str | None = None) -> ObjectDetail:
+        resp = await self._request("GET", f"/v1/objects/{object_id}", owner_id=owner_id, idempotent=True)
+        return ObjectDetail.from_dict(resp.json())
+
+    async def list_objects(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        doc_type: str | None = None,
+        owner_id: str | None = None,
+    ) -> list[ObjectSummary]:
+        """Список объектов владельца (новые сверху)."""
+        params: dict[str, Any] = {}
+        if limit:
+            params["limit"] = limit
+        if offset:
+            params["offset"] = offset
+        if doc_type:
+            params["doc_type"] = doc_type
+        resp = await self._request("GET", "/v1/objects", owner_id=owner_id, params=params or None)
+        return [ObjectSummary.from_dict(it) for it in resp.json().get("items", [])]
+
+    async def get_content(self, object_id: str, *, owner_id: str | None = None) -> ContentUrl:
+        resp = await self._request(
+            "GET", f"/v1/objects/{object_id}/content", owner_id=owner_id, idempotent=True
+        )
+        return ContentUrl.from_dict(resp.json())
+
+    async def download_url(self, url: str) -> bytes:
+        """Качает байты по (presigned) URL. Auth-заголовок НЕ шлём — ссылка самодостаточна."""
+        try:
+            resp = await self._client.get(url, follow_redirects=True)
+        except httpx.TransportError as exc:
+            raise AgentumAPIError(0, f"Сеть недоступна: {exc}") from exc
+        if resp.status_code >= 400:
+            raise AgentumAPIError(resp.status_code, "Не удалось скачать файл", body=resp.text[:300])
+        return resp.content
+
+    async def get_usage(self, *, days: int | None = None, owner_id: str | None = None) -> UsageSummary:
+        """Расход текущего владельца (или ``owner_id``): стоимость ₽ + разбивка по статьям."""
+        params = {"days": days} if days else None
+        resp = await self._request("GET", "/v1/usage", owner_id=owner_id, params=params)
+        return UsageSummary.from_dict(resp.json())
+
+    async def get_usage_breakdown(
+        self, *, days: int | None = None, owner_id: str | None = None
+    ) -> UsageBreakdown:
+        """Расход по всем юзерам тенанта (только админ; иначе AgentumAPIError 403)."""
+        params = {"days": days} if days else None
+        resp = await self._request("GET", "/v1/usage/breakdown", owner_id=owner_id, params=params)
+        return UsageBreakdown.from_dict(resp.json())
+
+    async def classify_intent(self, query: str, *, owner_id: str | None = None) -> tuple[str, str, str]:
+        """Намерение свободной фразы: ``(action, target, lang)``.
+
+        ``action`` ∈ {send_file, answer, delete, translate}; ``lang`` — целевой язык
+        для translate (для остальных — "").
+        """
+        resp = await self._request("POST", "/v1/intent", owner_id=owner_id, json={"query": query})
+        data = resp.json()
+        return (
+            str(data.get("action") or "answer"),
+            str(data.get("target") or ""),
+            str(data.get("lang") or ""),
+        )
+
+    async def transcribe(
+        self,
+        filename: str,
+        data: bytes,
+        *,
+        mime: str | None = None,
+        owner_id: str | None = None,
+    ) -> str:
+        """Распознаёт речь из аудио в текст (без сохранения в облаке). Возвращает текст ("" — нет речи)."""
+        files = {"file": (filename, data, mime or "audio/ogg")}
+        resp = await self._request("POST", "/v1/transcribe", owner_id=owner_id, files=files)
+        return str(resp.json().get("text", ""))
+
+    async def search(
+        self,
+        query: str,
+        *,
+        doc_type: str | None = None,
+        top_k: int | None = None,
+        owner_id: str | None = None,
+    ) -> list[SearchHit]:
+        params: dict[str, Any] = {"q": query}
+        if doc_type:
+            params["doc_type"] = doc_type
+        if top_k:
+            params["top_k"] = top_k
+        resp = await self._request("GET", "/v1/search", owner_id=owner_id, idempotent=True, params=params)
+        return [SearchHit.from_dict(h) for h in resp.json().get("hits", [])]
+
+    async def ask(
+        self,
+        query: str,
+        *,
+        doc_type: str | None = None,
+        top_k: int | None = None,
+        owner_id: str | None = None,
+    ) -> AskAnswer:
+        body: dict[str, Any] = {"query": query}
+        if doc_type:
+            body["doc_type"] = doc_type
+        if top_k:
+            body["top_k"] = top_k
+        # idempotent=False (по умолчанию): дорогой LLM-вызов не перезапускаем по read-timeout;
+        # сервер сам ограничен дедлайном (ask_deadline_seconds) и вернёт типизированную ошибку.
+        resp = await self._request("POST", "/v1/ask", owner_id=owner_id, json=body)
+        return AskAnswer.from_dict(resp.json())
+
+    async def wait_until_ready(
+        self,
+        object_id: str,
+        *,
+        owner_id: str | None = None,
+        timeout: float = 120.0,  # noqa: ASYNC109 — это бюджет поллинга, не single-shot asyncio.timeout
+        interval: float = 2.0,
+    ) -> ObjectDetail:
+        """Поллит статус объекта до ``ready``/``failed``. Бросает AgentumTimeoutError по таймауту."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            detail = await self.get_object(object_id, owner_id=owner_id)
+            if detail.status in _TERMINAL_STATUSES:
+                return detail
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                raise AgentumTimeoutError(f"Объект {object_id} не готов за {timeout:.0f}с")
+            await asyncio.sleep(min(interval, remaining))
+
+    # --- Папки/коллекции и удаление (Ф8, Dev A) ----------------------------
+
+    async def delete_object(self, object_id: str, *, owner_id: str | None = None) -> None:
+        """Удаляет объект (файл) безвозвратно. 204 — успех."""
+        await self._request("DELETE", f"/v1/objects/{object_id}", owner_id=owner_id)
+
+    async def create_collection(
+        self, name: str, *, parent_id: str | None = None, owner_id: str | None = None
+    ) -> Collection:
+        """Создаёт папку. ``parent_id`` — родитель (None для корня)."""
+        body: dict[str, Any] = {"name": name}
+        if parent_id is not None:
+            body["parent_id"] = parent_id
+        resp = await self._request("POST", "/v1/collections", owner_id=owner_id, json=body)
+        return Collection.from_dict(resp.json())
+
+    async def list_collections(self, *, owner_id: str | None = None) -> list[Collection]:
+        """Плоский список папок владельца (дерево строится по ``parent_id``)."""
+        resp = await self._request("GET", "/v1/collections", owner_id=owner_id)
+        return [Collection.from_dict(it) for it in resp.json().get("items", [])]
+
+    async def rename_collection(
+        self, collection_id: str, name: str, *, owner_id: str | None = None
+    ) -> Collection:
+        """Переименовывает папку."""
+        resp = await self._request(
+            "PATCH", f"/v1/collections/{collection_id}", owner_id=owner_id, json={"name": name}
+        )
+        return Collection.from_dict(resp.json())
+
+    async def move_collection(
+        self, collection_id: str, parent_id: str | None, *, owner_id: str | None = None
+    ) -> Collection:
+        """Переносит папку под нового родителя (``parent_id=None`` — в корень)."""
+        resp = await self._request(
+            "PATCH",
+            f"/v1/collections/{collection_id}",
+            owner_id=owner_id,
+            json={"parent_id": parent_id},
+        )
+        return Collection.from_dict(resp.json())
+
+    async def delete_collection(self, collection_id: str, *, owner_id: str | None = None) -> None:
+        """Удаляет папку (под-папки всплывают в корень, файлы — «без папки»)."""
+        await self._request("DELETE", f"/v1/collections/{collection_id}", owner_id=owner_id)
+
+    async def move_object(self, collection_id: str, object_id: str, *, owner_id: str | None = None) -> None:
+        """Перемещает файл в папку. 204 — успех."""
+        await self._request("POST", f"/v1/collections/{collection_id}/objects/{object_id}", owner_id=owner_id)
+
+    # --- Ф9 (Dev B): контент-функции ---------------------------------------
+
+    async def get_summary(self, object_id: str, *, owner_id: str | None = None) -> SummaryOut:
+        """Содержание объекта (Ф9): метаданные из обогащения. ``pending`` — статус без полей."""
+        resp = await self._request(
+            "GET", f"/v1/objects/{object_id}/summary", owner_id=owner_id, idempotent=True
+        )
+        return SummaryOut.from_dict(resp.json())
+
+    async def translate(
+        self, object_id: str, target_lang: str, *, owner_id: str | None = None
+    ) -> tuple[str, str]:
+        """Перевод объекта на ``target_lang`` → новый объект. Возвращает ``(object_id, status)``.
+
+        ``idempotent=False``: дорогой LLM-вызов не перезапускаем по read-timeout (дедуп
+        нового объекта по ``content_hash`` на сервере всё равно защищает от дублей).
+        """
+        resp = await self._request(
+            "POST",
+            f"/v1/objects/{object_id}/translate",
+            owner_id=owner_id,
+            json={"target_lang": target_lang},
+        )
+        data = resp.json()
+        return str(data.get("object_id") or ""), str(data.get("status") or "")
+
+
+def _backoff(attempt: int, retry_after: str | None = None) -> float:
+    if retry_after:
+        try:
+            return min(float(retry_after), _BACKOFF_CAP)
+        except ValueError:
+            pass
+    return min(_BACKOFF_BASE * (2 ** (attempt - 1)), _BACKOFF_CAP)
+
+
+def _error_message(resp: httpx.Response) -> str:
+    try:
+        payload = resp.json()
+    except ValueError:
+        return resp.reason_phrase or "ошибка"
+    if isinstance(payload, dict):
+        detail = payload.get("detail") or payload.get("error") or payload.get("message")
+        if isinstance(detail, str):
+            return detail
+    return resp.reason_phrase or "ошибка"

agentum_cloud/errors.py

@@ -0,0 +1,21 @@
+"""Ошибки SDK."""
+
+from __future__ import annotations
+
+
+class AgentumError(Exception):
+    """Базовая ошибка SDK."""
+
+
+class AgentumAPIError(AgentumError):
+    """Не-2xx ответ от API. Несёт статус и тело для диагностики у клиента."""
+
+    def __init__(self, status_code: int, message: str, *, body: str = "") -> None:
+        super().__init__(f"API {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+
+
+class AgentumTimeoutError(AgentumError):
+    """Объект не дошёл до терминального статуса за отведённое время (wait_until_ready)."""

agentum_cloud/models.py

@@ -0,0 +1,301 @@
+"""Типизированные DTO ответов API (зеркало backend/app/schemas).
+
+Лёгкие ``frozen``-датаклассы без pydantic — SDK не тянет лишних зависимостей.
+Каждый класс умеет собираться из JSON-словаря через ``from_dict``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class UploadResult:
+    id: str
+    status: str
+    duplicate: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> UploadResult:
+        return cls(id=str(d["id"]), status=str(d["status"]), duplicate=bool(d.get("duplicate", False)))
+
+
+@dataclass(frozen=True)
+class Enrichment:
+    title: str = ""
+    summary: str = ""
+    description: str = ""
+    keywords: list[str] = field(default_factory=list)
+    doc_type: str = "other"
+    language: str = ""
+    entities: dict[str, Any] = field(default_factory=dict)
+    model: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Enrichment:
+        return cls(
+            title=str(d.get("title", "")),
+            summary=str(d.get("summary", "")),
+            description=str(d.get("description", "")),
+            keywords=list(d.get("keywords") or []),
+            doc_type=str(d.get("doc_type", "other")),
+            language=str(d.get("language", "")),
+            entities=dict(d.get("entities") or {}),
+            model=str(d.get("model", "")),
+        )
+
+
+@dataclass(frozen=True)
+class SummaryOut:
+    """Карточка содержания объекта (Ф9): метаданные + статус. Зеркало backend ``SummaryOut``."""
+
+    object_id: str
+    status: str
+    filename: str = ""
+    title: str = ""
+    summary: str = ""
+    description: str = ""
+    doc_type: str = "other"
+    keywords: list[str] = field(default_factory=list)
+    language: str = ""
+    entities: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_ready(self) -> bool:
+        return self.status == "ready"
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SummaryOut:
+        return cls(
+            object_id=str(d["object_id"]),
+            status=str(d.get("status", "")),
+            filename=str(d.get("filename", "")),
+            title=str(d.get("title", "")),
+            summary=str(d.get("summary", "")),
+            description=str(d.get("description", "")),
+            doc_type=str(d.get("doc_type", "other")),
+            keywords=list(d.get("keywords") or []),
+            language=str(d.get("language", "")),
+            entities=dict(d.get("entities") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class ObjectDetail:
+    id: str
+    filename: str
+    mime: str
+    size: int
+    kind: str
+    status: str
+    error: str | None = None
+    content_hash: str = ""
+    enrichment: Enrichment | None = None
+
+    @property
+    def is_ready(self) -> bool:
+        return self.status == "ready"
+
+    @property
+    def is_failed(self) -> bool:
+        return self.status == "failed"
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ObjectDetail:
+        enr = d.get("enrichment")
+        return cls(
+            id=str(d["id"]),
+            filename=str(d.get("filename", "")),
+            mime=str(d.get("mime", "")),
+            size=int(d.get("size", 0)),
+            kind=str(d.get("kind", "")),
+            status=str(d.get("status", "")),
+            error=d.get("error"),
+            content_hash=str(d.get("content_hash", "")),
+            enrichment=Enrichment.from_dict(enr) if isinstance(enr, dict) else None,
+        )
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    object_id: str
+    filename: str = ""
+    doc_type: str = "other"
+    title: str = ""
+    summary: str = ""
+    score: float = 0.0
+    snippet: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SearchHit:
+        return cls(
+            object_id=str(d["object_id"]),
+            filename=str(d.get("filename", "")),
+            doc_type=str(d.get("doc_type", "other")),
+            title=str(d.get("title", "")),
+            summary=str(d.get("summary", "")),
+            score=float(d.get("score", 0.0)),
+            snippet=str(d.get("snippet", "")),
+        )
+
+
+@dataclass(frozen=True)
+class Citation:
+    object_id: str
+    ord: int = 0
+    index: int = 0
+    filename: str = ""
+    title: str = ""
+    snippet: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Citation:
+        return cls(
+            object_id=str(d["object_id"]),
+            ord=int(d.get("ord", 0)),
+            index=int(d.get("index", 0)),
+            filename=str(d.get("filename", "")),
+            title=str(d.get("title", "")),
+            snippet=str(d.get("snippet", "")),
+        )
+
+
+@dataclass(frozen=True)
+class AskAnswer:
+    answer: str
+    used_context: bool = False
+    citations: list[Citation] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AskAnswer:
+        cites = d.get("citations") or []
+        return cls(
+            answer=str(d.get("answer", "")),
+            used_context=bool(d.get("used_context", False)),
+            citations=[Citation.from_dict(c) for c in cites if isinstance(c, dict)],
+        )
+
+
+@dataclass(frozen=True)
+class ContentUrl:
+    url: str
+    expires_in: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ContentUrl:
+        return cls(url=str(d["url"]), expires_in=int(d.get("expires_in", 0)))
+
+
+@dataclass(frozen=True)
+class ObjectSummary:
+    id: str
+    filename: str = ""
+    kind: str = ""
+    status: str = ""
+    doc_type: str = "other"
+    title: str = ""
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ObjectSummary:
+        return cls(
+            id=str(d["id"]),
+            filename=str(d.get("filename", "")),
+            kind=str(d.get("kind", "")),
+            status=str(d.get("status", "")),
+            doc_type=str(d.get("doc_type", "other")),
+            title=str(d.get("title", "")),
+            created_at=str(d.get("created_at", "")),
+        )
+
+
+@dataclass(frozen=True)
+class Collection:
+    """Папка/коллекция (Ф8). ``parent_id`` — родитель в дереве (None для корня)."""
+
+    id: str
+    name: str = ""
+    parent_id: str | None = None
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Collection:
+        parent = d.get("parent_id")
+        return cls(
+            id=str(d["id"]),
+            name=str(d.get("name", "")),
+            parent_id=str(parent) if parent else None,
+            created_at=str(d.get("created_at", "")),
+        )
+
+
+@dataclass(frozen=True)
+class MeterCost:
+    meter: str
+    cost_rub: float = 0.0
+    prompt_tokens: int = 0
+    total_tokens: int = 0
+    audio_seconds: int = 0
+    calls: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> MeterCost:
+        return cls(
+            meter=str(d.get("meter", "")),
+            cost_rub=float(d.get("cost_rub", 0.0)),
+            prompt_tokens=int(d.get("prompt_tokens", 0)),
+            total_tokens=int(d.get("total_tokens", 0)),
+            audio_seconds=int(d.get("audio_seconds", 0)),
+            calls=int(d.get("calls", 0)),
+        )
+
+
+@dataclass(frozen=True)
+class UsageSummary:
+    owner_id: str | None = None
+    days: int | None = None
+    total_cost_rub: float = 0.0
+    by_meter: list[MeterCost] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> UsageSummary:
+        meters = d.get("by_meter") or []
+        return cls(
+            owner_id=d.get("owner_id"),
+            days=d.get("days"),
+            total_cost_rub=float(d.get("total_cost_rub", 0.0)),
+            by_meter=[MeterCost.from_dict(m) for m in meters if isinstance(m, dict)],
+        )
+
+
+@dataclass(frozen=True)
+class OwnerUsage:
+    owner_id: str | None = None
+    total_cost_rub: float = 0.0
+    by_meter: list[MeterCost] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> OwnerUsage:
+        meters = d.get("by_meter") or []
+        return cls(
+            owner_id=d.get("owner_id"),
+            total_cost_rub=float(d.get("total_cost_rub", 0.0)),
+            by_meter=[MeterCost.from_dict(m) for m in meters if isinstance(m, dict)],
+        )
+
+
+@dataclass(frozen=True)
+class UsageBreakdown:
+    days: int | None = None
+    total_cost_rub: float = 0.0
+    owners: list[OwnerUsage] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> UsageBreakdown:
+        owners = d.get("owners") or []
+        return cls(
+            days=d.get("days"),
+            total_cost_rub=float(d.get("total_cost_rub", 0.0)),
+            owners=[OwnerUsage.from_dict(o) for o in owners if isinstance(o, dict)],
+        )

agentum_cloud_sdk-0.1.62.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: agentum-cloud-sdk
+Version: 0.1.62
+Summary: Типизированный async-клиент Agentum Cloud (/v1): загрузка документов, поиск и RAG-вопросы по вашим файлам.
+Project-URL: Homepage, https://cloud.agentums.ru
+Project-URL: Repository, https://gitlab.basis-pro.tech/agentum-systems/agentum-cloud
+Author: Agentum Systems
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentum,ai,async,documents,httpx,llm,rag,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# agentum-cloud-sdk
+
+Типизированный **async**-клиент для [Agentum Cloud](https://cloud.agentums.ru) — облака
+ваших документов с поиском и ответами на естественном языке (RAG). Загружаете файлы
+(PDF, DOCX, изображения, аудио), а затем ищете по ним и задаёте вопросы — ИИ отвечает
+с ссылками на источники.
+
+Тонкая обёртка над `httpx` поверх REST `/v1`. Полные type hints, `py.typed`.
+
+## Установка
+
+```bash
+pip install agentum-cloud-sdk
+```
+
+Обновление до свежей версии: `pip install -U agentum-cloud-sdk`.
+
+Требуется Python 3.13+.
+
+## Токен
+
+1. Войдите в приложение [cloud.agentums.ru](https://cloud.agentums.ru) (через Яндекс).
+2. **Настройки → API-токены → Создать** — скопируйте токен `ak_…` (показывается один раз).
+
+Токен привязан к вашему аккаунту и подписке. Держите его в секрете (как пароль);
+если скомпрометирован — отзовите в настройках и создайте новый.
+
+## Быстрый старт
+
+```python
+import asyncio
+from agentum_cloud import AgentumClient
+
+
+async def main() -> None:
+    async with AgentumClient(
+        base_url="https://api.cloud.agentums.ru",
+        api_key="ak_ваш_токен",
+    ) as cloud:
+        # Загрузить документ
+        with open("contract.pdf", "rb") as f:
+            obj = await cloud.upload("contract.pdf", f.read())
+
+        # Дождаться, пока документ проиндексируется
+        await cloud.wait_until_ready(obj.id)
+
+        # Спросить — ответ с цитатами из ваших файлов
+        answer = await cloud.ask("Какой срок действия договора?")
+        print(answer.answer)
+        for c in answer.citations:
+            print(f"  источник: {c.filename}")
+
+
+asyncio.run(main())
+```
+
+## Что умеет
+
+| Метод | Назначение |
+|-------|-----------|
+| `upload(filename, data)` | загрузить документ/изображение/аудио |
+| `wait_until_ready(object_id)` | дождаться окончания индексации |
+| `list_objects(...)` / `get_object(id)` | список / детали файла (заголовок, summary, теги) |
+| `get_content(id)` | временная ссылка на оригинал (presigned URL) |
+| `search(q)` | гибридный поиск (вектор + полнотекст) по вашим файлам |
+| `ask(query)` | ответ ИИ по вашим документам + цитаты-источники |
+| `transcribe(filename, data)` | расшифровка аудио в текст |
+| `get_usage(days=...)` | расход (₽) и разбивка по статьям |
+| `delete_object(id)` | удалить файл |
+
+Все методы — корутины; клиент — async-context-manager (`async with`).
+
+## Заметки
+
+- Данные изолированы по аккаунту: токен видит только файлы вашего аккаунта. Файлы,
+  загруженные через [Telegram-бота](https://cloud.agentums.ru), доступны здесь же после
+  привязки бота к аккаунту.
+- Базовый URL прода — `https://api.cloud.agentums.ru`.
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

agentum_cloud_sdk-0.1.62.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentum_cloud/__init__.py,sha256=nM_ZAPUdpGEVGivIz0ufVwMstLXUi42F6Aez5wD3sKk,1332
+agentum_cloud/client.py,sha256=a6UOFDRrlk6VHALfE6D7VrzKQtfl_ywGCftO7kVBPGA,17378
+agentum_cloud/errors.py,sha256=diRKsl8Rmr-MAK3xfi321Yvr1SyvwtkYDTGJmbntUOY,723
+agentum_cloud/models.py,sha256=d97ZCtszlem6qBF4rzC5TdGqGL0VmdDae3Q1fRxf2GA,8872
+agentum_cloud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentum_cloud_sdk-0.1.62.dist-info/METADATA,sha256=D0EthZMLtyzNGnkjH7x2nr85eK7yiMudVnMpQJTyNA8,4703
+agentum_cloud_sdk-0.1.62.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentum_cloud_sdk-0.1.62.dist-info/licenses/LICENSE,sha256=eQ7tb37mTyh-nyBz8b2-gtI2QnI-AYfmr8WUp2C6HCM,1072
+agentum_cloud_sdk-0.1.62.dist-info/RECORD,,

agentum_cloud_sdk-0.1.62.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

agentum_cloud_sdk-0.1.62.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentum Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.