neatlogs 1.1.18 → 1.1.20

package/README.md

@@ -7,18 +7,15 @@ Automatically trace LLM calls, agent workflows, tool invocations, and retrieval
 ## Quick Start
 
 ```typescript
-import { init, span, shutdown } from 'neatlogs';
+import { init, span, shutdown, wrapOpenAI } from 'neatlogs';
 import OpenAI from 'openai';
 
 async function main() {
   // 1. Initialize the SDK
-  await init({
-    apiKey: process.env.NEATLOGS_API_KEY,
-    instrumentations: ['openai'],
-  });
+  await init({ apiKey: process.env.NEATLOGS_API_KEY });
 
-  // 2. Create your LLM client AFTER init()
-  const client = new OpenAI();
+  // 2. Explicitly wrap the provider client
+  const client = wrapOpenAI(new OpenAI());
 
   // 3. Wrap functions with span() for observability
   const myWorkflow = span({ kind: 'WORKFLOW', name: 'qa-bot' }, async (query: string) => {
@@ -44,56 +41,49 @@ main().catch(console.error);
 npm install neatlogs
 ```
 
-For auto-instrumentation of specific LLM providers, install the corresponding peer dependency:
-
-```bash
-# OpenAI
-npm install @arizeai/openinference-instrumentation-openai
-
-# Anthropic
-npm install @arizeai/openinference-instrumentation-anthropic
-
-# AWS Bedrock
-npm install @arizeai/openinference-instrumentation-bedrock
-
-# LangChain
-npm install @arizeai/openinference-instrumentation-langchain
-
-# MCP (Model Context Protocol)
-npm install @arizeai/openinference-instrumentation-mcp
-
-# BeeAI
-npm install @arizeai/openinference-instrumentation-beeai
-
-# Claude Agent SDK
-npm install @arizeai/openinference-instrumentation-claude-agent-sdk
-
-# Google GenAI (@google/genai)
-npm install @google/genai
-```
+Install the provider or framework package you already use, then apply its
+documented Neatlogs wrapper, hook, processor, or telemetry helper.
 
 ## Core Concepts
 
 | Function | Purpose |
 |----------|---------|
-| `init()` | Initialize the SDK — sets up OTel providers, exporters, and instrumentation |
+| `init()` | Initialize the SDK — sets up private OTel providers and exporters |
 | `span()` | Wrap a function with observability — captures inputs, outputs, timing, and errors |
 | `trace()` | Create a manual span with prompt template tracking and multi-turn session support |
 | `log()` | Capture timestamped log steps within the active trace |
 | `shutdown()` | Flush all pending data and shut down the SDK gracefully |
 
-### Important: Initialization Order
+## Doctor v2
 
-`init()` is **async** and must be called **before** creating any LLM client instances. This is because instrumentation works by monkey-patching libraries at init time.
+Run the local SDK pipeline check without credentials or network access:
 
-```typescript
-// ✅ Correct
-await init({ instrumentations: ['openai'] });
-const client = new OpenAI(); // patched
+```bash
+npx neatlogs doctor --local --json
+```
+
+Run the controlled end-to-end probe explicitly:
+
+```bash
+NEATLOGS_API_KEY=<project-key> \
+NEATLOGS_ENDPOINT=https://ingest.neatlogs.com \
+npx neatlogs doctor --probe --json
+```
+
+Probe mode exports four generated spans through the normal `/v1/traces` route
+with `x-neatlogs-doctor: v1`, flushes, and polls
+`/api/traces/v3/:traceId` for that exact trace. It passes only after persisted
+hierarchy, span semantics, input/output, versioned metadata, and numeric token
+totals validate. It does not call an LLM or inspect user data.
+
+### Important: Explicit integration
 
-// ❌ Wrong — client created before patching
-const client = new OpenAI(); // NOT patched
-await init({ instrumentations: ['openai'] });
+`init()` does not monkey-patch provider libraries. Use the documented explicit
+wrapper, hook, processor, or telemetry helper for each integration.
+
+```typescript
+await init({ apiKey: process.env.NEATLOGS_API_KEY });
+const client = wrapOpenAI(new OpenAI());
 ```
 
 ### Important: No Top-Level Await
@@ -119,7 +109,6 @@ Initialize the Neatlogs SDK. Returns `Promise<void>`.
 ```typescript
 await init({
   apiKey: process.env.NEATLOGS_API_KEY,
-  instrumentations: ['openai', 'anthropic'],
   debug: true,
 });
 ```
@@ -129,7 +118,6 @@ await init({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | `string` | `process.env.NEATLOGS_API_KEY` | Neatlogs API key. Export disabled if not set. |
-| `baseUrl` | `string` | `'https://app.neatlogs.com'` | Base URL for the Neatlogs API. |
 | `workflowName` | `string` | Derived from `process.argv[1]` | Name of the workflow being traced. |
 | `sessionId` | `string` | — | Explicit session ID for grouping traces. |
 | `autoSession` | `boolean` | `false` | Auto-generate a session ID if none provided. |
@@ -138,19 +126,49 @@ await init({
 | `metadata` | `Record<string, any>` | — | Custom metadata attached to all spans. |
 | `debug` | `boolean` | `false` | Enable debug logging. |
 | `disableExport` | `boolean` | `false` | Disable export to Neatlogs backend. |
-| `instrumentations` | `string[]` | — | Legacy manager path. Instrumentors that depend on global OTel context are rejected; use explicit wrappers below. |
 | `tracerProvider` | `BasicTracerProvider` | Private SDK provider | Optional caller-owned private provider. It is never registered globally or shut down by Neatlogs. |
 | `registerShutdownHandlers` | `boolean` | `true` for SDK-owned provider | Register process exit/signal handlers. Set `false` when the host application owns shutdown. |
 | `mask` | `MaskFunction` | — | Global mask function applied to all spans. |
 | `sampleRate` | `number` | `1.0` | Sampling rate (0.0 to 1.0). |
 | `captureLogs` | `boolean` | `false` | Capture log records via OTel LoggerProvider. |
-| `traceContent` | `boolean` | `true` | Capture input/output content on spans. |
 | `pii` | `'redact' &#124; 'hash' &#124; false` | — | PII detection mode. |
 | `endpoint` | `string` | `'https://ingest.neatlogs.com'` | Base ingest endpoint. The SDK sends traces to `/v1/traces` and logs to `/v1/logs`. |
 | `batchSize` | `number` | `100` | Maximum spans per export batch. |
 | `flushInterval` | `number` | `5` | Seconds between batch flushes. |
 | `piiEnabled` | `boolean` | — | Override team-level PII redaction toggle. |
 | `piiSpanTypes` | `string[]` | — | Override which span types have server-side PII redaction. |
+| `uploadAuthority` | `boolean \| UploadAuthority` | `false` | Enable the authenticated typed-media/oversized-OTLP upload contract, or inject an implementation. Keep disabled until the backend contract is deployed. |
+
+---
+
+### Independent `Client` pipelines
+
+Use `Client` when one process must send different executions to different
+Neatlogs projects. Each Client owns an isolated provider/export queue; the
+active Client is scoped to its synchronous or asynchronous `activate()` call.
+
+```typescript
+import { Client, trace, wrapOpenAI } from 'neatlogs';
+
+const project = new Client({
+  apiKey: process.env.NEATLOGS_API_KEY!,
+  workflowName: 'support-agent',
+  captureLogs: true,
+});
+const openai = wrapOpenAI(rawOpenAI); // reusable; routing occurs at invocation
+
+await project.activate(async () => {
+  await trace({ name: 'answer', kind: 'WORKFLOW' }, async () => {
+    return openai.responses.create({ model: 'gpt-5', input: 'Hello' });
+  });
+});
+
+await project.shutdown();
+```
+
+Do not share one activation across unrelated concurrent jobs. Create one Client
+per destination, use `activate()` around each execution, and always await
+`shutdown()` when that Client is no longer needed.
 
 ---
 
@@ -249,7 +267,7 @@ const result = await trace({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `name` | `string` | — | **Required.** Name for the trace span. |
-| `kind` | `SpanKind` | `'CHAIN'` | Span kind. |
+| `kind` | `TraceSpanKind` | `'CHAIN'` | Span kind. Base kinds include `GUARDRAIL` and `EVALUATOR`; `trace()` additionally accepts `LLM`, `RERANKER`, and `VECTOR_STORE`. |
 | `sessionId` | `string` | — | Session ID for grouping this root trace. |
 | `parentSessionId` | `string` | — | Immediate parent session ID. |
 | `sessionFeatureName` | `string` | — | Product feature that initiated the session request. |
@@ -345,8 +363,12 @@ Server-side prompt management for storing, versioning, and retrieving prompts fr
 import { PromptClient } from 'neatlogs';
 
 const client = new PromptClient({
-  baseUrl: 'https://app.neatlogs.com',
+  baseUrl: 'https://ingest.neatlogs.com',
   apiKey: process.env.NEATLOGS_API_KEY!,
+  cacheTtlMs: 60_000,              // fresh lifetime for latest/label lookups
+  staleWhileRevalidateMs: 300_000, // bounded stale fallback during refresh
+  requestTimeoutMs: 10_000,        // deadline for each prompt API request
+  maxCacheEntries: 100,             // LRU bound for process memory
 });
 
 // Create a prompt
@@ -359,9 +381,17 @@ const prompt = await client.createPrompt({
 // Fetch by name (returns latest version)
 const handle = await client.getPrompt('qa-system');
 
+// Per-key cache policy is retained across refreshes. During the stale window,
+// getPrompt returns the last known value and starts one coalesced refresh.
+const fastRefresh = await client.getPrompt('qa-system', {
+  cacheTtlMs: 5_000,
+  staleWhileRevalidateMs: 60_000,
+});
+
 // Fetch by label or version
 const prod = await client.getPrompt('qa-system', { label: 'production' });
 const v2 = await client.getPrompt('qa-system', { version: 2 });
+const v3 = await client.getPrompt('qa-system', { version: 3 });
 
 // Compile with variables
 const rendered = handle.compile({ role: 'helpful', company: 'Acme' });
@@ -372,20 +402,62 @@ const messages = handle.compileMessages({ role: 'helpful', company: 'Acme' });
 // List all prompts
 const all = await client.listPrompts();
 
-// Update prompt content
+// Backward-compatible alias: managed prompts are immutable, so this creates a version
 await client.updatePrompt('qa-system', { content: 'Updated: {{role}} for {{company}}.' });
 
-// Save a new version
-await client.saveAsVersion('qa-system', { label: 'v2' });
+// Save a new version. Content or messages is required by the backend contract.
+await client.saveAsVersion('qa-system', {
+  content: 'Version 2: {{role}} for {{company}}.',
+  labels: ['staging'],
+  commitMessage: 'Try the revised system prompt',
+});
+
+// Mutations target immutable version UUIDs. Name + version/label is resolved first.
+await client.setLabel('qa-system', 'production', { version: 2 });
+await client.addTag('qa-system', 'release-candidate', { version: 2 });
+await client.removeTag('qa-system', 'release-candidate', { version: 2 });
+await client.deletePrompt('qa-system', { version: 1 });
 
-// Delete a prompt
-await client.deletePrompt('qa-system');
+// Explicit PromptClient instances own their cache and prompt requests.
+client.close();
 ```
 
+Each prompt version may have zero or one active label. Accordingly, `labels`
+accepts at most one value on create/save, and `setLabel()` replaces or moves
+that label rather than adding a second simultaneous label.
+
+Latest and label selectors are fresh for `cacheTtlMs`. After that, they may be
+served only for the bounded `staleWhileRevalidateMs` window while one shared
+same-key refresh runs. Refresh failure leaves the last known value available
+until that stale window ends; after it ends, the next lookup waits for the
+backend and reports a typed error. A version selector is immutable in-process:
+`{ version: 2 }` never changes into another version. Request a different
+version explicitly, call `clearCache()`, or create a new client.
+
+Every request has a finite `requestTimeoutMs`. `close()` aborts in-flight prompt
+requests and releases the cache; calls after close raise
+`PromptClientClosedError`. The shared prompt client created by `init()` is
+closed by `shutdown()`, without making prompt failures part of telemetry flush
+success. An explicitly constructed `PromptClient` must be closed by its owner.
+
+#### Prompt privacy and ownership
+
+Prompt CRUD is intentional product-data transfer, separate from trace
+telemetry. The API key selects the Neatlogs project and authenticates prompt
+requests to `baseUrl`; the in-memory cache retains prompt content only until
+eviction, `clearCache()`, or `close()`. Server retention follows the managed
+prompt service policy for that project.
+
+Telemetry `mask=`, `pii`, and `piiSpanTypes` settings do **not** transform prompt
+content sent to the prompt-management API. If prompt content must be redacted,
+transform it explicitly before calling prompt CRUD. The SDK does not currently
+provide a prompt transform and does not claim that telemetry masking protects
+managed prompt payloads.
+
 Module-level convenience functions are also available after `init()`:
 
 ```typescript
-import { init, getPrompt, fetchPrompt, listPrompts, createPrompt, updatePrompt, saveAsVersion, deletePrompt, removeTag } from 'neatlogs';
+import { init, getPrompt, fetchPrompt, listPrompts, createPrompt, updatePrompt, saveAsVersion, deletePrompt, setLabel, addTag, removeTag } from 'neatlogs';
 
 await init({ apiKey: process.env.NEATLOGS_API_KEY });
 
@@ -395,16 +467,28 @@ const rendered = handle.compile({ name: 'world' });
 
 ---
 
-### `flush()` / `shutdown()`
+### `flush()` / `flushAll()` / `flushAllDetailed()` / `shutdown()`
 
 ```typescript
 // Flush pending spans without shutting down
 await flush();
 
+// Flush the default pipeline and every live Neatlogs Client under one deadline
+const flushed = await flushAll(30_000);
+if (!flushed) console.error('One or more Neatlogs pipelines failed to flush');
+
+// Inspect per-pipeline timeout and failure details when needed
+const result = await flushAllDetailed(30_000);
+if (!result.success) console.error(result.outcomes);
+
 // Flush and shut down — call before process exit
 await shutdown();
 ```
 
+`flushAll()` and `flushAllDetailed()` only know about Neatlogs-owned pipelines.
+They do not discover or flush Datadog, Langfuse, Braintrust, or a global
+OpenTelemetry provider.
+
 `shutdown()` resets all SDK state so `init()` can be called again if needed.
 
 ---
@@ -435,30 +519,36 @@ import { registerCrewaiTask } from 'neatlogs';
 registerCrewaiTask('research-task', 'Research the latest AI developments');
 ```
 
-## Supported Instrumentations
-
-### Isolation policy
-
-Neatlogs always runs on a private provider and private async context. Third-party
-auto-instrumentors that call the global OpenTelemetry context API cannot provide
-bidirectional isolation, so the manager rejects them at initialization before
-creating any provider state. Use the explicit provider/framework wrappers
-instead.
-
-### Registry Entries (not yet instrumented in TypeScript)
-
-The following libraries are registered in the instrumentation registry for future support. Passing them to `instrumentations` will log a debug message and skip gracefully:
-
-`cohere`, `groq`, `together`, `vertexai`, `google_generativeai`, `mistralai`, `ollama`, `watsonx`, `alephalpha`, `replicate`, `sagemaker`, `huggingface_hub`, `litellm`, `langgraph`, `llamaindex`, `autogen`, `haystack`, `dspy`, `chromadb`, `pinecone`, `weaviate`, `qdrant`, `milvus`, `opensearch`, `elasticsearch`, `redis`, `marqo`, `instructor`, `guardrails`, `google_adk`, `agno`, `openai_agents`, `pydantic_ai`, `smolagents`, `strands`, `pipecat`, `portkey`, `promptflow`
-
-## Framework Integrations
-
-For frameworks that don't fit the auto-instrument-on-init pattern, use the SDK's explicit wrappers. These wrappers use Neatlogs' private context and remain isolated from other tracing SDKs:
-
-| Framework | Helper |
-|-----------|--------|
-| Mastra (`@mastra/core`) | `wrapMastra()` from `neatlogs/mastra` |
-| Vercel AI SDK (`ai`) | `wrapAISDK()` from `neatlogs/ai` |
+## Supported TypeScript Integrations
+
+For `neatlogs >=1.1.19 <2.0.0`, use only the explicit helper shown below. The
+SDK has no `instrumentations: [...]` loader. These helpers attach to the object,
+callback surface, processor, or plugin you pass and use Neatlogs' private
+context. Versioned rows below name the dependencies installed by this repository's test
+matrix; API-shaped rows deliberately make no blanket semver claim.
+
+| Library | Repository test/API baseline | Explicit helper | Import path |
+|---|---|---|---|
+| OpenAI | `openai` 6.34.x | `wrapOpenAI(client)` | `neatlogs` or `neatlogs/openai` |
+| Anthropic | `@anthropic-ai/sdk` 0.68.x | `wrapAnthropic(client)` | `neatlogs` or `neatlogs/anthropic` |
+| Azure OpenAI | `openai` 6.34.x | `wrapAzureOpenAI(client)` | `neatlogs/azure-openai` |
+| AWS Bedrock Runtime | AWS SDK v3 command API | `wrapBedrock(client)` | `neatlogs/bedrock` |
+| Google GenAI | `@google/genai` 1.34.x | `wrapGoogleGenAI(client)` / `wrapGoogleGenAIChat(chat)` | `neatlogs/google-genai` |
+| Vertex AI through `@google/genai` | `@google/genai` 1.34.x | `wrapVertexAI(client)` / `wrapVertexAIChat(chat)` | `neatlogs/vertex-ai` |
+| OpenRouter Agent | `@openrouter/agent` 0.7.x | `wrapOpenRouterAgent(client)` / `wrapCallModel(fn)` | `neatlogs/openrouter-agent` |
+| Vercel AI SDK | `ai` 6.x | `wrapAISDK(ai)` | `neatlogs/ai` |
+| Mastra | `@mastra/core` 1.32.x | `wrapMastra(entity)` / `wrapMastraRerank(fn)` | `neatlogs/mastra` |
+| Claude Agent SDK | documented `query()` API | `wrapClaudeAgentSDK(sdk)` | `neatlogs/claude-agent-sdk` |
+| LangChain / LangGraph | `@langchain/core` 0.3.x | `langchainHandler()` callback | `neatlogs` or `neatlogs/langchain` |
+| OpenAI Agents SDK | documented `addTraceProcessor()` API | `openaiAgentsProcessor()` | `neatlogs` or `neatlogs/openai-agents` |
+| Pi Agent | `agent-core` 0.73.x and 0.83.x | `piAgentHooks(agent)` / `tracePiAgentEvents(...)` / `tracePiStream(...)` | `neatlogs` or `neatlogs/pi-agent` |
+| OpenCode | current plugin API | `NeatlogsOpencodePlugin` | `neatlogs/opencode` |
+| Browser client | browser SDK API in this release | `Neatlogs` | `neatlogs/browser` |
+
+Edge runtime packaging, the removed `instrumentations` init option, and Strands
+global-context hooks are not supported. `strandsHooks()` remains an explicit
+runtime rejection so an application cannot silently believe it is isolated or
+instrumented.
 
 ```typescript
 // Vercel AI SDK
@@ -468,16 +558,48 @@ import * as ai from 'ai';
 import { openai } from '@ai-sdk/openai';
 
 await init({ apiKey: process.env.NEATLOGS_API_KEY });
-const { generateText } = wrapAISDK(ai);
+const { generateText, ToolLoopAgent } = wrapAISDK(ai);
 
 const { text } = await generateText({
   model: openai('gpt-4o-mini'),
   prompt: 'What is TypeScript?',
 });
 
+// AI SDK v6 agents are supported too. The wrapper injects telemetry into the
+// constructor settings, including calls returned from a custom prepareCall.
+const agent = new ToolLoopAgent({
+  id: 'support-agent',
+  model: openai('gpt-4o-mini'),
+  experimental_telemetry: { functionId: 'support-agent' },
+});
+await agent.generate({ prompt: 'Help me debug my order' });
+
 await shutdown();
 ```
 
+If a call already supplies an `experimental_telemetry.tracer` (for example,
+Laminar), the wrapper mirrors the AI SDK's native spans to both that tracer and
+Neatlogs. The caller-owned tracer remains the global context owner; Neatlogs
+keeps separate parent context and export state in its private provider.
+
+The same coexistence is available without the wrapper by passing the existing
+tracer to `createAITelemetry`:
+
+```typescript
+import { getTracer } from '@lmnr-ai/lmnr';
+import { streamText } from 'ai';
+import { createAITelemetry } from 'neatlogs/ai';
+
+await streamText({
+  model,
+  prompt,
+  experimental_telemetry: createAITelemetry({
+    tracer: getTracer(),
+    functionId: 'progress-narration',
+  }),
+});
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -486,6 +608,7 @@ await shutdown();
 |----------|-------------|
 | `NEATLOGS_API_KEY` | API key (fallback when `apiKey` option is not provided) |
 | `NEATLOGS_DISABLE_EXPORT` | Set to `true`, `1`, or `yes` to disable export |
+| `NEATLOGS_UPLOADS_ENABLED` | Set to `true`, `1`, or `yes` to enable authenticated typed-media and oversized-OTLP uploads |
 
 ### Programmatic Configuration
 
@@ -499,7 +622,6 @@ await init({
   userId: 'user-456',
   tags: ['production', 'v2'],
   metadata: { environment: 'prod' },
-  instrumentations: ['openai', 'anthropic'],
   sampleRate: 0.5,
   captureLogs: true,
   debug: true,
@@ -575,7 +697,7 @@ See the [`examples/`](./examples/) directory for complete, runnable examples:
 
 | File | Description |
 |------|-------------|
-| [`basic-openai.ts`](./examples/basic-openai.ts) | Basic OpenAI usage with auto-instrumentation |
+| [`basic-openai.ts`](./examples/basic-openai.ts) | Basic OpenAI usage with an explicit wrapper |
 | [`prompt-management.ts`](./examples/prompt-management.ts) | PromptTemplate + trace() for prompt versioning |
 | [`multi-agent-workflow.ts`](./examples/multi-agent-workflow.ts) | Nested spans: WORKFLOW → AGENT → TOOL |
 | [`custom-spans.ts`](./examples/custom-spans.ts) | All span kinds: WORKFLOW, CHAIN, AGENT, TOOL, RETRIEVER, EMBEDDING, GUARDRAIL |