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.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_github-1.2.3.tar.gz | 22.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_storage_github-1.2.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 38.6 kB
Release files / tai42_storage_github-1.2.3.tar.gz
| Download URL | tai42_storage_github-1.2.3.tar.gz |
|---|---|
| Size | 22.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31e9d583e43ba9cda47138915217dc0b6ff01aa5c70aeb587c8db06356377c21
|
|
BLAKE2b-256 checksum How to use checksums |
0715a95ad5b9aa12442e2ef7a64eae6808cd16d4e0910b4d2cef3ee74f8fb58d
|
| 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.2.3-py3-none-any.whl
| Download URL | tai42_storage_github-1.2.3-py3-none-any.whl |
|---|---|
| Size | 15.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c8d0f01aa01a4b6e0a3dbc15fa30b0bba5a92bbeb322d8589f062a6f3d126031
|
|
BLAKE2b-256 checksum How to use checksums |
6160290e627be0f00af86013dce00930820d4b6d34a8d5044564034289dc13d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
