The Ontology Agent (source onboarding)

Route: /sources/onboard · File: app-source-onboarding.jsx · Public explainer: knowledge.html#agent · Technical: docs.html#onboarding

The idea

Adding a source was traditionally a two-specialist job: a Connector Engineer wires the feed and maps its fields, and a Canonical Model Steward decides how those fields become entities/events without forking the schema. The Ontology Agent compresses both into one guided, chat-driven flow. You drop a source — URL, API spec, sample payload, file, or catalog pick — and the agent profiles it, drafts the connector, drafts the field→Observation mapping, proposes which entity/event types it maps onto (reusing existing ones where possible), proposes resolution keys, and dry-runs the result against a live sample. It drafts; a human commits.

Doctrine Q9 — agent-drafted, human-committed

The agent removes the labour of onboarding, not the judgement. The canonical model is the shared contract every project depends on, so it's treated like a protected branch: the agent opens the "pull request," a human (the Steward) merges it. Every proposed connector, mapping, new type, and resolution rule is presented as one reviewable diff, approved with who/when in the audit log. Q9 is the extension of Q8 ("AI supports, never decides") into the data layer.

The 8-stage wizard

A two-pane surface: agent conversation (left) + the staged artifact with approve / edit / reject (right), and a 0–7 stepper. Seeded with the Spire satellite AIS worked example so it's demoable immediately.

Stages 0–7 are an org-layer capability (make a source exist and be trustworthy); stage 8 is the existing project-layer connect (decide to use it).

Automated vs. human-gated

• Agent drafts: protocol/field detection, unit·timestamp·geo normalization, connector + health probe, field→Observation mapping, proposed resolution keys & thresholds, dry-run replay with conflict/dedup detection, and reuse suggestions (anti-fork).
• Human only: committing a new entity/event type (Steward, Q9), supplying credentials/classification (Admin), merging two entities in the review band (analyst/Steward), connecting a source into a project (Project Lead).

Anti-fork

The biggest risk of many sources is schema sprawl — 50 feeds inventing 50 near-duplicate "vessel" types. At stage 4 the agent embeds the source's concepts, matches them against existing types, and defaults to reuse; new types are proposed only when fit is poor, as the minimal covering type, with near-neighbours shown. Every accepted change is a versioned ontology_diff in the audit log.

The chat in-progress gate (best-practice UX, not suppression)

The global analyst chat is available on the onboarding surface (the wizard reserves space via --chat-pad-right so there's no overlap). The wizard persists progress (localStorage('insigz-onboarding-state')) and publishes an in-progress flag (insigz-onboarding-active). If you ask the chat to onboard a source while one is already underway, it doesn't blindly relaunch — it replies that an onboarding is in progress and shows a gate widget with two actions:

• Continue where I left off → (navigates to the wizard, state restored)
• Start over (discard draft) (clears the persisted state via an insigz:onboard-reset event, then navigates)

Guardrails (summary)

• Q9 gate — no canonical-model change without Steward approval of the diff.
• Grounded onboarding — the agent works from a real sample; the dry-run is mandatory before the gate.
• No silent merges — review-band identity decisions go to a human queue (a merge-review alert).
• Full provenance — source_native + signature + classification on every Observation; every proposal and approval in the audit log.
• Secrets out-of-band — the connector references a secret, never contains one.

Responsiveness

The wizard is fully responsive: on mobile the two panes stack with an AGENT / ARTIFACT toggle, the stepper scrolls horizontally, and the decision bar clears the chat bubble.