tai42-storage-github
A GitHub-backed Storage provider for the TAI ecosystem. It stores content as
files in a GitHub repository and serves the full tai42_contract.storage.Storage
surface — the text methods (load / list / upload / delete / delete_dir)
plus the binary/media methods (load_bytes / upload_bytes / stat).
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 (GitHub); siblings back the same contract with S3 (tai42-storage-s3) and
the local filesystem (tai42-storage-local). 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-github
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-github
Use
The backend is loaded by import side-effect: importing the tai42_storage_github
package runs its @tai42_app.storage.register_storage decorator, making
GithubStorage the active storage provider. Point a manifest's storage_module
at the package:
# manifest.yml
storage_module: tai42_storage_github
Configuration
Configure through STORAGE_GITHUB_-prefixed environment variables:
| Variable | Default | Description |
|---|---|---|
STORAGE_GITHUB_USERNAME |
— | Repository owner (user or org). |
STORAGE_GITHUB_REPO |
— | Repository name. |
STORAGE_GITHUB_BRANCH |
main |
Branch to read/write. |
STORAGE_GITHUB_TOKEN |
— | Access token; omit for a public repository. |
STORAGE_GITHUB_TIMEOUT_TOTAL |
15.0 |
HTTP timeout (seconds). |
STORAGE_GITHUB_MAX_CONNECTIONS |
200 |
Connection-pool ceiling. |
STORAGE_GITHUB_MAX_KEEPALIVE_CONNECTIONS |
50 |
Keep-alive pool size. |
STORAGE_GITHUB_KEEPALIVE_EXPIRY |
300.0 |
Keep-alive expiry (seconds). |
The token is held as a SecretStr; it authenticates requests but never appears in
a log line, repr, or error message.
Reads and writes
- Reads (
load,load_bytes) go through the raw endpoint (raw.githubusercontent.com), which serves files of any size. The Contents API is deliberately not used for reads: it silently returns an empty body for a file over 1 MiB, so a large object would read as empty bytes. The raw endpoint is CDN-cached, so a read shortly after a write may return the previous content for up to ~5 minutes. - Writes (
upload,upload_bytes) go through the Contents API (base64) and are capped conservatively at 1 MiB. A larger payload raisesValueErrorbefore the request rather than truncating; the API's own422is the backstop. - Listing uses the recursive Git Trees API (one request) and raises loudly on
a
truncatedresponse rather than acting on a partial listing. statinferscontent_typefrom the path suffix — GitHub stores no per-object content-type.
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-github 1.4.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_github-1.4.0.tar.gz | 23.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_storage_github-1.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 38.7 kB
Release files / tai42_storage_github-1.4.0.tar.gz
| Download URL | tai42_storage_github-1.4.0.tar.gz |
|---|---|
| Size | 23.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b929ef181748d89ca4632279b2b40137579ffdaf2e709eb00b9222d1636e3fb8
|
|
BLAKE2b-256 checksum How to use checksums |
2b064d03a9350ff4f215ae05e9fdab274660b57ff2f2fe468ad96528753a8294
|
| 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_github-1.4.0-py3-none-any.whl
| Download URL | tai42_storage_github-1.4.0-py3-none-any.whl |
|---|---|
| Size | 15.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
06b7827bb5f0aca2fa7d4babaf8186f2abc4af0c9a0bd8509eacd1411aee1bd7
|
|
BLAKE2b-256 checksum How to use checksums |
49d7283903f2de0daa9e81d10f845fbbe9789c74422b434ea488cddef6630125
|
| 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-github 1.4.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.
