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 4.0.1

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

Built distribution (wheel)

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

Total release size: 39.6 kB

Release files / tai42_storage_local-4.0.1.tar.gz

Download URL tai42_storage_local-4.0.1.tar.gz
Size 24.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f5dcb0abef3fdec4ed09c9a70ab9894c7b0df9bbfbdd4496ef0475c051c2545e
BLAKE2b-256 checksum
How to use checksums
19d4879a066b51bc6e5a384c0779ae491fb1813c9c5fff1464ba8c022b2dd922
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_local-4.0.1-py3-none-any.whl

Download URL tai42_storage_local-4.0.1-py3-none-any.whl
Size 15.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4a641aeaabc3f37c1bab41fd4a2930a6bf7ec97967df496de19c4a216494354f
BLAKE2b-256 checksum
How to use checksums
ad827b9cafc9f4651a7398798985add28943516de499e88263fa3a914bcab3c2
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-local 4.0.1

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.1 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