Prompt Server Service Spec

Статус: draft для planned capability.

1. Назначение и граница сервиса

Назначение будущего сервиса:

  • обслуживать published prompt assets;

  • выполнять роль prompt registry для published blocks and compositions;

  • детерминированно resolve-ить и render-ить их;

  • не предоставлять authoring и draft access.

Потребители:

  • downstream runtime clients;

  • internal/external services, использующие published prompts;

  • C++ clients and SDK;

  • Python clients and SDK;

  • backend and agent integrations.

Не-цели:

  • authoring;

  • draft access;

  • hidden rewrite;

  • GUI preview semantics as delivery contract;

  • generic model gateway;

  • live LLM completion API as default contract.

2. Потребители и зависимости

Потребители:

  • downstream services

  • runtime clients

  • C++-side integrations

  • Python-side integrations

Зависимости:

  • published repository

  • renderer

  • authn/authz layer

  • parameter validation layer

  • compatibility/versioning policy

3. Ожидаемые методы и контрактные точки

Ожидаемые базовые контракты:

  • inspect published blocks/compositions and versions

  • resolve published composition

  • render with runtime parameters

  • inspect available published assets

Важно:

  • это ожидаемые методы planned capability, а не уже реализованный API.

  • server contract должен быть language-neutral и одинаково пригодным для C++ и Python clients.

Ожидаемые семейства endpoint-ов:

  • registry GET /blocks/{id}, GET /compositions/{id}, GET /compositions/{id}/versions

  • resolve POST /resolve

  • render POST /render

4. Предлагаемые endpoint contracts

Ниже фиксируется рекомендуемый shape будущего HTTP-style API. Это still planned contract, а не описание уже существующей реализации.

4.1. GET /blocks/{id}

Назначение:

  • получить published block metadata;

  • получить latest published version или конкретную published version.

Ожидаемые query params:

  • version optional explicit published version.

  • latest=true optional shortcut для latest published version.

Успешный ответ должен содержать:

  • block_id

  • version

  • type

  • language

  • description

  • templ

  • defaults

  • tags

  • published_at

4.2. GET /compositions/{id}

Назначение:

  • получить published composition metadata;

  • получить explicit published version или latest published version.

Ожидаемые query params:

  • version

  • latest=true

Успешный ответ должен содержать:

  • composition_id

  • version

  • description

  • fragment_summary

  • published_at

  • optional lightweight fragment metadata without full render

4.3. GET /compositions/{id}/versions

Назначение:

  • перечислить опубликованные версии composition;

  • дать клиенту stable way выбрать render target.

Успешный ответ должен содержать:

  • composition_id

  • versions list of published version descriptors

Каждый version descriptor должен включать:

  • version

  • published_at

  • optional revision_comment

  • optional deprecated

4.4. POST /resolve

Назначение:

  • получить resolved published composition view без окончательного render;

  • увидеть, какие published block versions будут использованы.

Ожидаемый request body:

  • composition_id

  • optional version

  • optional latest_published

  • optional params

Ожидаемый response body:

  • composition_id

  • version

  • resolved_blocks

  • fragments

  • required_params

  • warnings

Каждый resolved block entry должен включать:

  • block_id

  • version

  • type

  • language

  • description

4.5. POST /render

Назначение:

  • получить deterministic rendered prompt для published composition.

Ожидаемый request body:

  • composition_id

  • optional version

  • optional latest_published

  • params

  • optional strict_mode

  • optional response_format

Ожидаемый response body:

  • composition_id

  • version

  • rendered_text

  • resolved_blocks

  • param_summary

  • warnings

  • optional content_hash

resolved_blocks должны позволять клиенту понять:

  • какие published block versions вошли в render;

  • какой именно versioned asset был источником итогового текста.

5. Language-neutral Contract Rules

Remote contract должен соблюдать:

  • semantic parity across C++ and Python clients;

  • no language-specific hidden fields or privileged behavior;

  • одинаковую версионную и error semantics для обоих language surfaces.

При этом допустимы:

  • idiomatic differences in wrapper APIs;

  • разные transport helpers или typed models поверх одного server contract.

6. Входной контракт

Ожидаемые входы:

  • asset id / version

  • runtime params

  • optional response format

  • optional latest-published resolution mode

Недопустимые входы:

  • draft ids;

  • authoring mutation commands;

  • неявные AI rewrite requests в рамках базового deterministic contract.

Дополнительные правила для POST /render:

  • либо version, либо latest_published, но не двусмысленная комбинация;

  • params должны быть object-like key-value contract;

  • request не должен ссылаться на draft identity.

7. Выходной контракт

Ожидаемые выходы:

  • resolved published asset metadata

  • resolved block/version list

  • rendered text

  • validation errors

  • not-found / unavailable errors

Семантика:

  • возвращаемые данные должны соответствовать published-only view;

  • response не должен содержать draft state;

  • render response должен явно показывать, какие published versions участвовали в результате.

Дополнительные правила output contract:

  • GET endpoints должны отдавать registry metadata без hidden authoring state;

  • POST /resolve не должен притворяться окончательным render output;

  • POST /render должен возвращать final deterministic text plus version metadata.

8. Правила доменного контракта

Будущий сервис должен соблюдать:

  • addressable только published assets;

  • draft ids/versions должны отклоняться;

  • contract changes требуют compatibility policy;

  • delivery runtime не должен мутировать authoring state;

  • deterministic render - базовая норма поведения;

  • blocks and compositions должны оставаться first-class runtime entities, а не быть скрытыми за одним render endpoint.

9. Источники данных и иерархия

Primary source:

  • published repository

Допустимые вычисления:

  • deterministic resolve/render

  • parameter validation

Недопустимые скрытые источники:

  • draft storage

  • GUI state

  • implicit AI prompting в базовом delivery contract

10. Ошибки и retry policy

Ожидаемые ошибки:

  • asset not found;

  • missing required params;

  • invalid params;

  • repository unavailable;

  • authn/authz failures.

Ожидаемая политика:

  • not found - explicit not found;

  • invalid params - validation error;

  • published repository unavailable - fail closed;

  • fallback to draft data недопустим.

Для planned endpoint shape дополнительно ожидаются:

  • 400 invalid request shape or invalid params.

  • 401/403 authn/authz failures.

  • 404 published asset or version not found.

  • 409 incompatible version selection semantics, если request противоречив.

  • 503 published repository unavailable.

11. Routing и confidence policy

В базовом deterministic server contract:

  • confidence routing отсутствует;

  • model routing отсутствует;

  • AI-derived behavior не должен быть частью default contract.

Отдельно фиксируется:

  • server не должен позиционироваться как replacement для full LLM inference gateway;

  • его primary job - published prompt registry and render delivery.

12. Edge cases и fallback behavior

Основные edge cases:

  • draft requested Reject.

  • invalid params Reject with validation error.

  • unavailable published store Fail closed, do not switch to draft data.

  • both version and latest_published conflict Reject as invalid request.

  • render request with missing required params Reject with validation error, do not partially render hidden defaults unless policy explicitly allows them.

  • capability not implemented yet Документация должна явно маркировать статус planned.

13. Источник требований