conceptuum

A multilingual concept graph with Euler diagrams, executable concept algebra, and a question–answer generator for LLM training and evaluation.

conceptuum represents meanings as nodes and connects them through relations such as genus, purpose, material, opposition, and cause. Explore the graph, compute concept expressions, inspect their supporting relations, and export structured examples for language models. It combines a MariaDB snapshot, a Python parser and evaluator, and a Go web interface.

Development version: 0.1.0-dev · Bundled and live data: Q40, 2026-10-10 · Interface: 2026-10-10.1 · Changelog · Live demo

Try it: QA generator · Concept algebra · Euler circles · LLM training data and evaluation

Euler diagrams from the concept graph

Explore how concepts overlap, exclude one another, coincide, or fit inside a shared genus. Add or remove concepts, let sibling concepts bring in their common genus automatically, and highlight intersections, unions, differences, and complements.

Affirmative/negative and universal/particular judgments form overlapping classifications. The highlighted intersection contains the universal affirmative judgment. The outer circle is their automatically added genus.

Try the seven live demos: cross-classification, three-way intersection, union and difference, complement, empty intersection, equality, and inherited exclusion.

Catalog mode compares sets of stored concept records, with exact region counts and inspectable member samples. Share a selection by URL or export the diagram as SVG.

New in Q9: compare finite and nonempty sets, or commutative and associative operations. The first shares the singleton-set record; the second shares the union and intersection records.

Generate questions and answers for LLM training

Open the QA generator to create English or Russian questions with computed answers and the graph facts needed to solve them. Eight task families cover direct and shared genera, ancestry, intersections, differences, counts, inherited properties and valid or unsupported inferences.

Choose a seed, context and optional concept family, inspect each answer and its evidence, then uncheck examples you do not want to export. Download Training JSONL with system, user and assistant messages, or JSONL with evidence for source IDs, algebra queries and graph fingerprints. The website supports up to 50 examples per batch; the CLI supports up to 2,000.

Every answer is independently recomputed from its supplied facts. The adequacy review checks 200 English and 200 Russian examples, including 54 examples inspected for meaning and wording. Source errors and limited coverage still require editorial review. See how to prepare training data and the generator guide.

Topics: knowledge-graph · ontology · euler-diagrams · concept-algebra · llm-training · training-data · question-generation

What you can do

• Search English and Russian terms and inspect different meanings of a word.
• Explore separate hierarchy and relation views with zoom, filters, full ancestry, shareable links, and SVG export. The graph adapts to desktop and mobile screens.
• Compare concepts with Euler diagrams, using stored relations or catalog membership. Unknown semantic relationships remain explicitly marked.
• Retrieve stored facts from Python or the command line without an LLM.
• Evaluate concept algebra: combine catalog sets, follow relations, and select inherited properties with explicit negatives.
• Export expressions, resolved concept IDs, results and evidence as JSON for LLM training-data preparation and evaluation.
• Generate English or Russian questions with computed answers and supporting facts; review individual examples and export training JSONL.
• Review proposed changes against relation signatures, hierarchy checks, and explicit regression conditions.

The graph is experimental and still being reviewed. Structural validation catches some category errors; it does not establish whether a statement or translation is true.

How the graph works

Open the live concept explorer, or read the visualizer controls and browser checks.

Synonyms share a concept. Homonyms have separate concepts. A concept can have multiple genus links, each carrying its discourse context, or universe.

graph BT
  subtraction["subtraction"] -->|"14: genus"| arithmetic["arithmetic operation"]
  modulo["remainder operation"] -->|"14: genus"| arithmetic
  arithmetic -->|"14: genus"| operation["mathematical operation"]
  operation -->|"14: genus"| fn["mathematical function"]
  fn -->|"14: genus"| object["mathematical object"]
  remainder["division remainder"] -->|"14: genus"| number["number"]
  number -->|"14: genus"| object

Loading

An operation and its numerical result are different meanings. The defin field is a generated cache: change the reviewed relations, then rebuild the definition. An edge's strength=0 records explicit negation; an unspecified strength means no degree has been asserted.

Versions and requirements

Component	Version / requirement
Project	0.1.0-dev, an unreleased development version
Bundled and live data	2026-10-10 / Q40
Web interface	2026-10-10.1, with QA generation and reviewed JSONL export
Algebra language / example schema	1 / conceptuum.algebra.example.v1
QA generator / example schema	1 / conceptuum.qa.v1
Python	3.9+; checked with 3.9.13
PyMySQL	1.2.0, pinned in requirements.txt
pymorphy3	2.0.6, pinned for Russian morphological matching
Go	1.26.1+, required by visualizer/go.mod; only needed for the visualizer
MariaDB	Local setup checked on 5.5.42; live Q40 import and visualizer checked on 11.8.6

The MariaDB version records the existing test environment. Compatibility with other server versions, including MySQL, needs separate verification. Python direct dependencies are pinned; Go dependencies are recorded in go.mod and go.sum.

Run locally

1. Get the project and install Python dependencies

git clone https://github.com/thpg/conceptuum.git
cd conceptuum
python -m venv .venv

Activate the environment for your shell, then install the dependencies:

Shell	Activation command
Bash / Zsh	source .venv/bin/activate
PowerShell	.\.venv\Scripts\Activate.ps1

python -m pip install -r requirements.txt

Use python3 to create the environment if that is your Python command. If PowerShell blocks activation, use .\.venv\Scripts\python.exe in place of python; changing the machine's execution policy is unnecessary.

2. Import the database snapshot

Start MariaDB and open its client from the repository root:

mariadb --user=root --password --default-character-set=utf8mb4

At the database prompt:

SOURCE jnana3_dump.sql;
QUIT;

Use mysql if that is the installed client's name. This also works from PowerShell because SOURCE runs inside the database client.

The dump creates/uses jnana3 and replaces its six tables. Import into a fresh instance, or back up an existing jnana3 first. Selecting another database on the client command line does not redirect the dump's USE jnana3 statement.

3. Configure Python and retrieve facts

Set these variables in the same shell where you run Python, using an account that can read the imported database.

Bash / Zsh

export JNANA_HOST=127.0.0.1
export JNANA_PORT=3306
export JNANA_DATABASE=jnana3
export JNANA_USER=your_database_user
export JNANA_PASSWORD='your_database_password'

PowerShell

$env:JNANA_HOST = '127.0.0.1'
$env:JNANA_PORT = '3306'
$env:JNANA_DATABASE = 'jnana3'
$env:JNANA_USER = 'your_database_user'
$env:JNANA_PASSWORD = 'your_database_password'
$env:PYTHONIOENCODING = 'utf-8'

python ask.py "How are ice and water related?" --no-llm

This prints retrieved FACTS and one-hop RELATED context without contacting a model. Cached definitions are mostly Russian; --lang en selects lookup/display preferences and does not translate the stored definition cache.

See setup details and troubleshooting for database access, configuration precedence, and connection errors.

4. Start the visualizer (optional)

The Go application uses JNANA_DSN, independently of the Python settings. Set it with your own database account:

# Bash / Zsh
export JNANA_DSN='your_database_user:your_database_password@tcp(127.0.0.1:3306)/jnana3?charset=utf8mb4'

# PowerShell
$env:JNANA_DSN = 'your_database_user:your_database_password@tcp(127.0.0.1:3306)/jnana3?charset=utf8mb4'

Then run:

cd visualizer
go run .

For the Algebra and QA generator pages, also start the Python worker from the repository root in a second terminal with the JNANA_* settings from step 3:

python -m concept_algebra.web --port 7101 --version-file visualizer/static/version.json

Open http://127.0.0.1:7100/. Run from visualizer/ so the server can find static/index.html. LISTEN overrides the bind address. The interface chooses English or Russian from the browser locale; the hosted demo and bundled snapshot are updated independently.

Use the Python engine

Run from the repository root with the Python database variables configured:

from jnana_engine import JnanaEngine

eng = JnanaEngine(pref_lang="en")
try:
    print(eng.resolve_all("ice", lang="en"))
    print(eng.verify("ice", "freezing"))
    print(eng.stats())
finally:
    eng.close()

resolve_all() returns possible senses. verify() reports a stored path or relation; a positive result is not an independent fact check. Use concept IDs after selecting a meaning for edits.

rebuild() and define() write to the database. They are maintenance operations, not prerequisites for reading an imported snapshot. Reviewed changes use the transactional batch workflow.

Concept algebra

Open the concept algebra workspace to edit expressions, search and insert concept IDs, choose a relation context, restrict the domain, and inspect results and their source edges. Nine database examples demonstrate intersections, inherited materials, explicit exceptions, multiple genera, subset comparisons, counterexamples, unknown properties, complements and counts.

The same parser and evaluator are available from Python and the command line. For example, intersect glass jars with food-storage jars:

python -m concept_algebra '#25439 & #25446' --context 1 --lang en
python -m concept_algebra '#3500 & has(material, #90)' --json --explain 25447

The first expression returns #25447, the glass food storage jar. Operators include union, intersection, difference, complement, subset and equality; functions provide genus navigation, relation projections, counts and inherited property queries. Explanations retain source edge IDs. Homonyms require an explicit choice, and unknown properties remain distinct from explicit negatives.

Results contain stored concept records, with complements bounded by U or an explicit --within domain. Empty catalog intersections do not prove semantic incompatibility. See the language and API guide for syntax, Python examples, property inheritance and JSON snapshot support. Use Copy query link to share an expression and Download JSON to save a structured example. Exports contain all matching IDs; displayed concept labels are paginated. Select Explain before exporting to include a member's evidence.

Comparisons now show why they return true or false: operand sizes, exact counts for records only in A, in both, and only in B, plus inspectable samples. Try finding a counterexample to #25439 <= #25446. The general glass-jar record is outside the food-storage-jar catalog set, while the glass food storage jar belongs to both. Inspect any record also explains records outside a result, and works with counts and comparisons. Shared links retain the inspected ID.

LLM training data and evaluation

Use the online generator, or generate a reproducible batch from the local database:

python -m concept_algebra.qa --count 200 --seed 42 --lang en --output qa-en.jsonl --messages-output qa-en-sft.jsonl --report qa-en-report.json

Use --lang ru for Russian. Review the generated cards and exclude individual examples before downloading. Training JSONL contains system, user and assistant messages; annotated JSONL also retains concept IDs, source edges and graph hashes.

For supervised fine-tuning:

1. Fix the data revision, context, seed and task selection. Keep the annotated export and quality report alongside the training file for reproducibility.
2. Inspect the wording, supplied facts and answers. Remove unsuitable examples; automatic checks establish derivability, not independent world-fact accuracy.
3. Split annotated records by group_id, keeping language variants together. Check shared concept families and evidence across splits as well. A different random seed alone does not create a separate evaluation set.
4. Export each split as {"messages": [...]} rows. Preserve system instructions and the user message's facts, apply your model's chat template, and train on the assistant response using your trainer's appropriate loss masking.
5. Evaluate on held-out examples against their computed answers. Track task types and distinguish positive, negative, unknown and conflicting properties.

These examples teach answering from supplied evidence. The project generates and verifies data; training runs in your own pipeline. No improvement in a trained model is claimed by the generator's consistency checks.

For custom questions, use the algebra example collection to pair your own wording with executable expressions and inspectable answers:

1. Choose an expression in the web workspace or generate queries with the Python API.
2. Evaluate it in an explicit context and domain. Review the returned concepts; use Explain to inspect the supporting relations and inherited exceptions.
3. Enter an optional question and choose Add current example. Collect different queries, inspect saved examples again, or remove individual entries.
4. Download JSONL exports one self-contained example per line: question, request, resolved AST, answer, complete IDs for set results, comparison diagnostics, data revision and SQL snapshot hash, plus selected evidence.
5. Use reviewed question/expression–answer pairs for supervised examples, or compare model predictions with their computed answers.

Collections stay in browser storage, up to 50 examples or 4 MiB. Questions are not sent to the server. Export a portable copy before clearing browser data; when storage is unavailable, the collection lasts only for the page session. Reopening a saved example evaluates its query against the current graph while preserving the saved answer and its original revision. Diagnostic samples are limited to five records per group; their counts cover the full catalog domain.

The graph distinguishes positive, negative, unknown and conflicting property assertions. Preserve those distinctions in dataset labels. Answers describe the stored catalog and can inherit its omissions or errors; review examples before using them as targets. Keep a fixed data revision and separate related concept families across training and evaluation splits to reduce leakage.

This repository provides the graph, evaluator and export tooling. Model training and dataset orchestration run in your own pipeline; no model weights or private experiment results are included.

Optional LLM retrieval demo

Start a compatible local chat server, load a model, and pass its actual model identifier:

python ask.py "How are ice and water related?" --endpoint http://localhost:11434/v1 --model YOUR_LOADED_MODEL

The server must accept /chat/completions; ask.py does not start a server or download a model. The model receives retrieved graph context, which may contain incomplete or incorrect claims. interleave.py is a separate experiment that uses llama.cpp's native /completion endpoint.

Check the graph and code

From the repository root:

python -m unittest discover -s tools -p "test_*.py"
python tools/audit_quality.py --output quality.json
python tools/audit_upper_graph.py --output upper.json

The unit tests need no database or model. The audits read the configured database and write JSON reports. For a before/after comparison, save the first upper-graph report and pass its path with --scope-from on the second run; this keeps reparented nodes in scope.

Data snapshot and limits

The bundled and published Q40 snapshot contains 13,456 concepts, 17,350 accepted edges, 1,100 rejected edges, 64,683 genus paths, and 31,515 terms across everyday, IT, legal, and logic universes.

Q11–Q39 use Open English WordNet 2025 to guide reviewed additions. Q40 corrects 65 generated labels and removes 6,017 malformed Russian aliases. It removes 6,836 Russian infinitives from the English column while retaining those words as Russian terms. Concept identities, edges, rules, contexts and genus paths are unchanged. Rare and uncertain words remain available for review: dictionary absence alone is not grounds for deletion.

GitHub and the hosted demo include Q40. All six deployed tables match the reviewed snapshot, with timestamps compared in UTC. The SQL dump explicitly retains the source database's utf8_general_ci collation so newer MariaDB defaults do not merge distinct term keys during import. The local audit detected no signature violations, hierarchy cycles, or self-loops; all 23 explicit negations survived the reviews. These checks establish structural consistency, not complete or verified knowledge. 7,251 concepts still lack an English-tagged term containing Latin letters, and even Latin-script terms need translation review.

The coverage review and filling plan prioritizes remaining work. Sources and exact lexical changes are recorded in the Q40 review and its manifest. The Q40 publication record identifies the deployed snapshot; the Q11 review retains dictionary attribution. The changelog separates code versions from data revisions; older entries in the maintainer state include Russian text.

Documentation

Document	Purpose
Setup	Connection settings, import behavior, and troubleshooting
QA generator	Question types, training JSONL, CLI, API, verification and split guidance
Ontology rules	Concept identity, genera, relation meanings, and review constraints
Property review	Preparing, previewing, and applying a reviewed batch
Filling algorithm	Candidate generation, semantic review, and implementation limits
Roadmap	Remaining content and engine work
Versions	Development version and content revision history
Instruction audit	Published-document findings and setup verification

The six storage tables are concept, concept_term, edge, relevant, universum, and concept_path. The relation grammar is data in relevant; the root jnana_engine.py is the Python implementation. Older scripts in tools/ preserve development history and are not an installation sequence.

License

MIT for project code and original contributions. Q11–Q39 contain reviewed adaptations from Open English WordNet 2025, derived from Princeton WordNet, and BIPM unit information. Their attribution and source license notices are retained in the Q11 source notice.