Corveil Docs

Appearance

Ontology Concepts — Hydration, Extraction & Synthesis ​

A short guide to the knobs on the Type Registry and Sensor Bindings screens. These fields decide which entities your sensors produce and how much LLM work that costs. This page explains each one in plain terms.

Corveil ships a default schema of entity and link types, but the registry is yours to shape: you can turn types off, add your own, and tune how much LLM work each one is worth. The settings below are how you do that. New to sensors? Start at All Sources — a sensor is what feeds raw activity into the graph in the first place.

Hydration: deterministic vs LLM ​

Hydration is how a sensor turns a raw signal (a GitHub push, a meeting transcript, a Slack message) into entities in your knowledge graph. Every sensor binding picks one of two modes:

ModeWhat happensCostExample
deterministicThe sensor's mapper reads structured fields and emits the entity directly. No LLM is involved — it's exact and free.NoneGitHub push → Repository (the repo name is already in the event metadata)
llmA guided extractor calls an LLM to pull entities out of free text.Tokens (gated — see below)A meeting transcript → Decision (the decision only exists as prose)

Use deterministic whenever the entity is already present as a structured field — it's instant and costs nothing. Use llm only when the entity is buried in natural language and there's no structured field to read it from.

LLM-mode bindings don't run unconditionally. Each LLM extraction is gated by the target type's synthesis policy (the next two settings), so a binding can be set to llm and still skip the call when the policy says it isn't worth it.

Type Registry settings ​

Each entity/link type carries a small policy that the hydration and synthesis passes read at runtime.

Extractor enabled ​

Whether hydration emits this type at all.

  • On (default for new types) — the type appears in extraction and bindings can hydrate it.
  • Off — the type is hidden from the extractor. Existing entities are kept; the type simply stops being produced. Use this to retire a type without deleting it (built-in types can't be deleted, only hidden this way).

Synthesis enabled ​

Whether the knowledge layer writes a synthesized per-entity page for this type — a generated summary that reads across the events linked to each entity. This is cost-bearing LLM work.

  • Custom types default to OFF — synthesis is opt-in. A new custom type is extracted (if its binding fires) but won't generate per-entity summaries until you turn this on.
  • Turn it on only for types where a written summary is worth the token cost (e.g. Project, Person), and leave it off for high-volume, low-value types (e.g. Commit, Message).

Synthesis min content (bytes) ​

A cost gate. The minimum size (in bytes) of an event's content before synthesis — and guided-LLM extraction for this type — will run. Trivial events below the threshold are skipped so they never trigger an LLM call.

  • 0 (default) — any content qualifies.
  • A non-zero value (e.g. 200, roughly a paragraph) — only events with enough text get the expensive treatment. Built-in types like PullRequest ship with a small threshold for exactly this reason.

Cost at a glance ​

For an LLM-mode binding to actually spend tokens on a target type, all of these must hold:

  1. The binding's hydration mode is llm (deterministic never calls an LLM).
  2. The target type's synthesis is enabled.
  3. The event's content is at least synthesis min content (bytes) long.

If any one is false, the work is skipped and no tokens are spent. That's why a brand-new custom type is safe by default: synthesis is off, so its LLM-mode bindings stay quiet until you explicitly opt in.

Composing your own schema ​

The three settings above are per-type, so composing a schema is just a matter of deciding, type by type, whether it is produced (extractor enabled) and whether it is worth summarizing (synthesis enabled, gated by the byte threshold). Add the types your organization actually reasons about, point bindings at them, and leave synthesis off until a written per-entity summary earns its token cost. The defaults are deliberately cheap; you opt into spend one type at a time.