Building Reasoning Ontologies from Scratch: OntoL Auto Workshop Step-by-Step Guide

Overview

This manual (OntoL-Manage · Ontology Management · Auto Workshop v1.0, updated 2026-11-02) provides a step-by-step guide for practitioners to build a draft ontology that can reason and produce conclusion cards. All operations are performed within the /auto-manage page.

Prerequisites

Account permissions: auto-manage:edit for modelers; approvers additionally need auto-manage:approve.

Data sources configured: In Data Management → Data Source, table catalog must have source fields selected ( selected=true).

Model configured: At least one available chat model in LLM configuration.

Reasoning engine available: Memgraph connected; sandbox reasoning relies on replica space.

Step 1: Enter the Page

Path: left menu → Ontology Management → Auto Workshop. First entry shows empty iteration list with only a + button. URL pattern: /auto-manage?tree_id=<sessionID>&type=0. Shareable with colleagues who have permissions and own the session. Page layout: left iteration list, middle-top reasoning results (three tabs) + middle-bottom dialog, right current version details.

Step 2: Create Iteration (Choose Correct Mode)

Click + to open "New Ontology Iteration" dialog. Mode selection is critical because wrong choice prevents reusing existing asset IDs.

Auto Add (type=0): For building from scratch. Badge shows "Auto Add"; drafts can freely create new codes.

Auto Modify (type=1): For extending/modifying existing formal ontology. Requires selecting formal asset type (Entity Ontology / Feature Ontology) and searching asset by name/code. System reads the formal asset and derives a personal draft without modifying formal data.

Uncertain: Start with Auto Add; if later need to modify formal asset, create a separate iteration with Auto Modify. Both iterations have independent replicas.

Step 3: Write the First Prompt

The first prompt determines the agent's planning quality. Provide in one go: business object, business questions, data sources, and expected judgment criteria.

Recommended Prompt (Complete Information)

Based on data source [SalesDB], build an ontology for order fulfillment that can answer:
1) Which orders this month are overdue and not shipped;
2) Which customers have concentrated overdue orders;
3) Total amount of orders overdue more than 7 days.
Existing tables: orders, customers, shipments. Overdue definition: ship date < today AND not shipped.

Not Recommended Prompts & Improvements

"Help me build an ontology" → Missing business object & questions; agent produces empty shell. Fix: Add business object + 3-5 business questions.

"Turn all tables into entities" → Creates entities for views, dictionary tables, log tables, violating entity-layer semantics. Fix: Specify core business objects; let agent trim the rest based on questions.

"You query the database yourself" → Out-of-scope; product does not support direct SQL/query. Fix: "Bind data source, let reasoning engine fetch data during reasoning."

Step 4: Inspect Draft & Fields

After agent generates draft, "Ontology Draft" tab auto-refreshes with entity-relationship canvas; right panel "Ontology Draft Assets" lists field and relationship counts per draft.

Canvas auto-layout by hierarchy: entities left, downstream ontologies right;

R_SUBCLASS_OF</sub> arrows auto-reverse to avoid inheritance direction confusion.</li><li>Click canvas node → right inspector expands field list: custom fields editable; system fields (<code>ontoL_

prefix) collapsed, only default value editable.

Each field shows code, type, length, decimals, required, unique, format, default, description — missing items visible at a glance.

Canvas top-right "Fit Canvas" / "Zoom" for large diagrams; press Esc or click overlay to exit zoom.

Step 5: Add Fields & Relationships

Two methods, can mix:

Dialog (recommended for batch): Add multiple fields, modify formulas, connect multiple relationships at once. Example: "Add credit_level and industry_classification fields to customer table; credit_level as enum."

Inspector (recommended for fine-tuning): Single-field adjustments of length, required, unique, validation rules. Click field → edit → save; system fields only allow default value change.

Relationship maintenance handled by agent's manage_draft_relation, supports standard R_* and custom Chinese semantic relations; inheritance and containment cannot be mixed on same edge. Each edge can have pre-execution constraint ( ontoL_condition) and execution action ( ontoL_execution).

Step 6: Bind Data Sources

No source = reasoning gets no real data = only answers "not retrieved". Two binding methods:

Dialog: "Bind dynamic sources for Order, Customer, Shipment entities per data source [SalesDB], using order_no and customer_code as identity filters."

Auto-bind: "Use auto_bind_dynamic_sources to auto-bind per table catalog" — suitable for many tables with standardized naming.

Checkpoints: Entity must have identity filter (name/code/description); whole-table fetch then guess object not allowed; list-type data must enable multi_instance. Binding result visible in draft details as ontoL_db_dynamic_source config summary.

Step 7: Load Data

Click "Load Data" on toolbar: copies current draft snapshot into session sandbox replica — only nodes and edges, no reasoning. Purpose: give "question retrieval" a graph to query, and provide base for subsequent "re-reasoning".

Common Phenomena & Handling

No replica info after click: Draft has no assets or no copiable nodes → confirm draft list non-empty.

Question answers "not retrieved": Replica empty or nodes not loaded → click "Load Data" again.

Modified draft after load: Replica remains old snapshot → use "Re-reason" not "Reason Again".

Step 8: Reason & Read Cards

In toolbar select "Ontology Draft Assets" → click "Re-reason". Dialog shows reasoning step indicator; on completion, logs and cards tabs auto-refresh.

Tabs & Interpretation

Reasoning Log: Event stream, error lines highlighted red. Check for errors in data fetch, DSL validation, cloning, per-edge judgment.

Reasoning Cards: One card per edge: source → relation → target + pass/block. Pass = edge condition satisfied; Block = condition not satisfied or cascaded block.

Right Replica: Sandbox replica ID & status. Success = 02 Reasoned; blocks exist = 04.

When card data missing, correct action: add fields/sources then re-reason; do not ask agent to change fetch method; card conclusions are final — do not replace with model-computed numbers.

Step 9: Self-Test & Coverage

In dialog ask "self-test" or "check coverage". Agent executes sequentially: self_test_questions (per-question check data fetch & linked fields) → audit_ontology_coverage (question–business table/field match matrix) → verify_ontology_chain (chain self-check) → finalize_task_report (summary).

Report Items & Actions

Field match x/y (%): How many fields involved in question are mapped to draft. Action: If <100%, add missing fields.

Missing tables/fields: Tables hit by question but no entity created; columns not mapped. Action: Add entity or field then re-run.

Empty feature ontology: Feature ontology with 0 business fields → formula cannot fetch data. Action: Add fields or delete draft.

Self-test attempt 1/3: Same task max 3 retries. Action: 3rd failure reports reason, does not claim pass.

Step 10: Submit for Approval

After confirming draft, reasoning, self-test meet expectations: in "Ontology Draft Assets" select one item → click "Submit for Approval" → confirm dialog. Submits current draft snapshot, not live draft.

Scenarios

Existing pending record: Refreshes that record snapshot and logs resubmitted event; no duplicate ticket.

Continue editing after submit: Approval fingerprint mismatch → auto-set to "Content Changed", must resubmit.

Approved: Written to formal asset (new v1 or update v2…), appears in /audit-log.

Rejected: Formal asset unchanged, draft retained; modify per rejection reason and resubmit.

Tip: Submit one draft at a time. Multiple drafts in batches for approver to verify field snapshots individually.

Step 11: Approver Review Process

Approver views queue in right panel "Pending Approvals", toggle between "Pending Approval" / "My Applications". Click "Details & Records" to see:

Version lineage: Update shows "Formal major v1 → v2 | Draft minor v3"; new shows "New formal asset · initial v1".

Field snapshot: Custom fields listed with code, type, required, default; system fields collapsed as "System fields N items".

Approval timeline: Submit, resubmit, approve/reject/fail/expire each logged.

Only two actions: "Approve" or "Reject"; reject requires reason (API rejects if missing). Applicant cannot approve own request — enforced at API layer, not just UI.

Step 12: Troubleshooting Common Issues

Agent only answers "not found in graph": Replica empty / keyword mismatch → load data first; try synonyms, codes.

Reasoning passes but cards have no values: Dynamic source returned empty or DSL references non-existent field → check log's data fetch & DSL validation lines; add field or fix formula then re-reason.

Stuck at "field" stage: All drafts lack business fields → ask agent to write fields or add manually in inspector.

Multiple drafts but reasoning missing links: No relationships between drafts → ask agent to connect (standard R_* or business semantic).

Submit approval reports "Content Changed": Edited draft after submit → confirm final content then resubmit.

Submitted but formal asset unchanged: Still pending / rejected / execution failed → check approval status & comments; if failed, check logs and resubmit.

Dialog reports "Context full": Model context window configured too small → in LLM config set context_window to actual server value.

All failures must be read honestly: product explicitly forbids packaging failure as pass, and forbids using SQL/direct query to bypass reasoning engine.

Appendix A: Prompt Templates

Build from scratch: "Based on data source [X] build a [business domain] ontology that can answer: 1)… 2)… 3)…; key criteria are…"

Iterate on existing asset (Auto Modify): "(Auto Modify) Add fields to [asset name]: …; set [field] as required, length 32."

Add relationships: "Connect [Entity A] and [Entity B] with R_CONTAINS; rule attached to rule ontology under [Entity A], condition: '…'"

Bind sources: "Per [data source] bind dynamic source for [entity], identity filter uses [field], fetch [col1, col2]."

Reason: "Now re-reason, list conclusions, evidence cards, and missing data separately."

Self-test: "Self-test and coverage check on the question list above, state what's missing directly."

Submit: "Confirm ready, help me organize change summary, I'll submit for approval."

Appendix B: Complete Operation Example

0) Data prep: Data source "SalesDB" selected fields for orders/customers/shipments
1) New iteration: Auto Add, name "Order Fulfillment Ontology v1"
2) First prompt: see Step 3 recommended format
3) Inspect draft: 3 entities + overdue rule/query branches; add customers.credit_level field
4) Connect relationships: Customer R_CONTAINS Order; Order R_TRIGGERS overdue shipment validation
5) Bind sources: all three entities bind db_sim; overdue rule node references $.prev_n to avoid duplicate fetch
6) Load data → Re-reason → Cards show 12 overdue, 2 cascade-blocked (missing ship date)
7) Add shipments.ship_date field → Re-reason → Blocks disappear
8) Self-test + coverage: 3 questions fully covered, field match 100%
9) Submit approval → Approver verifies field snapshot → Approve → Formal asset v1 appears in domain-model

Appendix C: Operation Checklist

Mode correct: URL type matches badge; Auto Modify has formal asset selected.

Entities complete: One entity per business object; no views/dictionary tables mixed in.

Fields sufficient: All question-involved fields present; type/length/required reasonable.

Relationships connected: Entity chains and question branches linked; no isolated drafts.

Sources bound: Entities have identity filters; list-types have multi_instance enabled.

Reasoning passes: Cards have conclusions; blocked items have known causes.

Self-test passes: Questions fully covered, no pending, missing fields explained.

Submission complete: Change summary and impact scope documented.

This manual works with "Auto Workshop Product Functional Specification"; agent capability list in "Agent Capabilities & Safety Boundaries".