@zespan/sdk 1.0.0

package/README.md

@@ -0,0 +1,327 @@
+# @zespan/sdk
+
+Agent observability for Node.js. Trace every AI call — latency, tokens, cost, errors — with one `init()`.
+
+> For full documentation visit [docs.zespan.com](https://docs.zespan.com)
+
+## Install
+
+```bash
+npm install @zespan/sdk
+# or
+pnpm add @zespan/sdk
+```
+
+## Quick start
+
+```ts
+import { init } from "@zespan/sdk";
+
+init({
+  apiKey: "lqt_your_key_here",
+  projectId: "your_project_id",
+});
+```
+
+Get your API key and project ID from [app.zespan.com](https://app.zespan.com) → Project Settings → API Keys.
+
+After `init()`, all calls to OpenAI, Anthropic, and Google GenAI are automatically traced. No further changes needed.
+
+## Auto-instrumentation
+
+By default, `init()` patches OpenAI, Anthropic, and Google GenAI as soon as they are imported. You do not need to wrap anything.
+
+```ts
+import { init } from "@zespan/sdk";
+import OpenAI from "openai";
+
+init({ apiKey: "lqt_...", projectId: "proj_..." });
+
+const openai = new OpenAI();
+// This call is automatically traced
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+});
+```
+
+To disable autopatch and wrap manually:
+
+```ts
+init({ apiKey: "lqt_...", autopatch: false });
+```
+
+## Manual wrappers
+
+When you need explicit control, or when using providers beyond OpenAI/Anthropic/Google:
+
+```ts
+import { init, wrapOpenAI, wrapAnthropic, wrapGoogle } from "@zespan/sdk";
+import OpenAI from "openai";
+import Anthropic from "@anthropic-ai/sdk";
+import { GoogleGenerativeAI } from "@google/generative-ai";
+
+init({ apiKey: "lqt_...", autopatch: false });
+
+const openai = wrapOpenAI(new OpenAI());
+const anthropic = wrapAnthropic(new Anthropic());
+const google = wrapGoogle(new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!));
+```
+
+**All available wrappers:**
+
+| Function                 | Provider             |
+| ------------------------ | -------------------- |
+| `wrapOpenAI(client)`     | OpenAI               |
+| `wrapAnthropic(client)`  | Anthropic            |
+| `wrapGoogle(client)`     | Google Generative AI |
+| `wrapOpenRouter(client)` | OpenRouter           |
+| `wrapBedrock(client)`    | AWS Bedrock          |
+| `wrapMistral(client)`    | Mistral              |
+| `wrapGroq(client)`       | Groq                 |
+| `wrapLiteLLM(client)`    | LiteLLM              |
+
+## Configuration
+
+```ts
+init({
+  apiKey: "lqt_...", // required
+  projectId: "proj_...", // required — links traces to a project
+  environment: "production", // default: "production"
+  storePrompts: false, // store prompt/completion text (default: false)
+  redactKeys: ["password", "secret", "token", "api_key"], // keys to redact
+  sampleRate: 1.0, // 0.0–1.0, fraction of events to send
+  debug: false, // log SDK activity to console
+  batchSize: 50, // events per batch flush
+  flushInterval: 2000, // ms between batch flushes
+  autopatch: true, // auto-instrument OpenAI/Anthropic/Google
+});
+```
+
+## User and session context
+
+Tag traces with user ID, session ID, or custom metadata:
+
+```ts
+import { withZespanContext } from "@zespan/sdk";
+
+await withZespanContext(
+  { userId: "user_123", sessionId: "sess_abc", tags: { feature: "chat" } },
+  async () => {
+    // All AI calls inside here are tagged with this context
+    await openai.chat.completions.create({ ... });
+  }
+);
+```
+
+## Agent tracing
+
+Group multi-step agent workflows into a single trace:
+
+```ts
+import { withAgent } from "@zespan/sdk";
+
+await withAgent(
+  {
+    name: "SupportAgent",
+    role: "specialist",
+    framework: "custom",
+    tools: [{ name: "lookup_order", description: "Look up order by ID" }],
+  },
+  async (agent) => {
+    agent.logPlan(["Look up order", "Check policy", "Draft reply"]);
+
+    const result = await agent.traceTool(
+      "lookup_order",
+      { order_id: "123" },
+      async () => fetchOrder("123")
+    );
+
+    agent.delegateTo("RefundAgent", "refund requested");
+
+    // Wrapped LLM calls inside here inherit agent context
+    await openai.chat.completions.create({ ... });
+  }
+);
+```
+
+## Manual spans
+
+Trace custom operations that aren't LLM calls:
+
+```ts
+import { startSpan } from "@zespan/sdk";
+
+const { span, run } = startSpan({
+  name: "document-retrieval",
+  span_kind: "retrieval",
+});
+
+await run(async () => {
+  const docs = await vectorStore.search(query);
+  await span.end({ status: "success" });
+  return docs;
+});
+```
+
+## Framework integrations
+
+### LangChain
+
+```ts
+import { ZespanCallbackHandler } from "@zespan/sdk";
+
+const handler = new ZespanCallbackHandler();
+
+const chain = new LLMChain({ llm, prompt, callbacks: [handler] });
+```
+
+### Vercel AI SDK
+
+```ts
+import { instrumentVercelAI, getLumiqVercelTelemetry } from "@zespan/sdk";
+
+instrumentVercelAI();
+
+// Or per-call:
+const result = await generateText({
+  model: openai("gpt-4o"),
+  prompt: "Hello",
+  experimental_telemetry: getLumiqVercelTelemetry({ traceId: "my-trace" }),
+});
+```
+
+### Google ADK
+
+```ts
+import { instrumentADK } from "@zespan/sdk";
+
+instrumentADK(); // patches all ADK agents globally
+```
+
+Or wrap a specific agent:
+
+```ts
+import { wrapADKAgent } from "@zespan/sdk";
+
+const traced = wrapADKAgent(myAgent, { name: "MyAgent" });
+```
+
+### LlamaIndex
+
+```ts
+import { LumiqLlamaIndexHandler } from "@zespan/sdk";
+
+const handler = new LumiqLlamaIndexHandler();
+Settings.callbackManager.addEventHandler(handler);
+```
+
+### CrewAI / AutoGen / PydanticAI
+
+These frameworks use OTEL-based instrumentation. See exports:
+
+```ts
+import {
+  CREWAI_OTEL_ENV,
+  getCrewAIInstrumentationGuide,
+} from "@zespan/sdk";
+import { injectAutoGenContext } from "@zespan/sdk";
+import { getPydanticAIConfig } from "@zespan/sdk";
+```
+
+## Prompt management
+
+Fetch versioned prompts from Zespan with 5-minute client-side cache:
+
+```ts
+import { getZespanClient } from "@zespan/sdk";
+
+const client = getZespanClient();
+
+// Latest version
+const prompt = await client.prompts.get("support-reply");
+
+// Specific version or label
+const prompt = await client.prompts.get("support-reply", { version: 3 });
+const prompt = await client.prompts.get("support-reply", {
+  label: "production",
+});
+
+// Compile variables
+const text = client.prompts.compile(prompt, {
+  user_name: "Alice",
+  product: "Pro",
+});
+```
+
+## Guardrails
+
+Check content against your configured guardrail rules before or after LLM calls:
+
+```ts
+import { getZespanClient, GuardrailBlockedError } from "@zespan/sdk";
+
+const client = getZespanClient();
+
+try {
+  const check = await client.checkGuardrails({
+    text: userMessage,
+    phase: "pre",
+  });
+
+  if (!check.allowed) {
+    return "Request blocked by content policy.";
+  }
+
+  const response = await openai.chat.completions.create({ ... });
+
+  const postCheck = await client.checkGuardrails({
+    text: response.choices[0].message.content!,
+    phase: "post",
+  });
+
+  return postCheck.modifiedText ?? response.choices[0].message.content;
+} catch (err) {
+  if (err instanceof GuardrailBlockedError) {
+    return "Response blocked by content policy.";
+  }
+  throw err;
+}
+```
+
+Guardrails can also be applied automatically via wrapper options:
+
+```ts
+const openai = wrapOpenAI(new OpenAI(), { guardrails: true });
+// or fine-grained:
+const openai = wrapOpenAI(new OpenAI(), {
+  guardrails: { pre: true, post: true, failClosed: false },
+});
+```
+
+## Flush on exit
+
+The SDK flushes automatically on `process.beforeExit`. For serverless functions or short-lived scripts, flush manually:
+
+```ts
+import { getZespanClient } from "@zespan/sdk";
+
+await getZespanClient().flush();
+```
+
+## OpenTelemetry
+
+Enable native OTEL export alongside Zespan:
+
+```ts
+init({
+  apiKey: "lqt_...",
+  enableOTel: true,
+  otelEndpoint: "http://localhost:4318",
+  otelServiceName: "my-service",
+});
+```
+
+## TypeScript
+
+The SDK is fully typed. All wrapper functions preserve the original client's type signature.