03 · Model lab10 min read

Freit: letting AI into a haulage office without handing it the keys

Freit does the work of a transport office: it reads orders from mail, PDFs, scans and spreadsheets, sorts the inbox, proposes decisions and plans which truck takes what. A person makes every call that matters.

Freit does the work of a transport office. It reads orders from a mail, a PDF, a scanned CMR or a spreadsheet, sorts the inbox, proposes decisions and plans which truck takes what, and a person makes every call that matters. I built Freit as a working demo for transport companies in Austria, Germany and the Netherlands, and the most interesting part is not the AI itself. It is everything around the AI that decides what it may do, what a person must see, and when the answer is "ask a human".

Flow diagram titled 'The model reads and proposes; a person decides'. Order arrives (mail, PDF, scan, photo or spreadsheet), the model reads it (each field, where it was found, how sure), then the check screen, where a person settles every Needs you field, with a loop back when a field is missing: Freit asks the sender. The order is pushed to the TMS through its API and retried on failure. The approved order goes to route and solve (Valhalla routes, VROOM picks a truck), then a decision card (cost, margin and up to 3 alternatives), then a person decides (approve, pick another or decline), and the trip lands on the truck's row of the week board. The check screen and the person's decision are highlighted as the two places where a person must decide.
How an order moves through Freit · 8 steps, 2 human gates

The model only reads and proposes. A person settles every unsure field before the TMS sees it, and every truck assignment before it lands on the board.

The problem

In a mid-sized haulage company, orders arrive in every shape. A shipper sends a mail with the details in the body. Another attaches a PDF from their own system. A third sends a photo of a paper CMR, or a spreadsheet with twelve loads for next week. Someone in the office reads each one and types it into the transport management system, field by field.

That work is slow, but the real cost is the errors: a wrong postcode, a loading window read as the delivery window, a weight in the wrong unit. A truck sent to the wrong place costs far more than the typing ever did.

So the goal was never "let the AI enter orders". It was: take the typing away, and make every remaining human decision fast and well informed.

Reading an order: show where every value came from

The check screen is the heart of order entry. Every field shows three things: the value read, where it was found in the original, and how sure the model was. Click a field and the matching words light up in the mail, or the matching area on the scan. A dispatcher checks a field in one glance instead of hunting through a PDF.

The Freit check screen for order ORD-2026-01073: the original email on the left, the read order on the right. The pickup address is selected and the matching words in the email are highlighted; a note below reads 'Address, read with 100% confidence'.
The check screen · point at a value, see where it came from

A few rules make that screen trustworthy:

  • Needs you. Fields that are missing, unsure or break a business rule are marked. Approval stays closed until each one is corrected or confirmed. The model never gets to wave its own doubt through.
  • One input, many orders. A spreadsheet or a long mail can hold several orders. Freit splits them, and each one is checked on its own.
  • The agent asks the sender. When a required field is missing, Freit mails the sender a fixed question and reads the reply back into the order. The questions are fixed on purpose: a customer never receives free text the model made up.
  • Approve and push. An approved order goes to the TMS through its API. A failed push is shown and can be retried, never lost.

After approval, Freit produces a one-page eCMR preview for the sender. It is clearly marked as not legally valid, because a demo should never pass for a real consignment note.

The same intake also runs behind an inbox. Incoming mails and (simulated) WhatsApp messages are sorted into new order, change, status question or exception. A new order goes through the normal check; the rest lands where a person expects it.

Calm: an agent that acts as a person, never above one

Once orders are in, there is plenty an agent could do on its own: propose a truck, find a carrier, suggest a return load, move a delayed trip. Calm is the module that does this. Its design comes down to four rules.

1. It acts as a person, never with more power. Every action Calm takes runs on a real person's own session, through the database's row-level security. It never uses a service role. If Calm tries something that person could not do, the database refuses it the same way it would refuse them. The agent adds no new permission surface at all, and permissions are checked at the moment of each step, not when a routine was set up.

2. Decisions are things, not side effects. When Calm wants to do something that matters, it writes a decision: a card with the proposed action, its reasons and up to three alternatives. A person approves, picks an alternative or declines. The home page, Today, puts the next decision on top and lists what was handled since yesterday.

3. Two brakes, and the stricter one wins. How much Calm may do alone depends on two independent things: the mode an admin set for that kind of decision, and the model's own verdict on this particular action.

Mode set by the adminModel says "certain"Model says "valid"Model says "invalid"
Tell (report only)reportsreportsreports
Ask (a person decides)decision carddecision cardweak card or dropped
Autoruns on its owndecision cardweak card or dropped

Setting the dial to Auto is not enough. The model also has to be sure, so the model's own doubt always counts. In the app this shows as a dial per kind of decision, from Shadow (record only) to Suggest and higher, only where that kind allows it.

4. Taint. If a run reads anything untrusted, such as free text from a customer mail that could carry a prompt injection, the run is marked tainted. A tainted run can only propose, whatever its mode or verdict. This is a simple rule, but it closes the most obvious hole in any agent that reads mail.

Every step, by the agent or a person, lands in a history with undo where that kind of action has one. The logs hold field names, ids and codes, never raw personal data.

There is also something Calm deliberately does not have: memory. No vector store, no fine-tuning, no "what I learned about this customer". Every run starts cold and reads live data. It does not get smarter by itself, but every action can be explained by pointing at that run's inputs. For software that moves trucks, I think that is the right trade.

Planning: a solver for the maths, not a language model

The planning side is a week board: trucks in rows, trips as bars, unplanned orders in a side column. Drag a bar to plan or re-plan, or do it from the keyboard. Resources come in three kinds: own trucks, regular subcontractors and market carriers.

The Freit planning board for week 46: trucks in rows, trips as bars across Monday to Friday, proposals outlined in coral. On the right, the Plan the week result compares the agent with the nearest-truck baseline, and a proposal card asks to move a trip to another truck because a driver's weekly rest is due.
The week board · a plan, the baseline, and a proposal that needs you

The important choice here was where not to use an LLM. A language model is good at reading a messy mail. It is not good at assigning forty orders to twelve trucks under time windows and EU driving rules. So the two jobs are split:

  • Routes come from a self-hosted Valhalla engine, routed for a 40-tonne truck rather than a car. The order page shows the route on a map with self-hosted tiles.
  • Truck proposals come from the VROOM route optimiser. EU driving and rest times (45-minute breaks, 11-hour daily rests) are built into the estimate. Each proposal shows cost, margin and up to three alternatives.
  • Plan the week proposes the whole week in one go and compares it with a simple baseline: each order to the nearest free truck. That gives the dispatcher a reason to trust the plan, or to see where it does no better.

On top of that, the agent proposes a carrier from quotes, a return load for a truck, or a new slot for a delayed trip. Every proposal still ends as a decision card, and every proposal and its outcome (approved, edited, declined, expired) is logged and can be exported as CSV.

On the demo week from the film, Plan the week placed the same 18 orders as the nearest-truck baseline with 1,028 empty kilometres instead of 1,243, about 17 percent fewer, and a margin of €2,666.56 instead of €2,397.08. A demo week is not a customer's week, but it is the same comparison every dispatcher sees.

Built with the EU AI Act in mind

Freit is made for EU transport companies, so the AI Act was part of the design, not a checklist at the end. The project keeps a compliance document that maps each requirement to the code that meets it:

  • Human oversight: the decision cards, the autonomy dial and the Needs you gate. A person can always see, change or stop what the agent does.
  • Transparency: every value read shows its source and confidence, and the eCMR preview says plainly that it is not a legal document.
  • Record keeping: an append-only audit log of every step, by person or agent, without raw personal data.
  • Limits: a fixed catalogue of read tools built on each screen's own queries. No free SQL, no text-to-SQL, no vector store. AI calls run against a monthly budget and are recorded.

Writing down which file does what keeps the claims honest. If a new tool is added, the document has to change with it.

Stack and engineering

The database holds the rules. Every table has row-level security from the migration that creates it. Every write with a business rule goes through one database function that raises its own error code, and every privileged change writes an audit entry in the same transaction. The app never decides on its own who may do what, and that is exactly what lets the agent run on a person's session safely.

AreaChoice
AppNext.js (App Router), React, TypeScript, next-intl (English, Dutch)
Data and authSupabase Postgres with row-level security, about 120 migrations, passwordless sign-in by e-mail code
Background workDBOS durable workflows, an outbox, scheduled jobs
AILangChain with Mistral and OpenAI models, MCP tools, one budgeted AI call path
DocumentsPDF and scan reading (unpdf), mail parsing (postal-mime), PDF output (pdfkit)
Routing and planningValhalla (truck routing) and VROOM (optimiser) in Docker, MapLibre with self-hosted PMTiles
TestsVitest unit and integration tests, pgTAP for the database, an access-matrix suite, Playwright end to end

Two details I am happy with. By default nothing leaves the machine: mail, AI, the TMS push, routing and the optimiser all have a stand-in, so the whole app runs and tests offline. And because planning is a removable part, one command strips dispatch out, with its migrations, pages and scripts, leaving order entry on its own.

What it is, and what I took from it

Freit is a showcase and a sales demo, not a product. A transport company that wants this gets its own build, made on its own flows and its own TMS. The demo TMS, the staged truck tracking and the simulated WhatsApp channel are there to show the whole loop, not to pretend to be live.

What I took from building it:

  • The AI is the easy part. Reading an order well took less effort than deciding what happens when the reading is wrong. Most of the work went into the check screen, the gates and the logs.
  • Put the rules where they cannot be skipped. With permissions in the database, the agent, the app and a person are all held to the same rules, and I never had to trust the agent's code.
  • Use the right tool for each job. A language model for language, a solver for optimisation, a fixed list of questions for customers. Every place I kept the LLM out made the system easier to trust.

Next on the board: part loads (several customers' freight on one truck), sending orders and status updates to carriers, keeping customers informed from confirmed to delivered, compliance records such as a driver's week of driving and rest, and UK crossings.

Links: freit.eu

All notes