Shippy

The right route, with risk in mind

Comment

Project Story: Conversational Shipment Data Extraction (Gemini-powered)

  • Inspiration

    • We were inspired by how shipment details are usually shared in messy natural language, while real systems need structured, predictable fields.
    • People naturally say things like: “I’m shipping from London to Sheffield on Saturday 7th Feb 2026.”
    • The goal became: keep the experience conversational, but still output clean, canonical JSON.

  • What we learned

    • LLMs work best when constrained
    • A model can extract fields well, but it’s much more reliable when forced into a schematic and checked by backend rules.
    • Normalisation is essential
    • Human-friendly values must be converted into consistent machine formats, especially dates.
    • Example conversion:
      $$\text{"Saturday 7th Feb 2026"} \rightarrow 2026\text{-}02\text{-}07$$
    • Guided chat UX beats “free chat”
    • The UI should identify missing fields, ask follow-ups, and show users what was extracted.

  • How we built the project

    • Front End (Chat UI)
    • Message input + conversation history.
    • Guided prompts to collect missing details.
    • Output display showing extracted fields and a final JSON preview.
    • Two informational graphs visualising efficiency vs risk.
    • Backend (Server)
    • /chat endpoint: receives message + state, calls Gemini, returns assistant reply + current structured JSON.
    • /finalize endpoint: validates + normalises, then returns canonical JSON.
    • AI Layer (Gemini)
    • Extracts structured fields from conversation text.
    • Uses a schema-driven prompt and follow-up questions when fields are missing.
    • Normalisation + validation
    • Deterministic backend logic cleans and validates output.
    • You can think of date standardisation as a function:
      $$f(\text{human_date}) = \text{ISO_date}$$

  • Challenges we faced

    • Missing or ambiguous user input
    • Users often leave out origin, destination, or a clear date.
    • We solved this by tracking missing fields and asking targeted follow-up questions.
    • Inconsistent AI output
    • Sometimes the model can return extra text or slightly wrong formats.
    • We handled this with schema constraints, strict validation, and re-asking when needed.
    • Balancing friendliness with correctness
    • Too strict feels robotic, but too loose creates unreliable data.
    • We kept the chat natural, but made the backend the “source of truth.”
    • Keeping the end-to-end flow stable
    • The pipeline had to remain consistent:
      $$\text{User} \rightarrow \text{Gemini} \rightarrow \text{Normalise} \rightarrow \text{Validate} \rightarrow \text{JSON}$$
{
  "ship_from_city": "London",
  "ship_to_city": "Sheffield",
  "ship_date": "2026-02-07"
}
  • What next!
    • Fixing little errors! We had a lot of merge conflicts and issues with GitHub during the final couple hours which negatively affected the final usability of the project unfortunately, so going back to when it was working optimally and going onwards with Shippy from there.
    • Consider more variables than the weather, for example the final few miles by lorry - traffic may affect the overall efficiency and risk score.
Share this project:

Updates