gfa-sdk — Python SDK for gfa (Git for Agents)

Opinionated Python client for gfa. Picks the right endpoint for the access pattern, caches what is safe to cache, and emits hints when a strategy change would help. Designed for AI agents reading, mutating, and forking gfa-hosted repos.

Install

pip install gfa-sdk

Python >= 3.10 required.

Quickstart

import os
import gfa

client = gfa.Client(
    endpoint=os.environ["GFA_ENDPOINT"],
    token=os.environ["GFA_JWT"],
)

# Profile a repo (cheap, cached for the session)
profile = client.profile_repo("myrepo")
print(f"{profile.file_count_at_head} files, {profile.storage_bytes} bytes")

# Read one file
src = client.read_file("myrepo", "src/main.go")

# Read many files — SDK picks /file vs /files/batch vs partial-clone
files = client.read_files("myrepo", ["a.go", "b.go", "c.go"])

# Create a commit
sha = client.create_commit(
    "myrepo",
    branch="main",
    message="agent: refactor",
    files=[gfa.FileChange(path="a.go", content=b"// rewritten\n")],
)

# Workspace for isolated changes
with client.create_workspace("myrepo", base_ref="main", ttl_hours=2) as ws:
    ws.create_commit(branch="main", message="WIP", files=[...])
    ws.merge()

Smart routing

client.read_files(repo, paths) auto-routes by len(paths):

Threshold tuning:

from gfa import Client, ClientConfig
client = Client(
    endpoint,
    token,
    config=ClientConfig(batch_read_threshold=500),
)

Hints

The SDK emits structured hints when access patterns suggest a strategy change. The default handler writes to stderr; override with a logging hook:

def my_handler(hint):
    logger.info("gfa hint", extra={"code": hint.code, "repo": hint.repo})

client = gfa.Client(endpoint, token, hint_handler=my_handler)

Silence entirely:

client = gfa.Client(endpoint, token, hint_handler=lambda _: None)

Auth

Either a pre-minted JWT string, or a TokenProvider that mints per-call:

provider = gfa.FileKeyTokenProvider("/path/to/preview-jwt-priv.pem", ttl_hours=1)
client = gfa.Client(endpoint, provider)

FileKeyTokenProvider mints ES256 JWTs with sub=<repo>, iat=now, exp=now + ttl_hours. Mirrors the Go tools/mint-token binary.

Diagnostics

client.read_file("myrepo", "x.go")
client.read_files("myrepo", ["a.go", "b.go"])
print(client.stats)
# ClientStats(request_count=2, cache_hit_rate=0.0, ...)

Partial clone

with client.partial_clone("myrepo", filter="blob:none", depth=1) as repo:
    content = repo.read("src/foo.go")

Requires git binary on PATH.

Troubleshooting

License

MIT.