🚢 DemurrageDesk: Stop Hallucinating the Math - Building a Local RAG Assistant for Port Logistics

Rakshit Sharma — Sun, 04 Oct 2026 16:51:36 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

DemurrageDesk is a local RAG assistant for working with shipping line and terminal documents.

I built it around a problem I could easily imagine a friend working in logistics dealing with: finding demurrage and detention rules buried inside long tariff PDFs.

These documents can contain rules such as:

7 free days, days 8–14 at one rate, and day 15 onward at a higher rate.

Finding the right rule is only half the problem. The more dangerous part is applying the wrong container size, mixing up import and export terms, missing a tier boundary, or simply letting an LLM do the arithmetic.

DemurrageDesk is designed around the assumption that the model can be wrong.

You ask a question in plain English, the system retrieves the relevant document sections, and the answer includes the source file, page number, and the exact sentence used as evidence.

Then, when a charge needs to be estimated, the model extracts the relevant rules into structured data — but Python performs the actual calculation.

The goal isn't to make the LLM magically reliable.

The goal is to build a system that checks it.

Demo

🎥 Watch the DemurrageDesk demo

The video shows:

Asking a question about a shipping tariff
Retrieving the relevant source and page
Verifying the citation
Extracting the demurrage rate tiers
Calculating the final charge deterministically with Python

Code

rakshitsharma0402 / DemurrageDesk

🚢 DemurrageDesk: Port Terms Assistant

DemurrageDesk is a professional-grade, local RAG (Retrieval-Augmented Generation) assistant designed to parse complex port and shipping terminal documents. It allows users to query free-time rules, demurrage rates, and procedures, providing strictly cited answers and deterministic charge calculations.

Everything runs locally. Your documents never leave your machine.

✨ Key Features

Strict Citations: The assistant provides direct quotes from documents. A verification layer ensures that the AI didn't hallucinate the quote.
Deterministic Calculator: Instead of letting the LLM do math (which is error-prone), the AI extracts the rules into a structured format, and a pure-Python engine calculates the final charges.
Provider Filtering: Organize documents by shipping line or terminal; filter queries using the sidebar to avoid cross-provider confusion.
Privacy First: Built with Ollama, ChromaDB, and Streamlit for a 100% local execution environment.

🛠️ Tech Stack

LLM: Gemma (via Ollama)
Embeddings: nomic-embed-text…

View on GitHub

The repository contains the complete implementation along with the calculator tests and setup instructions.

How I Built It

I wanted the entire pipeline to run locally because shipping tariffs, contracts, and terminal documents can contain sensitive commercial information.

The stack is:

Gemma 3 through Ollama for local generation
nomic-embed-text through Ollama for embeddings
ChromaDB for local vector search
PyMuPDF for PDF text extraction
Pydantic for structured model output
Streamlit for the interface
Plain Python for the actual demurrage calculation

The application stores the provider/terminal as metadata during ingestion, which allows the UI to filter retrieval by shipping line or terminal rather than mixing documents from different providers.

The important part: evidence before answers

The RAG pipeline doesn't simply ask the model for an answer.

The response schema requires citations containing a source, page number, and a complete sentence copied from the retrieved text. The application then normalizes the citation and checks whether that quoted sentence actually exists in the retrieved document chunk. Only verified citations count toward found=True.

That means the model cannot simply invent a convincing-looking citation and have the application accept it.

The system prompt also explicitly tells the model to respect container size, import/export direction, and the applicable shipping line or terminal — and not to perform the charge calculation itself.

The LLM extracts the rule. Python does the math.

For a charge calculation, the model extracts structured information such as:

free days
starting day of each tier
ending day of each tier
rate
currency
notes about the rule

The result is represented as a structured Rule/Tier model rather than free-form text.

The actual calculation is deliberately kept outside the LLM.

The Python calculator resolves open-ended tiers automatically. For example:

Days 1–7: free
Days 8–14: $40/day
Day 15 onward: $80/day

The calculator converts the open-ended first tier into days 8–14 and then calculates each applicable day deterministically.

This gives me a much clearer failure boundary:

LLM: retrieve and interpret the document.

Python: perform arithmetic.

I also tested the failure cases

One of the useful things about building this was discovering that a seemingly correct RAG application can still produce a dangerously wrong number.

The calculator tests include:

days inside free time → $0
days 8–10 at $40/day → $120
crossing into the second tier at day 16
open-ended tiers
tiers supplied in reverse order

For example, the test suite explicitly checks that 10 days held with 7 free days produces $120, and that 16 days correctly crosses into the $80 tier.

The Streamlit UI also lets the user inspect and edit the extracted free days and rate tiers before the final calculation, rather than hiding the intermediate rule.

Why Does Open Innovation Matter?

This project is a good example of where local and open AI can be more useful than simply calling a hosted API.

Shipping tariffs and contracts can be commercially sensitive. Sending those documents to a third-party AI service may not be acceptable in some workflows.

With DemurrageDesk, the generation model, embedding model, vector database, document parsing, retrieval, and calculation all run locally.

The models can be pulled through Ollama, and the application uses ChromaDB as its local vector store.

More importantly, open/local AI gave me control over the entire reliability layer around the model.

I could decide:

what evidence the model must provide
how citations are verified
when an answer is considered “found”
what information gets converted into structured rules
and exactly how the final charge is calculated

I don't have to trust the model to do everything correctly.

I can put deterministic software around the parts where deterministic software is better.

That's the part of open innovation I found most interesting: the model doesn't have to be perfect if the system around it is designed to catch its mistakes.

Limitations

This is intentionally a focused prototype rather than a billing authority.

There are still important limitations:

PDF tables can extract poorly.
Scanned PDFs require OCR preprocessing.
Small local models can still misunderstand complex language.
Calendar-day vs. working-day rules require human confirmation.
The extracted rule should be reviewed before acting on a calculated charge.

The README therefore explicitly treats human verification as part of the workflow.

The next step would be to put DemurrageDesk in front of someone who actually works with shipping tariffs every day and see which failure cases I haven't anticipated yet.

Prize Categories

Best Use of Gemma
Most Helpful Tool for a Friend

Hacktoberfest 2021

Rakshit Sharma — Tue, 26 Oct 2021 16:45:17 +0000

✨Completed my 4 PR's, but this year I learned how to use Github Desktop.✨

My First Hacktoberfest...

Rakshit Sharma — Sun, 01 Nov 2020 06:41:48 +0000

✨My First Hacktoberfest...✨

Introduction

This was my first Hacktoberfest and I thoroughly enjoyed it. I exchanged 4 pull requests as per the guidelines and learned how to use GitHub.

Background

The idea and inspiration were given by my elder sister who is a software engineer and has been associated with the fest for the past 3 years. I have been taught by her how to proceed with the fest and what all has to be done.

Progress

I am a beginner. I like the way GitHub has helped me to get my self introduced to various open-source code over the platform I wish to explore it more and would continue contributing to it.

Contributions

I made a beginner project on CALCULATOR. I initially added square root, factorial, cube root, power functions, and send pull requests for the same. Therefore, I completed 4 pull request successfully.

Reflections

Overall, I enjoyed the Hacktoberfest 2020, it was really nice working with the open-source for the first time. I will surely participate again in the coming years. I have learned how to use GitHub successfully and also how to work with open-source. Yes, I have made a few connections while working with the project CALCULATOR @riya-17 @divyagupta-98 @Vyvy-vi. I am looking forward to building some new projects and contribute to Github and take help from GitHub for my upcoming project completion.

DEV Community: Rakshit Sharma