dimies 0.1.0 → 0.1.2

package/README.md

@@ -32,4 +32,27 @@ Paste into Claude Code (or Cursor, etc.) inside the repo you want instrumented.
 | `--dir path` | Target directory for `init` (default `.`) |
 | `--lang node\|python` | Override language detection |
 
+## Tracing
+
+Pass a `trace` array of spans to `trackConversation(...)` to get a Langfuse-style execution tree on each conversation. Give every span a stable `id`, and set `input`/`output` to the payload — for an `llm` span, the prompt and the completion; for a `tool` span, the args and the result:
+
+```ts
+trackConversation({
+  conversation_id: chat.id,
+  messages,
+  trace: [
+    { id: "llm-1", name: "vera.llm", type: "llm",
+      model: "gpt-4o", tokens_in: 1240, tokens_out: 85,
+      cost: 0.0017,            // optional — exact spend; omit and Dimies estimates it
+      input: prompt, output: completion },
+  ],
+});
+```
+
+Field names are **exact** — `prompt`/`completion`/`response` are silently dropped, so a span sent that way shows *"No payload recorded"*. Merge is field-level and keyed by `id`: resend the same `id` to update a span (e.g. `{ id: "llm-1", status: "error" }`) and only the fields you include change — the rest is preserved.
+
+**Cost accuracy:** set `model`, `tokens_in`, `tokens_out` on `llm` spans and the **Costs** dashboard prices them at list rates. For **exact** spend (negotiated rates, caching), also send `cost` in USD from your provider's usage — it's used verbatim instead of the estimate.
+
+Full span schema: `<your-instance>/llms.txt`.
+
 MIT.

package/bin/dimies.js

@@ -64,12 +64,14 @@ type DimiesSpan = {
   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;
+  input?: unknown;   // the payload shown when you click the span. llm: the prompt/messages;
+  output?: unknown;  // tool: args/result; retrieval: query/docs. Names are exact — "prompt"
+                     // or "completion" are dropped. Resend only the fields you change.
+  model?: string;      // llm spans: the model id, e.g. "gpt-4o", "kimi-k2"
+  tokens_in?: number;  // prompt tokens  (needed for cost)
+  tokens_out?: number; // completion tokens (needed for cost)
+  cost?: number;       // USD. Send it for EXACT spend in the Costs dashboard;
+                       // if omitted, Dimies estimates from model + tokens at list prices.
   status?: "ok" | "error";
   error?: string;
   metadata?: Record<string, unknown>;
@@ -173,8 +175,14 @@ const AGENT_PROMPT = (baseUrl) => `Integrate Dimies conversation analytics into
    (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.
+5. If the app has LLM / tool / retrieval steps, also send them as a "trace" array
+   (span schema in the spec) so executions are debuggable. On each span set
+   "input" and "output" (exact field names) to the payload — for an llm span that
+   is the prompt and the completion; for a tool span the args and the result.
+   On llm spans also set "model", "tokens_in", "tokens_out" (from the provider's
+   usage) for cost analytics — and "cost" in USD if you want exact spend instead
+   of an estimate. Without payload the span shows "No payload recorded". Give
+   every span a stable "id" and resend only the fields you change.
 6. Verify: run the app, trigger one conversation, and confirm it appears at
    ${baseUrl}/app (or run \`npx dimies test --key $DIMIES_API_KEY\`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dimies",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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"