@usefarol/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,11 @@
-# farol-sdk
+# @usefarol/sdk
 
 **AI agent observability for Node.js** — wrap your agent entrypoints with a single `trace()` helper to send runs, token usage, cost, and spans to [Farol](https://usefarol.dev).
 
 ## Install
 
 ```bash
-npm install farol-sdk
+npm install @usefarol/sdk
 ```
 
 Requires **Node.js 18+** (global `fetch`).
@@ -18,7 +18,7 @@ Create or copy your API key from the Farol app: **[usefarol.dev](https://usefaro
 
 ```typescript
 import Anthropic from "@anthropic-ai/sdk";
-import { trace } from "farol-sdk";
+import { trace } from "@usefarol/sdk";
 
 const client = new Anthropic();
 
@@ -60,7 +60,7 @@ await myAgent("Summarize this week’s metrics.");
 
 ```typescript
 import OpenAI from "openai";
-import { trace } from "farol-sdk";
+import { trace } from "@usefarol/sdk";
 
 const openai = new OpenAI();
 
@@ -103,7 +103,7 @@ await myAgent("Hello!");
 Use `run.startSpan(name, { type, metadata })` for tools, retrieval, or extra LLM steps. Call `span.end()` when the step finishes, or `span.end(error)` on failure. Unclosed spans are auto-ended when the run completes.
 
 ```typescript
-import { trace } from "farol-sdk";
+import { trace } from "@usefarol/sdk";
 
 const pipeline = trace(
   async (run, query: string) => {
@@ -147,6 +147,18 @@ await pipeline("What is Farol?");
 
 Set `captureIo: true` in `trace` options to include `span.input` / `span.output` in the payload (only when you assign them). **Do not enable for sensitive data** without reviewing compliance needs.
 
+## Sampling
+
+Set `sampleRate` to reduce the percentage of runs sent to Farol. Errors are always sent regardless of sample rate.
+
+```typescript
+const myAgent = trace(fn, {
+  agentName: "my-agent",
+  farolKey: "frl_...",
+  sampleRate: 0.1, // send 10% of successful runs
+});
+```
+
 ## Options
 
 | Option | Description |
@@ -157,6 +169,7 @@ Set `captureIo: true` in `trace` options to include `span.input` / `span.output`
 | `model` | Model label on the run |
 | `costPer1kInputTokens` / `costPer1kOutputTokens` | USD per 1k tokens for cost estimates |
 | `captureIo` | When `true`, include span `input`/`output` if set |
+| `sampleRate` | Fraction of successful runs to send (`0.0`–`1.0`). Errors always sent. Default `1.0`. |
 
 ## Build (from source)
 

package/dist/index.d.mts

@@ -6,6 +6,8 @@ interface TraceOptions {
     costPer1kInputTokens?: number;
     costPer1kOutputTokens?: number;
     captureIo?: boolean;
+    /** 0.0 to 1.0, default 1.0 */
+    sampleRate?: number;
 }
 interface SpanOptions {
     type?: "tool" | "llm";

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface TraceOptions {
     costPer1kInputTokens?: number;
     costPer1kOutputTokens?: number;
     captureIo?: boolean;
+    /** 0.0 to 1.0, default 1.0 */
+    sampleRate?: number;
 }
 interface SpanOptions {
     type?: "tool" | "llm";

package/dist/index.js

@@ -91,7 +91,8 @@ function trace(fn, options) {
     model = "unknown",
     costPer1kInputTokens = 25e-5,
     costPer1kOutputTokens = 125e-5,
-    captureIo = false
+    captureIo = false,
+    sampleRate = 1
   } = options;
   if (captureIo) {
     console.warn(
@@ -117,7 +118,12 @@ function trace(fn, options) {
       for (const span of run.spans) {
         if (!span.endedAt) span.end();
       }
-      await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      const shouldSend = run.status === "error" || Math.random() <= sampleRate;
+      if (shouldSend) {
+        await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      } else {
+        console.log(`[Farol] Run sampled out (sampleRate=${sampleRate})`);
+      }
     }
   };
 }

package/dist/index.mjs

@@ -65,7 +65,8 @@ function trace(fn, options) {
     model = "unknown",
     costPer1kInputTokens = 25e-5,
     costPer1kOutputTokens = 125e-5,
-    captureIo = false
+    captureIo = false,
+    sampleRate = 1
   } = options;
   if (captureIo) {
     console.warn(
@@ -91,7 +92,12 @@ function trace(fn, options) {
       for (const span of run.spans) {
         if (!span.endedAt) span.end();
       }
-      await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      const shouldSend = run.status === "error" || Math.random() <= sampleRate;
+      if (shouldSend) {
+        await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      } else {
+        console.log(`[Farol] Run sampled out (sampleRate=${sampleRate})`);
+      }
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefarol/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI agent observability SDK for Node.js — plug-and-play monitoring for your agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -9,6 +9,8 @@ export interface TraceOptions {
   costPer1kInputTokens?: number;
   costPer1kOutputTokens?: number;
   captureIo?: boolean;
+  /** 0.0 to 1.0, default 1.0 */
+  sampleRate?: number;
 }
 
 export interface SpanOptions {
@@ -109,6 +111,7 @@ export function trace<T extends unknown[], R>(
     costPer1kInputTokens = 0.00025,
     costPer1kOutputTokens = 0.00125,
     captureIo = false,
+    sampleRate = 1.0,
   } = options;
 
   if (captureIo) {
@@ -142,7 +145,13 @@ export function trace<T extends unknown[], R>(
         if (!span.endedAt) span.end();
       }
 
-      await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      const shouldSend =
+        run.status === "error" || Math.random() <= sampleRate;
+      if (shouldSend) {
+        await sendToFarol(run, farolKey, farolEndpoint, captureIo);
+      } else {
+        console.log(`[Farol] Run sampled out (sampleRate=${sampleRate})`);
+      }
     }
   };
 }