About cookedUserStory

Inspiration

Purchasing decisions often begin with vague requests such as:

“I need a laptop for engineering work that is affordable, portable, and powerful enough for CAD.”

The problem is that most shopping tools respond with a long list of products, sponsored rankings, or generic recommendations. They rarely show which requirements were actually satisfied, which claims came from reliable sources, or where important information is still missing.

I wanted to build a system that treats a purchasing request more like an engineering decision: define the requirements, gather evidence, identify uncertainties, compare alternatives consistently, and explain the final recommendation.

That idea became cookedUserStory—a tool that converts an informal purchasing need into a structured, evidence-aware decision brief.

What it does

cookedUserStory guides the user through four stages:

1. Describe - The user enters a purchasing need in natural language.
2. Confirm - The system extracts the category, mandatory requirements, preferences, assumptions, and scoring weights for the user to review.
3. Compare - Three candidate products are evaluated using structured product specifications and supporting evidence.
4. Recommend - The system provides a deterministic recommendation, explains the trade-offs, highlights missing or conflicting information, and links the result back to its sources.

The prototype supports three product categories:

• laptops;
• air purifiers;
• laboratory ovens.

Every product is assigned one of three qualification states:

• qualified;
• disqualified;
• needs_confirmation.

A product is disqualified when it fails a mandatory requirement. If a mandatory value is unknown, the product cannot become the primary recommendation until that information is confirmed.

Preferred criteria are scored from 0 to 10 and combined using user-editable weights:

[ S = \sum_{i=1}^{n} s_i w_i ]

where:

• (s_i) is the product’s score for criterion (i);
• (w_i) is the normalized weight of that criterion;
• (\sum w_i = 1).

The recommendation engine is deterministic and local. AI providers can help interpret requirements, retrieve evidence, and review results, but they do not secretly decide which product wins.

How we built it

The project was built as a single Next.js and TypeScript application using the App Router.

The architecture separates the workflow into several clear responsibilities:

• AI& interprets the user’s purchasing request and extracts structured requirements.
• Oxylabs retrieves public product evidence, including manufacturer pages, retailer listings, specifications, prices, and regional availability.
• Doubleword converts retrieved page content into validated structured claims.
• Local TypeScript scoring evaluates mandatory requirements and calculates the authoritative ranking.
• Daytona is used to execute the same scoring payload in an isolated sandbox and compare its output with the local result.
• Nosana reviews evidence quality and identifies claims that still require confirmation.

Oxylabs is intended to become the main evidence-acquisition layer rather than a single demonstration request. For each product, the system can retrieve several sources, such as:

• an official manufacturer page;
• one or more Singapore retailer pages;
• a manual or technical datasheet;
• an independent supporting source.

Each claim carries provenance information, including its source URL, retrieval time, evidence excerpt, origin, confidence, and claim status.

The application distinguishes between:

• live provider data;
• validated cached data;
• prepared fixtures;
• synthetic fixtures;
• calculated values;
• missing information;
• conflicting claims.

Provider failures are isolated. A failed external call does not crash the entire workflow, and the interface reports the actual provider mode instead of presenting fallback data as live.

The prototype currently has validated live execution for Doubleword and Oxylabs. AI&, Daytona, and Nosana are integrated with safe fallbacks while their live execution paths continue to be completed.

Challenges we ran into

Integrating providers with different response formats

Each provider had different request structures, response envelopes, timeout behaviour, and error conditions.

For example, AI& returned a successful HTTP response, but the returned content did not match the expected Zod schema. Solving this required strict JSON Schema output, fenced-JSON handling, response-shape parsing, and sanitized validation diagnostics.

Keeping AI separate from the final decision

It would have been easier to ask a language model to choose the “best” product directly. However, that would make the result difficult to reproduce and audit.

Instead, the recommendation is calculated using a pure deterministic scoring function. AI services assist with interpretation and evidence processing, but the same inputs always produce the same ranking.

Using external data without overstating reliability

A webpage can be live while still containing incomplete, outdated, regional, or conflicting information.

We therefore had to distinguish retrieval success from claim quality. A successful HTTP request is not automatically reliable evidence, and a missing specification must remain missing rather than being inferred or invented.

Safely processing large pages

Public product pages can be much larger than the small evidence excerpts needed by the application.

The Oxylabs retrieval path was designed to read only a bounded response size, cancel processing after the limit, retain useful provenance, and visibly report when the retrieved content was truncated.

Running scoring inside Daytona

The Daytona integration successfully reached sandbox creation, but code execution failed during the live probe. The application therefore retained local scoring as authoritative and reported Daytona as a fallback rather than claiming an unvalidated live result.

Deploying a real Nosana workload

Nosana requires a validated deployed workload and review endpoint. Rather than fabricating a successful result, the application currently reports a cache miss and uses an explicitly labelled synthetic fallback.

Time management

The largest project-management challenge was trying to build the application, validate five providers, protect credentials, test the system, and prepare the demonstration within a hackathon timeline.

Although the functional prototype reached a strong state, I missed the final submission deadline. That was disappointing, but it also changed the goal: instead of abandoning a rushed hackathon build, I decided to continue developing it into a complete and credible portfolio project.

Accomplishments that we're proud of

• Built a working end-to-end purchasing decision workflow.
• Supported three distinct product categories using shared configuration rather than separate applications.
• Created deterministic mandatory requirement handling and weighted scoring.
• Added editable user weights with immediate recalculation.
• Preserved evidence provenance for displayed product claims.
• Prevented unknown mandatory values from silently winning.
• Designed provider failures to degrade safely without breaking the application.
• Validated live Doubleword claim extraction.
• Validated live Oxylabs retrieval with bounded response processing.
• Integrated all five sponsor providers without misrepresenting fallback results as live.
• Completed linting, type checking, production build verification, and 108 automated tests.
• Added secret scanning and avoided printing credentials or upstream provider bodies.
• Preserved local scoring as authoritative even when external execution is available.

The accomplishment I am most proud of is not simply connecting several APIs. It is building a system where every provider has a defined responsibility, every recommendation can be traced to evidence, and uncertainty remains visible.

What we learned

I learned that building an AI application is often less about calling a model and more about controlling the boundaries around it.

Structured output still needs validation. Live retrieval still needs provenance. Provider success still needs semantic verification. AI-generated claims still need evidence. Fallback behaviour still needs honest labelling.

I also learned the importance of designing external integrations as replaceable adapters. The core product remains functional even when an individual provider is slow, unavailable, or returns unexpected data.

The project reinforced several engineering principles:

• deterministic logic should control decisions that must be reproducible;
• external services should fail independently;
• missing information should remain visible;
• evidence quality matters more than the number of retrieved pages;
• a successful API response is not the same as a valid application result;
• good fallback behaviour is part of the product, not an afterthought;
• claims should never be stronger than the evidence supporting them.

Finally, missing the submission deadline taught me that technical scope and submission strategy must be managed separately. A project can be technically strong and still fail the event objective if the final delivery process is not protected.

What's next for cookedUserStory

The next stage is to complete and strengthen all five provider integrations.

Expand Oxylabs evidence gathering

Oxylabs will be used extensively to retrieve multiple sources for every product, including:

• manufacturer specifications;
• Singapore retailer pricing and availability;
• regional model variants;
• manuals and datasheets;
• warranty information;
• replacement-part or consumable costs.

The system will also compare the same claim across different sources and flag disagreements instead of silently selecting one value.

Complete live AI& extraction

The AI& adapter will be updated to correctly interpret its returned content structure and validate live requirement extraction against the application schema.

Complete Daytona execution

The Daytona workflow will be debugged across sandbox creation, code transfer, execution, result collection, and cleanup. Its result will be compared against local scoring, with any mismatch shown to the user.

Deploy Nosana evidence review

A real Nosana workload will be deployed to evaluate:

• missing mandatory evidence;
• conflicting claims;
• weak source coverage;
• outdated retrievals;
• claims that require human confirmation.

Improve evidence reconciliation

Future versions will better handle:

• unit normalization;
• regional product variants;
• duplicate claims;
• conflicting retailer information;
• evidence freshness;
• manufacturer-versus-retailer authority;
• confidence scoring.

Expand beyond prepared products

The current prototype begins with prepared candidate products. A later version may add controlled live candidate discovery while retaining the same evidence, qualification, and deterministic scoring rules.

Build a category plugin system

Additional categories will be introduced through reusable category definitions covering:

• relevant specifications;
• mandatory operators;
• scoring direction;
• units;
• default weights;
• evidence expectations.

The long-term goal is for cookedUserStory to become a transparent decision-support tool that helps users understand not only what to buy, but also why the recommendation is justified, what remains uncertain, and which evidence supports the decision.

Built With

• codex
• nosana
• oxylab