@sprucelabs/sprucebot-llm 17.0.0 → 18.0.0

package/README.md

@@ -22,6 +22,9 @@ A TypeScript library for leveraging large language models to do... anything!
     * [Anthropic](#anthropic-adapter) - Claude models with prompt caching support
     * [Ollama](#ollama-adapter) - Run local models like Llama, Mistral, etc.
     * [Custom adapters](#custom-adapters) - Implement your own
+* [Track token usage](#tracking-token-usage)
+    * Read cumulative input/output/total tokens from any adapter
+    * Includes Anthropic prompt-cache token counts
 * Fully typed
 	* Built in modern TypeScript
 	* Fully typed schema-based state management (powered by `@sprucelabs/schema`)
@@ -192,6 +195,7 @@ adapter.setReasoningEffort('low')
 - `adapter.setModel(model)`: set a default model for all requests unless a Skill overrides it.
 - `adapter.setMessageMemoryLimit(limit)`: limit how many tracked messages are sent to OpenAI.
 - `adapter.setReasoningEffort(effort)`: set `reasoning_effort` for models that support it.
+- `adapter.getTokenUsage()`: returns cumulative [token usage](#tracking-token-usage) for this adapter. The OpenAI adapter currently returns zeros (not yet implemented).
 - `OpenAiAdapter.OpenAI`: assign a custom OpenAI client class (useful for tests).
 
 Requests are sent via `openai.chat.completions.create(...)` with messages built by the adapter from the Bot state and history.
@@ -234,6 +238,8 @@ Token usage (including cache creation and cache read tokens) is logged at the `i
 [TOKEN USAGE] input=1234 cache_create=800 cache_read=400 output=256
 ```
 
+The same numbers are also available programmatically via [`adapter.getTokenUsage()`](#tracking-token-usage).
+
 No configuration is required — caching is applied automatically.
 
 ### Ollama adapter
@@ -270,6 +276,48 @@ await bot.sendMessage('Hello!')
 
 The Ollama adapter connects to `http://localhost:11434/v1` by default (Ollama's OpenAI-compatible endpoint).
 
+### Tracking token usage
+
+Every adapter implements `getTokenUsage()`, which returns the **cumulative** token usage for that adapter instance since it was created:
+
+```ts
+import { LmmTokenUsage } from '@sprucelabs/sprucebot-llm'
+
+await bot.sendMessage('Hello!')
+
+const usage: LmmTokenUsage = adapter.getTokenUsage()
+// {
+//   inputTokens: 1234,
+//   outputTokens: 256,
+//   totalTokens: 1490,
+//   cacheCreationTokens: 800, // Anthropic only
+//   cacheReadTokens: 400,     // Anthropic only
+// }
+```
+
+The `LmmTokenUsage` shape:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `inputTokens` | `number` | Prompt / input tokens |
+| `outputTokens` | `number` | Completion / output tokens |
+| `totalTokens` | `number` | `inputTokens + outputTokens` |
+| `cacheCreationTokens` | `number` (optional) | Anthropic only — tokens written to the prompt cache |
+| `cacheReadTokens` | `number` (optional) | Anthropic only — tokens served from the prompt cache |
+
+**Adapter support:**
+
+| Adapter | `getTokenUsage()` |
+|---------|-------------------|
+| Anthropic | ✅ Fully tracked, including cache tokens |
+| OpenAI | ⚠️ Returns zeros — not yet implemented |
+| Ollama | ⚠️ Returns zeros — not yet implemented |
+
+**Things to know:**
+
+- **Cumulative, not per-call.** Totals accumulate across every `sendMessage` call on the adapter, and there is no reset method. To measure a single call, read `getTokenUsage()` before and after and diff the values.
+- **Per adapter, not per bot.** Usage lives on the adapter instance. If you share one adapter across multiple bots (e.g. through a single `SprucebotLlmFactory`), the totals aggregate across all of them.
+
 ### Custom adapters
 
 You can bring your own adapter by implementing the `LlmAdapter` interface and passing it to `SprucebotLlmFactory.Factory(...)`:
@@ -277,6 +325,8 @@ You can bring your own adapter by implementing the `LlmAdapter` interface and pa
 ```ts
 import {
 	LlmAdapter,
+	LllmReasoningEffort,
+	LmmTokenUsage,
 	SprucebotLlmBot,
 	SprucebotLlmFactory,
 } from '@sprucelabs/sprucebot-llm'
@@ -288,6 +338,15 @@ class MyAdapter implements LlmAdapter {
 		// Send to your model and return the model response as a string
 		return `echo: ${messages[messages.length - 1]?.message ?? ''}`
 	}
+
+	setModel(_model: string) {}
+	setReasoningEffort(_effort: LllmReasoningEffort) {}
+	setMemoryLimit(_limit: number) {}
+
+	// Return cumulative token usage for this adapter (zeros if you don't track it)
+	getTokenUsage(): LmmTokenUsage {
+		return { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+	}
 }
 
 const bots = SprucebotLlmFactory.Factory(new MyAdapter())

package/build/esm/index.d.ts

@@ -10,7 +10,7 @@ export { default as SpyLlmAdapter } from './tests/SpyAdapter';
 export { default as SpyOpenAiApi } from './bots/adapters/SpyOpenAiModule';
 export { default as OllamaAdapter } from './bots/adapters/OllamaAdapter';
 export * from './bots/adapters/OllamaAdapter';
-export { default as AthropicAdapter } from './bots/adapters/AnthropicAdapter';
+export { default as AnthropicAdapter } from './bots/adapters/AnthropicAdapter';
 export * from './bots/adapters/AnthropicAdapter';
 export { default as LlmAdapterLoader } from './bots/adapters/LlmAdapterLoader';
 export * from './bots/adapters/LlmAdapterLoader';

package/build/esm/index.js

@@ -10,7 +10,7 @@ export { default as SpyLlmAdapter } from './tests/SpyAdapter.js';
 export { default as SpyOpenAiApi } from './bots/adapters/SpyOpenAiModule.js';
 export { default as OllamaAdapter } from './bots/adapters/OllamaAdapter.js';
 export * from './bots/adapters/OllamaAdapter.js';
-export { default as AthropicAdapter } from './bots/adapters/AnthropicAdapter.js';
+export { default as AnthropicAdapter } from './bots/adapters/AnthropicAdapter.js';
 export * from './bots/adapters/AnthropicAdapter.js';
 export { default as LlmAdapterLoader } from './bots/adapters/LlmAdapterLoader.js';
 export * from './bots/adapters/LlmAdapterLoader.js';

package/build/index.d.ts

@@ -10,7 +10,7 @@ export { default as SpyLlmAdapter } from './tests/SpyAdapter';
 export { default as SpyOpenAiApi } from './bots/adapters/SpyOpenAiModule';
 export { default as OllamaAdapter } from './bots/adapters/OllamaAdapter';
 export * from './bots/adapters/OllamaAdapter';
-export { default as AthropicAdapter } from './bots/adapters/AnthropicAdapter';
+export { default as AnthropicAdapter } from './bots/adapters/AnthropicAdapter';
 export * from './bots/adapters/AnthropicAdapter';
 export { default as LlmAdapterLoader } from './bots/adapters/LlmAdapterLoader';
 export * from './bots/adapters/LlmAdapterLoader';

package/build/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockAdapterLoader = exports.LlmAdapterLoader = exports.AthropicAdapter = exports.OllamaAdapter = exports.SpyOpenAiApi = exports.SpyLlmAdapter = exports.SpyLllmBot = exports.MockLlmSkill = exports.SprucebotLlmError = exports.OpenAiAdapter = exports.SprucebotLlmSkillImpl = exports.SprucebotLlmBotImpl = exports.SprucebotLlmFactory = void 0;
+exports.MockAdapterLoader = exports.LlmAdapterLoader = exports.AnthropicAdapter = exports.OllamaAdapter = exports.SpyOpenAiApi = exports.SpyLlmAdapter = exports.SpyLllmBot = exports.MockLlmSkill = exports.SprucebotLlmError = exports.OpenAiAdapter = exports.SprucebotLlmSkillImpl = exports.SprucebotLlmBotImpl = exports.SprucebotLlmFactory = void 0;
 var SprucebotLlmFactory_1 = require("./bots/SprucebotLlmFactory");
 Object.defineProperty(exports, "SprucebotLlmFactory", { enumerable: true, get: function () { return __importDefault(SprucebotLlmFactory_1).default; } });
 var SprucebotLlmBotImpl_1 = require("./bots/SprucebotLlmBotImpl");
@@ -41,7 +41,7 @@ var OllamaAdapter_1 = require("./bots/adapters/OllamaAdapter");
 Object.defineProperty(exports, "OllamaAdapter", { enumerable: true, get: function () { return __importDefault(OllamaAdapter_1).default; } });
 __exportStar(require("./bots/adapters/OllamaAdapter"), exports);
 var AnthropicAdapter_1 = require("./bots/adapters/AnthropicAdapter");
-Object.defineProperty(exports, "AthropicAdapter", { enumerable: true, get: function () { return __importDefault(AnthropicAdapter_1).default; } });
+Object.defineProperty(exports, "AnthropicAdapter", { enumerable: true, get: function () { return __importDefault(AnthropicAdapter_1).default; } });
 __exportStar(require("./bots/adapters/AnthropicAdapter"), exports);
 var LlmAdapterLoader_1 = require("./bots/adapters/LlmAdapterLoader");
 Object.defineProperty(exports, "LlmAdapterLoader", { enumerable: true, get: function () { return __importDefault(LlmAdapterLoader_1).default; } });

package/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "17.0.0",
+  "version": "18.0.0",
   "files": [
     "build"
   ],