Интеграция AI-помощника¶

Роль в продукте¶

Во внешнем продукте используются формулировки «KarmaCode анализирует» и «система сопоставляет»; поставщик модели и внутренняя реализация не являются маркетинговой функцией. Однако в технической документации, логах и audit trail происхождение результата скрывать нельзя.

AI делает только платную интерпретацию. Он не вычисляет положения планет, дизайн-дату, числа или арканы и не исправляет детерминированный JSON. Неполный/невалидный расчёт не отправляется модели.

Вход¶

InterpretationInputV1 содержит:

schema/algorithm versions и immutable ID четырёх calculation artifacts;
нормализованные факты каждой системы со стабильными factId;
выбранные продуктовые оси из документа об осях;
тип результата: core_reading, route, daily|weekly|monthly_forecast;
locale и safety policy version.

Не отправляются e-mail, телефон, payment data, точный адрес, административные заметки и документы. Имя не нужно для вывода и по умолчанию заменяется псевдонимом. Для прогноза добавляются только рассчитанные транзиты/циклы и допустимый контекст целей; пользовательский текст всегда помечается как untrusted data.

Выход¶

Модель обязана вернуть structured JSON утверждённой схемы, а не готовый произвольный HTML:

{
    "schemaVersion": "interpretation-v1",
    "summary": "...",
    "axes": [
        {
            "axisId": "decision_style",
            "headline": "...",
            "synthesis": "...",
            "confidence": "medium",
            "evidenceRefs": ["astrology:mercury:...", "numerology:life-path:..."],
            "tensions": [
                {
                    "statement": "...",
                    "leftEvidenceRefs": ["..."],
                    "rightEvidenceRefs": ["..."]
                }
            ],
            "practices": ["..."]
        }
    ],
    "consultationTriggers": ["..."],
    "disclaimerKey": "entertainment-v1"
}

Backend валидирует JSON Schema, существование всех evidence refs, лимиты длины, запрещённые утверждения и полноту осей. Клиентский текст рендерится из полей безопасным renderer; model output никогда не выполняется как HTML/Markdown.

Pipeline¶

Проверить активный entitlement и наличие всех обязательных расчётов.
Собрать input, канонизировать и вычислить generationKey.
Вернуть готовый артефакт, если такой ключ уже существует.
Иначе создать GenerationJob; один ключ защищён unique constraint.
Worker разрешает логический providerKey через registry, выбирает model deployment по server config и посылает versioned system prompt и structured schema через AiProvider.
Провести schema/evidence/safety validation. При исправимой ошибке — один constrained repair; не бесконечный retry.
Сохранить input hash, output, provider request ID, model snapshot, token usage, latency, prompt/policy versions и moderation result.
Опубликовать артефакт и событие для уведомления. Failed job не списывает повторную продуктовую квоту.

generationKey = SHA-256(calculationResultHashes + generationType + period + promptVersion + modelSnapshot + locale). Повторное чтение не вызывает AI. Новая модель/методика создаёт новый артефакт; опубликованный текст не меняется задним числом.

Provider abstraction¶

AiProvider.capabilities() ->
  { structuredOutput, moderation, maxInputTokens }

AiProvider.generateStructured(request, schema, options) ->
  { providerKey, providerRequestId, modelSnapshot, output, usage, finishReason }

Бизнес-код не импортирует SDK поставщика. Adapter отвечает за auth, timeout, retry допустимых transport errors, structured-output API, moderation и нормализацию usage/errors. Provider registry и конфигурация выбирают adapter во время выполнения; доменные input/output schemas, jobs и артефакты от него не зависят. Это позволяет иметь несколько адаптеров, проводить A/B моделей и менять поставщика без миграции домена.

SDK конкретного AI-провайдера сознательно не добавлен в каркас. Во время разработки используется deterministic FixtureAiProvider, читающий утверждённые ответы из тестовых fixtures; он проверяет весь pipeline без внешней модели. Когда поставщик будет выбран, добавляется только infrastructure adapter. Выбор первого provider/model, договор по обработке данных, регион, лимиты и оценка качества входят в pre-pilot gate, но не блокируют модель БД.

Как сопоставлять системы¶

Каждый тезис обязан ссылаться минимум на один фактический factId; сильный синтез — на две независимые системы.
Совпадение описывается кратко, без искусственного усиления уверенности.
Расхождение не «усредняется»: показываются обе тенденции, контексты их проявления и открытый вопрос.
Отсутствие данных явно обозначается; AI не достраивает неизвестный ASC/дом/тип.
Сначала формируется evidence matrix по осям, затем текст. Оси и правила стабильны между пользователями.
Consultation trigger допустим в точке содержательного противоречия, но не через страх, диагноз или давление.

Безопасность содержания¶

Все результаты маркируются как развлекательно-консультационные, не как научный факт или гарантия будущего.
Запрещены диагнозы, лечение, отмена медицинской помощи, юридические и инвестиционные указания, категоричные прогнозы смерти/болезни/беременности, манипуляция страхом и дискриминационные выводы.
Раздел «здоровье» переименовать в «самочувствие и забота о себе» либо ограничить общими безопасными практиками; критические симптомы всегда направляют к квалифицированному специалисту.
Модель не принимает решений о платеже, бане, возврате, рейтинге практика или доступе.
Prompt injection из goal/consultation content нейтрализуется структурными границами и запретом выполнять инструкции из пользовательских полей.
Опасный/невалидный результат уходит в review/failed и не публикуется автоматически.

Экономика и наблюдаемость¶

На пользователя/период вводятся лимиты, max input/output tokens и budget alarm. Cache hit rate, jobs, latency, tokens/cost, schema failures, safety blocks, retry и оценки качества доступны через технические метрики и логи без лишних ПДн. Административной панели и административного API в MVP нет.

При отказе provider API уже рассчитанные бесплатные данные и старые публикации остаются доступны. Пользователь видит асинхронный статус и возможность безопасного retry, а не пустую страницу.

Оценка качества до запуска¶

Эксперт размечает набор расчётов, включая совпадения, противоречия и неполные данные.
Для каждой версии prompt/model прогоняются одинаковые fixtures.
Рубрика: фактологическая привязка, покрытие осей, корректность tension, отсутствие выдуманных фактов, полезность, повторяемость, стиль и safety.
Hard fail: несуществующий evidence ref, изменение исходного расчёта, опасный совет, утечка данных или невалидный JSON.
Первая production-выборка проходит ручное review; пользователь может пожаловаться на конкретный фрагмент.

Принятый стартовый режим¶

архитектура provider-agnostic; конкретный provider/model — runtime-конфигурация и immutable snapshot результата;
pipeline двухшаговый: сначала evidence plan в строгой схеме, затем narrative JSON;
внешняя модель не вызывается до появления adapter; для разработки используется FixtureAiProvider;
первая выборка перед внешним пилотом проходит ручное экспертное review;
регенерация не перезаписывает публикацию и требует нового versioned artifact; пользовательская квота задаётся тарифом;
disclosure сообщает об автоматизированной интерпретации, не превращая название модели в продуктовую функцию.

Коммерческий provider/model и связанные legal/data параметры намеренно выбираются позднее по pre-pilot checklist.