Local Testing: consumer-context-service against Staging

Overview

Run the consumer-context-service locally, pointing at Fetch staging upstream services. This gives you a real integration test without deploying to ECS.

Prerequisites

Go 1.23+ installed
Network access to *.stage-services.fetchrewards.com (VPN required)
No Python sidecars needed for core functionality (brand/category/fuzzy-match degrade gracefully)
No Neo4j needed (graph endpoints return nil gracefully)

Build

cd /Users/s.hollinger/experiments/pilot-agent/full-agent/consumer-context-service
go build -o server ./cmd/server/

Run with Stage Services

ENVIRONMENT=local \
HTTP_PORT=9080 \
MCP_PORT=9081 \
FPS_BASE_URL="https://stage-fido-product-service.fetchrewards.com" \
FIDO_SEARCH_BASE_URL="https://stage-pam-ml-search.us-east-1.stage-services.fetchrewards.com" \
OFFER_SEARCH_BASE_URL="https://stage-offer-search-service.stage-ml.us-east-1.stage-services.fetchrewards.com" \
NELI_BASE_URL="https://stage-neli.fetchrewards.com" \
LIDAR_BASE_URL="https://stage-lidar-api.us-east-1.stage-services.fetchrewards.com" \
PURCHASE_HISTORY_BASE_URL="https://stage-purchase-history-service.fetchrewards.com" \
USER_SERVICE_BASE_URL="https://stage-user-service.fetchrewards.com" \
FIDORA_BASE_URL="https://stage-fido-assortment-service.us-east-1.stage-services.fetchrewards.com" \
OFFER_GUARDIAN_HOST="https://stage-offer-guardian.fetchrewards.com" \
OG_CACHE_ENABLED="false" \
BUTTON_BASE_URL="https://stage-button-merchant-service.us-east-1.stage-services.fetchrewards.com" \
RETAILER_BASE_URL="https://stage-retailer-service.fetchrewards.com" \
ERECEIPT_BASE_URL="https://stage-ereceipt-provider-service.fetchrewards.com" \
FIDO_INDEX_REFRESH="0" \
./server

Notes on env vars

HTTP_PORT=9080 / MCP_PORT=9081 avoids conflicts with Docker on 8080
FIDO_INDEX_REFRESH="0" disables the background FIDO index rebuild (avoids hitting OG /active endpoint on startup)
OG_CACHE_ENABLED="false" disables Kafka-backed OG cache (requires MSK brokers). Set OG_KAFKA_BROKERS and OG_CACHE_ENABLED=true if Kafka is accessible
Python sidecar URLs default to localhost — they’ll fail silently for purchase history enrichment
Neo4j is omitted — graph-dependent endpoints (candidates, history) return nil gracefully
Google search keys omitted — web search MCP tool unavailable

URL patterns per service

Fetch services use two URL patterns — external ALB and internal ALB:

Pattern	Format	Example
External	`https://stage-{service}.fetchrewards.com`	FPS, OG, Neli, PHS, Retailer, eReceipt, User Service
Internal	`https://stage-{service}.us-east-1.stage-services.fetchrewards.com`	FIDO Search, FIDORA, Button, LIDAR
Internal ML	`https://stage-{service}.stage-ml.us-east-1.stage-services.fetchrewards.com`	Offer Search

Ports

Transport	Default	Local Override	Description
REST API	8080	9080	HTTP endpoints
MCP	8081	9081	MCP tool server

Test Endpoints

Use port 9080 if running with HTTP_PORT=9080 override. Known stage FIDO: 062ba603-6ed2-4b01-b017-c37dcf53e491 (cheerios-ish product from FPS).

Health check

curl http://localhost:9080/health
# Expected: {"status":"ok"}

Product context (FPS lookup)

# Known FIDO ID that exists in stage FPS:
curl http://localhost:9080/v1/products/062ba603-6ed2-4b01-b017-c37dcf53e491/context
# Note: FPS returns 404 for FIDOs not in its attribute store — service returns empty fields gracefully

Product context with full enrichment (FPS + offers + user data)

curl "http://localhost:9080/v1/products/062ba603-6ed2-4b01-b017-c37dcf53e491/context?user_id={user_id}"

Batch product context

curl -X POST http://localhost:9080/v1/products/context \
  -H 'Content-Type: application/json' \
  -d '{"fido_ids": ["062ba603-6ed2-4b01-b017-c37dcf53e491"]}'

Product search (FIDO Search)

curl -X POST http://localhost:9080/v1/products/search \
  -H 'Content-Type: application/json' \
  -d '{"descriptions": ["organic milk"]}'
# Note: FIDO Search returns IDs that may not exist in FPS — product names may be empty

Offer search (Offer Search + optional Neli eligibility)

curl -X POST http://localhost:9080/v1/offers/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "coffee", "limit": 5}'

# With eligibility filtering:
curl -X POST http://localhost:9080/v1/offers/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "coffee", "limit": 5, "user_id": "some-user-id"}'

Offers for a product (Offer Guardian + FIDO Index)

# Requires FIDO_INDEX_REFRESH > 0 to populate the FIDO reverse index
curl "http://localhost:9080/v1/products/{fido_id}/offers"

Nearby offers (LIDAR)

curl -X POST http://localhost:9080/v1/offers/search/nearby \
  -H 'Content-Type: application/json' \
  -d '{"latitude": 40.7128, "longitude": -74.006, "user_id": "some-user"}'

Purchase history (PHS)

curl "http://localhost:9080/v1/users/{user_id}/purchases"
curl "http://localhost:9080/v1/users/{user_id}/purchases?category=Dairy&brand=Happy+Cow"

User profile

curl "http://localhost:9080/v1/users/{user_id}/profile"

Graph endpoints (require Neo4j — will return null without it)

curl "http://localhost:9080/v1/users/{user_id}/candidates?lookback_days=90"
curl "http://localhost:9080/v1/users/{user_id}/history?fido_id={fido_id}"

Troubleshooting

DNS resolution failures

Stage service hostnames resolve within Fetch VPN. If you get DNS errors, check VPN connection.

TLS errors

Stage services use valid certs. If you see TLS errors, your system CA bundle may be outdated.

Empty responses from FPS

FPS returns 404 for FIDO IDs not in its attribute store. The service treats 404 as “not found” (empty product fields, not an error). FIDO Search may return IDs that don’t exist in FPS — this is a data mismatch between the ML search index and the FPS attribute store. Use known prod FIDO ID 062ba603-6ed2-4b01-b017-c37dcf53e491 for meaningful results.

Offer Guardian returns no offers

If OG host is set but FIDO_INDEX_REFRESH=0, the FIDO index won’t be populated. GetOffersForProduct still works (direct OG call per FIDO), but the index-based reverse lookup won’t. Set FIDO_INDEX_REFRESH=“5m” to enable background indexing.

Config Reference

All env vars with defaults — see internal/config/config.go. Key cache TTL defaults:

Cache	TTL	Max Size
FPS metadata	1h	50,000
FIDORA retailer data	15m	20,000
Neli eligibility	5m	10,000
Button merchants	24h	50,000
Retailer venue type	30m	10,000