latentlab 0.2.0

LatentLab Python package: MCP server (latentlab.mcp) + reserved namespace for a forthcoming REST SDK

latentlab

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

Submodule	Status	What it is
latentlab.mcp	shipped	MCP server that wraps the LatentLab API as Model Context Protocol tools, so MCP-aware agents (Claude Desktop, Claude Code, Cline, Anthropic Agent SDK, …) can drive a deployment with typed tools. Implements the agent-facing surface of ADR-055.
latentlab (top level)	reserved	A sync REST client (from latentlab import Client) is planned. Until it lands, the top level only exposes __version__.

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

Tool	Args	What it does
latentlab_login	{}	Run device-code flow if no key cached.
latentlab_logout	{}	Delete the cached key.
latentlab_whoami	{}	Return the LatentLab user this key belongs to.
latentlab_list_datasets	{}	List the user's datasets.
latentlab_get_dataset	{ id }	Get one dataset by id (includes status).
latentlab_upload_csv	{ path, name, description? }	Upload a CSV from a local file.
latentlab_create_live_url_dataset	{ source_url, source_ref, name, ... }	Create a git-source live folder dataset.
latentlab_search	{ dataset_id, query, k? }	Semantic search inside a dataset.
latentlab_wait_for_processing	{ dataset_id, timeout_seconds? }	Poll until status=='complete'.
latentlab_dataset_url	{ dataset_id }	Return the human-facing /app/dataset URL.

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.