opsveritas-sdk 0.1.4 → 0.3.0

package/README.md

@@ -0,0 +1,79 @@
+# opsveritas-sdk
+
+Monitor your AI agents in **three lines of code**. Tracks tokens, cost, latency, model, and silent failures (200 OK with empty output) — and routes alerts to Slack / Email / Teams via [OpsVeritas AI Agents Control Tower](https://agents.opsveritas.com).
+
+```bash
+npm install opsveritas-sdk
+```
+
+## Quick start (3 lines)
+
+```ts
+import { OpsVeritas } from 'opsveritas-sdk';
+
+OpsVeritas.init('<your-ingest-key>');                 // key from Settings → Integrations
+const client = OpsVeritas.wrap(new OpenAI(), { agentName: 'Support Bot' });
+// use `client` exactly as before — runs appear in your dashboard automatically
+```
+
+Works the same for Anthropic and Gemini clients. Prefer manual control? Wrap a function:
+
+```ts
+await OpsVeritas.trace('Nightly Report', async () => runReport());
+```
+
+## LangChain (one line)
+
+Attach the handler to any LangChain chat model, LLM or chain — every call reports token / cost / latency / silent-failure automatically:
+
+```ts
+import { ChatOpenAI } from '@langchain/openai';
+import { OpsVeritas } from 'opsveritas-sdk';
+
+OpsVeritas.init('<your-ingest-key>');
+const model = new ChatOpenAI({ callbacks: [OpsVeritas.langchain('My Agent')] });
+```
+
+No extra dependency — it's a plain LangChain callback handler. Works with any LangChain-backed provider (OpenAI, Anthropic, Gemini, Groq…). Inside `OpsVeritas.run(...)` the handler aggregates into a single execution instead of double-counting.
+
+## What data is sent
+
+By design the SDK sends **metadata only, plus a short output snippet** — never your prompts/inputs:
+
+| Sent | Detail |
+|------|--------|
+| ✅ Metadata | agent name, status, timestamps, duration, token counts, model, cost, tool-call count |
+| ⚠️ Output snippet | first 300 chars of the response (`output_summary`) — powers silent-failure detection |
+| ⚠️ Error message | the exception text, if a call fails |
+| ❌ Prompts / inputs | **never sent** — only token counts |
+
+### Metadata-only mode (for regulated / client data)
+
+Drop the output snippet and redact error text so **no response content ever leaves your environment** — token/cost/latency metadata still flows:
+
+```ts
+OpsVeritas.init('<your-ingest-key>', { metadataOnly: true });
+```
+
+Or set the environment variable:
+
+```bash
+OPSVERITAS_METADATA_ONLY=true
+```
+
+## Reliability
+
+Telemetry is **non-blocking and fire-and-forget** — it never throws into your code and never slows your agent. If the ingest endpoint is briefly unreachable, sends are **retried with backoff** and **buffered in memory** (bounded), then flushed on the next event — so a transient outage doesn't lose telemetry.
+
+## Configuration
+
+```ts
+OpsVeritas.init(apiKey, {
+  endpoint,      // optional — defaults to https://agents.opsveritas.com
+  metadataOnly,  // optional — default false; when true, no response content is sent
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 declare function init(apiKey: string, options?: {
     endpoint?: string;
+    metadataOnly?: boolean;
 }): void;
 
 declare function run<T>(agentName: string, fn: () => Promise<T>, opts?: {
@@ -19,6 +20,26 @@ interface WrapOptions {
 }
 declare function wrap<T extends object>(client: T, opts: WrapOptions): T;
 
+/**
+ * LangChain integration — one-line callback handler.
+ *
+ *   import { ChatOpenAI } from '@langchain/openai';
+ *   import opsveritas from 'opsveritas-sdk';
+ *
+ *   opsveritas.init('<key>');
+ *   const model = new ChatOpenAI({ callbacks: [opsveritas.langchain('My Agent')] });
+ *   // every LLM call now reports token / cost / latency / silent-failure to OpsVeritas
+ *
+ * Returns a plain CallbackHandlerMethods object — LangChain.js accepts this shape
+ * directly in the `callbacks` array, so there's no @langchain/core dependency.
+ * Reuses the same ingest, pricing and silent-failure semantics as wrap()/run().
+ */
+interface LangChainOptions {
+    platform?: string;
+    userId?: string;
+}
+declare function langchain(agentName: string, opts?: LangChainOptions): Record<string, unknown>;
+
 interface ExecutionPayload {
     platform: string;
     agent_name: string;
@@ -42,6 +63,7 @@ declare const OpsVeritas: {
     run: typeof run;
     trace: typeof trace;
     wrap: typeof wrap;
+    langchain: typeof langchain;
 };
 
-export { type ExecutionPayload, OpsVeritas, type TraceOptions, type WrapOptions, OpsVeritas as default, init, run, trace, wrap };
+export { type ExecutionPayload, type LangChainOptions, OpsVeritas, type TraceOptions, type WrapOptions, OpsVeritas as default, init, langchain, run, trace, wrap };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 declare function init(apiKey: string, options?: {
     endpoint?: string;
+    metadataOnly?: boolean;
 }): void;
 
 declare function run<T>(agentName: string, fn: () => Promise<T>, opts?: {
@@ -19,6 +20,26 @@ interface WrapOptions {
 }
 declare function wrap<T extends object>(client: T, opts: WrapOptions): T;
 
+/**
+ * LangChain integration — one-line callback handler.
+ *
+ *   import { ChatOpenAI } from '@langchain/openai';
+ *   import opsveritas from 'opsveritas-sdk';
+ *
+ *   opsveritas.init('<key>');
+ *   const model = new ChatOpenAI({ callbacks: [opsveritas.langchain('My Agent')] });
+ *   // every LLM call now reports token / cost / latency / silent-failure to OpsVeritas
+ *
+ * Returns a plain CallbackHandlerMethods object — LangChain.js accepts this shape
+ * directly in the `callbacks` array, so there's no @langchain/core dependency.
+ * Reuses the same ingest, pricing and silent-failure semantics as wrap()/run().
+ */
+interface LangChainOptions {
+    platform?: string;
+    userId?: string;
+}
+declare function langchain(agentName: string, opts?: LangChainOptions): Record<string, unknown>;
+
 interface ExecutionPayload {
     platform: string;
     agent_name: string;
@@ -42,6 +63,7 @@ declare const OpsVeritas: {
     run: typeof run;
     trace: typeof trace;
     wrap: typeof wrap;
+    langchain: typeof langchain;
 };
 
-export { type ExecutionPayload, OpsVeritas, type TraceOptions, type WrapOptions, OpsVeritas as default, init, run, trace, wrap };
+export { type ExecutionPayload, type LangChainOptions, OpsVeritas, type TraceOptions, type WrapOptions, OpsVeritas as default, init, langchain, run, trace, wrap };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   OpsVeritas: () => OpsVeritas,
   default: () => index_default,
   init: () => init,
+  langchain: () => langchain,
   run: () => run,
   trace: () => trace,
   wrap: () => wrap
@@ -35,7 +36,9 @@ function init(apiKey, options) {
   if (!apiKey || typeof apiKey !== "string") throw new Error("[OpsVeritas] apiKey is required");
   _config = {
     apiKey,
-    endpoint: (options?.endpoint ?? "https://agents.opsveritas.com").replace(/\/$/, "")
+    endpoint: (options?.endpoint ?? "https://agents.opsveritas.com").replace(/\/$/, ""),
+    // Opt-in via init() or the OPSVERITAS_METADATA_ONLY=true env var. Defaults off (unchanged behavior).
+    metadataOnly: options?.metadataOnly ?? (typeof process !== "undefined" && process.env?.OPSVERITAS_METADATA_ONLY === "true")
   };
 }
 function getConfig() {
@@ -47,20 +50,78 @@ function getConfig() {
 var import_async_hooks = require("async_hooks");
 
 // src/http.ts
-async function sendExecution(payload) {
-  const { apiKey, endpoint } = getConfig();
+var RETRY_BACKOFF_MS = [500, 2e3, 5e3];
+var MAX_BUFFER = 200;
+var buffer = [];
+var flushing = false;
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t?.unref === "function") t.unref();
+  });
+}
+function scrubForMetadataOnly(payload) {
+  return {
+    ...payload,
+    output_summary: void 0,
+    error_message: payload.error_message != null ? "[redacted \u2014 metadata-only mode]" : payload.error_message
+  };
+}
+async function postOnce(endpoint, apiKey, body) {
   try {
-    await fetch(`${endpoint}/webhooks/agent-execution`, {
+    const res = await fetch(`${endpoint}/webhooks/agent-execution`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-opsveritas-key": apiKey
-      },
-      body: JSON.stringify(payload)
+      headers: { "Content-Type": "application/json", "x-opsveritas-key": apiKey },
+      body: JSON.stringify(body)
     });
+    if (res.ok) return "ok";
+    if (res.status >= 400 && res.status < 500) return "drop";
+    return "retry";
   } catch {
+    return "retry";
+  }
+}
+async function deliver(endpoint, apiKey, body) {
+  for (let attempt = 0; ; attempt++) {
+    const outcome = await postOnce(endpoint, apiKey, body);
+    if (outcome === "ok" || outcome === "drop") return true;
+    if (attempt >= RETRY_BACKOFF_MS.length) return false;
+    await sleep(RETRY_BACKOFF_MS[attempt]);
   }
 }
+function enqueue(body) {
+  buffer.push(body);
+  while (buffer.length > MAX_BUFFER) buffer.shift();
+}
+async function flush(endpoint, apiKey) {
+  if (flushing || buffer.length === 0) return;
+  flushing = true;
+  try {
+    const pending = buffer.splice(0, buffer.length);
+    for (let i = 0; i < pending.length; i++) {
+      const ok = await deliver(endpoint, apiKey, pending[i]);
+      if (!ok) {
+        for (let j = pending.length - 1; j >= i; j--) buffer.unshift(pending[j]);
+        break;
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+async function sendExecution(payload) {
+  let cfg;
+  try {
+    cfg = getConfig();
+  } catch {
+    return;
+  }
+  const { apiKey, endpoint, metadataOnly } = cfg;
+  const body = metadataOnly ? scrubForMetadataOnly(payload) : payload;
+  void flush(endpoint, apiKey);
+  const ok = await deliver(endpoint, apiKey, body);
+  if (!ok) enqueue(body);
+}
 
 // src/context.ts
 var storage = new import_async_hooks.AsyncLocalStorage();
@@ -472,13 +533,119 @@ function wrap(client, opts) {
   return client;
 }
 
+// src/langchain.ts
+function extractUsage2(output) {
+  let model;
+  let inputTokens;
+  let outputTokens;
+  const lo = output?.llmOutput;
+  if (lo && typeof lo === "object") {
+    const tu = lo.tokenUsage ?? lo.token_usage ?? lo.usage;
+    if (tu && typeof tu === "object") {
+      inputTokens = tu.promptTokens ?? tu.prompt_tokens ?? tu.inputTokens ?? tu.input_tokens;
+      outputTokens = tu.completionTokens ?? tu.completion_tokens ?? tu.outputTokens ?? tu.output_tokens;
+    }
+    model = lo.model_name ?? lo.modelName ?? lo.model;
+  }
+  if (inputTokens == null || !model) {
+    try {
+      for (const genList of output?.generations ?? []) {
+        for (const gen of genList) {
+          const msg = gen?.message;
+          const um = msg?.usage_metadata ?? msg?.usageMetadata;
+          if (um && inputTokens == null) {
+            inputTokens = um.input_tokens ?? um.inputTokens;
+            outputTokens = um.output_tokens ?? um.outputTokens;
+          }
+          const rm = msg?.response_metadata ?? msg?.responseMetadata;
+          if (rm && !model) model = rm.model_name ?? rm.modelName ?? rm.model;
+        }
+      }
+    } catch {
+    }
+  }
+  return { model: model != null ? String(model) : void 0, inputTokens, outputTokens };
+}
+function extractText(output) {
+  try {
+    for (const genList of output?.generations ?? []) {
+      for (const gen of genList) {
+        let t = gen?.text;
+        if (!t) {
+          const c = gen?.message?.content;
+          if (typeof c === "string") t = c;
+        }
+        if (typeof t === "string" && t.trim()) return t.slice(0, 300);
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
+function langchain(agentName, opts = {}) {
+  const platform = opts.platform ?? "sdk";
+  const starts = /* @__PURE__ */ new Map();
+  const begin = (runId) => {
+    starts.set(runId, { t0: Date.now(), executedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  };
+  const finish = (status, output, errorMessage, runId) => {
+    const s = starts.get(runId);
+    starts.delete(runId);
+    const duration_ms = s ? Date.now() - s.t0 : 0;
+    const executed_at = s?.executedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+    const { model, inputTokens, outputTokens } = output ? extractUsage2(output) : {};
+    const cost_usd = model && inputTokens != null && outputTokens != null ? calcCost(model, inputTokens, outputTokens) : void 0;
+    const activeRun = getActiveRun();
+    if (activeRun) {
+      activeRun.calls.push({ platform, model, inputTokens, outputTokens, costUsd: cost_usd, status });
+    } else {
+      void sendExecution({
+        platform,
+        agent_name: agentName,
+        status,
+        executed_at,
+        duration_ms,
+        model,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cost_usd,
+        error_message: errorMessage ?? null,
+        output_summary: output ? extractText(output) : void 0,
+        user_id: opts.userId
+      });
+    }
+  };
+  return {
+    name: "opsveritas",
+    handleLLMStart(_llm, _prompts, runId) {
+      begin(runId);
+    },
+    handleChatModelStart(_llm, _messages, runId) {
+      begin(runId);
+    },
+    handleLLMEnd(output, runId) {
+      try {
+        finish("success", output, void 0, runId);
+      } catch {
+      }
+    },
+    handleLLMError(err, runId) {
+      try {
+        finish("failed", void 0, err instanceof Error ? err.message : String(err), runId);
+      } catch {
+      }
+    }
+  };
+}
+
 // src/index.ts
-var OpsVeritas = { init, run, trace, wrap };
+var OpsVeritas = { init, run, trace, wrap, langchain };
 var index_default = OpsVeritas;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OpsVeritas,
   init,
+  langchain,
   run,
   trace,
   wrap

package/dist/index.mjs

@@ -4,7 +4,9 @@ function init(apiKey, options) {
   if (!apiKey || typeof apiKey !== "string") throw new Error("[OpsVeritas] apiKey is required");
   _config = {
     apiKey,
-    endpoint: (options?.endpoint ?? "https://agents.opsveritas.com").replace(/\/$/, "")
+    endpoint: (options?.endpoint ?? "https://agents.opsveritas.com").replace(/\/$/, ""),
+    // Opt-in via init() or the OPSVERITAS_METADATA_ONLY=true env var. Defaults off (unchanged behavior).
+    metadataOnly: options?.metadataOnly ?? (typeof process !== "undefined" && process.env?.OPSVERITAS_METADATA_ONLY === "true")
   };
 }
 function getConfig() {
@@ -16,20 +18,78 @@ function getConfig() {
 import { AsyncLocalStorage } from "async_hooks";
 
 // src/http.ts
-async function sendExecution(payload) {
-  const { apiKey, endpoint } = getConfig();
+var RETRY_BACKOFF_MS = [500, 2e3, 5e3];
+var MAX_BUFFER = 200;
+var buffer = [];
+var flushing = false;
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t?.unref === "function") t.unref();
+  });
+}
+function scrubForMetadataOnly(payload) {
+  return {
+    ...payload,
+    output_summary: void 0,
+    error_message: payload.error_message != null ? "[redacted \u2014 metadata-only mode]" : payload.error_message
+  };
+}
+async function postOnce(endpoint, apiKey, body) {
   try {
-    await fetch(`${endpoint}/webhooks/agent-execution`, {
+    const res = await fetch(`${endpoint}/webhooks/agent-execution`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-opsveritas-key": apiKey
-      },
-      body: JSON.stringify(payload)
+      headers: { "Content-Type": "application/json", "x-opsveritas-key": apiKey },
+      body: JSON.stringify(body)
     });
+    if (res.ok) return "ok";
+    if (res.status >= 400 && res.status < 500) return "drop";
+    return "retry";
   } catch {
+    return "retry";
+  }
+}
+async function deliver(endpoint, apiKey, body) {
+  for (let attempt = 0; ; attempt++) {
+    const outcome = await postOnce(endpoint, apiKey, body);
+    if (outcome === "ok" || outcome === "drop") return true;
+    if (attempt >= RETRY_BACKOFF_MS.length) return false;
+    await sleep(RETRY_BACKOFF_MS[attempt]);
   }
 }
+function enqueue(body) {
+  buffer.push(body);
+  while (buffer.length > MAX_BUFFER) buffer.shift();
+}
+async function flush(endpoint, apiKey) {
+  if (flushing || buffer.length === 0) return;
+  flushing = true;
+  try {
+    const pending = buffer.splice(0, buffer.length);
+    for (let i = 0; i < pending.length; i++) {
+      const ok = await deliver(endpoint, apiKey, pending[i]);
+      if (!ok) {
+        for (let j = pending.length - 1; j >= i; j--) buffer.unshift(pending[j]);
+        break;
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+async function sendExecution(payload) {
+  let cfg;
+  try {
+    cfg = getConfig();
+  } catch {
+    return;
+  }
+  const { apiKey, endpoint, metadataOnly } = cfg;
+  const body = metadataOnly ? scrubForMetadataOnly(payload) : payload;
+  void flush(endpoint, apiKey);
+  const ok = await deliver(endpoint, apiKey, body);
+  if (!ok) enqueue(body);
+}
 
 // src/context.ts
 var storage = new AsyncLocalStorage();
@@ -441,13 +501,119 @@ function wrap(client, opts) {
   return client;
 }
 
+// src/langchain.ts
+function extractUsage2(output) {
+  let model;
+  let inputTokens;
+  let outputTokens;
+  const lo = output?.llmOutput;
+  if (lo && typeof lo === "object") {
+    const tu = lo.tokenUsage ?? lo.token_usage ?? lo.usage;
+    if (tu && typeof tu === "object") {
+      inputTokens = tu.promptTokens ?? tu.prompt_tokens ?? tu.inputTokens ?? tu.input_tokens;
+      outputTokens = tu.completionTokens ?? tu.completion_tokens ?? tu.outputTokens ?? tu.output_tokens;
+    }
+    model = lo.model_name ?? lo.modelName ?? lo.model;
+  }
+  if (inputTokens == null || !model) {
+    try {
+      for (const genList of output?.generations ?? []) {
+        for (const gen of genList) {
+          const msg = gen?.message;
+          const um = msg?.usage_metadata ?? msg?.usageMetadata;
+          if (um && inputTokens == null) {
+            inputTokens = um.input_tokens ?? um.inputTokens;
+            outputTokens = um.output_tokens ?? um.outputTokens;
+          }
+          const rm = msg?.response_metadata ?? msg?.responseMetadata;
+          if (rm && !model) model = rm.model_name ?? rm.modelName ?? rm.model;
+        }
+      }
+    } catch {
+    }
+  }
+  return { model: model != null ? String(model) : void 0, inputTokens, outputTokens };
+}
+function extractText(output) {
+  try {
+    for (const genList of output?.generations ?? []) {
+      for (const gen of genList) {
+        let t = gen?.text;
+        if (!t) {
+          const c = gen?.message?.content;
+          if (typeof c === "string") t = c;
+        }
+        if (typeof t === "string" && t.trim()) return t.slice(0, 300);
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
+function langchain(agentName, opts = {}) {
+  const platform = opts.platform ?? "sdk";
+  const starts = /* @__PURE__ */ new Map();
+  const begin = (runId) => {
+    starts.set(runId, { t0: Date.now(), executedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  };
+  const finish = (status, output, errorMessage, runId) => {
+    const s = starts.get(runId);
+    starts.delete(runId);
+    const duration_ms = s ? Date.now() - s.t0 : 0;
+    const executed_at = s?.executedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+    const { model, inputTokens, outputTokens } = output ? extractUsage2(output) : {};
+    const cost_usd = model && inputTokens != null && outputTokens != null ? calcCost(model, inputTokens, outputTokens) : void 0;
+    const activeRun = getActiveRun();
+    if (activeRun) {
+      activeRun.calls.push({ platform, model, inputTokens, outputTokens, costUsd: cost_usd, status });
+    } else {
+      void sendExecution({
+        platform,
+        agent_name: agentName,
+        status,
+        executed_at,
+        duration_ms,
+        model,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cost_usd,
+        error_message: errorMessage ?? null,
+        output_summary: output ? extractText(output) : void 0,
+        user_id: opts.userId
+      });
+    }
+  };
+  return {
+    name: "opsveritas",
+    handleLLMStart(_llm, _prompts, runId) {
+      begin(runId);
+    },
+    handleChatModelStart(_llm, _messages, runId) {
+      begin(runId);
+    },
+    handleLLMEnd(output, runId) {
+      try {
+        finish("success", output, void 0, runId);
+      } catch {
+      }
+    },
+    handleLLMError(err, runId) {
+      try {
+        finish("failed", void 0, err instanceof Error ? err.message : String(err), runId);
+      } catch {
+      }
+    }
+  };
+}
+
 // src/index.ts
-var OpsVeritas = { init, run, trace, wrap };
+var OpsVeritas = { init, run, trace, wrap, langchain };
 var index_default = OpsVeritas;
 export {
   OpsVeritas,
   index_default as default,
   init,
+  langchain,
   run,
   trace,
   wrap

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opsveritas-sdk",
-  "version": "0.1.4",
-  "description": "Monitor your AI agents with 2 lines of code",
+  "version": "0.3.0",
+  "description": "Monitor your AI agents in 3 lines of code — tokens, cost, latency, and silent failures",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -30,12 +30,16 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.20.0",
+    "@langchain/core": ">=0.2.0",
     "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sdk": {
       "optional": true
     },
+    "@langchain/core": {
+      "optional": true
+    },
     "openai": {
       "optional": true
     }