big refactor to use google places for lookups, not geocoding api

Author: ndbroadbent

src/caching/index.ts

@@ -9,6 +9,7 @@ export {
   generateCacheKey,
   generateClassifierCacheKey,
   generateEmbeddingCacheKey,
-  generateGeocodeCacheKey
+  generateGeocodeCacheKey,
+  generatePlaceLookupCacheKey
 } from './key'
 export type { CachedResponse, CacheKeyComponents, ResponseCache } from './types'

src/caching/integration.test.ts

@@ -10,7 +10,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createActivity } from '../test-support'
-import type { CandidateMessage, ClassifiedActivity, GeocoderConfig } from '../types'
+import type { CandidateMessage, ClassifiedActivity, PlaceLookupConfig } from '../types'
 import { FilesystemCache } from './filesystem'
 
 // Base config with required fields for all tests
@@ -23,6 +23,7 @@ const BASE_CONFIG = {
 const mockFetch = vi.fn()
 vi.mock('../http', () => ({
   httpFetch: mockFetch,
+  guardedFetch: mockFetch, // place-lookup uses guardedFetch
   handleHttpError: async (response: { status: number; text: () => Promise<string> }) => {
     const errorText = await response.text()
     return {
@@ -305,14 +306,14 @@ describe('Cache Integration', () => {
     })
   })
 
-  describe('geocodeActivities cache integration', () => {
-    const config: GeocoderConfig = {
+  describe('lookupActivityPlaces cache integration', () => {
+    const config: PlaceLookupConfig = {
       apiKey: 'test-key',
       regionBias: 'NZ'
     }
 
     it('calls API on cache miss', async () => {
-      const { geocodeActivities } = await import('../geocoder/index')
+      const { lookupActivityPlaces } = await import('../place-lookup/index')
 
       const suggestions = [createClassifiedActivity(1, 'Try the cafe', 'Cuba Street, Wellington')]
 
@@ -330,14 +331,14 @@ describe('Cache Integration', () => {
         })
       })
 
-      const result = await geocodeActivities(suggestions, config, cache)
+      const result = await lookupActivityPlaces(suggestions, config, cache)
 
       expect(result).toHaveLength(1)
       expect(mockFetch).toHaveBeenCalledTimes(1)
     })
 
     it('skips API call on cache hit', async () => {
-      const { geocodeActivities } = await import('../geocoder/index')
+      const { lookupActivityPlaces } = await import('../place-lookup/index')
 
       const suggestions = [createClassifiedActivity(1, 'Try the cafe', 'Cuba Street, Wellington')]
 
@@ -356,16 +357,16 @@ describe('Cache Integration', () => {
       })
 
       // First call - should hit API
-      await geocodeActivities(suggestions, config, cache)
+      await lookupActivityPlaces(suggestions, config, cache)
       expect(mockFetch).toHaveBeenCalledTimes(1)
 
       // Second call - should use cache
-      await geocodeActivities(suggestions, config, cache)
+      await lookupActivityPlaces(suggestions, config, cache)
       expect(mockFetch).toHaveBeenCalledTimes(1)
     })
 
     it('makes new API call for different locations', async () => {
-      const { geocodeActivities } = await import('../geocoder/index')
+      const { lookupActivityPlaces } = await import('../place-lookup/index')
 
       // Mock successful API responses
       mockFetch.mockResolvedValueOnce({
@@ -395,14 +396,14 @@ describe('Cache Integration', () => {
       })
 
       // First call
-      await geocodeActivities(
+      await lookupActivityPlaces(
         [createClassifiedActivity(1, 'Try the cafe', 'Cuba Street, Wellington')],
         config,
         cache
       )
 
       // Second call with different location
-      await geocodeActivities(
+      await lookupActivityPlaces(
         [createClassifiedActivity(2, 'Visit Queenstown', 'Queenstown, New Zealand')],
         config,
         cache

src/caching/key.ts

@@ -89,8 +89,30 @@ export function generateClassifierCacheKey(
   return `ai/${provider}/${model}/${promptSig}/${hash}`
 }
 
+/**
+ * Generate cache key for place lookup requests.
+ * Path: places/<type>/<hash>.json
+ *
+ * @param type - 'places' for Places API Text Search, 'geocode' for Geocoding API
+ * @param query - The search query or address
+ * @param regionBias - Optional region bias code
+ */
+export function generatePlaceLookupCacheKey(
+  type: 'places' | 'geocode',
+  query: string,
+  regionBias?: string
+): string {
+  const hash = generateCacheKey({
+    service: 'google',
+    model: type,
+    payload: { query, regionBias }
+  })
+  return `places/${type}/${hash}`
+}
+
 /**
  * Generate cache key for geocoding requests.
+ * @deprecated Use generatePlaceLookupCacheKey('geocode', ...) instead
  * Path: geo/google/<hash>.json
  */
 export function generateGeocodeCacheKey(location: string, regionBias?: string): string {

src/caching/pipeline.ts

@@ -14,7 +14,7 @@
  * ├── candidates.all.json
  * ├── scraped_urls.json
  * ├── classifications.json
- * └── geocodings.json
+ * └── place_lookups.json
  * ```
  *
  * The sha256 is computed from the input file bytes (NOT content).
@@ -36,13 +36,13 @@ type PipelineStage =
   | 'scrape_stats'
   | 'scrape_metadata'
   | 'classify_stats'
-  | 'geocode_stats'
+  | 'place_lookup_stats'
   | 'fetch_images_stats'
   | 'candidates.heuristics'
   | 'candidates.embeddings'
   | 'candidates.all'
   | 'classifications'
-  | 'geocodings'
+  | 'place_lookups'
   | 'images'
 
 interface PipelineRunMeta {
@@ -97,7 +97,7 @@ const STAGES_WITH_TIMESTAMPS: PipelineStage[] = [
   'candidates.embeddings',
   'candidates.all',
   'classifications',
-  'geocodings'
+  'place_lookups'
 ]
 
 function stageHasTimestamps(stage: PipelineStage): boolean {

src/cli.ts

@@ -17,9 +17,9 @@ import { cmdExport } from './cli/commands/export'
 import { cmdFetchImageUrls } from './cli/commands/fetch-image-urls'
 import { cmdFetchImages } from './cli/commands/fetch-images'
 import { cmdFilter } from './cli/commands/filter'
-import { cmdGeocode } from './cli/commands/geocode'
 import { cmdList } from './cli/commands/list'
 import { cmdParse } from './cli/commands/parse'
+import { cmdPlaceLookup } from './cli/commands/place-lookup'
 import { cmdPreview } from './cli/commands/preview'
 import { cmdScan } from './cli/commands/scan'
 import { cmdScrapeUrls } from './cli/commands/scrape-urls'
@@ -72,8 +72,8 @@ async function main(): Promise<void> {
         await cmdClassify(args, logger)
         break
 
-      case 'geocode':
-        await cmdGeocode(args, logger)
+      case 'place-lookup':
+        await cmdPlaceLookup(args, logger)
         break
 
       case 'fetch-image-urls':

src/cli/args.test.ts

@@ -42,10 +42,10 @@ describe('CLI Args', () => {
 
     it('parses boolean flags for analyze', () => {
       const args = parseArgs(
-        ['analyze', 'chat.txt', '-c', 'NZ', '--skip-geocoding', '--dry-run', '--verbose'],
+        ['analyze', 'chat.txt', '-c', 'NZ', '--skip-place-lookup', '--dry-run', '--verbose'],
         false
       )
-      expect(args.skipGeocoding).toBe(true)
+      expect(args.skipPlaceLookup).toBe(true)
       expect(args.dryRun).toBe(true)
       expect(args.verbose).toBe(true)
     })
@@ -57,7 +57,7 @@ describe('CLI Args', () => {
       expect(args.minConfidence).toBe(0.5)
       expect(args.maxResults).toBe(10)
       expect(args.maxMessages).toBeUndefined()
-      expect(args.skipGeocoding).toBe(false)
+      expect(args.skipPlaceLookup).toBe(false)
       expect(args.quiet).toBe(false)
       expect(args.verbose).toBe(false)
       expect(args.dryRun).toBe(false)

src/cli/args.ts

@@ -16,9 +16,9 @@ export interface CLIArgs {
   outputDir: string
   formats: string[]
   minConfidence: number
-  skipGeocoding: boolean
+  skipPlaceLookup: boolean
   fetchImages: boolean
-  skipCdn: boolean
+  skipMediaLibrary: boolean
   skipPixabay: boolean
   skipWikipedia: boolean
   skipGooglePlaces: boolean
@@ -172,9 +172,9 @@ function buildCLIArgs(commandName: string, input: string, opts: Record<string, u
     outputDir: typeof opts.outputDir === 'string' ? opts.outputDir : DEFAULT_OUTPUT_DIR,
     formats: format.split(',').map((f) => f.trim()),
     minConfidence: Number.parseFloat(String(opts.minConfidence ?? '0.5')),
-    skipGeocoding: opts.skipGeocoding === true,
+    skipPlaceLookup: opts.skipPlaceLookup === true,
     fetchImages: opts.images === true,
-    skipCdn: opts.imageCdn === false,
+    skipMediaLibrary: opts.mediaLibrary === false,
     skipPixabay: opts.skipPixabay === true,
     skipWikipedia: opts.skipWikipedia === true,
     skipGooglePlaces: opts.skipGooglePlaces === true,

src/cli/commands.ts

@@ -92,6 +92,20 @@ function addPrefixedPdfOptions(cmd: Command): Command {
     .option('--pdf-sort <order>', 'Sort for PDF: score, oldest, newest (overrides --export-sort)')
 }
 
+/**
+ * Add common options for classify and place-lookup commands.
+ */
+function addClassifyOptions(cmd: Command): Command {
+  return cmd
+    .option('-c, --home-country <name>', 'Your home country (auto-detected from IP if not set)')
+    .option('--timezone <tz>', 'Your timezone (auto-detected from system if not set)')
+    .option('--json [file]', 'Output as JSON (to file if specified, otherwise stdout)')
+    .option('-n, --max-results <num>', 'Max results to display', '10')
+    .option('-m, --max-messages <num>', 'Max messages to process (for testing)')
+    .option('-a, --all', 'Show all activities (default: top 10)')
+    .option('--dry-run', 'Show stats without API calls')
+}
+
 /**
  * Add common pipeline options shared by analyze and export commands.
  */
@@ -106,7 +120,7 @@ function addPipelineOptions(cmd: Command): Command {
       'csv,excel,json,map,pdf'
     )
     .option('--min-confidence <num>', 'Minimum confidence threshold', '0.5')
-    .option('--skip-geocoding', 'Skip geocoding step')
+    .option('--skip-place-lookup', 'Skip place lookup step')
     .option('--images', 'Fetch images for activities (slower, uses external APIs)')
     .option(
       '--media-library-path <path>',
@@ -215,7 +229,7 @@ export function createProgram(): Command {
   const baseAnalyzeCmd = program
     .command('analyze')
     .description(
-      'Run the complete pipeline (parse → filter → scrape-urls → classify → geocode → export)'
+      'Run the complete pipeline (parse → filter → scrape-urls → classify → place-lookup → export)'
     )
     .argument('<input>', 'Chat export (.zip, directory, or .txt file)')
 
@@ -287,38 +301,28 @@ export function createProgram(): Command {
     .option('--dry-run', 'Show URL count without scraping')
 
   // ============ CLASSIFY ============
-  program
-    .command('classify')
-    .description('Classify candidates into activities using AI')
-    .argument('<input>', 'Chat export (.zip, directory, or .txt file)')
-    .option('-c, --home-country <name>', 'Your home country (auto-detected from IP if not set)')
-    .option('--timezone <tz>', 'Your timezone (auto-detected from system if not set)')
-    .option('--json [file]', 'Output as JSON (to file if specified, otherwise stdout)')
-    .option('-n, --max-results <num>', 'Max results to display', '10')
-    .option('-m, --max-messages <num>', 'Max messages to process (for testing)')
-    .option('-a, --all', 'Show all activities (default: top 10)')
-    .option('--dry-run', 'Show stats without API calls')
+  addClassifyOptions(
+    program
+      .command('classify')
+      .description('Classify candidates into activities using AI')
+      .argument('<input>', 'Chat export (.zip, directory, or .txt file)')
+  )
 
-  // ============ GEOCODE ============
-  program
-    .command('geocode')
-    .description('Geocode classified activities using Google Maps API')
-    .argument('<input>', 'Chat export (.zip, directory, or .txt file)')
-    .option('-c, --home-country <name>', 'Your home country (auto-detected from IP if not set)')
-    .option('--timezone <tz>', 'Your timezone (auto-detected from system if not set)')
-    .option('--json [file]', 'Output as JSON (to file if specified, otherwise stdout)')
-    .option('-n, --max-results <num>', 'Max results to display', '10')
-    .option('-m, --max-messages <num>', 'Max messages to process (for testing)')
-    .option('-a, --all', 'Show all geocoded activities (default: top 10)')
-    .option('--dry-run', 'Show stats without API calls')
+  // ============ PLACE-LOOKUP ============
+  addClassifyOptions(
+    program
+      .command('place-lookup')
+      .description('Look up places for classified activities using Google Maps API')
+      .argument('<input>', 'Chat export (.zip, directory, or .txt file)')
+  )
 
   // ============ FETCH-IMAGE-URLS ============
   program
     .command('fetch-image-urls')
     .description('Fetch image URLs for geocoded activities')
     .argument('<input>', 'Chat export file or directory')
     .option('--json [file]', 'Output as JSON (to file if specified, otherwise stdout)')
-    .option('--no-image-cdn', 'Skip CDN default images (fetch all from APIs)')
+    .option('--no-media-library', 'Skip media library images')
     .option('--skip-pixabay', 'Skip Pixabay image search')
     .option('--skip-wikipedia', 'Skip Wikipedia image lookup')
     .option('--skip-google-places', 'Skip Google Places photos')

src/cli/commands/export.ts

@@ -62,12 +62,12 @@ export async function cmdExport(args: CLIArgs, logger: Logger): Promise<void> {
   if (needsThumbnails) {
     const result = await runner.run('fetchImages')
     thumbnails = result.thumbnails
-    // Get geocoded activities from the runner
-    const geocodeResult = await runner.run('geocode')
-    geocoded = geocodeResult.activities
+    // Get place lookup activities from the runner
+    const placeLookupResult = await runner.run('placeLookup')
+    geocoded = placeLookupResult.activities
   } else {
-    // Just run through geocode step
-    const result = await runner.run('geocode')
+    // Just run through place lookup step
+    const result = await runner.run('placeLookup')
     geocoded = result.activities
   }
 

src/cli/commands/fetch-image-urls.ts

@@ -58,11 +58,11 @@ function logStatsSummary(stats: FetchImagesStats, logger: Logger): void {
 export async function cmdFetchImageUrls(args: CLIArgs, logger: Logger): Promise<void> {
   const { ctx, config } = await initCommandContext('Fetch Image URLs', args, logger)
 
-  // Use StepRunner to handle dependencies: geocode → fetch-image-urls
+  // Use StepRunner to handle dependencies: placeLookup → fetch-image-urls
   const runner = new StepRunner(ctx, args, config, logger)
 
-  // Run geocode step (which runs the full pipeline up to geocode)
-  const { activities: geocodedActivities } = await runner.run('geocode')
+  // Run place lookup step (which runs the full pipeline up to place-lookup)
+  const { activities: geocodedActivities } = await runner.run('placeLookup')
 
   logger.log(`   Geocoded ${geocodedActivities.length} activities`)
 
@@ -76,7 +76,7 @@ export async function cmdFetchImageUrls(args: CLIArgs, logger: Logger): Promise<
     logger.log('\n📊 Image Fetch Estimate (dry run)')
     logger.log(`   Activities: ${geocodedActivities.length}`)
     const sources: string[] = []
-    if (!args.skipCdn) sources.push('CDN')
+    if (!args.skipMediaLibrary) sources.push('Media Library')
     if (!args.skipWikipedia) sources.push('Wikipedia')
     if (!args.skipPixabay && process.env.PIXABAY_API_KEY) sources.push('Pixabay')
     if (!args.skipGooglePlaces && process.env.GOOGLE_MAPS_API_KEY) sources.push('Google Places')
@@ -88,7 +88,7 @@ export async function cmdFetchImageUrls(args: CLIArgs, logger: Logger): Promise<
   // Media library path can come from CLI arg or config
   const mediaLibraryPath = args.mediaLibraryPath ?? config?.mediaLibraryPath
   const fetchResult = await stepFetchImageUrls(ctx, geocodedActivities, {
-    skipCdn: args.skipCdn,
+    skipMediaLibrary: args.skipMediaLibrary,
     skipPixabay: args.skipPixabay,
     skipWikipedia: args.skipWikipedia,
     skipGooglePlaces: args.skipGooglePlaces,
@@ -153,9 +153,9 @@ function displayActivities(
 
     if (image) {
       const queryInfo = image.query ? ` (query: "${image.query}")` : ''
-      logger.log(`   🖼️  ${image.source}${queryInfo}: ${image.url}`)
-      if (image.attribution) {
-        logger.log(`   📝 ${image.attribution.name}`)
+      logger.log(`   🖼️  ${image.meta.source}${queryInfo}: ${image.imageUrl}`)
+      if (image.meta.attribution) {
+        logger.log(`   📝 ${image.meta.attribution.name}`)
       }
     } else {
       logger.log(`   ⚠️  No image found`)