Wingman

Inspiration

Shopping online often means opening dozens of tabs, comparing prices, checking delivery times, and trying to remember which products satisfy every requirement. AI assistants can recommend products, but recommendations alone are not enough when real purchases are involved.

We created Wingman to explore a safer approach to agentic commerce: an AI shopping companion that understands what the user wants, converts it into clear rules, finds eligible products, and keeps the user in control of the final selection.

## What it does

A user describes a purchase in simple language, for example:

Find Bluetooth headphones under EUR 500 with delivery within two days.

Wingman converts the request into a validated JSON purchase contract containing the category, budget, currency, compatibility requirements, delivery limits, rating requirements, and authorization preferences.

The completed contract is saved to the authenticated user's account. Wingman evaluates products from a deterministic catalog of 15,000 products across 15 categories and returns up to 12 eligible options together with a recommended product.

The user can review the results and select any eligible product. Only that selected product is saved as a purchase. Users can then view their contract history and all their purchases.

## How we built it

We built the mobile client with Flutter and created the backend using Python and FastAPI.

OpenAI structured outputs transform natural-language requests into predictable JSON. Pydantic validates every generated contract, while deterministic Python rules verify product eligibility. This separation means the AI can interpret intent but cannot bypass the user's budget or constraints.

A product is eligible only when every contract condition passes:

$$ \operatorname{eligible}(p,c)=\bigwedge_{i=1}^{n}\operatorname{constraint}_i(p,c) $$

The backend uses SQLAlchemy and PostgreSQL to store authenticated users, generated contracts, and selected purchases. JWT tokens ensure every contract and purchase belongs to the correct user. Docker Compose runs the API, database, migrations, and development tools locally.

We also created automated API, contract-generation, catalog, and PostgreSQL integration tests, together with detailed documentation for frontend developers and coding agents.

## Challenges we ran into

One major challenge was turning ambiguous language into reliable purchasing rules. Users may forget to include a budget, currency, or product category. Instead of inventing important information, Wingman returns the missing fields and a clarification question.

We also encountered frontend and backend schema mismatches that caused 422 Unprocessable Entity responses. We improved validation errors, added request IDs, simplified user registration to a single name field, and created a complete API integration guide.

Another challenge was deciding what should be persisted. We designed a clear workflow: completed generated contracts are saved to the user's contract history, but product recommendations do not become purchases automatically. A purchase is created only after the user explicitly selects a product.

## Accomplishments that we're proud of

We are proud that Wingman is more than another shopping chatbot. It creates a structured and testable workflow from user intent to an explicit purchase selection.

Our accomplishments include:

Natural-language to validated JSON contract generation
User-specific contract and purchase history
A deterministic catalog containing 15,000 products
Constraint-based product filtering and ranking
Explicit user selection before purchase creation
Secure JWT authentication and user data isolation
Safe and actionable backend error reporting
Automated API and PostgreSQL integration tests
A documented API that another developer or coding agent can integrate

## What we learned

We learned that structured AI output is useful, but valid JSON is not automatically a safe business decision. AI interpretation must be followed by strict schemas and deterministic validation.

We also learned that trust is one of the most important parts of agentic commerce. Users should be able to see what the AI understood, which requirements were applied, and exactly when information becomes a saved purchase.

Finally, we learned that good API documentation and useful error messages are essential when frontend and backend development happen in parallel.

## What's next for Wingman

Next, we want to complete the Flutter integration and make the entire workflow feel seamless—from writing a request to viewing saved purchases.

Future plans include live retailer integrations, current price and inventory checks, richer product comparisons, secure test payments, delivery tracking, notifications, cancellations, returns, refunds, and a user-facing audit receipt explaining every important decision.

Our long-term vision is for Wingman to become a trusted layer between users, AI agents, and online stores—providing the convenience of delegated shopping without sacrificing transparency or control.