Metadata-Version: 2.4
Name: latentlab
Version: 0.2.0
Summary: LatentLab Python package: MCP server (latentlab.mcp) + reserved namespace for a forthcoming REST SDK
Author: LatentLab maintainers
License: MIT
Project-URL: Homepage, https://github.com/viral-medialab/latentlabv4
Project-URL: Repository, https://github.com/viral-medialab/latentlabv4
Project-URL: Issues, https://github.com/viral-medialab/latentlabv4/issues
Project-URL: Source, https://github.com/viral-medialab/latentlabv4/tree/dev/python
Keywords: latentlab,mcp,llm,agents,anthropic,embeddings,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.9
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0

# latentlab

The official Python package for [LatentLab](https://latentlabdev.media.mit.edu).
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

```bash
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):

```jsonc
{
  "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:

   ```bash
   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.
