Operational Ontology Target, Logic, and Implementation
목표는 모든 source row를 예쁘게 graph로 바꾸는 것이 아니다. 목표는 conservative logistics data를 decision 가능한 의미 계층으로 compile해서, deterministic logic과 LLM retrieval이 같은 source-grounded context를 쓰게 만드는 것이다.
1. Objective
현재 digital twin은 source-world를 잘 보여준다. 다음 단계의 ontology decision layer는 “왜 이 action을 추천하는가”를 source row, typed edge, deterministic fact, semantic explanation으로 traceable하게 보여줘야 한다.
2. Actions Enabled
| Action | Ontology support | Demo target |
|---|---|---|
| Retrieve context | searchable nodes with retrieval_description, aliases, source refs, and typed graph expansion policy | T05 query retrieves dock, shipment, task, capacity, lineage, and source evidence without pulling baseline noise. |
| Understand incident | Incident -> Risk -> SourceRecord plus NEXT_INCIDENT causal replay edges | Carrier early arrival is represented as an operational pressure event, not just a UI label. |
| Propagate impact | AFFECTS, EXECUTES_ORDER, FULFILLS_IN, CONSTRAINED_BY, LINEAGE_STEP_AT | Order risk expands to WCS work, AMR assignment, dock shipment, resource overload, and handling-unit trace gaps. |
| Rank action options | Decision -> RECOMMENDS/CONSIDERS -> ActionOption -> IMPACTS_RISK | Resequence APT-007 premium cartons outranks conditional notice because deterministic KPI deltas are stronger. |
| Explain provenance | EVIDENCED_BY and REFERS_TO edges preserve source file, source record id, freshness, replay order | Every decision surface can show what source rows supported it and which evidence is stale/missing. |
3. Minimal Schema
v0.1 uses 14 node types. This is intentionally small enough to reason about, but complete enough to support deterministic and semantic decision work.
| Node type | Why it deserves a node | Rejected as separate node |
|---|---|---|
Location | Spatial anchor for tasks, assets, resources, incidents, and twin highlights. | Zone/status are fields. |
Asset | AMR/charger can be assigned, excluded, routed, charged, or used as capacity evidence. | Battery snapshot is evidence/source state. |
Order, OrderLine, Shipment | Each has independent SLA, allocation, fulfillment, or carrier-decision lifecycle. | Customer/account/wave are fields for v0.1. |
WorkTask, HandlingUnit | Execution and movement truth are where operational decisions become concrete. | Milestones are lineage edge fields. |
Resource, LaborRole | Feasibility, approval, staffing, and bottleneck logic need deterministic capacity anchors. | Individual worker is not needed in this demo. |
SourceRecord | Provenance must be a first-class retrievable object, not hidden metadata. | Raw source system is a field/source ref. |
Incident, Risk, Decision, ActionOption | Decision twin needs explicit causal state, risk, selected action, rejected action, and explanation target. | Pressure score is a field, not a node. |
4. Logic Boundary
| Layer | Owns | Reason |
|---|---|---|
| Deterministic selectors | ID match, source freshness, affected entity expansion, task status, capacity overload, lineage gap, action KPI scoring | These are exact source facts or computed checks. They should not be delegated to a model. |
| Graph query | typed path expansion with max depth and allowed edge types | It prevents context explosion while preserving why each node is included. |
| LLM judgment | operator-language synthesis, uncertainty explanation, supervisor/customer-facing rationale | These require language judgment but must stay inside the ContextPacket evidence boundary. |
| Human approval | resequence, split, notify, operational override, customer-facing commitment | Conservative logistics environments require approval for side effects and external commitments. |
5. ContextPacket
ContextPacket is the retrieval boundary between ontology and LLM. The model receives selected nodes, selected edges, deterministic facts, missing/conflicting evidence, allowed actions, and semantic judgment needs. It does not receive the full graph.
CTX-T05. It contains carrier early arrival, APT-007 / SHIP-007, DOCK-03 capacity pressure, high-priority blocked WCS tasks, source sync asymmetry, handling-unit trace gaps, and the recommended resequence action.
6. Implementation
| Artifact | Purpose |
|---|---|
scripts/compile-operational-ontology.mjs | Reads source exports and twin scenario data, emits full ontology, context packets, and UI projection. |
scripts/validate-operational-ontology.mjs | Validates node/edge integrity, provenance, retrieval fields, ContextPacket references, and T05 smoke case. |
data/ontology/operational-logistics-ontology-v0.1/operational-ontology.json | Full source-grounded ontology artifact for research, validation, and future compiler work. |
src/data/generated/ontology-decision-demo.json | Small UI projection for graph view and decision process panels. |
app/api/ontology/decision | Runtime LLM explanation endpoint using OpenRouter openai/gpt-5.4-mini when the API key is configured. |
7. High Standard
v0.1 is intentionally minimal, but it is not a toy graph. It must prove that ontology compilation makes operational decisions traceable: source rows become evidence nodes, evidence nodes expand to operational entities, deterministic facts choose and constrain action options, and LLM explanation is bounded by the ContextPacket.
source row -> ontology node/edge -> deterministic fact -> selected action -> LLM explanation -> digital twin impact without trusting hidden prompt magic.