SurplusLink AI: Reviving Surplus Bakery Inventory with Open-Source LLMs on a B2B Platform

In the food industry, vast quantities of packaged bakery products lose value every day as they approach their expiration dates; meanwhile, small retailers struggle to find wholesale sources at reasonable prices. SurplusLink AI aims to build a bridge using open-source LLMs and a rules engine, turning wholesalers' surplus inventory into purchasing opportunities for retailers. Based on the project's submission to the Hacktoberfest challenge, this article breaks down its product logic, technical architecture, and commercialization concept.

Starting from the Pain Point: The Mismatch Between Surplus Inventory and Purchasing Demand

Food manufacturers, bakeries, and wholesalers regularly face a practical problem: inventory must be sold before it loses commercial value. Small retailers, while in need of low-cost supply, lack direct channels to reach suitable wholesalers. SurplusLink AI's entry point is precisely this gap in supply-demand matching.

The project is positioned as a prototype B2B trading platform for surplus packaged bakery goods targeting the Pakistani market, initially limited to sealed packaged items such as biscuits, rusks, crackers, and cookies. The author explicitly states that a real deployment would also require supporting product validation, shelf-life control, and food safety compliance measures—indicating the team has a clear-eyed understanding of the business boundaries.

Core Workflow: AI Handles Only Language Understanding, Rules Drive Business Decisions

The most notable design choice in SurplusLink is its strict separation of responsibilities between AI and business logic. Wholesalers enter product details, quantities, asking prices, locations, and shelf-life information; retailers describe their needs in natural language—for example, "I need 150 packs of biscuits in the Lahore area, budget under 20,000 rupees, with at least 30 days of remaining shelf life."

The open-source language model is responsible for extracting fields such as category, quantity, unit, budget ceiling, city, and minimum remaining shelf life from this unstructured text. The extracted results are first validated by Pydantic; missing fields are not guessed but are confirmed by the user before being saved. The backend then uses deterministic business rules to perform inventory matching—across dimensions including category, unit, quantity, city, shelf life, and price.

The value of this division of labor lies in the fact that AI solves the usability problem of inconsistent descriptions between buyers and sellers, while decisions involving money—such as pricing and inventory allocation—remain with a testable, explainable rules engine, avoiding the handover of critical judgments to a black-box model.

Pydantic is a widely used data validation library in the Python ecosystem. Its core mechanism is that developers define the structure and constraints of data models using type annotations, and the library automatically validates at runtime whether incoming data satisfies these constraints, raising clear error messages when they do not. In SurplusLink's scenario, the category, quantity, budget, and other fields extracted by the language model from a retailer's natural language are essentially untrusted raw output—they may be missing, have type errors, or fall outside reasonable ranges. By defining a requirements model with Pydantic, the system can enforce the type and value range of each field, intercepting validation failures or incomplete extraction results and returning them to the user for review, rather than allowing dirty data to flow into the subsequent matching stage. This practice of "running model output through structural validation first" is a common approach for controlling output reliability in LLM application engineering.

Technical Implementation: Centered on a Trading System, Not a Chatbot

The author's key architectural choice is to "build SurplusLink as a marketplace rather than an AI chat application." The backend data model covers organizations, enterprise members, surplus inventory, buyer demands, quotes, deals, payments, and transaction events, using PostgreSQL for relational management, with SQLAlchemy and Alembic handling model definitions and versioned migrations.

Inventory consistency is the lifeline of a trading system. The project defines an explicit rule: available quantity = total quantity - reserved quantity - sold quantity, thereby distinguishing inventory committed to completed orders from inventory already picked up. When a quote is accepted, the backend validates inventory availability and reserves stock within a transaction, preventing the same batch from being allocated to multiple buyers—an essential problem to solve in a marketplace that may simultaneously attract multiple buyers.

The AI inference layer calls hosted open-source Llama models through GroqCloud, eliminating the hassle of downloading model weights onto a development machine, while encapsulating model calls behind a provider interface for easy replacement with other compatible models later. The matching engine supports bidirectional discovery: buyers can find goods, and sellers can find demand.

Alembic is the official database migration tool that accompanies SQLAlchemy, used to record every structural change to the data model (such as adding tables, modifying fields, or adding indexes) as versionable, replayable migration scripts. For transactional systems, database schemas evolve continuously as the business evolves. If databases are modified manually, development, testing, and production environments are prone to structural inconsistencies, leading to hard-to-diagnose failures. By maintaining a migration version chain, Alembic enables teams to upgrade or roll back database schemas in order and keeps model definitions in the code repository in sync with the live database schema. SurplusLink's use of Alembic alongside SQLAlchemy model definitions means the structural evolution of core tables such as orders, inventory, and quotes is brought under engineering management—essential infrastructure for a platform that needs to maintain real transaction data over the long term.

A transaction in "reserving inventory within a transaction" refers to a database transaction: a set of operations that either all commit successfully or all roll back, with no intermediate state. In the inventory reservation scenario, the system needs to atomically increment the reserved quantity for that batch and write the order record at the same time it confirms a quote is accepted. If two buyers accept quotes for the same batch almost simultaneously, the absence of transaction protection could lead to overselling or duplicate allocation. With database transactions and row-level locks, a later request will see the reserved quantity already taken and be rejected during validation. Combined with the rule "available quantity = total quantity - reserved quantity - sold quantity," this mechanism forms the core defense against inventory inconsistency in a trading system—and is a key engineering requirement that distinguishes it from an ordinary chat application.

Business Model: Transaction Commission Rather Than Subscription

SurplusLink envisions generating revenue through transaction fees rather than monthly fees: a 2% buyer service fee and a 2% seller commission. Taking a wholesale transaction of 150 packs of biscuits at 120 rupees each as an example, the transaction subtotal is 18,000 rupees; buyer and seller each pay 360 rupees in fees, the buyer pays 18,360 rupees in total, the seller receives 17,640 rupees, and the platform earns 720 rupees in gross revenue.

The author specifically states that this is only an illustrative business scenario, not real revenue, and that the prototype does not handle real money transactions. This restrained framing is commendable, but it also exposes a question that remains to be validated: whether a 2% two-sided fee rate is attractive enough in a surplus-goods business with low unit prices and thin margins still requires real-market testing.

A take rate is a common monetization method for two-sided marketplace platforms, where the platform charges a percentage of the transaction value to the buyer, the seller, or both. Revenue scales naturally with transaction volume without relying on users paying directly. Compared with subscriptions, the commission model is friendlier to merchants during the cold-start phase—no transaction, no fee—lowering the barrier for small retailers to try it out. However, its viability depends heavily on two conditions: first, that the platform genuinely facilitates transactions that would otherwise not happen; second, that the commission rate is low enough relative to the gross margin of a single transaction that it does not erode the gains buyers and sellers obtain from low surplus-goods prices. In a surplus food business with low unit prices and thin margins, whether a 2% two-sided fee rate is sustainable depends on whether the matching efficiency gains the platform delivers can cover this cost—this is the assumption that most needs validation in the real market.

Flexibility and Boundaries of Open-Weight Models

The project's rationale for choosing open-weight models is pragmatic: for a small team, the value lies not in training larger models but in applying existing models to specific problems and using solid software engineering to contain their output. Hosted inference lowers the infrastructure barrier, model integration can be isolated and swapped, and business logic remains controllable.

The author also candidly points out the boundaries: using open-weight models does not automatically mean the application is private, offline, or zero-cost. Hosted inference still involves provider costs and data-processing considerations that need to be evaluated before onboarding real merchants. In the future, the model could be evaluated or fine-tuned for local wholesale inventory descriptions, including Urdu-English mixed terminology and product abbreviations.

During development, the author used OpenAI Codex to assist with implementing FastAPI endpoints, database models, Alembic migrations, AI inference integration, and frontend integration—but first defined the marketplace architecture, business workflows, and technical requirements independently, then had AI implement and refine components, thereby focusing effort on understanding backend architecture, inventory management, and transaction processing.

Editorial View

The lesson of SurplusLink AI is not that "AI was used to build a marketplace," but rather how it handles AI's boundaries: letting the model process ambiguous natural language while letting rules handle explicit business logic. For developers looking to use LLMs to transform traditional industry workflows, this prototype offers a reusable approach—first figure out which decisions can be delegated to the model and which must remain with auditable code. The project is still at the prototype stage; food safety compliance, two-sided cold start, and fee-rate viability are all thresholds it must cross to go from a hackathon project to a real business.

One-line Summary

SurplusLink AI uses open-source LLMs to parse demand and a rules engine to match supply, building a B2B trading prototype for surplus bakery goods.

Paragraph Summary

SurplusLink AI is a prototype B2B trading platform for surplus packaged bakery goods targeting the Pakistani market, aiming to resolve the supply-demand mismatch between depreciating near-expiry inventory at wholesalers and small retailers' lack of low-cost supply sources. Its core design strictly separates AI from business logic: the open-source Llama model is responsible only for extracting structured fields—category, quantity, budget, city, and minimum shelf life—from retailers' natural-language requests; after Pydantic validation, a deterministic rules engine performs inventory matching, avoiding model involvement in critical decisions such as pricing and inventory allocation. The tech stack is built on PostgreSQL, SQLAlchemy, Alembic, and FastAPI, using the rule "available quantity = total quantity - reserved quantity - sold quantity" and transactional reservation to prevent duplicate allocation. The business model adopts a 2% transaction commission from both buyers and sellers. The project is still at the prototype stage, with food safety compliance, two-sided cold start, and fee-rate viability yet to be validated.