@cendor/core 0.2.0 → 0.3.1

package/dist/otel.js

@@ -0,0 +1,132 @@
+/**
+ * OpenTelemetry GenAI span helpers (optional) + a dependency-free `gen_ai.*` ingest path. The TS
+ * mirror of `cendor.core.otel`. Emits/reads `gen_ai.*` following the OpenTelemetry GenAI semantic
+ * conventions, so the whole stack speaks the standard everyone is converging on — no proprietary
+ * telemetry format.
+ *
+ * `span()` needs `@opentelemetry/api` (an optional peer dep); it is a **no-op when the package is
+ * absent** (never throws). `ingest()` has no OTel dependency at all — it just reads a `gen_ai.*`
+ * attribute bag. Neither touches the event bus except `ingest`, which emits the normalized `LLMCall`.
+ */
+import { createRequire } from 'node:module';
+import { emit } from './bus.js';
+import { estimate } from './prices.js';
+import { LLMCall, Usage } from './types.js';
+function loadTracer() {
+    try {
+        const req = createRequire(import.meta.url);
+        // Loaded synchronously (mirrors Python's `from opentelemetry import trace`); no-op if absent.
+        const otel = req('@opentelemetry/api');
+        return otel.trace.getTracer('cendor.core');
+    }
+    catch {
+        return null; // OpenTelemetry not installed — stay in no-op mode
+    }
+}
+/**
+ * Run `fn` inside a `gen_ai` span named `chat {model}`, setting `gen_ai.request.model`,
+ * `gen_ai.system` (= provider), and any extra attributes. The span is passed to `fn`, or **`null`
+ * when `@opentelemetry/api` is absent** — in which case `fn(null)` still runs and its value is
+ * returned (a no-op that never raises). The span is ended when `fn` returns (awaiting a returned
+ * promise first). Callback form (a `@contextmanager` in Python); `ingest()` is the bus path.
+ */
+export function span(model, opts, fn) {
+    const tracer = loadTracer();
+    if (tracer === null)
+        return fn(null);
+    const { provider, ...attributes } = opts;
+    const current = tracer.startSpan(`chat ${model}`);
+    let ended = false;
+    const end = () => {
+        if (!ended) {
+            ended = true;
+            current.end();
+        }
+    };
+    try {
+        current.setAttribute('gen_ai.request.model', model);
+        if (provider != null)
+            current.setAttribute('gen_ai.system', provider);
+        for (const [key, value] of Object.entries(attributes))
+            current.setAttribute(key, value);
+        const result = fn(current);
+        if (result != null && typeof result.then === 'function') {
+            return result.then((v) => {
+                end();
+                return v;
+            }, (e) => {
+                end();
+                throw e;
+            });
+        }
+        end();
+        return result;
+    }
+    catch (e) {
+        end();
+        throw e;
+    }
+}
+function uuidHex() {
+    return globalThis.crypto.randomUUID().replace(/-/g, '');
+}
+function attr(bag, ...keys) {
+    for (const k of keys) {
+        const v = bag[k];
+        if (v !== undefined && v !== null)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Turn OpenTelemetry GenAI (`gen_ai.*`) span attributes into a normalized `LLMCall`. This is the
+ * managed-runtime capture path: when a server-side runtime owns the loop and only emits `gen_ai.*`
+ * spans, feed those attributes here and the call joins the same event bus — so `@cendor/tokenguard`
+ * and `@cendor/acttrace` consume it exactly as if it had been instrumented locally. No OTel dependency.
+ *
+ * Reads `gen_ai.request.model` (or `response.model`), `gen_ai.system`, and the usage attributes;
+ * prices it via `@cendor/core` `prices` (missing price → `cost = null`); emits on the bus unless
+ * `emit: false`. Returns the call.
+ */
+export function ingest(attributes, opts = {}) {
+    const { messages, emit: doEmit = true } = opts;
+    const model = String(attr(attributes, 'gen_ai.request.model', 'gen_ai.response.model') ?? '');
+    const provider = String(attributes['gen_ai.system'] ?? '');
+    const inp = attr(attributes, 'gen_ai.usage.input_tokens', 'gen_ai.usage.prompt_tokens');
+    const out = attr(attributes, 'gen_ai.usage.output_tokens', 'gen_ai.usage.completion_tokens') ?? 0;
+    // Cached / reasoning breakdowns, if the runtime reports them (a couple of common spellings).
+    const cached = attr(attributes, 'gen_ai.usage.cached_tokens', 'gen_ai.usage.cache_read_input_tokens') ?? 0;
+    const reasoning = attributes['gen_ai.usage.reasoning_tokens'] ?? 0;
+    const usage = inp != null
+        ? new Usage({
+            inputTokens: Math.trunc(Number(inp)),
+            outputTokens: Math.trunc(Number(out)),
+            cachedTokens: Math.trunc(Number(cached)),
+            reasoningTokens: Math.trunc(Number(reasoning)),
+        })
+        : null;
+    const call = new LLMCall({
+        id: uuidHex(),
+        provider,
+        model,
+        messages: messages ?? [],
+        usage,
+        ts: new Date(),
+    });
+    call.metadata.source = 'otel';
+    if (usage !== null) {
+        try {
+            call.cost = estimate(call.model, usage.inputTokens, {
+                outputTokens: usage.outputTokens,
+                cachedTokens: usage.cachedTokens,
+            });
+        }
+        catch {
+            call.cost = null;
+        }
+    }
+    if (doEmit)
+        emit(call);
+    return call;
+}
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cendor/core",
-  "version": "0.2.0",
-  "description": "The shared foundation of the Cendor stack: types, event bus, decimal-safe Money, price table, token counting, and instrument(). The TypeScript port of cendor.core.",
+  "version": "0.3.1",
+  "description": "Wrap your LLM client once and capture exact token counts and cost on every call — the shared foundation the other Cendor tools build on.",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -24,6 +24,14 @@
     "decimal.js": "^10.4.3",
     "js-tiktoken": "^1.0.15"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "keywords": [
     "llm",
     "openai",