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 |
./templates |
The base directory every stored path is resolved under. |
STORAGE_LOCAL_CREATE_DIRS |
true |
Create missing parent directories on write. |
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 1.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tai42_storage_local-1.2.3.tar.gz | 20.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_storage_local-1.2.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 34.9 kB
Release files / tai42_storage_local-1.2.3.tar.gz
| Download URL | tai42_storage_local-1.2.3.tar.gz |
|---|---|
| Size | 20.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96dd141328b07fb3301a23c9a6882c3d13a98cf8516c7c09ce19f32998dbc34f
|
|
BLAKE2b-256 checksum How to use checksums |
0dfb849d09e261543836aa669ba196ba0622e056ba04b9399c72daf054e40741
|
| 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-1.2.3-py3-none-any.whl
| Download URL | tai42_storage_local-1.2.3-py3-none-any.whl |
|---|---|
| Size | 14.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9650ec616d27be5a5665c55df60df748c9f76592bb55d33b7e238f5f416f0ec
|
|
BLAKE2b-256 checksum How to use checksums |
d3b770b73194c3bb2ef0b8c47f57f68882127893c1ff7aa7b036179163d10404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
