@farzanhossans/agentlens 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# @farzanhossans/agentlens
+
+Universal AI agent observability — **one line** to trace every LLM call.
+
+Patches `globalThis.fetch` and Node's `http`/`https` so every call to OpenAI,
+Anthropic, Gemini, Cohere, or Mistral is captured automatically. No SDK
+wrappers. No code changes inside your call sites.
+
+## Install
+
+```bash
+pnpm add @farzanhossans/agentlens
+# or: npm i @farzanhossans/agentlens
+```
+
+## Quickstart
+
+### 1. Cloud — zero config (default)
+
+```ts
+import { AgentLens } from '@farzanhossans/agentlens'
+
+AgentLens.init({ apiKey: 'proj_xxx' })
+```
+
+### 2. Self-hosted — point at your own ingest endpoint
+
+```ts
+import { AgentLens } from '@farzanhossans/agentlens'
+
+AgentLens.init({
+  apiKey: 'proj_xxx', // key from your own AgentLens dashboard
+  endpoint: 'https://agentlens.your-company.com/v1/spans',
+})
+```
+
+### 3. Self-hosted + debug mode (logs each captured span to stdout)
+
+```ts
+AgentLens.init({
+  apiKey: 'proj_xxx',
+  endpoint: 'https://agentlens.your-company.com/v1/spans',
+  debug: true,
+})
+```
+
+### 4. Disable PII scrubbing (only for trusted internal data)
+
+```ts
+AgentLens.init({
+  apiKey: 'proj_xxx',
+  pii: false,
+})
+```
+
+## What gets captured
+
+For every matched LLM HTTP call:
+
+- `provider` and `model`
+- `inputTokens`, `outputTokens`, `totalTokens`
+- `costUsd` (calculated from a built-in price table per provider)
+- `inputText` and `outputText` (PII-scrubbed by default)
+- `latency` and `status`
+- `isStream` flag — streaming responses are tapped via `ReadableStream.tee()` so
+  the stream you read is byte-identical to the original
+
+## Supported providers
+
+All five providers support both streaming and non-streaming responses.
+
+| Provider  | Hosts                                  | Endpoints                                                      | Streaming |
+| --------- | -------------------------------------- | -------------------------------------------------------------- | --------- |
+| OpenAI    | `api.openai.com`                       | `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`    | ✅        |
+| Anthropic | `api.anthropic.com`                    | `/v1/messages`                                                 | ✅        |
+| Gemini    | `generativelanguage.googleapis.com`    | `/v1beta/models`, `/v1/models`                                 | ✅        |
+| Cohere    | `api.cohere.com`                       | `/v1/chat`, `/v1/generate`, `/v2/chat` (v1 + v2 stream shapes) | ✅        |
+| Mistral   | `api.mistral.ai`                       | `/v1/chat/completions`                                         | ✅        |
+
+## Grouping calls with `trace()`
+
+Wrap a logical unit of work (an agent step, a multi-call retrieval, etc.) in
+`AgentLens.trace(name, fn)`. Every LLM call inside `fn` — including async ones
+and across nested traces — is auto-tagged with the same `traceId` and gets
+`parentSpanId` set to the trace's span. Built on Node's `AsyncLocalStorage`,
+so it composes with `Promise.all`, `setTimeout`, async generators, etc.
+
+```ts
+import { AgentLens } from '@farzanhossans/agentlens'
+
+AgentLens.init({ apiKey: 'proj_xxx' })
+
+await AgentLens.trace('classify-then-rephrase', async () => {
+  const classification = await openai.chat.completions.create({ ... })
+  // ↑ span emitted with parentSpanId = the trace's spanId
+  const rephrased = await anthropic.messages.create({ ... })
+  // ↑ same trace, same parentSpanId
+})
+```
+
+Nested traces nest:
+
+```ts
+await AgentLens.trace('outer', async () => {
+  await AgentLens.trace('inner', async () => {
+    await openai.chat.completions.create({ ... })
+    // child of `inner`, which is child of `outer`, all sharing one traceId
+  })
+})
+```
+
+## PII scrubbing
+
+Enabled by default. Strips emails, phone numbers, SSNs, credit cards, IPv4
+addresses, and obvious API-key shapes from `inputText` / `outputText` before
+spans leave your process. Pass `pii: false` to disable.
+
+## Self-hosted flow
+
+1. Deploy AgentLens via Docker Compose on your own server
+2. Open your own dashboard → create a project → copy the API key
+3. `AgentLens.init({ apiKey, endpoint })` pointing at your own ingest URL
+4. Spans flow: your app → your worker → your DB. Nothing touches AgentLens cloud.
+
+## API
+
+```ts
+AgentLens.init(config: {
+  apiKey: string
+  endpoint?: string       // default: https://ingest.agentlens.dev/v1/spans
+  debug?: boolean         // default: false
+  pii?: boolean           // default: true
+  flushIntervalMs?: number // default: 500
+  maxBatchSize?: number   // default: 50
+}): void
+
+AgentLens.flush(): Promise<void>   // force-flush pending spans
+AgentLens.shutdown(): void         // stop the flush timer
+
+AgentLens.trace<T>(name: string, fn: () => Promise<T>): Promise<T>
+// re-exports from @farzanhossans/agentlens-core:
+getCurrentTrace(), getCurrentTraceId(), getCurrentSpanId(), runWithTrace(ctx, fn)
+```
+
+## Requirements
+
+Node ≥ 18 (the SDK uses `AsyncLocalStorage`, `globalThis.fetch`, and `crypto.randomUUID`).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+export { getCurrentSpanId, getCurrentTrace, getCurrentTraceId, runWithTrace } from '@farzanhossans/agentlens-core';
+
+type ParserName = 'openai' | 'anthropic' | 'gemini' | 'cohere' | 'mistral';
+interface LLMEndpoint {
+    provider: string;
+    parser: ParserName;
+    paths: string[];
+}
+interface ParsedSpan {
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    inputText: string;
+    outputText: string;
+    isStream: boolean;
+    error?: string;
+}
+interface AgentLensConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    pii?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+}
+interface OutboundSpan extends ParsedSpan {
+    spanId: string;
+    traceId: string;
+    parentSpanId?: string;
+    timestamp: string;
+    latency: number;
+    status: number;
+}
+
+declare const LLM_REGISTRY: Record<string, LLMEndpoint>;
+declare function matchLLM(url: string): LLMEndpoint | null;
+
+declare function scrubPII(text: string): string;
+declare function scrubObject(obj: unknown): unknown;
+
+declare const AgentLens: {
+    init(config: AgentLensConfig): void;
+    flush(): Promise<void>;
+    shutdown(): void;
+    /**
+     * Wraps `fn` in a named trace context. Any LLM calls made inside `fn`
+     * (including async ones) are auto-tagged with this trace's `traceId` and
+     * get `parentSpanId` set to this trace's `spanId`. Nested `trace()` calls
+     * become child spans automatically.
+     *
+     * Use this to group multiple LLM calls that belong to the same agent run.
+     */
+    trace<T>(_name: string, fn: () => Promise<T>): Promise<T>;
+};
+
+export { AgentLens, type AgentLensConfig, LLM_REGISTRY, type OutboundSpan, type ParsedSpan, matchLLM, scrubObject, scrubPII };

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+export { getCurrentSpanId, getCurrentTrace, getCurrentTraceId, runWithTrace } from '@farzanhossans/agentlens-core';
+
+type ParserName = 'openai' | 'anthropic' | 'gemini' | 'cohere' | 'mistral';
+interface LLMEndpoint {
+    provider: string;
+    parser: ParserName;
+    paths: string[];
+}
+interface ParsedSpan {
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    inputText: string;
+    outputText: string;
+    isStream: boolean;
+    error?: string;
+}
+interface AgentLensConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    pii?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+}
+interface OutboundSpan extends ParsedSpan {
+    spanId: string;
+    traceId: string;
+    parentSpanId?: string;
+    timestamp: string;
+    latency: number;
+    status: number;
+}
+
+declare const LLM_REGISTRY: Record<string, LLMEndpoint>;
+declare function matchLLM(url: string): LLMEndpoint | null;
+
+declare function scrubPII(text: string): string;
+declare function scrubObject(obj: unknown): unknown;
+
+declare const AgentLens: {
+    init(config: AgentLensConfig): void;
+    flush(): Promise<void>;
+    shutdown(): void;
+    /**
+     * Wraps `fn` in a named trace context. Any LLM calls made inside `fn`
+     * (including async ones) are auto-tagged with this trace's `traceId` and
+     * get `parentSpanId` set to this trace's `spanId`. Nested `trace()` calls
+     * become child spans automatically.
+     *
+     * Use this to group multiple LLM calls that belong to the same agent run.
+     */
+    trace<T>(_name: string, fn: () => Promise<T>): Promise<T>;
+};
+
+export { AgentLens, type AgentLensConfig, LLM_REGISTRY, type OutboundSpan, type ParsedSpan, matchLLM, scrubObject, scrubPII };