latentlab

The official Python package for LatentLab. One distribution on PyPI, multiple submodules — the same shape as anthropic, openai, etc.

Install

pip install latentlab
# Or from source while developing:
pip install -e ./python

MCP — configure

Point the server at a LatentLab deployment. In your MCP host's config (example for Claude Desktop / Claude Code):

{
  "mcpServers": {
    "latentlab": {
      "command": "python",
      "args": ["-m", "latentlab.mcp"],
      "env": {
        "LATENTLAB_API_URL": "https://latentlabdev.media.mit.edu/api"
      }
    }
  }
}

Restart the host. A new tool group latentlab_* becomes available.

MCP — auth (one-time per user)

The first call to any tool that needs auth runs the device-code flow:

1. Server hits POST /v1/auth/device/start, prints the verification_url and user_code for the user to open.
2. User signs in to the deployment, lands on /device, types the code, clicks "Approve."
3. Server polls POST /v1/auth/device/poll and persists the returned API key under ~/.latentlab/credentials.json.

After that, every tool reuses the saved key. Run latentlab_logout to forget it.

MCP — tools

Source layout

python/
  pyproject.toml
  README.md                            (this file)
  CONTRIBUTING.md                      Three-test checklist for new endpoints
  src/latentlab/
    __init__.py                        Exposes __version__; SDK lands here
    mcp/
      __init__.py
      __main__.py                      `python -m latentlab.mcp` entry
      server.py                        Tool registry + dispatch, MCP stdio bootstrap
      client.py                        Thin REST client (httpx)
      storage.py                       Local credentials persistence
      settings_schema.py               Per-call pipeline-settings overrides (ADR-056)

Versioning

Pinned to the LatentLab API version. Server-side OpenAPI changes that break tool signatures are rolled out with a matching minor bump here. See CONTRIBUTING.md for the rolling-patch convention.

The top-level latentlab.__version__ is read from package metadata so it always matches what's on PyPI.

Releasing to PyPI

Publishing is automated by .github/workflows/publish-latentlab.yml. It is wired to PyPI Trusted Publishing (OIDC) — no API token is stored as a repo secret. To cut a release:

1. Bump version in pyproject.toml (the installed __version__ is read from package metadata, so there's only one place to edit).

2. Commit on dev.

3. Tag and push:

   git tag v0.2.1
   git push origin v0.2.1
   

The workflow verifies that the tag matches the pyproject version, builds an sdist + wheel, and uploads them. The trusted-publisher binding on PyPI must already be configured for this repo and the publish-latentlab.yml workflow under environment pypi — see docs/releasing-latentlab.md for the one-time setup.