@amplitude/ai 0.1.0

package/bin/amplitude-ai-completions.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+const commands = ['init', 'doctor', 'mcp', 'status'];
+const flags = ['--help', '-h', '--version', '-v', '--dry-run', '--force', '--no-mock-check'];
+
+const shell = process.argv[2];
+
+if (shell === 'bash') {
+  process.stdout.write(
+    `_amplitude_ai() {\n  local cur=\${COMP_WORDS[COMP_CWORD]}\n  COMPREPLY=($(compgen -W "${commands.join(' ')} ${flags.join(' ')}" -- "$cur"))\n}\ncomplete -F _amplitude_ai amplitude-ai\n`,
+  );
+} else if (shell === 'zsh') {
+  process.stdout.write(
+    `#compdef amplitude-ai\n_amplitude_ai() {\n  _arguments '1:command:(${commands.join(' ')})' '*:flags:(${flags.join(' ')})'\n}\n_amplitude_ai\n`,
+  );
+} else {
+  process.stderr.write('Usage: amplitude-ai-completions <bash|zsh>\n');
+  process.exit(1);
+}

package/bin/amplitude-ai-doctor.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { runDoctor } from '../dist/cli/doctor.js';
+
+const args = process.argv.slice(2);
+const includeMockCheck = !args.includes('--no-mock-check');
+const jsonMode = args.includes('--json');
+const result = runDoctor(process.cwd(), { includeMockCheck });
+
+if (jsonMode) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} else {
+  const checkMark = '\u2713';
+  const crossMark = '\u2717';
+
+  process.stdout.write(`amplitude-ai doctor\n\n`);
+  for (const check of result.checks) {
+    process.stdout.write(`  ${check.ok ? checkMark : crossMark} ${check.name}: ${check.detail}\n`);
+    if (check.fix) {
+      process.stdout.write(`    fix: ${check.fix}\n`);
+    }
+  }
+  process.stdout.write(`\n${result.ok ? 'All checks passed.' : 'Some checks failed.'}\n`);
+}
+
+process.exit(result.ok ? 0 : 1);

package/bin/amplitude-ai-init.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { runInit } from '../dist/cli/init.js';
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const force = args.includes('--force');
+
+const result = runInit({
+  cwd: process.cwd(),
+  dryRun,
+  force,
+});
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      command: 'init',
+      dryRun,
+      force,
+      created: result.created,
+      skipped: result.skipped,
+    },
+    null,
+    2,
+  ) + '\n',
+);

package/bin/amplitude-ai-instrument.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/**
+ * CLI wrapper for zero-code LLM instrumentation.
+ *
+ * Usage:
+ *   AMPLITUDE_AI_API_KEY=xxx AMPLITUDE_AI_AUTO_PATCH=true amplitude-ai-instrument node app.js
+ *
+ * This sets NODE_OPTIONS to preload the register module, then exec's the user command.
+ * Same pattern as ddtrace, opentelemetry-instrument, etc.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const registerPath = join(__dirname, '..', 'dist', 'register.js');
+
+const apiKey = process.env.AMPLITUDE_AI_API_KEY || '';
+const autoPatch = (process.env.AMPLITUDE_AI_AUTO_PATCH || '').toLowerCase() === 'true';
+
+if (!apiKey) {
+  process.stderr.write('amplitude-ai-instrument: AMPLITUDE_AI_API_KEY not set, passing through.\n');
+} else if (!autoPatch) {
+  process.stderr.write("amplitude-ai-instrument: AMPLITUDE_AI_AUTO_PATCH is not 'true', passing through.\n");
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  process.stderr.write('Usage: amplitude-ai-instrument <command> [args...]\n');
+  process.exit(1);
+}
+
+const existingNodeOpts = process.env.NODE_OPTIONS || '';
+if (apiKey && autoPatch) {
+  process.env.NODE_OPTIONS = existingNodeOpts
+    ? `${existingNodeOpts} --import ${registerPath}`
+    : `--import ${registerPath}`;
+}
+
+try {
+  execFileSync(args[0], args.slice(1), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+} catch (err) {
+  if (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number') {
+    process.exit(err.status);
+  }
+  process.exit(1);
+}

package/bin/amplitude-ai-mcp.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runMcpServer } from '../dist/mcp/server.js';
+
+runMcpServer().catch((error) => {
+  process.stderr.write(`[amplitude-ai-mcp] failed to start: ${String(error)}\n`);
+  process.exit(1);
+});

package/bin/amplitude-ai-register-catalog.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+/**
+ * Generate curl commands to register the [Agent] event schema in your
+ * Amplitude project's data catalog.
+ *
+ * This script reads the bundled agent_event_catalog.json and prints
+ * executable curl commands — it makes NO network requests itself.
+ *
+ * Usage:
+ *   npx amplitude-ai-register-catalog --api-key YOUR_KEY --secret-key YOUR_SECRET
+ *   npx amplitude-ai-register-catalog                # prints commands with placeholder keys
+ *
+ * Pipe to bash to execute:
+ *   npx amplitude-ai-register-catalog --api-key KEY --secret-key SECRET | bash
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CATEGORY = 'Agent Analytics';
+
+function loadCatalog() {
+  const catalogPath = join(__dirname, '..', 'data', 'agent_event_catalog.json');
+  return JSON.parse(readFileSync(catalogPath, 'utf-8')).events;
+}
+
+function shellEscape(str) {
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      'api-key': { type: 'string' },
+      'secret-key': { type: 'string' },
+      eu: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+  });
+
+  if (values.help) {
+    console.log(`Generate curl commands to register [Agent] event schema in your Amplitude data catalog.
+
+Usage:
+  npx amplitude-ai-register-catalog --api-key KEY --secret-key SECRET
+  npx amplitude-ai-register-catalog                # uses placeholder keys
+  npx amplitude-ai-register-catalog ... | bash     # pipe to execute
+
+Options:
+  --api-key      Amplitude project API key
+  --secret-key   Amplitude project Secret key
+  --eu           Use EU data residency endpoint
+  --help         Show this help message
+
+Alternatively, use the Python CLI for direct execution:
+  pip install amplitude-ai
+  amplitude-ai-register-catalog --api-key KEY --secret-key SECRET`);
+    process.exit(0);
+  }
+
+  const apiKey = values['api-key'] || 'YOUR_API_KEY';
+  const secretKey = values['secret-key'] || 'YOUR_SECRET_KEY';
+  const baseUrl = values.eu ? 'https://analytics.eu.amplitude.com/api/2' : 'https://amplitude.com/api/2';
+
+  const authHeader = `Basic ${Buffer.from(`${apiKey}:${secretKey}`).toString('base64')}`;
+  const catalog = loadCatalog();
+
+  if (!values['api-key'] || !values['secret-key']) {
+    console.error(
+      '# WARNING: No --api-key / --secret-key provided. Commands use placeholders.',
+    );
+    console.error(
+      '# Replace YOUR_API_KEY and YOUR_SECRET_KEY, or pass them as arguments.',
+    );
+    console.error('');
+  }
+
+  console.log('#!/usr/bin/env bash');
+  console.log('# Auto-generated curl commands to register [Agent] event schema');
+  console.log(`# ${catalog.length} events, ${catalog.reduce((n, e) => n + e.properties.length, 0)} total properties`);
+  console.log('set -euo pipefail');
+  console.log('');
+
+  // Create category
+  console.log('# Create event category');
+  console.log(
+    `curl -s -X POST ${shellEscape(`${baseUrl}/taxonomy/category`)} \\`,
+  );
+  console.log(`  -H ${shellEscape(`Authorization: ${authHeader}`)} \\`);
+  console.log(`  -d ${shellEscape(`name=${CATEGORY}`)}`);
+  console.log('echo ""');
+  console.log('');
+
+  for (let i = 0; i < catalog.length; i++) {
+    const event = catalog[i];
+    const eventType = event.event_type;
+    const desc = event.description || '';
+    const props = event.properties;
+
+    console.log(`# [${i + 1}/${catalog.length}] ${eventType} (${props.length} properties)`);
+
+    // Create event (POST) — 409 means it already exists, that's fine
+    const eventData = new URLSearchParams({
+      event_type: eventType,
+      description: desc,
+      category: CATEGORY,
+    }).toString();
+    console.log(
+      `curl -s -X POST ${shellEscape(`${baseUrl}/taxonomy/event`)} \\`,
+    );
+    console.log(`  -H ${shellEscape(`Authorization: ${authHeader}`)} \\`);
+    console.log(`  -d ${shellEscape(eventData)}`);
+    console.log('echo ""');
+
+    // Update event (PUT) to ensure description is current
+    const encodedEvent = encodeURIComponent(eventType);
+    const updateData = new URLSearchParams({
+      description: desc,
+      category: CATEGORY,
+    }).toString();
+    console.log(
+      `curl -s -X PUT ${shellEscape(`${baseUrl}/taxonomy/event/${encodedEvent}`)} \\`,
+    );
+    console.log(`  -H ${shellEscape(`Authorization: ${authHeader}`)} \\`);
+    console.log(`  -d ${shellEscape(updateData)}`);
+    console.log('echo ""');
+
+    // Register each property
+    for (const prop of props) {
+      const propData = new URLSearchParams({
+        event_type: eventType,
+        event_property: prop.name,
+        description: prop.description || '',
+        type: prop.type || 'string',
+        ...(prop.is_required ? { is_required: 'true' } : {}),
+        ...(prop.is_array_type ? { is_array_type: 'true' } : {}),
+      }).toString();
+
+      console.log(
+        `curl -s -X POST ${shellEscape(`${baseUrl}/taxonomy/event-property`)} \\`,
+      );
+      console.log(`  -H ${shellEscape(`Authorization: ${authHeader}`)} \\`);
+      console.log(`  -d ${shellEscape(propData)}`);
+      console.log('echo ""');
+    }
+    console.log('');
+  }
+
+  console.log(`echo "Done. Registered ${catalog.length} events."`);
+}
+
+main();

package/bin/amplitude-ai-status.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { runStatus } from '../dist/cli/status.js';
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const result = runStatus(process.cwd());
+
+if (jsonMode) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} else {
+  const checkMark = '\u2713';
+  const crossMark = '\u2717';
+
+  process.stdout.write(`@amplitude/ai v${result.version}\n\n`);
+
+  process.stdout.write('Providers:\n');
+  for (const p of result.providers) {
+    process.stdout.write(`  ${p.installed ? checkMark : crossMark} ${p.name}\n`);
+  }
+
+  process.stdout.write('\nEnvironment:\n');
+  for (const [key, present] of Object.entries(result.env)) {
+    process.stdout.write(`  ${present ? checkMark : crossMark} ${key}\n`);
+  }
+
+  process.stdout.write('\n');
+}

package/bin/amplitude-ai.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const [, , command, ...rest] = process.argv;
+
+const commandToBin = {
+  mcp: './amplitude-ai-mcp.mjs',
+  init: './amplitude-ai-init.mjs',
+  doctor: './amplitude-ai-doctor.mjs',
+  status: './amplitude-ai-status.mjs',
+};
+
+if (command === '--help' || command === '-h' || command === undefined) {
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const version = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  process.stdout.write(
+    `amplitude-ai v${version}\n\nUsage: amplitude-ai <command> [options]\n\nCommands:\n  init      Scaffold .env.example and setup file\n  doctor    Validate environment, deps, and event pipeline\n  status    Show SDK version, installed providers, and env config\n  mcp       Start the MCP server over stdio\n\nOptions:\n  --help, -h       Show this help message\n  --version, -v    Show version number\n`
+  );
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const version = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
+if (command in commandToBin) {
+  const binPath = fileURLToPath(new URL(commandToBin[command], import.meta.url));
+  const result = spawnSync(process.execPath, [binPath, ...rest], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+}
+
+process.stderr.write(`Unknown command: ${command}\nUsage: amplitude-ai <mcp|init|doctor|status>\n`);
+process.exit(1);

package/bin/validate-catalog-constants.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * Validate that EVENT_* and PROP_* constants in TypeScript source files
+ * match the canonical agent_event_catalog.json.
+ *
+ * Usage:
+ *   node packages/amplitude-ai/bin/validate-catalog-constants.mjs
+ *
+ * Checks:
+ *   - packages/amplitude-ai/src/core/constants.ts
+ *   - server/packages/temporal-worker/src/workflows/llm-analytics/constants.ts
+ *
+ * Exit code 0 = all constants covered; exit code 1 = drift detected.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const REPO_ROOT = resolve(PACKAGE_ROOT, '..', '..');
+
+const CATALOG_PATH = join(PACKAGE_ROOT, 'data', 'agent_event_catalog.json');
+
+const FILES_TO_CHECK = [
+  {
+    path: join(PACKAGE_ROOT, 'src', 'core', 'constants.ts'),
+    label: 'amplitude-ai/constants.ts',
+    allowExtra: new Set(),
+  },
+  {
+    path: join(REPO_ROOT, 'server', 'packages', 'temporal-worker', 'src', 'workflows', 'llm-analytics', 'constants.ts'),
+    label: 'temporal-worker/constants.ts',
+    allowExtra: new Set([
+      '[Agent] Tool Input Hash',
+      '[Agent] Tool Output Hash',
+      '[Agent] Tool Output Size',
+      '$llm_message',
+      '$llm_message.text',
+      '$llm_message.n',
+      '$llm_message.len',
+      '$llm_message.c',
+      'agent session id',
+      'message id',
+      'user id',
+      '$llm message',
+    ]),
+  },
+];
+
+function loadCatalog() {
+  const raw = readFileSync(CATALOG_PATH, 'utf-8');
+  const data = JSON.parse(raw);
+  const eventTypes = new Set(data.events.map((e) => e.event_type));
+  const propNames = new Set();
+  for (const event of data.events) {
+    for (const prop of event.properties) {
+      propNames.add(prop.name);
+    }
+  }
+  return { eventTypes, propNames };
+}
+
+function extractConstants(filePath) {
+  const source = readFileSync(filePath, 'utf-8');
+  const events = {};
+  const props = {};
+
+  const pattern = /export\s+const\s+(EVENT_\w+|PROP_\w+)\s*=\s*['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const [, name, value] = match;
+    if (name.startsWith('EVENT_')) {
+      events[name] = value;
+    } else if (name.startsWith('PROP_')) {
+      props[name] = value;
+    }
+  }
+
+  return { events, props };
+}
+
+function main() {
+  const { eventTypes, propNames } = loadCatalog();
+  let allOk = true;
+
+  for (const { path: filePath, label, allowExtra } of FILES_TO_CHECK) {
+    let source;
+    try {
+      source = readFileSync(filePath, 'utf-8');
+    } catch {
+      console.warn(`SKIP: ${label} not found at ${filePath}`);
+      continue;
+    }
+
+    const { events, props } = extractConstants(filePath);
+    let fileOk = true;
+
+    const eventCount = Object.keys(events).length;
+    console.log(`Checking ${eventCount} EVENT_* constants in ${label}...`);
+    for (const [name, value] of Object.entries(events).sort()) {
+      if (!eventTypes.has(value) && !allowExtra.has(value)) {
+        console.error(`  DRIFT: ${name} = "${value}" is not in agent_event_catalog.json`);
+        fileOk = false;
+      }
+    }
+
+    const propCount = Object.keys(props).length;
+    console.log(`Checking ${propCount} PROP_* constants in ${label}...`);
+    for (const [name, value] of Object.entries(props).sort()) {
+      if (!propNames.has(value) && !allowExtra.has(value)) {
+        console.error(`  DRIFT: ${name} = "${value}" is not in agent_event_catalog.json`);
+        fileOk = false;
+      }
+    }
+
+    if (fileOk) {
+      console.log(`  OK: All ${eventCount} EVENT_* and ${propCount} PROP_* constants in ${label} are covered.\n`);
+    } else {
+      allOk = false;
+    }
+  }
+
+  if (allOk) {
+    console.log('All JS constants are in sync with the catalog.');
+  } else {
+    console.error('Drift detected! Update agent_event_catalog.json or the constants files.');
+    process.exit(1);
+  }
+}
+
+main();