TAI42 — the OS for AI tools

Describe a plugin with tai-plugin.yml — the descriptor the marketplace indexes a plugin from. Every plugin ships a tai-plugin.yml at its repository root and inside its built wheel. It is the single source for what the plugin is (name, package, version, license, contract range) and what it provides (one entry per contained item). The registry validates a release’s artifact against it before publishing, and the installer patches the server manifest from its provides list. It is not the server manifest: tai-plugin.yml describes what a plugin offers; the server manifest declares what a server loads.

The fields

Field	Meaning
`spec_version`	The descriptor format version — currently `1`. An unknown version is rejected loudly.
`namespace` / `name`	The listing ref, `namespace/name` — lowercase slugs, unique per listing.
`display_name`	Optional human UI title; the listing falls back to a titleized `name` when omitted.
`package`	The normalized pip distribution name.
`version`	The release version (PEP 440); it must equal the built wheel’s version on ingest.
`description`	One line for the listing.
`icon`	Optional: a package-relative image path or an `https://` URL; a monogram is generated when omitted.
`license`	Required SPDX identifier.
`homepage` / `repository`	Optional links.
`contract`	The tai42-contract compatibility range (a PEP 440 specifier set).
`categories`	One to three lowercase category slugs.
`tags`	Free-form lowercase tags, at most ten.
`permissions`	Declared capabilities — `network`, `subprocess`, `filesystem`. Informational: surfaced in listings, not enforced by a sandbox.
`provides`	One entry per contained item: `kind`, `name`, `module`, `description`, `tags`. At least one.

Each provides entry’s module is the module whose import registers the item, and its kind maps onto the server-manifest field the installer patches — a tool lands under tools, an extension under extensions_modules, and so on.

Router and middleware kinds

A plugin can also provide an HTTP router or an ASGI middleware — the two provides kinds that map onto the manifest’s module lists:

`kind`	Manifest field	Module registration
`router`	`routers_modules`	`@tai42_app.http.custom_route`
`middleware`	`middlewares_modules`	`@tai42_app.http.middleware`

The module you name registers the route or middleware on import, exactly as an authored code plugin does — the descriptor just lets the marketplace install it and merge it into the server manifest for you.

An installed router or middleware activates on the next server restart, not instantly. Installing merges the module into the persisted manifest, but the served route table and the middleware stack are fixed when the server boots, so the new routes bind only the next time it starts. Tools and agents hot-activate on install; a router or middleware needs a restart.

For a router, the installer orders the router ahead of the Studio SPA catch-all, so its routes are not shadowed by the catch-all — an authored router never has to manage that ordering itself. A middleware is appended to the stack, where it wraps the built-in middleware and so runs outermost. If a plugin middleware needs a precise position relative to the others, that ordering is not configurable.

A real descriptor

The toolbox’s own descriptor, in full:

tai-plugin.yml

spec_version: 1
namespace: tai42
name: toolbox
package: tai42-toolbox
version: 0.1.0
description: "Reference contrib package for the TAI ecosystem: opt-in, manifest-loaded generic tools and tool extensions (a tool extension extends a single tool)."
license: Apache-2.0
homepage: https://tai42.ai
repository: https://github.com/tai42ai/tai-toolbox
contract: ">=0.1,<0.2"
categories: [utilities, productivity]
tags: [uuid, time, embeddings, http, cache, batch, chain]
permissions:
  network: true
  subprocess: false
  filesystem: false
provides:
  - kind: tool
    name: current_time_info
    module: tai42_toolbox.tools.current_time_info
    description: "Return the current time as a structured object."
    tags: [time]
  - kind: tool
    name: generate_embeddings
    module: tai42_toolbox.tools.generate_embeddings
    description: "Generate embeddings for a single string or a list of strings."
    tags: [embeddings]
  - kind: tool
    name: generate_uuid
    module: tai42_toolbox.tools.generate_uuid
    description: "Generate a random UUID (version 4)."
    tags: [uuid]
  - kind: tool
    name: pad_embeddings
    module: tai42_toolbox.tools.pad_embeddings
    description: "Pad each embedding vector with zeros up to a target dimension."
    tags: [embeddings]
  - kind: tool
    name: request
    module: tai42_toolbox.tools.request
    description: "Execute an HTTP request through a curl-backed session."
    tags: [http]
  - kind: extension
    name: batch
    module: tai42_toolbox.extensions.batch
    description: "Branch a tool into a variant that runs many instances at once."
    tags: [batch]
  - kind: extension
    name: cache
    module: tai42_toolbox.extensions.cache
    description: "Branch a tool into a variant that memoizes results by call arguments."
    tags: [cache]
  - kind: extension
    name: chain
    module: tai42_toolbox.extensions.chain
    description: "Branch a tool into a variant that transforms its output and calls a next tool."
    tags: [chain]
  - kind: extension
    name: output_schema
    module: tai42_toolbox.extensions.output_schema
    description: "Branch a tool into a variant that forces a configured JSON Schema as its output schema and validates every result against it."
    tags: [schema]
  - kind: extension
    name: prometheus_metrics
    module: tai42_toolbox.extensions.prometheus
    description: "Branch a tool into a variant that records a Prometheus call metric."
    tags: [metrics]
  - kind: extension
    name: proxy
    module: tai42_toolbox.extensions.proxy
    description: "Branch a tool into a variant that runs the wrapped tool through a proxy."
    tags: [proxy]

Package it

Ship the file twice: at the repository root (the registry reads it from the repo) and as package-data inside the wheel (the registry validates the built artifact against the listing). Keep the wheel copy under your package directory and name it in the package-data config so the build includes it:

pyproject.toml

[tool.setuptools.packages.find]
where = ["src"]
include = ["tai42_toolbox*"]

[tool.setuptools.package-data]
tai42_toolbox = ["py.typed", "tai-plugin.yml"]

Validate it

Load and validate a descriptor before you publish with load_plugin_spec, which parses the file and returns a validated PluginSpec — a schema violation raises rather than returning a partial spec:

from pathlib import Path

from tai42_kit.plugins import load_plugin_spec

spec = load_plugin_spec(Path("tai-plugin.yml"))
print(spec.ref, spec.version)

Get started

Concepts

Guides

Marketplace

Contributing

The plugin descriptor

The fields

Router and middleware kinds

A real descriptor

Package it

Validate it

See also

​The fields

​Router and middleware kinds

​A real descriptor

​Package it

​Validate it

​See also

The fields

Router and middleware kinds

A real descriptor

Package it

Validate it

See also