API Reference

TextFoundry API Documentation

Обзор библиотеки

TextFoundry — это C++ библиотека для конструирования текстов и промптов из переиспользуемых смысловых блоков. Библиотека предоставляет детерминированный движок для сборки текстов с поддержкой параметризации, версионирования, структурированных композиций и explicit AI-assisted workflow.

Основные принципы

  • Engine-first: движок — самостоятельная библиотека без зависимостей от UI

  • No magic: обычный render path детерминирован и не вызывает AI автоматически

  • Control over convenience: контроль над текстом важнее скрытой автоматизации

Пространство имён

Все основные классы и функции находятся в пространстве имён tf.

Основные типы и псевдонимы

Идентификаторы

Тип Определение Описание

BlockId

std::string

Глобально уникальный идентификатор блока

CompositionId

std::string

Уникальный идентификатор композиции

ParamValue

std::string

Значение параметра

Params

std::unordered_map<std::string, ParamValue>

Карта параметров

ParamSchema

struct ParamSchema {
    std::string name;
    bool required = false;
    std::optional<ParamValue> defaultValue;
};

Версионирование

struct Version {
    uint16_t major = 0;
    uint16_t minor = 0;

    std::string ToString() const;
};

Version v1{1, 0};
Version v2{1, 2};
assert(v1 < v2);

Перечисления

BlockType

Значение Назначение

Role

Роли и инструкции для LLM

System

Системный контекст и framing

Mission

Цели, задачи и intent blocks

Safety

Ограничения безопасности и guardrails

Constraint

Формальные ограничения и требования

Style

Стилистические параметры

Domain

Предметные блоки

Meta

Вспомогательные и meta-блоки

BlockState

Значение Описание

Draft

Редактируемая версия

Published

Зафиксированная версия

Deprecated

Устаревшая, но доступная для чтения

SeparatorType

Значение Описание

Newline

Перевод строки

Paragraph

Пустая строка между фрагментами

Hr

Горизонтальный разделитель

FragmentType

Значение Описание

BlockRef

Ссылка на блок

StaticText

Inline текст без параметров

Separator

Типизированный разделитель

ErrorCode

Код Описание

MissingParam

Обязательный параметр не предоставлен

InvalidParamType

Несоответствие типа параметра

UnknownParam

Параметр не определён в схеме

VersionRequired

Для BlockRef требуется версия

VersionNotFound

Запрошенная версия не существует

InvalidVersion

Некорректная версия

BlockNotFound

Блок не найден

CompositionNotFound

Композиция не найдена

DuplicateId

Идентификатор уже существует

InvalidStateTransition

Недопустимый переход состояния

DraftRequired

Операция требует Draft состояния

PublishedRequired

Операция требует Published состояния

TemplateSyntaxError

Ошибка синтаксиса шаблона

CircularReference

Циклическая ссылка

StorageError

Ошибка хранилища

Success

Успех

Error и Result

struct Error {
    ErrorCode code;
    std::string message;

    bool is_error() const noexcept;
    bool is_success() const noexcept;

    static Error MissingParam(const std::string_view& paramName);
    static Error VersionRequired();
    static Error BlockNotFound(const std::string& blockId);
    static Error CompositionNotFound(const std::string& compId);
    static Error success();
};

template <typename T>
class Result {
public:
    explicit Result(T value);
    explicit Result(Error error);

    bool HasValue() const noexcept;
    bool HasError() const noexcept;
    T& value() &;
    const T& value() const&;
    Error& error() &;
    const Error& error() const&;
};

Класс Template

Шаблон с плейсхолдерами вида {{paramName}}.

class Template {
public:
    Template();
    explicit Template(std::string content);

    const std::string& Content() const noexcept;
    void SetContent(std::string content);

    std::vector<std::string> ExtractParamNames() const;
    Result<std::string> Expand(const Params& params) const;
};

Класс Block

Логический переиспользуемый фрагмент текста.

Основные методы

class Block {
public:
    Block();
    explicit Block(BlockId id);

    const BlockId& Id() const noexcept;
    BlockType type() const noexcept;
    BlockState state() const noexcept;
    const Version& version() const noexcept;
    const Template& templ() const noexcept;
    const Params& defaults() const noexcept;
    const std::vector<ParamSchema>& param_schema() const noexcept;
    const std::unordered_set<std::string>& tags() const noexcept;
    const std::string& language() const noexcept;
    const std::string& description() const noexcept;
    const std::string& revision_comment() const noexcept;

    void SetId(BlockId id);
    void SetType(BlockType type);
    void SetState(BlockState state);
    void SetTemplate(Template templ);
    void SetDefaults(Params defaults);
    void SetParamSchema(std::vector<ParamSchema> schema);
    void SetTags(std::unordered_set<std::string> tags);
    void SetLanguage(std::string lang);
    void SetDescription(std::string desc);
    void SetRevisionComment(std::string comment);
    void SetVersion(const Version& v);

    Result<ParamValue> ResolveParam(
        const std::string& param_name,
        const Params& local_override,
        const Params& runtime_context
    ) const;

    bool CanResolveParam(
        const std::string& param_name,
        const Params& local_override,
        const Params& runtime_context
    ) const;

    Error ValidateParams(
        const Params& local_override,
        const Params& runtime_context
    ) const;

    Error publish(const Version& new_version);
    void deprecate();
};

BlockDraftBuilder

auto draft = BlockDraftBuilder("greeting.basic")
    .WithType(BlockType::Domain)
    .WithTemplate(Template("Здравствуйте, {{name}}!"))
    .WithDefault("name", "пользователь")
    .WithTag("formal")
    .WithLanguage("ru")
    .WithDescription("Базовое приветствие")
    .WithRevisionComment("Initial version")
    .build();

Класс BlockRef

Ссылка на блок с локальными переопределениями параметров.

class BlockRef {
public:
    BlockRef();
    explicit BlockRef(BlockId blockId);
    BlockRef(BlockId blockId, Version version);
    BlockRef(BlockId blockId, Version version, Params LocalParams);

    const BlockId& GetBlockId() const noexcept;
    const std::optional<Version>& version() const noexcept;
    const Params& LocalParams() const noexcept;
    bool UseLatest() const noexcept;

    void SetBlockId(BlockId id);
    void SetVersion(Version ver);
    void SetLocalParams(Params params);
    void SetUseLatest(bool UseLatest);

    BlockRef& WithParam(const std::string& name, ParamValue value);

    Error validate(bool is_draft_context = false) const;
    Result<Params> ResolveParams(
        const Block& block,
        const Params& runtime_context
    ) const;
};

Fragment, StaticText и Separator

struct StaticText {
    std::string content;
    explicit StaticText(std::string text);
    const std::string& text() const noexcept;
};

struct Separator {
    SeparatorType type;
    explicit Separator(SeparatorType sepType);
    std::string toString() const;
};

class Fragment {
public:
    Fragment();
    explicit Fragment(BlockRef blockRef);
    explicit Fragment(StaticText staticText);
    explicit Fragment(Separator separator);

    static Fragment MakeBlockRef(BlockRef ref);
    static Fragment MakeStaticText(std::string text);
    static Fragment MakeSeparator(SeparatorType type);

    FragmentType type() const noexcept;
    bool IsBlockRef() const noexcept;
    bool IsStaticText() const noexcept;
    bool IsSeparator() const noexcept;

    BlockRef& AsBlockRef() &;
    const BlockRef& AsBlockRef() const&;
    StaticText& AsStaticText() &;
    const StaticText& AsStaticText() const&;
    Separator& AsSeparator() &;
    const Separator& AsSeparator() const&;

    BlockRef* GetBlockRef() noexcept;
    const BlockRef* GetBlockRef() const noexcept;
    StaticText* GetStaticText() noexcept;
    const StaticText* GetStaticText() const noexcept;
    Separator* GetSeparator() noexcept;
    const Separator* GetSeparator() const noexcept;

    Error validate(bool isDraftContext = false) const;
};

Стили и контекст рендера

StructuralStyle

struct StructuralStyle {
    std::optional<std::string> blockWrapper;
    std::optional<std::string> preamble;
    std::optional<std::string> postamble;
    std::optional<std::string> delimiter;
};

SemanticStyle

struct SemanticStyle {
    std::optional<std::string> tone;
    std::optional<std::string> tense;
    std::optional<std::string> targetLanguage;
    std::optional<std::string> person;
    std::optional<std::string> rewriteStrength;
    std::optional<std::string> audience;
    std::optional<std::string> locale;
    std::optional<std::string> terminologyRigidity;
    std::optional<bool> preserveFormatting;
    std::optional<bool> preserveExamples;

    bool isEmpty() const noexcept;
};

StyleProfile

struct StyleProfile {
    StructuralStyle structural;
    SemanticStyle semantic;

    static StyleProfile plain();
};

RenderContext

struct RenderContext {
    Params params;
    std::optional<std::string> targetLanguage;
    bool strictMode = false;

    RenderContext& WithParam(const std::string& name, ParamValue value);
    RenderContext& WithLanguage(std::string lang);
    RenderContext& with_strict_mode(bool strict);
};

Класс Composition

Упорядоченный список фрагментов, формирующих полный текст.

class Composition {
public:
    Composition();
    explicit Composition(CompositionId id);

    const CompositionId& id() const noexcept;
    BlockState state() const noexcept;
    const Version& version() const noexcept;
    void SetVersion(const Version& v);

    const std::vector<Fragment>& fragments() const noexcept;
    const std::optional<StyleProfile>& GetStyleProfile() const noexcept;
    const std::string& ProjectKey() const noexcept;
    const std::string& description() const noexcept;
    const std::string& revision_comment() const noexcept;

    void SetId(CompositionId id);
    void SetState(BlockState state);
    void SetStyleProfile(StyleProfile profile);
    void SetProjectKey(std::string key);
    void SetDescription(std::string desc);
    void SetRevisionComment(std::string comment);

    Fragment& AddBlockRef(const BlockId& blockId, Version version, Params localParams = {});
    Fragment& AddBlockRefLatest(const BlockId& blockId, Params localParams = {});
    Fragment& AddStaticText(std::string text);
    Fragment& AddSeparator(SeparatorType type);

    void InsertFragment(size_t index, Fragment fragment);
    void RemoveFragment(size_t index);
    void ClearFragments();

    Fragment& fragment(size_t index);
    const Fragment& fragment(size_t index) const;
    size_t fragmentCount() const noexcept;

    Error validate() const;
    Error publish(Version new_version);
    void deprecate();
};

CompositionDraftBuilder

auto comp = CompositionDraftBuilder("welcome.message")
    .WithProjectKey("myproject")
    .WithStyleProfile(StyleProfile::plain())
    .WithDescription("Greeting composition")
    .WithRevisionComment("Initial version")
    .AddBlockRef("greeting.basic", 1, 0, {{"name", "Анна"}})
    .AddStaticText("\n\n")
    .AddSeparator(SeparatorType::Paragraph)
    .build();

Рендеринг

RenderResult

struct RenderResult {
    std::string text;
    CompositionId compositionId;
    Version compositionVersion;
    std::vector<std::pair<BlockId, Version>> blocksUsed;

    bool isEmpty() const noexcept;
};

IBlockCache и Renderer

class IBlockCache {
public:
    virtual ~IBlockCache() = default;
    virtual const Block* GetBlock(const BlockId& id, Version version) const = 0;
    virtual const Block* GetLatestBlock(const BlockId& id) const = 0;
    virtual void clear() = 0;
};

class Renderer {
public:
    Renderer();
    explicit Renderer(std::unique_ptr<IBlockCache> cache);

    void SetBlockCache(std::unique_ptr<IBlockCache> cache);
    void ClearCache();

    Result<RenderResult> Render(
        const Composition& composition,
        const RenderContext& context = RenderContext{}
    ) const;

    static Result<std::string> RenderBlock(
        const Block& block,
        const RenderContext& context = RenderContext{}
    );

    static std::string ApplyStructuralStyle(
        const std::vector<std::string>& fragmentTexts,
        const StructuralStyle& style
    );
};

AI-assisted API

Block generation

struct BlockGenerationRequest {
    std::string prompt;
    std::optional<BlockId> preferred_id;
    std::optional<BlockType> preferred_type;
    std::optional<std::string> preferred_language;
    std::vector<BlockId> existing_block_ids;
    bool allow_id_collision = false;
};

struct PromptSlicingRequest {
    std::string source_text;
    std::optional<std::string> preferred_language;
    std::optional<std::string> namespace_prefix;
    std::vector<BlockId> existing_block_ids;
    std::vector<BlockId> reusable_block_ids;
    std::vector<std::string> reusable_block_summaries;
    int preserve_reuse_percent = 70;
    bool preserve_order = false;
    bool allow_id_collision = false;
};

struct GeneratedBlockData {
    BlockId id;
    BlockType type = BlockType::Domain;
    std::string language = "en";
    std::string description;
    std::string templ;
    Params defaults;
    std::vector<std::string> tags;
};

struct GeneratedBlockBatch {
    std::vector<GeneratedBlockData> blocks;
};

Normalization и rewrite

struct BlockNormalizationRequest {
    Block source_block;
    SemanticStyle style;
};

struct NormalizedBlockData {
    std::string templ;
    std::optional<std::string> description;
    std::optional<std::string> language;
};

struct CompositionNormalizationRequest {
    CompositionId source_composition_id;
    std::optional<Version> source_version;
    SemanticStyle style;
    std::optional<std::string> target_composition_id;
    bool normalize_static_text = false;
    bool reuse_cached_blocks = true;
};

struct NormalizedCompositionResult {
    CompositionId composition_id;
    Version composition_version;
    std::vector<std::pair<BlockId, BlockId>> rewritten_blocks;
};

struct CompositionBlockRewriteRequest {
    CompositionId source_composition_id;
    std::optional<Version> source_version;
    std::string instruction;
    bool preserve_language = true;
    bool preserve_placeholders = true;
};

struct BlockRewritePatch {
    BlockId block_id;
    std::optional<std::string> description;
    std::optional<std::string> templ;
    std::optional<Params> defaults;
    std::optional<std::vector<std::string>> tags;
    std::string rationale;
};

struct CompositionBlockRewritePreview {
    CompositionId source_composition_id;
    Version source_version;
    std::vector<BlockRewritePatch> patches;
};

struct AppliedCompositionBlockRewriteResult {
    CompositionId composition_id;
    Version composition_version;
    std::vector<std::pair<BlockId, Version>> rewritten_blocks;
};

Класс Engine

Главный API-класс TextFoundry.

EngineConfig

struct EngineConfig {
    std::string ProjectKey = "default";
    bool strict_mode = false;
    std::string default_data_path = "memory:tf";
};

Конфигурация зависимостей

class Engine {
public:
    enum class VersionBump { Minor, Major };

    Engine();
    explicit Engine(EngineConfig config);

    void SetBlockRepository(std::shared_ptr<IBlockRepository> repo);
    void SetCompositionRepository(std::shared_ptr<ICompositionRepository> repo);
    void SetNormalizer(std::shared_ptr<INormalizer> normalizer);
    void SetBlockNormalizer(std::shared_ptr<IBlockNormalizer> normalizer);
    void SetBlockGenerator(std::shared_ptr<IBlockGenerator> generator);
    void SetCompositionBlockRewriter(std::shared_ptr<ICompositionBlockRewriter> rewriter);
};

Операции с Block

Result<Block> LoadBlock(
    const BlockId& id,
    std::optional<Version> version = std::nullopt
) const;

Error DeprecateBlock(const BlockId& id, Version version);
Error DeleteBlock(const BlockId& id);

Result<Version> GetLatestBlockVersion(const BlockId& id);
Result<std::vector<Version>> ListBlockVersions(const BlockId& id);
std::vector<BlockId> ListBlocks(
    std::optional<BlockType> typeFilter = std::nullopt
);

Result<PublishedBlock> PublishBlock(
    BlockDraft draft,
    VersionBump bump = VersionBump::Minor
);
Result<PublishedBlock> PublishBlock(BlockDraft draft, Version explicit_version);
Result<PublishedBlock> UpdateBlock(
    BlockDraft draft,
    VersionBump bump = VersionBump::Minor
);

Операции AI-authoring для Block

Result<GeneratedBlockData> GenerateBlockData(
    const BlockGenerationRequest& request
) const;

Result<GeneratedBlockBatch> GenerateBlockBatchData(
    const PromptSlicingRequest& request
) const;

Result<BlockDraft> GenerateBlockDraft(
    const BlockGenerationRequest& request
) const;

Result<std::vector<BlockDraft>> GenerateBlockDrafts(
    const PromptSlicingRequest& request
) const;

Операции с Composition

Result<PublishedComposition> PublishComposition(
    CompositionDraft draft,
    VersionBump bump = VersionBump::Minor
);
Result<PublishedComposition> PublishComposition(
    CompositionDraft draft,
    Version explicit_version
);
Result<PublishedComposition> UpdateComposition(
    CompositionDraft draft,
    VersionBump bump = VersionBump::Minor
);

Result<Version> GetLatestCompositionVersion(const CompositionId& id);
Result<std::vector<Version>> ListCompositionVersions(const CompositionId& id);

Result<Composition> LoadComposition(
    const CompositionId& id,
    std::optional<Version> version = std::nullopt
);

Error DeprecateComposition(const CompositionId& id, Version version);
Error DeleteComposition(const CompositionId& id);
std::vector<CompositionId> ListCompositions() const;

Рендеринг и validation

Result<RenderResult> Render(
    const CompositionId& compositionId,
    const RenderContext& context = RenderContext{}
);
Result<RenderResult> Render(
    const CompositionId& compositionId,
    Version version,
    const RenderContext& context = RenderContext{}
);

Result<std::string> RenderBlock(
    const BlockId& blockId,
    const RenderContext& context = RenderContext{}
);
Result<std::string> RenderBlock(
    const BlockId& blockId,
    Version version,
    const RenderContext& context = RenderContext{}
);

Error ValidateComposition(const CompositionId& id);
Error ValidateBlock(const BlockId& id);

Normalization и rewrite

Result<std::string> Normalize(
    const std::string& text,
    const SemanticStyle& style
) const;

Result<NormalizedCompositionResult> NormalizeComposition(
    const CompositionNormalizationRequest& request
);

Result<CompositionBlockRewritePreview> PreviewCompositionBlockRewrite(
    const CompositionBlockRewriteRequest& request
);

Result<AppliedCompositionBlockRewriteResult> ApplyCompositionBlockRewrite(
    const CompositionBlockRewritePreview& preview,
    VersionBump bump = VersionBump::Minor
);

bool HasNormalizer() const noexcept;
bool HasBlockNormalizer() const noexcept;
bool HasBlockGenerator() const noexcept;
bool HasCompositionBlockRewriter() const noexcept;

Инициализация

void FullInit();

Репозитории

class IBlockRepository {
public:
    virtual ~IBlockRepository() = default;
    virtual Error save(const Block& block) = 0;
    virtual Result<Block> load(const BlockId& id, Version version) = 0;
    virtual Result<Block> LoadLatest(const BlockId& id) = 0;
    virtual std::vector<BlockId> list(std::optional<BlockType> typeFilter = std::nullopt) = 0;
    virtual Result<Version> GetLatestVersion(const BlockId& id) = 0;
    virtual Result<std::vector<Version>> ListVersions(const BlockId& id) = 0;
    virtual Error deprecate(const BlockId& id, Version version) = 0;
    virtual Error remove(const BlockId& id) = 0;
};

class ICompositionRepository {
public:
    virtual ~ICompositionRepository() = default;
    virtual Error save(const Composition& composition) = 0;
    virtual Result<Composition> load(const CompositionId& id, Version version) = 0;
    virtual Result<Composition> LoadLatest(const CompositionId& id) = 0;
    virtual std::vector<CompositionId> list() = 0;
    virtual Result<Version> GetLatestVersion(const CompositionId& id) = 0;
    virtual Result<std::vector<Version>> ListVersions(const CompositionId& id) = 0;
    virtual Error deprecate(const CompositionId& id, Version version) = 0;
    virtual Error remove(const CompositionId& id) = 0;
};

Этот документ синхронизирован с текущими заголовками src/textfoundry_engine/tf и описывает фактический API codebase. Для продуктовых решений и planned архитектуры используйте doc/prd.adoc, а для текущего статуса реализации — doc/status.adoc.