@respan/cli 0.14.2 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@respan/cli",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "Respan CLI - manage your LLM observability from the command line",
   "type": "module",
   "main": "dist/index.js",
@@ -17,9 +17,8 @@
     "directory": "javascript-sdks/respan-cli"
   },
   "scripts": {
-    "build": "npm run generate:skill-refs && tsc && npm run build:hooks",
+    "build": "npm run clean && tsc && npm run build:hooks",
     "build:hooks": "node -e \"const{build}=require('esbuild');const hooks=['claude-code','codex-cli','gemini-cli'];Promise.all(hooks.map(h=>build({entryPoints:['src/hooks/'+h+'.ts'],bundle:true,platform:'node',target:'node18',format:'cjs',outfile:'dist/hooks/'+h+'.cjs',external:[]}))).then(()=>console.log('Hooks bundled.'))\"",
-    "generate:skill-refs": "node scripts/embed-skill-refs.mjs",
     "test": "npm run build && node --test tests/*.test.mjs",
     "clean": "rm -rf dist",
     "dev": "node --loader ts-node/esm bin/dev.js",

package/dist/lib/skill-content.d.ts

@@ -1 +0,0 @@
-export declare function getSkillMd(): string;

package/dist/lib/skill-content.js

@@ -1,16 +0,0 @@
-// Skill content assembly.
-//
-// All skill markdown (the SKILL.md routing index and every reference) is now
-// authored as markdown under skills/ and embedded into skill-refs.generated.ts
-// by scripts/embed-skill-refs.mjs. This module only wraps the routing index in
-// the skill frontmatter that coding agents expect.
-import { SKILL_MD } from './skill-refs.generated.js';
-export function getSkillMd() {
-    return `---
-name: respan
-description: Use Respan for tracing, evals, prompts, gateway, and SDK setup. Covers CLI commands, SDK instrumentation, and platform features.
-user-invocable: true
----
-
-${SKILL_MD}`;
-}

package/dist/lib/skill-refs.generated.d.ts

@@ -1,6 +0,0 @@
-export declare const SKILL_MD = "# Respan\n\nUse the Respan CLI and SDK for LLM observability \u2014 tracing, evals, prompts, datasets, and gateway routing.\n\n## When To Use\n\n- **Set up tracing** (instrument your app to capture LLM calls \u2014 install + decorators, propagation, processors) \u2192 read [references/tracing.md](references/tracing.md)\n- **Set up gateway** (route LLM calls through the Respan proxy \u2014 wiring + model switching, fallbacks, caching) \u2192 read [references/gateway.md](references/gateway.md)\n- **Prompt management** (create, version, deploy) \u2192 read [references/prompts.md](references/prompts.md)\n- **Evals** (datasets, evaluators, experiments) \u2192 read [references/evals.md](references/evals.md)\n- **Monitors & automation** (alerts, online evals, webhooks) \u2192 read [references/monitors.md](references/monitors.md)\n\nTracing and gateway are separate setups \u2014 configure one at a time, never both in the same pass.\n\n## Core Principles\n\n1. **Read the reference first.** Each reference file has the exact setup steps, API patterns, MCP tools, and CLI commands.\n2. **Use MCP tools** for platform operations (prompts, datasets, evaluators, experiments, traces, logs).\n3. **Use CLI** when MCP is not available: `respan traces list`, `respan prompts list`, etc.\n4. **Fetch docs** for integration-specific details not covered in references.\n\n## Quick Reference\n\n| Task | Reference / Command |\n|------|--------------------|\n| Set up tracing (steps + decorators, propagation) | [references/tracing.md](references/tracing.md) |\n| Set up gateway (steps + features) | [references/gateway.md](references/gateway.md) |\n| Prompt management | [references/prompts.md](references/prompts.md) |\n| Evals & experiments | [references/evals.md](references/evals.md) |\n| Monitors & automation | [references/monitors.md](references/monitors.md) |\n| List traces | `respan traces list --limit 10` |\n| View a trace | `respan traces get <id>` |\n| Check auth | `respan auth status` |\n\n## Documentation Access\n\nAny doc page can be fetched as markdown:\n`https://respan.ai/docs/integrations/openai-sdk.md`\n`https://respan.ai/docs/sdks/typescript-sdk/overview.md`\n\nFull docs index: `https://www.respan.ai/docs/llms.txt`\n\nPlatform: `https://platform.respan.ai`\n";
-export declare const TRACING_MD = "# Tracing\n\nSet up and configure Respan SDK tracing: instrument an app to capture LLM calls as\nstructured traces, then refine with decorators, context propagation, and processors.\n\nThis file covers **both** the initial setup steps and the advanced reference. Tracing\nis a separate setup from the gateway \u2014 do one at a time, never both in the same pass.\n\nDocs: `https://respan.ai/docs/documentation/features/tracing/traces/tracing-sdk.md`\nFull docs index: `https://www.respan.ai/docs/llms.txt`\n\n---\n\n## Setup\n\nUse this section when the user asks to set up Respan tracing in their project.\n\n### Hard Rules\n\n- **Interactive mode:** Ask the user questions when you need input. Do not assume.\n- **Only add Respan code.** Do not refactor or modify unrelated code.\n- **Pin exact versions.** Never use `latest` or unpinned ranges.\n- **Do not guess APIs.** Use only the patterns from the integration docs linked below.\n- **If Respan is already installed/configured, do not duplicate work.** Check for existing `respan` imports first.\n- **Read the code before proposing changes.** Understand the actual workflow, not just the dependencies.\n\nThe API key is stored in `.env` as `RESPAN_API_KEY`.\n\n### 1. Ask first: Auto or Full?\n\n**Before analyzing anything, ask the user which setup they want.** This is the first question \u2014 the two branches diverge immediately.\n\n1. **Auto** \u2014 the fastest working path. For a supported direct SDK, install the core SDK and add `Respan()` (one line) to capture flat LLM spans. The Vercel AI SDK is an explicit-only exception: Auto must also add `@respan/instrumentation-vercel` and `VercelAIInstrumentor`, but still adds no decorators or manual workflow wrappers. Best for a quick start or a live demo: traces flowing in under two minutes.\n2. **Full** \u2014 structured setup. Adds framework-specific instrumentation and/or workflow structure on top:\n   - **Explicit instrumentor** \u2014 for agent frameworks (LangChain, CrewAI, OpenAI Agents, Claude Agent SDK, LlamaIndex, Haystack, \u2026) so the framework's agent / tool / chain structure is captured.\n   - **Decorators** \u2014 wrap the user's own functions with `@workflow` / `@task` for nested spans.\n\nFollow only the branch the user picks; skip the other one.\n\n> **Frameworks under Auto:** Auto normally does not install a framework instrumentor. If the app uses a framework (LangChain, CrewAI, an agents SDK), Auto captures only spans from a supported underlying direct SDK. **Direct Vercel AI SDK usage is different:** the Respan facade deliberately does not auto-discover it, and AI SDK calls are not covered by core-only setup. If the project directly calls the `ai` package and no higher-level framework owns its AI SDK telemetry, follow the Vercel branch below in both Auto and Full.\n\n---\n\n### Auto path\n\n**A1. Detect language, package manager, and integration** \u2014 inspect `package.json` and source imports for JS/TS, or `pyproject.toml` / `requirements.txt` for Python. Before choosing core-only initialization, check whether the JS/TS project directly imports and calls the `ai` package (Vercel AI SDK). Apply the priority rule first: if a higher-level integration owns AI SDK telemetry, use that integration instead of also adding Vercel instrumentation. For example, an Eve app must use `EveInstrumentor`; do not activate `VercelAIInstrumentor` or another `@ai-sdk/otel` bridge alongside it.\n\n**A2. Install the core SDK** (pin the exact current version):\n```bash\n# Python\npip install respan-ai\n\n# TypeScript\nnpm install @respan/respan\n```\n\nIf the project uses Vercel AI SDK directly, fetch and follow its [integration doc](https://respan.ai/docs/integrations/vercel-ai-sdk.md), and pin exact compatible versions of:\n\n- `@respan/respan`\n- `@respan/instrumentation-vercel`\n- `@ai-sdk/otel` when the installed `ai` major version is 7 (AI SDK 4 through 6 do not require this adapter)\n\n**A3. Add initialization code** at the top of the entrypoint, before any LLM client is created:\n```python\n# Python\nfrom respan import Respan\nRespan()\n```\n```typescript\n// TypeScript\nimport { Respan } from \"@respan/respan\";\nconst respan = new Respan();\nawait respan.initialize();\n```\n\nFor a Vercel AI SDK project, use its required explicit instrumentor instead of the core-only TypeScript initialization above:\n\n```typescript\nimport { Respan } from \"@respan/respan\";\nimport { VercelAIInstrumentor } from \"@respan/instrumentation-vercel\";\n\nconst respan = new Respan({\n  instrumentations: [new VercelAIInstrumentor()],\n});\nawait respan.initialize();\n```\n\nIf the project already has a `Respan` instance, merge `VercelAIInstrumentor` into its existing `instrumentations` list instead of creating a second instance. Preserve other explicit instrumentors that cover genuinely separate direct-SDK calls; do not add a provider instrumentor solely for calls made through Vercel AI SDK.\n\nIf the application already registers its own compatible `@ai-sdk/otel` integration, construct `VercelAIInstrumentor({ autoRegisterAISDKTelemetry: false })` so Respan translates the spans without claiming a second registration. For Next.js, follow the integration doc's root `instrumentation.ts` `register()` placement and `serverExternalPackages` configuration; keep tracing on the server runtime, not an Edge or browser path.\n\nAlso enable Vercel telemetry on every AI SDK operation. Use the option that matches the installed AI SDK major version:\n\n```typescript\n// AI SDK 7\ntelemetry: { isEnabled: true }\n\n// AI SDK 4 through 6\nexperimental_telemetry: { isEnabled: true }\n```\n\nDo **not** add decorators. For non-Vercel Auto setups, do not add a framework instrumentor. For Vercel, keep the required `VercelAIInstrumentor` and go straight to **Verify**.\n\n---\n\n### Full path\n\nThe rest of this section is the **Full** path \u2014 follow it only if the user chose Full. It adds an explicit framework instrumentor and/or decorators on top of the core SDK.\n\n#### 1. Analyze the Project\n\n**1a. Detect language and package manager:**\n- Check `package.json` (JS/TS) or `pyproject.toml` / `requirements.txt` (Python)\n- Detect package manager from lock files\n\n**1b. Detect libraries in priority order:**\n\nCheck higher-priority categories first. If a match is found, use that instrumentation \u2014 do NOT also add lower-level SDK instrumentation.\n\n**Priority 1 \u2014 Agent Frameworks & High-Level SDKs:**\n\n| Library | Python package | JS/TS package | Respan instrumentation (Python) | Respan instrumentation (JS/TS) | Docs |\n|---------|---------------|---------------|--------------------------------|-------------------------------|------|\n| Vercel AI SDK | \u2014 | `ai` | \u2014 | `@respan/instrumentation-vercel` | [docs](https://respan.ai/docs/integrations/vercel-ai-sdk.md) |\n| OpenAI Agents SDK | `openai-agents` | `@openai/agents` | `respan-instrumentation-openai-agents` | `@respan/instrumentation-openai-agents` | [docs](https://respan.ai/docs/integrations/openai-agents-sdk.md) |\n| Claude Agent SDK | `claude-agent-sdk` | \u2014 | `respan-instrumentation-claude-agent-sdk` | \u2014 | [docs](https://respan.ai/docs/integrations/claude-agents-sdk.md) |\n| Pi coding agent | \u2014 | `@earendil-works/pi-coding-agent` | \u2014 | `@respan/instrumentation-pi` | [README](https://github.com/RespanAI/respan/tree/main/javascript-sdks/instrumentations/respan-instrumentation-pi) |\n| Pydantic AI | `pydantic-ai` | \u2014 | `respan-instrumentation-pydantic-ai` | \u2014 | [docs](https://respan.ai/docs/integrations/pydantic-ai.md) |\n| LangChain | `langchain` | `langchain` | `respan-instrumentation-langchain` | `@respan/instrumentation-langchain` | [docs](https://respan.ai/docs/integrations/langchain.md) |\n| LangGraph | `langgraph` | `@langchain/langgraph` | `respan-instrumentation-langchain` | `@respan/instrumentation-langchain` | [docs](https://respan.ai/docs/integrations/langgraph.md) |\n| CrewAI | `crewai` | \u2014 | `respan-instrumentation-crewai` | \u2014 | [docs](https://respan.ai/docs/integrations/crewai.md) |\n| LlamaIndex | `llama-index` | \u2014 | `respan-instrumentation-llama-index` | \u2014 | [docs](https://respan.ai/docs/integrations/llama-index.md) |\n| Haystack | `haystack-ai` | \u2014 | `respan-instrumentation-haystack` | \u2014 | [docs](https://respan.ai/docs/integrations/haystack.md) |\n| Mastra | \u2014 | `mastra` | \u2014 | via OTEL | [docs](https://respan.ai/docs/integrations/mastra.md) |\n| Google ADK | `google-adk` | \u2014 | `respan-instrumentation-google-adk` | \u2014 | [docs](https://respan.ai/docs/integrations/google-adk.md) |\n\nIf a Priority 1 framework is found, use its instrumentation. Do NOT also add Priority 2 instrumentation for the same provider.\n\nFor direct Vercel AI SDK usage, the explicit `VercelAIInstrumentor` and per-operation telemetry option are required in both Auto and Full. Never replace them with core-only `new Respan()` setup, and never stack them with a higher-level integration that already owns AI SDK telemetry.\n\n**LangChain / LangGraph setup differs by language** (one package covers both frameworks: `respan-instrumentation-langchain` / `@respan/instrumentation-langchain`). In **Python**, pass `LangChainInstrumentor()` to `Respan(instrumentations=[...])` \u2014 it patches the LangChain and LangGraph callback managers globally on init, so every chain, graph, node, LLM, tool, and retriever run is traced **automatically with no per-call setup**. `add_respan_callback(config=...)` is optional and only labels a run with a name, tags, or metadata. In **TypeScript**, create a `LangChainInstrumentor`, pass it to `new Respan({ instrumentations: [...] })`, **and** attach `instrumentor.addCallback(...)` to the **outermost** chain or graph invocation (`.invoke()` / `.stream()`, not inside a node \u2014 LangChain/LangGraph propagate it to nested runs); the TypeScript instrumentor does **not** patch globally, so without the callback no spans are emitted. (The other Priority-1 frameworks use the standard `Respan(instrumentations=[XInstrumentor()])` plugin pattern.)\n\n**Pi coding agent (TypeScript only)** has no global patch point, so the instrumentor must be wired into the session. Create `new PiInstrumentor()` from `@respan/instrumentation-pi`, pass it to `new Respan({ instrumentations: [...] })`, and either pass `instrumentor.extension` via `new DefaultResourceLoader({ cwd: process.cwd(), agentDir: getAgentDir(), extensionFactories: [instrumentor.extension] })` (pi requires `cwd` and `agentDir`; `getAgentDir` is exported by `@earendil-works/pi-coding-agent`) before `createAgentSession(...)`, or call `instrumentor.attach(session)` on an existing `AgentSession`. By default every run of a pi session joins one multi-root trace whose id is derived from the pi session id (`traceScope: \"session\"`), so a session resumed across processes and pauses stays one trace; `traceScope: \"run\"` makes each agent run its own trace instead. All runs of a pi session share its thread id either way. For always-on agent fleets, pair it with a local OpenTelemetry Collector persistent queue (see Delivery Guarantees below) so spans survive Respan outages and restarts without a local journal. For the interactive `pi` CLI, run `respan integrate pi` instead \u2014 it installs the `@respan/instrumentation-pi` pi package (a pi extension) and writes a non-secret `respan.json` (`--trace-scope run` for one trace per prompt instead of one per session).\n\n**Priority 2 \u2014 Direct LLM SDKs** (only if no P1 framework covers this provider):\n\nThe integrations listed for each language are **auto-instrumented** with `Respan()` / `new Respan()`. The application still provides the provider SDK; the matching first-party instrumentation adapter is bundled by the Respan facade. A dash means that language currently requires an explicit instrumentation package and instrumentor.\n\n| Library | Python SDK (auto) | JS/TS SDK (auto) | Docs |\n|---------|-------------------|------------------|------|\n| OpenAI SDK | `openai` | `openai` | [docs](https://respan.ai/docs/integrations/openai-sdk.md) |\n| Anthropic SDK | `anthropic` | `@anthropic-ai/sdk` | [docs](https://respan.ai/docs/integrations/anthropic.md) |\n| Azure OpenAI | `openai` (Azure config) | `openai` (Azure client) | [docs](https://respan.ai/docs/integrations/providers/azure.md) |\n| Google Vertex AI | `google-cloud-aiplatform` | `@google-cloud/vertexai` | [docs](https://respan.ai/docs/integrations/vertex-ai.md) |\n| Google GenAI | `google-genai` | \u2014 | [docs](https://respan.ai/docs/integrations/google-genai.md) |\n| AWS Bedrock | `boto3` | `@aws-sdk/client-bedrock-runtime` | [docs](https://respan.ai/docs/integrations/aws-bedrock.md) |\n| Cohere | \u2014 | `cohere-ai` | [docs](https://respan.ai/docs/integrations/providers/cohere.md) |\n| Together AI | `together` | `together-ai` | [docs](https://respan.ai/docs/integrations/together-ai.md) |\n| OpenRouter | \u2014 | `@openrouter/sdk` | [docs](https://respan.ai/docs/integrations/providers/openrouter.md) |\n| Writer | \u2014 | `writer-sdk` | [docs](https://respan.ai/docs/integrations/writer.md) |\n| Ollama | `ollama` | \u2014 | [docs](https://respan.ai/docs/integrations/ollama.md) |\n\n**Note:** LLM wrappers such as Python LiteLLM stay explicit-only to avoid overlapping provider spans. See the [LiteLLM guide](https://respan.ai/docs/integrations/litellm.md) for its explicit setup.\n\n**1c. Read the actual code and understand the workflow:**\n\nThis is the most important step. Read the entrypoint and all files that make LLM calls. Map out:\n\n- What is the **overall workflow**? (e.g. \"user sends question \u2192 retrieve context \u2192 generate answer \u2192 format response\")\n- What are the **individual steps/tasks**? (e.g. \"embed query\", \"search DB\", \"call GPT\", \"parse output\")\n- Are there **agent loops**? (e.g. a loop that calls tools until done)\n- Are there **tool calls**? (e.g. functions the LLM invokes)\n\n#### 2. Propose an Implementation Plan\n\nPresent the user with a concrete plan before making any changes. The plan should include:\n\n**a) Packages to install** \u2014 core SDK + instrumentation package (with exact versions)\n\n**b) Initialization code** \u2014 where to add it (which file, which line)\n\n**c) Workflow structure** \u2014 how to wrap the existing code:\n\nFor **agent frameworks** (Priority 1): The framework instrumentation auto-captures the workflow structure. Usually just need init code, no manual wrapping needed. Fetch and follow the integration doc.\n\nFor **direct LLM SDKs** (Priority 2): Individual LLM calls will be auto-traced as flat spans. Propose wrapping the logical workflow with Respan decorators/wrappers to get structured nested traces:\n\nTypeScript example:\n```typescript\n// Before: flat traces \u2014 each LLM call is an isolated span\nconst outline = await openai.chat.completions.create({...});\nconst draft = await openai.chat.completions.create({...});\n\n// After: structured traces \u2014 nested spans showing the workflow\nconst result = await withWorkflow({ name: \"write_article\" }, async () => {\n  const outline = await withTask({ name: \"generate_outline\" }, async () => {\n    return await openai.chat.completions.create({...});\n  });\n  const draft = await withTask({ name: \"write_draft\" }, async () => {\n    return await openai.chat.completions.create({...});\n  });\n  return draft;\n});\n```\n\nPython example:\n```python\n# Before: flat traces\noutline = client.chat.completions.create(...)\ndraft = client.chat.completions.create(...)\n\n# After: structured traces\n@workflow(name=\"write_article\")\ndef write_article(topic):\n    outline = generate_outline(topic)\n    return write_draft(outline)\n\n@task(name=\"generate_outline\")\ndef generate_outline(topic):\n    return client.chat.completions.create(...)\n\n@task(name=\"write_draft\")\ndef write_draft(outline):\n    return client.chat.completions.create(...)\n```\n\nWithin Full, pick what the app needs (they can combine):\n- **Framework detected** \u2192 add its **explicit instrumentor** (or the LangChain callback). The framework auto-captures its agent / tool / chain structure \u2014 usually no manual wrapping needed.\n- **Direct LLM SDK, or you want structure over your own orchestration code** \u2192 add **decorators** (`@workflow` / `@task`) to wrap the logical workflow into nested spans.\n\n(If the user only wanted flat spans with zero code changes, that's the **Auto** path \u2014 go back to it.)\n\nWhen adding decorators:\n- **If multiple independent workflows are detected** (e.g. `writeArticle()`, `summarizeDoc()`, `classifyEmail()`), list them and ask which ones to instrument. Don't assume all of them.\n- **Show the user what the trace will look like** \u2014 describe the span hierarchy:\n```\nworkflow: write_article\n  \u251C\u2500\u2500 task: generate_outline\n  \u2502     \u2514\u2500\u2500 llm: openai.chat (auto-captured)\n  \u2514\u2500\u2500 task: write_draft\n        \u2514\u2500\u2500 llm: openai.chat (auto-captured)\n```\n\nWait for user confirmation before proceeding.\n\n#### 3. Implement\n\n**a) Install packages:**\n\nFor direct LLM SDKs (Priority 2) \u2014 just the core SDK:\n```bash\n# Python\npip install respan-ai\n\n# TypeScript\nnpm install @respan/respan\n```\n\nFor agent frameworks (Priority 1) \u2014 also install the instrumentor. Check the docs link in the table above for the exact packages.\n\n**b) Add initialization code** \u2014 at the top of the entrypoint, before any LLM client is created:\n\nFor **direct LLM SDKs** (auto-instrumented):\n```python\n# Python\nfrom respan import Respan\nRespan()\n```\n```typescript\n// TypeScript\nimport { Respan } from \"@respan/respan\";\nconst respan = new Respan();\nawait respan.initialize();\n```\n\nFor **agent frameworks** (explicit instrumentor \u2014 fetch the docs URL from the table for the exact pattern):\n```python\n# Python example (OpenAI Agents)\nfrom respan import Respan\nfrom respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor\nRespan(instrumentations=[OpenAIAgentsInstrumentor()])\n```\n```typescript\n// TypeScript example (OpenAI Agents)\nimport { Respan } from \"@respan/respan\";\nimport { OpenAIAgentsInstrumentor } from \"@respan/instrumentation-openai-agents\";\nconst respan = new Respan({ instrumentations: [new OpenAIAgentsInstrumentor()] });\nawait respan.initialize();\n```\n\n**c) Add workflow wrappers** \u2014 if the user chose structured traces in the plan.\n\n### Verify (final test \u2014 always run this, both paths)\n\nAs the final step \u2014 for **both** Auto and Full \u2014 **run the user's program once with a small request** and confirm tracing works end to end:\n\n- The app runs without errors\n- A trace appears at https://platform.respan.ai or via `respan traces list --limit 5`\n- If wrappers were added, the trace shows the expected nested span hierarchy\n\nIf no trace appears, the instrumentation isn't taking effect \u2014 debug (init placement, missing `flush()`, wrong entrypoint) and re-run before declaring setup done.\n\n---\n\n## Reference\n\nAdvanced tracing configuration: decorators, context propagation, processors, and span attributes.\n\n### Decorators\n\nWrap functions to create structured span hierarchies. All decorators share the same signature.\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@workflow` / `withWorkflow` | Root span \u2014 top-level pipeline |\n| `@task` / `withTask` | Step within a workflow |\n| `@agent` / `withAgent` | Agent loop span |\n| `@tool` / `withTool` | Tool/function call span |\n\n#### Python\n\n```python\nfrom respan import Respan, workflow, task, agent, tool\n\nRespan()\n\n@workflow(name=\"write_article\")\ndef write_article(topic: str):\n    outline = generate_outline(topic)\n    return write_draft(outline)\n\n@task(name=\"generate_outline\")\ndef generate_outline(topic: str):\n    return client.chat.completions.create(...)\n\n@task(name=\"write_draft\")\ndef write_draft(outline: str):\n    return client.chat.completions.create(...)\n```\n\n#### TypeScript\n\n```typescript\nimport { Respan, withWorkflow, withTask } from \"@respan/respan\";\n\nconst respan = new Respan();\nawait respan.initialize();\n\nconst result = await withWorkflow({ name: \"write_article\" }, async () => {\n  const outline = await withTask({ name: \"generate_outline\" }, async () => {\n    return await client.chat.completions.create({...});\n  });\n  return await withTask({ name: \"write_draft\" }, async () => {\n    return await client.chat.completions.create({...});\n  });\n});\n```\n\n#### Decorator Parameters\n\n```python\n@workflow(\n    name=\"my_workflow\",               # Display name (default: function name)\n    version=1,                        # Version number\n    processors=\"my_processor\",        # Route to specific processor(s)\n    sample_rate=0.5,                  # 0.0-1.0, fraction of spans exported\n    export_filter={                   # Conditional export\n        \"metadata.env\": {\"operator\": \"\", \"value\": \"production\"}\n    },\n)\n```\n\nAll parameters are optional. Without any, the function name is used as the span name.\n\n#### Async Support\n\nDecorators work with `async def`, generators, and async generators automatically.\n\n### Context Propagation\n\nAttach attributes to **all spans** within a scope, including auto-instrumented LLM calls.\n\n#### propagate_attributes\n\n```python\nfrom respan import Respan, propagate_attributes\n\nRespan()\n\nwith propagate_attributes(\n    customer_identifier=\"user_123\",\n    thread_identifier=\"conv_abc\",\n    environment=\"production\",\n    metadata={\"plan\": \"pro\", \"team\": \"search\"},\n):\n    # All spans here (including auto-instrumented OpenAI calls) get these attributes\n    result = run_pipeline()\n```\n\n##### Available attributes\n\n| Attribute | Description |\n|-----------|-------------|\n| `customer_identifier` | User/customer ID \u2014 enables per-user analytics |\n| `customer_email` | Customer email |\n| `customer_name` | Customer display name |\n| `thread_identifier` | Conversation thread ID \u2014 groups related calls |\n| `custom_identifier` | Indexed custom identifier for fast queries |\n| `group_identifier` | Group related traces together |\n| `environment` | Environment name (e.g. `\"production\"`, `\"staging\"`) |\n| `metadata` | Dict of custom key-value pairs (merged in nested contexts) |\n| `prompt` | Dict with `prompt_id` and `variables` for prompt logging |\n\n##### TypeScript\n\n```typescript\nconst result = await respan.propagateAttributes(\n  {\n    customerIdentifier: \"user_123\",\n    threadIdentifier: \"conv_abc\",\n    metadata: { plan: \"pro\" },\n  },\n  async () => {\n    return await runPipeline();\n  }\n);\n```\n\n##### Nesting behavior\n\n- Nested `propagate_attributes` calls merge with the outer context\n- `metadata` dicts are merged (not replaced)\n- For duplicate keys, inner values override outer\n- Async-safe via `contextvars`\n\n#### respan_span_attributes\n\nAttaches attributes to the **current active span only** (not auto-instrumented child spans):\n\n```python\nfrom respan import respan_span_attributes\n\nwith respan_span_attributes({\n    \"customer_identifier\": \"user-123\",\n    \"metadata\": {\"priority\": \"high\"},\n}):\n    pass\n```\n\nUse `propagate_attributes` when you need attributes on all nested spans (most common). Use `respan_span_attributes` when you only want to tag the current span.\n\n### Imperative Span Creation\n\nFor runtime-determined span names, use the client API instead of decorators:\n\n```python\nfrom respan import get_client\n\nclient = get_client()\n\nwith client.start_span(name=\"dynamic_step\", kind=\"task\") as span:\n    result = do_work()\n    # span is automatically closed and exported\n```\n\n### Updating the Current Span\n\nAdd attributes or change status on the active span at runtime:\n\n```python\nfrom respan import get_client\n\nclient = get_client()\n\n# Inside a decorated function or start_span context:\nclient.update_current_span(\n    respan_params={\n        \"customer_identifier\": \"user_123\",\n        \"metadata\": {\"step\": \"final\"},\n    },\n    name=\"renamed_span\",\n)\n\n# Add events\nclient.add_event(\"checkpoint_reached\", attributes={\"items\": 42})\n\n# Record exceptions (span continues)\ntry:\n    risky_operation()\nexcept Exception as e:\n    client.record_exception(e)\n```\n\n### Custom Processors\n\nRoute spans to multiple destinations with filtering:\n\n```python\nfrom respan_tracing import RespanTelemetry\n\ntelemetry = RespanTelemetry(api_key=\"...\", base_url=\"...\")\n\n# Add a second exporter for debug logging\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter\n\ntelemetry.add_processor(\n    exporter=ConsoleSpanExporter(),\n    name=\"debug\",\n    filter_fn=lambda span: span.attributes.get(\"environment\") == \"debug\",\n)\n```\n\nRoute specific spans to a processor using the `processors` parameter on decorators:\n\n```python\n@task(name=\"sensitive_step\", processors=\"debug\")\ndef sensitive_step():\n    ...\n```\n\n### Flush\n\nAlways call `flush()` before process exit to ensure all spans are exported:\n\n```python\nrespan = Respan()\n# ... your code ...\nrespan.flush()\n```\n\nIn serverless/Lambda: call `flush()` at the end of every handler invocation.\n\n### Delivery Guarantees\n\nThe SDK batches spans in memory and the OTLP exporter retries 429/502/503/504 with backoff; it never writes to disk. Spans still queued during a long outage or a process crash are lost \u2014 the same trade-off every LLM observability SDK makes. For long-running production agents where that is not acceptable, run the packaged Respan Collector next to the application: `respan collector start` (Docker if available, otherwise the pinned `otelcol-contrib` binary) or `docker compose -f collector/docker-compose.yaml up -d` from the monorepo's `collector/` directory, then set `RESPAN_BASE_URL=http://127.0.0.1:4318`. It is the upstream OpenTelemetry Collector with a persistent, bounded queue (`file_storage` write-ahead log capped by `RESPAN_COLLECTOR_MAX_SIZE_BYTES`, `RESPAN_COLLECTOR_QUEUE_SIZE`, retries with `max_elapsed_time: 0`, uncompressed JSON export because Respan's ingest does not inflate gzip) receiving on `/api/v2/traces`, the path the SDK posts to. Never build a local journal into the application itself; alert on `otelcol_exporter_enqueue_failed_spans` (drops) and watch `otelcol_exporter_queue_size`. `respan collector status` prints those counters.\n\n### Trace Hierarchy Example\n\n```\nworkflow: handle_request\n  +-- task: classify_intent\n  |     +-- llm: openai.chat (auto-captured)\n  +-- agent: support_agent\n  |     +-- tool: lookup_order\n  |     +-- llm: openai.chat (auto-captured)\n  |     +-- tool: process_refund\n  +-- task: generate_response\n        +-- llm: openai.chat (auto-captured)\n```\n\nLLM calls within decorated functions are automatically nested as child spans.\n";
-export declare const GATEWAY_MD = "# Gateway\n\nSet up and use the Respan **gateway** \u2014 routing an app's LLM calls through the Respan\nproxy for logging, caching, key management, fallbacks, and model switching.\n\nThis file covers **both** the setup steps and the feature reference. Gateway is a\nseparate setup from tracing \u2014 do one at a time, never both in the same pass. Gateway\nsetup does **not** install instrumentation packages; it repoints the LLM client's base\nURL at the Respan proxy and applies the framework's specific wiring.\n\nDocs: `https://respan.ai/docs/documentation/features/gateway/gateway-quickstart.md`\nFull docs index: `https://www.respan.ai/docs/llms.txt`\n\n---\n\n## Setup\n\nUse this section when the user asks to set up the Respan gateway.\n\n### Hard Rules\n\n- **Interactive mode:** Ask the user questions when you need input. Do not assume.\n- **Only add Respan wiring.** Do not refactor or modify unrelated code.\n- **The gateway serves only the completion / text-generation operation**, exposed per provider:\n  - OpenAI-compatible \u2192 `https://api.respan.ai/api/chat/completions`\n  - Anthropic Messages \u2192 `https://api.respan.ai/api/anthropic/`\n  - Google Gemini \u2192 `https://api.respan.ai/api/google/gemini/...`\n\n  **Use the exact base path from the per-SDK gateway doc you fetch in Step 4** \u2014 it is authoritative. Do **NOT** repoint clients used for any other operation \u2014 embeddings, moderation, images, audio/speech, assistants, batch, fine-tuning \u2014 they are not supported and will fail (e.g. 404). Leave those untouched.\n- **Use chat completions, not the Responses API.** The gateway serves chat completions (`/api/chat/completions`), not the OpenAI Responses API (`/api/responses`). SDKs that *default* to the Responses API are still fully supported \u2014 you just switch them to chat-completions mode, per their per-SDK doc:\n  - **OpenAI Agents SDK** \u2014 Python: `set_default_openai_client(AsyncOpenAI(base_url=..., api_key=os.environ[\"RESPAN_API_KEY\"]))` + `set_default_openai_api(\"chat_completions\")` (TS: `setDefaultOpenAIClient(...)` + `setOpenAIAPI(\"chat_completions\")`).\n  - **Vercel AI SDK / `@ai-sdk/openai`** \u2014 use `provider.chat(model)`, not the default `provider(model)` (which targets the Responses API).\n- **Scope the wiring \u2014 do not blanket-rewrite.** Wire only the client(s) that make the completion call you are setting up. Do **NOT** repoint every client instance in the repo (especially in example/monorepo projects with many independent scripts).\n- **Do NOT install instrumentation packages.** Gateway routing does not use them. (That is tracing setup \u2014 see `tracing.md`.)\n- **Do not guess APIs or doc slugs.** Use only the patterns from the live integration doc you fetch, and the exact slug from the map below.\n- **Pin exact versions** if you install a framework SDK that is genuinely missing.\n- **If the gateway is already wired up, do not duplicate work.** Check for an existing `base_url`/`baseURL` pointing at `api.respan.ai` first.\n- **Read the code before proposing changes.** Find where the client is actually instantiated.\n\nThe API key is stored in `.env` as `RESPAN_API_KEY`. Gateway base URL: `https://api.respan.ai/api` (the proxy completions path is `https://api.respan.ai/api/chat/completions`).\n\n### 1. Detect\n\nIdentify:\n- **Language & package manager** \u2014 `package.json` (JS/TS), `pyproject.toml` / `requirements.txt` (Python), `Gemfile` (Ruby). Detect the package manager from lock files.\n- **LLM library / framework in use** \u2014 match the project's dependencies against the **Detection \u2192 slug map** below.\n\n### 2. Map to slug\n\nMatch the detected package(s) against the map. **Use the slug from the map verbatim \u2014 never auto-derive a slug from a display name** (the kebab-casing is irregular).\n\nApply the **priority rule:** a high-level framework wins over the raw SDK beneath it.\nFor example, a project with both `crewai` and `openai` maps to `crew-ai` (not `open-ai-sdk`),\nbecause their gateway wiring differs. **If two frameworks match, ask the user which to configure.**\n\n#### Detection \u2192 slug map\n\nURL pattern: `https://respan.ai/docs/integrations/gateway/<slug>.md`\n\n| Detected package(s) | Slug |\n|---|---|\n| `@openai/agents` / `openai-agents` | `open-ai-agents` |\n| `claude-agent-sdk` | `claude-agent-sdk` |\n| `ai` (Vercel AI SDK) | `vercel-ai-sdk` |\n| `pydantic-ai` | `pydantic-ai` |\n| `crewai` | `crew-ai` |\n| `haystack-ai` | `haystack` |\n| `langchain` | `lang-chain` |\n| `llama-index` | `llama-index` |\n| `autogen` / `autogen-agentchat` | `auto-gen` |\n| `dspy` / `dspy-ai` | `ds-py` |\n| `google-adk` | `google-adk` |\n| `openai` | `open-ai-sdk` |\n| `anthropic` / `@anthropic-ai/sdk` | `anthropic-sdk` |\n| `google-genai` / `@google/genai` | `google-gen-ai` |\n| `litellm` | `lite-llm` |\n| `ruby_llm` (gem) | `ruby-llm` |\n| `google-cloud-aiplatform` | `vertex-ai` |\n\n> Namespace note: OpenAI, Anthropic, and Vertex each have both an SDK-level gateway page (`open-ai-sdk`, `anthropic-sdk`, `vertex-ai`) and a `model-providers/*` page. The SDK-level slugs above are the correct targets for this map.\n\n### 3. Confirm\n\nShow the user what was detected and which doc will be used. Wait for confirmation.\n\n> Detected:\n> - Language: [TypeScript/Python/Ruby]\n> - Framework / SDK: [e.g. OpenAI Agents]\n> - Gateway doc: https://respan.ai/docs/integrations/gateway/open-ai-agents.md\n>\n> Set up the gateway for this? (yes/no)\n\n### 4. Fetch the live doc\n\nFetch `https://respan.ai/docs/integrations/gateway/<slug>.md` for the chosen slug.\nUse the slug from the map verbatim.\n\nIf a pinned URL fails to resolve, that signals the **map is stale** and the table should be\nupdated \u2014 it does **not** mean you should guess an alternative slug.\n\n### 5. Read the project's client code\n\nFind where the LLM client / `base_url` is instantiated, and identify **which client(s) make\ncompletion / text-generation calls** (chat completions, Anthropic `messages.create`, Gemini\n`generate_content`) \u2014 that is the only path you repoint. This is the step that determines the\ncorrect wiring \u2014 do not skip it.\n\nIf the project has multiple clients or many scripts (e.g. an examples repo), repoint **only**\nthe completion ones. Leave clients that call embeddings, moderation, images, audio,\nassistants, batch, or fine-tuning exactly as they are \u2014 the gateway does not serve them.\n\n### 6. Apply the framework-specific wiring\n\nApply the exact pattern from the fetched doc:\n\n- Ensure `RESPAN_API_KEY` is set (it is in `.env`).\n- Repoint `base_url` / `baseURL` to the gateway path from the fetched doc (e.g. `https://api.respan.ai/api` for OpenAI-compatible, `\u2026/api/anthropic/` for Anthropic) \u2014 **only on the completion client(s)** identified in step 5, not on every client in the project.\n- Apply the framework's exact wiring \u2014 e.g. OpenAI Agents requires `set_default_openai_client(AsyncOpenAI(base_url=...))`, **not** env vars.\n- Install the framework SDK only if it is genuinely missing.\n- **Do NOT install instrumentation packages.**\n\n### 7. Verify (final test \u2014 always run this)\n\nAs the final step, **run the user's program once with a small request** through the\nconfigured gateway and confirm it works:\n\n```bash\nrespan logs list --limit 5\n```\n\nConfirm:\n- The app runs without errors\n- The request appears in the gateway logs (via the CLI above, or the Respan platform at https://platform.respan.ai)\n\nIf no log entry appears, the request is not actually routing through the gateway \u2014 debug\nthe `base_url`/wiring and re-run before declaring setup done.\n\n---\n\n## Reference\n\n### Wiring Patterns\n\nPoint the LLM client's `base_url` at the Respan gateway. The Respan API key authenticates both the proxy and tracing.\n\n#### Python (OpenAI SDK)\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"RESPAN_API_KEY\"],\n    base_url=os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\"),\n)\n\nresponse = client.chat.completions.create(\n    model=\"gpt-4o-mini\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\n```\n\n#### TypeScript (OpenAI SDK)\n\n```typescript\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  apiKey: process.env.RESPAN_API_KEY,\n  baseURL: process.env.RESPAN_BASE_URL || \"https://api.respan.ai/api\",\n});\n\nconst response = await client.chat.completions.create({\n  model: \"gpt-4o-mini\",\n  messages: [{ role: \"user\", content: \"Hello!\" }],\n});\n```\n\n#### Python (Anthropic SDK)\n\n```python\nimport os\nimport anthropic\n\nclient = anthropic.Anthropic(\n    api_key=os.environ[\"RESPAN_API_KEY\"],\n    base_url=os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\"),\n)\n```\n\n#### Environment variables\n\nSet once, works everywhere:\n\n```bash\nexport RESPAN_API_KEY=\"your-key\"\nexport OPENAI_API_KEY=\"$RESPAN_API_KEY\"\nexport OPENAI_BASE_URL=\"https://api.respan.ai/api\"\n```\n\n### Framework-Specific Gateway Setup\n\n#### CrewAI\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = os.environ[\"RESPAN_API_KEY\"]\nos.environ[\"OPENAI_BASE_URL\"] = os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\")\n\nfrom crewai import Agent, Task, Crew\n# CrewAI uses the env vars automatically\n```\n\n#### Haystack\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = os.environ[\"RESPAN_API_KEY\"]\nos.environ[\"OPENAI_BASE_URL\"] = os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\")\n\nfrom haystack.components.generators import OpenAIGenerator\n# OpenAIGenerator picks up env vars automatically\n```\n\n#### OpenAI Agents SDK\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = os.environ[\"RESPAN_API_KEY\"]\nos.environ[\"OPENAI_BASE_URL\"] = os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\")\n```\n\n#### Pydantic AI\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = os.environ[\"RESPAN_API_KEY\"]\nos.environ[\"OPENAI_BASE_URL\"] = os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\")\n\nfrom pydantic_ai import Agent\nagent = Agent(model=\"openai:gpt-4o-mini\")\n```\n\n### Model Switching\n\nThe gateway supports 250+ models across providers. Use any model name:\n\n```python\n# OpenAI models\nresponse = client.chat.completions.create(model=\"gpt-4o\", ...)\n\n# Anthropic models (via OpenAI SDK!)\nresponse = client.chat.completions.create(model=\"claude-sonnet-4-20250514\", ...)\n\n# Google models\nresponse = client.chat.completions.create(model=\"gemini-2.0-flash\", ...)\n\n# Open-source models\nresponse = client.chat.completions.create(model=\"llama-3.1-70b\", ...)\n```\n\nNo code changes needed \u2014 just change the model string. View all models at `https://platform.respan.ai/platform/models`.\n\n### Advanced Features\n\n#### Fallback Models\n\nAutomatic failover if the primary model fails:\n\n```python\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[...],\n    extra_body={\n        \"fallback_models\": [\"claude-sonnet-4-20250514\", \"gemini-2.0-flash\"],\n    },\n)\n```\n\n#### Retries\n\n```python\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[...],\n    extra_body={\n        \"retries\": 3,\n    },\n)\n```\n\n#### Caching\n\nEnable response caching to save cost on repeated calls:\n\n```python\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[...],\n    extra_body={\n        \"cache_enabled\": True,\n        \"cache_ttl\": 3600,  # seconds\n    },\n)\n```\n\n#### Streaming\n\nStreaming works normally through the gateway:\n\n```python\nstream = client.chat.completions.create(\n    model=\"gpt-4o-mini\",\n    messages=[{\"role\": \"user\", \"content\": \"Tell me a story\"}],\n    stream=True,\n)\nfor chunk in stream:\n    print(chunk.choices[0].delta.content, end=\"\")\n```\n\n#### Disable Logging\n\nFor sensitive data, disable logging on specific requests:\n\n```python\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[...],\n    extra_body={\n        \"disable_log\": True,\n    },\n)\n```\n\n### Key Benefits\n\n- **Unified key management** \u2014 one Respan API key for all providers\n- **Automatic logging** \u2014 every request logged as a span\n- **Cost tracking** \u2014 per-request cost tracking across providers\n- **Caching** \u2014 cache repeated LLM calls to reduce cost and latency\n- **Fallbacks** \u2014 automatic failover between providers\n- **Model switching** \u2014 swap models without code changes\n- **~50-150ms added latency** \u2014 minimal overhead\n";
-export declare const PROMPTS_MD = "# Prompts Reference\n\nCreate, version, deploy, and use prompt templates from the Respan platform.\n\nDocs: `https://respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart.md`\n\n---\n\n## Overview\n\nPrompts are version-controlled templates stored on the Respan platform. The workflow is:\n\n1. **Create** a prompt with a name\n2. **Add versions** with messages, model config, and `{{variables}}`\n3. **Deploy** the version you want live\n4. **Fetch** the prompt in code using the API or MCP tools\n5. **Iterate** \u2014 commit new versions and deploy without code changes\n\n---\n\n## Create a Prompt\n\n### Via MCP\n\n```\nUse create_prompt to create a prompt:\n  name: \"classify_intent\"\n  description: \"Classifies user messages into intent categories\"\n\nThen use create_prompt_version to add content:\n  prompt_id: \"<id from above>\"\n  model: \"gpt-4o-mini\"\n  messages:\n    - role: \"system\"\n      content: \"You are an intent classifier. Classify the user message into one of: question, complaint, request, feedback.\"\n    - role: \"user\"\n      content: \"{{user_message}}\"\n```\n\n### Via CLI\n\n```bash\nrespan prompts create --name \"classify_intent\"\nrespan prompts versions <prompt-id>\n```\n\n---\n\n## Variables\n\nUse `{{variable_name}}` in message content. Variables are filled at runtime.\n\n```json\n{\n  \"messages\": [\n    {\"role\": \"system\", \"content\": \"You are a {{role}} assistant.\"},\n    {\"role\": \"user\", \"content\": \"{{user_input}}\"}\n  ]\n}\n```\n\n### Jinja templates\n\nPrompts support Jinja2 syntax:\n\n- **Conditionals:** `{% if context %}Use this context: {{context}}{% endif %}`\n- **JSON access:** `{{ input.key }}`\n- **Filters:** `{{ var | upper }}`\n- **Loops:** `{% for item in items %}{{item}}{% endfor %}`\n- **Default values:** Set via the API or platform UI\n\n---\n\n## Versioning and Deployment\n\nEach prompt can have multiple versions. Only one version is **deployed** (live) at a time.\n\n### Workflow\n\n1. `create_prompt_version` \u2014 creates a new version (always starts as NOT deployed)\n2. Test the version in the playground or via API\n3. Deploy via platform UI when ready\n4. Code using `prompt_id` automatically gets the deployed version\n\n### Version pinning\n\n```python\n# Always use the deployed version (default)\nprompt = get_prompt(prompt_id=\"abc123\")\n\n# Pin to a specific version\nprompt = get_prompt(prompt_id=\"abc123\", version=3)\n```\n\n---\n\n## Using Prompts in Code\n\n### Python (via Gateway)\n\nFetch the prompt config and pass to the LLM:\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"RESPAN_API_KEY\"],\n    base_url=os.getenv(\"RESPAN_BASE_URL\", \"https://api.respan.ai/api\"),\n)\n\n# The gateway resolves the prompt template and fills variables\nresponse = client.chat.completions.create(\n    model=\"gpt-4o-mini\",\n    messages=[],  # Messages come from the prompt template\n    extra_body={\n        \"prompt_id\": \"your-prompt-id\",\n        \"prompt_variables\": {\n            \"user_message\": \"I want to return my order\",\n        },\n    },\n)\n```\n\n### Linking traces to prompts\n\nUse `propagate_attributes` to tag traces with the prompt used:\n\n```python\nfrom respan import propagate_attributes\n\nwith propagate_attributes(\n    prompt={\"prompt_id\": \"abc123\", \"variables\": {\"user_message\": \"Hello\"}},\n):\n    response = client.chat.completions.create(...)\n```\n\n---\n\n## Prompt Composition\n\nVariables can reference other prompts (child prompts rendered first, injected as text).\n\nConfigure in the platform UI by changing a variable's type from **Text** to **Prompt**.\n\nMax nesting depth: 2 (parent -> child).\n\n---\n\n## Structured Output (JSON Schema)\n\nAttach a JSON schema to a prompt version for structured responses:\n\n```json\n{\n  \"response_format\": {\n    \"type\": \"json_schema\",\n    \"json_schema\": {\n      \"name\": \"extraction\",\n      \"strict\": true,\n      \"schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"intent\": {\"type\": \"string\"},\n          \"confidence\": {\"type\": \"number\"}\n        },\n        \"required\": [\"intent\", \"confidence\"],\n        \"additionalProperties\": false\n      }\n    }\n  }\n}\n```\n\n---\n\n## MCP Tools Reference\n\n| Action | Tool |\n|--------|------|\n| List all prompts | `list_prompts` |\n| Get prompt details | `get_prompt_detail(prompt_id)` |\n| Create a prompt | `create_prompt(name, description)` |\n| Update name/description | `update_prompt(prompt_id, name, description)` |\n| Create a version | `create_prompt_version(prompt_id, messages, model, ...)` |\n| Update a version | `update_prompt_version(prompt_id, version, ...)` |\n| List versions | `list_prompt_versions(prompt_id)` |\n| Get version detail | `get_prompt_version_detail(prompt_id, version)` |\n\n---\n\n## CLI Commands\n\n```bash\nrespan prompts list                    # List all prompts\nrespan prompts get <id>                # Get prompt details\nrespan prompts create --name <name>    # Create a prompt\nrespan prompts update <id>             # Update a prompt\nrespan prompts versions <id>           # List prompt versions\n```\n";
-export declare const EVALS_MD = "# Evals Reference\n\nBuild evaluation pipelines: datasets, evaluators, and experiments.\n\nDocs: `https://respan.ai/docs/documentation/features/evals/concepts.md`\n\n---\n\n## Overview\n\nTwo evaluation modes:\n\n- **Offline** \u2014 build datasets, run experiments across prompt/model variants, compare scores\n- **Online** \u2014 automatically score live production traffic (see [monitors.md](monitors.md))\n\nOffline eval workflow:\n\n```\nCreate dataset -> Create evaluator -> Create experiment -> Run & compare\n```\n\n---\n\n## Datasets\n\nA dataset is a collection of test rows (input/output pairs) for experiments.\n\n### Create from scratch\n\n```\nUse create_dataset:\n  name: \"intent_classification_testset\"\n  description: \"Test cases for intent classifier\"\n\nThen add rows with create_dataset_span:\n  dataset_id: \"<id>\"\n  input: '{\"user_message\": \"I want a refund\"}'\n  output: '{\"intent\": \"refund_request\"}'\n```\n\n### Create from production traces\n\nSample real spans from traced data:\n\n```\n1. Use list_traces or list_logs to find relevant spans\n2. Use add_spans_to_dataset to add span IDs to a dataset:\n     dataset_id: \"<id>\"\n     span_ids: [\"span_1\", \"span_2\", \"span_3\"]\n```\n\nOr use the platform UI: Datasets -> Insert by sampling (filter, set sampling %, preview, confirm).\n\n### CSV import\n\nUpload CSV via the platform UI. Columns map to prompt variables. Optional `ideal_output` column for expected outputs. Max 500 rows per import.\n\n### MCP tools\n\n| Action | Tool |\n|--------|------|\n| Create dataset | `create_dataset(name, description)` |\n| List datasets | `list_datasets` |\n| Get dataset | `get_dataset(dataset_id)` |\n| Update dataset | `update_dataset(dataset_id, name, description)` |\n| Add a row manually | `create_dataset_span(dataset_id, input, output)` |\n| Add existing spans | `add_spans_to_dataset(dataset_id, span_ids)` |\n| List rows | `list_dataset_spans(dataset_id)` |\n| Get a row | `retrieve_dataset_span(dataset_id, log_id)` |\n| Update a row | `update_dataset_span(dataset_id, log_id, ...)` |\n\n---\n\n## Evaluators\n\nAn evaluator scores LLM outputs. It is a workflow built from **graders** connected with conditions.\n\n### Grader types\n\n| Type | How it works |\n|------|-------------|\n| **LLM grader** | A language model judges the output. Uses variables: `{{output}}`, `{{input}}`, `{{expected_output}}`, `{{metadata}}`, `{{metrics}}` |\n| **Code grader** | A Python function returns a score. Signature: `main(eval_inputs)` where `eval_inputs[\"output\"]` is required |\n| **Human grader** | Team members review and score outputs manually |\n\n### Score value types\n\n| Type | Use case |\n|------|----------|\n| `numerical` | Rating scales (e.g. 0-5) |\n| `boolean` | Pass/fail checks |\n| `categorical` | Multi-choice classifications |\n| `comment` | Qualitative text feedback |\n\n### Create an evaluator\n\n```\nUse create_evaluator:\n  name: \"response_quality\"\n  score_value_type: \"numerical\"\n  type: \"llm\"\n  description: \"Scores response quality 1-5\"\n  evaluator_slug: \"response-quality\"\n```\n\nFor complex evaluators with grader workflows, conditions, and compute blocks \u2014 use the platform UI (Evaluators -> Create).\n\n### Evaluator workflow blocks\n\n- **Markers:** `Original input`, `Final result` (entry/exit)\n- **Graders:** LLM, Code, or Human scoring\n- **Conditions:** `If...Then...Else` branching based on scores\n- **Compute:** Average/weighted average of multiple grader scores\n- **Metrics:** Built-in: completion tokens, cost, latency, model, prompt tokens, total tokens\n- **Constants:** Fixed threshold values\n\n### MCP tools\n\n| Action | Tool |\n|--------|------|\n| List evaluators | `list_evaluators` |\n| Get evaluator | `get_evaluator(evaluator_id)` |\n| Create evaluator | `create_evaluator(name, score_value_type, ...)` |\n| Update evaluator | `update_evaluator(evaluator_id, ...)` |\n| Run evaluator | `run_evaluator(evaluator_id, dataset_id or log_ids)` |\n\n---\n\n## Experiments\n\nAn experiment runs evaluators across a dataset to compare prompt/model configurations.\n\n### Workflow\n\n1. Create a dataset with test rows\n2. Create evaluator(s) to score outputs\n3. Create an experiment linking dataset + evaluators\n4. Run the experiment \u2014 it generates outputs for each row and scores them\n5. Compare results across configurations\n\n### Create an experiment\n\n```\nUse create_experiment:\n  name: \"v2_vs_v3_comparison\"\n  dataset_id: \"<dataset-id>\"\n  evaluator_slugs: [\"response-quality\", \"hallucination-check\"]\n  workflows:\n    - type: \"prompt\"\n      config: { prompt_id: \"<prompt-v2-id>\" }\n    - type: \"prompt\"\n      config: { prompt_id: \"<prompt-v3-id>\" }\n```\n\n### Workflow types\n\n| Type | Description |\n|------|-------------|\n| `prompt` | Run a saved prompt template against dataset rows |\n| `completion` | Run a model completion with config |\n| `custom` | User-defined logic |\n\n### MCP tools\n\n| Action | Tool |\n|--------|------|\n| List experiments | `list_experiments` |\n| Get experiment | `get_experiment(experiment_id)` |\n| Create experiment | `create_experiment(name, dataset_id, ...)` |\n| List experiment spans | `list_experiment_spans(experiment_id)` |\n| Get experiment span | `get_experiment_span(experiment_id, log_id)` |\n| Update experiment span | `update_experiment_span(experiment_id, log_id, ...)` |\n| Get summary stats | `get_experiment_spans_summary(experiment_id, start_time, end_time)` |\n\n---\n\n## End-to-End Example\n\n```\nStep 1: Create dataset\n  create_dataset(name=\"qa_testset\")\n  create_dataset_span(dataset_id=\"...\", input=\"What is Python?\", output=\"A programming language\")\n  create_dataset_span(dataset_id=\"...\", input=\"Who made Rust?\", output=\"Mozilla Research\")\n\nStep 2: Create evaluator\n  create_evaluator(\n    name=\"accuracy_check\",\n    score_value_type=\"boolean\",\n    type=\"llm\",\n    evaluator_slug=\"accuracy-check\"\n  )\n\nStep 3: Create experiment\n  create_experiment(\n    name=\"gpt4o_vs_claude\",\n    dataset_id=\"...\",\n    evaluator_slugs=[\"accuracy-check\"]\n  )\n\nStep 4: Review results\n  list_experiment_spans(experiment_id=\"...\")\n  get_experiment_spans_summary(experiment_id=\"...\", start_time=\"...\", end_time=\"...\")\n```\n\n---\n\n## CLI Commands\n\n```bash\nrespan datasets list                   # List datasets\nrespan datasets create --name <name>   # Create a dataset\nrespan datasets get <id>               # Get dataset details\nrespan datasets spans <id>             # List dataset spans\nrespan evaluators list                 # List evaluators\nrespan evaluators get <id>             # Get evaluator details\nrespan evaluators create               # Create an evaluator\nrespan evaluators run <id>             # Run an evaluator\nrespan experiments list                # List experiments\nrespan experiments get <id>            # Get experiment details\nrespan experiments create              # Create an experiment\nrespan eval <file>                     # Run a one-shot eval defined in a JSON file\n```\n\n## One-Shot Evals via JSON\n\n`respan eval <file.json>` runs a complete eval pipeline from a single JSON spec \u2014\ncreates the prompt, dataset, evaluators, and experiment in one command.\nIDs are written back into the file so reruns reuse existing resources.\n\n### Minimal example\n\n```json\n{\n  \"name\": \"Movie matcher\",\n  \"prompt\": {\n    \"name\": \"movie-matcher\",\n    \"model\": \"gpt-5-mini\",\n    \"messages\": [\n      { \"role\": \"system\", \"content\": \"Identify the movie. Reply with only the title.\" },\n      { \"role\": \"user\", \"content\": \"{{description}}\" }\n    ]\n  },\n  \"dataset\": {\n    \"name\": \"movie-descriptions\",\n    \"rows\": [\n      { \"description\": \"A detective investigates seven deadly sins.\", \"expected_output\": \"Se7en\" },\n      { \"description\": \"A hacker learns reality is a simulation.\", \"expected_output\": \"The Matrix\" }\n    ]\n  },\n  \"experiment\": {\n    \"evaluators\": [\n      {\n        \"name\": \"Title match\",\n        \"type\": \"llm\",\n        \"score_value_type\": \"boolean\",\n        \"llm_config\": {\n          \"model\": \"openai/gpt-5-mini\",\n          \"evaluator_definition\": \"Expected: {{expected_output}}. Got: {{output}}. Correct? Reply true or false.\"\n        }\n      }\n    ]\n  }\n}\n```\n\nRun:\n\n```bash\nrespan eval movie-matcher.eval.json\n```\n\nThe runner creates the prompt (and deploys version 1), creates the dataset (and bulk-loads rows),\ncreates each evaluator + its workflow (and deploys), then creates the experiment linking them.\nEach step writes the resulting IDs back to the JSON file so subsequent runs are idempotent \u2014\nre-running with the same file reuses the existing resources.\n";
-export declare const MONITORS_MD = "# Monitors & Automation Reference\n\nSet up monitoring alerts, online evaluations, and automated workflows.\n\nDocs: `https://respan.ai/docs/documentation/features/monitoring/monitors.md`\n\n---\n\n## Monitors\n\nA monitor watches a metric over time and sends a notification when a threshold is crossed.\n\n### Examples\n\n- Error rate > 5% over 10 minutes\n- Total cost > $1.00 over 5 minutes\n- Average latency > 3 seconds over 15 minutes\n- P95 latency > 5 seconds over 1 hour\n\n### Setup\n\nMonitors are configured in the platform UI: **Monitoring -> Monitors -> Create**.\n\nA monitor has two parts:\n\n#### 1. Trigger\n\nTemplate: `When [metric] of [source] is [threshold] over [time window]`\n\n- **Metric:** cost, latency, error rate, token usage, request count, etc.\n- **Source:** all requests, specific model, specific customer, etc.\n- **Threshold:** condition (greater than, less than, equals)\n- **Time window:** evaluation period (1 min, 5 min, 10 min, 1 hour, etc.)\n\nAdd **Where** conditions to narrow scope:\n- Filter by model, project, environment, customer, or custom metadata\n\n#### 2. Notifications\n\nDestinations:\n\n| Destination | Details |\n|-------------|---------|\n| **Email** | Customizable subject and body |\n| **Slack** | Customizable message |\n| **Webhook** | Raw URL \u2014 receives JSON payload |\n\nA single monitor can send to multiple destinations.\n\n### Manage\n\n- **Deploy** to make a monitor live\n- **Pause/Resume** deployed monitors\n- **Send test alert** to validate before deploying\n- **View versions** and restore earlier versions as drafts\n- **Create from chart** \u2014 select a metric on the dashboard, click to create a monitor with metric/source/interval prefilled\n\n---\n\n## Online Evaluations (Automation)\n\nAutomatically score production traffic in real time using deployed evaluators.\n\n### Setup\n\nConfigure in the platform UI: **Evaluators -> Automations -> Create**.\n\n1. **Create a condition** \u2014 filter rules for which logs to evaluate:\n   - **Single log** \u2014 evaluate individual spans matching criteria\n   - **Aggregation** \u2014 evaluate aggregated metrics over a window\n\n2. **Create an automation** \u2014 connect:\n   - Condition (which logs)\n   - Evaluator (which scoring workflow)\n   - Sampling rate (0.0-1.0, fraction of matching logs to evaluate)\n\n3. **Check results** \u2014 view eval scores in the automation table\n\n### Use case\n\n> \"Score 10% of production chat responses for hallucination using my LLM evaluator\"\n\n```\nCondition: log_type = \"chat\" AND model = \"gpt-4o\"\nEvaluator: hallucination-check\nSampling: 0.1\n```\n\n---\n\n## Webhooks\n\nReceive event notifications via HTTP webhooks.\n\n### Setup\n\n1. Go to platform: **Settings -> Webhooks -> Create**\n2. Enter your endpoint URL\n3. Select event types to subscribe to\n4. Optionally set a webhook secret for HMAC-SHA256 verification\n\n### Verification\n\nRespan signs webhook payloads with HMAC-SHA256. Verify the signature:\n\n```python\nimport hashlib\nimport hmac\n\ndef verify_webhook(payload: bytes, signature: str, secret: str) -> bool:\n    expected = hmac.new(\n        secret.encode(),\n        payload,\n        hashlib.sha256,\n    ).hexdigest()\n    return hmac.compare_digest(expected, signature)\n```\n\nThe signature is sent in the request headers.\n\n---\n\n## Metrics Dashboard\n\nTrack key indicators in the platform: **Dashboard -> Metrics**.\n\n### Available metrics\n\n- **Requests:** total count, requests per model/customer/API key\n- **Tokens:** prompt tokens, completion tokens, total tokens\n- **Cost:** per-request, per-model, per-customer\n- **Latency:** average, P50, P95, P99\n- **Errors:** error count, error rate\n- **Time to first token (TTFT):** streaming latency\n\n### Breakdowns\n\nSlice metrics by:\n- Model\n- Customer (`customer_identifier`)\n- API key\n- Prompt template\n- Environment\n- Custom metadata keys\n\n### Per-user analytics\n\nUse `customer_identifier` in spans to enable:\n- Per-user cost tracking and budgets\n- Per-user rate limiting\n- User-level quality metrics\n\n---\n\n## CLI Commands\n\n```bash\nrespan traces list --limit 10          # List recent traces\nrespan traces get <trace-id>           # Get trace details\nrespan traces summary                  # Trace summary stats\nrespan logs list --limit 10            # List recent logs\nrespan logs get <log-id>               # Get log details\nrespan logs summary                    # Log summary stats\n```\n";