Add usage data to classifier and place-lookup APIs

Phase 5 of credit metering integration:
- Add LlmUsage type (inputTokens, outputTokens) to track LLM API usage
- Add PlaceLookupUsage type (placesSearchCalls, geocodingCalls) to track Places API usage
- Update classifyMessages() to return ClassifyMessagesResult with activities + usage
- Update classifyBatch() to return ClassifyBatchResult with activities + usage
- Update lookupActivityPlace() to return LookupActivityResult with activity + usage
- Update lookupActivityPlaces() to return LookupActivitiesResult with activities + usage
- Add helper functions for adding usage data (addLlmUsage, addPlaceLookupUsage)
- Add empty usage constants (EMPTY_LLM_USAGE, EMPTY_PLACE_LOOKUP_USAGE)
- Export new types from shared module for lightweight imports
- Update all tests and consumers to use new .activities property

Breaking change: Consumer code must now access result.value.activities
instead of result.value for classifier and place-lookup results.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ndbroadbent

src/caching/integration.test.ts

@@ -205,9 +205,9 @@ describe('Cache Integration', () => {
 
       // Results should have same content (timestamps may differ due to JSON serialization)
       if (result1.ok && result2.ok) {
-        expect(result2.value).toHaveLength(result1.value.length)
-        expect(result2.value[0]?.activity).toBe(result1.value[0]?.activity)
-        expect(result2.value[0]?.city).toBe(result1.value[0]?.city)
+        expect(result2.value.activities).toHaveLength(result1.value.activities.length)
+        expect(result2.value.activities[0]?.activity).toBe(result1.value.activities[0]?.activity)
+        expect(result2.value.activities[0]?.city).toBe(result1.value.activities[0]?.city)
       }
     })
 

src/classifier/images-schema.integration.test.ts

@@ -74,7 +74,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -115,7 +115,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -155,7 +155,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -197,7 +197,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -237,7 +237,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -277,7 +277,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 
@@ -321,7 +321,7 @@ describe('Classifier Images Schema (IMAGES.md Examples)', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error(result.error.message)
 
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity')
 

src/classifier/index.test.ts

@@ -265,9 +265,9 @@ describe('Classifier Module', () => {
 
       expect(result.ok).toBe(true)
       if (result.ok) {
-        expect(result.value).toHaveLength(1)
-        expect(result.value[0]?.activity).toBe('Italian Restaurant')
-        expect(result.value[0]?.category).toBe('food')
+        expect(result.value.activities).toHaveLength(1)
+        expect(result.value.activities[0]?.activity).toBe('Italian Restaurant')
+        expect(result.value.activities[0]?.category).toBe('food')
       }
     })
 
@@ -423,7 +423,7 @@ describe('Classifier Module', () => {
 
       expect(result.ok).toBe(true)
       if (result.ok) {
-        expect(result.value[0]?.category).toBe('other')
+        expect(result.value.activities[0]?.category).toBe('other')
       }
     })
 
@@ -519,7 +519,7 @@ describe('Classifier Module', () => {
 
       expect(result.ok).toBe(true)
       if (result.ok) {
-        expect(result.value[0]?.activity).toBe('Fallback Test')
+        expect(result.value.activities[0]?.activity).toBe('Fallback Test')
       }
       expect(mockFetch).toHaveBeenCalledTimes(2)
       expect(mockFetch).toHaveBeenNthCalledWith(

src/classifier/index.ts

@@ -10,10 +10,13 @@ import type { ResponseCache } from '../caching/types'
 import { type EntityType, VALID_LINK_TYPES } from '../search/types'
 import {
   type ActivityCategory,
+  addLlmUsage,
   type CandidateMessage,
   type ClassifiedActivity,
   type ClassifierConfig,
   calculateCombinedScore,
+  EMPTY_LLM_USAGE,
+  type LlmUsage,
   type Result
 } from '../types'
 import { DEFAULT_MODELS } from './models'
@@ -27,6 +30,18 @@ import { callProviderWithFallbacks } from './providers'
 import type { ParsedClassification } from './response-parser'
 import { countTokens, MAX_BATCH_TOKENS } from './tokenizer'
 
+/** Result from classifyBatch including activities and usage data */
+export interface ClassifyBatchResult {
+  readonly activities: ClassifiedActivity[]
+  readonly usage: LlmUsage
+}
+
+/** Result from classifyMessages including activities and total usage */
+export interface ClassifyMessagesResult {
+  readonly activities: ClassifiedActivity[]
+  readonly usage: LlmUsage
+}
+
 export { createSmartBatches, groupCandidatesByProximity } from './batching'
 export type { ResolvedModel } from './models'
 export {
@@ -149,13 +164,14 @@ function toClassifiedActivity(
  * @param config Classifier configuration
  * @param cache Optional response cache
  * @param promptType Optional prompt type override (auto-detected if not specified)
+ * @returns Result with activities AND usage data (usage is 0 for cache hits)
  */
 export async function classifyBatch(
   candidates: readonly CandidateMessage[],
   config: ClassifierConfig,
   cache?: ResponseCache,
   promptType?: PromptType
-): Promise<Result<ClassifiedActivity[]>> {
+): Promise<Result<ClassifyBatchResult>> {
   const prompt = buildClassificationPrompt(
     candidates,
     {
@@ -191,7 +207,7 @@ export async function classifyBatch(
 
   try {
     const expectedIds = candidates.map((c) => c.messageId)
-    const parsed = parseClassificationResponse(responseResult.value, expectedIds)
+    const parsed = parseClassificationResponse(responseResult.value.text, expectedIds)
 
     // Map responses to candidates, filtering out invalid classifications
     const suggestions: ClassifiedActivity[] = []
@@ -206,7 +222,10 @@ export async function classifyBatch(
       }
     }
 
-    return { ok: true, value: suggestions }
+    return {
+      ok: true,
+      value: { activities: suggestions, usage: responseResult.value.usage }
+    }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     return {
@@ -233,6 +252,12 @@ function createBatches(
   return batches
 }
 
+/** Internal result from processBatches */
+interface ProcessBatchesResult {
+  activities: ClassifiedActivity[]
+  usage: LlmUsage
+}
+
 /**
  * Process batches of a specific type.
  */
@@ -244,8 +269,9 @@ async function processBatches(
   model: string,
   batchIndexOffset: number,
   totalBatches: number
-): Promise<Result<ClassifiedActivity[]>> {
+): Promise<Result<ProcessBatchesResult>> {
   const results: ClassifiedActivity[] = []
+  let totalUsage: LlmUsage = EMPTY_LLM_USAGE
 
   for (let i = 0; i < batches.length; i++) {
     const batch = batches[i]
@@ -281,14 +307,15 @@ async function processBatches(
     config.onBatchComplete?.({
       batchIndex: globalBatchIndex,
       totalBatches,
-      activityCount: result.value.length,
+      activityCount: result.value.activities.length,
       durationMs
     })
 
-    results.push(...result.value)
+    results.push(...result.value.activities)
+    totalUsage = addLlmUsage(totalUsage, result.value.usage)
   }
 
-  return { ok: true, value: results }
+  return { ok: true, value: { activities: results, usage: totalUsage } }
 }
 
 /**
@@ -300,13 +327,13 @@ async function processBatches(
  * @param candidates Candidate messages to classify
  * @param config Classifier configuration
  * @param cache Optional response cache to prevent duplicate API calls
- * @returns Classified suggestions or error
+ * @returns Classified activities with aggregated usage data, or error
  */
 export async function classifyMessages(
   candidates: readonly CandidateMessage[],
   config: ClassifierConfig,
   cache?: ResponseCache
-): Promise<Result<ClassifiedActivity[]>> {
+): Promise<Result<ClassifyMessagesResult>> {
   const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE
   const model = config.model ?? DEFAULT_MODELS[config.provider]
 
@@ -319,6 +346,7 @@ export async function classifyMessages(
   const totalBatches = suggestionBatches.length + agreementBatches.length
 
   const results: ClassifiedActivity[] = []
+  let totalUsage: LlmUsage = EMPTY_LLM_USAGE
 
   // Process suggestion batches first
   if (suggestionBatches.length > 0) {
@@ -334,7 +362,8 @@ export async function classifyMessages(
     if (!suggestionResult.ok) {
       return suggestionResult
     }
-    results.push(...suggestionResult.value)
+    results.push(...suggestionResult.value.activities)
+    totalUsage = addLlmUsage(totalUsage, suggestionResult.value.usage)
   }
 
   // Process agreement batches
@@ -351,10 +380,11 @@ export async function classifyMessages(
     if (!agreementResult.ok) {
       return agreementResult
     }
-    results.push(...agreementResult.value)
+    results.push(...agreementResult.value.activities)
+    totalUsage = addLlmUsage(totalUsage, agreementResult.value.usage)
   }
 
-  return { ok: true, value: results }
+  return { ok: true, value: { activities: results, usage: totalUsage } }
 }
 
 /**

src/classifier/pronoun-resolution.integration.test.ts

@@ -79,7 +79,7 @@ describe('Classifier Pronoun Resolution', () => {
 
     // Verify the structure without checking exact timestamp (timezone-dependent)
     expect(result.value).toHaveLength(1)
-    const activity = result.value[0]
+    const activity = result.value.activities[0]
     expect(activity).toBeDefined()
     if (!activity) throw new Error('No activity found')