DEV Community: Umar Bilal

An Industrial Data Ontology for Freight Wagon Records in Pakistan

Umar Bilal — Sun, 15 Nov 2026 02:38:39 +0000

Originally published on CodeNinja Atoms. Part of the open industrial data ontology series; every published object model is collected under ontologies.

An industrial data ontology, for a freight wagon fleet, is one governed model of what a wagon is and what happens to it, filled from the operator's own registers and files, with every fact tied to the register page, ledger entry or builder's document it came from. This post publishes the requirement we put to CodeNinja Praxis for such a model: a rail freight operator in Pakistan, described by class, asking for a single queryable truth about its wagons where today there are paper registers in many hands. How we define and build these models is on the industrial data ontology page.

Why a wagon fleet

The operator's freight fleet carries petroleum, containers, coal, fertilizer, wheat and rock phosphate across a national network. Public reporting on the operator puts its freight business at over eight million tonnes moved last financial year, and hundreds of new high capacity wagons are being inducted in 2026, some imported and some built locally, alongside an ageing legacy fleet. Wagons are maintained at divisional sick lines and periodically overhauled at central workshops, and the new wagons arrive from two builders with their own documentation and spares.

Each wagon has a history of examinations, repairs, wheel turnings, brake overhauls and component changes. That history exists, but it lives in workshop registers, divisional ledgers and, for the newest wagons, the builders' delivery files. So the operator cannot answer a simple question about a wagon. Which wagons of one batch have had a bogie component changed twice. Which wagons are due for periodic overhaul this quarter, and where are they. Which wagons were in the consist of the last three derailments. Each answer is a week of clerks' work across several workshops and ledgers kept in different words.

Two pressures make this urgent. New wagons are arriving with warranty terms the operator cannot enforce, because it cannot produce the maintenance history the builder asks for within the notice period. And the supervisors who know each workshop's registers by heart are retiring, taking the index in their heads with them.

The systems of record

The rolling stock register, the workshop job cards and registers, the divisional examination books, the stores ledgers for components and spares, the builders' delivery and warranty documents, the train running records, and the accident and derailment inquiry files. Every fact the system holds is tied back to one of them, with its date and the workshop that wrote it.

What the operator asks for

An industrial data ontology of the freight fleet, owned by the operator: one governed model of what a wagon is and what happens to it, filled from the registers and the builders' files, with open weight models on the operator's own hardware in the country reading the paper and the ledgers, and nothing about the fleet leaving the country or reaching a foreign model service.
The ontology itself. Wagon, wagon type, batch, builder, bogie, wheelset, brake assembly, coupler, component serial, examination, repair, overhaul, job card, store issue, warranty claim, consist, journey, incident and location, each fact tied to its source register, page or file.
Named agents that draft, officers who decide. A register reading agent, triggered by a scanned register page or a builder's file, drafts the wagon facts it contains in the ontology's terms with the page cited, confirmed by the workshop records clerk. An overhaul due agent, triggered by month start, drafts the wagons due for periodic overhaul with their last known location and open repairs, approved by the divisional mechanical engineer. A warranty agent, triggered by a component failure on a new wagon, drafts the claim with the maintenance history the builder requires, approved by the chief mechanical engineer's office.
Memory. Every confirmed reading and every accepted claim is kept, so the next register page and the next claim are read better, without training a model on the fly.
A command centre for the mechanical department: the fleet by type, batch, overhaul status and location, registers digitised by workshop, agent drafts awaiting confirmation, and a conversational interface that answers in English and Urdu with citations to the register page.
The model named. Reasoning runs on GLM 5.3 open weights, self hosted on the operator's own hardware in Pakistan.

The rules that bind

In country. Fleet records never leave the operator's network. Models are open weights on hardware the operator owns. No third party model service.
Rules. The railway's general and subsidiary rules on rolling stock examination, the public procurement rules that govern the builders' contracts and warranties, the national data protection rules for staff records appearing in the registers, and the audit requirements of the national audit office. The design names the approvals it needs.
Registers remain the record. The ontology cites the register. It does not replace it until the department says so, and no agent closes a job card or files a claim without a named approval.
People decide. Agents read and draft. Clerks, engineers and officers confirm.

What success looks like

Phase one covers one wagon type, the new high capacity wagons from both builders, and the two workshops that maintain them, for one quarter. It is measured against a baseline of days to answer a wagon history question, overhaul due lists produced on time, warranty claims accepted by the builders, and register pages digitised with confirmed accuracy. The event the design is tested on is a bogie component failing on a wagon from the newest batch, with the full history drafted from the registers and the claim filed within the builder's notice period.

What makes it an industrial data ontology

Three things separate this from a document scanning project.

The objects are typed, not imaged. A scanned register is a picture of a fact. The ontology holds the fact itself, a wheel turning on a named wagon on a date at a named workshop, as an object a query can reach, with the scan as its citation. More patterns of this kind are collected as industrial ontology examples.

The model is owned and governed by the operator. The vocabulary of wagon, batch, overhaul and claim is the operator's own, written down once and enforced everywhere, so two workshops that kept the same fact in different words now write it the same way.

The ontology is where agents and people meet. Every agent drafts in the ontology's terms and every officer confirms against the cited page, so each confirmed reading becomes memory that improves the next one, in context, never by retraining weights.

Questions the design must answer

What runs where on the operator's hardware, the hardware class and size, and the three year cost computed from the models' own weights.
How the ontology is built from paper registers, ledgers and builders' files and kept current job card by job card.
How a register reading and a warranty draft are explained to a clerk and to the audit office.
How confirmed outcomes become memory that improves the next reading.
Phase one's gates for extending to the legacy fleet and the other workshops.

The published designs that already answer parts of this, asset registers and maintenance history among them, are collected as physical AI system design and as sovereign AI reference architectures. Every object model is in the Vertical-Driven Architectures dataset.

About CodeNinja

CodeNinja is a Middle Eastern-American artificial intelligence lab focused on building self-improving systems. We are reinventing knowledge work to close the loop between vertical AI use cases and the generalized intelligence that fuels it, accelerating the path toward organizational superintelligence.

A Sovereign AI Reference Architecture for a Container Terminal in Pakistan

Umar Bilal — Sat, 14 Nov 2026 02:52:06 +0000

A sovereign AI reference architecture, for a container terminal, is a complete system design the operator owns end to end: open weight models running on hardware inside the country, reasoning over the terminal's own systems of record, with nothing about customers' cargo leaving the country or reaching a foreign model service. This post publishes the requirement we put to CodeNinja Praxis for such a system: a container terminal operator at a major seaport in Pakistan, described by class only, under pressure from the government's programme to cut container dwell time by two thirds. The architectures that answer requirements like this one are collected on the sovereign AI reference architectures page.

Why a container terminal

A container terminal moves boxes between ships, the yard and the road gate, with the customs authority clearing cargo on the premises and off dock yards taking the overflow. Terminals of this class in Pakistan see container dwell of around a week against a national target of two days, gate queues that stretch into the city, and periodic backlogs of hundreds of boxes that make the news. Trucks now need tracking devices fitted before they can carry cargo out, which has added hours to gate turnaround.

Every box that overstays has a reason, and the operator learns it late: a release the shipping line has not sent, a customs hold nobody chased, a consignee who has not booked a truck, a yard stack that buries the box under newer arrivals. The gate backs up when the yard cannot deliver boxes in appointment order, and the yard cannot plan when it does not know which boxes will clear today.

The planners know the lines, the agents and the cargo types that overstay most. None of that knowledge is written anywhere, so each planner starts the shift from a fresh list. And when the trade bodies or the port authority ask why a box took nine days to leave, the answer is assembled from four systems by hand.

The systems of record

There are seven: the terminal operating system, the gate operating system and its cameras, the customs authority's clearance messages, the shipping lines' manifests and releases, the yard equipment telematics, the truck appointment system and the off dock transfer log. Every fact the system uses is tied back to one of them.

What the operator asks for

A sovereign AI reference architecture. Open weight models on hardware the operator owns in Pakistan, reading the terminal's systems and the customs authority's messages, with nothing about customers' cargo leaving the country or reaching a foreign model service.
One model of the operation. A governed ontology of vessel call, container, consignee, agent, line, release, customs state, hold, yard position, stack, appointment, truck, gate transaction, dwell and off dock transfer, each fact tied to its source system, so one box has one story from discharge to gate.
Named agents that draft, planners who decide. An overstay agent, triggered by a box passing half its free time without a clearance step, drafts the chase to the line, the agent or the authority and the recommended off dock transfer, approved by the yard planner. A stack agent, triggered by the next day's clearances, drafts the housekeeping moves that put tomorrow's deliveries on top, approved by the yard superintendent. A gate agent, triggered by an appointment queue crossing its threshold, drafts the lane and slot changes for the gate supervisor to approve.
Memory. Every confirmed overstay cause and every accepted housekeeping plan is kept, so the next plan is better, without training a model on the fly.
A command centre for the planning team, with boxes ranked by dwell and cause, chases open, housekeeping drafts, gate queue state, agent drafts awaiting approval, and a conversational interface that answers with citations.
The model named. Reasoning runs on GLM 5.3 open weights, self hosted on the operator's own hardware in Pakistan.

The rules that bind

In country. Cargo, customer and gate camera data never leave the operator's network. Models are open weights on hardware the operator owns. No third party model service.
Rules. The port authority's concession terms, the customs authority's clearance rules and message formats, the national data protection rules for gate cameras and drivers, and the shipping lines' data terms. The design names the approvals it needs.
Systems first. The system reads from the terminal, gate and customs systems. No agent moves a box, releases a hold or changes an appointment without a named approval.
People decide. Agents watch and draft; planners and supervisors confirm.

What success looks like

Phase one covers import containers on one yard block and one gate complex for one quarter, measured against a baseline of median dwell days, boxes over seven days, housekeeping moves per delivered box and gate turnaround minutes. The event the design is tested on is a shipping line's release file arriving late for forty boxes due out tomorrow: seen, chased, and the stack replanned overnight so the morning appointments still clear.

What makes it a sovereign reference architecture

Three things separate this from a terminal analytics product bought off the shelf.

The data never leaves. Cargo manifests name customers and their goods, and gate cameras record trucks and drivers. All of it stays on the operator's network in Pakistan, and the models that reason over it are open weights on hardware the operator owns, never a third party model service that another jurisdiction can switch off or read.

The design is owned, not rented. The architecture must say what runs where on the operator's hardware, the hardware class and size, and the three year cost, so the operator can buy, run and replace every part of it. That is what makes it a reference: another terminal in the country facing the same dwell targets can take the same design.

The authority can audit it. Because every fact in the ontology is tied to its source system, an overstay chase or a housekeeping plan can be explained line by line to a planner, to the port authority and to the trade bodies asking why a box took nine days.

Questions the design must answer

What runs where on the operator's hardware, the hardware class and size, and the three year cost computed from the models' own weights.
How the terminal ontology is built from the operator's systems and the authority's messages, and kept current move by move.
How an overstay chase and a housekeeping plan are explained to a planner and to the port authority.
How confirmed outcomes become memory that improves the next plan.
Phase one's gates for extending to export containers and the other yard blocks.

The published designs this requirement sits beside are collected as physical AI system design and as sovereign AI reference architectures. Every object model is in the Vertical-Driven Architectures dataset.

About CodeNinja

A Sovereign AI Architecture for Refinery Operations Knowledge in Saudi Arabia

Umar Bilal — Fri, 13 Nov 2026 02:43:03 +0000

A sovereign AI architecture, for a refinery, is one the operator owns end to end: open weight models running on hardware the operator controls inside Saudi Arabia, reading the refinery's own systems of record, with nothing about the plant leaving the country or reaching a foreign model service. This post publishes the requirement we put to CodeNinja Praxis for such a system: a refining operator in Saudi Arabia, described by class alone, that wants the judgement of its best shift engineers turned into operations knowledge the whole plant can use. The published designs of this kind are collected as sovereign AI architecture reference pages.

Why a refinery

The refinery runs crude distillation, hydrocracking, hydrotreating, reforming, sulphur recovery and utilities around the clock, with a control room per complex and a shift engineer responsible for each. Refineries of this class process several hundred thousand barrels a day, by public reporting on plants of the class in the country, and run a major turnaround every few years with thousands of contractor workers on site.

The shift engineers are asked questions no single system answers. Why did the hydrocracker trip in the same way twice this year. What did the last turnaround find in this exchanger bank. Which procedure change was made after the last sulphur unit upset, and did it work. The answers exist, in the historian, in a shift log, in a change record and in an incident report, and a good engineer spends a night shift joining them.

The urgency is generational. Half the senior shift engineers retire within five years, and the new engineers inherit the systems but not the judgement. During a turnaround the problem doubles: thousands of findings arrive in days, and the engineers who can read them are out on the plant.

The systems of record

The distributed control system and its historian, the alarm and event journal, the operating procedures and shift logs, the maintenance management system, the management of change records, the incident and near miss system, the laboratory information system and the turnaround planning system. Every fact the system uses is tied back to one of them.

What the operator asks for

A sovereign AI architecture owned by the operator. Open weight models on the operator's own hardware in the country, reading the systems of record, with nothing about the plant leaving the country or reaching a foreign model service.
One model of the plant. A governed ontology of unit, equipment, tag, alarm, procedure, shift log entry, work order, change, incident, lab result, finding and turnaround task, each fact tied to its source system, so an exchanger has one history across the historian, the work orders and the findings.
Named agents that draft, engineers who decide. A trip analyst, triggered by a unit trip, drafts the sequence of events with the matching earlier trips and the changes made since, confirmed by the shift engineer. A handover agent, triggered by shift end, drafts the handover from the alarms, logs and work orders of the shift for the outgoing engineer to confirm. A findings agent, triggered by a turnaround inspection finding, drafts the matching history and the recommended disposition for the turnaround engineer to approve.
Memory. Every confirmed cause and every accepted disposition is kept so the next analysis is better, without training a model on the fly.
A command centre for shift engineers, showing open trips, handovers, findings waiting and agent drafts, with a conversational interface that answers with citations.
The model named. Reasoning runs on GLM 5.3 open weights, self hosted on the operator's own hardware in Saudi Arabia.

The rules that bind

In country. Plant data never leaves the operator's network. Models are open weights on hardware the operator owns. No third party model service.
Rules. The national critical infrastructure cybersecurity controls for operational technology, the process safety management rules, the operator's own management of change procedure, and the national data protection law. The design names the approvals it needs.
Read only on control systems. The architecture reads the historian and journals through the existing one way path. It never writes to the control system, and no agent changes a setpoint, a procedure or a work order without a named approval.
People decide. Agents draft; engineers confirm.

What success looks like

The first phase covers one complex and its control room for one quarter, including the turnaround if it falls in the quarter, measured against a baseline of hours to a confirmed trip sequence, handover completeness, repeat trips with the same cause, and findings dispositioned per day during the turnaround. The simulated event the design is tested on is a hydrocracker recycle compressor trip at night, with the matching trip from last year and the change made after it found and shown to the shift engineer within minutes.

What makes it a sovereign AI architecture

Three things separate this from a cloud analytics subscription.

The weights live with the plant. Reasoning runs on open weight models on hardware the operator owns inside Saudi Arabia, so the capability cannot be priced up, switched off or routed abroad by a vendor, and nothing about the plant crosses the border to a model service.

The knowledge is the operator's object model, not a vendor's index. The ontology of units, tags, procedures, changes, incidents and findings is governed by the operator and tied fact by fact to the systems of record, so it outlives any one supplier and any one model.

The judgement stays auditable and in country. Every confirmed cause and accepted disposition is a cited record an engineer and a process safety auditor can read, kept as memory on the same sovereign hardware, so the plant's hardest earned knowledge accumulates where it was earned.

Questions the design must answer

What runs where on the operator's hardware, the hardware class and size, and the three year cost computed from the models' own weights.
How the plant ontology is built from the systems of record and kept current shift by shift.
How a trip sequence and a finding disposition are explained to a shift engineer and to a process safety auditor.
How confirmed outcomes become memory that improves the next analysis.
The first phase's gates for extending to the other complexes.

The published designs that already answer parts of this, refinery and process plant operations among them, are collected as physical AI system design and as sovereign AI reference architectures. Every object model is in the Vertical-Driven Architectures dataset.

About CodeNinja

A Physical AI System Design for a Semiconductor Assembly and Test Line in Pakistan

Umar Bilal — Thu, 12 Nov 2026 02:41:00 +0000

By CodeNinja Atoms. First published on codeatoms.ai. The operator is described by class, never by name.

A physical AI system design, for a semiconductor assembly and test line, is one where the system's eyes sit at the stations themselves: edge units beside the bonders, moulders and markers read the inspection cameras as packages pass, classify what they see, and feed one governed model of the line that agents reason over and engineers decide from. This post publishes the requirement we put to CodeNinja Praxis for such a system: a semiconductor assembly and test operator in Pakistan, described by class only, building a new outsourced semiconductor assembly and test (OSAT) line under the national semiconductor roadmap, with its first packaging and test line commissioning in 2026. The published designs of this kind are collected on the physical AI system design page.

Why an assembly and test line

Wafers arrive diced from fabs abroad. The line attaches die to substrates or lead frames, wire bonds or flip chip bonds them, moulds, marks and singulates the packages, then tests them electrically and inspects them before shipment. The pilot line is sized for a few hundred thousand packages a month in the first year across two or three package families, with a path to tens of millions a year if anchor customers commit.

Back end yield is decided by things that are hard to see and easy to miss: a lifted wire, a cracked die edge, a void under the die attach, a smeared mark, a bent lead. The inspection stations image every package, but they raise far more alerts than a small quality team can review, and a tuned rule that catches one package family misses the next. When an anchor customer rejects a lot, engineers rebuild the story by hand across the bonder log, the mould recipe, the test bin map and the inspection images, which takes days and often ends without a confirmed cause.

This is a new line with a new team. The judgement of the few experienced engineers hired from abroad lives in their heads and leaves with them. A physical AI system is how that judgement becomes a property of the line instead of a property of the people.

The systems of record

The manufacturing execution system, the equipment data collection on each bonder, moulder and tester, the automated optical inspection stations' own result databases, the test cell's data logs, the quality management system and the customer return log. Every fact the system uses is tied back to one of them.

What the operator asks for

Physical AI at the station. Edge units beside the die attach, wire bond, mould and marking stations, on the CodeNinja on device AI stack, that read the inspection cameras as packages pass, classify each defect candidate and keep nothing but the classified result and the evidence frame. The design says which stations get a camera, what each camera looks for and what runs on the unit.
One model of the line. A governed ontology of lot, substrate, die, package, station, recipe, bonder head, mould tool, inspection run, defect, defect class, test bin, hold, customer return and corrective action, each fact tied to its source system.
Named agents that draft, engineers who decide. A classification agent, triggered by a new defect candidate, proposes the class with its evidence frame, confirmed by the quality engineer. An excursion agent, triggered by a defect rate crossing its control limit on one station, traces the likely recipe, tool or material lot and drafts a hold, approved by the process engineer. A return agent, triggered by a customer return, assembles the lot's full history and drafts the eight discipline report for the quality manager to approve.
Memory. Every confirmed class and every traced cause is kept so the next classification and the next trace are better, without training a model on the fly.
A command centre for the quality and process team with station defect rates, open holds, agent drafts and a conversational interface that answers with citations.
The model named. Reasoning runs on GLM 5.3 open weights, self hosted on the operator's own servers in Pakistan.

The rules that bind

Inside the plant. Customer die images, recipes and test data never leave the operator's network. Models are open weights on hardware the operator owns. No third party model service.
Rules. The anchor customers' confidentiality and data protection terms, the export control conditions attached to the equipment and die the line receives, the national data protection rules, and the automotive and consumer quality standards the customers audit against. The design names the approvals it needs.
Systems first. Read from the execution system, the inspection databases and the equipment logs. No agent places or releases a hold without a named approval.
People decide. Agents classify and draft; engineers confirm.

What success looks like

The first phase covers one package family on one line for one quarter, measured against a baseline of false alert rate, escapes found at final test or by the customer, time from excursion onset to hold, and engineer review hours per lot. The event the design is tested on is one wire bonder drifting and producing lifted wires across three lots, caught at the station, traced and held before the lots reach test.

What makes it a physical AI system design

Three things separate this from an inspection dashboard.

The intelligence is at the machine. The edge unit beside the bonder classifies the frame while the package is still in reach, so an excursion is caught at the station where it starts, not at final test or at the customer, lots later.

The physical line and the record of it are one model. A lifted wire is not an image in one database and a bin code in another; it is a defect, on a package, from a bonder head, under a recipe, inside a lot, and the agents trace along those relations the way an experienced engineer would.

The outcome feeds back. Every class the quality engineer confirms and every cause the process engineer accepts is written into memory that the next classification and the next trace must read, so the line's judgement compounds with every lot instead of leaving with the engineers who carry it.

Questions the design must answer

Which stations carry cameras, what runs on each edge unit and on the plant servers, and the hardware class, size and three year cost of each, computed from the models' own weights.
How the line ontology is built from the operator's systems and kept current lot by lot.
How a classification and an excursion trace are explained to an engineer and to a customer auditor.
How confirmed outcomes become memory that improves the next result.
The first phase's gates for extending to the next package family and the next line.

The published designs that already answer parts of this, vision at the station and plant quality among them, are collected as physical AI system design and as sovereign AI reference architectures. Every object model is in the Vertical-Driven Architectures dataset.

About CodeNinja

The published designs of this kind, each with its object model as hyper-ontology/1 JSON under CC BY 4.0, are collected on the CodeNinja Atoms physical AI system design page.

System design for physical AI: a robot field watched by the cameras it has

Umar Bilal — Wed, 11 Nov 2026 06:59:38 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/mobile-robot-fulfilment-centre-saudi-arabia/. DOI 10.5281/zenodo.24048579. The operator is described by class, never by name.

A warehousing and intralogistics operator in Saudi Arabia runs a robotic e commerce fulfilment centre of roughly 400,000 square feet with more than 250 autonomous mobile robots. The question it needs answered all the time is who and what is inside the robot field right now, and what that is doing to throughput and safety. Today the answer is scattered: the fleet orchestration system holds stall codes but not causes, the warehouse management system holds waves but not field state, and the incident and near miss log records a person in the field days after the event, if at all. When a replenishment cage is left in a lane during a peak wave, the design sees the blocked lane on the cameras that already cover the field, joins the stalled robots to the totes they carry and the wave those totes fulfil, and drafts the clearance task the fleet controller approves while the wave can still be recovered.

1. Six sources, read only, behind one adapter family

The warehouse management system owns orders, waves, totes and locations. The robot fleet orchestration system owns robot state, stall and fault codes and charging queues. The warehouse control system supplies conveyor and sorter jams, the labour management system supplies role and shift context, the incident and near miss log is the record the operator learns from late, and the building's camera recorders carry every detection point. All six are bound read only, and the direction is structural rather than a policy: the adapters hold credentials for read endpoints only, so nothing above them can reach a write path even by mistake. The platform never drives a robot, never issues a motion command and never writes into a system of record.

Data enters through one family of read only integration adapters, never directly: change data capture through Debezium for the transactional systems, which reads their change logs instead of polling them and adds no query load during a peak, and stream ingest through MediaMTX and Frigate for the camera substreams where they already exist. Every message is stamped with its source, its timestamp and its adapter version, so provenance is a queryable property of every object. Apache Kafka 4.3 in KRaft mode carries it all, partitioned by robot, zone and wave so each entity's sequence holds, at least once, with idempotent writes keyed by offset so a replayed message cannot double count an incursion. Linuxptp and chrony, disciplined by a GNSS PTP grandmaster, put evidence frames, robot positions and badge extracts on one clock, because the join between an incursion and a stall is only as good as its timestamps.

2. Fifteen objects, from a person at a gate to the orders delayed

The object model holds fifteen typed objects and thirteen typed links: zone, robot, charging bay, pick station, camera view, tote, order wave, shift, incursion, stall, person role, near miss, corrective action, agent draft and edge unit. A robot carries a tote, the tote fulfils an order wave, a stall delays that wave, a near miss references the stall and triggers a corrective action, so a query walks from a person at a gate to the orders their presence held up. The person role carries a pseudonymised badge reference, a shift and authorised zones, never an identity: people appear in the record as anonymous presence with a role. It is a governed graph written only by the adapter tier and the approvals service, and it is published as JSON for Hyper Ontology.

3. Three tiers inside the building, sized by arithmetic

Five models, no third party model service. On the edge tier, camera group units on an industrial grade octa core SoC with a 6 TOPS NPU sit beside the reused cameras and run RF-DETR (small) per frame under OpenVINO for person detection, with motion only trackers holding objects across frames and the re identification branch switched off. The checkpoints run about 61 to 68 MB at 16 bit, so the binding constraint is NPU load, and a dev board measurement on the real substreams is the gate before any unit is ordered at fleet scale. On the site servers, on CPU, Grounding DINO Swin-T classifies fallen totes, cages and blocked lanes on evidence frames the edge has already flagged, never per frame, and BGE-M3 serves Arabic and English cited retrieval.

The central tier is GLM 5.3 under vLLM, serving the three drafting agents, ontology maintenance and the command centre. The sizing is written out: 753 billion parameters at FP8 is 753 GB of weights, a factor of 1.2 for KV cache and activations gives 904 GB, and one node of eight 141 GB HBM accelerators provides 1,128 GB. It sits in the site data room at about ten kilowatts. Nothing in the design closes a control loop: the fleet's own sensors stop robots, and these analytics are operational feedback, never a safety rated stop. Frames, detections, weights and memory never leave the building. The node is a 4A090 class item for a D:3 and D:4 destination, so an export licence determination is a phase one procurement gate before the order, with an in country sovereign data center as the fallback placement.

Appendix A prices the node at about 569,000 US dollars to own over three years (541,000 to 594,000). Renting the same eight cards on the deepest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it; on demand is about 2.00 million, against which ownership costs a little over a quarter. Renting is a price reference only: AWS listed no Saudi region on the day read, and every rented option would carry evidence frames of the operator's people across the border. The edge units and site servers are not priced, because the paper does not count or size them.

4. Three agents, named people

The agents detect and draft, and people decide, by name. The shift supervisor approves the incursion agent's zone slow down and supervisor call, the fleet controller approves the stall agent's clearance task and reroute request, and the operations manager confirms the shift agent's handover. Execution is manual, every approval is logged with its reasoning, and known answer probes on the review queue measure whether approvers are rubber stamping. Nothing is trained into weights.

5. Gates, not dates

Three phases carry 16 scope items (4, 11 and 1), each closed by a gate. Camera reuse verification first, with six gates per view recorded at the worst hour, and purpose placed cameras bought only where a gate fails. Then one robot field zone and its pick stations live for one quarter against the operator's own baselines: incursions per thousand robot hours, stoppage minutes per shift, time from stall to clearance and orders per labour hour. Then the whole field and the next site, earned by that evidence.

Made with CodeNinja Praxis, the CodeNinja Atoms platform for designing physical AI systems. The object model imports into Hyper Ontology. Paper, ontology and register: https://codeatoms.ai/mobile-robot-fulfilment-centre-saudi-arabia/

One of the CodeNinja Atoms worked examples of physical AI system design: read only systems of record below, a governed ontology joined by typed links, detection on the cameras the building already runs, open weights on hardware the operator owns in its own country, and agents that draft while named people approve.

System design for physical AI: one corridor ontology over a freight operator's seven systems of record

Umar Bilal — Tue, 10 Nov 2026 02:44:13 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/freight-corridor-customs-saudi-arabia/. DOI 10.5281/zenodo.24048557. The operator is described by class, never by name.

A national freight and logistics operator in Saudi Arabia moves containers and bulk from seaports to dry ports and freight yards, by rail and road, across corridors of more than two thousand kilometres. The expensive failure is a chain: a customs declaration stalls at the seaport, the road leg runs late for its train, the handover slot is lost, and the first anyone hears of it is the customer calling. Every fact needed to see that chain early already exists, spread over seven systems that each own one piece of it. The design joins them into one consignment story so a corridor planner sees the stall, the connection it will cost and the customer who will call, and approves the chase and the re booking before the call comes.

1. Seven sources, read only, behind two adapter families

The rail operations and yard management system owns trains, wagons, yard slots and the handover the corridor turns on. The transport management system owns the road legs. The customs authority's declaration and clearance interfaces, the port community system feeds, the haulier telematics feeds, the container tracking system and the customer service case log hold the rest. Every one is bound read only: no agent files, amends, re books or cancels a declaration or a booking, and the design never writes into a system of record.

Data enters through two adapter families, never directly: an integration adapter on Debezium with Apache Camel for the operational systems, and a telemetry adapter for the haulier feeds. Each adapter guarantees three things before any agent reasons over a fact: lineage, ordering and a staleness flag. The staleness flag is the quiet hero here. A stall is defined by time passing without an event, so the system has to know the difference between "nothing happened" and "the feed stopped". Apache Kafka 4.3 in KRaft mode carries every change the adapters emit, in order.

2. Fifteen objects, joined on the container number

The object model holds fifteen typed objects and eleven typed links: consignment, container, declaration, train, wagon, road leg, haulier, terminal, dry port, handover slot, exception and customer case, with the corridor planner, yard controller and service desk agent as actors. It is a projection over the seven systems, held in Hyper Ontology v0.9, never a migration and never a copy. It owns no record, only the crossing mappings that answer questions no single system can, and the key it joins on is the container number every system already carries.

A projection only works if the join is honest, so the design carries a weekly join success gate at 95 per cent with failures triaged by source system. A join failing silently is worse than no join at all.

3. One node, sized by arithmetic

GLM 5.3 is named by the requirement for the command center that answers questions about a consignment with citations, with GLM 5.2 under MIT as the licence fallback, and the register commits no model row until a live verification passes. At FP8 the weights take about 756 GB. One node of eight 141 GB HBM cards gives about 1,038 GB usable, which leaves about 280 GB of KV cache ceiling, and one node serves the phase one corridor. It sits in the operator's own data center in the country at about ten kilowatts of rack power. There is no edge tier, no camera and no new field sensing: everything this design needs is already being recorded. The node is a 4A090 class item for a D:3 and D:4 destination, so an export licence determination is a phase zero checkpoint before any GPU class is quoted.

Appendix A prices the node at about 569,000 US dollars to own over three years (541,000 to 594,000). Renting the same eight cards on the deepest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it; on demand is about 2.00 million. Renting is a price reference only: AWS listed no Saudi region on the day read, and every rented option would carry cargo, customer and declaration data across the border.

4. Three agents, named people

The agents draft and people decide, by name. The corridor planner approves the stall chase and the revised handover slot, the yard controller approves every re booking, and the service desk agent sends the cited answer. Approval authority is a property of the actor objects in the model, not a setting in an app. A per shift alert budget is agreed before any threshold is set, and the action rate is itself a gate. Nothing is trained into weights: every confirmed stall cause and accepted re booking is kept as memory the next plan reads.

5. Gates, not dates

Three phases carry 17 scope items (2, 14 and 1). Baseline and approvals first, gated on the residency approvals closing and the baseline being recorded. Then one corridor between one seaport and one dry port for a measured quarter, whose exit gate is the source bindings and lineage proven on one real week of production data. Then the other corridors. The headline measure is dry port dwell in hours against a nominal of 96, with stalled declarations, missed connections and answered questions counted beside it.

One of the CodeNinja Atoms worked examples of a sovereign AI architecture: read only systems of record below, a projection ontology joined by typed links, open weights on hardware the operator owns in its own country, and agents that draft while named people approve.

System design for physical AI: a self-improving advisor for a cement kiln line

Umar Bilal — Mon, 09 Nov 2026 02:54:02 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/cement-kiln-control-saudi-arabia/. The DOI is assigned on release. The operator is described by class, never by name.

A cement company in Saudi Arabia runs several integrated plants, each with a preheater and precalciner kiln line of several thousand tonnes of clinker a day. When a new alternative fuel lot drifts the burning zone over a shift, the control room operator needs the likely cause, the recovery moves that worked in matching past upsets, and the setpoint adjustments with their expected effect on thermal energy per tonne. The historian holds the tags, the laboratory system holds the clinker quality, the fuel records hold the calorific value behind the drift, the shell scanner holds the physical sign of burning zone trouble, the maintenance system holds the refractory history, and the shift log holds what the last crew tried. Reconstructing one upset's story from them is hand work, and the practice that joins them lives in people's heads and leaves with them.

1. Advisory above the controller, never inside it

The agents ride above the incumbent model predictive controller rather than replacing or re-tuning it, so one control path survives and operators keep authority. The seven systems of record are bound read only, closed loop writes are excluded by the scope boundary, and the single write path in the whole design is a named person confirming, rejecting or annotating a draft. The one crossing toward the control network is the Lidi with Eurydice one way transfer stack, a data diode that makes a return path physically absent rather than merely blocked, and it fails closed: when the link, the power or the update path fails, the diode stops, the adapters buffer, the agents pause their drafts, and the kiln's control path is untouched.

2. Three adapter families on one backbone

Seven sources feed the design: the distributed control system and its historian, the laboratory system, the fuel and alternative fuel feed records, the kiln shell scanner, the maintenance management system, the shift log and the production reporting system. Three adapter families carry them, each owning its source contract: the integration adapter for the operational systems, the telemetry adapter for the streaming tag flow, and the ops systems adapter for logs, work orders and reports. A schema change at a source surfaces as a contract failure rather than silent corruption, every record is validated and stamped with provenance and receipt time, and both clocks align to the plant time source through Chrony, because a join between the historian and the laboratory system is only as good as their shared clock.

Apache Kafka 4.3 with KRaft is the event backbone. Tag streams are partitioned by tag name so the sequence of any one variable is never reordered, and delivery is at least once, made effectively once by idempotent writes keyed on each source's sequence numbers, so a replay after a fault cannot double apply an operator action or a lab value. The ontology lives in Hyper Ontology v0.9 over TimescaleDB as a governed projection over the systems of record, never a copy; a shadow data lake was set aside because copies drift and no document store joins an upset to the moves that cured it.

3. Sixteen objects, one walk

The object model holds sixteen objects: kiln line, equipment, tag, setpoint, recipe, raw meal lot, fuel lot, clinker sample and quality result, upset, operator action, shell scan, work order, shift, and the control room operator, shift supervisor and production manager. One query walks a path no single system holds: ask for every upset that began during a fuel lot change and was followed by a clinker sample back in specification, and the model traverses upset to fuel lot to operator action to sample in one step, where a document store would need the question known in advance and the join written by hand. Twelve objects are anchored in a named system of record; the upset and the three people are anchored in the model itself, because no system of record holds an upset whole or holds a person at all. The human loop lives in the status vocabularies: an upset walks from open through cause drafted and cause confirmed to recovered and closed, and only a person moves it.

4. One node, sized by arithmetic

GLM 5.3 files 753 billion parameters. At FP8, one byte per parameter, the weights occupy 753 GB, and the 1.2 planning factor, which reserves room for the KV cache and activations, brings the requirement to 904 GB. One node of eight accelerators of the 141 GB high bandwidth memory class offers 1,128 GB, which leaves 375 GB beside the weights, so the work surface never needs a second node. The node runs in the company's own data centre in the country, with vLLM serving under K3s and an air gapped Harbor registry for updates, and it is a 4A090 class item for a D:3 and D:4 destination, so an export licence determination comes before the order, with two nodes of the 80 GB class as the fallback shape. A third party model service was rejected outright, because nothing about the plants leaves the country.

The two small models need no frontier hardware. Chronos-2 (Apache-2.0, about 0.24 GB) forecasts the stable band on the streaming tags and its residuals raise the drift trigger; BGE-M3 (MIT, about 1.1 GB at FP16) embeds past upsets, shift logs and maintenance history in Arabic and English. Both run on the plant GPU server on one or two PCIe cards, because anything with a physical deadline runs beside the stream, and only drafts, citations and questions travel to the frontier node.

5. Three agents, named staff

The upset agent drafts a cause and recovery for the control room operator to confirm, the setpoint agent drafts adjustments after a fuel lot change for the shift supervisor to approve while that lot is still feeding the burner, and the shift agent drafts the handover with its energy and quality comparison for the production manager. Drafts run in shadow before anyone approves them. Nothing is trained; every confirmation or rejection is kept as the memory the next shift reads, so the system improves without a single weight changing, and a plant can audit a decision record where it could never audit drifting weights. The sector precedent that read 4.1 percent in a continuous month and 2.2 percent under a controlled comparison sets the honesty bar for what the gate may claim.

Appendix A prices the node at about 570,000 US dollars to own over three years (542,000 to 594,000: server, support and power at the national commercial electricity tariff). Renting the same eight cards around the clock on the deepest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it, and on demand is about 2.00 million, against which ownership costs a little over a quarter. Renting is a price reference only: the AWS price files list no Saudi region on the day read, and every rented option would carry the tag stream, the laboratory results, the fuel records and the decision record across the border, which the design's own rule forbids.

The rollout is two phases carrying 17 scope items (16, then 1) against 18 requirements, each closed by a gate, never a date: one kiln line at one plant for one quarter, gated on the setpoint agent's drafts flowing to a named approver and a controlled on and off comparison of thermal energy per tonne of clinker, in the units the national energy efficiency program itself collects. Further lines and plants follow on that evidence.

One of the CodeNinja Atoms worked examples of a self-improving AI system: a system that senses an operation, reasons over typed objects, acts through a named person and improves from what those people confirm, published with its object model as hyper-ontology/1 JSON under CC BY 4.0.

System design for physical AI: a patch cycle that learns from every confirmed call

Umar Bilal — Sun, 08 Nov 2026 03:32:47 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/ot-vulnerability-utility-us/. DOI to follow on Zenodo. The operator is described by class, never by name.

An electric utility in the United States runs substations, control centers and generating plants whose control systems fall under the critical infrastructure protection standards. Every time a vendor publishes an advisory, the compliance team has to answer one sentence: which of our devices does this touch, what does the verified baseline say, do we apply the patch or mitigate, and where is the evidence that we decided inside the window. The standards give thirty five days to review and thirty five more to act. The facts sit in seven systems of record, and the reasoning behind the last call on the same relay sits in somebody's mailbox. A handful of engineers know which vendors matter and which devices can take an outage, and two of them retire next year.

1. Inbound only, two writes

The useful signals, advisories, vulnerability records and patch artifacts, arrive from outside, while facts about the assets must never travel out. The design reads inbound feeds through verified paths and sends nothing back. Where the utility's policy demands it, OT side data leaves the electronic security perimeter through a hardware enforced one way path with no return route and no credentials inside the perimeter; a DMZ conduit is the lighter alternative. Every system of record is read only except two paths: the disposition agent drafts apply or mitigate change requests into the change management system, and the evidence agent writes confirmed evidence items into the evidence repository. Both land where the auditor already looks, which keeps the ontology a projection rather than a second system of record.

2. Eight sources, two adapter families

Seven systems of record feed the design, each read through its own API where one exists and a scheduled export where it does not: the asset inventory and configuration baseline system, the vendors' patch and advisory feeds, the national vulnerability advisories, the change management system, the work order system, the evidence repository for audits, and the network monitoring tool's device list. The eighth source is the patch artifact channel, the patches themselves, verified for source identity and integrity before any change can reference them. Two adapter families own the contracts: the integration adapter for the API and export sources, and the telemetry adapter for the OT side device list where it crosses the one way path. Every record carries its source system and its freshness, and business critical drafts refuse data older than an agreed age rather than guessing from a stale baseline.

Apache Kafka 4.4 carries everything between the adapters and the ontology, keyed on advisory identifiers and record identifiers. Delivery is at least once, made safe by idempotent upserts keyed on record identity and content hash, so a replayed export can refresh a record but never create a second applicability decision or a duplicate evidence item. There is no historian, no camera and no telemetry feed in scope: the design watches advisories, baselines and decisions.

3. Sixteen objects, three born in the design

The object model holds sixteen objects with thirteen typed links. Five anchor in the asset inventory and configuration baseline system: substation, protective relay, engineering workstation, firmware and software version, and configuration baseline. Eight more anchor in the vendor feeds, the national advisories, change management, the work order system and the evidence repository. Three anchor nowhere because the design creates them: applicability decision, disposition and cycle agent. One walk across the links answers the morning question: from the advisory through firmware and software version to the protective relays running it, onward to the substation and the outage window, and back through prior applicability decisions to their evidence items. An applicability decision moves from Drafted to Confirmed or Rejected only when a named engineer acts.

4. One node, sized by arithmetic

There is no edge tier. Both inference tiers, reasoning and embedding, sit on one node of eight GPUs of the 80 GB class in the utility's own data center. The register files gpt-oss-120b at 117 billion parameters (the paper rounds it to about 120 billion). At INT4, 0.5 bytes per parameter, the weights occupy 58.4 GB; multiplying by 1.2 to cover KV cache and activations gives 70.1 GB the GPUs must hold. The node offers 640 GB, so the weights fit with generous headroom for concurrent agent sessions. The checkpoint itself is 60.8 GiB, 65.2 GB of root safetensors; expanded fully to 16 bit it would need about 234 GB, which is what rules out a smaller host. vLLM 0.32 serves it from the node it sits on, and Harbor v2.15.2 holds signed artifacts in an air gapped registry. Nomic Embed Text v2 MoE, 475 million parameters at FP16, about 0.95 GB resident, embeds advisories, baselines and confirmed decisions on the same node. Both models carry Apache-2.0, a permissive license with no usage based trigger and no field of use restriction, and both were chosen because the requirement names open weights of United States origin on owned hardware, a GPU class with domestic supply and no export control complication for a United States end user.

5. Three agents that draft, memory that compounds

The applicability agent drafts which devices an advisory touches, for the compliance engineer to confirm. The disposition agent drafts apply or mitigate with its outage window and change request, for the asset owner to approve. The evidence agent assembles the audit package, for the compliance manager to confirm. No agent applies a patch, changes a baseline or closes a change. Nothing is trained on the fly: improvement is retrieval of confirmed decisions, with supersession and tombstone checks on every retrieval so a wrong precedent cannot confirm itself. Weights change only through a separately governed offline fine tune lane, promoted against a frozen question set built from the first cycles' confirmed calls, and never inside an active cycle week. Because engineers under a thirty five day clock can rubber stamp drafts, the acceptance rate is instrumented both ways and unflagged drafts are sampled independently each cycle.

Appendix A prices the node at about 477,000 US dollars to own over three years (437,000 to 496,000). Renting the same eight H100 80 GB cards on the deepest three year commitment in AWS US East is about 544,000, so ownership costs about seven eighths of it, and about 1.45 million on demand, against which ownership costs about a third. The region's other 80 GB class instance, eight A100 cards, rents for about 268,000 on the same plan, against which owning the H100 node costs about 1.8 times as much. Renting is a price reference only: every rented option would carry the asset inventory, the baselines and the vulnerability record outside the utility's network.

The rollout is two gated phases and 17 scope items (16, then 1): the protective relay fleet and its engineering workstations at one group of substations for two patch cycles, then an extension gate to the other asset classes and the generating plants. Phase 1 exits when the disposition agent is drafting apply or mitigate recommendations that engineers confirm on the record, measured against the utility's own baseline of engineer hours per cycle, windows kept, evidence completeness and auditor questions answered from the record.

One of the CodeNinja Atoms worked examples of a self-improving AI system, published with its object model as hyper-ontology/1 JSON under CC BY 4.0 in the cumulative dataset of vertical-driven architectures.

A Self-Improving AI System for a Gas Compressor Fleet in Saudi Arabia

Umar Bilal — Sat, 07 Nov 2026 02:49:07 +0000

A self-improving AI system, for a gas compressor fleet, is one that gets measurably better at maintenance decisions every time a work order closes, because what was predicted and what was actually found are written back into the context it reasons with, never into retrained weights. This post publishes the requirement we put to CodeNinja Praxis for such a system: a large gas processing operator in Saudi Arabia, described by class only, deciding when to inspect, extend or overhaul its compression trains. The way Praxis itself is run as one is on the self-improving AI system page.

Why a compressor fleet

Compression is the heart of a gas plant: trains of centrifugal compressors driven by gas turbines and large electric motors run around the clock. Every maintenance decision on a train, inspect now or extend, overhaul or repair, is made by a reliability engineer reading the historian, the vibration system, oil results and old inspection reports by hand.

When the inspection is done, what was found, worse than expected, better, or a different fault, is written into a work order and rarely flows back into the next decision. So the same judgement is relearned train by train, the best engineers' knowledge stays in their heads, and the fleet carries both unnecessary inspections and surprise trips.

An unplanned trip cuts plant throughput and can flare gas. An unnecessary inspection takes a train offline for days. Refurbishment capacity is limited, so every overhaul slot matters. A published 2026 maintenance case study from this class of operator showed that moving from fixed maker intervals to an extend and inspect approach, reading exhaust temperature, compressor discharge, bearing temperature, load, vibration, inlet filter differential pressure and trip logs, extended inspection intervals by 20 to 34 percent on one frame family.

The systems of record

The plant historian, the vibration and machinery protection system, the maintenance management system, the lube oil laboratory, inspection reports and the makers' service bulletins. Every fact the system uses is tied back to one of them.

What the operator asks for

A self-improving AI system. One governed ontology of plant, compression train, compressor, driver, component, sensor tag, reading, trip, inspection, finding, work order, interval decision and service bulletin, each fact tied to its source.
A loop that improves from outcomes. Every work order outcome, what was predicted and what was found, is written to memory and changes the next recommendation. The system improves loop by loop through memory, never by retraining weights.
Named agents that draft, people who decide. A condition agent, triggered by a new reading pattern or a trip, ranks each train's risk with its evidence, confirmed by the reliability engineer. An interval agent, triggered by an upcoming scheduled inspection, drafts extend or inspect with the evidence and past outcomes, approved by the maintenance superintendent. An outcome agent, triggered when a work order closes, compares prediction with finding and drafts the lesson into memory, confirmed by the maintenance planner.
Sensing at the edge. Continuous sensing on the critical trains, route based collection for the rest, at the edge on the CodeNinja on device AI stack.
A command centre for the reliability team, and a conversational interface whose answers cite their records.
The model named. Reasoning runs on GLM 5.3 open weights, self hosted in the operator's own data centre in Saudi Arabia.

The rules that bind

Sovereign. All plant data and models stay in Saudi Arabia on hardware the operator controls. No third party model service. Operational networks stay separated.
Rules. The national cybersecurity controls for operational technology, the Personal Data Protection Law, process safety management, and the operator's own engineering standards and permit to work. The design names the approvals it needs.
Read first. No agent changes a maintenance plan, a protection setting or a work order without a named approval.
People decide.

What success looks like

The first phase covers one plant's gas turbine driven compressor trains for twelve months, measured against a baseline of unplanned trips, inspections performed versus deferred with no adverse finding, the prediction hit rate on closed work orders, and overhaul slots used. The event the design is tested on is one compressor train tripping on high bearing temperature.

What makes it self-improving

Three things separate this from a condition monitoring dashboard.

The outcome is recorded against the prediction. When a work order closes, the outcome agent puts the finding next to what the condition and interval agents said before the inspection. That pair is the learning signal.

The lesson changes context, not weights. The confirmed lesson becomes a memory entry that the next recommendation for any similar train must read and cite. Nothing is trained into the model, so every change is a document a reliability engineer can read.

The loop is auditable. Because every lesson is a record with an author, a date and the work order it came from, a bad lesson can be found and retired, and the prediction hit rate on closed work orders shows loop by loop whether the system is actually getting better.

Questions the design must answer

How the fleet ontology is built from the historian and maintenance systems.
How each work order outcome changes the next recommendation, measurably, without training a model.
What sensing and edge hardware the critical trains need, sized and costed.
How the loop is audited so a bad lesson can be found and retired.
The first phase's gates for extending to every plant.

The published designs that already answer parts of this, rotating equipment condition monitoring and plant reliability among them, are collected as physical AI system design and as sovereign AI reference architectures. Every object model is in the Vertical-Driven Architectures dataset.

About CodeNinja

First published on CodeNinja Atoms. How CodeNinja Praxis runs as a self-improving AI system.

System design for physical AI: one ontology from tag to pump to permit limit

Umar Bilal — Fri, 06 Nov 2026 02:39:43 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/water-utility-ontology-us/. DOI 10.5281/zenodo.23889772. The operator is described by class, never by name.

A municipal water utility in the United States is in the middle of a control system migration. When the duty pump at a station trips at two in the morning, the operator on shift needs to know which tag tripped, which physical pump it belongs to, which zone that pump feeds, how long the reservoir covers zone demand, what the last work orders on the pump found, and which permit limits sit on the zone. The historian holds the tag and the alarm, the CMMS holds the asset number and the work order, the GIS holds the pipe and the zone, the LIMS holds the sample and the permit files hold the limit. Today the answer is a phone call to the person who remembers which tag is which, and those people are retiring before the cutover.

1. Cross the control boundary once

The ontology reads the control network and never sends a control command. The historian is read only through a mirror in a demilitarized zone, carried across a hardware enforced data diode by Lidi, so read only is a physical property of the link. A DMZ feed held by firewall rules alone was set aside, because configuration drifts and can be misconfigured into a write. The platform holds no credentials in the control network and no write path toward any system of record. Agents draft only: there is no write back to the CMMS or the permit records in phase one, set against the sector's usual pattern of writing work orders back, so the named approver acts in the system of record and the single write path ends at a confirmation record in memory.

2. Three adapter families on one stack

Six sources feed the design: the historian, the CMMS, the GIS, the LIMS, the permit records, and condition sensing (permanent vibration on pump and motor frames and motor current at the starter panels, with reservoir level and discharge pressure from existing instrumentation). Three adapter families carry them, all built on the Open62541 OPC UA stack with read only credentials: the ops systems adapter for the historian mirror, the integration adapter for the CMMS, GIS, LIMS and permit records, and the telemetry adapter for the sensing channels. Every fact enters stamped with its source system, its extraction method and its timestamp. Because the target historian is not yet selected, a dual tag namespace bridge holds the legacy and new namespaces at once, and the connectors are typed extractors re-confirmed against the chosen historian before cutover.

Apache Kafka 4.4, self managed in KRaft mode, keys events by tag and asset identifier and delivers at least once with idempotent upserts into the object model. The mirror buffers without pushing back pressure toward the source, the platform raises a staleness alarm at 15 minutes, and the command center drops into an explicit degraded mode while the raw alarms stand alone. Linuxptp with chrony, fed by an OCP Time Card grandmaster, puts alarm timestamps, lab result dates and work order dates on one clock. The graph lives in Hyper Ontology, time series in InfluxDB 3 Core.

3. Sixteen objects, one walk

The object model holds sixteen objects with fourteen typed links: treatment plant, well, distribution reservoir, pump station, lift station and pressure zone; pump, pipe segment, PLC and RTU; tag and alarm; work order, sampling point, lab result and permit limit. One query walks the night trip: the alarm is raised on a tag, the tag maps to a pump, the pump runs at a station, the station feeds a zone, the zone draws on a reservoir whose time to drain says how long the operator has, and the pump carries an open work order. A tag moves from Unmapped through Proposed to Confirmed only by the engineer, which is what lets a migration cut over on mappings someone has checked.

4. Two air cooled cards, sized by arithmetic

All reasoning runs in one tier, a single node in the utility's own server room; nothing computes at a station or a well, and the anomaly work on vibration and current is CPU class on the same server. gpt-oss-120b files 117 billion parameters. At half a byte per parameter that is 58.4 GB of weights, and the 1.2 planning factor brings the requirement to 70.1 GB. Two cards of the 48 GB PCIe class give 96 GB, about 88 GB usable, leaving roughly 38 GB beside the weights against the 12 GB the factor reserves, and the class air cools in a standard rack. vLLM serves it under RKE2, with an offline Harbor install for updates and Keycloak for identity. gpt-oss-120b was chosen over the GLM 5.3 class because the buyer is US state and local critical infrastructure and the maker of GLM sits on the US Entity List. Nomic Embed Text v2 MoE (475 million parameters, about 0.95 GB at fp16) handles retrieval for cited answers, chosen over BGE-M3 for origin. Both are Apache-2.0.

5. Three agents, named staff

The tag mapping agent proposes a mapping for the engineer to confirm, the alarm context agent assembles a pack for the operator on shift, and the compliance agent drafts monthly permit report data for the compliance manager to approve before any figure leaves the room. Nothing is trained; every confirmed mapping and resolved alarm is kept and read before the next proposal. A monthly sampled audit of confirmed mappings logs the error rate, so the queue cannot become a rubber stamp, and no seal claim is made for the vibration channel, because discharge pressure carries that failure mode.

Appendix A prices the server at about 59,000 US dollars to own over three years (57,000 to 61,000), with power at the United States average commercial tariff. Renting the same card class on the deepest three year commitment in AWS US East is about 104,000, so ownership costs a little under three fifths of it, though that instance carries four cards where the design sizes two. The lowest priced rented instance that holds the model, one 96 GB card of a different class, is about 33,000, against which ownership costs about 1.8 times as much. The choice rests on the room, not the rent: every rented option would carry tag values, alarms, work orders and permit records outside the utility's boundary.

The rollout is three gated phases and 16 scope items (5, 7, then 4) on one treatment plant and its distribution zone during the migration, held to the utility's own four baselines before the estate follows. The first gate is the tag mapping agent producing proposals with evidence the engineer can check against the source systems.

One of the CodeNinja Atoms worked examples of physical AI system design: systems that sense an operation, reason over typed objects and act through a named person, published with their object models as hyper-ontology/1 JSON under CC BY 4.0.

System design for physical AI: from a line trip to the first correct action

Umar Bilal — Thu, 05 Nov 2026 09:15:33 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/grid-control-room-saudi-arabia/. DOI 10.5281/zenodo.23889768. The operator is described by class, never by name.

A national grid operator in Saudi Arabia runs the transmission grid from regional and national control rooms. When one 380 kilovolt line trips at summer peak, the control engineer needs a list with a clock on it: which protection operated and in what order, which busbars and connected operators now sit de-energized, what maintenance is already under way on the affected apparatus, which procedure governs the switching that follows, and who must approve each step. Every fact exists, spread across SCADA and EMS, the outage plan, meter data, the asset system, the protection settings, a procedure library in Arabic and English and the weather feed. Today the engineer is the join, working from memory, phone calls and window switching while the alarm flood is still arriving.

1. A boundary that only points one way

The platform never sends a control command and never writes into a system of record. It reads ten sources, all read only and all of operator provenance, through a replicated historian or DMZ feed into a separate AI platform zone. Direct read only links inside the operational network were set aside, because the segmentation controls and the operator's own separation rule make any direct path a compliance breach rather than a shortcut. A hardware data diode with forward error correction is the committed fallback wherever the segmentation review demands demonstrable one way flow; software only read only links cannot demonstrate it. The single write path anywhere in the design is the recorded confirmation or approval, written into the object model and the memory service.

2. Three adapter families, one backbone

Three adapter families own every contract. The telemetry adapter carries the replicated SCADA and EMS series into the time series store; the integration adapter carries outage plans, protection settings, procedures and weather; the ERP adapter carries asset, maintenance and meter data from the enterprise systems. The tier checks schema and units, stamps provenance on every fact as it lands, and checks citation resolution and freshness on every answer, so a draft that cites a superseded procedure or a stale feed is caught before a person reads it. Apache Kafka carries everything, partitioned by point or asset, delivered at least once with idempotent writes so a replay cannot double count an alarm. Its retained log is also the replay mechanism that validates the triage agent on the operators' own recorded alarm floods. Linuxptp with chrony, disciplined by a GNSS PTP grandmaster with holdover, puts alarms, events and telemetry in one sequence of events. The time series store is left as a class, chosen at design against the historian's export format and scan rate.

3. Sixteen objects seeded from the network model

The object model holds sixteen objects with thirteen typed links: substation, transmission line, busbar, transformer, breaker and protection relay; alarm and grid event; switching program, planned outage and shift log; operating procedure; weather cell, connected operator, control engineer and shift supervisor. Topology is seeded by the CIM export from the EMS network model rather than assembled from documents. When the line trips, one traversal starts at the alarm, reaches the line it references, the substations at both ends, the busbars behind them, the operators supplied through them, the relays that protect the line with their settings revisions, the procedures that govern restoring it and the shift logs where the last comparable event was handled. An alarm moves to Acknowledged only under the control engineer, and a switching program moves to Approved only under the shift supervisor.

4. No edge, two central tiers

There is no edge tier and there are no cameras: the platform consumes replicated data, and fast protection decisions stay in the relays and remote terminal units where they have always lived. GLM 5.3 is filed at 753 billion parameters; at FP8 that is 753 GB of weights, and a 1.2 planning factor makes 904 GB. One node of eight 141 GB class GPUs gives 1,128 GB, which leaves 375 GB beside the weights against the 151 GB the factor reserves, and that headroom is what serves concurrent requests during an alarm flood. Two nodes of the 80 GB class were set aside because they need a fabric between them, and the 180 to 192 GB class buys headroom this workload does not need. BGE-M3 at FP16, about 1.1 GB, runs on the platform zone's rack server class for Arabic and English retrieval, and its recall on the operator's own Arabic procedures is evaluated before go live. vLLM serves the weights, Kubernetes orchestrates, and updates move through Harbor as staged, signed images.

5. Four agents that draft, people who decide

GLM 5.3 drafts for four agents: alarm triage confirmed by the control engineer, the switching program approved by the shift supervisor, the handover approved by the incoming supervisor, and the event analysis prepared for the protection engineer. Nothing is trained into weights; memory loops over confirmed decisions improve each shift, because a moving model would invalidate the frozen baselines. The GLM-5.3 bespoke license allows commercial use, fine tuning and redistribution, with an attribution notice and a managed access trigger above 10 billion US dollars of group revenue that internal control room use does not reach. Holding the sizing at one node means the export license determination for the GPU node, naming this end user, is asked once, early, as a phase one checkpoint before the order is placed.

Appendix A prices the node at about 570,000 US dollars to own over three years (542,000 to 594,000), with power at the national commercial electricity tariff. Renting the same eight cards on the deepest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it, and about 2.00 million on demand, against which ownership costs a little over a quarter. Renting is a price reference only: AWS listed no Saudi region on the day the prices were read, and the grid data would cross the border.

The rollout is three phases and 18 scope items (15, 2 and 1), each closed by a gate rather than a date: a pre summer build and replay gated on the switching program agent running end to end on replayed records, one regional control center live through one summer, then extension gates. Baselines are frozen before go live, and the headline measure is trip to first correct action.

One of the CodeNinja Atoms sovereign AI reference architectures: every published design with its sector, country, compute and three year cost.

System design for physical AI: predictive maintenance across five fleet records

Umar Bilal — Wed, 04 Nov 2026 02:41:34 +0000

By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/open-pit-mine-haul-fleet-saudi-arabia/. DOI 10.5281/zenodo.23889774. The operator is described by class, never by name.

An open pit mine in Saudi Arabia works a haul fleet of about 35 trucks of the 100 tonne class against one electric rope shovel of the 600 tonne class, feeding a crusher. A final drive announces its failure for months before it arrives on the ramp: rising wear metals in the laboratory's oil records, payload strain on ramp segments in the fleet system's cycles, an escalating alarm in telematics, and a rebuild history in the maintenance system that says the component is past its mean time between failures. Each system holds one link and none holds the chain, so the failure announces itself on the ramp with a loaded truck on it instead of in the workshop.

1. Two adapter families, one door

Five systems of record feed the design, all the operator's own and all read only at the door: the fleet management and dispatch system, the operator's own telematics, the maintenance management system, the oil laboratory and the mine plan. Two adapter families carry every fact in. The integration adapter handles vendor APIs, database reads and scheduled file exports; the telemetry adapter handles high rate signals from the truck bus and the edge units. Every fact carries its source system, its provenance class and a synchronized timestamp, and replays are idempotent. Writes return only through the owning systems, after a named approval and with an audit trail: approved haul redrafts into the fleet system's assignments, approved work orders and rebuild records into the maintenance system. No agent has a direct path to a machine. Truck positions come from the fleet system, so no tracking or trajectory layer is added.

2. A backbone that survives the link

Apache Kafka 4.3.x in KRaft mode runs on the site servers, partitioned by machine so one truck's events land in order, delivered at least once to idempotent consumers. Buffering happens twice: at the edge, where units hold events and small image crops while the private LTE link is down, and in the backbone, whose retention covers a replay after a consumer failure. The spectrum is shared access with no guaranteed channel, so the design sends events and crops, never continuous pixels. Linuxptp with chrony keeps sensors and systems on one clock. Models and containers arrive one way through a hardware data diode running Lidi into an air gapped Harbor registry, so the update path can never become an egress path. The time series store is deliberately left open: InfluxDB 3 Core, TimescaleDB and QuestDB are compared, and the choice lands after phase one measures the real telemetry rates.

3. Sixteen objects, one walk

The object model holds sixteen objects with thirteen typed links: haul truck, shovel, component, haul road segment, haul cycle, payload record, telematics alarm, oil sample, tyre reading, work order, rebuild, ground engaging tool and shift, plus the maintenance planner, the dispatcher and the mine superintendent. A query starts at a telematics alarm on a truck working the ramp, walks to the haul cycles it ran over that segment, to the final drive with its hours since rebuild, to the oil trend on that component and to the findings at its last rebuild. Every one of those records exists today. The walk between them does not. A work order sits at "Drafted by agent" until a named person moves it to "Approved".

4. Detect at the bucket, forecast on site

The edge tier is an automotive grade octa core SoC on the trucks and at the shovel bucket camera, chosen over off the shelf edge boxes or GPU modules that need a heat path a sealed cab mount cannot give; a fan would pull dust through the board. It serves Grounding DINO, the Swin-T checkpoint at about 345 MB at 16 bit, through ONNX Runtime under K3s, to catch a missing tooth before it travels to the crusher, with the Swin-B checkpoint at about 467 MB as the fallback. The site servers run Chronos-2 zero shot with covariates, about 0.24 GB at 16 bit, thresholding forecast residuals for anomaly, and BGE-M3 at about 1.1 GB for retrieval over records that mix Arabic and English. Chronos-2 was picked over fine tuned models, which would move the operator's data into weights, and over TimesFM 3.0 and Moirai 2.0, whose non commercial terms cannot ship inside the boundary.

5. One node, sized by arithmetic

GLM 5.3 is filed at 753 billion parameters. At FP8 that is 753 GB of weights; a 1.2 planning factor brings the requirement to 904 GB. One node of eight 141 GB GPUs, about ten kilowatts in the site server room, gives 1,128 GB, which leaves 375 GB beside the weights against the 151 GB the factor reserves. It runs under vLLM and drafts for three agents: the health ranking the maintenance planner approves, the haul redraft the dispatcher approves, and the tooth loss alert the shovel operator confirms. The one exception to named approval is the tooth loss stop, which follows the site safety procedure. Rankings improve through memory of work order outcomes and planner decisions, never through weights. GLM 5.3's bespoke license permits commercial use, fine tuning and redistribution; Grounding DINO and Chronos-2 are Apache-2.0 and BGE-M3 is MIT, so the operator holds every copy.

Appendix A prices the node at about 556,000 US dollars to own over three years (528,000 to 580,000), with power at the Saudi industrial electricity tariff. Renting the same eight cards on the cheapest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it. Renting is a price reference only: AWS listed no Saudi region on the day the prices were read, and the fleet records would cross the border.

The rollout is four phases and 18 scope items (5, 6, 6, then 1), gated on the fleet ontology standing on the systems of record, the private LTE network across the pit, the tooth loss stop agent, and a six month measured run against the operator's own baselines of unplanned downtime, mean time between failures, tooth loss reaching the crusher and cost per tonne.

One design in the CodeNinja Atoms industrial AI reference architecture: open designs for real industrial operations by sector, each with its object model, open weight models, compute and three year cost.