@amplitude/ai 0.1.0

package/.cursor/skills/instrument-with-amplitude-ai/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: instrument-with-amplitude-ai
+description: Detect framework, install @amplitude/ai dependencies, scaffold init code, and identify likely LLM call sites in JavaScript/TypeScript projects.
+---
+
+# /instrument-with-amplitude-ai
+
+## Goal
+
+Instrument a JS/TS app with `@amplitude/ai` quickly and safely.
+
+## Steps
+
+1. Detect project type from `package.json` and lockfiles:
+   - web apps: `next`, `react`, `vite`
+   - APIs: `express`, `fastify`, `hono`
+   - workers/CLI: no web framework, but provider SDKs present
+2. Install deps:
+   - `pnpm add @amplitude/ai`
+   - provider packages used by the app (`openai`, `@anthropic-ai/sdk`, etc.)
+3. Scaffold bootstrap:
+   - run `amplitude-ai init`
+   - ensure `AMPLITUDE_AI_API_KEY` is documented in `.env.example`
+4. Identify likely LLM call sites (priority order):
+   - provider SDK direct calls:
+     - `openai.chat.completions.create`
+     - `openai.responses.create`
+     - `anthropic.messages.create`
+   - framework integrations:
+     - route handlers (`app.get/post`, `router.*`, Next route handlers)
+     - agent orchestration loops and tool executors
+5. Add instrumentation (choose one path):
+   - zero-code: `patch({ amplitudeAI })`
+   - explicit wrappers: `wrap(existingClient, amplitudeAI)`
+   - explicit lifecycle: `ai.agent(agentId, { userId }).session({ sessionId })`
+   - function tracing: `tool(...)` / `observe(...)`
+6. Validate:
+   - run `amplitude-ai doctor`
+   - run tests and typecheck
+   - verify generated files are fresh: `pnpm --filter @amplitude/ai check:generated`
+7. Suggested ripgrep probes:
+   - `openai|anthropic|chat\\.completions|responses\\.create|messages\\.create`
+   - `agent\\(|session\\(|tool\\(|observe\\(`
+
+## Safety checks
+
+- Do not modify unrelated files.
+- Prefer adding instrumentation near existing provider calls.
+- Keep content mode explicit if privacy constraints apply.
+- Do not duplicate instrumentation (avoid wrapping and patching the same call path twice).

package/AGENTS.md

@@ -0,0 +1,79 @@
+<!-- GENERATED FILE: do not edit manually -->
+
+# AGENTS.md
+
+Package: `@amplitude/ai` v0.1.0
+
+## Install
+
+- `pnpm add @amplitude/ai`
+
+## Decision Tree
+
+- Need zero-code coverage: use `patch()`.
+- Already have a provider client: use `wrap()` or provider wrappers.
+- Need user/session lineage: use `ai.agent(...).session(...)`.
+- Need tool telemetry: use `tool()`.
+- Need agent-assistant guidance: run MCP prompt `instrument_app`.
+
+## Canonical Patterns
+
+- zero-code patching
+- wrap-openai
+- bound-agent-session
+- tool-decorator
+- express-middleware
+
+## MCP Surface
+
+- Tools: `get_event_schema`, `get_integration_pattern`, `validate_setup`, `suggest_instrumentation`, `validate_file`, `search_docs`
+- Resources: `amplitude-ai://event-schema`, `amplitude-ai://integration-patterns`
+- Prompt: `instrument_app`
+
+## Gotchas
+
+- `tool()` in Node requires explicit JSON schema for robust agent input shaping.
+- Keep `AMPLITUDE_AI_API_KEY` available in runtime env for telemetry delivery.
+- Use `MockAmplitudeAI` for deterministic tests.
+
+## Testing
+
+- Run package tests: `pnpm --filter @amplitude/ai test`
+- Run typecheck: `pnpm --filter @amplitude/ai test:typescript`
+- Run docs freshness: `node scripts/generate-agent-docs.mjs --check`
+
+## CLI
+
+- `amplitude-ai init [--dry-run] [--force]`
+- `amplitude-ai doctor`
+- `amplitude-ai status`
+- `amplitude-ai mcp`
+
+## Examples
+
+- `examples/zero-code.ts`
+- `examples/wrap-openai.ts`
+- `examples/multi-agent.ts`
+- `examples/framework-integration.ts`
+- `examples/real-openai.ts` (requires OPENAI_API_KEY)
+
+## Extended Reference
+
+- `llms-full.txt` — Full API signatures and canonical patterns for LLM agents
+
+## Cursor Skill
+
+- `.cursor/skills/instrument-with-amplitude-ai/SKILL.md`
+
+## Event Schema (names)
+
+- `[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Amplitude, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.