Conduit

Conduit is the data module — capability area data, labelled Conduit (data) in the capability catalog. A workspace registers scoped, read-only connectors (PostgreSQL, MySQL, Snowflake) and a set of named queries: human-authored, single-statement SQL templates with typed parameters. Callers pick a query by slug and supply parameter values; they never supply SQL.

Every execution is checked against a read-only statement policy, capped by the connector's maxRows and timeoutMs, and recorded as an append-only data_calls row. The id of that row comes back as dataCallId — the anchor a [Dn] citation points at. Separately, a query can be bound to a graph entity or entity type, which is what lets other modules resolve "the current numbers for this thing" without anyone writing SQL at answer time.

Use it standalone

Conduit's public surface is three HTTP operations and one React component. Adopting it needs no documents, no knowledge graph, no embeddings, and no chat model.

React components

@eli-ai/react/data exports exactly one component, EliLiveData, plus its two label/prop types (EliLiveDataProps, EliLiveDataLabels). There is no separate connector-management or binding-editor component in the package.

EliLiveData

A single surface that loads the workspace's connectors and named queries on mount, renders the connectors as badges (the package's positive tone when enabled, neutral otherwise), and renders a form with a query select, a JSON textarea for parameters, and a submit button. Options for disabled queries render but are non-selectable, and each option is labelled title (falling back to slug) followed by its connector name when that connector is in the list. On success it renders a results table with the returned columns as headers, plus badges for rowCount, durationMs, and a "Truncated" badge when the row cap was hit. Cells that are objects or arrays are JSON-stringified; null and undefined render as an em dash.

The component issues one data:read call per list on mount and one data:run call per submit. The parameter textarea starts at {} and must parse to a JSON object: invalid JSON reports "Parameters are not valid JSON." and a JSON array or null reports "Parameters must be a JSON object." — both inline, before any request is made.

HTTP API

Three operations, all under /api/v1/data. Failures use the shared envelope { "error", "message" }; a body that fails validation adds an issues array. Because the apex 308-redirects, pass -L on the non-GET call so curl replays the POST body.

config is the non-secret connection shape for that kind: Postgres and MySQL carry host · port · database · user (plus sslMode or ssl); Snowflake carries account · database · warehouse · user (plus optional schema and role). schemaSnapshot, when present, holds the discovered tables with their columns (name · dataType · nullable) and a nullable rowEstimate.

Each entry in params declares name, a type of string | number | boolean | date, and optionally required, default, and description. Order is meaningful: the executor binds params[0] to $1, and so on.

truncated is true when the connector's maxRows cap clipped the result — the rows you received are a prefix, not the whole answer. Data-layer failures map their code to a status:

• 404 query-not-found — no query with that slug or id; connector-not-found— the query's connector row is gone.
• 409 connector-disabled — emitted when either the query or its connector has enabled: false. The message names which one.
• 400 invalid-params — a missing required param or a value that will not coerce to its declared type; not-read-only — the stored template failed the statement gate.
• 502 execution-failed and 504 timeout — the external engine errored or exceeded timeoutMs.
• 401 unauthorized; 403 insufficient_scope or insufficient_capability; 400 invalid_json / invalid_body from the shared gate.

Data elements

Four tables. All four are workspace-scoped and carry a row-level-security policy keyed on workspace_id for every operation, so a query outside the workspace transaction context returns nothing — the API's scope check and RLS are two independent gates.

How it composes

Conduit runs entirely on its own for the slug-and-params use case. What the other modules add is binding — the ability to go from a thing in the graph to the live numbers about it without a caller knowing which query to run.

With Atlas — bindings become available

entity_bindings resolves against entity rows: a binding matches either the entity's id or its type, and a lookup for one entity returns its direct bindings plus the ones inherited from its type. Without Atlas there are no entities to bind to, so the binding table stays empty and the param_map source entity_name has nothing to resolve. Everything in the three v1 routes still works unchanged — those never touch bindings.

With Lens — live rows join the cited answer

POST /api/v1/query takes an includeData boolean. When true, the pipeline resolves bindings for the entities it detected in the question, executes those whose params fully resolve without a model source, and returns them as dataCalls — each entry carrying id · dataCallId · connectorName · queryTitle · rowCount · executedAt. It is capped at three data calls per answer, a per-binding failure never blocks the document-grounded answer, and that route gates on agents:run and needs a configured chat model — both things Conduit alone does not. See Lens.

With Warrant — data evidence can overturn an abstain

In the same pipeline, a retrieval-floor verdict of abstain_with_pointers is overridden to proceed when live data actually ran, and the override is recorded on the decision. That is a Warrant policy behaviour reacting to Conduit evidence; it does not exist if you use Conduit by itself.

With Ports — two MCP tools

The MCP server exposes kb_data_discover (accepts data:read or data:run) to list the bindings that apply to a named entity along with the params the caller still has to supply, and kb_data_lookup (requires data:run) to execute one, selected by bindingId or bindingLabel. Omitting both works only when exactly one binding applies. Both mirror the REST scope map rather than bypassing it, and the lookup returns the same eight fields as the run endpoint. See Ports.

With Lineage — the [Dn] trail

data_calls is the provenance substrate a Lineage trace follows for a live figure, the way a document chunk backs an [Sn] citation. Conduit writes those rows unconditionally, so the trail exists whether or not you have adopted the module that reads it.