Configuration

Configuration

ShelfWise runs out of the box with no API keys. Optional providers can be enabled for higher-confidence enrichment and additional search sources.

Environment Variables

Copy backend/.env.example to backend/.env and fill in the values you need.

cp backend/.env.example backend/.env

Optional AI / LLM Providers

Variable	Description
FOUNDRY_ENDPOINT	Azure OpenAI, GitHub Models, or Ollama endpoint URL
FOUNDRY_API_KEY	API key for the endpoint
FOUNDRY_MODEL	Model name (default: gpt-4.1-mini)

Azure OpenAI Example

FOUNDRY_ENDPOINT=https://your-resource.openai.azure.com/openai/deployments/gpt-4.1-mini/chat/completions?api-version=2024-02-01
FOUNDRY_API_KEY=your-azure-openai-key
FOUNDRY_MODEL=gpt-4.1-mini

GitHub Models Example

FOUNDRY_ENDPOINT=https://models.inference.ai.azure.com
FOUNDRY_API_KEY=your-github-token
FOUNDRY_MODEL=gpt-4.1-mini

Ollama Example

FOUNDRY_ENDPOINT=http://localhost:11434/v1
FOUNDRY_API_KEY=ollama
FOUNDRY_MODEL=llama3.1

Scraper Tuning

Variable	Description
SHELFWISE_MAX_REGISTRY_SOURCES	Number of registry sources to query per UPC (default: 10, max: 271)
SHELFWISE_RETRIES	Number of retries for each HTTP request (default: 2)
SHELFWISE_REQUEST_TIMEOUT	HTTP request timeout in seconds (default: 10.0)
SHELFWISE_CIRCUIT_FAILURE_THRESHOLD	Failures before a source circuit opens (default: 5)
SHELFWISE_CIRCUIT_RECOVERY_TIMEOUT	Seconds before a tripped circuit tries again (default: 60.0)
SHELFWISE_IMAGE_DEDUP_THRESHOLD	Perceptual-hash Hamming distance threshold for image deduplication (default: 8)

Optional Search Providers

Variable	Description
BRAVE_API_KEY	Brave Search API key for web fallback
GOOGLE_API_KEY	Google Custom Search API key
GOOGLE_CX	Google Programmable Search Engine ID

One-Click Azure Setup

Run the provided PowerShell script to provision Azure OpenAI:

backend/setup-azure-openai.ps1

Follow the prompts to create or select a resource group and deployment.

Deterministic Local Mode

When no LLM endpoint is configured, ShelfWise uses:

• Local source weighting and voting
• Jaccard similarity for name deduplication
• Pillow-based image verification
• BM25-style knowledge graph retrieval

This mode is fully functional and requires zero cloud credentials.

Tuning the Scraper Registry

backend/scraper_registry.json contains 271 configurable sources. By default the top 10 weighted sources are queried per UPC (configurable via SHELFWISE_MAX_REGISTRY_SOURCES). Adjust the weight field to change priority, or set enabled: false to disable a source.

Docker Environment

When running via Docker Compose, create a .env file in the project root or pass variables in docker-compose.yml:

services:
  backend:
    environment:
      - FOUNDRY_API_KEY=${FOUNDRY_API_KEY}

Security Notes

• Never commit .env files. They are already gitignored.
• Rotate API keys regularly.
• Use least-privilege keys when possible.