Atlas

Atlas is the module that turns names into addressable concepts. It owns the entities, their aliases, the typed directed edges between them, and the mention-level provenance that says which document and which character offsets produced each fact. Everything below is served by pure SQL — no model, no embedding, no reranker.

What it does

Atlas stores a workspace's concepts as typed entities and connects them with typed, directed relations. Duplicates collapse into a single canonical head, and the serve-time edge table (canonical_relations) is a materialized rollup over that head, so a read never has to reason about merges. Every entity carries the aliases it answers to, a mention count, and the documents it was found in; every extracted edge can carry the quote that grounds it. The public surface is a list, a single concept read, a bounded neighborhood expansion, a workspace manifest, and hand-authored writes for entities and relations.

Use it standalone

Atlas is self-contained. The only things it needs are a workspace and an API key with the right scopes.

1. Give the key the graph scopes

   Reads (GET /entities, GET /entities/:id, the neighborhood, the manifest) require kb:read; the legacy runs:read grant is still accepted on those four. Writes (POST/PATCH/DELETE on entities and relations) require kb:write. Scopes are checked by exact membership — kb:write does not imply kb:read, so a key that both reads and edits the graph needs both. Delegated user keys (eli_uk_) additionally have their owner's live capabilities re-checked: graph:read for the entity reads, graph:write for the writes, and workspace:read for the manifest.

2. Import one module

   Headless: createGraphClient from @eli-ai/client/graph. React: EliKnowledgeGraph from @eli-ai/react/graph. Types-only: @eli-ai/contracts/graph. None of the three pulls in another capability module.

3. Seed the graph by hand, or let ingestion fill it

   POST /api/v1/entities and POST /api/v1/relations are enough to build a complete graph with no documents at all. If documents are present, extraction writes into the same tables and the reads are unchanged.

import { createEliTransport } from "@eli-ai/client/core";
import { createGraphClient } from "@eli-ai/client/graph";

const graph = createGraphClient(
  createEliTransport({
    baseUrl: "https://eli.ai",
    apiKey: () => process.env.ELI_API_KEY!,
    workspaceId: process.env.ELI_WORKSPACE_ID,
  }),
);

// Hand-author two concepts and the edge between them.
const platform = await graph.createEntity({
  name: "Order Platform",
  type: "system",
  aliases: ["order-platform", "OP"],
});
const owner = await graph.createEntity({ name: "Ada Byron", type: "person" });

await graph.createRelation({
  srcEntityId: owner.id,
  dstEntityId: platform.id,
  type: "owns",
  evidence: "Ada is listed as the service owner in the on-call rota.",
});

// Read it back.
const page = await graph.listEntities({ limit: 25, type: "system" });
const around = await graph.neighborhood(platform.id, { depth: 2, perHopCap: 10 });
console.log(page.total, around.edges.length, around.truncated);

React components

@eli-ai/react/graph exports exactly one component, EliKnowledgeGraph, plus its two prop types (EliKnowledgeGraphProps, EliKnowledgeGraphLabels). It renders a Surface containing an optional create form, a filter input, a flat canvas of clickable concept buttons, and a side panel that loads the selected concept's neighborhood at depth 1. It calls three operations through the headless graph client: listEntities on mount, neighborhood when a concept is selected, and createEntity when the form is submitted. The filter is client-side only — it narrows the already-loaded page by name or type and issues no request.

{
  title: "Knowledge graph",
  description: "Explore concepts and the evidence-backed relationships between them.",
  filter: "Filter concepts",
  type: "Type",
  create: "New concept",
  cancel: "Cancel",
  name: "Name",
  aliases: "Aliases",
  save: "Create concept",
  empty: "No concepts found",
  neighborhood: "Neighborhood",
  relations: "Relations",
  sourceDocuments: "Source documents",
}

import { createEliTransport } from "@eli-ai/client/core";
import { EliProvider } from "@eli-ai/react/provider";
import { EliKnowledgeGraph } from "@eli-ai/react/graph";
import "@eli-ai/react/styles.css";

// EliProvider has no API-key prop by design. Point the transport at a
// same-origin route of your own that injects the Bearer key server-side.
const transport = createEliTransport({ fetch: sameOriginProxyFetch });

export function ConceptExplorer({ workspaceId }: { workspaceId: string }) {
  return (
    <EliProvider transport={transport} workspaceId={workspaceId}>
      <EliKnowledgeGraph
        limit={200}
        allowCreate
        labels={{ title: "Concepts", create: "Add concept" }}
        onEntitySelect={(entity) => track("concept.open", entity.id)}
        onDocumentSelect={(documentId) => openDocument("/documents/" + documentId)}
        onError={(error) => reportError(error)}
      />
    </EliProvider>
  );
}

There is no component for the manifest or for relation writes. Both are one hook away — the same generic hooks the packaged components are built on work with any graph-client method and your own markup.

import { createGraphClient } from "@eli-ai/client/graph";
import { useEliQuery } from "@eli-ai/react/hooks";
import type { WorkspaceManifest } from "@eli-ai/contracts/graph";

export function HubConcepts() {
  const manifest = useEliQuery<WorkspaceManifest>(
    "graph.manifest",
    (context, signal) =>
      createGraphClient(context.transport).manifest({
        signal,
        ...(context.workspaceId ? { workspaceId: context.workspaceId } : {}),
      }),
  );

  if (manifest.isLoading) return <p>Loading…</p>;
  if (!manifest.data) return null;

  return (
    <ol>
      {manifest.data.hubConcepts.map((concept) => (
        <li key={concept.id}>
          {concept.name} · in-degree {concept.inDegree} · {concept.authority}
        </li>
      ))}
    </ol>
  );
}

HTTP API

Nine operations across six paths. Every request carries a Bearer key; see Authentication. Examples use https://eli.ai, whose apex 308-redirects, so -L is included on every non-GET example. A resource in another workspace is invisible under row-level security and comes back as 404, never 403.

curl -s "https://eli.ai/api/v1/entities?limit=25&type=system" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "entities": [
    { "id": "01KY0ZW3B8AVDR67NXSE96P81N", "name": "Order Platform", "type": "system", "pagerank": 0.0421 },
    { "id": "01KY10DDDDDDDDDDDDDDDDDDDD", "name": "northwind-ops", "type": "system", "pagerank": null }
  ],
  "total": 27,
  "limit": 25,
  "offset": 0
}

curl -L -X POST https://eli.ai/api/v1/entities \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Fulfillment Console","type":"system","aliases":["fulfillment-console"]}'

{
  "id": "01KY10KKKKKKKKKKKKKKKKKKKK",
  "name": "Fulfillment Console",
  "type": "system",
  "nameNorm": "fulfillment console",
  "origin": "manual",
  "description": null,
  "aliases": ["Fulfillment Console", "fulfillment-console"]
}

curl -s https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY"

{
  "id": "01KY0ZW3B8AVDR67NXSE96P81N",
  "name": "Order Platform",
  "type": "system",
  "nameNorm": "order platform",
  "origin": "extraction",
  "description": "Core order intake and fulfillment system.",
  "aliases": ["order-platform", "OP"],
  "curation": {
    "authority": "curated",
    "lifecycleStatus": "published",
    "ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
    "stewardIds": [],
    "version": 4,
    "lastReviewedAt": "2026-05-02T10:14:00.000Z",
    "nextReviewAt": "2026-11-02T10:14:00.000Z",
    "supersededBy": null,
    "sourceRefs": [{ "label": "Service catalogue", "url": "https://intranet.example.com/catalogue" }],
    "editorialNote": null
  }
}

curl -L -X PATCH https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"service"}'

{
  "id": "01KY10KKKKKKKKKKKKKKKKKKKK",
  "name": "Fulfillment Console",
  "type": "service",
  "nameNorm": "fulfillment console",
  "origin": "manual",
  "description": null,
  "aliases": ["Fulfillment Console", "fulfillment-console"]
}

curl -L -X DELETE https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10KKKKKKKKKKKKKKKKKKKK" }

curl -s "https://eli.ai/api/v1/entities/$ENTITY_ID/neighborhood?depth=2&perHopCap=10" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "entity": {
    "id": "01KY0ZW3B8AVDR67NXSE96P81N",
    "name": "Order Platform",
    "type": "system",
    "aliases": ["order-platform", "OP"],
    "mentionCount": 42,
    "topRelations": ["Order Platform —depends_on→ northwind-ops"],
    "docIds": ["01KY10AAAAAAAAAAAAAAAAAAAA"],
    "authority": "curated",
    "lifecycleStatus": "published"
  },
  "nodes": [
    {
      "id": "01KY10DDDDDDDDDDDDDDDDDDDD",
      "name": "northwind-ops",
      "type": "system",
      "aliases": [],
      "mentionCount": 18,
      "topRelations": ["Order Platform —depends_on→ northwind-ops"],
      "docIds": ["01KY10AAAAAAAAAAAAAAAAAAAA"],
      "authority": "machine_extracted",
      "lifecycleStatus": "published"
    }
  ],
  "edges": [
    {
      "src": "01KY0ZW3B8AVDR67NXSE96P81N",
      "type": "depends_on",
      "dst": "01KY10DDDDDDDDDDDDDDDDDDDD",
      "mentionCount": 7
    }
  ],
  "truncated": false
}

curl -L -X POST https://eli.ai/api/v1/relations \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"srcEntityId":"01KY0ZW3…","dstEntityId":"01KY10KK…","type":"depends_on"}'

{
  "relationId": "01KY10MMMMMMMMMMMMMMMMMMMM",
  "affectedCanonicalIds": ["01KY0ZW3B8AVDR67NXSE96P81N", "01KY10KKKKKKKKKKKKKKKKKKKK"]
}

curl -L -X DELETE https://eli.ai/api/v1/relations/$RELATION_ID \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10MMMMMMMMMMMMMMMMMMMM" }

curl -s https://eli.ai/api/v1/manifest \
  -H "Authorization: Bearer $ELI_KEY"

{
  "generatedAt": "2026-07-21T09:15:00.000Z",
  "workspace": { "id": "ws_01KY0Z00000000000000000000", "name": "Northwind Ops" },
  "counts": {
    "documents": 128,
    "chunks": 3410,
    "entities": 743,
    "relations": 1289,
    "entitiesByType": { "system": 41, "metric": 22, "policy": 17 },
    "relationsByType": { "governed_by": 58, "owned_by": 44 },
    "byAuthority": { "machine_extracted": 601, "asserted": 92, "curated": 38, "certified": 12 },
    "byLifecycle": { "draft": 4, "pending_review": 2, "published": 724, "deprecated": 9, "superseded": 4 },
    "documentsByVerification": { "unverified": 96, "verified": 24, "certified": 6, "deprecated": 2 }
  },
  "hubConcepts": [
    {
      "id": "01KY0ZW3B8AVDR67NXSE96P81N",
      "name": "Order Platform",
      "type": "system",
      "summary": "Core order intake and fulfillment system.",
      "authority": "certified",
      "lifecycleStatus": "published",
      "version": 6,
      "inDegree": 31,
      "outDegree": 12,
      "mentionCount": 87,
      "lastReviewedAt": "2026-07-14T10:02:11.000Z",
      "ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z"
    }
  ],
  "staleness": { "overdueReviews": 3, "neverReviewed": 640 }
}

Data elements

Atlas owns ten tables. Every one of them carries a workspace_id column and a tenant-isolation row-level-security policy that constrains both reads and writes to the workspace of the current transaction, so a cross-workspace id is simply not visible rather than forbidden. Ids are ULID strings.

Atlas also reads two tables it does not own: documents (for the ACL columns and to resolve docIds) and chunks (referenced by mentions and evidence). Three more Atlas-adjacent tables exist but have no v1 endpoint on this page — merge_log, extraction_runs, and rejection_tombstones.

Feature map

Six feature areas make up the module. Each names the concrete modules and tables that deliver it, and those names reappear in the code map and internals below, so every claim on this page is traceable to the code that enforces it.

System architecture

The topology separates the write side (manual curation, extraction, merges) from the serve side (pure SQL reads) with canonical_relations as the hinge between them. Rectangles are API routes and services, cylinders are tables, and the one rounded node is the only model call in the module — extraction on the write side. Nothing on the serve side calls a model.

Where the logic lives

The code map is the module boundary in file terms. Every path is real; table names are stated in the notes because tables are defined in the schema module, not in files of their own.

Primary runtime flow

The highest-value read is the neighborhood expansion — it exercises canonicalization, the rollup, the caps, and the ACL in one request. Message labels use the operation names from the HTTP API section above.

Internals and invariants

Canonical concepts and aliases

An entity's identity is its normalized name — NFKC, whitespace-collapsed, lowercased — computed by normName. A manual create registers the display name and every alias as alias rows, which is how later ingestion reuses the concept instead of duplicating it. Deletes are soft: the row keeps its id, and the serve side excludes it.

• Invariant — Normalized-name uniqueness across live, unmerged entities: a colliding create is a 409 carrying the existing id, enforced in src/server/graph/manual.ts.
• Invariant — Only multi-token or six-plus-character normalized names may become cross-document aliases, so short speaker labels cannot fabricate structure, enforced by isAliasEligible in src/server/graph/shared.ts.

Typed relations with evidence

A relation is a directed triple that must connect two live entities. When the relation type declares domain or range constraints, the endpoints' entity types are checked on write. Re-asserting an existing triple promotes it rather than erroring, which makes the endpoint safe to replay.

• Invariant — Domain and range constraints reject a violating manual write with a 400 naming the offending side; extraction skips and counts the same violations, enforced by src/server/graph/constraints.ts.
• Invariant— Relation writes and deletes rebuild the canonical rollup for both endpoints' heads in the same operation, so reads never see a stale edge, enforced through src/server/graph/manual.ts.

Serve-time reads

Reads never traverse raw relations. Cards and frontiers come from canonical_relations, hydrated with aliases, mention rollups, and rendered top-relation sentences; the thin list joins persisted PageRank. All of it is short workspace transactions of plain SQL.

• Invariant — Soft-deleted, draft, and pending-review concepts are never served on cards or frontiers, and neither are edges to them, enforced by the serving-exclusion predicate in src/server/graph/query.ts.
• Invariant— An entity with document mentions is readable only when at least one of those documents passes the caller's content ACL, enforced in src/server/graph/query.ts via src/server/authz/content-acl.ts.
• Invariant— The list endpoint's pagerank comes only from the persisted layout version selected by workspace_meta, never computed inline, enforced in src/server/query/entities.ts.

Merge resolution and canonical rollup

A merge is a pointer plus a transactional recompute: merged_into is set, canonical ids are recalculated for the source cluster, aliases are repointed and tagged with the merge id, and the rollup is rebuilt for both heads. Unmerge reverses every step from the merge_log row.

• Invariant — Merges are cycle-guarded and non-destructive: every step is recorded and invertible, so unmerge restores the exact pre-merge graph, enforced in src/server/graph/resolution.ts.
• Invariant — canonical_relations is repaired by delete-and-reinsert closed under one predicate for the touched heads, aggregating mention counts with bounded evidence samples, enforced by rebuildCanonicalForIds in src/server/graph/shared.ts.

Extraction and graph analytics

Extraction runs per document from queued jobs: the model proposes entities and relations, deterministic wikilink and co-occurrence lanes add structure without a model, and every mention lands with character offsets so provenance is exact. Analytics computes PageRank and communities in memory after one short read and persists them as a new layout version.

• Invariant — Every extracted fact carries locatable provenance — mention and evidence rows store the document, chunk, and offsets, written by src/server/graph/extraction.ts.
• Invariant— Rejected extractions leave tombstones so a re-run cannot resurrect a curator's rejection, enforced via the tombstone signatures in src/server/graph/shared.ts.

Workspace manifest

The manifest is one read: corpus and graph counts, distributions by type, authority, lifecycle, and verification, hub concepts ranked by directed in-degree over the canonical graph, and staleness counters. Only published concepts are hub-eligible.

• Invariant — Hub concepts are computed over canonical_relations restricted to live, published entities, enforced in src/server/graph/manifest.ts.

For a self-hosting team the safe extension points are the ontology and the read facade: register entity and relation types (with domain and range constraints) rather than forking the writers, drive writes through the plugin data facade so constraints and ACLs still apply, and re-run analytics on your own cadence — a new layout version swaps in atomically. The normalized-name identity, the canonical rollup, and the serving-exclusion rules are load-bearing and not configurable.

How it composes

Atlas is usable on its own, and every other module that touches the graph does so through the same tables and the same serve-time functions this page documents.

• Intake — the biggest gain. With documents in the workspace, extraction writes entities, aliases, relations, mentions, and evidence for you, and the fields that are empty in a hand-built graph fill in: mentionCount, docIds, edge mentionCount, and the manifest's document and chunk counts. Without it, nothing breaks — you author the graph through POST /entities and POST /relations.
• Warrant — required for governance writes. The authority and lifecycle_status columns live on the Atlas entities row and Atlas serves them on every card and in the curation block, but Atlas has no endpoint to change them. Certifying, setting an owner, stamping a review, deprecating, the revision history endpoint, change requests, and the SKOS export are all Warrant. Without Warrant the defaults hold — manual creates are asserted, extraction is machine_extracted, everything is published — and the serving rules above still apply.
• Lineage — reads Atlas from the document side: which concepts a document produced, and how many live relations its evidence grounds. It needs documents, so it is meaningful only alongside Intake.
• Lens — the retrieval pipeline's graph-fusion stage calls the very same frontier expansion this module exposes, to surface evidence that is structurally rather than textually related. Atlas does not need Lens; Lens gets materially better with a populated Atlas. See Retrieval pipeline.
• Conduit — binds a governed live query to an entity id or to an entity type, so Atlas is the addressing scheme for live data. The binding rows live in Conduit's table and reference Atlas ids; Atlas itself neither reads nor needs them.
• Crucible — grades concept recall against entity ids on golden items. Optional, and evaluation-only.
• Ports — exposes the same reads over MCP (kb_entity_lookup, kb_entity_get, kb_graph_query, and the eli://workspace/manifest resource) for agents that speak that protocol instead of REST. Same server functions, different envelope.