@moda-ai/cli 1.11.0 → 1.12.0

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

@@ -0,0 +1,141 @@
+---
+id: integration-python-langchain
+name: "Integrate Moda with LangChain / LangGraph (Python)"
+version: 1.0.0
+category: integration
+targets:
+  language: python
+  frameworks:
+    - langchain
+  providers: []
+sdk_package: moda-ai
+summary: "Instrument a Python LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run."
+---
+
+# Integrate Moda with LangChain / LangGraph (Python)
+
+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.
+
+## 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. Moda's Python SDK
+   ships a LangChain instrument (`Instruments.LANGCHAIN`), and `moda.init()`
+   enables all instruments by default (`instruments=None`). Do not add
+   LangChain callbacks or handler 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.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(`uv.lock` means uv, `poetry.lock` means poetry, otherwise pip):
+
+```bash
+pip install moda-ai
+```
+
+With uv:
+
+```bash
+uv add moda-ai
+```
+
+With poetry:
+
+```bash
+poetry add moda-ai
+```
+
+If `moda-ai` is already a dependency, skip the install.
+
+## Step 3: Initialize Moda once at startup
+
+`moda.init` is synchronous and must run before LangChain models, chains, or
+graphs are constructed. 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.
+
+```python
+import os
+
+import moda
+
+moda.init(os.environ["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 context managers so
+concurrent runs do not leak context into each other:
+
+```python
+from moda import set_conversation_id, set_user_id
+
+with set_conversation_id(f"agent_session_{session_id}"):
+    with set_user_id(user_id):
+        result = agent.invoke({"input": user_query})
+```
+
+For strictly sequential code, the module-level property form is equivalent:
+
+```python
+moda.conversation_id = f"agent_session_{session_id}"
+result = agent.invoke({"input": user_query})
+moda.conversation_id = None
+```
+
+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
+
+Flush pending telemetry before the process exits (short-lived scripts) or on
+shutdown (servers):
+
+```python
+moda.flush()
+```
+
+## 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-python-openai/EXAMPLE.md

@@ -0,0 +1,65 @@
+# Golden reference: FastAPI + OpenAI SDK + Moda
+
+The complete finished integration for a minimal FastAPI chat service that
+calls the OpenAI SDK directly. Match this structure; adapt names to the
+target repository.
+
+## app/main.py
+
+```python
+import os
+from contextlib import asynccontextmanager
+
+import moda
+from fastapi import FastAPI
+from moda import set_conversation_id, set_user_id
+from openai import OpenAI
+from pydantic import BaseModel
+
+# Initialize Moda before creating any LLM client so instrumentation is
+# active. After this, every chat.completions.create call is captured
+# automatically.
+moda.init(os.environ["MODA_API_KEY"])
+
+client = OpenAI()
+
+
+@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.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": request.message}],
+            )
+    return {"reply": response.choices[0].message.content}
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to the project dependencies.
+- One `moda.init` call added at module import time, before `OpenAI()` is
+  constructed.
+- The handler wraps its existing OpenAI call in the scoped context managers;
+  the `chat.completions.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.

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

@@ -0,0 +1,151 @@
+---
+id: integration-python-openai
+name: "Integrate Moda with the OpenAI SDK (Python)"
+version: 1.0.0
+category: integration
+targets:
+  language: python
+  frameworks: []
+  providers:
+    - openai
+sdk_package: moda-ai
+summary: "Auto-instrument openai client calls with Moda in a Python app; no per-call changes required."
+---
+
+# Integrate Moda with the OpenAI SDK (Python)
+
+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.
+
+## 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 `OpenAI()` from the `openai` package.
+
+- If the OpenAI calls go through a wrapper framework instead (LangChain,
+  CrewAI, the Claude Agent SDK, or similar), 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
+  `app/llm.py` 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
+(`uv.lock` means uv, `poetry.lock` means poetry, otherwise pip):
+
+```bash
+pip install moda-ai
+```
+
+With uv:
+
+```bash
+uv add moda-ai
+```
+
+With poetry:
+
+```bash
+poetry add moda-ai
+```
+
+If `moda-ai` is already a dependency, skip the install. `moda-ai` includes
+the OpenAI and Anthropic instrumentation packages; nothing else is needed
+for this integration.
+
+## 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 and tool use) is
+captured with no per-call changes.
+
+`moda.init` is synchronous and 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.
+
+```python
+import os
+
+import moda
+from openai import OpenAI
+
+moda.init(os.environ["MODA_API_KEY"])
+
+client = OpenAI()
+```
+
+For web frameworks, initialize at import time of the application module (as
+above) so the client-creation ordering holds; requirement: `moda.init` runs
+before any `OpenAI()` construction.
+
+## 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 module-level properties:
+
+```python
+moda.conversation_id = f"session_{session_id}"
+moda.user_id = user_id
+```
+
+For concurrent request handlers (any web server), use the scoped context
+managers so overlapping requests do not leak context into each other:
+
+```python
+from moda import set_conversation_id, set_user_id
+
+with set_conversation_id(f"session_{session_id}"):
+    with set_user_id(user_id):
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": user_message}],
+        )
+```
+
+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
+
+Flush pending telemetry before the process exits (short-lived scripts) or on
+shutdown (servers):
+
+```python
+moda.flush()
+```
+
+## 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/dist/init/detect.d.ts

@@ -1,9 +0,0 @@
-export interface ProjectInfo {
-    language: 'typescript' | 'python' | null;
-    packageManager: string | null;
-    llmProviders: string[];
-}
-export declare function detectProject(): Promise<ProjectInfo>;
-export declare function installSDK(project: ProjectInfo): Promise<boolean>;
-export declare function getInitSnippet(project: ProjectInfo): string;
-//# sourceMappingURL=detect.d.ts.map

package/dist/init/detect.js

@@ -1,179 +0,0 @@
-// src/init/detect.ts — Project detection and SDK installation
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { select, confirm } from '@inquirer/prompts';
-const LOCKFILE_TO_PM = {
-    'package-lock.json': 'npm',
-    'yarn.lock': 'yarn',
-    'pnpm-lock.yaml': 'pnpm',
-    'bun.lockb': 'bun',
-    'bun.lock': 'bun',
-    'poetry.lock': 'poetry',
-    'uv.lock': 'uv',
-};
-const INSTALL_COMMANDS = {
-    npm: 'npm install moda-ai',
-    yarn: 'yarn add moda-ai',
-    pnpm: 'pnpm add moda-ai',
-    bun: 'bun add moda-ai',
-    pip: 'pip install moda-ai',
-    poetry: 'poetry add moda-ai',
-    uv: 'uv add moda-ai',
-};
-const LLM_PATTERNS = [
-    { pattern: /from openai|import openai|require\(['"]openai['"]\)/i, name: 'OpenAI' },
-    { pattern: /from anthropic|import.*@anthropic-ai\/sdk|require\(['"]@anthropic-ai\/sdk['"]\)/i, name: 'Anthropic' },
-    { pattern: /from ai |import.*@ai-sdk|require\(['"](ai|@ai-sdk)/i, name: 'Vercel AI SDK' },
-    { pattern: /from langchain|import.*langchain/i, name: 'LangChain' },
-    { pattern: /from claude_agent_sdk|import.*claude.agent/i, name: 'Claude Agent SDK' },
-];
-export async function detectProject() {
-    const cwd = process.cwd();
-    const hasPackageJson = existsSync(join(cwd, 'package.json'));
-    const hasPython = existsSync(join(cwd, 'pyproject.toml')) ||
-        existsSync(join(cwd, 'requirements.txt')) ||
-        existsSync(join(cwd, 'Pipfile'));
-    let language = null;
-    if (hasPackageJson && hasPython) {
-        language = await select({
-            message: 'Both TypeScript and Python detected. Which to configure?',
-            choices: [
-                { name: 'TypeScript / JavaScript', value: 'typescript' },
-                { name: 'Python', value: 'python' },
-            ],
-        });
-    }
-    else if (hasPackageJson) {
-        language = 'typescript';
-    }
-    else if (hasPython) {
-        language = 'python';
-    }
-    // Detect package manager
-    let packageManager = null;
-    if (language === 'typescript') {
-        for (const [lockfile, pm] of Object.entries(LOCKFILE_TO_PM)) {
-            if (existsSync(join(cwd, lockfile))) {
-                packageManager = pm;
-                break;
-            }
-        }
-        // No lockfile — detect which package manager is actually installed
-        if (!packageManager) {
-            for (const pm of ['bun', 'pnpm', 'yarn', 'npm']) {
-                try {
-                    execSync(`${pm} --version`, { stdio: 'pipe' });
-                    packageManager = pm;
-                    break;
-                }
-                catch {
-                    // not installed
-                }
-            }
-            if (!packageManager)
-                packageManager = 'npm';
-        }
-    }
-    else if (language === 'python') {
-        if (existsSync(join(cwd, 'poetry.lock'))) {
-            packageManager = 'poetry';
-        }
-        else if (existsSync(join(cwd, 'uv.lock'))) {
-            packageManager = 'uv';
-        }
-        else {
-            packageManager = 'pip';
-        }
-    }
-    // Detect LLM providers (shallow scan)
-    const llmProviders = detectLLMProviders(cwd, language);
-    return { language, packageManager, llmProviders };
-}
-function detectLLMProviders(cwd, language) {
-    if (!language)
-        return [];
-    const providers = new Set();
-    const extensions = language === 'typescript' ? ['.ts', '.tsx', '.js', '.jsx', '.mjs'] : ['.py'];
-    const dirs = ['src', 'app', 'lib', '.'];
-    for (const dir of dirs) {
-        const dirPath = join(cwd, dir);
-        if (!existsSync(dirPath))
-            continue;
-        try {
-            const files = readdirSync(dirPath, { withFileTypes: true });
-            for (const file of files) {
-                if (!file.isFile())
-                    continue;
-                if (!extensions.some((ext) => file.name.endsWith(ext)))
-                    continue;
-                try {
-                    const content = readFileSync(join(dirPath, file.name), 'utf8');
-                    for (const { pattern, name } of LLM_PATTERNS) {
-                        if (pattern.test(content)) {
-                            providers.add(name);
-                        }
-                    }
-                }
-                catch {
-                    // Skip unreadable files
-                }
-            }
-        }
-        catch {
-            // Skip unreadable dirs
-        }
-    }
-    return Array.from(providers);
-}
-export async function installSDK(project) {
-    if (!project.packageManager)
-        return false;
-    const command = INSTALL_COMMANDS[project.packageManager];
-    if (!command)
-        return false;
-    const shouldInstall = await confirm({
-        message: `Install moda-ai SDK? (${command})`,
-        default: true,
-    });
-    if (!shouldInstall) {
-        console.log(`  Skipped. Run manually: ${command}`);
-        return false;
-    }
-    console.log(`  Installing moda-ai (${project.packageManager})...`);
-    try {
-        execSync(command, { cwd: process.cwd(), stdio: 'pipe' });
-        console.log('  Installed moda-ai');
-        return true;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`  Warning: SDK install failed: ${message}`);
-        console.error(`  Run manually: ${command}`);
-        return false;
-    }
-}
-export function getInitSnippet(project) {
-    if (project.language === 'typescript') {
-        return `
-    import { Moda } from 'moda-ai';
-
-    await Moda.init(process.env.MODA_API_KEY!);
-    // Moda.conversationId = 'your-session-id';
-    // ... your LLM calls are auto-instrumented ...
-    await Moda.flush();
-`;
-    }
-    if (project.language === 'python') {
-        return `
-    import moda
-
-    moda.init()  # reads MODA_API_KEY from env
-    # moda.conversation_id = 'your-session-id'
-    # ... your LLM calls are auto-instrumented ...
-    moda.flush()
-`;
-    }
-    return '';
-}
-//# sourceMappingURL=detect.js.map