Forage

Home Page
Naive keyword search returns one random match. The enriched agent composes a 3-item, budget-tracked cart. Same data, different outcome.
Three items out of stock. The agent substitutes, rechecks the budget, and badges every swap with the original product it replaced.
No hallucinated matches. The agent reports what's missing, shows the closest option, and recommends what to add to the catalog.

Inspiration

I built a commerce agent in production. We killed it after hallucination testing. The agent fabricated product attributes, ignored constraints, and couldn't distinguish relevant results from noise. The catalog was the problem: descriptions written for humans, with no structure an agent could reason over.

Forage exists to answer one question: can an agent compose a multi-item shopping solution from a merchant catalog while showing exactly how it reached each decision?

What it does

Give Forage a natural-language goal ("business casual outfit for a job interview, budget $150"), and it decomposes the request into explicit and inferred constraints, searches structured catalog attributes, checks stock, replans around unavailable items, and reports catalog gaps when it can't fulfill the goal.

The UI places a raw-catalog keyword match beside the agent-composed cart. Same goal, same products, dramatically different outcomes. The gap between them is the catalog readiness problem.

How we built it

Two separate modules, one clean interface. The enrichment module (GPT-5.6 Terra) converts raw Shopify CSV records into a structured index with material, use-case, style, seasonal, functional, and substitution attributes, each with a confidence score. The cart agent (GPT-5.6 Sol) drives a ReAct loop with five tools in function-calling format. The agent never touches the raw CSV.

Codex handled the full lifecycle. A single planning prompt generated the PRD, AGENTS.md, BDD scenarios, task backlog, and test stubs. Then each task was fed to Codex individually with explicit acceptance criteria. Ten commits show the iterative build.

Challenges we ran into

Token cost at $0.50 per cart. Using Sol for all 15 agent steps (including mechanical lookups like inventory checks) made per-query cost too high for production. I documented four optimizations in a Production Optimization Roadmap that reduce cost to $0.05: model tiering, vector search, semantic caching, and context window management.

Agent stopping early. GPT-5.6 Sol would sometimes assemble 2 of 3 requested items and declare the cart complete. I had to add explicit instructions in the agent prompt: "Complete ALL items in a multi-item request. Do not stop after 1-2 items." This failure mode was predicted in the PRD before building.

Substitution budget drift. When the agent substituted a more expensive item for an out-of-stock product, it would not always recheck the running budget total. I added a hard rule: after every substitution, call get_cart_summary and verify budget compliance before proceeding.

Enrichment hallucination. GPT-5.6 Terra would fabricate material percentages ("60% organic cotton, 40% polyester") for products where the description only said "cotton shirt." I added confidence scoring (1.0 for observed attributes, 0.5-0.9 for inferences) and anti-hallucination constraints in the enrichment prompt.

Accomplishments that we're proud of

The side-by-side comparison. No other approach to demonstrating catalog readiness is this immediate. A judge spends 5 seconds looking at the two panels and understands the thesis without reading a word of documentation.

Gap reporting. When the agent can't fulfill a request, it doesn't hallucinate a match. It reports exactly what's missing, shows the closest available option with its image and price, and recommends specific catalog additions. This is how agents should fail: truthfully, with actionable feedback.

The modular architecture. The EnrichmentProvider interface means the enrichment module can be swapped for an external service without touching the agent code. This isn't a demo shortcut. It's a deliberate design decision for post-hackathon extensibility.

Forty-eight hours from empty repo to deployed product with a production optimization roadmap and strategic context document. Codex made this possible by handling implementation while I focused on architecture, product decisions, and framing.

What we learned

Predicting failure modes works. The PRD listed 4 specific predictions about how GPT-5.6 would fail. Three of them happened exactly as predicted. Writing testable failure modes before building made the fixes faster because I was looking for them.

Task decomposition beats big prompts. Feeding Codex one task at a time with explicit acceptance criteria produced significantly better code than asking for the entire application in one prompt. The AGENTS.md file was critical: Codex read it at the start of every task and maintained consistency across the codebase.

Cost transparency is a feature. Showing token usage and estimated cost per query in the UI turned a weakness (high per-query cost) into a strength (production cost awareness). No other hackathon entry surfaces this.

The enrichment is the product, not the agent. The agent is impressive, but what makes it work is the underlying structured data. Swap in a different agent framework, and it still works. Remove the enrichment and any agent fails. The data layer is the durable value.

What's next for Forage

Multi-category catalogs with vector retrieval. Real-time inventory via MCP. A pluggable enrichment interface connected to RIA, a standalone catalog readiness tool built separately. User-facing tradeoff negotiation when constraints conflict. And the longer-term direction: a merchant-facing readiness layer that tests how shopping agents will behave against real catalog data before customers encounter the gaps.