@moda-ai/cli 1.11.0 → 1.12.0

package/skills/integration/integration-node-langchain/SKILL.md

@@ -0,0 +1,144 @@
+---
+id: integration-node-langchain
+name: "Integrate Moda with LangChain / LangGraph (Node.js / TypeScript)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks:
+    - langchain
+  providers: []
+sdk_package: moda-ai
+summary: "Instrument a Node.js LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run."
+---
+
+# Integrate Moda with LangChain / LangGraph (Node.js / TypeScript)
+
+Follow the steps below in order. Each step has a stop condition; when you hit
+one, stop and report instead of guessing. `EXAMPLE.md` in this directory shows
+the complete finished integration; match its structure. For API details beyond
+this skill, read https://docs.moda.dev/ingestion/moda-sdk-node (if the
+installed `moda-ai` package ships docs under `node_modules/moda-ai/docs/`,
+prefer those; they match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## What is different about agent frameworks
+
+Two constraints drive every step below:
+
+1. Instrument at the Moda SDK level, not inside LangChain. Initialize Moda
+   once and set an explicit conversation id around each run; the LLM calls
+   the agent makes internally are then captured and share that id (this is
+   the documented agent-framework pattern — see the "Solution for Agent
+   Applications" section of the Node SDK docs). Do not add LangChain
+   callbacks, handlers, or tracer classes for Moda — no such Moda API
+   exists.
+2. Explicit conversation ids are mandatory. Moda's automatic conversation
+   detection hashes the first user message, and agent frameworks construct
+   different messages on every internal iteration, so without an explicit id
+   every iteration lands in a different conversation.
+
+## Step 1: Find the agent/chain entry points
+
+Find where the application invokes LangChain or LangGraph: `.invoke(...)`,
+`.stream(...)`, agent executor runs, or graph runs. These entry points — not
+the internal LLM calls — are where conversation context gets set.
+
+- If you cannot find any LangChain/LangGraph entry point, stop and report.
+- If the repository's LLM calls actually go through the Vercel AI SDK (the
+  `ai` package) rather than LangChain, stop: use the Vercel AI SDK skill
+  instead.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup
+
+`Moda.init` must run before LangChain constructs any provider client (which
+usually happens at model/agent construction). Initialize at the top of the
+application entry point. If a `Moda.init` call already exists, verify it runs
+at startup and skip this step; never add a second call.
+
+```typescript
+import { Moda } from 'moda-ai';
+
+await Moda.init(process.env.MODA_API_KEY!);
+```
+
+## Step 4: Wrap every agent/chain run in an explicit conversation id
+
+Wrap each entry point found in Step 1 so all internal LLM calls made during
+that run share one conversation id. Use the scoped helpers so concurrent
+runs do not leak context into each other:
+
+```typescript
+import { withContext } from 'moda-ai';
+
+const result = await withContext(`agent_session_${sessionId}`, userId, async () =>
+  agent.invoke({ input: userQuery }),
+);
+```
+
+For strictly sequential code, the global property form is equivalent:
+
+```typescript
+Moda.conversationId = `agent_session_${sessionId}`;
+const result = await agent.invoke({ input: userQuery });
+Moda.conversationId = null;
+```
+
+Reuse the session/thread identifier the app already has (LangGraph
+`thread_id`, a chat session id, a ticket id). If no session identifier
+exists anywhere, stop and report; do not invent one.
+
+## Step 5: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 6: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces, and multi-step agent runs should share
+one conversation id. If each internal LLM call shows up as its own
+conversation, the explicit conversation id from Step 4 is not wrapping the
+run — fix that before finishing.

package/skills/integration/integration-node-openai/EXAMPLE.md

@@ -0,0 +1,55 @@
+# Golden reference: Express + OpenAI SDK + Moda
+
+The complete finished integration for a minimal Express chat server that
+calls the OpenAI SDK directly. Match this structure; adapt names to the
+target repository.
+
+## src/server.ts
+
+```typescript
+import express from 'express';
+import { Moda, withContext } from 'moda-ai';
+import OpenAI from 'openai';
+
+// Initialize Moda once, before the OpenAI client is created. After this,
+// every chat.completions.create call is captured automatically.
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new OpenAI();
+const app = express();
+app.use(express.json());
+
+app.post('/chat', async (req, res) => {
+  const { sessionId, userId, message } = req.body;
+
+  // Scoped context: safe under concurrent requests.
+  const response = await withContext(`session_${sessionId}`, userId, async () =>
+    client.chat.completions.create({
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: message }],
+    }),
+  );
+
+  res.json({ reply: response.choices[0].message.content });
+});
+
+// Flush pending telemetry on shutdown.
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+
+app.listen(3000);
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- One `Moda.init` call added at startup, before `new OpenAI()`.
+- The handler wraps its existing OpenAI call in `withContext`; the
+  `chat.completions.create` call itself is unchanged — instrumentation is
+  automatic.
+- A `SIGTERM` handler flushes telemetry on shutdown.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

package/skills/integration/integration-node-openai/SKILL.md

@@ -0,0 +1,148 @@
+---
+id: integration-node-openai
+name: "Integrate Moda with the OpenAI SDK (Node.js / TypeScript)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks: []
+  providers:
+    - openai
+sdk_package: moda-ai
+summary: "Auto-instrument direct openai client calls with Moda in a Node.js or TypeScript app; no per-call changes required."
+---
+
+# Integrate Moda with the OpenAI SDK (Node.js / TypeScript)
+
+Follow the steps below in order. Each step has a stop condition; when you hit
+one, stop and report instead of guessing. `EXAMPLE.md` in this directory shows
+the complete finished integration; match its structure. For API details beyond
+this skill, read https://docs.moda.dev/ingestion/providers/openai and
+https://docs.moda.dev/ingestion/moda-sdk-node (if the installed `moda-ai`
+package ships docs under `node_modules/moda-ai/docs/`, prefer those; they
+match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## Step 1: Confirm the raw OpenAI client is the integration surface
+
+Find the real LLM call sites: `client.chat.completions.create(...)` on a
+client constructed with `new OpenAI()` from the `openai` package.
+
+- If the OpenAI calls go through a wrapper framework instead — the `ai`
+  package (Vercel AI SDK) or LangChain — stop: instrument the wrapper layer
+  with its dedicated skill, never the underlying provider client.
+- If the repo wraps its OpenAI client in a helper module (for example
+  `lib/openai.ts` exporting a shared client), plan to instrument at that one
+  place; do not edit every call site.
+- If there are no OpenAI call sites at all, stop and report.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup, before the client is created
+
+Instrumentation is automatic: once `Moda.init` has run, every
+`chat.completions.create` call (including streaming, function calling, and
+embeddings) is captured with no per-call changes.
+
+`Moda.init` must run before the OpenAI client is constructed. If a
+`Moda.init` call already exists, verify it runs at startup before client
+creation and skip this step; never add a second call.
+
+```typescript
+import { Moda } from 'moda-ai';
+import OpenAI from 'openai';
+
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new OpenAI();
+```
+
+If the client lives in a shared helper module, initialize Moda at the top of
+the application entry point (before that module is imported), or at the top
+of the helper module itself — whichever the existing structure makes
+smallest.
+
+## Step 4: Set conversation and user context
+
+Set a stable conversation id before each LLM call so multi-turn
+conversations group together, and a user id when one user can be identified.
+
+For sequential code, use the global properties:
+
+```typescript
+Moda.conversationId = `session_${sessionId}`;
+Moda.userId = userId;
+```
+
+For concurrent request handlers (any web server), use the scoped helper so
+overlapping requests do not leak context into each other:
+
+```typescript
+import { withContext } from 'moda-ai';
+
+const response = await withContext(`session_${sessionId}`, userId, async () =>
+  client.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: userMessage }],
+  }),
+);
+```
+
+Reuse the session/thread identifier the app already has. If no session
+identifier exists anywhere, the SDK falls back to hashing the first user
+message plus the system prompt — acceptable only for simple chatbots that
+pass full message history on every call. If this repo is an agent framework
+or does not pass full history, an explicit conversation id is required; stop
+and report if you cannot find a session identifier to use.
+
+## Step 5: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 6: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces. If it does not, confirm `MODA_API_KEY`
+is available in the runtime environment and that `Moda.init()` runs before
+the OpenAI client is created.

package/skills/integration/integration-node-vercel-ai-sdk/EXAMPLE.md

@@ -0,0 +1,55 @@
+# Golden reference: Next.js App Router + Vercel AI SDK + Moda
+
+The complete finished integration for a minimal Next.js chat route. Match
+this structure; adapt names to the target repository.
+
+## instrumentation.ts (project root)
+
+Moda initializes once at server startup, before any AI SDK call.
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { Moda } = await import('moda-ai');
+    await Moda.init(process.env.MODA_API_KEY!);
+  }
+}
+```
+
+## app/api/chat/route.ts
+
+Every AI SDK call passes `experimental_telemetry`, and conversation/user
+context is scoped per request with `withContext` so concurrent requests
+never leak into each other.
+
+```typescript
+import { Moda, withContext } from 'moda-ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+export async function POST(request: Request) {
+  const { sessionId, userId, message } = await request.json();
+
+  const result = await withContext(`session_${sessionId}`, userId, async () =>
+    generateText({
+      model: openai('gpt-4o'),
+      prompt: message,
+      experimental_telemetry: Moda.getVercelAITelemetry(),
+    }),
+  );
+
+  await Moda.flush();
+
+  return Response.json({ reply: result.text });
+}
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- `instrumentation.ts` created (or extended) with the one-time `Moda.init`.
+- Each AI SDK call site gained `experimental_telemetry` and scoped context.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.
+- The raw `@ai-sdk/openai` provider client was NOT separately instrumented;
+  the AI SDK telemetry layer is the single integration surface.

package/skills/integration/integration-node-vercel-ai-sdk/SKILL.md

@@ -0,0 +1,179 @@
+---
+id: integration-node-vercel-ai-sdk
+name: "Integrate Moda with the Vercel AI SDK (Node.js / TypeScript)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks:
+    - vercel-ai-sdk
+  providers: []
+sdk_package: moda-ai
+summary: "Instrument Vercel AI SDK calls (generateText, streamText, generateObject) with Moda telemetry in a Node.js or TypeScript app."
+---
+
+# Integrate Moda with the Vercel AI SDK (Node.js / TypeScript)
+
+Follow the steps below in order. Each step has a stop condition; when you hit
+one, stop and report instead of guessing. `EXAMPLE.md` in this directory shows
+the complete finished integration; match its structure. For API details beyond
+this skill, read https://docs.moda.dev/ingestion/vercel-ai-sdk (if the
+installed `moda-ai` package ships docs under `node_modules/moda-ai/docs/`,
+prefer those; they match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## Step 1: Confirm the Vercel AI SDK is the integration surface
+
+Find the real LLM call sites: search for `generateText`, `streamText`,
+`generateObject`, or `streamObject` imported from the `ai` package.
+
+- If you find none, stop and report: this skill only applies to apps that
+  call the Vercel AI SDK directly.
+- Instrument the Vercel AI SDK layer only. Do NOT also instrument raw
+  `openai` / `@anthropic-ai/sdk` clients that are used through the AI SDK;
+  that produces duplicate telemetry for the same call.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup
+
+`Moda.init` must run once, before the first AI SDK call. If a `Moda.init`
+call already exists somewhere in the codebase, verify it runs at startup and
+skip this step; never add a second call.
+
+Next.js: put it in `instrumentation.ts` at the project root (create the file
+if it does not exist):
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { Moda } = await import('moda-ai');
+    await Moda.init(process.env.MODA_API_KEY!);
+  }
+}
+```
+
+Any other Node app: initialize at the top of the entry point, before the
+first AI SDK call:
+
+```typescript
+import { Moda } from 'moda-ai';
+
+await Moda.init(process.env.MODA_API_KEY!);
+```
+
+`Moda.init` is async. Await it so initialization completes before the first
+LLM call; skipping the await risks the first call going uninstrumented.
+
+## Step 4: Pass Moda telemetry at every AI SDK call site
+
+Add `experimental_telemetry: Moda.getVercelAITelemetry()` to every
+`generateText` / `streamText` / `generateObject` / `streamObject` call:
+
+```typescript
+import { Moda } from 'moda-ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: userMessage,
+  experimental_telemetry: Moda.getVercelAITelemetry(),
+});
+```
+
+Streaming works the same way; telemetry is captured after the stream
+completes. If a call site already passes `experimental_telemetry`, stop and
+report that call site instead of overwriting it.
+
+## Step 5: Set conversation and user context
+
+Set a stable conversation id before each AI SDK call so multi-turn
+conversations group together, and a user id when one user can be identified.
+Set them before calling `Moda.getVercelAITelemetry()`; the telemetry config
+captures them at call time.
+
+For sequential code, use the global properties:
+
+```typescript
+Moda.conversationId = `session_${sessionId}`;
+Moda.userId = userId;
+```
+
+For concurrent request handlers (any web server), use the scoped helper so
+overlapping requests do not leak context into each other:
+
+```typescript
+import { Moda, withContext } from 'moda-ai';
+
+const result = await withContext(`session_${sessionId}`, userId, async () =>
+  generateText({
+    model: openai('gpt-4o'),
+    prompt: userMessage,
+    experimental_telemetry: Moda.getVercelAITelemetry(),
+  }),
+);
+```
+
+Reuse the session/thread identifier the app already has. If no session
+identifier exists anywhere, stop and report; do not invent one.
+
+## Step 6: Attribute managed prompts (only if the repo uses them)
+
+Only if this repository has a `.moda/prompts.yml` manifest: render managed
+prompts through the SDK before creating the telemetry config, so traces point
+at exact prompt versions. See
+[references/prompt-attribution.md](references/prompt-attribution.md).
+If there is no prompt manifest, skip this step.
+
+## Step 7: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 8: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces. If it does not, confirm `MODA_API_KEY`
+is available in the runtime environment and that `Moda.init()` runs before
+the first AI SDK call.

package/skills/integration/integration-node-vercel-ai-sdk/references/prompt-attribution.md

@@ -0,0 +1,31 @@
+# Prompt attribution with the Vercel AI SDK
+
+Only relevant when the repository manages prompts with Moda
+(`.moda/prompts.yml` exists and prompts are synced with `moda prompts sync`).
+
+Render the managed prompt through the SDK, then create the telemetry config.
+`Moda.getVercelAITelemetry()` includes the rendered prompt's metadata
+(`moda.prompt_key`, `moda.prompt_id`, `moda.prompt_version`,
+`moda.prompt_version_id`) in `experimental_telemetry.metadata`, so production
+traces point at the exact prompt version:
+
+```typescript
+import { Moda } from 'moda-ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const rendered = Moda.prompt('support.triage').render({
+  ticket: { text: userMessage },
+});
+
+const result = await generateText({
+  model: openai('gpt-4o'),
+  messages: rendered.messages,
+  experimental_telemetry: Moda.getVercelAITelemetry(),
+});
+```
+
+Order matters: render the prompt before calling
+`Moda.getVercelAITelemetry()` so prompt metadata is attached.
+
+Full reference: https://docs.moda.dev/ingestion/vercel-ai-sdk

package/skills/integration/integration-python-anthropic/EXAMPLE.md

@@ -0,0 +1,66 @@
+# Golden reference: FastAPI + Anthropic SDK + Moda
+
+The complete finished integration for a minimal FastAPI chat service that
+calls the Anthropic SDK directly. Match this structure; adapt names to the
+target repository.
+
+## app/main.py
+
+```python
+import os
+from contextlib import asynccontextmanager
+
+import moda
+from anthropic import Anthropic
+from fastapi import FastAPI
+from moda import set_conversation_id, set_user_id
+from pydantic import BaseModel
+
+# Initialize Moda before creating any LLM client so instrumentation is
+# active. After this, every messages.create call is captured automatically.
+moda.init(os.environ["MODA_API_KEY"])
+
+client = Anthropic()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+    # Flush pending telemetry on shutdown.
+    moda.flush()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+class ChatRequest(BaseModel):
+    session_id: str
+    user_id: str
+    message: str
+
+
+@app.post("/chat")
+def chat(request: ChatRequest):
+    # Scoped context: safe under concurrent requests.
+    with set_conversation_id(f"session_{request.session_id}"):
+        with set_user_id(request.user_id):
+            response = client.messages.create(
+                model="claude-sonnet-4-20250514",
+                max_tokens=1024,
+                messages=[{"role": "user", "content": request.message}],
+            )
+    reply = "".join(block.text for block in response.content if block.type == "text")
+    return {"reply": reply}
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to the project dependencies.
+- One `moda.init` call added at module import time, before `Anthropic()` is
+  constructed.
+- The handler wraps its existing Anthropic call in the scoped context
+  managers; the `messages.create` call itself is unchanged — instrumentation
+  is automatic.
+- Shutdown flushes telemetry via the FastAPI lifespan hook.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.