How a text-to-SQL chatbot became an AI platform on a governed knowledge graph — drafting a region’s project reviews, reading its RFPs, building its bid decks — and what made people trust it.
The Middle East division of a global engineering consultancy runs a portfolio of engineering projects that reports in six currencies. Every month, projects go through a project review. Leadership reads market-level views of finance and risk. Bid teams race incoming tenders against their deadlines.
The data behind all of it already existed — in a governed project-controls warehouse, in risk registers, in meeting notes, in RFP email threads. What didn’t exist was a short path from that data to a decision. That path ran through people copying numbers between windows.
01
Project managers
A monthly project-review pack: open risks, KPI trends, schedule, actions and quality findings — reconciled and argued.
BeforeAssembled by hand, every month, per project.
02
Market leadership
A portfolio view of finance and risk per market: targets, pipeline, debt, billing, work in progress.
BeforeStitched together from separate reports.
03
Bid teams
Fast triage of incoming tenders and a bid deck in the corporate template before the go / no-go.
BeforeKey dates buried in email threads; a 35-slide deck filled manually.
Chapter IIThe first answer
Ask the database. Then doubt it.
The first version was the obvious one: a chatbot that turned questions into SQL. It showed what was possible. But the figures a monthly review signs off can’t hinge on a query a model improvised a second ago — and nobody reading the answer could tell whether it had.
So the approach flipped. Curated stored procedures would fetch governed data, and each analysis would get its own system prompt. The model stopped being asked to find the numbers and started being asked to explain them.
Don’t let the model write the query. Let it read the result.
The principle every later design decision traces back to.
Chapter IIIThe ceiling
Streamlit got it to people. Then it got in the way.
The second version put that approach behind a grid of buttons in Streamlit: six analysis modules, thirteen stored procedures, a prompt for each. People used it — and every new request made the code a little stranger.
It had grown from a 2,800-line file, refactored into four. Output had to be coaxed into rendering below the buttons with a deferred-execution workaround. A new analysis touched four or five files. When a second developer joined, we needed an agent registry and written path-ownership rules just to avoid stepping on each other. Every piece of logic read and wrote the framework’s session state directly: the UI framework had become the architecture.
Era 1
Ask the database
A text-to-SQL chatbot. Impressive in a demo; hard to sign off. Governed numbers can’t depend on a query the model improvised.
Era 2
Streamlit modules
Curated stored procedures plus analysis prompts, behind a grid of buttons. Six modules, thirteen procedures — and a 2,800-line file.
Era 3
Two builders, one shell
The monolith split into four files, then an agent registry with path-ownership rules so a second developer could ship alongside.
Era 4
The platform
A FastAPI service streaming typed events to a React workspace. Agents became configuration, not code.
Chapter IVThe rebuild
Separate the brain from the face.
The rebuild split the platform in two: a FastAPI service that does the work, and a React workspace that shows it. Every place the old code poked the UI’s state became a yielded event instead — and four event types became the one protocol every agent speaks.
status
A step started — “Reading KPI trends”. The UI shows a live checklist instead of half-rendered text.
warn
A source failed softly. The run continues and the user is told what’s missing.
delta
A chunk of the report. Most agents append; the expertise finder sends cumulative text the client replaces.
done
The finished report plus metadata: tokens, timings, cache state — and for the deck, its full slide payload.
POST/api/agents/project-health/runready
Event stream
Report
Waiting for the first event…
A stylised, sped-up replay over the real event protocol — invented project and figures.
Because the browser needs to send a request body and receive a stream, the client reads server-sent events off a plain fetch rather than an EventSource, and maps HTTP failures into the same error event — so every screen handles a broken network and a broken run the same way.
Behind the gateway, a handler registry routes each agent to its runner. Eight handlers cover everything today, and one of them is generic: an admin can register a new stored-procedure agent in the agent builder — a procedure, a prompt key and a parameter schema — with no new runner code.
With identity, access, streaming, logging and export solved once, each agent only had to bring its data and its prompt. They’re organised the way the business is — by the phase of work they serve.
01 / 05
Project health report
Delivery
You do
Pick a project and a period. Choose a narrative report or a dashboard.
The platform does
Twelve fail-soft data pulls: project context, open risks with exposure converted at fixed FX rates, three months of cost-performance and aged-debt trends, schedule, change register, action tracker and quality findings.
The KPI dashboard — Healthy, Recovering, Deteriorating, At Risk — is built in Python and handed to the model to copy verbatim.
A 414-line prompt of mechanical rules: risks older than six months are flagged “Revisit”, new risks are raised only when a KPI trigger fires, every quote from a meeting is verbatim.
You get
A monthly project-review report with PDF export, email, a follow-up chat grounded in the report, and a presentation mode that paginates its own risk slides.
02 / 05
Market portfolio review
Delivery
You do
Pick a market and a period.
The platform does
Eight data loads — actuals, targets, pipeline, KPI trend, debt, billing, aged WIP — reduced by a 1,790-line pure-Python aggregation layer before the model sees a single row.
Billing is reported per local currency and never summed across them. Zero and “absent” are different values, so the report says “Not available” instead of a misleading 0.
You get
A market-level narrative over six computed tables, with an explicit banner if the report is ever incomplete.
03 / 05
Tender digest
Winning work
You do
Pick a processed RFP, or drop in the files — PDFs, Word documents, even Outlook email threads.
The platform does
Files are merged, Arabic is detected and translated, and eighteen fields are extracted in one strict-JSON pass with per-field instructions.
The receipt date comes from a scored heuristic over “sent / issued” lines — not from the model — and is normalised with the other key dates.
You get
A three-card summary where every cell is editable in place, then emailed as Outlook-safe HTML built from the edited values.
04 / 05
Bid deck drafter
Winning work
You do
Pick an RFP. Press generate.
The platform does
One structured-JSON call drafts the project description, scope bullets and programme narrative with milestones. Durations are calculated in Python.
The corporate 35-slide template is filled on the six slides that change; everything else — all 335 package parts — survives intact.
You get
The actual deck rendered to PDF for preview, then downloaded as an editable PowerPoint named after the client and bid.
05 / 05
Expertise finder
People
You do
“Who has rail supervision experience in the region?” — typed or dictated.
The platform does
Built by a colleague as a standalone agent; I integrated it into the platform’s streaming protocol, access model and workspace.
Semantic search over several hundred CV profiles, with intent classifiers, fuzzy skill matching and a diversity pass so one person can’t fill the shortlist.
You get
A conversational shortlist of candidate cards with CV downloads.
Chapter VIThe knowledge layer
Teach it how the business fits together.
Each agent knew its own stored procedures and nothing else. A question that crossed their lines — a client’s debt and its open risks and what the last project review decided — had no agent to go to. A sixth agent wouldn’t fix that. A layer underneath all of them would.
So the platform gained a governed knowledge graph: nine levels from the region down to a single dated fact, built by eighteen adapters from the warehouse, the registers, the change log, the CRM, processed RFPs and review-meeting transcripts. From a meeting it keeps only a few scored key passages, never the full text. Every fact at the bottom can be traced to its project, its month, its source and the exact row it came from.
L1
Root
The platform
L2
Business domain
Project delivery
L3
Operating structure
Divisions and markets
L4
Division
Infrastructure
L5
Market
Transport
L6
Client
A port authority
L7
Project · opportunity
Project 2417 · a bid in pursuit
L8
Lens
Financials · Risk · Reviews …
Financials
Cash & collections
Variations
Risk
Reviews & actions
Programme
Quality
Scope
Pipeline
L9
Dated evidence
Risk R-14 · Sep 2026 · risk register
Financial snapshot
Status report
Review KPIs
Risk
Action
Review narrative
AI risk review
Human review
Milestone
QA finding
Non-conformance
Unapproved work
Change order
Billing
Debt
Scope statement
Meeting passages
CRM opportunity
Processed RFP
Knowledge note
every fact →projectmonthsourcesource row
The catalogue as shipped, with its names paraphrased and its examples invented.
It lives in SQL Server, beside the data it describes: ordinary tables modelled as a labelled property graph, not a separate graph database. Nearly every walk is down the spine, then one hop sideways, which indexed tables handle well. Keeping it there meant one backup, one security model and no cross-server copying. If graph analytics ever justify Neo4j, an export writes the approved graph as Cypher.
The rule for what gets in is models propose, people ratify. A sync, a rule, an admin’s edit or a model’s suggested link each becomes a change request. Governed policies decide which apply on their own. And if a sync suddenly tries to create far more structure than already exists — the signature of a key-normalisation bug — the whole batch is held for one human decision instead of being written.
01
Propose
A sync, a rule, an admin edit or a schema-constrained model proposal — each one a change request.
02
Validate
Checked against the schema first. Invalid proposals are pruned with one of seven reason codes.
03
Ratify
Policies decide what applies on its own. The rest waits for a reviewer — never its own author, with four-eyes on.
04
Use
Only approved rows reach retrieval, routing or a prompt. Everything else is a dashed line in the explorer.
Questions are answered by walking the graph, not by guessing a query. Retrieval finds what a question names, routes it to the business lenses it touches, picks a governed retrieval recipe — a time window, evidence budget and which relationships to follow — and descends to the evidence. The old rule still holds: totals are computed in code at ask time, over every project in scope, with coverage stated and currencies kept apart. A leadership question also gets an attention screen: thirteen exception rules, using the same thresholds as the agents, so the chat and the reports agree on what is red.
Askready
Retrieval
Entity linkingTransport → a market. Checked against your project access.
PeriodSep 2026 — the latest month loaded
Domain routingA leadership question → all seven delivery lenses
Retrieval recipeLeadership exceptions — how to rank, what to cite
Attention screen13 exception rules → watchlist: 2417 flagged on 4
TraversalEvidence ranked by relevance × recency × salience
Human reviewAn AI-flagged risk was rejected by its reviewer
ContextApproved facts only, each cited as [E#]
Subgraph walked
Answer
A stylised, sped-up walk through one question — the market, clients, projects and figures are invented.
Two rules keep it honest. Where a person has reviewed an AI-flagged risk, the human verdict wins, and a rejection becomes a note the model has to respect. And every answer is cut to what the asker may see: each entry point is checked against their project access, and when something was left out the answer says so — never how much.
The same pipeline powers the home page: a chat with one question box. Beside each answer sit the subgraph it walked and the evidence it cited, and hovering a citation lights its row and its node together. Its charts are drawn by rule from figures the answer already holds — never supplied by the model. Behind it, an eleven-tab admin console exposes the rest: the graph explorer, a playground showing every retrieval step and the exact prompt, approvals, sync runs, health checks and the audit trail.
Chapter VIIThe hard parts
Where it got hard.
None of these show up in a demo. Every one of them shows up with real data, real templates and real users. Most ended in the same place: take work away from the model and give it to code that can be tested.
01
Numbers come from code. Words come from the model.
ProblemA model that does arithmetic will eventually do it wrong, confidently, in a board pack.
DecisionEvery KPI table, currency conversion, aggregation and project duration is computed in code — SQL and Python — first. The model receives finished figures and rules on how to talk about them — never a request to calculate.
Aggregation layer · 1,790 lines
02
Widening a proven query is not free
ProblemThe knowledge graph’s first production sync read the reporting views for every market at once. One market’s unconvertible text failed the whole debt read, one bad date failed billing, and a renamed column broke the schedule.
DecisionWhere a view converts text itself, the adapter reads one market and month at a time and isolates each failure. Dates are compared through a safe conversion, columns are resolved against the live table, and a partial read is reported as partial — never as a clean sync.
Graph sync · each adapter fails soft
03
Binary files over a JSON-only stream
ProblemServer-sent events carry text. A PowerPoint is not text.
DecisionA two-phase flow: the run streams its progress and ends with the fully resolved slide payload. The browser posts that same object back to render the preview and to build the file — stateless, no temp files, and the preview can never disagree with the download.
Deck service · two endpoints, one payload
04
The preview is the real document
ProblemAn HTML mock-up of a slide is a promise the PowerPoint may not keep.
DecisionThe exact generated file is converted to PDF by headless LibreOffice, each request in its own throwaway profile so concurrent previews never collide. If LibreOffice is missing, it degrades to a labelled facsimile.
Real PDF preview in ≈4 s in testing
05
A corporate template that fights back
ProblemThe masters disable bullets at every level, and setting an indent level silently switches text to the bold display face.
DecisionBullets carry their own character and hanging indent; sub-levels indent by margin only. Rows are matched by their real labels, never by position, and any mismatch fails loudly instead of filling the wrong slide.
Self-test asserts all 335 package parts survive
06
A content filter that cut reports mid-sentence
ProblemThe portfolio report occasionally stopped halfway, with no error the user could see.
DecisionA five-stage diagnostics harness separated token caps from content filtering from instruction overload. The fix: a blocking call with one retry, replayed as a stream, and an honest “report incomplete” banner if it still falls short.
Diagnostics script · 5 stages
07
Hiding the machine’s notes mid-stream
ProblemThe report ended in a machine-readable appendix that users should never see flash on screen.
DecisionThe stream holds back its last few characters until it knows whether a fenced appendix is starting, then diverts it into metadata for presentation mode.
Stream filter · a few characters of look-ahead
08
Email that survives Outlook
ProblemOutlook renders HTML with Word’s engine: no CSS variables, no flexbox, no mercy.
DecisionTable-based, inline-styled HTML rendered server-side from the user’s edited values, with every value escaped. The self-test injects a script tag to prove it never executes.
Email renderer · self-tested
09
Deterministic beats the model for provenance
ProblemWhen a bid arrived is a fact with consequences; a model’s best guess isn’t good enough.
DecisionA scored heuristic over the email thread’s “sent / issued” lines decides the receipt date and overrides the model. The model extracts; code arbitrates.
RFP ingest · heuristic override
Chapter VIIITrust by design
Trust, by design.
An internal AI tool lives or dies on whether people believe it — and whether it’s there when they need it. Every run passes through the same layers, whichever agent it is.
Identity
Windows authentication from IIS — no passwords, no new accounts.
Access
Per-agent and per-module grants in SQL, cached for 60 s. Hidden agents return 404, not 403.
Resilience
If the access store is down, enforcement fails open — an outage must not lock out the business.
Grounding
Follow-up questions are answered from the report, and told to say so rather than invent.
Knowledge
Only approved facts reach a model, and a person’s verdict overrides the AI risk row they reviewed.
Caching
Keyed on the data version, input hashes and model — so a stale report can’t be served as new.
Audit
Every run writes one usage row — user, agent, tokens, seconds — even if the browser disconnects.
Chapter IXShipping on-prem
Shipping where the data lives.
The platform runs on-prem, on a Windows server behind IIS, so identity comes free from Windows authentication. One process serves both the API and the prebuilt React app. The build output is committed to the repository, so the server needs no Node toolchain — a deploy is a pull.
It ran side by side with the Streamlit version, so rolling back meant repointing IIS, not restoring a server. And because the modules that read, write and render documents carry self-tests that need no database, model or network, the parts most likely to break quietly can be checked anywhere, in seconds.
$python -m utils.deck_builder --selftest✓ pass335 package parts round-trip
$python -m utils.deck_preview --selftest✓ passreal PDF via LibreOffice, ≈4 s
$python -m core.ontology --selftest✓ pass220 checks · a demo portfolio through the real sync
›6 / 6 passed
lines of Python
44,915
121 files
lines of TypeScript
20,107
68 React components
API routes
94
5 of them streaming
agent handlers
8
one generic, no-code
Module names simplified. Figures counted from the repository.
Chapter XWhat changed
What changed.
The work didn’t disappear; the copying did. Each agent replaced a manual assembly step with a run that shows its sources, flags what’s missing and leaves something the team can still edit.
TaskBeforeWith the platform
Monthly project review packAssembled by hand from reports, trackers and meeting notes.Drafted in one run from twelve live sources, with stale risks already flagged.
Market portfolio viewStitched together from separate finance and risk reports.Six computed tables and a narrative, per market, per period.
RFP triageKey dates dug out of long email threads, sometimes in Arabic.Eighteen fields extracted, edited in place, emailed in a click.
Bid deckA 35-slide corporate template filled in manually.Drafted, previewed as the real file, downloaded editable.
A question across the portfolioPossible only where an agent’s fixed query happened to fit it.Asked in plain words: totals computed, evidence cited, the path through the graph shown.
Adding a new analysisTouch four or five files and redeploy.Configure it in the agent builder — stored-procedure agents need no code.
Measuring nextEvery run already writes a usage row — user, agent, tokens, seconds. Adoption and time-saved figures belong here once they’re drawn from those logs; until then, this page doesn’t estimate them.
Chapter XIWhat I took away
What I took away.
1
Encode how the reviewers already work.
What makes the risk report trustworthy isn’t cleverness — it’s the review meeting’s habits written down as mechanical rules: the six-month “Revisit” flag, verbatim evidence, no new risk without a trigger.
2
Give the model less to do.
Every reliability gain came from moving work out of the prompt and into code: arithmetic, dates, provenance, layout. The model is best at the part only it can do — turning evidence into prose.
3
The platform is the product.
By the fifth agent, identity, access, streaming, logging and export were already solved once, properly. Each new agent only had to bring its data and its prompt.