@amplitude/ai 0.1.0

package/llms-full.txt

@@ -0,0 +1,127 @@
+# llms-full.txt
+# @amplitude/ai 0.1.0 — Detailed API Reference for LLM Agents
+# Use this file for instrumentation guidance. See llms.txt for discovery.
+
+## Core API
+
+### AmplitudeAI(config)
+Initialize the SDK. Required entry point.
+```
+new AmplitudeAI({ apiKey: string, contentMode?: 'full' | 'metadata_only' | 'customer_enriched' })
+```
+
+### patch(options)
+Zero-code instrumentation. Monkey-patches all detected provider SDKs.
+```
+patch({ amplitudeAI: AmplitudeAI })
+unpatch()
+```
+
+### wrap(client, amplitude, opts?)
+Convert an existing provider client into an instrumented wrapper.
+```
+wrap(openaiClient, ai) → OpenAI wrapper
+wrap(anthropicClient, ai) → Anthropic wrapper
+wrap(azureClient, ai) → AzureOpenAI wrapper
+```
+
+### ai.agent(agentId, options)
+Create a bound agent for user/session lineage.
+```
+const agent = ai.agent('my-agent', { userId: 'u1' })
+const session = agent.session({ sessionId: 's1' })
+await session.run(async (s) => { ... })
+```
+
+### tool(fn, options) / tool(options)(fn)
+Wrap a function to emit [Agent] Tool Call events.
+```
+const search = tool(async (query: string) => results, {
+  name: 'search_products',
+  inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+})
+```
+
+### observe(fn, options) / observe(options)(fn)
+Wrap a function to emit [Agent] Span events with session lifecycle.
+```
+const handler = observe(async (req) => response, { name: 'request-handler' })
+```
+
+### MockAmplitudeAI
+Deterministic testing helper. Drop-in replacement.
+```
+const mock = new MockAmplitudeAI()
+mock.getEvents('[Agent] AI Response') → BaseEvent[]
+mock.flush() → BaseEvent[]
+```
+
+## Provider Wrappers
+
+| Provider    | Import                          | Streaming | Tool Calls | TTFB | Cache Tokens |
+|-------------|---------------------------------|-----------|------------|------|--------------|
+| OpenAI      | `new OpenAI({ amplitude })`     | Yes       | Yes        | Yes  | Yes          |
+| Anthropic   | `new Anthropic({ amplitude })`  | Yes       | Yes        | Yes  | Yes          |
+| Gemini      | `new Gemini({ amplitude })`     | Yes       | No         | No   | No           |
+| AzureOpenAI | `new AzureOpenAI({ amplitude })` | Yes      | Yes        | Yes  | No           |
+| Bedrock     | `new Bedrock({ amplitude })`    | Yes       | Yes        | No   | No           |
+| Mistral     | `new Mistral({ amplitude })`    | Yes       | No         | No   | No           |
+
+## Canonical Patterns
+
+### 1. Zero-code (patch)
+```typescript
+import { AmplitudeAI, patch } from '@amplitude/ai';
+const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY! });
+patch({ amplitudeAI: ai });
+```
+
+### 2. Wrap existing client
+```typescript
+import { AmplitudeAI, wrap } from '@amplitude/ai';
+const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY! });
+const instrumented = wrap(existingOpenAIClient, ai);
+```
+
+### 3. Provider wrapper
+```typescript
+import { AmplitudeAI, OpenAI } from '@amplitude/ai';
+const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY! });
+const client = new OpenAI({ amplitude: ai, apiKey: process.env.OPENAI_API_KEY! });
+```
+
+### 4. Bound agent + session
+```typescript
+const agent = ai.agent('assistant', { userId: 'u1' });
+const session = agent.session({ sessionId: 's1' });
+await session.run(async () => { /* LLM calls tracked automatically */ });
+```
+
+### 5. Express middleware
+```typescript
+import { createAmplitudeAIMiddleware } from '@amplitude/ai';
+app.use(createAmplitudeAIMiddleware());
+```
+
+## MCP Tools
+
+- `get_event_schema(event_type?)` — Return event schema and property definitions
+- `get_integration_pattern(id?)` — Return canonical instrumentation patterns
+- `validate_setup()` — Check required environment variables
+- `suggest_instrumentation(framework?, provider?, content_tier?)` — Value-first setup guidance with content-tier and privacy defaults
+- `validate_file(source, language?)` — Detect uninstrumented LLM call sites
+- `search_docs(query, max_results?)` — Search README and API reference by keyword
+
+## CLI
+
+- `amplitude-ai init [--dry-run] [--force]` — Scaffold .env.example and setup file
+- `amplitude-ai doctor [--json] [--no-mock-check]` — Validate environment and event pipeline
+- `amplitude-ai status [--json]` — Show SDK version, installed providers, and env config
+- `amplitude-ai mcp` — Start MCP server over stdio
+- `amplitude-ai --help` / `amplitude-ai --version`
+
+## Common Errors
+
+- "No events captured" → Ensure session.run() wraps your LLM calls
+- "patch() drops events silently" → patch() requires active SessionContext; use session.run()
+- "flush() timeout" → Call ai.flush() before process exit in serverless

package/llms.txt

@@ -0,0 +1,28 @@
+<!-- GENERATED FILE: do not edit manually -->
+# llms.txt
+package=@amplitude/ai
+version=0.1.0
+
+[mcp.tools]
+get_event_schema
+get_integration_pattern
+validate_setup
+suggest_instrumentation
+validate_file
+search_docs
+
+[mcp.resources]
+amplitude-ai://event-schema
+amplitude-ai://integration-patterns
+
+[events]
+[Agent] AI Response
+[Agent] Embedding
+[Agent] Score
+[Agent] Session End
+[Agent] Session Enrichment
+[Agent] Session Evaluation
+[Agent] Span
+[Agent] Tool Call
+[Agent] Topic Classification
+[Agent] User Message

package/mcp.schema.json

@@ -0,0 +1,18 @@
+{
+  "generated": true,
+  "package": "@amplitude/ai",
+  "version": "0.1.0",
+  "prompt": "instrument_app",
+  "tools": [
+    "get_event_schema",
+    "get_integration_pattern",
+    "validate_setup",
+    "suggest_instrumentation",
+    "validate_file",
+    "search_docs"
+  ],
+  "resources": [
+    "amplitude-ai://event-schema",
+    "amplitude-ai://integration-patterns"
+  ]
+}

package/package.json

@@ -0,0 +1,189 @@
+{
+  "name": "@amplitude/ai",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Amplitude AI SDK - LLM usage tracking for Amplitude Analytics",
+  "keywords": [
+    "amplitude",
+    "ai",
+    "llm",
+    "analytics",
+    "tracking",
+    "openai",
+    "anthropic"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amplitude/Amplitude-AI-Node.git"
+  },
+  "homepage": "https://github.com/amplitude/Amplitude-AI-Node#readme",
+  "bugs": {
+    "url": "https://github.com/amplitude/Amplitude-AI-Node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./bound-agent": "./dist/bound-agent.js",
+    "./cli/doctor": "./dist/cli/doctor.js",
+    "./cli/init": "./dist/cli/init.js",
+    "./cli/providers": "./dist/cli/providers.js",
+    "./cli/status": "./dist/cli/status.js",
+    "./client": "./dist/client.js",
+    "./config": "./dist/config.js",
+    "./context": "./dist/context.js",
+    "./core/constants": "./dist/core/constants.js",
+    "./core/enrichments": "./dist/core/enrichments.js",
+    "./core/privacy": "./dist/core/privacy.js",
+    "./core/tracking": "./dist/core/tracking.js",
+    "./decorators": "./dist/decorators.js",
+    "./exceptions": "./dist/exceptions.js",
+    "./integrations/anthropic-tools": "./dist/integrations/anthropic-tools.js",
+    "./integrations/crewai": "./dist/integrations/crewai.js",
+    "./integrations/langchain": "./dist/integrations/langchain.js",
+    "./integrations/llamaindex": "./dist/integrations/llamaindex.js",
+    "./integrations/openai-agents": "./dist/integrations/openai-agents.js",
+    "./integrations/opentelemetry": "./dist/integrations/opentelemetry.js",
+    "./internals": "./dist/internals.js",
+    "./mcp": "./dist/mcp/index.js",
+    "./mcp/contract": "./dist/mcp/contract.js",
+    "./mcp/patterns": "./dist/mcp/patterns.js",
+    "./mcp/server": "./dist/mcp/server.js",
+    "./mcp/validate-file": "./dist/mcp/validate-file.js",
+    "./middleware": "./dist/middleware.js",
+    "./patching": "./dist/patching.js",
+    "./propagation": "./dist/propagation.js",
+    "./providers/anthropic": "./dist/providers/anthropic.js",
+    "./providers/azure-openai": "./dist/providers/azure-openai.js",
+    "./providers/base": "./dist/providers/base.js",
+    "./providers/bedrock": "./dist/providers/bedrock.js",
+    "./providers/gemini": "./dist/providers/gemini.js",
+    "./providers/mistral": "./dist/providers/mistral.js",
+    "./providers/openai": "./dist/providers/openai.js",
+    "./register": "./dist/register.js",
+    "./session": "./dist/session.js",
+    "./tenant": "./dist/tenant.js",
+    "./testing": "./dist/testing.js",
+    "./types": "./dist/types.js",
+    "./utils/costs": "./dist/utils/costs.js",
+    "./utils/debug": "./dist/utils/debug.js",
+    "./utils/logger": "./dist/utils/logger.js",
+    "./utils/model-tiers": "./dist/utils/model-tiers.js",
+    "./utils/providers": "./dist/utils/providers.js",
+    "./utils/resolve-module": "./dist/utils/resolve-module.js",
+    "./utils/streaming": "./dist/utils/streaming.js",
+    "./utils/tokens": "./dist/utils/tokens.js",
+    "./wrappers": "./dist/wrappers.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "amplitude-ai": "./bin/amplitude-ai.mjs",
+    "amplitude-ai-completions": "./bin/amplitude-ai-completions.mjs",
+    "amplitude-ai-doctor": "./bin/amplitude-ai-doctor.mjs",
+    "amplitude-ai-init": "./bin/amplitude-ai-init.mjs",
+    "amplitude-ai-instrument": "./bin/amplitude-ai-instrument.mjs",
+    "amplitude-ai-mcp": "./bin/amplitude-ai-mcp.mjs",
+    "amplitude-ai-register-catalog": "./bin/amplitude-ai-register-catalog.mjs",
+    "amplitude-ai-status": "./bin/amplitude-ai-status.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "dist",
+    "bin",
+    "data",
+    "llms.txt",
+    "llms-full.txt",
+    "mcp.schema.json",
+    ".cursor/skills/instrument-with-amplitude-ai/SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "check:generated": "node scripts/generate-agent-docs.mjs --check",
+    "clean": "rimraf dist",
+    "generate:agent-docs": "node scripts/generate-agent-docs.mjs",
+    "lint": "eslint --cache --ext .js,.jsx,.ts,.tsx --quiet . && biome lint ./src --log-level=error --diagnostic-level=error --no-errors-on-unmatched",
+    "lint:fix": "eslint --fix --ext .js,.jsx,.ts,.tsx . --cache && biome lint ./src --log-level=error --diagnostic-level=error --no-errors-on-unmatched --write",
+    "test": "vitest",
+    "test:changed": "vitest run --changed${VITEST_CHANGED_BASE:+=$VITEST_CHANGED_BASE}",
+    "test:coverage": "vitest run --coverage",
+    "test:packaged": "pnpm run build && vitest run test/packaged-dist-smoke.test.ts",
+    "test:typescript": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@amplitude/analytics-node": "1.3.5",
+    "@biomejs/biome": "1.9.4",
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "@typescript-eslint/eslint-plugin": "8.29.1",
+    "@typescript-eslint/parser": "8.29.1",
+    "@vitest/coverage-v8": "4.0.14",
+    "eslint": "8.57.0",
+    "openai": "^5.23.2",
+    "rimraf": "5.0.5",
+    "tsdown": "0.18.4",
+    "typescript": "5.9.3",
+    "vitest": "4.0.14"
+  },
+  "peerDependencies": {
+    "@amplitude/analytics-node": ">=1.3.0",
+    "@anthropic-ai/sdk": ">=0.29.0 <1.0.0",
+    "@aws-sdk/client-bedrock-runtime": ">=3.0.0 <4.0.0",
+    "@google/generative-ai": ">=0.21.0 <1.0.0",
+    "@mistralai/mistralai": ">=1.3.6 <2.0.0",
+    "@pydantic/genai-prices": ">=0.0.1",
+    "js-tiktoken": ">=1.0.0",
+    "openai": ">=4.0.0 <7.0.0",
+    "tiktoken": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@amplitude/analytics-node": {
+      "optional": false
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@aws-sdk/client-bedrock-runtime": {
+      "optional": true
+    },
+    "@google/generative-ai": {
+      "optional": true
+    },
+    "@mistralai/mistralai": {
+      "optional": true
+    },
+    "@pydantic/genai-prices": {
+      "optional": true
+    },
+    "js-tiktoken": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "tiktoken": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "zod": "3.25.76"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@biomejs/biome",
+      "esbuild"
+    ],
+    "overrides": {
+      "fast-xml-parser": ">=5.5.6"
+    }
+  },
+  "packageManager": "pnpm@10.30.3+sha512.c961d1e0a2d8e354ecaa5166b822516668b7f44cb5bd95122d590dd81922f606f5473b6d23ec4a5be05e7fcd18e8488d47d978bbe981872f1145d06e9a740017"
+}