Skip to main content

tai42-storage-s3

License: Apache 2.0

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 metadata read stat, the bounded read load_range and the binary/media methods (load_bytes / upload_bytes / load_object). 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:

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 and its ContentLength (as size) 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.
  • load_object is one get_object: it answers the bytes with the object's stored ContentType, so a caller wanting both makes no head_object call.
  • list(directory) lists only the keys under <directory>/ (a Prefix on list_objects_v2); delete_dir and the upload path-conflict check list the same way.
  • load_range is one get_object with a Range: bytes=start-end header: it answers fewer bytes at the object's end and b"" at or past it (S3's InvalidRange), raises FileNotFoundError for a missing object, and sends no request for a zero length.

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.

Metadata

Release files for tai42-storage-s3 4.0.3

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 4.0.3
File Size Uploaded Provenance Actions
tai42_storage_s3-4.0.3.tar.gz 28.6 kB Without provenance Details for tai42_storage_s3-4.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tai42-storage-s3 4.0.3
File Interpreter ABI Platform Actions
tai42_storage_s3-4.0.3-py3-none-any.whl Python 3 none any Details for tai42_storage_s3-4.0.3-py3-none-any.whl

Total release size: 45.6 kB

Release files / tai42_storage_s3-4.0.3.tar.gz

Download URL tai42_storage_s3-4.0.3.tar.gz
Size 28.6 kB
Tags Source
SHA-256 checksum
How to use checksums
543c3ea9be6ef4d8aaf40cddc11d1b2b07424fee60cf9debb15d1f8b32dbaaf3
BLAKE2b-256 checksum
How to use checksums
3f79cb3867027f7003a9d15427b5ab0ca8e4fe8db3bb880b382efdc7039414f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

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

Download URL tai42_storage_s3-4.0.3-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e0d2dec4a7dd40c38e63c06026422353db31732c058e784eee0998eb1ab45b7b
BLAKE2b-256 checksum
How to use checksums
66d68b3b8a424bdcf670a5d738f734d285fb284e763dff6e0cb305db7b5ba9ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for tai42-storage-s3 4.0.3

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.

Release history Release notifications | RSS feed

This release

4.0.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page