@moda-ai/cli 1.11.0 → 1.12.0

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

@@ -0,0 +1,153 @@
+---
+id: integration-python-anthropic
+name: "Integrate Moda with the Anthropic SDK (Python)"
+version: 1.0.0
+category: integration
+targets:
+  language: python
+  frameworks: []
+  providers:
+    - anthropic
+sdk_package: moda-ai
+summary: "Auto-instrument anthropic client calls with Moda in a Python app; no per-call changes required."
+---
+
+# Integrate Moda with the Anthropic 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/anthropic 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 Anthropic client is the integration surface
+
+Find the real LLM call sites: `client.messages.create(...)` or
+`client.messages.stream(...)` on a client constructed with `Anthropic()`
+from the `anthropic` package.
+
+- If the Anthropic 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 Anthropic 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 Anthropic 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
+`messages.create` / `messages.stream` call (including extended thinking and
+tool use) is captured with no per-call changes.
+
+`moda.init` is synchronous and must run before the Anthropic 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 anthropic import Anthropic
+
+moda.init(os.environ["MODA_API_KEY"])
+
+client = Anthropic()
+```
+
+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 `Anthropic()` 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.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            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 Anthropic client is created.

package/skills/integration/integration-python-claude-agent-sdk/EXAMPLE.md

@@ -0,0 +1,61 @@
+# Golden reference: Claude Agent SDK + Moda
+
+The complete finished integration for a minimal Claude Agent SDK script.
+Match this structure; adapt names to the target repository.
+
+## agent.py
+
+```python
+import asyncio
+import os
+
+import moda
+from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+
+# Initialize Moda before creating the ClaudeSDKClient. When
+# moda-claude-agent-sdk is installed, the instrumentor is enabled
+# automatically.
+moda.init(os.environ["MODA_API_KEY"])
+
+# Explicit conversation and user context so all turns group together.
+moda.conversation_id = "session_123"
+moda.user_id = "user_456"
+
+
+async def main():
+    options = ClaudeAgentOptions(model="claude-sonnet-4-20250514")
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("What is the capital of France?")
+
+        # Consume the full stream: token usage arrives in the final
+        # ResultMessage.
+        async for msg in client.receive_response():
+            print(msg)
+
+
+asyncio.run(main())
+
+# Flush pending telemetry before exit.
+moda.flush()
+```
+
+## Dependencies
+
+Both packages are required; `moda-claude-agent-sdk` is not included with
+`moda-ai`:
+
+```bash
+pip install moda-ai moda-claude-agent-sdk claude-agent-sdk
+```
+
+## What changed, and what did not
+
+- `moda-ai` and `moda-claude-agent-sdk` added to the project dependencies.
+- One `moda.init` call added at startup, before `ClaudeSDKClient` is
+  constructed.
+- Conversation and user ids set before the agent runs.
+- The agent code itself is unchanged; the instrumentor wraps
+  `ClaudeSDKClient` automatically.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

package/skills/integration/integration-python-claude-agent-sdk/SKILL.md

@@ -0,0 +1,129 @@
+---
+id: integration-python-claude-agent-sdk
+name: "Integrate Moda with the Claude Agent SDK (Python)"
+version: 1.0.0
+category: integration
+targets:
+  language: python
+  frameworks:
+    - claude-agent-sdk
+  providers: []
+sdk_package: moda-claude-agent-sdk
+summary: "Instrument Claude Agent SDK sessions (ClaudeSDKClient) with Moda via the dedicated moda-claude-agent-sdk instrumentor."
+---
+
+# Integrate Moda with the Claude Agent 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/claude-agent-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.
+
+## Why this integration needs a separate package
+
+The Claude Agent SDK spawns Claude as a subprocess rather than making direct
+Anthropic API calls, so standard Anthropic API instrumentation does not
+fire. The `moda-claude-agent-sdk` package provides a dedicated instrumentor
+that wraps `ClaudeSDKClient` to capture agent-level spans (token usage, tool
+calls, turns, session metadata). The Claude Agent SDK is Python-only; if
+this repository is Node.js, stop and report — there is no Node.js support.
+
+## Step 1: Find the Claude Agent SDK call sites
+
+Find where the application constructs `ClaudeSDKClient` (from
+`claude_agent_sdk`). If there are none, stop and report: this skill only
+applies to apps using the Claude Agent SDK.
+
+## Step 2: Install the SDK packages
+
+Install both `moda-ai` and `moda-claude-agent-sdk` with the package manager
+this repository already uses (`uv.lock` means uv, `poetry.lock` means
+poetry, otherwise pip). `moda-claude-agent-sdk` is NOT included with
+`moda-ai`; it must be installed separately:
+
+```bash
+pip install moda-ai moda-claude-agent-sdk
+```
+
+With uv:
+
+```bash
+uv add moda-ai moda-claude-agent-sdk
+```
+
+With poetry:
+
+```bash
+poetry add moda-ai moda-claude-agent-sdk
+```
+
+If both are already dependencies, skip the install.
+
+## Step 3: Initialize Moda once at startup, before the client is created
+
+`moda.init` is synchronous, automatically enables the Claude Agent SDK
+instrumentor when `moda-claude-agent-sdk` is installed, and must run before
+any `ClaudeSDKClient` is constructed. 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: Set conversation and user context
+
+Set a stable conversation id (and user id when one user can be identified)
+before running the agent, so all turns of a session group together:
+
+```python
+moda.conversation_id = f"session_{session_id}"
+moda.user_id = user_id
+```
+
+Reuse the session identifier the app already has. If no session identifier
+exists anywhere, stop and report; do not invent one.
+
+## Step 5: Consume the full response stream
+
+Token usage comes from the `ResultMessage` at the end of the stream. Verify
+the code consumes the full async generator from `receive_response()`; if it
+breaks out early, token counts will be missing. Do not restructure working
+code — just confirm the stream is fully consumed, and report if it is not.
+
+## Step 6: Flush before exit
+
+Flush pending telemetry before the process exits:
+
+```python
+moda.flush()
+```
+
+## Step 7: 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-claude-agent-sdk` is installed (it is separate from `moda-ai`), that
+`moda.init()` runs before `ClaudeSDKClient` is created, and that
+`MODA_API_KEY` is available in the runtime environment.

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

@@ -0,0 +1,46 @@
+# Golden reference: generic Python app + Moda
+
+The complete finished integration for a small Python chat script whose LLM
+calls go through the `openai` client (automatically instrumented). Match
+this structure; adapt names to the target repository.
+
+## app/main.py
+
+```python
+import os
+
+import moda
+from moda import set_conversation_id, set_user_id
+from openai import OpenAI
+
+# Initialize Moda once, before any LLM client is created.
+moda.init(os.environ["MODA_API_KEY"])
+
+client = OpenAI()
+
+
+def answer(session_id: str, user_id: str, message: str) -> str:
+    # Scoped context: safe under concurrent callers.
+    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": message}],
+            )
+    return response.choices[0].message.content
+
+
+print(answer("demo-session", "user-123", "Hello!"))
+
+# Flush pending telemetry before exit.
+moda.flush()
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to the project dependencies.
+- One `moda.init` call added at startup, before any LLM client is created.
+- Call sites through instrumented clients are unchanged; only context
+  scoping was added around them.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

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

@@ -0,0 +1,146 @@
+---
+id: integration-python-generic
+name: "Integrate the Moda SDK (Python, any provider)"
+version: 1.0.0
+category: integration
+targets:
+  language: python
+  frameworks: []
+  providers: []
+sdk_package: moda-ai
+summary: "General Moda SDK integration for a Python app when no specific framework or provider skill matches."
+---
+
+# Integrate the Moda SDK (Python, any provider)
+
+This is the general Python integration path, used when no framework- or
+provider-specific skill matches. 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 a 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.
+
+## Step 1: Find the real LLM call sites and pick the right surface
+
+Search the repository for LLM calls and classify them:
+
+- Calls through an instrumented provider or framework: automatically
+  captured once Moda is initialized (Step 3); no per-call changes. The
+  Python SDK's `Instruments` set covers providers including OpenAI,
+  Anthropic, Cohere, Mistral, Groq, Ollama, Bedrock, VertexAI, and
+  frameworks including LangChain, LlamaIndex, Haystack, and CrewAI (full
+  table: https://docs.moda.dev/ingestion/moda-sdk). OpenAI-compatible
+  gateways (for example OpenRouter used through the `openai` client with a
+  custom `base_url`) count as OpenAI here.
+- Calls through LangChain or the Claude Agent SDK: stop — use the dedicated
+  skill instead; never instrument the underlying provider client when a
+  wrapper framework is in use.
+- Direct HTTP calls to a provider outside the instruments table: the Python
+  SDK does not capture these automatically. Note them in your report and
+  point the user at https://docs.moda.dev/ingestion/direct-api; do not
+  build a custom ingestion path yourself.
+
+If the repository has no LLM 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.
+
+## Step 3: Initialize Moda once at startup
+
+`moda.init` is synchronous and must run once, at startup, before any LLM
+client is created. 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: 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.
+If one user reaches the same agent through several channels, use the same
+user id across channels.
+
+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 = make_llm_call(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 first LLM client is created.

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

@@ -0,0 +1,63 @@
+# Golden reference: Python LangChain agent + Moda
+
+The complete finished integration for a minimal LangChain app. Match this
+structure; adapt names to the target repository. Note what is absent: no
+LangChain callbacks or handler classes for Moda — `moda.init()` enables all
+instruments (including LangChain) by default, and the only per-run change is
+the explicit conversation id wrapper.
+
+## app/agent.py
+
+```python
+import os
+
+import moda
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_openai import ChatOpenAI
+from moda import set_conversation_id, set_user_id
+
+# Initialize Moda once, before LangChain models are constructed. moda.init
+# enables all instruments (including LangChain) by default.
+moda.init(os.environ["MODA_API_KEY"])
+
+model = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant."),
+    ("human", "{input}"),
+])
+chain = prompt | model
+
+
+def run_agent(session_id: str, user_id: str, user_query: str):
+    # Explicit conversation id around the whole run: every internal LLM call
+    # made during this invocation shares it. Automatic detection does NOT
+    # work for agent frameworks.
+    with set_conversation_id(f"agent_session_{session_id}"):
+        with set_user_id(user_id):
+            return chain.invoke({"input": user_query})
+```
+
+## app/main.py
+
+```python
+import moda
+
+from app.agent import run_agent
+
+result = run_agent("demo-session", "user-123", "What is Python?")
+print(result.content)
+
+# Flush pending telemetry before exit.
+moda.flush()
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to the project dependencies.
+- One `moda.init` call added at startup, before any LangChain model is
+  constructed.
+- Each agent/chain entry point is wrapped in the scoped context managers
+  with an explicit conversation id; the LangChain code itself is unchanged.
+- No LangChain callbacks or handler classes were added for Moda.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.