lakeFS

Track exactly which version of a policy document, taxonomy, or reference file an agent read, by capturing the lakeFS commit SHA on every object access.

lakeFS is one bundled versioned-data source — if your data lives elsewhere, implement the same capture against any version-controlled store through the generic vcs protocol (pip install briefcase-ai[vcs]).

pip install briefcase-ai[lakefs] For: reproducible RAG & data lineage

pip install briefcase-ai[lakefs]

The [lakefs] extra installs the lakefs package. Import from briefcase.integrations.lakefs.

npm install @briefcase-ai/runtime@4.4.0

Import from @briefcase-ai/runtime/lakefs. The client is a typed wrapper over the lakeFS HTTP API with no lakeFS SDK dependency.

VersionedClient no longer falls back to a mock when the endpoint or credentials are missing — it raises, and a live operation that fails raises rather than returning fabricated data. A commit SHA you can’t trust is worse than no SHA at all.

Pass mock=True to opt into the offline stub; its metadata carries "mock": True so it can never be mistaken for real provenance. versioned_context and @versioned both forward the flag, and require_live=True rejects mock=True outright for production paths.

VersionedClient(repository="kb", branch="main", mock=True)          # offline
VersionedClient(                                                   # live
    repository="kb",
    branch="main",
    lakefs_endpoint="https://example.lakefscloud.io/api/v1",
    lakefs_access_key="...",
    lakefs_secret_key="...",
)

Credentials also resolve from LAKEFS_ENDPOINT, LAKEFS_ACCESS_KEY, and LAKEFS_PRIVATE_KEY.

Track Reads with a Context Manager

Open a versioned_context and every read inside it is tagged with the resolved commit SHA.

from briefcase.integrations.lakefs import versioned_context
from unittest.mock import Mock


class MockBriefcaseClient:
    def __init__(self):
        self.config = {
            "lakefs_endpoint": "https://example.lakefscloud.io/api/v1",
            "lakefs_access_key": "your_access_key",
            "lakefs_secret_key": "your_secret_key",
        }


client = MockBriefcaseClient()

with versioned_context(client, "knowledge-base", "main", mock=True) as lakefs:
    refund_policy = lakefs.read_object("docs/refund_policy.pdf")
    taxonomy = lakefs.read_object("config/category_taxonomy.json")

    print(f"Read refund policy: {len(refund_policy)} bytes")
    print(f"Read taxonomy: {len(taxonomy)} bytes")
    print(f"Commit SHA: {lakefs.get_commit()}")

Track Reads with a Decorator

@versioned injects a VersionedClient as the versioned_client keyword argument. Pass your Briefcase AI client as briefcase_client when you call the function.

from briefcase.integrations.lakefs import versioned
from unittest.mock import Mock


class MockBriefcaseClient:
    def __init__(self):
        self.config = {
            "lakefs_endpoint": "https://example.lakefscloud.io/api/v1",
            "lakefs_access_key": "your_access_key",
            "lakefs_secret_key": "your_secret_key",
        }


client = MockBriefcaseClient()


@versioned(repository="knowledge-base", branch="main", mock=True)
def classify_ticket(ticket: dict, versioned_client=None) -> dict:
    policy = versioned_client.read_object("docs/refund_policy.pdf")
    taxonomy = versioned_client.read_object("config/category_taxonomy.json")

    return {
        "category": "billing",
        "commit_sha": versioned_client.get_commit(),
        "bytes_read": len(policy) + len(taxonomy),
    }


ticket = {"id": "TKT-4471", "subject": "Refund request"}
result = classify_ticket(ticket, briefcase_client=client)
print(f"Category: {result['category']}")
print(f"Commit SHA: {result['commit_sha']}")

Use the Client Directly

Construct a VersionedClient when you need explicit control over reads, existence checks, and listings.

from briefcase.integrations.lakefs import VersionedClient
from unittest.mock import Mock


class MockBriefcaseClient:
    def __init__(self):
        self.config = {
            "lakefs_endpoint": "https://example.lakefscloud.io/api/v1",
            "lakefs_access_key": "your_access_key",
            "lakefs_secret_key": "your_secret_key",
        }


client = MockBriefcaseClient()

versioned_client = VersionedClient(
    repository="knowledge-base",
    branch="main",
    briefcase_client=client,
    mock=True,   # drop this and pass an endpoint + credentials for live reads
)

for path in ["docs/refund_policy.pdf", "docs/shipping_policy.pdf"]:
    if versioned_client.object_exists(path):
        content = versioned_client.read_object(path)
        print(f"Read {path}: {len(content)} bytes")

objects = versioned_client.list_objects(prefix="docs/")
print(f"Found {len(objects)} objects in docs/")
print(f"Commit SHA: {versioned_client.get_commit()}")

The TypeScript client is addressed per call rather than constructed against one repository and branch, so the ref you read at is explicit at every read:

import { createLakefsClient } from '@briefcase-ai/runtime/lakefs';

const lakefs = createLakefsClient({
  endpoint: process.env.LAKEFS_ENDPOINT!,
  accessKeyId: process.env.LAKEFS_ACCESS_KEY!,
  secretAccessKey: process.env.LAKEFS_SECRET_KEY!,
});

const policy = await lakefs.getObjectText({
  repo: 'knowledge-base',
  ref: 'main',
  path: 'docs/refund_policy.pdf',
});

const [latest] = await lakefs.listObjectCommits({
  repo: 'knowledge-base',
  ref: 'main',
  path: 'docs/refund_policy.pdf',
  limit: 1,
});

console.log(policy.length, latest?.id);

listObjectCommits is how you record provenance in TypeScript: it returns the commits that touched one path, up to limit (default 50), each with an id, message, author, and timestamp. Order is whatever lakeFS returns; sort by timestamp if you depend on it. There is no mock mode, so point the client at a lakeFS instance or stub fetch in your own tests.

VersionedClient Methods

Method	Returns
`read_object(path, return_metadata=False)`	Object bytes, optionally with metadata
`upload_object(path, data, content_type=...)`	Writes bytes to the branch
`list_objects(prefix="")`	Objects under a prefix
`object_exists(path)`	`True` if the object is present
`get_commit()`	The resolved commit SHA for this client

VersionedClient(repository, branch, commit="latest", briefcase_client=None, mock=False, require_live=False, ...) resolves commit="latest" against the branch head; pin a SHA to read a fixed version. Construction raises without an endpoint and credentials unless mock=True.

Limits

Mock mode returns a fixed commit and fabricated bytes. mock=True answers get_commit() with the same constant SHA every time and read_object() with stub content for any path, including paths that do not exist. It is for examples and offline tests. Pass require_live=True on production paths and the two flags together raise ValueError: mock=True conflicts with require_live.

Missing credentials raise at construction. VersionedClient(repository="kb", branch="main") with nothing configured raises ValueError: missing credentials rather than degrading. That is the 4.0.0 behavior described above, and it means client construction belongs where you can handle a failure.

The commit is resolved when the client is created, not per read. Every read inside a versioned_context is tagged with that one SHA. A commit landing on the branch mid-context is not picked up, which is what makes the provenance consistent and also means a long-lived client goes stale.

Provenance is recorded, not enforced. Tagging a read with a commit does not stop anything from reading around the client. A file opened directly gets no SHA and nothing notices.

API reference

briefcase.integrations.lakefs has the full VersionedClient, versioned_context, and @versioned signatures.

Where this fits

Capturing a lakeFS commit SHA is part of the Store & Query act: pin exactly what your agents read so replays are reproducible.

External Data Capture references to any external source — including data-lake commits — behind a decision.

Reproducible RAG Pin retrieval sources so a replayed RAG decision reads the same context.

Next steps

Storage Adapters Persist the decisions that captured these commit SHAs.

RAG Versioning Pin and track the document versions feeding your retrieval pipeline.