dimies 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# dimies
+
+Integrate [Dimies](https://dimies.com) — conversation analytics for AI agents — into any codebase in one command.
+
+```sh
+npx dimies init --key dm_live_…     # scaffold a tracking helper (Node or Python)
+npx dimies test --key dm_live_…     # send a test conversation, verify end-to-end
+npx dimies prompt                    # print an integration prompt for AI coding agents
+npx dimies spec                      # print the machine-readable spec (llms.txt)
+```
+
+## The fastest path: let your coding agent do it
+
+```sh
+npx dimies prompt | pbcopy
+```
+
+Paste into Claude Code (or Cursor, etc.) inside the repo you want instrumented. The agent fetches `llms.txt` from your Dimies instance and wires everything: fire-and-forget conversation tracking, trace spans around LLM/tool calls, env vars in `.env.example`.
+
+## What `init` does
+
+- Detects Node (TS/JS) or Python
+- Writes a zero-dependency `dimies.ts` / `dimies.js` / `dimies.py` helper exporting `trackConversation(...)` / `track_conversation(...)` — fire-and-forget, never throws, never blocks your response path
+- Adds `DIMIES_API_KEY` / `DIMIES_URL` to `.env.example` (never hardcodes your key)
+
+## Flags
+
+| Flag | Meaning |
+|---|---|
+| `--key dm_live_…` | Dimies API key (or env `DIMIES_API_KEY`) |
+| `--url https://…` | Your Dimies instance URL (or env `DIMIES_URL`) |
+| `--dir path` | Target directory for `init` (default `.`) |
+| `--lang node\|python` | Override language detection |
+
+MIT.

package/bin/dimies.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * Dimies CLI — integrate conversation analytics into any codebase.
+ *
+ *   npx dimies init  --key dm_live_… [--url https://…] [--lang node|python] [--dir .]
+ *   npx dimies test  --key dm_live_… [--url https://…]
+ *   npx dimies prompt [--url https://…]        # integration prompt for AI coding agents
+ *   npx dimies spec   [--url https://…]        # print the machine-readable spec (llms.txt)
+ *
+ * Zero dependencies. Node 18+.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_URL = process.env.DIMIES_URL || "https://app.dimies.com";
+
+/* ----------------------------- arg parsing ----------------------------- */
+
+const [, , command, ...rest] = process.argv;
+const flags = {};
+for (let i = 0; i < rest.length; i++) {
+  if (rest[i].startsWith("--")) {
+    const key = rest[i].slice(2);
+    const next = rest[i + 1];
+    if (next && !next.startsWith("--")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+}
+
+const url = String(flags.url || DEFAULT_URL).replace(/\/$/, "");
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+function die(message) {
+  console.error(red(`✖ ${message}`));
+  process.exit(1);
+}
+
+/* ------------------------------ templates ------------------------------ */
+
+const TS_HELPER = (baseUrl) => `/**
+ * Dimies — conversation analytics for AI agents.
+ * Fire-and-forget: never throws, never blocks your response path.
+ * Docs: ${baseUrl}/llms.txt
+ */
+
+type DimiesMessage = {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  timestamp?: number | string;
+};
+
+type DimiesSpan = {
+  id?: string;
+  parent_id?: string;
+  name: string;
+  type?: "llm" | "tool" | "retrieval" | "function" | "other";
+  started_at?: number | string;
+  ended_at?: number | string;
+  input?: unknown;
+  output?: unknown;
+  model?: string;
+  tokens_in?: number;
+  tokens_out?: number;
+  cost?: number;
+  status?: "ok" | "error";
+  error?: string;
+  metadata?: Record<string, unknown>;
+};
+
+const DIMIES_URL = process.env.DIMIES_URL ?? "${baseUrl}";
+const DIMIES_API_KEY = process.env.DIMIES_API_KEY ?? "";
+
+/**
+ * Send the FULL conversation so far (idempotent upsert on conversation_id).
+ * Call after each exchange, or once with closed: true when it ends.
+ */
+export function trackConversation(options: {
+  conversation_id: string;
+  messages: DimiesMessage[];
+  user_id?: string;
+  channel?: string;
+  closed?: boolean;
+  metadata?: Record<string, unknown>;
+  trace?: DimiesSpan[];
+}): void {
+  if (!DIMIES_API_KEY) return;
+  fetch(\`\${DIMIES_URL}/api/v1/conversations\`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: \`Bearer \${DIMIES_API_KEY}\`,
+    },
+    body: JSON.stringify(options),
+  }).catch(() => {
+    /* analytics must never break the product */
+  });
+}
+`;
+
+const PY_HELPER = (baseUrl) => `"""
+Dimies — conversation analytics for AI agents.
+Fire-and-forget: never raises, never blocks your response path.
+Docs: ${baseUrl}/llms.txt
+"""
+
+import json
+import os
+import threading
+import urllib.request
+
+DIMIES_URL = os.environ.get("DIMIES_URL", "${baseUrl}")
+DIMIES_API_KEY = os.environ.get("DIMIES_API_KEY", "")
+
+
+def track_conversation(
+    conversation_id: str,
+    messages: list,          # [{"role": "user"|"assistant"|"system"|"tool", "content": str}]
+    user_id: str | None = None,
+    channel: str | None = None,
+    closed: bool = False,
+    metadata: dict | None = None,
+    trace: list | None = None,  # spans: see ${baseUrl}/llms.txt
+) -> None:
+    """Send the FULL conversation so far (idempotent upsert on conversation_id)."""
+    if not DIMIES_API_KEY:
+        return
+
+    payload = {"conversation_id": conversation_id, "messages": messages, "closed": closed}
+    if user_id:
+        payload["user_id"] = user_id
+    if channel:
+        payload["channel"] = channel
+    if metadata:
+        payload["metadata"] = metadata
+    if trace:
+        payload["trace"] = trace
+
+    def _send() -> None:
+        try:
+            req = urllib.request.Request(
+                f"{DIMIES_URL}/api/v1/conversations",
+                data=json.dumps(payload).encode(),
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {DIMIES_API_KEY}",
+                },
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass  # analytics must never break the product
+
+    threading.Thread(target=_send, daemon=True).start()
+`;
+
+const AGENT_PROMPT = (baseUrl) => `Integrate Dimies conversation analytics into this codebase.
+
+1. Fetch the integration spec: ${baseUrl}/llms.txt — follow it exactly.
+2. Find where this app exchanges messages with an LLM or serves an AI agent/chatbot.
+3. After each completed exchange (or when a conversation ends), send the FULL
+   conversation to POST ${baseUrl}/api/v1/conversations with the Authorization
+   header. Prefer a small fire-and-forget helper (never block or throw on the
+   response path). If the repo uses the OpenAI or Anthropic SDK directly, the
+   zero-code alternative is swapping the client baseURL to the Dimies proxy
+   (details in the spec).
+4. Read DIMIES_API_KEY and DIMIES_URL from environment variables; add them
+   to .env.example. Never hardcode the key.
+5. If the app has tool calls / retrievals around the LLM call, also send them as
+   a "trace" array (span schema in the spec) so executions are debuggable.
+6. Verify: run the app, trigger one conversation, and confirm it appears at
+   ${baseUrl}/app (or run \`npx dimies test --key $DIMIES_API_KEY\`).
+
+My Dimies API key is in the DIMIES_API_KEY environment variable.`;
+
+/* ------------------------------ commands ------------------------------- */
+
+function detectLang(dir) {
+  if (flags.lang) return String(flags.lang);
+  if (fs.existsSync(path.join(dir, "package.json"))) return "node";
+  if (
+    fs.existsSync(path.join(dir, "pyproject.toml")) ||
+    fs.existsSync(path.join(dir, "requirements.txt")) ||
+    fs.existsSync(path.join(dir, "setup.py"))
+  ) {
+    return "python";
+  }
+  return "node";
+}
+
+function cmdInit() {
+  const dir = path.resolve(String(flags.dir || "."));
+  if (!fs.existsSync(dir)) die(`Directory not found: ${dir}`);
+  const lang = detectLang(dir);
+
+  let helperPath;
+  if (lang === "python") {
+    helperPath = path.join(dir, "dimies.py");
+    fs.writeFileSync(helperPath, PY_HELPER(url));
+  } else {
+    const isTs = fs.existsSync(path.join(dir, "tsconfig.json"));
+    const srcDir = fs.existsSync(path.join(dir, "src")) ? path.join(dir, "src") : dir;
+    helperPath = path.join(srcDir, isTs ? "dimies.ts" : "dimies.js");
+    const content = isTs
+      ? TS_HELPER(url)
+      : TS_HELPER(url)
+          .replace(/^type DimiesMessage[\s\S]*?};\n\n/m, "")
+          .replace(/^type DimiesSpan[\s\S]*?};\n\n/m, "")
+          .replace(/options: \{[\s\S]*?\}\): void \{/m, "options) {");
+    fs.writeFileSync(helperPath, content);
+  }
+
+  // .env.example entries (never write the real key into tracked files)
+  const envExample = path.join(dir, ".env.example");
+  const envLines = `\n# Dimies — conversation analytics (${url}/app/docs)\nDIMIES_API_KEY=\nDIMIES_URL=${url}\n`;
+  if (fs.existsSync(envExample)) {
+    if (!fs.readFileSync(envExample, "utf8").includes("DIMIES_API_KEY")) {
+      fs.appendFileSync(envExample, envLines);
+    }
+  } else {
+    fs.writeFileSync(envExample, envLines.trimStart());
+  }
+
+  // real key goes into .env only when provided explicitly
+  if (flags.key) {
+    const envFile = path.join(dir, ".env");
+    const line = `DIMIES_API_KEY=${flags.key}\n`;
+    if (!fs.existsSync(envFile)) fs.writeFileSync(envFile, line);
+    else if (!fs.readFileSync(envFile, "utf8").includes("DIMIES_API_KEY")) fs.appendFileSync(envFile, line);
+  }
+
+  console.log(green("✔ Dimies integration scaffolded"));
+  console.log(`  helper:   ${bold(path.relative(process.cwd(), helperPath) || helperPath)}`);
+  console.log(`  env:      DIMIES_API_KEY ${flags.key ? "written to .env" : dim("(set it in your env)")}`);
+  console.log(`\nNext: call ${bold(lang === "python" ? "track_conversation(...)" : "trackConversation(...)")} after each exchange with your agent.`);
+  console.log(`Then verify: ${bold(`npx dimies test --key <your-key> --url ${url}`)}`);
+  console.log(dim(`Full spec (also for AI coding agents): ${url}/llms.txt`));
+}
+
+async function cmdTest() {
+  const key = flags.key || process.env.DIMIES_API_KEY;
+  if (!key) die("Pass --key dm_live_… (or set DIMIES_API_KEY)");
+  const conversationId = `cli-test-${Date.now()}`;
+  const res = await fetch(`${url}/api/v1/conversations`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+    body: JSON.stringify({
+      conversation_id: conversationId,
+      user_id: "dimies-cli",
+      channel: "cli-test",
+      closed: true,
+      messages: [
+        { role: "user", content: "Hello! This is a test conversation sent by the Dimies CLI to verify the integration." },
+        { role: "assistant", content: "Integration confirmed — this conversation was ingested successfully and will be analyzed shortly." },
+      ],
+    }),
+  }).catch((err) => die(`Could not reach ${url} — ${err.message}`));
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) die(`API returned ${res.status}: ${body.error ?? "unknown error"}`);
+  console.log(green("✔ Test conversation ingested"));
+  console.log(`  conversation_id: ${bold(body.conversation_id)}`);
+  console.log(`  analysis: runs automatically within ~1 minute (conversation was sent as closed)`);
+  console.log(`  view it:  ${bold(`${url}/app/conversations`)}`);
+}
+
+function cmdPrompt() {
+  console.log(AGENT_PROMPT(url));
+}
+
+async function cmdSpec() {
+  const res = await fetch(`${url}/llms.txt`).catch((err) => die(`Could not reach ${url} — ${err.message}`));
+  if (!res.ok) die(`GET ${url}/llms.txt returned ${res.status}`);
+  console.log(await res.text());
+}
+
+function cmdHelp() {
+  console.log(`${bold("dimies")} — integrate Dimies conversation analytics
+
+${bold("Usage")}
+  npx dimies <command> [flags]
+
+${bold("Commands")}
+  init      Scaffold a tracking helper into this codebase (detects Node/Python)
+  test      Send a test conversation to verify your key + endpoint
+  prompt    Print a ready-to-paste prompt for AI coding agents (Claude Code, Cursor…)
+  spec      Print the machine-readable integration spec (llms.txt)
+
+${bold("Flags")}
+  --key <dm_live_…>   Dimies API key (or env DIMIES_API_KEY)
+  --url <https://…>   Dimies instance ${dim(`(default: ${DEFAULT_URL})`)}
+  --dir <path>        Target directory for init ${dim("(default: .)")}
+  --lang node|python  Override language detection
+
+${bold("Fastest path with Claude Code")}
+  npx dimies prompt | pbcopy   ${dim("# then paste into Claude Code")}
+`);
+}
+
+/* -------------------------------- main --------------------------------- */
+
+(async () => {
+  switch (command) {
+    case "init":
+      cmdInit();
+      break;
+    case "test":
+      await cmdTest();
+      break;
+    case "prompt":
+      cmdPrompt();
+      break;
+    case "spec":
+      await cmdSpec();
+      break;
+    default:
+      cmdHelp();
+      process.exit(command ? 1 : 0);
+  }
+})();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "dimies",
+  "version": "0.1.0",
+  "description": "Integrate Dimies (conversation analytics for AI agents) into any codebase in one command — human- and AI-coding-agent-friendly.",
+  "bin": {
+    "dimies": "bin/dimies.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "dimies",
+    "llm",
+    "analytics",
+    "observability",
+    "ai-agents",
+    "conversation-analytics"
+  ],
+  "homepage": "https://dimies.com",
+  "license": "MIT"
+}