Skip to main content

tai42-storage-local

License: Apache 2.0

Local-filesystem storage backend for the TAI ecosystem. It implements the tai42_contract.storage.Storage contract over a directory tree on the local disk, serving both text and binary content, and registers itself as the active storage provider when its package is imported.

The TAI ecosystem

TAI is an open-source runtime for MCP tools, agents, and workflows. A Storage backend answers the question of where content physically lives — a template, a document, or a media file loaded by id. This package is the local-filesystem implementation; siblings back the same contract with S3 (tai42-storage-s3) and GitHub (tai42-storage-github). 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:

Install

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

uv add tai42-storage-local

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-local

Discovery

A backend is activated by a manifest, not an entry point. Name this package in the manifest's storage_module field; the runtime imports it, and the @tai42_app.storage.register_storage decorator fires as an import side-effect to register LocalStorage as the active provider:

storage_module: tai42_storage_local

There is no auto-discovery — importing the package is the registration.

Configuration

Settings are read from the environment (or a .env file) with the STORAGE_LOCAL_ prefix:

Variable Default Description
STORAGE_LOCAL_ROOT_PATH required The base directory every stored path resolves under; every call refuses until it is set.
STORAGE_LOCAL_CREATE_DIRS true Create missing parent directories on write.

The root has no default: until STORAGE_LOCAL_ROOT_PATH is set, every storage call (list included) raises RuntimeError, so an unmounted or mistyped location never reads as an empty store. A relative root resolves against the process working directory (STORAGE_LOCAL_ROOT_PATH=./templates); a container sets the absolute path it mounts.

Contract surface

LocalStorage implements the full ten-method Storage contract:

  • Text: load (raises FileNotFoundError when missing), list, upload, delete, delete_dir. list(directory) walks only that directory's subtree; a directory that does not exist answers [].
  • Binary/media: load_bytes / upload_bytes read and write raw bytes directly (no encoding); load_object answers the bytes with the content type inferred from the path suffix, in one file read.
  • Metadata and bounded reads: stat answers the file's size from os.stat and infers the content type from the path suffix, since the local filesystem stores no content-type metadata; load_range seeks to start and reads at most length bytes. Both raise FileNotFoundError for a missing path or a directory.

Every path is resolved under the configured root and rejected if it escapes it (a path-boundary check, not a string prefix), and delete_dir refuses the storage root via the shared assert_not_root guard.

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-local 5.0.4

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-local 5.0.4
File Size Uploaded Provenance Actions
tai42_storage_local-5.0.4.tar.gz 24.0 kB Without provenance Details for tai42_storage_local-5.0.4.tar.gz

Built distribution (wheel)

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

Total release size: 39.6 kB

Release files / tai42_storage_local-5.0.4.tar.gz

Download URL tai42_storage_local-5.0.4.tar.gz
Size 24.0 kB
Tags Source
SHA-256 checksum
How to use checksums
8cd9d8df8696bb6871b2b6b57888b00d993f7fee36ee68965dc022a63a9978bb
BLAKE2b-256 checksum
How to use checksums
5d49a69d9a091e4d55256522682c04d07d12cdfadd8df9075e7b9d03285291b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / tai42_storage_local-5.0.4-py3-none-any.whl

Download URL tai42_storage_local-5.0.4-py3-none-any.whl
Size 15.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
05234ded44d9331c5a6fb4dc4ca785dc73d2831ca8d9ec329d2b29b724d21473
BLAKE2b-256 checksum
How to use checksums
97a0afae6a9890f4dc737bc379f8f17057c91c67325346827835d466192dec9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for tai42-storage-local 5.0.4

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

5.0.4 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