@frugalco/frugal-sdk-node 0.3.0 → 0.5.0

package/dist/duplicate-filter.d.ts

@@ -0,0 +1,46 @@
+import type { Config } from "./config.js";
+import { DUP_FIRST_SEEN, DUP_REPEAT_SEEN } from "./semconv.js";
+export type DupState = typeof DUP_FIRST_SEEN | typeof DUP_REPEAT_SEEN;
+export declare class RotatingBloomFilter {
+    private readonly m;
+    private readonly k;
+    private readonly generations;
+    private readonly rotateMs;
+    private readonly bytesPerGen;
+    private bits;
+    private activeIndex;
+    private genStartMs;
+    private disabled;
+    private insertsSinceCheck;
+    private saturationWarned;
+    constructor(opts: {
+        capacity: number;
+        fpRate: number;
+        generations: number;
+        windowSeconds: number;
+    });
+    /**
+     * Classify a signature and insert it. Returns null when the filter is
+     * disabled (bit-array allocation failed — latched for the process lifetime
+     * so the allocation is not retried on every call).
+     *
+     * The clock defaults to performance.now() (monotonic): rotation must not
+     * freeze when NTP steps the wall clock backward.
+     */
+    seenBefore(signature: string, nowMs?: number): DupState | null;
+    clear(): void;
+    /**
+     * Warn (once per fill, re-armed by clear()) when the filter is saturating.
+     * Membership tests the UNION of all generations, so occupancy is measured on
+     * the union too — measuring only the active generation would let two
+     * generations at 49% (union ~74%) pass silently. Past ~50% union fill the
+     * effective false-positive rate is far above the configured target and the
+     * metric drifts toward all-repeat_seen.
+     */
+    private maybeWarnSaturation;
+    private rotate;
+    private positions;
+}
+export declare function getSharedDuplicateFilter(config: Config): RotatingBloomFilter | null;
+export declare function resetSharedDuplicateFilterForTests(): void;
+//# sourceMappingURL=duplicate-filter.d.ts.map

package/dist/duplicate-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicate-filter.d.ts","sourceRoot":"","sources":["../src/duplicate-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,OAAO,cAAc,GAAG,OAAO,eAAe,CAAC;AAyBtE,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,gBAAgB,CAAS;gBAErB,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;KACvB;IASD;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,MAA0B,GAAG,QAAQ,GAAG,IAAI;IAwDjF,KAAK,IAAI,IAAI;IAQb;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,SAAS;CASlB;AAID,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAWnF;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD"}

package/dist/duplicate-filter.js

@@ -0,0 +1,168 @@
+import { emitLog, emitLogOnce } from "./debug.js";
+import { DUP_FIRST_SEEN, DUP_REPEAT_SEEN } from "./semconv.js";
+function bloomParams(capacity, fpRate) {
+    const N = Math.max(1, Math.floor(capacity));
+    const p = Math.min(Math.max(fpRate, 1e-6), 0.5);
+    const ln2 = Math.LN2;
+    const m = Math.max(8, Math.ceil((-N * Math.log(p)) / (ln2 * ln2)));
+    const k = Math.max(1, Math.round((m / N) * ln2));
+    return { m, k };
+}
+// How often (in insertions) to measure occupancy for the saturation warning.
+// Counting set bits is O(m/8) bytes, so amortizing over 1024 inserts keeps the
+// check negligible even at the capacity clamp.
+const SATURATION_CHECK_INTERVAL = 1024;
+// Union occupancy at which the false-positive rate is degraded badly enough to
+// warn: at 50% fill the FP rate is ~(0.5)^k, orders of magnitude above the
+// configured target, and rising fast.
+const SATURATION_FILL_THRESHOLD = 0.5;
+const POPCOUNT = new Uint8Array(256);
+for (let i = 0; i < 256; i++) {
+    POPCOUNT[i] = (i & 1) + POPCOUNT[i >> 1];
+}
+export class RotatingBloomFilter {
+    m;
+    k;
+    generations;
+    rotateMs;
+    bytesPerGen;
+    bits = null;
+    activeIndex = 0;
+    genStartMs = 0;
+    disabled = false;
+    insertsSinceCheck = 0;
+    saturationWarned = false;
+    constructor(opts) {
+        const { m, k } = bloomParams(opts.capacity, opts.fpRate);
+        this.m = m;
+        this.k = k;
+        this.generations = Math.max(1, Math.floor(opts.generations));
+        this.rotateMs = Math.max(1, (opts.windowSeconds * 1000) / this.generations);
+        this.bytesPerGen = Math.ceil(m / 8);
+    }
+    /**
+     * Classify a signature and insert it. Returns null when the filter is
+     * disabled (bit-array allocation failed — latched for the process lifetime
+     * so the allocation is not retried on every call).
+     *
+     * The clock defaults to performance.now() (monotonic): rotation must not
+     * freeze when NTP steps the wall clock backward.
+     */
+    seenBefore(signature, nowMs = performance.now()) {
+        if (this.disabled)
+            return null;
+        if (this.bits === null) {
+            try {
+                this.bits = Array.from({ length: this.generations }, () => new Uint8Array(this.bytesPerGen));
+            }
+            catch (err) {
+                this.disabled = true;
+                emitLogOnce("duplicate_filter_alloc_failed", "error", `duplicate filter allocation failed (${this.generations} × ${this.bytesPerGen} bytes); duplicate detection disabled for this process. Lower FRUGAL_DUPLICATE_CAPACITY / FRUGAL_DUPLICATE_GENERATIONS.`);
+                // Rethrow once so the caller records a single internal_errors point;
+                // every later call short-circuits on the latch above.
+                throw err;
+            }
+            this.genStartMs = nowMs;
+        }
+        this.rotate(nowMs);
+        const positions = this.positions(signature);
+        const bits = this.bits;
+        let present = true;
+        for (const pos of positions) {
+            const byte = pos >> 3;
+            const mask = 1 << (pos & 7);
+            let anySet = false;
+            for (let g = 0; g < this.generations; g++) {
+                if ((bits[g][byte] & mask) !== 0) {
+                    anySet = true;
+                    break;
+                }
+            }
+            if (!anySet) {
+                present = false;
+                break;
+            }
+        }
+        const active = bits[this.activeIndex];
+        for (const pos of positions) {
+            active[pos >> 3] |= 1 << (pos & 7);
+        }
+        if (++this.insertsSinceCheck >= SATURATION_CHECK_INTERVAL) {
+            this.insertsSinceCheck = 0;
+            this.maybeWarnSaturation();
+        }
+        return present ? DUP_REPEAT_SEEN : DUP_FIRST_SEEN;
+    }
+    clear() {
+        this.bits = null;
+        this.activeIndex = 0;
+        this.genStartMs = 0;
+        this.insertsSinceCheck = 0;
+        this.saturationWarned = false;
+    }
+    /**
+     * Warn (once per fill, re-armed by clear()) when the filter is saturating.
+     * Membership tests the UNION of all generations, so occupancy is measured on
+     * the union too — measuring only the active generation would let two
+     * generations at 49% (union ~74%) pass silently. Past ~50% union fill the
+     * effective false-positive rate is far above the configured target and the
+     * metric drifts toward all-repeat_seen.
+     */
+    maybeWarnSaturation() {
+        if (this.saturationWarned || this.bits === null)
+            return;
+        const gens = this.bits;
+        let setBits = 0;
+        for (let byte = 0; byte < this.bytesPerGen; byte++) {
+            let union = 0;
+            for (let g = 0; g < gens.length; g++) {
+                union |= gens[g][byte];
+            }
+            setBits += POPCOUNT[union];
+        }
+        const fill = setBits / this.m;
+        if (fill >= SATURATION_FILL_THRESHOLD) {
+            this.saturationWarned = true;
+            emitLog("warn", `duplicate filter is ${Math.round(fill * 100)}% full — false-positive rate is degraded and repeat_seen counts are inflated. Raise FRUGAL_DUPLICATE_CAPACITY above the number of distinct requests per window.`);
+        }
+    }
+    rotate(nowMs) {
+        const elapsed = nowMs - this.genStartMs;
+        if (elapsed < this.rotateMs)
+            return;
+        const steps = Math.floor(elapsed / this.rotateMs);
+        const clears = Math.min(this.generations, steps);
+        for (let s = 0; s < clears; s++) {
+            this.activeIndex = (this.activeIndex + 1) % this.generations;
+            this.bits[this.activeIndex].fill(0);
+        }
+        this.genStartMs += steps * this.rotateMs;
+    }
+    positions(signature) {
+        const h1 = (parseInt(signature.slice(0, 8), 16) || 0) >>> 0;
+        const h2 = ((parseInt(signature.slice(8, 16), 16) || 0) | 1) >>> 0;
+        const out = new Array(this.k);
+        for (let i = 0; i < this.k; i++) {
+            out[i] = (h1 + i * h2) % this.m;
+        }
+        return out;
+    }
+}
+let shared = null;
+export function getSharedDuplicateFilter(config) {
+    if (!config.duplicateDetection)
+        return null;
+    if (shared === null) {
+        shared = new RotatingBloomFilter({
+            capacity: config.duplicateCapacity,
+            fpRate: config.duplicateFpRate,
+            generations: config.duplicateGenerations,
+            windowSeconds: config.duplicateWindowSeconds,
+        });
+    }
+    return shared;
+}
+export function resetSharedDuplicateFilterForTests() {
+    shared = null;
+}
+//# sourceMappingURL=duplicate-filter.js.map

package/dist/duplicate-filter.js.map

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

package/dist/instrument.d.ts

@@ -12,6 +12,13 @@ export interface CallContext {
     batched?: boolean;
     /** Captured request kwargs for prompt analysis + cap utilization. */
     requestPayload?: RequestPayload;
+    /**
+     * Optional caller-defined tag (e.g. a business unit) for the
+     * frugal.custom_label attribute. Set ONLY by
+     * the manual track API (trackAICall / startAICall) — provider wrappers must
+     * leave it unset. Values outside the config allowlist are coerced to "other".
+     */
+    customLabel?: string;
 }
 export interface UsageReport {
     responseModel?: string | null;
@@ -20,6 +27,7 @@ export interface UsageReport {
     cacheReadTokens?: number | null;
     cacheWriteTokens?: number | null;
     reasoningTokens?: number | null;
+    agentTurns?: number | null;
 }
 export interface StartCallOptions {
     /**
@@ -43,10 +51,35 @@ export declare class CallEmitter {
     private finalized;
     constructor(config: Config, ctx: CallContext, caller: CallerInfo, instruments: Instruments, startSec: number, provider: ProviderEntry, operation: string);
     success(usage: UsageReport): void;
+    private recordCallShape;
+    private recordInternalError;
+    private recordDuplicate;
     private recordCapUtilization;
     private maybeAnalyze;
     private recordStable;
     error(err: unknown): void;
     private baseAttrs;
 }
+export interface BatchRequestGroup {
+    requestModel: string;
+    count: number;
+}
+/**
+ * Record the calls a batch submission carries — one counter increment per
+ * (model, count) group so mixed-model batches attribute per model. Duration
+ * and error accounting for the submitting HTTP call stay on its CallEmitter;
+ * this only records the fanned-out request volume.
+ */
+export declare function recordBatchedCalls(config: Config, base: {
+    system: string;
+    operation: string;
+}, caller: CallerInfo, groups: readonly BatchRequestGroup[]): void;
+/**
+ * Record one batch result entry's token usage. No calls increment — the
+ * request was already counted at submission; results only attribute spend.
+ */
+export declare function recordBatchedUsage(config: Config, base: {
+    system: string;
+    operation: string;
+}, caller: CallerInfo, requestModel: string, usage: UsageReport): void;
 //# sourceMappingURL=instrument.d.ts.map

package/dist/instrument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../src/instrument.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAyB9B,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,gBAAqB,GAC1B,WAAW,CAyCb;AAOD,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAV5B,OAAO,CAAC,SAAS,CAAS;gBAGP,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,WAAW,EACxB,MAAM,EAAE,UAAU,EACV,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,EAEhB,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM;IAGpC,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAqCjC,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,YAAY;IAyCpB,OAAO,CAAC,YAAY;IAgBpB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAWzB,OAAO,CAAC,SAAS;CAgBlB"}
+{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../src/instrument.ts"],"names":[],"mappings":"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"}