### Local Development Setup

Source: https://github.com/latitude-dev/latitude-llm/blob/development/CONTRIBUTING.md

Installs dependencies, configures environment variables, builds the project, and starts local infrastructure. Ensure Node.js 25, Python 3.13, pnpm 10, Docker, goose, and uv are installed.

```bash
pnpm install                           # also configures the git hooks
cd packages/platform/op-gepa/python 
 && uv venv \
 && uv sync --all-extras --all-groups
cp .env.example .env.development       # local defaults
cp .env.example .env.test              # then set NODE_ENV=test in it
mkdir -p storage                       # set LAT_STORAGE_FS_ROOT to its absolute path in both env files
pnpm build                             # required before migrations
docker compose up -d                   # start infrastructure only
pnpm migrate                           # run Postgres (Drizzle) + ClickHouse (goose) migrations
pnpm seed                              # create sample org, users and telemetry
pnpm tmux                              # or `pnpm dev`, or per-service `pnpm --filter @app/<svc> dev`
```

--------------------------------

### Install Dependencies and Configure Environment

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/flue-app/README.md

Install project dependencies and copy the example environment file. Fill in the necessary API keys and URLs for Latitude and OpenAI.

```bash
npm install
cp .env.example .env   # fill in LATITUDE_API_KEY, LATITUDE_PROJECT_SLUG, OPENAI_API_KEY
                       # point LATITUDE_TELEMETRY_URL at your instance (http://localhost:3002 for local)
```

--------------------------------

### Setup: Installing Provider SDK

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Command to install a specific AI provider's SDK, such as OpenAI, using npm. This is a prerequisite for running provider-specific examples.

```bash
npm install openai
```

--------------------------------

### Setup: Running an Example with Exported Environment Variables

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Command to execute a TypeScript example file using tsx, assuming environment variables have been exported directly in the shell.

```bash
npx tsx test_openai.ts
```

--------------------------------

### Run SDK examples from this directory

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/typescript/examples/README.md

Invokes the SDK example scripts directly from the example directory. Ensure your `.env` file is configured.

```bash
pnpm annotate:byTraceId   # by-id
pnpm annotate:byFilter    # by-filter (requires LATITUDE_SESSION_ID)
pnpm apiKeys:list         # list API keys for the organization
```

--------------------------------

### Setup: Using .env File for Environment Variables

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Shows how to copy and edit the example .env file to configure your environment variables for Latitude and provider API keys. This method is recommended for local development.

```bash
cp .env.example .env
# Edit .env with your actual values
```

--------------------------------

### Interactive Installation

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/openclaw-cli/README.md

Use this command for a guided, interactive setup of the telemetry plugin. The CLI will prompt for necessary details like API key and project slug.

```bash
npx -y @latitude-data/openclaw-telemetry-cli@0.0.9 install
```

--------------------------------

### Setup: Running an Example with .env File

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Command to execute a TypeScript example file using tsx, specifically when environment variables are configured via a .env file. Requires Node.js 20+.

```bash
npx tsx --env-file=.env test_openai.ts
```

--------------------------------

### Install Dependencies and Configure Environment

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/eve-app/README.md

Install project dependencies and copy the example environment file. Fill in the necessary API keys and project slugs for Latitude and OpenAI, and set the Latitude telemetry URL.

```bash
pnpm install
cp .env.example .env.local   # fill in LATITUDE_API_KEY, LATITUDE_PROJECT_SLUG, OPENAI_API_KEY
                             # point LATITUDE_TELEMETRY_URL at your instance (http://localhost:3002 for local)
```

--------------------------------

### Install SDK and Dependencies

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/examples/README.md

Installs the Latitude SDK in editable mode and its development dependencies using uv. Also copies the example environment file.

```bash
uv sync                # installs the SDK (editable) + dev deps into .venv
cp examples/.env.example examples/.env
# then fill in LATITUDE_API_KEY, LATITUDE_PROJECT_SLUG, LATITUDE_TRACE_ID
# (and LATITUDE_SESSION_ID for the filter variant). LATITUDE_API_BASE_URL
# is optional — unset means production.
```

--------------------------------

### Quick Start Helm Installation

Source: https://github.com/latitude-dev/latitude-llm/blob/development/charts/latitude/README.md

Install the Latitude Helm chart with essential configurations for a complete deployment. Ensure you store the generated secrets for future upgrades.

```bash
helm install latitude ./charts/latitude \
  --namespace latitude --create-namespace \
  --set config.webUrl=https://latitude.example.com \
  --set config.apiUrl=https://api.latitude.example.com \
  --set config.ingestUrl=https://ingest.latitude.example.com \
  --set secrets.masterEncryptionKey=$(openssl rand -hex 32) \
  --set secrets.betterAuthSecret=$(openssl rand -hex 32) \
  --set postgres.auth.password=$(openssl rand -hex 16) \
  --set postgres.auth.runtimePassword=$(openssl rand -hex 16) \
  --set clickhouse.auth.password=$(openssl rand -hex 16) \
  --timeout 15m
```

--------------------------------

### Quick Start: Basic Latitude Telemetry Setup

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Demonstrates the simplest way to initialize Latitude and capture an AI provider call without an existing OpenTelemetry setup. Ensure your API key, project slug, and LLM SDK module are correctly passed.

```typescript
import OpenAI from "openai"
import { Latitude, capture } from "@latitude-data/telemetry"

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI }, // Pass the LLM SDK module you use in app code.
})

const client = new OpenAI()

await capture(
  "chat-call",
  async () => {
    return await client.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: "Hello!" }],
    })
  },
  { tags: ["production"], userId: "user-123" },
)

await latitude.flush()
```

--------------------------------

### Download Deployment Files

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/deployment/single-host.mdx

Download the necessary deployment configuration files for a single-host setup. Ensure you have `curl` installed.

```bash
base=https://raw.githubusercontent.com/latitude-dev/latitude-llm/development
curl -fsSL --create-dirs "$base/docker-stack.yml"              -o docker-stack.yml
curl -fsSL --create-dirs "$base/.env.example"                  -o .env.example
curl -fsSL --create-dirs "$base/docker/init-db.sh"             -o docker/init-db.sh
curl -fsSL --create-dirs "$base/docker/seaweedfs/init.sh"      -o docker/seaweedfs/init.sh
curl -fsSL --create-dirs "$base/docker/clickhouse/storage.xml" -o docker/clickhouse/storage.xml
```

--------------------------------

### Example Run Configuration

Source: https://github.com/latitude-dev/latitude-llm/blob/development/tools/live-seeds/README.md

Configure an example run with specific fixtures, counts, parallel cases, and a seed for reproducible testing.

```bash
cd /Users/sans/src/latitude-v2/tools/live-seeds
pnpm seed:live-seeds --fixtures warranty-eval-in,frustration-in,tool-call-error --count-per-fixture 3 --parallel-cases 2 --seed example-run-01
```

--------------------------------

### Run Python SDK Examples

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/examples/README.md

Executes Python SDK examples using uv run, specifying the environment file. Examples include creating annotations and listing API keys.

```bash
uv run --env-file examples/.env python examples/create_annotation.py
```

```bash
uv run --env-file examples/.env python examples/create_annotation_by_filter.py   # requires LATITUDE_SESSION_ID
```

```bash
uv run --env-file examples/.env python examples/list_api_keys.py
```

--------------------------------

### Run All Tests

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/platform/testkit/README.md

Execute all tests across the monorepo with automatic test database setup. This is the recommended quick start method.

```bash
# Setup test database and run all tests across the monorepo
pnpm test
```

--------------------------------

### Install Provider SDKs

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/python/examples/README.md

Install the Python SDKs for the specific AI providers you intend to test using 'uv add'.

```bash
# Examples:
uv add openai
uv add anthropic
uv add groq
uv add mistralai
uv add cohere
uv add together
uv add replicate
uv add google-generativeai
uv add ollama
uv add litellm
uv add boto3  # For Bedrock and SageMaker
uv add google-cloud-aiplatform  # For Vertex AI
uv add aleph-alpha-client
uv add ibm-watsonx-ai
uv add transformers torch
uv add langchain langchain-openai
uv add llama-index llama-index-llms-openai
uv add haystack-ai
uv add dspy-ai
uv add crewai
uv add google-adk
```

--------------------------------

### Copy and Edit .env Example

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/python/examples/README.md

Copy the example .env file and edit it with your specific values for local testing.

```bash
cp .env.example .env

# Edit .env with your actual values
```

--------------------------------

### Run LangChain Example

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Execute the LangChain example using tsx and environment variables.

```bash
npx tsx --env-file=.env test_langchain.ts
```

--------------------------------

### Install LlamaIndex Telemetry (poetry)

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/llamaindex.mdx

Install the Latitude telemetry package using poetry.

```bash
poetry add latitude-telemetry
```

--------------------------------

### Install Latitude Telemetry and Google ADK

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/google-adk.mdx

Install the necessary libraries using pip, uv, or poetry.

```bash
pip install latitude-telemetry google-adk
```

```bash
uv add latitude-telemetry google-adk
```

```bash
poetry add latitude-telemetry google-adk
```

--------------------------------

### Install LlamaIndex Telemetry (bun)

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/llamaindex.mdx

Install the Latitude telemetry package using bun.

```bash
bun add @latitude-data/telemetry
```

--------------------------------

### Run Vercel AI SDK Example

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/typescript/examples/README.md

Execute the Vercel AI SDK example using tsx and environment variables.

```bash
npx tsx --env-file=.env test_vercel_ai.ts
```

--------------------------------

### Create Production Environment File

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/deployment/single-host.mdx

Copy the example environment file to create your production configuration. This file will contain all necessary variables.

```bash
cp .env.example .env.production
```

--------------------------------

### Manual Test Database Setup

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/platform/testkit/README.md

Manually set up the test database by creating the database and running migrations. This is an alternative to the automatic setup.

```bash
# 1. Setup test database (create DB + run migrations)
pnpm test:db:setup

# 2. Run tests (will use the already-setup database)
pnpm --filter @app/api test
```

--------------------------------

### Create Environment Files

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/development/setup.mdx

Copies the example environment file to create development and test configurations. Ensure LAT_STORAGE_FS_ROOT points to an absolute path.

```bash
cp .env.example .env.development
cp .env.example .env.test
```

--------------------------------

### Run Local Latitude API

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/examples/README.md

Starts the Latitude API locally using pnpm, which is necessary for running the SDK examples against a local development environment.

```bash
pnpm --filter @app/api dev
```

--------------------------------

### Create Complete Organization Setup

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/platform/testkit/README.md

Illustrates creating a full organization setup, including an owner user and membership, using `createOrganizationSetup`. This function takes the test database instance as input.

```typescript
const { user, organization, membership } = await Effect.runPromise(
  createOrganizationSetup(testDb)
);
```

--------------------------------

### Create and Configure S3 Backend Bucket

Source: https://github.com/latitude-dev/latitude-llm/blob/development/infra/README.md

Create an S3 bucket for Pulumi state storage and enable versioning. This is a one-time setup step.

```bash
aws s3 mb s3://latitude-pulumi-state --region eu-central-1
aws s3api put-bucket-versioning --bucket latitude-pulumi-state --versioning-configuration Status=Enabled
```

--------------------------------

### Copy .env example

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/typescript/examples/README.md

Copies the example environment file to `.env`. You must then fill in your API key, project slug, and trace ID.

```bash
cp .env.example .env
```

--------------------------------

### Basic LLM Call Capture with Latitude

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/python/examples/README.md

This example shows the fundamental setup for capturing an LLM call using the `@capture` decorator. It initializes Latitude, wraps a function containing an LLM call, and flushes the telemetry data.

```python
import openai
import os

from latitude_telemetry import Latitude, capture

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

@capture("test-name", {"tags": ["test"], "session_id": "example"})
def test_function():
    # Your LLM call here
    ...

if __name__ == "__main__":
    test_function()
    latitude.flush()
```

--------------------------------

### Install Pi Telemetry Package

Source: https://github.com/latitude-dev/latitude-llm/blob/development/dev-docs/pi-telemetry.md

Use this command to install the pi telemetry package. Ensure you have Node.js and npm installed.

```bash
npx -y @latitude-data/pi-telemetry install
```

--------------------------------

### Run SDK examples from the repo root

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/typescript/examples/README.md

Invokes the SDK example scripts using the workspace filter from the repository root. This is useful for CI or when not changing directories.

```bash
pnpm --filter @examples/sdk-typescript annotate:byTraceId
pnpm --filter @examples/sdk-typescript annotate:byFilter
pnpm --filter @examples/sdk-typescript apiKeys:list
```

--------------------------------

### Set Pulumi Configuration and Deploy

Source: https://github.com/latitude-dev/latitude-llm/blob/development/infra/README.md

Configure SSH public key and egress CIDRs for Hex, then deploy the stack. This will replace the bastion with updated user data.

```bash
pulumi config set --secret hexSshPublicKey "ssh-ed25519 AAAA... hex-workspace" --stack production
pulumi config set --plaintext hexEgressCidrs '["1.2.3.4/32","5.6.7.8/32"]' --stack production
pulumi up --stack production
```

--------------------------------

### Manual Installation Configuration

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/telemetry/claude-code/README.md

This JSON configuration can be used for manual installation of Claude Code Telemetry if the installer is not suitable. It includes environment variables and hook settings.

```json
{
  "env": {
    "LATITUDE_API_KEY": "lat_xxx",
    "LATITUDE_PROJECT": "my-project-slug"
  },
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @latitude-data/claude-code-telemetry",
            "async": true
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/latitude-dev/latitude-llm/blob/development/infra/README.md

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Slack OAuth Install Flow Steps

Source: https://github.com/latitude-dev/latitude-llm/blob/development/specs/slack-integration.md

Outlines the sequence of HTTP requests and redirects involved in the Slack OAuth installation process, from user initiation to callback handling.

```text
1. User clicks "Connect Slack" in settings
   → GET /integrations/slack/install (apps/web)
   → write state in Redis
   → 302 to https://slack.com/oauth/v2/authorize?client_id=…&scope=…&state=…&redirect_uri=…

2. User approves in Slack
   → Slack 302s to /integrations/slack/oauth/callback?code=…&state=…

3. Callback handler (apps/web)
   → validate state (CSRF + binds org + user)
   → POST https://slack.com/api/oauth.v2.access (code + client_id + client_secret)
   → extract { access_token, team.id, team.name, bot_user_id, scope, app_id, authed_user.id }
   → if another live install exists for team.id under a different organization_id → error
   → in a single transaction: insert into integrations
     (kind='slack', vendor_account_id=team.id) and slack_integration_details
     (encrypted bot token, scopes, team_name, …)
     - on (organization_id, kind) conflict where revoked_at IS NULL → soft-revoke
       the prior parent row first, then re-insert
   → 302 to settings page
```

--------------------------------

### Install Packages for bun

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/eve.mdx

Install the necessary OpenTelemetry packages for bun.

```bash
bun add @vercel/otel @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Install Packages for yarn

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/eve.mdx

Install the necessary OpenTelemetry packages for yarn.

```bash
yarn add @vercel/otel @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Install Packages for pnpm

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/eve.mdx

Install the necessary OpenTelemetry packages for pnpm.

```bash
pnpm add @vercel/otel @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Install Packages for npm

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/eve.mdx

Install the necessary OpenTelemetry packages for npm.

```bash
npm install @vercel/otel @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Install Latitude TypeScript SDK

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/typescript/README.md

Install the Latitude TypeScript SDK using npm.

```sh
npm install @latitude-data/sdk
```

--------------------------------

### Example Monitor Preview Sentence

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/monitors/overview.mdx

This is an example of a preview sentence that restates the monitor configuration in plain English. It is generated as you configure an alert for a saved search.

```text
Alerts each time a new trace matching 'Checkout 5xx errors' is detected.
```

--------------------------------

### Install Latitude Python SDK

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/README.md

Install the Latitude Python SDK using pip.

```shell
pip install latitude-sdk
```

--------------------------------

### Async Client Example

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/README.md

Demonstrates how to use the asynchronous Latitude API client to list projects.

```python
from latitude_sdk import AsyncLatitudeApiClient

client = AsyncLatitudeApiClient(token=os.environ["LATITUDE_API_KEY"])
projects = await client.projects.list()
```

--------------------------------

### Install LlamaIndex Telemetry (uv)

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/llamaindex.mdx

Install the Latitude telemetry package using uv.

```bash
uv add latitude-telemetry
```

--------------------------------

### List and Create API Keys

Source: https://github.com/latitude-dev/latitude-llm/blob/development/packages/sdk/python/README.md

Demonstrates listing existing API keys and creating a new API key with a specified name.

```python
page = client.api_keys.list()

new_key = client.api_keys.create(name="ci-pipeline")
```

--------------------------------

### Install LlamaIndex Telemetry (pip)

Source: https://github.com/latitude-dev/latitude-llm/blob/development/docs/telemetry/frameworks/llamaindex.mdx

Install the Latitude telemetry package using pip.

```bash
pip install latitude-telemetry
```