Migrate from Latitude V1

​

What changed

​

Concept map

​

Before you start

1. Export your prompts while your V1 workspace is still active. latitude.prompts.getAll() (SDK 5) or GET https://gateway.latitude.so/api/v3/projects/{projectId}/versions/live/documents returns every PromptL document with its content and config. Commit them to your repository; they are the source material for moving the prompts into code.
2. Export every dataset. Download the CSV from the Datasets page, or list them with GET /api/v3/datasets and pull rows with GET /api/v3/dataset-rows?datasetId=...&page=1&pageSize=100. Note which column is the label.
3. List your evaluations per prompt: name, type (judge, rule, human), criteria, and whether it ran live. Each becomes a signal or an annotation habit.
4. Write down your customIdentifier scheme. It usually maps to a session id or a user id.
5. Pick a project boundary. V2 projects are per agent. LinguaAI’s grammar checker and quiz writer share one project because they share one product surface and one user base.
6. Connect the MCP to your coding agent. For Claude Code:
   claude mcp add --transport http latitude https://api.latitude.so/v1/mcp --scope user
   
   Then type /mcp, pick latitude, authenticate, and choose the organization. Other agents are covered on the MCP page. The MCP is OAuth-only; an API key on that URL gets a 401 by design. Revoke the agent any time under Settings, Keys, OAuth Keys.
7. Point your coding agent at the V2 docs. Older V1 pages survive in search caches, and agents sometimes pull them in. Tell the agent to use https://docs.latitude.so/llms.txt as its index.

​

The example: LinguaAI

​

Create the V2 project

Create a Latitude project called LinguaAI and give me its slug.

​

Move the prompts into code

---
provider: anthropic
model: claude-3-5-sonnet-latest
temperature: 0
---
<system>
You are LinguaAI's grammar coach. The learner is studying {{ language }}.
Check the learner's text for grammar errors.
Reply ONLY with JSON of this shape: ...
</system>

<user>
Language: {{ language }}
Text: {{ text }}
</user>

GRAMMAR_CHECK_V2 = """You are LinguaAI's grammar coach. The learner is studying {language}.
Check the learner's text for grammar errors.
Reply ONLY with JSON of this shape: ..."""

GRAMMAR_CHECK_VERSIONS = {
    "2.0.0": ("grammar-check@2", GRAMMAR_CHECK_V2),
    "2.1.0": ("grammar-check@3", GRAMMAR_CHECK_V3),
}

def grammar_check_prompt(language: str) -> tuple[str, str]:
    version, template = GRAMMAR_CHECK_VERSIONS[APP_RELEASE]
    return version, template.format(language=language)

​

Replace the gateway call with a direct call plus telemetry

from latitude_sdk import Latitude, LatitudeOptions, RunPromptOptions

sdk = Latitude(api_key, LatitudeOptions(project_id=int(project_id), version_uuid=version_uuid))

result = await sdk.prompts.run("grammar-check", RunPromptOptions(parameters={"text": req.text, "language": req.language}))
data = _extract_json(result.response.text)

# telemetry.py: import this before any Anthropic client exists
import anthropic
from latitude_telemetry import Latitude

latitude = Latitude(
    api_key=os.environ["LATITUDE_API_KEY"],
    project=os.environ["LATITUDE_PROJECT_SLUG"],
    instrumentations={"anthropic": anthropic},
)

# services.py: one capture() per use case
from anthropic import Anthropic
from latitude_telemetry import capture

client = Anthropic()

def check_grammar(text, language, *, user_id, session_id):
    version, system = prompts.grammar_check_prompt(language)
    raw = capture(
        "grammar-check",
        lambda: client.messages.create(
            model=prompts.MODEL, max_tokens=600, system=system,
            messages=[{"role": "user", "content": f"Language: {language}\nText: {text}"}],
        ).content[0].text,
        {
            "user_id": user_id,
            "session_id": session_id,
            "tags": ["grammar", f"release-{prompts.APP_RELEASE}", "production"],
            "metadata": {"release": prompts.APP_RELEASE, "prompt_version": version, "language": language},
        },
    )
    return _extract_json(raw)

• Construct Latitude(...) once, at import time, before the provider client. Pass the same module your code imports (anthropic, not a wrapper around it).
• Wrap the model call in capture(). It creates no spans of its own. It attaches user, session, tags and metadata to the spans the instrumentation creates inside the callback. The route handler reads X-User-Id and X-Session-Id headers and passes them down; the smoke script passes them directly.
• Put the release in a tag as well as in metadata. Tags are the cohort key for session filters and Experiments; metadata holds exact values for search.
• Flush before a short-lived process exits (latitude.flush(), then latitude.shutdown()). Servers export in the background, but scripts, tests and jobs can exit before the last batch ships.

Install the latitude-migrate skill from github.com/latitude-dev/skills and use it to move this app from Latitude V1 to V2.

Install the latitude-telemetry skill from github.com/latitude-dev/skills and use it to add Latitude tracing to this app.

​

Run traffic and verify it with the MCP

APP_RELEASE=2.0.0 python -m scripts.smoke
APP_RELEASE=2.1.0 python -m scripts.smoke

List the latest grammar traces in linguaai and open one. Show me the conversation, the metadata, and who the user was.

​

Recreate the evaluation as a signal

Create a signal in linguaai called “Missed grammar error” for traces tagged grammar. Use an LLM judge: the behaviour is present when the learner’s text has an error that the corrections list does not cover, or when is_correct is true although the text has an error.

• A signal detector collects forward from creation. It does not scan history, so create signals before you generate the traffic you want judged.
• Judge evaluations default to 10 percent sampling. On a low-traffic demo, open the signal in the UI and set the scope to 100 percent, or it may never fire.
• The criteria text is compiled into the detector. Avoid backticks in it. In our run, a criteria string with backticks was rejected with a syntax error.

​

Bring your golden dataset

Create a dataset called grammar-regressions in linguaai. Import every grammar trace from release 2.0.0 with no errors as rows.

rows = [
    {"input": {"text": r["text"], "language": r["language"]},
     "expectedOutput": r["expected_output"],
     "metadata": {"source": "latitude-v1-golden-dataset"}}
    for r in csv.DictReader(fh)
]
client.datasets.insert_rows(project, "grammar-regressions", rows=rows)

Set the expected output of the row whose input contains “If I would have known” to “If I had known, I would have come earlier.”

​

Regression test by replaying the dataset

LATITUDE_DATASET_SLUG=grammar-regressions APP_RELEASE=2.1.0 pytest -q

​

Compare prompt versions with an Experiment

Create an experiment in linguaai comparing sessions tagged release-2.0.0 (baseline) with sessions tagged release-2.1.0, excluding sessions tagged simulation, over the last 7 days.

​

Annotate, monitor, dispatch

Annotate trace 2a27c6f2… in linguaai as passed with the feedback “Correctly recognised a well-formed sentence and returned is_correct=true with no spurious corrections.”

​

Decommission V1

• Remove latitude-sdk<6 (Python) or @latitude-data/sdk<6 (TypeScript) and every prompts.run, prompts.chat, logs.create and evaluations.annotate call.
• Delete LATITUDE_PROJECT_ID and LATITUDE_VERSION_UUID from your environment. V2 uses LATITUDE_PROJECT_SLUG.
• Keep the exported PromptL files in your repository history and delete them once every prompt has a code owner.
• Rotate the V1 API key.

​

Gotchas from this migration

• Provider parameters are yours now. The PromptL frontmatter hid provider differences; Anthropic’s Python SDK 1.x rejected temperature on messages.create(). Check each setting you carry over.
• Sessions belong to one release. Reusing session ids across releases produced sessions that no cohort filter could own. Suffix the id or start new sessions on deploy.
• Split cohorts on tags. Tag filters worked on sessions and in Experiments in our run, while a metadata.release filter on sessions did not match even though the sessions showed the field. Metadata is for search and for filtering traces.
• Keep replays out of production cohorts. Regression runs carry the release tag too, so exclude simulation in experiment variants and monitors.
• Signals collect forward and sample at 10 percent by default. Create them first, then generate traffic, and raise sampling in the UI for low-volume projects.
• No backticks in judge criteria. The criteria is compiled, and a backtick broke it with a syntax error.
• A V1 prompt with type: agent and a Latitude-hosted tool (latitude/extract and similar) needs a real implementation and a hand-written tool-call loop in V2; there is no hosted-tool equivalent. The latitude-migrate skill’s promptl-to-code.md has a full example.
• Flush before exit. Short scripts lose their last batch without flush() and shutdown().
• The MCP is OAuth-only. An API key on the MCP URL returns 401. Use the API key for the SDK, CLI and REST, and OAuth for the MCP.
• Old docs linger in agent memory. Point coding agents at docs.latitude.so/llms.txt.

​

Frequently asked

​

Reference: the MCP calls used in this guide