AgentShelf

Mission control for how AI shopping agents see, rank, and describe merchant products. AgentShelf loads a bundled sample store — outdoor footwear (Trailforge) or homeware (Hearth & Handled) — simulates shopping-agent recommendations, proposes a truthful listing improvement, then measures the resulting visibility and revenue lift.

AgentShelf was designed and built primarily with OpenAI Codex, working under human product direction. Codex helped shape the architecture, implement the FastAPI and React applications, develop the visual system, write tests, debug integrations, and prepare the documentation. The product vision, requirements, creative direction, review, and final decisions remained human-led.

This project is an example of close human-AI collaboration: Codex handled much of the hands-on design and engineering work while the creator guided the product, evaluated each iteration, and determined what shipped.

1. Choose a sample store (Trailforge footwear or Hearth & Handled homeware) and deterministic local mode or opt-in live OpenAI mode.
2. Run a baseline simulation across that store's shopping queries.
3. Review a truthful fix that preserves the product's title, price, and supported claims — it only makes existing proof explicit.
4. Apply the fix, re-run the simulation, and compare visibility and revenue lift.
5. Continue to the other sample, return to the picker, or preview the Shopify connection.

The client is a lightweight single-page app with three routes:

• / — pick an example and run the Look → Learn → Fix → Prove workflow.
• /about — the product story: why agent-readable proof matters and how the feedback loop works.
• /connect-shopify — an honest, preview-only walkthrough of how a real Shopify connection would look. It makes no Shopify API calls and connects no store; real OAuth/import is a follow-on project.

flowchart LR
  Browser[React + Vite client] --> API[FastAPI feature modules]
  API --> Local[Deterministic local providers]
  API --> Live[OpenAI providers]
  API --> DB[(SQLite runs, fixes, results)]
  Key[OPENAI_API_KEY\nserver only] --> Live

The browser connects to http://localhost:8000 by default. The API permits the Vite development origin at http://localhost:5173.

flowchart LR
  Seed[Load sample store] --> Baseline[Run baseline]
  Baseline --> Fix[Review truthful fix]
  Fix --> Rerun[Apply and re-run]
  Rerun --> Lift[Measure visibility and revenue lift]

Start the API from the repository root:

uv --directory server run uvicorn app.main:app --reload

In another terminal, install and start the client:

cd client && bun install && bun run dev

Open the client, keep Reliable local demo selected, and load the sample store. To point the client at a different API address, set VITE_API_BASE_URL before starting it.

Reliable local demo is deterministic and needs no credentials. It is the recommended default for exploring the workflow.

Live OpenAI test is opt-in and uses server-side config only — never put a key in client-side configuration. Copy the template and fill it in:

cp server/.env.example server/.env

Then set two values in server/.env:

• OPENAI_API_KEY — your key from the OpenAI dashboard.
• OPENAI_MODEL — a model your account can use that supports structured outputs, for example gpt-4.1-mini. The built-in default is a placeholder and must be replaced, or live calls will fail.

Restart Uvicorn after editing .env — configuration is read at startup. Process environment variables take precedence over dotenv files, and .env files are gitignored (only *.env.example is committed).

Run the API test suite:

cd server && uv run pytest -q

Run the client test, lint, and production-build checks:

cd client && bun run test && bun run lint && bun run build

AgentShelf's local provider simulates a candidate set for demonstration. It is not a production-ranking scrape or a claim that it reproduces a third-party agent's real rankings.