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` — the request-body checksum on `delete_objects` (which the S3 API requires one on) for a store that refuses the CRC32 default; uploads are optional and follow `STORAGE_S3_REQUEST_CHECKSUM_CALCULATION` (CRC32C/CRC64NVME need `botocore[crt]`)

Content-type behavior

upload (text) stores ContentType: text/plain; charset=utf-8.
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. stat on a text object reports text/plain; charset=utf-8.

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 2.0.2

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 2.0.2
File	Size	Uploaded
tai42_storage_s3-2.0.2.tar.gz	26.8 kB	Oct 14, 2026	Details

Built distribution (wheel)

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

Total release size: 43.0 kB

Release files / tai42_storage_s3-2.0.2.tar.gz

Download URL	tai42_storage_s3-2.0.2.tar.gz
Size	26.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`47bd164e74a56622af267e1c5c22c8e94430cd28fb3fbce538cf1875e1151bed`
BLAKE2b-256 checksum How to use checksums	`370eecfec2d7e9adfb586d2837b9caafd62e0560eb451f873188efa040cf45ef`
Upload date	Oct 14, 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-2.0.2-py3-none-any.whl

Download URL	tai42_storage_s3-2.0.2-py3-none-any.whl
Size	16.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6e80c1290261f164b27b5744008a5060d631514406ae793d24dc9e50b35e67a0`
BLAKE2b-256 checksum How to use checksums	`2a294b8f564a3665e1481338386ab0bf8091c017054ee282323ebff733b08567`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`