• 

  landing page to try out example

• 

  about page

AgentShelf - Devpost Story

Written in first person for a solo submission.

Inspiration

Shopping is quietly moving inside AI assistants. People now ask ChatGPT "what's the best waterproof hiking boot for wide feet under $150?" and get a shortlist of brands, and if you're a merchant who sells exactly that boot, you may simply not be on the list. There's no click, no abandoned cart, no analytics event. Just a sale that went somewhere else, and you never find out.

What struck me is that after the first wave of in-chat checkout stalled, the industry converged on a different model, discover in AI, buy on your own site. That made discovery the thing that matters: getting the agent to recommend you, and to describe you correctly. Yet merchants have no visibility into any of it. They're optimizing for a shelf they can't see. AgentShelf is the instrument panel for that shelf.

What it does

AgentShelf runs a merchant's products through a shopping agent and turns the result into a clear, four-step loop : Look → Learn → Fix → Prove:

• Look : load a sample store (Trailforge outdoor footwear or Hearth & Handled homeware) and run a baseline simulation across that store's shopper queries.
• Learn : see where you show up, where you vanish, and how you're described, scored as a visibility number.
• Fix : get a truthful listing improvement. The fix preserves the product's title, price, and supported claims; it only makes existing proof explicit. It never invents features.
• Prove: apply the fix, re-run the same queries, and compare the visibility and estimated revenue lift side by side.

It ships with two modes: a deterministic local demo that needs no credentials and runs the same every time, and an opt-in live OpenAI mode powered by GPT-5.6 for real agent reasoning. There's also an honest, preview-only Shopify connection page that shows how a real integration would look without making any live API calls.

How I built it

The stack is a FastAPI backend managed with uv, a React 19 + Vite frontend managed with bun, and SQLite persisting runs, fixes, and results. Live mode uses the OpenAI API (GPT-5.6) with structured outputs for the agent simulation, diagnosis, and the listing rewrite; local mode uses deterministic providers behind the same interface.

The architecture centers on a provider abstraction: the local and live engines implement one contract, so the whole Look → Learn → Fix → Prove pipeline runs identically whether or not a key is present. That kept the demo reliable and the live path a drop-in.

Codex did the heavy lifting on the build, scaffolding the FastAPI feature modules and the bun/React/TypeScript client, wiring the SQLite layer and the run pipeline, and generating UI. That freed me to concentrate on the decisions that actually define the product: how to frame the agent's ranking decision, the prompt and JSON-schema design, the hard "truthful fix" constraint, and the visibility and revenue scoring. Both the API (pytest) and the client (test, lint, production build) are covered by checks.

Challenges I ran into

• Keeping the demo bulletproof. Live model calls are great but risky to lean on during a timed demo. Building a deterministic local mode that mirrors the live pipeline, same contract, reproducible output, was the fix, and it turned into one of the project's best decisions.
• Enforcing truthfulness. The easy version of "optimize my listing" is to make the AI write flattering copy. I didn't want a tool that fabricates claims. Designing the fix so it only surfaces existing, supported proof, never inventing features, prices, or warranties, took real care in the prompt and logic.
• Being honest about scope. The simulation models an agent's decision over a candidate set; it does not scrape or reproduce a third party's live production rankings. I built the product, and wrote the copy, to say that plainly rather than overclaim.
• Structured-output reliability. Getting consistent, parseable JSON out of the model for the simulate/diagnose/fix steps meant schema discipline and graceful handling when a response didn't conform.

Accomplishments that I'm proud of

• A closed loop that proves lift, not just a report of problems, you watch a listing go from invisible to recommended, with a before/after number.
• A deterministic local mode that makes the whole thing demoable anywhere, with no key and no flakiness.
• Two distinct verticals (footwear and homeware) that show the engine generalizes rather than being tuned to one catalog.
• The truthfulness discipline, an optimization tool that improves listings without lying about the product.
• Integrity over hype, an honest, preview-only Shopify page and a clear scope statement, instead of faking an integration.
• A clean, tested codebase built inside a hackathon window.

What I learned

• In agentic commerce, value has shifted from checkout plumbing to discovery, being recommended and described correctly is the new battleground.
• How to design AI features around a hard non-negotiable constraint (never fabricate) using prompts plus structured outputs.
• The provider-abstraction pattern, one contract, swappable deterministic and live implementations, is a clean way to keep a demo reliable while shipping a real AI path.
• Where Codex accelerates most (scaffolding, wiring, UI) versus where human judgment has to own the outcome (framing, prompts, constraints, scoring).

What's next for AgentShelf

• Real Shopify integration, turn the preview page into live OAuth and catalog import.
• Multi-surface coverage, the same engine across ChatGPT, Gemini, and Perplexity via additional adapters, so a merchant can see "recommended on one, invisible on another."
• Continuous monitoring, drift alerts when visibility drops or an agent starts misdescribing a product.
• Multi-protocol feed syndication, generate compliant feeds for competing agentic-commerce standards from one source of truth.
• Live competitor discovery, replace bundled candidate sets with real, current competitors pulled at run time.

Built With

• codex
• fastapi
• openai
• vite