Metadata-Version: 2.5
Name: agentum-cloud-sdk
Version: 0.1.570
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)
        if answer.primary:  # закреплённый главный файл под запрос («найди X» → вот он)
            print(f"  главный файл: {answer.primary.filename}")
        for c in answer.citations:
            print(f"  источник: {c.filename}")

        # Продолжить разговор: вернув session_id, получаем ответ с оглядкой на сказанное.
        # Без него «а подробнее?» ушло бы на сервер отдельным диалогом и отвечалось с нуля.
        more = await cloud.ask("а подробнее?", session_id=answer.session_id)
        print(more.answer)


asyncio.run(main())
```

## Агентный режим (стрим)

`agent_chat` возвращает поток событий: агент сам решает, какими инструментами
воспользоваться (поиск, конвертация, перевод, сборка PDF), и по пути шлёт токены ответа.

```python
from contextlib import aclosing

from agentum_cloud import AgentumClient


async def main() -> None:
    async with AgentumClient(base_url="https://api.cloud.agentums.ru", api_key="ak_…") as cloud:
        # aclosing обязателен: только он закроет HTTP-ответ, если выйти из цикла через break
        async with aclosing(cloud.agent_chat("собери все счета за июнь в один PDF")) as stream:
            async for ev in stream:
                if ev.type == "token":
                    print(ev.delta, end="", flush=True)
                elif ev.type == "tool_start":
                    print(f"\n[{ev.name}]")
                elif ev.type == "paused":
                    # Опасное действие ждёт подтверждения — стрим на этом закончился
                    await confirm(cloud, ev)
                    break
```

Форма стрима — два правила, которые легко нарушить:

- **`paused` — конец стрима.** События `done` не будет: агент упёрся в опасный инструмент
  (удаление, перезапись файла) и ждёт решения. Продолжают ран через `agent_continue`,
  передавая решения по **всем** инструментам из события одним вызовом — не упомянутый
  инструмент молча не выполнится.
- **`error` — не конец стрима.** Кадр с ошибкой не прерывает ран: за ним могут прийти ещё
  токены и `done`. Выходить из цикла по `error` — потерять хвост ответа.

```python
async def confirm(cloud, ev) -> None:
    decisions = [(t.tool_call_id, input(f"{t.name} {t.args}? [y/n] ") == "y") for t in ev.tools]
    async with aclosing(
        cloud.agent_continue(run_id=ev.run_id, session_id=ev.session_id, decisions=decisions)
    ) as stream:
        async for ev in stream:
            if ev.type == "token":
                print(ev.delta, end="", flush=True)
```

`session_id` из `start`/`done` продолжает диалог: `agent_chat(..., session_id=sid)`. История
доступна через `list_chats()` / `get_chat(id)`; у агентных сессий `kind == "agent"`, и их `id`
можно передать обратно в `agent_chat` как `session_id`.

## Что умеет

Клиент покрывает продуктовый контракт `/v1` целиком. Ниже — по разделам; полное описание
каждого метода лежит в его докстроке (`help(cloud.имя_метода)`).

**Файлы.** `upload` · `add_link` (страница или видео по URL) · `upload_archive` ·
`wait_until_ready` · `list_objects` / `list_objects_page` (у второго ещё и `total`) ·
`get_object` · `rename_object` · `update_enrichment` · `reprocess_object` ·
`save_to_cloud` · корзина: `delete_object` (soft) → `restore_object` /
`delete_object_permanent` / `empty_trash`.

**Имена.** Облако предлагает имя и папку, а решает пользователь: `accept_folder`,
`apply_ai_name`, `restore_name`, `lock_name`.

**Содержимое.** `get_content` (временная ссылка) · `get_raw` / `get_thumbnail` /
`get_page_image` (байты через API — у них наш CORS) · `get_text_content` · `save_content`
(с `base_version` — защита от гонки редакторов) · `list_revisions` / `restore_revision` ·
черновики (`get_draft` / `save_draft` / `delete_draft`) · `get_summary` · `translate`.

**Преобразования.** `convert_targets` → `convert` · `pdf_op` (15 операций) · `image_op` ·
`assemble_pdf` · `zip_objects` · `reorganize`. Все асинхронные: возвращают `task_id`,
готовность — соответствующий `*_status`, все они дают один `JobStatus`.

**Осмысление.** `summarize` · `suggested_questions` · `protocol_questions` →
`build_protocol` (протокол встречи отдельным файлом) · диаризация: `diarize`,
`get_diarization`, `get_transcript`, `rename_speakers` (он же энроллмент голоса),
`list_voice_profiles`.

**Поиск и ответы.** `search` (вектор + полнотекст + имя с расширением) · `ask`
(`session_id` продолжает разговор, `object_ids` сужает до конкретных файлов) · `chat`
(без агента и инструментов) · `extract_attachment` (текст файла без сохранения) ·
`classify_intent` · `command` · `rewrite` · `transcribe` · `generate_document`.

**Агент.** `agent_chat` / `agent_continue` (стрим, см. выше) · `agent_status` ·
`agent_task` · память: `list_agent_memory`, `forget_agent_memory`, `clear_agent_memory` ·
роли: `list_agent_profiles`, `activate_agent_profile`, `create_agent_profile`.

**Организация.** Папки (`list_collections`, `create_collection`, `update_collection`,
`move_object`, `set_primary_object`) · темы (`list_themes`, `create_theme`) · публичные
ссылки (`create_share`, `list_shares`, `revoke_share` и чтение по токену: `get_shared`,
`list_shared_objects`, `get_shared_raw`, `upload_to_share`) · скрытая зона
(`unlock_hidden` → `hidden_token=` в списках и поиске).

**Дела.** Поручения (`list_tasks`, `update_task`) · уведомления (`list_notifications`,
`mark_notifications_read`) · календарь (`list_events`, `create_event`, `agenda`,
`create_calendar_feed`, `import_ics`).

**Аккаунт и расход.** `get_usage` / `get_usage_history` / `get_usage_breakdown` /
`get_quota` · `get_settings` / `update_settings` · `list_models` · `get_referral` ·
свои LLM и хранилище (`save_llm_integration`, `save_s3_integration`, `test_integration`,
`migrate_storage`) · свои Telegram-боты (`list_bots`, `create_bot`, `list_bot_chats`,
`list_bot_subscribers`) · `health` / `health_deep`.

Все методы — корутины, кроме `agent_chat`/`agent_continue`: они возвращают асинхронный
генератор, так что `await` не нужен — сразу `async for` (внутри `aclosing`).
Клиент — async-context-manager (`async with`).

## Заметки

- Данные изолированы по аккаунту: токен видит только файлы вашего аккаунта. Файлы,
  загруженные через [Telegram-бота](https://cloud.agentums.ru), доступны здесь же после
  привязки бота к аккаунту.
- Базовый URL прода — `https://api.cloud.agentums.ru`.
- **Загрузка асинхронна.** `upload` отвечает `status="pending"` до обработки: искать по
  содержимому сразу после загрузки бесполезно, дождитесь `wait_until_ready`.
- **Список по умолчанию прячет четыре класса файлов** — удалённые, вложения чата,
  заметки и скрытые. «Файл загрузился, но его нет» почти всегда объясняется этим:
  посмотрите `list_objects(trashed=True)`.
- **Ретраи осторожные, и это осознанно.** `504` не повторяется (это дедлайн сервера —
  повтор лишь сожжёт токены), неидемпотентный POST не перезапускается по таймауту ответа,
  агентный стрим идёт мимо ретраев вовсе. Автоматически повторяется только запрос, который
  заведомо не дошёл до сервера.
- Вне SDK намеренно остались браузерные потоки входа, вебхуки чужих систем и управление
  аккаунтом с биллингом — они живут на сессии приложения, а не на `ak_`-токене.

## Лицензия

MIT — см. [LICENSE](LICENSE).
