The ontology is proposed from the open graph and judged by its questions: cut 1 by WaylandYang · Pull Request #947 · deeplethe/utopia · GitHub
Skip to content

The ontology is proposed from the open graph and judged by its questions: cut 1 - #947

Merged
WaylandYang merged 2 commits into
devfrom
feat/ontology-agent-cut1
Sep 26, 2026
Merged

WaylandYang merged 2 commits into
devfrom
feat/ontology-agent-cut1

Conversation

@WaylandYang

Copy link
Copy Markdown
Contributor

ADR 0061 cut 1 (the ADR landed in #945).

What a base gains

  • Competency questions are rows: competency_questions (migration 0077), written by a person, accepted on arrival, retirable. GET/POST /kbs/{id}/questions, PATCH/DELETE /kbs/{id}/questions/{qid}.
  • An ontology agent reads the phrase signatures alignment decided bind to nothing (none / undecided) and the kind words with no class, against the glossary and the accepted questions, and proposes classes and properties with a definition, the shapes they would bind and the questions they serve. Prompt and parsing live in utopia-extract::ontology_agent (unit-tested); the job propose_ontology in the server batches twelve shapes plus up to six kind words a call, glossary once per batch, at most 120 shapes a round, one run per base at a time.
  • Proposals land in ontology_proposals beside Suggest's, with proposed_by = 'agent', serves (question ids) and signatures (the shapes). Shapes already proposed, whatever their status, are not offered again. GET /ontology/proposals carries the new fields; POST /ontology/proposals accepts a reason on reject.
  • Adoption (POST /ontology/proposals/adopt, with optional edits to label / description / datatype / domains / ranges / parents) writes the element through the store calls the editor uses, marks the proposal adopted, and enqueues align_types or align_phrases so the shapes re-decide on their 0053 fingerprints. Nothing is adopted automatically (0012).
  • Trigger: alignment enqueues the agent (60 s debounce) when it settles with ≥ 20 unbound shapes. POST /ontology/propose asks on demand.
  • Web: "Ask the agent" on the misses page (polls for the result), agent chip / definition / shapes / kind words / served-questions on each proposal, Reject with an optional reason, and a competency-questions panel.

Tests

  • utopia-extract: prompt lists shapes, glossary and questions; lenient parse; ids outside the batch or binding nothing are malformed.
  • utopia-server::ontology_agent: scripted model; an unbound shape becomes a proposal serving a question; a second round makes no model call; adoption builds the property with the proposal's domain/range and the person's label, marks the proposal, enqueues alignment; a decided proposal cannot be adopted again; an existing key or a proposal binding nothing is dropped; a literal-valued property lands in attribute_types with datatype defaulting to text.
  • Store, alignment and proposal suites still pass; pnpm build and vitest pass.

Cuts 2 (regression cases), 3 (measurement by questions) and 4 follow.

🤖 Generated with Claude Code

WaylandYang and others added 2 commits September 26, 2026 14:58
…ons: cut 1

ADR 0061 cut 1. A base can say what it is for: competency questions are
rows (`competency_questions`, migration 0077), a person writes them and
they are accepted on arrival. An ontology agent reads the phrase
signatures alignment decided bind to nothing and the kind words with no
class, against the glossary and the accepted questions, and proposes
classes and properties with a definition, the shapes they would bind and
the questions they serve. Proposals land in `ontology_proposals`
(`proposed_by = 'agent'`, `serves`, `signatures`) beside Suggest's;
shapes already proposed are not offered again. Adoption writes the
element through the same store calls the editor uses, marks the
proposal, and enqueues alignment so the shapes re-decide on their 0053
fingerprints. Rejection records a reason. Alignment calls the agent when
it settles with twenty or more unbound shapes; the ontology page has
"Ask the agent", the agent's fields on each proposal, Reject, and a
competency-questions panel.

Batches are twelve shapes plus up to six kind words per call with the
glossary once per batch; a round is capped at 120 shapes. Nothing is
adopted automatically (0012).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Wayland Yang <wayland0916@gmail.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Wayland Yang <wayland0916@gmail.com>
@WaylandYang
WaylandYang merged commit b07af8f into dev Sep 26, 2026
@WaylandYang
WaylandYang deleted the feat/ontology-agent-cut1 branch September 26, 2026 07:04
WaylandYang added a commit that referenced this pull request Sep 26, 2026
…ology becomes a proposal: 0061 cut 1.1 (#950)

* The agent remembers what it has seen, and "already in the ontology" becomes a proposal

ADR 0061 cut 1.1, from the first real round (bench4, 100 documents, #947):
120 shapes went to the model, 35 came back in proposals, and the other 85
had no record, so the next round would have offered the same shapes first
and spent seven tenths of its tokens on them. The shapes with the most
statements (died in, wrote, directed, is in) were answered as "the
ontology already has this" (placeOfDeath, author, director, locatedIn),
and cut 1 dropped that answer.

Every shape offered is now recorded in `ontology_agent_reviews`
(migration 0078) with its outcome: proposed, existing or declined, and
the glossary fingerprint it was judged against. Proposed shapes are never
offered again; existing and declined ones return when the glossary
changes. An "existing" answer is saved as a `map_to` proposal with the
property, the direction the shape reads it in, and the shapes; adopting
it writes a person's binding per shape (the same call as the review
queue) or classes each kind word, and enqueues the projection. The prompt
asks for the direction and says not to propose the inverse of an existing
property. The ontology page shows the agent's map_to items with their
shapes and a Reject.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Wayland Yang <wayland0916@gmail.com>

* Direction belongs to the shape, a declined shape returns when its statements double, and adoption embeds the element

Three more things the real base showed (bench4, rounds 2 and 3):

Two answers for one existing property in two rounds overwrote each other
(p1056 lost "was long a center of" to "continued to produce"), and the
direction they disagreed on was per shape, not per property. A map_to
row now merges across rounds and each shape carries its own direction;
adoption reads it per shape.

Re-offering declined shapes whenever the glossary changed would resend
every declined shape after every adoption (165 shapes, a dozen calls).
Alignment already re-decides unbound shapes against a new element on its
0053 fingerprint, so the agent has nothing to add there. A declined shape
now returns only when its statement count has doubled since it was seen.

An adopted property never entered the alignment shortlist: the shortlist
is picked by vector when a shape has many structural candidates, and a
new element has no vector until something refreshes the index. Adoption
now refreshes the ontology index before enqueueing alignment. On the
bench base this bound the adopted `houses` and four neighbouring
phrasings within a minute, and caught up the five "is bordered to the …
by" shapes left unbound by the earlier `bordered_by` adoption.

Also: map_to items carry the target's label, the page no longer shows
0003's "reclassifies N facts" on agent items, and "Add all" counts only
Suggest's proposals (an agent proposal is signed one at a time, 0012).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Wayland Yang <wayland0916@gmail.com>

* ADR 0061 and the index record cut 1.1 (#950)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Wayland Yang <wayland0916@gmail.com>

---------

Signed-off-by: Wayland Yang <wayland0916@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant