Python SDK: Ai: анализ и преобразование

ctx.ai() вызывается через платформу и расходует AI-бюджет пространства, кроме подтверждённого попадания extract() в кэш. Все методы синхронны. Модель выбирает платформа: сценарий задаёт уровень и усилие.

Примеры являются фрагментами тела def run(ctx):. Все методы SDK синхронны, await не нужен.

Перед первым вызовом

• За один прогон доступно не более восьми AI-вызовов. В один запрос передавайте не более 48 КБ. Если страница большая, сначала выберите нужный фрагмент обычными методами SDK.
• Запрос расходует AI-бюджет пространства. Фактический расход отражается в лимитах и журнале операций; время выполнения сценария учитывается отдельно. Проверенный кэш extract() позволяет повторно использовать правило без нового AI-вызова.
• Не передавайте в запрос пароли, токены и персональные данные. Не отправляйте туда результат ctx.credential().
• Автономный агент не может выполнить AI-запрос без платформы. Для регулярного автономного сбора сохраняйте уже проверенные правила в коде.

Уровень и усилие

По умолчанию используются small и medium. Для repair(): large и high. Платформа сама выбирает подходящую модель; название модели в сценарии указывать не нужно.

Методы

• analyze()
• transform()
• find()
• repair()
• document_rows()
• extract()

analyze

ctx.ai().analyze(content, question, tier='small', effort='medium') -> str

Результат: str.

Отвечает текстом на вопрос о переданном содержимом. Ответ может ошибаться: проверяйте факты перед сохранением данных.

result = ctx.ai().analyze('sku,price\nA-1,1250', 'Which column contains the price?')

transform

ctx.ai().transform(data, shape, instruction='', tier='small', effort='medium') -> dict[str, Any]

Результат: dict[str, Any].

Преобразует объект под указанную структуру и возвращает сам результат как объект. Проверяйте обязательные поля перед ctx.emit().

result = ctx.ai().transform(
    {'title': 'Product', 'price': '1 250 RUB'},
    {'title': 'string', 'price': 'number'},
)

find

ctx.ai().find(html, description, tier='small', effort='medium') -> dict[str, str]

Результат: dict[str, str].

Предлагает CSS-селектор элемента по переданному HTML и описанию. Возвращает selector и reason; проверяйте селектор на странице.

result = ctx.ai().find('<button class="next">Next</button>', 'Next page button')

repair

ctx.ai().repair(source, error, goal, tier='large', effort='high') -> str

Результат: str.

Возвращает предложение по исправлению переданного Python-кода. Не сохраняет его и не публикует новую версию. Проверьте ответ и сделайте пробный прогон.

result = ctx.ai().repair('def run(ctx):\n    pass', 'Element not found', 'Collect the product name')

document_rows

ctx.ai().document_rows(document, sheet=0) -> dict[str, Any]

Результат: dict[str, Any].

Планирует строки и заголовок таблицы по форме ячеек, без раскрытия значений внешней модели. Вернёт ready, needs_range или incomplete; в двух последних случаях задайте диапазон вручную.

document = ctx.documents().from_url(ctx.param('file_url'), 'prices.csv')
result = ctx.ai().document_rows(document, 0)
if result.get('status') == 'ready':
    for row in result.get('records', []):
        ctx.emit(row)

extract

ctx.ai().extract(input, schema, options=None) -> dict[str, Any]

Результат: dict[str, Any].

Извлекает записи из одной HTML-таблицы, JSON-массива, массива строк или одного листа документа. CSV сначала прочитайте через documents().from_bytes() или sources().document(). PDF без таблицы и произвольные карточки страницы нужно предварительно преобразовать в строки.

result = ctx.ai().extract(
    [['SKU', 'Price'], ['A-1', '1 250,50']],
    {'sku': {'type': 'string', 'unique': True}, 'price': {'type': 'decimal', 'min': 0}},
    {'key': 'supplier-prices', 'expected_rows': 1},
)
for record in result.get('records', []):
    ctx.emit(record, record['sku'])

records содержит данные текущего запуска, даже если правило найдено в кэше. Поля cache_hit и ai_used помогают понять, был ли запрос к модели. Для явного сопоставления можно указать column у полей и header_row в настройках; индексы начинаются с нуля. При неоднозначном заголовке проверьте выбор колонок вручную.

Если сервис недоступен или вернул неверный ответ, SDK выдаёт ошибку. Предложенный селектор, преобразование или исправление кода всегда проверяйте пробным прогоном, прежде чем публиковать сценарий.

Жизненный цикл · Лимиты и баланс

Ошибки и контекст выполнения

Все вызовы синхронны. Неверный аргумент или формат данных может вызвать ValueError/TypeError; отказ платформы или недоступность сервиса вызывает RuntimeError. Отсутствие элемента/значения даёт None либо пустой список только там, где это явно описано. Не превращайте любое исключение в пустой успешный результат. Методы внешних сервисов недоступны в преобразовании выгрузки; см. ограничения преобразований и среду.