TAI42 — the OS for AI tools

Plugin manifest contract: the tai-plugin.yml schema (PluginSpec). Every installable TAI plugin ships a tai-plugin.yml — at its repo root and as package-data inside the built wheel. The file names the listing (namespace/name), the pip distribution that backs it, the tai42-contract compatibility range, declared capabilities, and the item-level provides index: one entry per tool/agent/extension/… the package registers, because items are what users search for while the plugin is what gets installed. The models here are the one schema shared by the marketplace registry’s validator, the skeleton’s installer, and each plugin repo’s own spec test. The YAML I/O helpers live above the contract (tai42_kit.plugins) — the contract itself has no YAML dependency. KIND_MANIFEST_BINDINGS is the single source for how each provided item kind wires into a Manifest: which manifest field an installer patches and with what shape (a config row, a module-list entry, a single-module slot, a package-name entry, or no manifest field at all for the env-selected config kind). Version strings are validated as PEP 440 (an anchored regex of the spec’s canonical pattern) and contract as a PEP 440 specifier set — shape-level parseability only; evaluating whether a version satisfies a range is the consumer’s concern. display_name and icon are the optional marketplace display metadata: a human UI title (the UI titleizes name when absent) and either a packaged image path relative to the package root or an https URL (the UI falls back to a generated monogram when absent).

KIND_MANIFEST_BINDINGS

tai42_contract.plugins.KIND_MANIFEST_BINDINGS

KIND_MANIFEST_BINDINGS: Mapping[PluginItemKind, ManifestBinding] = MappingProxyType({PluginItemKind.TOOL: ManifestBinding(field='tools', mode='config_row'), PluginItemKind.AGENT: ManifestBinding(field='agents', mode='config_row'), PluginItemKind.EXTENSION: ManifestBinding(field='extensions_modules', mode='module_list'), PluginItemKind.CONNECTOR: ManifestBinding(field='lifecycle_modules', mode='module_list'), PluginItemKind.CHANNEL: ManifestBinding(field='channel_modules', mode='module_list'), PluginItemKind.BACKEND: ManifestBinding(field='backend_module', mode='scalar_module'), PluginItemKind.STORAGE: ManifestBinding(field='storage_module', mode='scalar_module'), PluginItemKind.MONITORING: ManifestBinding(field='monitoring_module', mode='scalar_module'), PluginItemKind.WEBHOOK_VERIFIER: ManifestBinding(field='webhook_verifier_modules', mode='module_list'), PluginItemKind.CONFIG: ManifestBinding(field=None, mode='env_selected'), PluginItemKind.IDENTITY: ManifestBinding(field='lifecycle_modules', mode='module_list'), PluginItemKind.STUDIO_PLUGIN: ManifestBinding(field='studio_plugins', mode='package_list'), PluginItemKind.ROUTER: ManifestBinding(field='routers_modules', mode='module_list'), PluginItemKind.MIDDLEWARE: ManifestBinding(field='middlewares_modules', mode='module_list')})

ManifestBinding

tai42_contract.plugins.ManifestBinding

class ManifestBinding(BaseModel)

How one provided item kind wires into a Manifest. field names the manifest field an installer patches for an item of this kind; mode is the patch shape:

config_row — append a config row (tools/agents) whose module is the item’s module.
module_list — append the item’s module to a plain module list.
scalar_module — set a single-module slot; the slot holds ONE module, so a second plugin claiming an occupied slot is a conflict the caller must reject loudly.
package_list — append the plugin’s DISTRIBUTION name (not the item’s module) to a package list (studio_plugins).
env_selected — no manifest field: the kind is selected through the environment (a config provider is named by TAI_CONFIG_MODE and imported by the config seam), so field is None.

Attributes

Attribute	Type
`model_config`	—
`field`	`str \| None`
`mode`	`Literal['config_row', 'module_list', 'scalar_module', 'package_list', 'env_selected']`

PluginItem

tai42_contract.plugins.PluginItem

class PluginItem(BaseModel)

One installable item in a plugin’s provides index. module is the import path whose import side-effect registers the item (or, for env-selected kinds, the module the selecting seam imports); the installer patches it into the manifest per KIND_MANIFEST_BINDINGS. Attributes

Attribute	Type
`model_config`	—
`kind`	`PluginItemKind`
`name`	`str`
`module`	`str`
`description`	`str`
`tags`	`list[str]`

PluginItemKind

tai42_contract.plugins.PluginItemKind

class PluginItemKind(StrEnum)

Kind of one installable item a plugin provides. The values are the ecosystem’s item-kind vocabulary (the same words the catalog and the marketplace facets use). KIND_MANIFEST_BINDINGS maps every member onto its manifest wiring; an unknown kind in a spec is a loud validation reject, never a skipped row. Attributes

Attribute	Type
`TOOL`	—
`AGENT`	—
`EXTENSION`	—
`CONNECTOR`	—
`CHANNEL`	—
`BACKEND`	—
`STORAGE`	—
`MONITORING`	—
`WEBHOOK_VERIFIER`	—
`CONFIG`	—
`IDENTITY`	—
`STUDIO_PLUGIN`	—
`ROUTER`	—
`MIDDLEWARE`	—

PluginPermissions

tai42_contract.plugins.PluginPermissions

class PluginPermissions(BaseModel)

Capabilities a plugin declares — informational: surfaced in listings, not enforced by a sandbox. Omitting the block declares none (every flag defaults to False); an unknown key is rejected loudly rather than silently ignored. Attributes

Attribute	Type
`model_config`	—
`network`	`bool`
`subprocess`	`bool`
`filesystem`	`bool`

PluginSpec

tai42_contract.plugins.PluginSpec

class PluginSpec(BaseModel)

The complete, validated content of one tai-plugin.yml. Frozen and extra="forbid": a typo’d key fails validation loudly. The listing reference is namespace/name (ref); package is the normalized pip distribution the listing points at; version must equal the built wheel’s version (each plugin repo’s spec test and the registry’s ingest validation both pin that); contract is the tai42-contract compatibility range as a PEP 440 specifier set. display_name and icon are optional marketplace display metadata. Attributes

Attribute	Type
`model_config`	—
`spec_version`	`Literal[1]`
`namespace`	`str`
`name`	`str`
`display_name`	`str \| None`
`package`	`str`
`version`	`str`
`description`	`str`
`icon`	`str \| None`
`license`	`str`
`homepage`	`str \| None`
`repository`	`str \| None`
`contract`	`str`
`categories`	`list[str]`
`tags`	`list[str]`
`permissions`	`PluginPermissions`
`provides`	`list[PluginItem]`

Members

ref

tai42_contract.plugins.PluginSpec.ref

ref: str

The full listing reference, namespace/name.

HTTP API

CLI

Settings

Python SDK

Catalog

Studio SDK

Plugins (tai42_contract.plugins)

KIND_MANIFEST_BINDINGS

ManifestBinding

PluginItem

PluginItemKind

PluginPermissions

PluginSpec

Members

ref

​KIND_MANIFEST_BINDINGS

​ManifestBinding

​PluginItem

​PluginItemKind

​PluginPermissions

​PluginSpec

​Members

​ref

KIND_MANIFEST_BINDINGS

ManifestBinding

PluginItem

PluginItemKind

PluginPermissions

PluginSpec

Members

ref