Skip to documentation
eli.aidocs

Use cases by industry

Use case: merchandising

A buyer on the floor at Summit Outfitters needs a straight answer: which hero SKUs are about to stock out, what a category is actually earning across stores, and who owns the fix — not a stale spreadsheet, and not a confident guess about numbers nobody can trace. This guide builds that merchandising analyst end to end across seven module slices: Intake to ingest the store and category docs, Atlas to type them into a retail graph, Warrant to certify the reorder policy, Conduit to bind the live retail data warehouse, Lens to answer with citations, Lineage to trace any figure back to its source, and Crucible & Ports to measure the accuracy and ship the agent.

One retail graph, seven slices. Documents and the live warehouse both feed the answer; the dashed edge is the loop that keeps it honest — a regression the golden set catches steers the next round of curation.

Follow along in the seeded workspace

Everything below runs against a real, pre-built workspace. Seed it in one command: yarn demo:seed retail — it appears as the Summit Outfitters (Retail) workspace, with a dozen densely-wikilinked docs, the merchandising ontology, the summit-rdw connector, a data-enabled agent with a saved run, sample answer-policy decisions, alerts, and a golden set already in place. The command is idempotent — re-running reuses the same workspace. Full catalog: Demo workspaces.

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 configure the data connector.
  • An enabled chat model, so /query and the agent can generate — otherwise 409 no-model-configured.

1 · Intake — ingest the merchandising knowledge

Summit's merchandising knowledge already lives as markdown — a store-network-overview.md, per-store interviews, category and vendor references, campaign recaps like Trail Season Launch, and findings like the Inventory Health Review. Post each straight in so it becomes searchable, citable documents. The seed did this for a dozen files; this is how you'd add one:

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": "store-network-overview.md",
    "title": "Store Network Overview",
    "content": "# Summit Outfitters\n\n[[Summit Outfitters]] is an omnichannel [[Outdoor Gear Retailer]] running eight physical stores plus [[Summit Online]]. Merchandising is organized around [[Technical Apparel]], [[Camping Hardgoods]], [[Footwear]], and [[Climbing Gear]], each supplied by vendors such as [[Granite Textiles]] and [[Summit Forge]]."
  }'
Responsejson
{ "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "path": "store-network-overview.md", "contentHash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "title": "Store Network Overview" }

The chunks and FTS index are already committed at 201. Detached embedding and extraction can then let Atlas reconcile references into the concept graph. The create payload does not expose enrichment state. Watch the store profiles (stores/boulder-flagship.md), category docs (categories/technical-apparel.md), and vendor pages (vendors/granite-textiles.md) all cross-link into one graph. Have a Confluence or SharePoint of merchandising docs instead? Wire it as a content connector per Ingest documents — the rest of this guide is identical.

2 · Atlas — type the retail graph

Extraction alone gives you a bag of names. Atlas types them against the workspace ontology — Store, Category, Vendor, Campaign, FulfillmentMethod, and System — and records typed relations: a Store carries a Category, a Vendor supplies a Category, a Campaign promotes a Category or Store, a Store fulfills_via a method. That structure is what lets retrieval follow the merchandising web, not just the text. Pull a key entity — Technical Apparel, the flagship category — and read its type, authority, and edges:

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

Fetch one entity with its ontology type, authority tier, and typed relations. This is the structured view Lens uses to expand a question into the right neighborhood of the graph.

Example requestbash
curl -s https://your-host/api/v1/entities/01KZTECHAPPAREL0000000000 \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "id": "01KZTECHAPPAREL0000000000",
  "name": "Technical Apparel",
  "type": "Category",
  "authority": "machine_extracted",
  "relations": [
    { "type": "supplies", "direction": "in",  "entity": "Granite Textiles",    "entityType": "Vendor" },
    { "type": "carries",  "direction": "in",  "entity": "Boulder Flagship",    "entityType": "Store" },
    { "type": "carries",  "direction": "in",  "entity": "Portland Pearl",      "entityType": "Store" },
    { "type": "promotes", "direction": "in",  "entity": "Trail Season Launch", "entityType": "Campaign" }
  ]
}

Note the authority tier: machine_extracted. Atlas gave you the shape of the graph — who supplies what, who carries what — but nothing here has been vouched for yet. That is the job of the next slice.

3 · Warrant — certify the reorder policy

Every inventory answer in this workspace turns on one governed concept: the Reorder Point Policy. If a buyer is going to act on "below reorder point," that policy has to be vouched for. In Warrant, propose its canonical definition as a reviewable change rather than editing silently, then certify it — certified is the only tier the analyst states without hedging:

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

Propose the canonical definition as a reviewable change. 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": "01KZREORDERPOLICY00000000",
    "payload": { "description": "Reorder point equals ~3 weeks of forecast demand plus vendor lead time. Any SKU below reorder point at a store is flagged to the category buyer and Yuki Tanaka." },
    "note": "Pinning the replenishment rule buyers act on"
  }'
Responsejson
{ "id": "01KZCR00000000000000000AA", "entityId": "01KZREORDERPOLICY00000000", "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 policy can't quietly go stale.

Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KZREORDERPOLICY00000000/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by Yuki Tanaka (Inventory Planning) for FY26"}'
Responsejson
{ "authority": "certified", "lifecycleStatus": "published", "version": 2, "nextReviewAt": "2027-01-17T09:10:00.000Z" }

Do the same for the source finding — verify the Inventory Health Review 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/01KY18AAAAAAAAAAAAAAAAAAAA/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"certified","note":"Current as of the latest inventory health review"}'
Responsejson
{ "id": "01KY18AAAAAAAAAAAAAAAAAAAA", "verification": "certified", "verifiedAt": "2026-07-22T09:12:00.000Z", "nextVerifyAt": "2026-12-29T00:00:00.000Z" }

Governance is what lets the answer policy commit. Ask "Which SKUs at Boulder Flagship are below reorder point?" and the engine returns answer at confidence 0.83 (confidence_above_answer_floor) because the claim rests on the certified Reorder Point Policy plus live data. Ask something thinner — "Should we mark down the Cascade rain shells now?" — and it returns answer_with_caveat at 0.41 (confidence_in_caveat_band), hedging instead of committing. That contrast is exactly the payoff of certifying.

Curate in the UI too

Everything here is also a click: the curation workflow shows the open change-request queue, the review-due list, and a certify button per concept. The API and the UI write the same append-only revisions — pick whichever fits the reviewer.

4 · Conduit — wire in the live retail data warehouse

Documents describe the assortment; the Retail Data Warehouseknows what actually sold and what's on hand right now. Conduit binds governed, read-only named queries onto entities. Summit's warehouse is wired as the summit-rdwconnector with three queries the buyers actually use. List what's available — you see slugs, titles, and param specs, never credentials or SQL:

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

List named queries (domain components) available to run, with their parameter specs and owning connector.

Example requestbash
curl -s https://your-host/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "queries": [
    { "slug": "net-sales-by-store", "title": "Net sales by store", "description": "Net sales and units grouped by store, largest first. No parameters.", "connectorName": "summit-rdw", "params": [] },
    { "slug": "category-performance-by-store", "title": "Category performance across stores", "description": "Revenue and margin for a given category, broken out by store, best revenue first.", "connectorName": "summit-rdw", "params": [ { "name": "category", "type": "string", "required": true, "description": "Category to analyze, e.g. Technical Apparel" } ] },
    { "slug": "low-stock-by-store", "title": "Low-stock reorder candidates by store", "description": "SKUs at a given store whose on-hand is below the reorder point, largest shortfall first.", "connectorName": "summit-rdw", "params": [ { "name": "store", "type": "string", "required": true, "description": "Store to check, e.g. Boulder Flagship" } ] }
  ]
}
POST/api/v1/data/queries/{slug}/runBearer · data:run

Execute a named query with validated params. Read-only, row-capped (maxRows 200), timed, and provenance-logged. Params are bound, never interpolated. Returns a dataCallId — the [Dn] provenance anchor.

Example requestbash
curl -s -X POST https://your-host/api/v1/data/queries/low-stock-by-store/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"store":"Boulder Flagship"}}'
Responsejson
{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "summit-rdw",
  "queryTitle": "Low-stock reorder candidates by store",
  "columns": ["sku", "product", "on_hand", "reorder_point", "shortfall"],
  "rows": [
    { "sku": "TA-SHELL-M", "product": "Alpine Hardshell — M", "on_hand": 2, "reorder_point": 12, "shortfall": 10 },
    { "sku": "TA-SHELL-L", "product": "Alpine Hardshell — L", "on_hand": 3, "reorder_point": 12, "shortfall": 9 }
  ],
  "rowCount": 6,
  "truncated": false,
  "durationMs": 38,
  "executedAt": "2026-07-22T09:14:03.412Z"
}

Bound to entities, so the question runs it for you

The seed binds each query onto an entity, so you rarely call /run by hand: Boulder Flagship → low-stock-by-store (with store fixed to the literal "Boulder Flagship"), Technical Apparel → category-performance-by-store (with category read from the question), and Retail Data Warehouse → net-sales-by-store. Authoring connectors and SQL is a deliberately UI-only, owner/admin task — the API consumes the governed surface, it never writes SQL. See Query live data.

5 · Lens — a buyer asks, and gets a cited, live answer

Now the payoff. A buyer asks in plain language; Lens retrieves the documents, detects the entities in the question, runs their bound queries as governed [Dn] lookups, and grounds the answer in both documents ([Sn]) and live rows ([Dn]) — under the answer policy. Ask the workspace's signature question with includeData: true:

POST/api/v1/queryBearer · agents:run

Run the grounded query pipeline: retrieval + entity detection + bound data lookups + one generation + a groundedness check + the answer-policy engine. Returns a dual-cited answer with a policy decision. 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 SKUs at Boulder Flagship are below reorder point?","includeData":true}'
Responsejson
{
  "answer": "Six Technical Apparel SKUs at Boulder Flagship are currently below their reorder point [D1], led by the Alpine Hardshell in sizes M and L. Replenishment follows the Reorder Point Policy — about three weeks of forecast demand plus vendor lead time — and Granite Textiles' four-week lead time is why these SKUs keep slipping under [S1].",
  "claims": [
    { "text": "Six Technical Apparel SKUs at Boulder Flagship are below reorder point", "citations": ["D1"] },
    { "text": "Reorder point is ~3 weeks of forecast demand plus vendor lead time", "citations": ["S1"] },
    { "text": "Granite Textiles has a four-week lead time", "citations": ["S1"] }
  ],
  "dataCalls": [
    { "id": "D1", "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC", "connectorName": "summit-rdw", "queryTitle": "Low-stock reorder candidates by store", "rowCount": 6, "executedAt": "2026-07-22T09:14:03.412Z" }
  ],
  "sources": [
    { "id": "S1", "docId": "01KY18AAAAAAAAAAAAAAAAAAAA", "docTitle": "Finding — Inventory Health Review", "docPath": "merchandising/inventory-health-review.md", "chunkId": "01KY18BBBBBBBBBBBBBBBBBBBB" }
  ],
  "entities": [
    { "id": "01KZBOULDERFLAGSHIP000000", "name": "Boulder Flagship", "type": "Store", "authority": "curated" },
    { "id": "01KZREORDERPOLICY00000000", "name": "Reorder Point Policy", "type": "concept", "authority": "certified" }
  ],
  "policy": { "decision": "answer", "confidence": 0.83, "reasons": ["confidence_above_answer_floor"] },
  "groundedness": { "verified": 3, "total": 3 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" }
}

The policy block is the trust signal: answer at 0.83 because the claim rests on a certified concept plus a logged, read-only query — with the live figure carrying its [D1] anchor and the definition its [S1] citation. Ask something the warehouse and docs can't back — "What will holiday foot traffic be next year?" — and the policy engine returns abstain_with_pointers (no_relevant_chunks) rather than inventing a number. This same result also fires the seeded inventory.stockoutalert ("6 SKUs below reorder point; Granite Textiles lead time is 4 weeks"), and the whole pipeline is a native MCP tool, so it drops straight into a buyer's Claude or BI assistant.

6 · Lineage — trace the answer back to its source

A category manager acting on this asks the fair question: where is this coming from, and can I trust it? The answer cited D1 → a live summit-rdw query and S1 → docId 01KY18…. 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/01KY18AAAAAAAAAAAAAAAAAAAA/lineage \
  -H "Authorization: Bearer $ELI_KEY" | jq '{origin: .origin, verification: .governance.verification, citedBy: .downstream.citedByAnswers}'
Responsejson
{
  "origin": {
    "kind": "upload",
    "path": "merchandising/inventory-health-review.md",
    "ingestedAt": "2026-07-22T09:05:12.008Z"
  },
  "verification": "certified",
  "citedBy": 9
}

There it is, closed loop: the answer traces to an ingested finding (merchandising/inventory-health-review.md), the document is certified, and it is currently grounding 9 answers — so an edit to it has a known blast radius. And the live figure has its own trail: the [D1] anchor points at a data_calls row that recorded the exact SQL, the bound param (store = "Boulder Flagship"), and the status. Two provenance trails behind one answer — the document and the query — and the manager didn't have to trust the model; they read the pedigree.

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 & Ports — lock accuracy in, then ship the analyst

Merchandising changes weekly — new campaigns, shifting lead times, mid-season markdowns — and a wrong inventory answer costs a sale or a margin point. Capture the questions buyers actually ask as a golden set so Crucible can prove the assistant still answers them after every change. The seed ships the Merchandising Q&A baseline set with items like "Which vendor supplies Summit Outfitters' technical apparel?" (Granite Textiles), "Who manages the Boulder Flagship store?" (Dylan Cruz), and the harder "Why did footwear maintained margin erode during the Trail Season Launch?". Anchor a provenance qrel from the vendor doc that should ground the first one:

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": "01KZGOLDEN000000000000000",
    "chunkId": "01KY1CGRANITE00000000000A",
    "docId": "01KY1CGRANITE000000000000",
    "grade": 3,
    "source": "provenance"
  }'
Responsejson
{ "id": "01KZQREL0000000000000000A", "queryId": "01KZGOLDEN000000000000000", "grade": 3, "source": "provenance" }

Run the set, 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": 3,
  "retrieval": { "recallAtK": 0.83, "ndcgAt10": 0.79, "mrr": 0.86, "hitAtK": 1.0 },
  "ragas": { "faithfulness": 0.94, "responseRelevancy": 0.88, "contextPrecision": 0.72 },
  "abstention": { "truthfulness": 0.67, "abstainRate": 0.14, "aurc": 0.061 }
}

Once the numbers hold, ship it. The workspace seeds the merchandising-analyst agent — data-enabled, cites the document or data source for every claim, and abstains without verified backing. Drive the exact same harness the UI uses over the agents surface:

POST/api/v1/agents/{slug}/runsBearer · agents:run

Start a run of the named agent. SSE stream when stream is true (default); a blocking JSON RunResult when false. Runs are keyed, attributed, and budgeted, and leave a full step trace.

Example requestbash
curl -s -X POST https://your-host/api/v1/agents/merchandising-analyst/runs \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Which SKUs at Boulder Flagship are below reorder point, and who should own the fix?","stream":false}'
Responsejson
{
  "runId": "01KZRUN00000000000000000B",
  "status": "succeeded",
  "text": "Six Technical Apparel SKUs at Boulder Flagship are below reorder point [D1]. Per the Reorder Point Policy the fix routes to the category buyer, Theo Marsh, and Yuki Tanaka in inventory planning [S1].",
  "citations": [ { "docId": "01KY18AAAAAAAAAAAAAAAAAAAA", "chunkId": "01KY18BBBBBBBBBBBBBBBBBBBB" } ]
}

The seeded run leaves a full, ordered step trace at GET /api/v1/runs/{id} — the model calls, the kb_search and the summit-rdwdata lookup, tokens, and cost — so every automated answer comes with its own receipt. When a metric drops after a merchandising 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 behind a two-gate significance test in Measure & compare.

The leverage

Seven slices, one retail graph, one audit trail. The buyer gets a fast, cited, live answer; the manager can trace any figure to a certified concept and a logged read-only query and see its blast radius; and the analyst is shipped, budgeted, and measured, so accuracy is a number you watch rather than a hope. Swap outdoor gear for grocery, apparel, or hardgoods and the shape is identical — the platform doesn't care what the SKUs are, only that every answer is grounded, governed, traceable, and measured.

Keep going

Turn the same live numbers into a scheduled, defensible deliverable with Automated reports, end to end, seed another domain from Demo workspaces, or see the whole platform at a glance in the Capability map.