tai42-storage-s3

An S3 Storage backend for the TAI ecosystem. It stores text, binary, and media content in an S3 bucket, implementing the full tai42_contract.storage.Storage surface — the five text methods (load / list / upload / delete / delete_dir) plus the binary/media methods (load_bytes / upload_bytes / stat). S3 stores bytes natively, so the binary methods are true reads/writes rather than the text bridge.

The TAI ecosystem

TAI is an open-source runtime for MCP tools, agents, and workflows. A Storage backend is "where content physically lives" — a pluggable provider the runtime's ResourceManager loads and renders content over. This package is one such provider (S3); siblings back the same contract with GitHub or the local filesystem. The ecosystem is open-ended: any package can back the same contract, so this repo is this provider's own full doc home, and the documentation site covers the platform-level story:

• Storage & resources concept: https://tai42.ai/concepts/storage-and-resources
• Build a storage provider (author guide): https://tai42.ai/guides/authors/storage-provider
• Ecosystem catalog: https://tai42.ai/reference/catalog

Its only tai-* dependencies are tai42-contract (the Storage ABC, ObjectStat, assert_not_root, and the tai42_app handle) and tai42-kit (PooledClient, TaiBaseSettings, and the settings cache). Beyond those it depends on its S3 driver (aioboto3, botocore) and pydantic / pydantic-settings.

Install

Requires Python 3.13+. Install from PyPI into the environment that runs the server:

uv add tai42-storage-s3

Or from source — clone this repo and add it as an editable dependency. Clone tai-contract and tai-kit beside this repo first — [tool.uv.sources] resolves them from sibling paths.

git clone https://github.com/tai42ai/tai-storage-s3   # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai-storage-s3

Discovery

The skeleton discovers this backend by importing its package — importing tai42_storage_s3 fires the @tai42_app.storage.register_storage decorator on S3Storage as a side-effect (there is no entry-point). Name the package in your manifest's storage_module field so the runtime imports it at startup:

storage_module: tai42_storage_s3

Configuration

Settings are read from the STORAGE_S3_ environment group (see S3Settings):

Content-type behavior

• upload (text) stores ContentType: application/jinja2 — a template reads back as its authoring format, not an inferred text/*.
• upload_bytes stores the parametrized content_type as the object's ContentType (omitted when None).
• stat returns the object's stored ContentType via head_object, mapping a missing object (404) to FileNotFoundError — no raw ClientError or metadata leaks. Because text uploads store application/jinja2, stat on a text template reports that type; it reads as non-media, which is the only thing the content-type gates.

Development

uv venv --python 3.13
uv pip install --no-sources --group dev --editable .
uv run --no-sync pytest --cov --cov-report=term-missing
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright

License

Apache-2.0. See LICENSE and NOTICE.