Merge pull request #35 from Floe-Labs/feat/per-call-log

feat: add per call native spend logs.

Author: shivamfloe

CHANGELOG.md

@@ -10,6 +10,31 @@ both packages adhere to [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+## py 0.3.0 / js 0.3.0 — 2026-07-14
+
+### Added (py + js)
+
+- **Per-call spend ledger**: every priced `record()` / `settle()` appends a
+  typed `SpendEvent` (`timestamp`, `kind: llm|tool`, `model_or_tool`,
+  `prompt_tokens`, `completion_tokens`, `cost_usd`, optional `label` and
+  `reserved`) to `guard.spend_log` (py) / `guard.spendLog` (js), so the ledger
+  sums to the running total (unless the ring-buffer cap below has evicted old
+  events) — no more rebuilding per-call breakdowns outside the guard. `export_log()` / `exportLog()` serialises it as JSONL with
+  an identical snake_case schema in both languages, so heterogeneous agents
+  emit one concatenable stream. An optional `max_log_events` / `maxLogEvents`
+  ring-buffer cap bounds memory for long-running agents.
+- **`record_tool()` / `recordTool()`**: accrue a non-LLM cost (paid tool/API
+  call) against the same ceiling and log it as a `kind: "tool"` event, so
+  `check()` / `reserve()` enforce the budget across LLM and tool spend
+  together.
+- `record()` / `settle()` accept an optional `label` to tag events with an
+  agent/task name.
+
+### Fixed (py)
+
+- `floe_guard.__version__` now reports the real package version (it had been
+  stuck at `0.1.0` since the 0.2.0 release).
+
 ## py 0.2.0 / js 0.2.1 — 2026-07-10
 
 Everything the repo grew between the 0.1.0 uploads and this release ships here —

README.md

@@ -150,6 +150,31 @@ unchanged — hosted just answers across *every* vendor and cap with server-trut
 balances and rolling-window reset timing, which a single local budget can't know.
 The TS package exposes the identical `guard.advisory()`.
 
+## Per-call spend log
+
+The guard keeps a typed, in-memory ledger of everything it priced: each
+`record()` / `settle()` appends one `SpendEvent`, and `record_tool()` lets paid
+non-LLM calls (search APIs, scrapers) spend the same budget and land in the same
+log. The events sum to `spent_usd` (unless a `max_log_events` ring buffer has
+evicted old ones) — no more rebuilding per-call breakdowns around the guard.
+
+```python
+guard = BudgetGuard(limit_usd=1.00)                      # max_log_events=N caps memory
+guard.record("gpt-4o", 1_200, 350, label="researcher")   # label is optional
+guard.record_tool("serpapi.search", 0.01, label="researcher")
+
+guard.spend_log      # [SpendEvent(timestamp=…, kind="llm", model_or_tool="gpt-4o",
+                     #             prompt_tokens=1200, completion_tokens=350,
+                     #             cost_usd=0.0065, label="researcher"), …]
+print(guard.export_log(), end="")   # JSONL, one event per line
+```
+
+`export_log()` emits a stable snake_case schema —
+`{timestamp, kind: llm|tool, model_or_tool, prompt_tokens, completion_tokens,
+cost_usd, label?, reserved?}` — identical to the TS package's `exportLog()`, so
+every agent produces the same shape regardless of stack and the streams can be
+concatenated and analysed together.
+
 ## Framework adapters (optional extras)
 
 ### CrewAI

js/README.md

@@ -63,6 +63,27 @@ const adv = guard.advisory();
 const model = adv.nearLimit ? openai("gpt-4o-mini") : openai("gpt-4o");
 ```
 
+## Per-call spend log
+
+The guard keeps a typed, in-memory ledger of everything it priced: each
+`record()` / `settle()` appends one `SpendEvent`, and `recordTool()` lets paid
+non-LLM calls spend the same budget and land in the same log. The events sum to
+`spentUsd` (unless a `maxLogEvents` ring buffer has evicted old ones).
+
+```ts
+const guard = new BudgetGuard(1.0); // { maxLogEvents: N } caps memory
+guard.record("gpt-4o", 1_200, 350, { label: "researcher" });
+guard.recordTool("serpapi.search", 0.01, { label: "researcher" });
+
+guard.spendLog; // [{ timestamp, kind: "llm", modelOrTool: "gpt-4o", … }, …]
+process.stdout.write(guard.exportLog()); // JSONL, one event per line
+```
+
+`exportLog()` emits a stable snake_case schema —
+`{timestamp, kind: llm|tool, model_or_tool, prompt_tokens, completion_tokens,
+cost_usd, label?, reserved?}` — identical to the Python package's
+`export_log()`, so every agent produces the same shape regardless of stack.
+
 ## Compatibility
 
 `ai` is declared as a peer dependency with the range `>=4.0.0 <6.0.0`:

js/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "floe-guard",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A local budget guardrail for AI agents — hard-stops your agent before its next LLM call crosses a USD ceiling. Vercel AI SDK middleware.",
   "type": "module",
   "license": "MIT",

js/package.json

@@ -33,6 +33,33 @@ import {
 /** Tolerance for float rounding in the running spend total (well below $0.000001). */
 const EPS = 1e-12;
 
+/**
+ * One priced spend event in the guard's per-call ledger.
+ *
+ * Every {@link BudgetGuard.record} / {@link BudgetGuard.settle} /
+ * {@link BudgetGuard.recordTool} that accrues spend appends exactly one event, so
+ * the ledger's costs sum to `spentUsd` (unless a `maxLogEvents` ring buffer has
+ * evicted old events). The schema is identical in the Python
+ * package (`SpendEvent` in `src/floe_guard/guard.py`) and
+ * {@link BudgetGuard.exportLog} serialises it with the same snake_case keys in
+ * both languages, so every agent emits the same shape regardless of stack.
+ */
+export interface SpendEvent {
+  /** Unix epoch seconds (UTC). */
+  readonly timestamp: number;
+  readonly kind: "llm" | "tool";
+  readonly modelOrTool: string;
+  /** `null` for tool events. */
+  readonly promptTokens: number | null;
+  /** `null` for tool events. */
+  readonly completionTokens: number | null;
+  readonly costUsd: number;
+  /** Caller-supplied tag (agent/task name). */
+  readonly label?: string;
+  /** The reservation settled by this call, if any. */
+  readonly reserved?: number;
+}
+
 export interface BudgetGuardOptions {
   /** Per-model manual prices for models the bundled cost map cannot price. */
   priceOverrides?: Record<string, ManualPrice>;
@@ -53,6 +80,13 @@ export interface BudgetGuardOptions {
    * flags `nearLimit` so an agent can taper before the hard-stop. Default 8000.
    */
   nearLimitBps?: number;
+  /**
+   * Optional cap on the per-call spend ledger ({@link BudgetGuard.spendLog}).
+   * When set, the ledger is a ring buffer keeping the most recent N events so a
+   * long-running agent's memory stays bounded; the running totals are
+   * unaffected. Default: keep every event.
+   */
+  maxLogEvents?: number;
 }
 
 /**
@@ -92,6 +126,9 @@ export class BudgetGuard {
   private lastCost = 0;
   /** USD held for in-flight calls (reserved, not yet settled). Counts toward the ceiling. */
   private reserved = 0;
+  /** Per-call ledger, oldest first; a ring buffer when maxLogEvents is set. */
+  private readonly spendEvents: SpendEvent[] = [];
+  private readonly maxLogEvents?: number;
 
   /**
    * @param limitUsd the spend ceiling, in USD. `0` blocks the very first call.
@@ -112,7 +149,16 @@ export class BudgetGuard {
         `nearLimitBps must be an integer in 0..10000, got ${nearLimitBps}`,
       );
     }
+    if (
+      options.maxLogEvents !== undefined &&
+      (!Number.isInteger(options.maxLogEvents) || options.maxLogEvents < 0)
+    ) {
+      throw new RangeError(
+        `maxLogEvents must be a non-negative integer, got ${options.maxLogEvents}`,
+      );
+    }
     this.limitUsd = limitUsd;
+    this.maxLogEvents = options.maxLogEvents;
     this.priceOverrides = options.priceOverrides;
     this.failClosed = options.failClosed ?? true;
     this.onBlock = options.onBlock ?? defaultOnBlock;
@@ -181,13 +227,16 @@ export class BudgetGuard {
    * Release a reservation and record the actual cost. `record` is `settle` with
    * no reservation. Returns the USD cost of this call; unpriceable-model handling
    * matches {@link BudgetGuard.record}, and any held reservation is released even
-   * on the warn-and-skip path.
+   * on the warn-and-skip path. A priced call appends one {@link SpendEvent} to
+   * {@link BudgetGuard.spendLog} (`label` tags it, e.g. with an agent/task name);
+   * the warn-and-skip path accrues nothing and logs nothing, so the ledger stays
+   * in lockstep with `spentUsd`.
    */
   settle(
     model: string,
     promptTokens: number,
     completionTokens: number,
-    options: { reserved?: number; price?: ManualPrice } = {},
+    options: { reserved?: number; price?: ManualPrice; label?: string } = {},
   ): number {
     const reserved = options.reserved ?? 0;
     // A bad reserved handle would corrupt this.reserved and break the ceiling for
@@ -237,6 +286,18 @@ export class BudgetGuard {
       this.spentUsd = this.limitUsd;
     }
     this.lastCost = cost;
+    this.appendEvent({
+      timestamp: Date.now() / 1000,
+      kind: "llm",
+      modelOrTool: model,
+      promptTokens,
+      completionTokens,
+      costUsd: cost,
+      ...(options.label !== undefined ? { label: options.label } : {}),
+      // 0 means "no reservation" (the plain record() path) — omit rather than
+      // log a meaningless zero.
+      ...(reserved ? { reserved } : {}),
+    });
     return cost;
   }
 
@@ -251,14 +312,48 @@ export class BudgetGuard {
     model: string,
     promptTokens: number,
     completionTokens: number,
-    options: { price?: ManualPrice } = {},
+    options: { price?: ManualPrice; label?: string } = {},
   ): number {
     return this.settle(model, promptTokens, completionTokens, {
       reserved: 0,
       price: options.price,
+      label: options.label,
     });
   }
 
+  /**
+   * Accrue a non-LLM cost (a paid tool/API call) against the same ceiling.
+   *
+   * Tools with direct dollar costs — search APIs, scrapers, sandboxes — spend the
+   * same budget the LLM calls do; `recordTool` folds them into `spentUsd` (so
+   * `check()` / `reserve()` see them) and appends a `kind: "tool"`
+   * {@link SpendEvent} to {@link BudgetGuard.spendLog}. The caller supplies the
+   * cost: tools have no token usage to price. Deliberately does NOT update the
+   * next-call estimate — that predicts the next *LLM* call, and a tool's price
+   * would skew it. Returns `costUsd`.
+   */
+  recordTool(tool: string, costUsd: number, options: { label?: string } = {}): number {
+    if (!Number.isFinite(costUsd) || costUsd < 0) {
+      throw new RangeError(`costUsd must be a finite, non-negative number, got ${costUsd}`);
+    }
+    this.spentUsd += costUsd;
+    // Same sub-epsilon clamp as settle(): never report a rounding-artifact
+    // crossing of the ceiling.
+    if (this.spentUsd - this.limitUsd > 0 && this.spentUsd - this.limitUsd < EPS) {
+      this.spentUsd = this.limitUsd;
+    }
+    this.appendEvent({
+      timestamp: Date.now() / 1000,
+      kind: "tool",
+      modelOrTool: tool,
+      promptTokens: null,
+      completionTokens: null,
+      costUsd,
+      ...(options.label !== undefined ? { label: options.label } : {}),
+    });
+    return costUsd;
+  }
+
   /**
    * Drop an in-flight reservation without recording spend (e.g. the call failed
    * before producing usage). Safe to call with `0`.
@@ -278,6 +373,55 @@ export class BudgetGuard {
     return Math.max(0, this.limitUsd - this.spentUsd - this.reserved);
   }
 
+  /**
+   * The per-call spend ledger, oldest first — one {@link SpendEvent} per priced
+   * `record()` / `settle()` / `recordTool()`. Returns a snapshot copy: mutating
+   * it cannot corrupt the ledger.
+   */
+  get spendLog(): SpendEvent[] {
+    return [...this.spendEvents];
+  }
+
+  /**
+   * The spend ledger as JSONL — one event per line, newline-terminated.
+   *
+   * The schema is stable and language-independent (snake_case keys, fixed order;
+   * optional fields omitted when absent), identical to the Python package's
+   * `export_log()`, so heterogeneous agents produce logs you can concatenate and
+   * analyse as one stream. (The *schema* is the contract, not the bytes: the two
+   * runtimes may render the same float differently, e.g. JS `0.0000025` vs
+   * Python `2.5e-06`.) Empty ledger yields `""`.
+   */
+  exportLog(): string {
+    return this.spendEvents
+      .map((e) => {
+        // snake_case wire shape, fixed key order — the cross-language schema.
+        const row: Record<string, unknown> = {
+          timestamp: e.timestamp,
+          kind: e.kind,
+          model_or_tool: e.modelOrTool,
+          prompt_tokens: e.promptTokens,
+          completion_tokens: e.completionTokens,
+          cost_usd: e.costUsd,
+        };
+        if (e.label !== undefined) row.label = e.label;
+        if (e.reserved !== undefined) row.reserved = e.reserved;
+        return `${JSON.stringify(row)}\n`;
+      })
+      .join("");
+  }
+
+  private appendEvent(event: SpendEvent): void {
+    // Frozen for parity with Python's frozen dataclass: spendLog copies the
+    // array but shares the event objects, so an unfrozen event would let a
+    // consumer silently rewrite logged history.
+    this.spendEvents.push(Object.freeze(event));
+    if (this.maxLogEvents !== undefined && this.spendEvents.length > this.maxLogEvents) {
+      // Ring buffer: drop the oldest overflow (at most one per append).
+      this.spendEvents.splice(0, this.spendEvents.length - this.maxLogEvents);
+    }
+  }
+
   /**
    * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
    *

js/src/guard.ts

@@ -10,6 +10,7 @@ export {
   BudgetGuard,
   type BudgetGuardOptions,
   type BudgetAdvisory,
+  type SpendEvent,
 } from "./guard.js";
 export {
   FloeGuardError,