Skip to documentation
eli.aidocs

Use cases by industry

Use case: fleet operations

A dispatcher on the morning standup needs the truth, fast: which lanes are missing their on-time target, why the Atlanta–Miami numbers slipped, and whether a driver has hours left — not a guess, and not a confident number the database can't back. This guide builds that assistant end to end for Ironline Logistics, an asset-based freight carrier, touching seven module slices: Intake to load the ops records, Atlas to type the fleet graph, Warrant to certify the on-time target, Conduit to connect the live TMS, Lens to answer with citations, Lineage to trace any answer to its source, and Crucible to keep it accurate as the network changes.

You can follow along in a real workspace. Run yarn demo:seed logistics and it opens as the Ironline Logistics (Freight) workspace — one of the demo workspaces — pre-loaded with the drivers, tractors, lanes, facilities, and the read-only TMS this guide uses verbatim.

One knowledge base, seven slices. The dashed edge is the loop that keeps it honest: a regression the golden set catches steers the next round of curation.

Prerequisites

  • A workspace key with kb:write, kb:read, data:read, data:run, agents:run, and runs:read, exported as $ELI_KEY. See Getting started.
  • Owner/admin on the workspace, to certify concepts and to author the TMS connector and its named queries.
  • An enabled chat model, so /query can generate — otherwise 409 no-model-configured.

1 · Intake — load the operations records

Ironline's knowledge already exists as ride-along notes, lane sheets, facility docs, and process pages. Post them as documents so their text becomes durably searchable and citable; graph enrichment follows independently. The seed loads the whole corpus for you; here is the shape of a single ingest so you can add your own:

POST/api/v1/documentsBearer · kb:write

Save markdown through the vault. The file, chunks, and full-text index commit before 201; embedding and graph enrichment continue as detached work, so the response contains stored-document metadata only.

Example requestbash
curl -s -X POST https://your-host/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "lanes/atlanta-miami.md",
    "title": "Lane — Atlanta-Miami",
    "content": "# Atlanta-Miami Lane\n\n~665 miles, one-day transit. Primary driver Sofia Reyes on Tractor 4118. Anchor customer Halewood Appliances. Recent I-75 construction pushed on-time below the 90% review threshold."
  }'
Responsejson
{ "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "path": "lanes/atlanta-miami.md", "contentHash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "title": "Lane — Atlanta-Miami" }

The response reports storage metadata only. Once detached extraction catches up, documents can cross-reference each other — the lanes/chicago-dallas.md doc, the fleet/tractor-fleet.md sheet, and processes/on-time-delivery.md all name the same drivers, tractors, and facilities, so retrieval becomes structured rather than a bag of paragraphs. No content of your own? The seeded workspace already has all fifteen documents; skip straight to Atlas.

2 · Atlas — type the fleet graph

Extraction populates Atlas with typed entities and relations from the workspace ontology: a Driver drives a Tractor, a Shipment runs_on a Lane, a Lane hubs_at a Facility, and overflow is subcontracted_to a Carrier. Read the neighborhood around a key entity — the Chicago-Dallas Lane— and the graph is right there:

GET/api/v1/entities/{id}/neighborhoodBearer · kb:read

The knowledge-graph frontier around one entity — canonical relations in both directions, typed by the ontology. depth (1–3) controls how many hops out you expand.

Example requestbash
curl -s "https://your-host/api/v1/entities/01KZLANECHIDAL0000000000/neighborhood?depth=2" \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "entity": { "id": "01KZLANECHIDAL0000000000", "name": "Chicago-Dallas Lane", "type": "Lane", "authority": "curated" },
  "nodes": [
    { "id": "01KZTRACTOR41020000000000", "name": "Tractor 4102", "type": "Tractor" },
    { "id": "01KZDRIVERBILLTURNER00000", "name": "Bill Turner", "type": "Driver" },
    { "id": "01KZFACCHICAGOTERMINAL000", "name": "Chicago Terminal", "type": "Facility" },
    { "id": "01KZFACDALLASDC0000000000", "name": "Dallas Distribution Center", "type": "Facility" },
    { "id": "01KZCARRIERBLUERIDGE00000", "name": "Blue Ridge Freight", "type": "Carrier" }
  ],
  "edges": [
    { "src": "01KZLANECHIDAL0000000000", "rel": "hubs_at", "dst": "01KZFACCHICAGOTERMINAL000" },
    { "src": "01KZLANECHIDAL0000000000", "rel": "hubs_at", "dst": "01KZFACDALLASDC0000000000" },
    { "src": "01KZLANECHIDAL0000000000", "rel": "subcontracted_to", "dst": "01KZCARRIERBLUERIDGE00000" },
    { "src": "01KZDRIVERBILLTURNER00000", "rel": "drives", "dst": "01KZTRACTOR41020000000000" }
  ]
}

The types are what make retrieval structured

Because Bill Turner is a Driver and Tractor 4102 is a Tractor— not just two strings that co-occur — Lens can answer "which tractor is Bill Turner assigned to?" from the edge, and a lane question can fan out to its facilities and its overflow carrier. Browse the same graph visually on the Graph explorer.

3 · Warrant — certify the on-time target

Extraction gives you concepts at authority machine_extracted— a starting point, not a source of truth. On-Time Deliveryis the carrier's headline KPI; before an assistant states its target it has to be vouched for. In Warrant, pin the canonical definition as a reviewable change, then certifyit — certified is the only tier an assistant states without hedging:

POST/api/v1/change-requestsBearer · kb:write

Propose the canonical definition as a reviewable change rather than editing silently. Approval promotes authority to at least curated and records the reviewer on the revision.

Example requestbash
curl -s -X POST https://your-host/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZONTIMEDELIVERY000000",
    "payload": { "description": "On-Time Delivery (OTD): a shipment is on-time if it delivers within the appointment window recorded in Ironline TMS. Company target is 95%; any lane below 90% triggers a root-cause review." },
    "note": "Pin the OTD definition and thresholds dispatch should quote"
  }'
Responsejson
{ "id": "01KZCR00000000000000000AA", "entityId": "01KZONTIMEDELIVERY000000", "kind": "update", "status": "open" }
POST/api/v1/entities/{id}/certifyBearer · kb:write

Owner/admin sign-off — authority certified. Also starts the review clock: nextReviewAt lands at now + the workspace's reviewIntervalDays, so a certified target can't quietly go stale.

Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KZONTIMEDELIVERY000000/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by Nadia Volkov (Ops Analytics) and Rosa Delgado (VP Operations)"}'
Responsejson
{ "authority": "certified", "lifecycleStatus": "published", "version": 3, "nextReviewAt": "2027-01-18T09:10:00.000Z" }

Do the same for the source of record — verify processes/on-time-delivery.md so its provenance carries a governance tier:

POST/api/v1/documents/{id}/verifyBearer · kb:write

Glean-style document verification. Stamps the verification tier, the verifier, and the next re-verify date — the governance block Lineage reports and the manifest counts.

Example requestbash
curl -s -X POST https://your-host/api/v1/documents/01KZDOCOTDPROCESS0000000/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"certified","note":"Current OTD process of record"}'
Responsejson
{ "id": "01KZDOCOTDPROCESS0000000", "verification": "certified", "verifiedAt": "2026-07-22T09:12:00.000Z", "nextVerifyAt": "2026-12-29T00:00:00.000Z" }

Certification is what lets the policy answer plainly

Once On-Time Delivery is certified, a question grounded in it clears the answer floor: the seeded workspace records the decision for "What is the on-time rate on the Chicago-Dallas lane?" as answer at confidence 0.80 (confidence_above_answer_floor). Uncertified concepts make the same engine hedge.

4 · Conduit — connect the live TMS

Documents describe the process; the Ironline TMS knows what the fleet is doing right now. Wire it in as a read-only data connector with a handful of governed, parameterized named queries a human authored — no SQL in prompts. List what the workspace exposes:

GET/api/v1/data/queriesBearer · data:read

List the named queries (domain components) available to run, with their parameter specs. Secrets and connection configs are never returned — only slugs, titles, and params.

Example requestbash
curl -s https://your-host/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "queries": [
    { "slug": "on-time-rate-by-lane", "title": "On-time rate by lane", "connectorName": "ironline-tms", "description": "Delivered-shipment on-time percentage for every lane, worst performers first.", "params": [] },
    { "slug": "lane-performance", "title": "Lane performance", "connectorName": "ironline-tms", "description": "On-time %, shipment count, and average miles for a single lane code.", "params": [ { "name": "lane", "type": "string", "required": true, "description": "Lane code, e.g. Chicago-Dallas" } ] },
    { "slug": "open-shipments-by-status", "title": "Open shipments by status", "connectorName": "ironline-tms", "description": "Count and revenue of shipments not yet delivered, grouped by status.", "params": [] }
  ]
}

Run on-time-rate-by-lane — the query bound to the On-Time Delivery entity — and every figure comes back with a dataCallId anchoring it in the append-only provenance trail:

POST/api/v1/data/queries/{slug}/runBearer · data:run

Execute a named query with validated params. Read-only, capped at the connector's maxRows, timed, and provenance-logged. Params are bound, never interpolated.

Example requestbash
curl -s -X POST https://your-host/api/v1/data/queries/on-time-rate-by-lane/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
Responsejson
{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "ironline-tms",
  "queryTitle": "On-time rate by lane",
  "columns": ["lane", "shipments", "on_time_pct"],
  "rows": [
    { "lane": "Atlanta-Miami", "shipments": 212, "on_time_pct": 84.0 },
    { "lane": "Columbus-Chicago", "shipments": 167, "on_time_pct": 91.3 },
    { "lane": "Dallas-Denver", "shipments": 143, "on_time_pct": 93.8 },
    { "lane": "Chicago-Dallas", "shipments": 389, "on_time_pct": 96.1 }
  ],
  "rowCount": 4,
  "truncated": false,
  "durationMs": 37,
  "executedAt": "2026-07-22T09:14:03.412Z"
}

Authoring is deliberately not an API job

Creating the ironline-tmsconnector and its queries — with the credential, the SQL, and read-only validation — is an owner/admin task in the UI. The API consumes the governed surface: it lists and runs, it never writes SQL. That boundary is what keeps the data layer from becoming a prompt-injection target.

5 · Lens — the dispatcher asks, and gets a cited answer

Now the payoff. A dispatcher asks in plain language; Lens retrieves the documents, detects the entities, runs their bound TMS queries as governed lookups, and returns an answer that cites both documents ([Sn]) and live rows ([Dn]) — plus a policy decision that says how much to trust it. Ask the real golden question:

POST/api/v1/queryBearer · agents:run

Run the grounded query pipeline with includeData: retrieval + entity detection + bound data lookups + one generation + a groundedness check + the answer-policy engine. The workspace comes from the key.

Example requestbash
curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Which lanes are below the on-time target this week?","includeData":true}'
Responsejson
{
  "answer": "One lane is below the 90% review threshold: the Atlanta-Miami Lane at 84% on-time [D1]. The company target is 95%, and any lane under 90% triggers a root-cause review with Grace Okafor [S1].",
  "claims": [
    { "text": "Atlanta-Miami is at 84% on-time, below the 90% threshold", "citations": ["D1"] },
    { "text": "Target is 95%; below 90% triggers a root-cause review", "citations": ["S1"] }
  ],
  "sources": [
    { "id": "S1", "docId": "01KZDOCOTDPROCESS0000000", "docTitle": "On-Time Delivery", "docPath": "processes/on-time-delivery.md", "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB" }
  ],
  "dataCalls": [
    { "id": "D1", "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC", "connectorName": "ironline-tms", "queryTitle": "On-time rate by lane", "rowCount": 4, "executedAt": "2026-07-22T09:14:03.412Z" }
  ],
  "entities": [ { "id": "01KZONTIMEDELIVERY000000", "name": "On-Time Delivery", "type": "concept", "authority": "certified" } ],
  "policy": { "decision": "answer", "confidence": "medium", "reason": "confidence_above_answer_floor" },
  "groundedness": { "verified": 2, "total": 2 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" }
}

The policy block is the trust signal: answer at medium confidence (0.73in the seeded decision), because the number is a logged live query and the threshold is a certified concept. Ask something the corpus and the data can't back — "Will the Atlanta-Miami lane be delayed by weather next week?" — and the policy engine returns abstain_with_pointers (no_relevant_chunks, confidence 0.11) instead of forecasting weather. And a safety-shaped question like "Is Bill Turner over his hours-of-service limit right now?" comes back as answer_with_caveat— the behavior fleet operations demands. The same pipeline is a native MCP tool, so it drops straight into a dispatcher's Claude or TMS assistant.

6 · Lineage — trace the answer back to its source

A VP reviewing the assistant asks the fair question: where is this coming from, and can I trust it? The answer cited S1 → docId 01KZDOCOTDPROCESS… and D1 → dataCallId 01KY10CC…. Pull that document's lineage and read the whole trail in one call — origin, governance, and the downstream answers it is grounding right now:

GET/api/v1/documents/{id}/lineageBearer · kb:read or runs:read

The unified per-document lineage trail: origin provenance, governance, the audit trail, derived knowledge, and downstream impact. This is how you prove an answer's pedigree end to end.

Example requestbash
curl -s https://your-host/api/v1/documents/01KZDOCOTDPROCESS0000000/lineage \
  -H "Authorization: Bearer $ELI_KEY" | jq '{origin: .origin, verification: .governance.verification, derived: .derived.entities, citedBy: .downstream.citedByAnswers}'
Responsejson
{
  "origin": { "kind": "manual", "path": "processes/on-time-delivery.md", "ingestedVia": "POST /api/v1/documents", "lastIngestedAt": "2026-07-22T09:05:11.008Z" },
  "verification": "certified",
  "derived": ["On-Time Delivery", "Detention Time", "FMCSA Hours of Service"],
  "citedBy": 9
}

There it is, closed loop: the words trace to a certified process doc that derived the On-Time Delivery concept and is currently grounding 9answers — so an edit to the target has a known blast radius. And the number in the answer traces the other way: the [D1] figure resolves to a data_calls provenance row recording the exact on-time-rate-by-laneSQL, its params, and its status. The VP didn't have to trust the model — they read the pedigree of every claim, document and data alike.

Same trail, in the document view

The workspace UI renders this exact DocumentLineage as a visual trail on the document page (via the BFF at GET /api/w/{workspaceId}/documents/{docId}/lineage), and an agent can pull it mid-run with the kb_document_lineage MCP tool. One shape, three surfaces.

7 · Crucible — lock the accuracy in

Lanes shift, construction clears, docks change appointment discipline — and a wrong answer to a shipper is expensive. Capture the questions dispatch actually asks as a golden set so Cruciblecan prove the assistant still answers them correctly after every change. Anchor the golden item "Why did on-time delivery drop on the Atlanta-Miami lane?" and seed a provenance qrel from the lane doc that should ground it:

POST/api/v1/qrelsBearer · kb:write

Author a graded relevance judgment for a golden item. source=provenance derives the highest-grade judgment from the item's anchored citation — deterministic, no judge model needed.

Example requestbash
curl -s -X POST https://your-host/api/v1/qrels \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "01KZGOLDENATLMIA00000000",
    "chunkId": "01KZCHUNKATLMIALANE00000",
    "docId": "01KZDOCATLMIALANE0000000",
    "grade": 3,
    "source": "provenance"
  }'
Responsejson
{ "id": "01KZQREL0000000000000000A", "queryId": "01KZGOLDENATLMIA00000000", "grade": 3, "source": "provenance" }

Run the Fleet Ops Q&A baseline set from the evals workspace, then read the metrics for the run. Retrieval and abstention numbers are deterministic; RAGAS numbers carry the judge model that produced them:

GET/api/v1/evals/runs/{id}/metricsBearer · kb:read or runs:read

Retrieval, RAGAS, and abstention metrics for one run — overall and by facet. The ruler for 'did the assistant get worse?'

Example requestbash
curl -s https://your-host/api/v1/evals/runs/01KZRUNA00000000000000000/metrics \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "runId": "01KZRUNA00000000000000000",
  "n": 18,
  "retrieval": { "recallAtK": 0.78, "ndcgAt10": 0.74, "mrr": 0.81, "hitAtK": 0.94 },
  "ragas": { "faithfulness": 0.92, "responseRelevancy": 0.85, "contextPrecision": 0.69 },
  "abstention": { "truthfulness": 0.66, "abstainRate": 0.14, "aurc": 0.071 }
}

When a metric drops after a network change, the golden set names exactly which question regressed — and promoting that miss back into the set turns it into a permanent test. That is the dashed loop in the diagram: Crucible's regressions steer the next round of Warrant curation. Compare two configs with a two-gate significance test in Measure & compare.

Ports — the standing assistant and its alerts

The whole loop is packaged as the fleet-ops-analystagent ("Fleet Operations Analyst"), whose system prompt cites every claim, abstains without verified backing, and neveradvises a driver to run past their FMCSA hours. The seeded workspace also ships two live alerts — an otd.breach for the Atlanta-Miami Lane at 84% and a critical hos.violationfor Bill Turner on Tractor 4102 after detention at the Dallas Distribution Center — the same signals a scheduled agent run surfaces on its own.

The leverage

Seven slices, one knowledge base, one audit trail. The dispatcher gets a fast answer that fuses the process docs with the live TMS; the VP can trace any answer to a certified source anda logged query and see its blast radius; and the whole thing is measured, so on-time accuracy is a number you watch rather than a hope. Swap freight for field service, utilities, or manufacturing and the shape is identical — the platform doesn't care what the trucks are carrying, only that every answer is grounded, governed, traceable, and measured.

Keep going

See the other demo workspaces you can seed in one command, walk the live-data surface in depth in Query live data, or see the whole platform at a glance in the Capability map.