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; the tai42-* dependencies resolve in-tree from the workspace.

git clone https://github.com/tai42ai/tai42   # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai42/plugins/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):

Env var	Default	Purpose
`STORAGE_S3_BUCKET`	—	Target bucket (required)
`STORAGE_S3_ENDPOINT`	—	Custom endpoint (e.g. MinIO); scheme inferred from `SECURE` if omitted
`STORAGE_S3_ACCESS_KEY`	—	AWS access key id
`STORAGE_S3_SECRET_KEY`	—	AWS secret access key
`STORAGE_S3_SECURE`	`true`	Use HTTPS
`STORAGE_S3_REGION`	`us-east-1`	AWS region
`STORAGE_S3_VERIFY_SSL`	`true`	Verify TLS certificates
`STORAGE_S3_CONNECT_TIMEOUT`	`5`	Connect timeout (seconds)
`STORAGE_S3_READ_TIMEOUT`	`30`	Read timeout (seconds)
`STORAGE_S3_ADDRESSING_STYLE`	`auto`	`path` / `virtual` / `auto`
`STORAGE_S3_REQUEST_CHECKSUM_CALCULATION`	—	`when_supported` / `when_required`
`STORAGE_S3_CHECKSUM_ALGORITHM`	—	`CRC32` / `CRC32C` / `SHA1` / `SHA256` / `CRC64NVME` — request-body checksum for a store that refuses the CRC32 default (CRC32C/CRC64NVME need `botocore[crt]`)

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.

Development Status
- 4 - Beta
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3.13
Typing
- Typed

Metadata

Development Status
- 4 - Beta
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3.13
Typing
- Typed

Release files for tai42-storage-s3 1.2.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tai42-storage-s3 1.2.8
File	Size	Uploaded
tai42_storage_s3-1.2.8.tar.gz	24.4 kB	Oct 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tai42-storage-s3 1.2.8
File	Interpreter	ABI	Platform	Reset
tai42_storage_s3-1.2.8-py3-none-any.whl 15.7 kB Oct 4, 2026	Python 3	none	any	Details

Total release size: 40.0 kB

Release files / tai42_storage_s3-1.2.8.tar.gz

Download URL	tai42_storage_s3-1.2.8.tar.gz
Size	24.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`50ca64ec3f2ce635c642cd447a7dde19debcc094cb86f4ef642d958bf96f9eb9`
BLAKE2b-256 checksum How to use checksums	`59092b2372cc27a9a0344ce76d42804455cf24771492bfbea1fc1f0b64b39f54`
Upload date	Oct 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / tai42_storage_s3-1.2.8-py3-none-any.whl

Download URL	tai42_storage_s3-1.2.8-py3-none-any.whl
Size	15.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9bea15e94d21e50d56415d4db7b7d1a2c4206c49329e6fadf27d0b9f9a88132c`
BLAKE2b-256 checksum How to use checksums	`a2444d544edfa2c97ffb7d804804aaca1a2bbd2b9ba303f4fcd764a9d57d4412`
Upload date	Oct 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`