agentum-cloud-sdk 0.1.122

Типизированный async-клиент Agentum Cloud (/v1): загрузка документов, поиск и RAG-вопросы по вашим файлам.

agentum-cloud-sdk

Типизированный async-клиент для Agentum Cloud — облака ваших документов с поиском и ответами на естественном языке (RAG). Загружаете файлы (PDF, DOCX, изображения, аудио), а затем ищете по ним и задаёте вопросы — ИИ отвечает с ссылками на источники.

Тонкая обёртка над httpx поверх REST /v1. Полные type hints, py.typed.

Установка

pip install agentum-cloud-sdk

Обновление до свежей версии: pip install -U agentum-cloud-sdk.

Требуется Python 3.13+.

Токен

1. Войдите в приложение cloud.agentums.ru (через Яндекс).
2. Настройки → API-токены → Создать — скопируйте токен ak_… (показывается один раз).

Токен привязан к вашему аккаунту и подписке. Держите его в секрете (как пароль); если скомпрометирован — отзовите в настройках и создайте новый.

Быстрый старт

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}")


asyncio.run(main())

Что умеет

Метод	Назначение
upload(filename, data)	загрузить документ/изображение/аудио
wait_until_ready(object_id)	дождаться окончания индексации
list_objects(...) / get_object(id)	список / детали файла (заголовок, summary, теги)
get_summary(id)	карточка содержания (метаданные обогащения)
get_content(id)	временная ссылка на оригинал (presigned URL)
search(q)	гибридный поиск (вектор + полнотекст + имя/расширение) по вашим файлам
ask(query)	ответ ИИ по вашим документам + цитаты и закреплённый файл (primary)
translate(id, target_lang)	перевести документ → новый объект
transcribe(filename, data)	расшифровка аудио в текст
get_usage(days=...)	расход (₽) и разбивка по статьям
get_usage_history(days=...)	дневной ряд расхода (₽ + токены + вызовы) для графика
list_collections() / create_collection(...) / move_object(...)	папки и раскладка файлов
delete_object(id)	удалить файл

Все методы — корутины; клиент — async-context-manager (async with).

Заметки

• Данные изолированы по аккаунту: токен видит только файлы вашего аккаунта. Файлы, загруженные через Telegram-бота, доступны здесь же после привязки бота к аккаунту.
• Базовый URL прода — https://api.cloud.agentums.ru.

Лицензия

MIT — см. LICENSE.