TAI42 — the OS for AI tools

The presets contract: the PresetSpec model, PresetBody shape, errors, and store. Covers the PresetSpec data model, the PresetBody persisted shape, the preset-specific errors, and the PresetStore Protocol. A preset is a base tool with a partial set of keyword arguments baked in, exposed as a new named, versioned tool. It is the FIRST typed VIEW over the generic versioned-document store (kind="preset"): the store holds the opaque body, this Protocol is the typed interface over it. tai42-contract owns only the Protocol + models + errors; the concrete view that delegates to the store, validates/reshapes the body, and maps the generic errors to these preset errors lives in the skeleton (no versioning code in the view).

CARRY_FORWARD

tai42_contract.presets.models.CARRY_FORWARD

CARRY_FORWARD = CarryForward()

CarryForward

tai42_contract.presets.models.CarryForward

class CarryForward

Sentinel for a save_version field the caller did not provide. Carry the ACTIVE value forward. fixed_kwargs / extensions clear with an empty container, so None is their carry-forward sentinel; output_schema / input_schema have no empty container (their cleared state IS None), so each needs a distinct sentinel to tell “not provided” (carry forward) apart from an explicit None (clear).

PresetBody

tai42_contract.presets.models.PresetBody

class PresetBody(BaseModel)

The persisted body of a versioned preset. base_tool is the tool the preset binds; description is the preset’s human description; fixed_kwargs are the baked kwargs (each becomes a hidden, fixed constant on the bound tool). extensions is a list of extension COMBOS — the SAME shape as a manifest extensions map value, each combo element an extension name or a {"name", "config"} mapping binding author config (e.g. an ask_external verifier) — fed unconverted to the structured runtime-attach API at register (an empty outer list means no extensions; an empty INNER combo is rejected by the validating view). output_schema is an optional author-set OUTPUT JSON Schema (an object schema): on an AGENT base it is baked into the run tool’s response_format so the agent FORCES a structured output matching it; on a plain tool it is advertised as the bound tool’s output schema and every result is validated against it at run time. input_schema is an optional author-set INPUT JSON Schema: it becomes the exposed named tool’s input contract, and the caller’s validated object is routed into the base tool’s declared payload argument (see PresetInputSchemaSupport). Only a base tool that DECLARES input-schema support accepts one; otherwise a set input_schema is a loud authoring error. Each schema is the TemplatedText | dict union: an inline dict is the JSON Schema document itself; a TemplatedText names a stored schema by id (or carries it inline as content), rendered and parsed as JSON to the same schema at the point of use and save. Every field must survive carry-forward on a version save: dropping extensions would make the branch tools vanish on reload, dropping base_tool would break the bind, dropping description would strip the tool’s description, dropping output_schema would silently un-enforce the structured output, and dropping input_schema would silently un-enforce the structured input. Attributes

Attribute	Type
`base_tool`	`str`
`description`	`str`
`fixed_kwargs`	`dict[str, Any]`
`extensions`	`list[list[ExtensionElement]]`
`output_schema`	`TemplatedText \| dict[str, Any] \| None`
`input_schema`	`TemplatedText \| dict[str, Any] \| None`
`state_binding`	`StateBinding \| None`

PresetError

tai42_contract.presets.errors.PresetError

class PresetError(Exception)

Base for preset view failures, carrying the preset name. Attributes

Attribute	Type
`name`	—

PresetExistsError

tai42_contract.presets.errors.PresetExistsError

class PresetExistsError(PresetError)

A preset named name already exists.

PresetInputSchemaSupport

tai42_contract.presets.models.PresetInputSchemaSupport

class PresetInputSchemaSupport(BaseModel)

A base tool’s declaration that it ACCEPTS a per-preset input schema. Most base tools declare none — their typed schema is fixed. A base tool that declares support names, via payload_arg, the base tool’s OWN argument the validated structured input is delivered under: a preset’s input_schema becomes the exposed named tool’s input contract and the caller’s validated object is routed into payload_arg on the base call. Attributes

Attribute	Type
`payload_arg`	`str`

PresetNameConflictError

tai42_contract.presets.errors.PresetNameConflictError

class PresetNameConflictError(PresetError)

The preset name collides with an existing base tool. A preset must never silently shadow a real tool, so the register/create path raises this loudly rather than overwriting the tool.

PresetNotFoundError

tai42_contract.presets.errors.PresetNotFoundError

class PresetNotFoundError(PresetError)

No preset (or no active preset) named name.

PresetSeed

tai42_contract.presets.models.PresetSeed

class PresetSeed(BaseModel)

A declared default preset a plugin ships for import-time seeding. A seed names the preset (name), its human description, the base_tool it binds, and the fixed_kwargs baked in — the same body a PresetBody carries — plus the optional author input_schema / output_schema and optional tool_meta display seed. The applier creates or upgrades the preset from this shape; the contract holds only the SHAPE, never the applier logic. Attributes

Attribute	Type
`name`	`str`
`description`	`str`
`base_tool`	`str`
`fixed_kwargs`	`dict[str, Any]`
`input_schema`	`TemplatedText \| dict[str, Any] \| None`
`output_schema`	`TemplatedText \| dict[str, Any] \| None`
`tool_meta`	`PresetSeedToolMeta \| None`
`state_binding`	`StateBinding \| None`

PresetSeedToolMeta

tai42_contract.presets.models.PresetSeedToolMeta

class PresetSeedToolMeta(BaseModel)

The optional display metadata a PresetSeed seeds onto its preset’s tool_meta. Each field is applied only where the preset’s tool_meta leaves it absent — a seed never overwrites an operator-set display value. display_name is the human tool title; tags label it in listings; folder_path is a /-style path the applier resolves into the tool_meta folder tree (creating missing segments), never a raw stored string. Attributes

Attribute	Type
`display_name`	`str \| None`
`tags`	`list[str] \| None`
`folder_path`	`str \| None`

PresetSpec

tai42_contract.agent.base.PresetSpec

class PresetSpec(BaseModel)

A base tool bound to fixed kwargs, resolved into a StructuredTool at run time. See resolve_tools. A base tool that interprets its fixed kwargs as a nested document carries that document opaquely here. Attributes

Attribute	Type
`name`	`str`
`description`	`str`
`base_tool`	`str`
`fixed_kwargs`	`dict[str, Any]`

PresetStore

tai42_contract.presets.PresetStore

class PresetStore(Protocol)

The typed interface over the versioned-document store with kind="preset". Delegation, body validation/reshaping, and error mapping are the concrete (skeleton) view’s job — this Protocol pins only the surface. A preset body is always the full PresetBody ({base_tool, description, fixed_kwargs, extensions}); the editable-field methods reconstruct it under the carry-forward rules documented on save_version.

Members

create_preset

tai42_contract.presets.PresetStore.create_preset

async create_preset(
    self,
    spec: PresetSpec,
    extensions: Sequence[Sequence[ExtensionElement]],
    output_schema: TemplatedText | dict[str, Any] | None = None,
    input_schema: TemplatedText | dict[str, Any] | None = None,
    *,
    state_binding: StateBinding | None = None,
    tags: list[str] | None = None,
) -> DocumentRecord

Create a versioned preset. spec carries name/description/ base_tool/fixed_kwargs; extensions (the combos list) and the optional output_schema / input_schema ride alongside — all of them land in the persisted PresetBody. tags labels version 1 in the SAME create commit (None leaves it untagged); a caller that must tag the first version does so atomically, never through a separate follow-up write. Raise PresetExistsError on a duplicate name, PresetNameConflictError if the name collides with a base tool. Parameters

Parameter	Type	Default	Description
`spec`	`PresetSpec`	—	—
`extensions`	`Sequence[Sequence[ExtensionElement]]`	—	—
`output_schema`	`TemplatedText \| dict[str, Any] \| None`	`None`	—
`input_schema`	`TemplatedText \| dict[str, Any] \| None`	`None`	—
`state_binding`	`StateBinding \| None`	`None`	—
`tags`	`list[str] \| None`	`None`	—

save_version

tai42_contract.presets.PresetStore.save_version

async save_version(
    self,
    name: str,
    fixed_kwargs: dict[str, Any] | None = None,
    extensions: Sequence[Sequence[ExtensionElement]] | None = None,
    output_schema: TemplatedText | dict[str, Any] | CarryForward | None = CARRY_FORWARD,
    description: str | None = None,
    *,
    input_schema: TemplatedText | dict[str, Any] | CarryForward | None = CARRY_FORWARD,
    state_binding: StateBinding | CarryForward | None = CARRY_FORWARD,
    tags: list[str] | None = None,
) -> DocumentVersion

Append a new version from the editable body fields. tags labels the new version in the SAME save commit (None leaves it untagged, the door’s default); a caller that must tag the version does so atomically, never through a separate follow-up write. A version body is the FULL PresetBody, so the view reconstructs the new body by ALWAYS carrying base_tool forward from the ACTIVE version body, then applying each of fixed_kwargs, extensions under one UNIFORM sentinel: omitted/None = carry the active value forward unchanged; an explicit empty list (extensions=[]) = deliberately CLEAR that field. An explicitly provided empty list is a value, never “not provided”. output_schema and input_schema each follow the SAME rule but with a distinct CARRY_FORWARD sentinel (their cleared state is None, so None cannot double as “not provided”): omitted = carry forward, an explicit None = clear, an explicit dict = wins. description is editable per version: None = carry the active description forward, an explicit non-empty string = set it. The RESULTING description — explicit or carried — is validated non-empty (raising ValueError, surfaced as a 400), so an explicit "" is rejected and a carry-forward from a legacy body with an empty description raises rather than persisting an empty tool docstring. An empty INNER combo ([[]] or any [] member of extensions) is REJECTED. The new body never DROPS a field. Raise PresetNotFoundError if the preset is absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`fixed_kwargs`	`dict[str, Any] \| None`	`None`	—
`extensions`	`Sequence[Sequence[ExtensionElement]] \| None`	`None`	—
`output_schema`	`TemplatedText \| dict[str, Any] \| CarryForward \| None`	`CARRY_FORWARD`	—
`description`	`str \| None`	`None`	—
`input_schema`	`TemplatedText \| dict[str, Any] \| CarryForward \| None`	`CARRY_FORWARD`	—
`state_binding`	`StateBinding \| CarryForward \| None`	`CARRY_FORWARD`	—
`tags`	`list[str] \| None`	`None`	—

list_presets

tai42_contract.presets.PresetStore.list_presets

async list_presets(self) -> list[DocumentRecord]

List the active versioned presets.

get_preset

tai42_contract.presets.PresetStore.get_preset

async get_preset(self, name: str) -> DocumentRecord

Fetch a preset’s active record. Raise PresetNotFoundError if absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

get_active_kwargs

tai42_contract.presets.PresetStore.get_active_kwargs

async get_active_kwargs(self, name: str) -> dict[str, Any]

Return the active version’s baked fixed_kwargs. Raise PresetNotFoundError if absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

list_versions

tai42_contract.presets.PresetStore.list_versions

async list_versions(self, name: str) -> list[DocumentVersion]

List every version of the preset, each carrying its is_current signal. Raise PresetNotFoundError if the preset is absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

get_version

tai42_contract.presets.PresetStore.get_version

async get_version(self, name: str, version: int) -> DocumentVersion

Fetch one version. Raise PresetVersionNotFoundError if that version does not exist. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`version`	`int`	—	—

get_active_body

tai42_contract.presets.PresetStore.get_active_body

async get_active_body(self, name: str) -> PresetBody

Return the FULL active-version body ({base_tool, description, fixed_kwargs, extensions}). So reload/startup can re-register from the whole body, not just fixed_kwargs. Raise PresetNotFoundError if absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

rollback

tai42_contract.presets.PresetStore.rollback

async rollback(self, name: str, version: int) -> DocumentRecord

Re-point the active version to version (no data copy). Raise PresetVersionNotFoundError if that version does not exist. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`version`	`int`	—	—

soft_delete

tai42_contract.presets.PresetStore.soft_delete

async soft_delete(self, name: str) -> None

Soft-delete the preset, keeping its version history (audit). Raise PresetNotFoundError if absent. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

rename_preset

tai42_contract.presets.PresetStore.rename_preset

async rename_preset(self, name: str, new_name: str) -> DocumentRecord

Re-key a preset from name to new_name. Delegates to the generic store’s rename under kind="preset". The version history, every per-version tags label, and the active_version pointer are preserved by the store contract — a rename moves a key, it never rewrites the body. Raise PresetNotFoundError for an absent name, PresetExistsError when new_name is already a live preset, and PresetNameConflictError when the injected collision predicate says new_name is held by a live non-preset tool (the same predicate create_preset consults). Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`new_name`	`str`	—	—

PresetVersionNotFoundError

tai42_contract.presets.errors.PresetVersionNotFoundError

class PresetVersionNotFoundError(PresetError)

No version version exists for preset name. Attributes

Attribute	Type
`version`	—

PresetWriteValidator

tai42_contract.presets.PresetWriteValidator

PresetWriteValidator = Callable[[PresetBody], Awaitable[Sequence[str]]]

HTTP API

CLI

Settings

Capability map

Conversation bridge

Python SDK

Studio SDK

Presets (tai42_contract.presets)

CARRY_FORWARD

CarryForward

PresetBody

PresetError

PresetExistsError

PresetInputSchemaSupport

PresetNameConflictError

PresetNotFoundError

PresetSeed

PresetSeedToolMeta

PresetSpec

PresetStore

Members

create_preset

save_version

list_presets

get_preset

get_active_kwargs

list_versions

get_version

get_active_body

rollback

soft_delete

rename_preset

PresetVersionNotFoundError

PresetWriteValidator

​CARRY_FORWARD

​CarryForward

​PresetBody

​PresetError

​PresetExistsError

​PresetInputSchemaSupport

​PresetNameConflictError

​PresetNotFoundError

​PresetSeed

​PresetSeedToolMeta

​PresetSpec

​PresetStore

​Members

​create_preset

​save_version

​list_presets

​get_preset

​get_active_kwargs

​list_versions

​get_version

​get_active_body

​rollback

​soft_delete

​rename_preset

​PresetVersionNotFoundError

​PresetWriteValidator

CARRY_FORWARD

CarryForward

PresetBody

PresetError

PresetExistsError

PresetInputSchemaSupport

PresetNameConflictError

PresetNotFoundError

PresetSeed

PresetSeedToolMeta

PresetSpec

PresetStore

Members

create_preset

save_version

list_presets

get_preset

get_active_kwargs

list_versions

get_version

get_active_body

rollback

soft_delete

rename_preset

PresetVersionNotFoundError

PresetWriteValidator