tai42-storage-local
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:
- 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
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 eight-method Storage contract:
- Text:
load(raisesFileNotFoundErrorwhen missing),list,upload,delete,delete_dir. - Binary/media:
load_bytes/upload_bytesread and write raw bytes directly (no encoding);statinherits the contract'smimetypes-based path inference, since the local filesystem stores no content-type metadata.
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.
1 maintainer
Metadata
1 maintainer
Release files for tai42-storage-local 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| tai42_storage_local-2.3.0.tar.gz | 21.9 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_storage_local-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 36.5 kB
Release files / tai42_storage_local-2.3.0.tar.gz
| Download URL | tai42_storage_local-2.3.0.tar.gz |
|---|---|
| Size | 21.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7707da4f7883acbb7cbc0cf327685cc64f9ff25b59313df6aa0a1c257f3e8e92
|
|
BLAKE2b-256 checksum How to use checksums |
6bf25152fa309085fbc48e916fd1b3809d9f6dbaed5f8c87868e4a348fc89fa4
|
| 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-2.3.0-py3-none-any.whl
| Download URL | tai42_storage_local-2.3.0-py3-none-any.whl |
|---|---|
| Size | 14.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7cde4c0b86653f6a20b632e4c95ec647383d49efffc1398c1e9ccef43cf6d7a8
|
|
BLAKE2b-256 checksum How to use checksums |
67957df9364b2b6f87afa08f9bb0f6c3302d5b861024154bfae355926bcea395
|
| 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 2.3.0
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.
