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.2.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.2.2
File	Size	Uploaded	Provenance
tai42_storage_s3-2.2.2.tar.gz	26.9 kB	Oct 21, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for tai42-storage-s3 2.2.2
File	Interpreter	ABI	Platform	Reset
tai42_storage_s3-2.2.2-py3-none-any.whl 16.3 kB Oct 21, 2026 Without provenance	Python 3	none	any	Details

Total release size: 43.2 kB

Release files / tai42_storage_s3-2.2.2.tar.gz

Download URL	tai42_storage_s3-2.2.2.tar.gz
Size	26.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`aae069552731d0265f70540da1c26bea64d4ecc039f10433f1ddb9f039c8017a`
BLAKE2b-256 checksum How to use checksums	`857f24981e8b9c43f22fdf909ff9c8f32f9bd5e0580987cc9362d37f045e755f`
Upload date	Oct 21, 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.2.2-py3-none-any.whl

Download URL	tai42_storage_s3-2.2.2-py3-none-any.whl
Size	16.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`717036b33694ae0a9558b59a5836410179f81da3a76d8453c2deff9c59e7187b`
BLAKE2b-256 checksum How to use checksums	`d9fe042c1060443207477b99b2f19c51405cb739ebb6210a97e2121c967df065`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Security for tai42-storage-s3 2.2.2

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.