ster 0.5.0

Terminal tool for building and exploring SKOS taxonomies and OWL ontologies

ster

   _____ ______ ______ ____
  / ___//_  __// ____// __ \
  \__ \  / /  / __/  / /_/ /
 ___/ / / /  / /___ / _, _/
/____/ /_/  /_____//_/ |_|

  [ Breton: "Meaning" or "Sense" ]
  [  Semantic Knowledge Editor  ]
  v0.5.0

ster is a terminal tool for building and exploring semantic knowledge bases. Edit SKOS taxonomies and OWL ontologies in a full-screen TUI, explore them as VOWL-style interactive graphs in the browser, and export HTML documentation — all from your terminal, no database required.

ster is the Breton word for meaning, with homonyms for river and star. Let it guide your semantic voyage, keeping the flow and always following your star.

---

What's inside

Layer	What ster does
Edit	Full-screen TUI for SKOS concepts and OWL classes / individuals / properties
Visualise	VOWL-style interactive graph — classes as circles, property edges, per-class individual toggle, drag, zoom, detail panel
API server	Local JSON/WebSocket server exposing the taxonomy for external tools; configurable host and port
AI assist	LLM-powered concept suggestions (online or local via Ollama)
Git	Stage, commit, push without leaving the terminal
Export	pyLODE HTML documentation; SPARQL query runner
SPARQL	Cache-warmed query engine — first query fires in milliseconds, not seconds

---

Features

Interactive TUI — SKOS and OWL in one view

• Full-screen tree browser for SKOS concept schemes and OWL class hierarchies
• Inline concept creation, renaming, deletion, and label editing
• Detail panel: view and edit all SKOS fields (labels, definitions, scope notes, related links…)
• OWL layer: browse classes, named individuals, object/datatype properties, axioms
• Visual ⇔ indicator for concepts with cross-scheme mapping links
• Fold / unfold subtrees; hidden-concept count shown
• Scheme dashboard: completion rates, quality issues, concept counts at a glance
• OWL class quality stats: label/comment coverage, instance count, and property fill rates displayed inline on each class node
• Ontology root node: selectable in the tree; opens the ontology overview panel
• Smart startup: opening a pure-OWL file goes directly to the ontology overview

VOWL graph visualisation

Open any ontology or taxonomy as an interactive VOWL-style graph in the browser:

• OWL classes as circles, datatype nodes as amber rectangles, SKOS schemes and concepts as circles
• Object-property edges with floating label boxes; subClassOf rendered with a hollow arrowhead; datatype properties as amber dashed edges
• Hierarchical layout auto-selected for OWL-only graphs; force layout for SKOS and mixed ontologies
• Drag, zoom, and pin nodes; hover tooltips; highlight neighbourhoods on click
• Per-class individual toggle: click the count badge on a class circle to show/hide its individuals; "Hide/show all individuals" button in the sidebar
• Cardinality labels: functional properties display 0..1 on their edge box
• Closeable detail panel: × button or Escape hides the right panel
• Link-type toggles: rdf:type, inScheme, and datatype link families can be hidden/shown from the toolbar

Local API server

Start a local JSON + WebSocket server to expose your taxonomy to external tools:

ster api my-taxonomy.ttl

• REST endpoints for querying concepts, classes, and properties
• WebSocket push on every file change (live refresh for connected clients)
• Host and port are configurable — set them once in ⚙ Setup / Options and they persist across sessions
• Bearer-token authentication (token generated on first launch, viewable in Setup / Options)

AI-assisted concept creation

When adding a concept (+ key), choose between entering a name manually or letting AI suggest up to 20 ordered concept names:

• AI Auto Suggest — the AI acts as a professional taxonomist who knows your domain. It proposes names ranked by relevance, you pick one (or ask for more), and the form is pre-filled.
• Before generating, ster shows you the exact prompt so you can review and adjust it.
• Supports any LLM via the llm library — including local models via Ollama.
• Pull Ollama models directly from the ⚙ Setup / Options wizard without leaving ster.
• Copy-paste mode — no local LLM needed: ster displays the prompt, copies it to the clipboard, and you paste the model's response from any web AI (ChatGPT, Claude, Gemini…).

Setup / Options screen

A dedicated full-screen settings panel, available from the main menu:

── Server Setup ─────────────────────────────────────────────
  server URL          http://127.0.0.1
  server port         8765
  bearer token        ***
  configure AI model  →
── LLM Setup ────────────────────────────────────────────────
  configure AI model  →
  language            en

• Edit server URL and port inline; ster saves changes and shows a restart reminder
• Toggle bearer token visibility to copy it when connecting external tools
• Launch the AI model configuration wizard directly from this screen

Multi-file workspace

• Open several .ttl files at once and see a merged taxonomy view
• Edits are always written to the correct source file automatically

Cross-scheme mapping

• Add exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch links between concepts in different files
• Remove links from the detail view — works even when the target file has been deleted
• Both source and target files are saved and staged in git on every change

Git integration

• Stage, commit, and push changes without leaving the terminal
• Browse full commit history with diffs inside the TUI

HTML export

• Generate a browsable, wiki-style HTML page from any taxonomy via pyLODE
• One HTML file per language detected in the taxonomy
• Sticky language-switcher bar links between language versions
• Available from the main menu or ster export

---

Installation

Minimal (TUI + editing)

pip install ster

With AI features

pip install "ster[ai]"

Then configure your model from the main menu: ⚙ Setup / Options. No model needed if you use copy-paste mode.

With HTML export

pip install "ster[html]"

With API server

pip install "ster[api]"

From source

git clone https://github.com/gbelbe/ster.git
cd ster
pip install -e .           # core only
pip install -e ".[ai]"     # with AI features
pip install -e ".[html]"   # with HTML export
pip install -e ".[api]"    # with API server
pip install -e ".[dev]"    # with test suite

---

Dependencies

Group	Package	Purpose
core	rdflib>=7.0	RDF parsing and serialisation
core	typer[all]>=0.12	CLI framework
core	rich>=13.0	Terminal rendering, prompts, tables
[ai]	llm>=0.19	LLM abstraction layer (online & offline models)
[api]	fastapi[standard]>=0.110	JSON + WebSocket API server
[api]	watchfiles>=0.21	File-change watcher for live push
[html]	pylode>=3.0	HTML generation from SKOS / OWL (VocPub / OntPub profiles)
[dev]	pytest>=9.0	Test suite
[dev]	pytest-cov>=5.0	Coverage reporting

Both llm and pylode are not installed by default. When you trigger a feature that needs them, ster will offer to install the package automatically.

---

Quick start

Launch the interactive editor

ster

The home screen lists all ontology and taxonomy files in the current directory. Use arrow keys to navigate the action menu, then press Enter to confirm.

       ✓  my-ontology.ttl
       ✓  products.ttl

 ▶  1  ↵  Open Tree View
    2  ◈  Open Graph Viz
    3  🔍 Query Graph SPARQL
    4  📥 Import External Ontology
    5  🌐 Generate Web-Documentation
    6  ⎇  Browse git history
    7  ⚙  Setup / Options
    8  ✕  Quit

Keyboard shortcuts (TUI)

Key	Action
↑ ↓	Navigate tree / fields
Enter	Expand/collapse node or open detail
+	Add concept — opens a menu: enter name manually or use AI Auto Suggest
d	Delete selected concept
e	Edit selected field in detail panel
m	Add a mapping link to another concept
g	Commit & push changes
?	Help screen
q / Esc	Back / quit

AI Auto Suggest

Press + on any concept or scheme, then select ✦ AI Auto Suggest:

1. ster renders the prompt and shows it for review — edit prompts.py to customise the wording
2. Press Enter to generate; the AI suggests up to 20 concept names ranked by relevance
3. Navigate the list and press Enter to pick a name (pre-fills the creation form)
4. Select Suggest more to get a fresh batch with deduplication

In copy-paste mode the prompt is displayed and copied to the clipboard; paste the model's response back and press Enter on an empty line.

Export to HTML

ster export my-taxonomy.ttl          # generates ./html/my-taxonomy_en.html …
ster export my-taxonomy.ttl -l en,fr # specific languages only
ster export my-taxonomy.ttl -o /tmp  # custom output directory

Or use the 🌐 Generate Web-Documentation option from the main menu.

SPARQL query runner

Query the loaded taxonomy or ontology with SPARQL directly from the TUI. Select 🔍 Query Graph SPARQL from the main menu, type or paste a query, and press F5 (or Ctrl+R) to run.

SELECT ?class ?label WHERE {
  ?class a owl:Class ;
         rdfs:label ?label .
  FILTER(LANG(?label) = "en")
}
ORDER BY ?label

Results appear in a scrollable table. Navigate rows with arrow keys, copy a cell with Enter, and export the full result set to a CSV file.

Cache-warmed engine — zero cold-start delay

ster builds a URI index and prefilled prefix map from your RDF files before you open the query screen. After the index is ready, ster pre-fires a no-op SPARQL query (SELECT * WHERE { ?s ?p ?o } LIMIT 0) against the cached graph in the background. This forces rdflib's plugin discovery system to resolve all importlib.metadata entry points once, so the first real query you run returns in milliseconds instead of the ~20-second delay that rdflib triggers on Python 3.13 without this warm-up.

The warm-up runs asynchronously — it does not block the TUI.

Validate

ster validate my-taxonomy.ttl

---

Annotating entities with rich media

ster reads schema:image, schema:video, and schema:url triples and uses them in the graph visualiser's detail panel:

@prefix schema: <https://schema.org/> .

<https://example.org/MyClass> a owl:Class ;
    rdfs:label "My Class"@en ;
    schema:image <https://upload.wikimedia.org/wikipedia/commons/thumb/.../500px-image.png> ;
    schema:video <https://www.youtube.com/watch?v=...> ;
    schema:url   <https://en.wikipedia.org/wiki/My_Class> .

Images appear as thumbnails in the graph detail panel; videos open in a popup window; URLs render as link buttons in the detail panel.

---

Architecture

ster/
├── model.py            — Pure dataclasses: Concept, ConceptScheme, Taxonomy, RDFClass, OWLIndividual…
├── store.py            — RDF I/O via rdflib (.ttl / .rdf / .jsonld); loads SKOS + OWL layers
├── operations.py       — All SKOS mutations (add, remove, move, relate…)
├── workspace.py        — Multi-file workspace: merged view + per-file saves
├── workspace_ops.py    — Cross-file mapping operations
├── cli.py              — Typer entry-points (ster, ster export…)
├── api_server.py       — FastAPI JSON + WebSocket server; host/port config persistence
├── ai.py               — LLM abstraction: model routing, copy-paste mode, Ollama integration
├── prompts.py          — All AI prompt templates (string.Template)
├── config_screen.py    — Standalone curses Setup / Options screen
├── ai_config_screen.py — Standalone curses AI model configuration wizard
├── html_export.py      — pyLODE HTML export (VocPub / OntPub profiles)
├── viz.py              — Graph helpers: label formatters, node detail builders, metadata
├── viz_vowl.py         — VOWL-style D3 graph: writes self-contained HTML, opens in browser
├── owl_analysis.py     — OWL axiom analysis and statistics
├── sparql_query.py     — SPARQL query runner against the loaded taxonomy
├── handles.py          — Short handle generation from camelCase URIs
├── validator.py        — SKOS integrity checks
└── nav/
    ├── viewer.py       — Full-screen TUI (curses): tree, detail, inline edit; SKOS + OWL modes
    ├── state.py        — Typed state machine: one dataclass per viewer mode
    ├── logic.py        — Pure functions: tree flattening, field builders, OWL node rendering
    ├── draw.py         — Curses drawing primitives and colour pair constants
    └── …

Each layer depends only on the layers below it, keeping every module independently testable. AI prompts live in prompts.py as plain string.Template objects — edit them freely without touching any logic.

---

Supported formats

Extension	Format
.ttl	Turtle (recommended)
.rdf / .xml	RDF/XML
.jsonld / .json	JSON-LD
.owl	OWL/XML

---

Development

See CONTRIBUTING.md for the full workflow including branch conventions, commit style, and pull request process.

git clone https://github.com/gbelbe/ster.git
cd ster
uv sync --extra html --extra api --extra dev
bash scripts/install-hooks.sh   # install git pre-push hook (once per clone)

Run the local CI gate

bash scripts/ci.sh          # full run: lint + types + security + tests on 3.11/3.12/3.13
bash scripts/ci.sh --fast   # current Python only (quick iteration)
bash scripts/ci.sh --fix    # auto-fix ruff, then full gate

The local gate mirrors the GitHub Actions pipeline exactly. A git pre-push hook (installed by scripts/install-hooks.sh) blocks any git push that does not have a passing CI run from the last 60 minutes.

---

CI / CD

Every push and pull request runs four parallel jobs via GitHub Actions:

Job	Tool	What it checks
Lint	ruff	Code style, import order, common bugs
Type check	mypy	Static type correctness
Security	bandit + pip-audit	SAST + known CVEs in dependencies
Tests	pytest × Python 3.11 / 3.12 / 3.13	Full test suite + coverage report

Coverage is uploaded to Codecov on every run.

---

Changelog

0.5.0

• SPARQL predicate autocomplete: typing prefix: at predicate position in a WHERE clause now filters suggestions to OWL properties only
• SPARQL subject autocomplete: typing prefix: at subject position shows class roots and properties; expanding a class reveals its subclasses and individuals; leaf classes with only individuals now correctly show the expand arrow
• Fix: creating a new OWL property from the Properties section panel now works (was silently discarded due to routing bug)

0.4.6

• Cache-warmed SPARQL engine: after building the URI index, ster pre-fires a no-op SPARQL query against the cached graph in the background, forcing rdflib's plugin discovery to complete before the user opens the query screen — eliminates the ~20-second first-query delay on Python 3.13
• Main menu reordered: Query Graph SPARQL promoted to 3rd position (no longer labelled "Beta"); Import External Ontology 4th; Generate Web-Documentation 5th
• Git pre-push hook: scripts/install-hooks.sh installs a standard git hook that blocks git push when CI has not passed in the last 60 minutes — works for all developers, not just inside Claude Code
• Local CI script (scripts/ci.sh): mirrors the GitHub Actions pipeline exactly — lint, format, types, security, and pytest across Python 3.11, 3.12, and 3.13 in isolated per-version virtual environments
• CONTRIBUTING.md: full contributor guide covering prerequisites, clone + hook setup, branching, local CI, commit conventions, PR process, and troubleshooting

0.4.5

• Standalone Setup / Options screen: replaced the tree-view panel with a dedicated full-screen curses settings page, accessible from the main menu — server URL, port, bearer token, and AI model configuration in one place
• AI model configuration wizard: extracted from the tree-view modal into its own standalone curses module (ai_config_screen.py) — cleaner UX, no longer tied to the taxonomy viewer
• API server: ster api command starts a local JSON + WebSocket server; host and port are persisted in ~/.config/ster/server_config.json and read at startup — no more hardcoded address
• Bearer token management: token is visible in Setup / Options (hidden by default, toggle with Enter); change server URL or port triggers an in-screen restart reminder
• Server startup from config: ster serve / ster api now read host and port from the saved config rather than hardcoded defaults

0.4.4

• Standalone Setup / Options screen: replaced the tree-view panel with a dedicated full-screen curses settings page, accessible from the main menu — server URL, port, bearer token, and AI model configuration in one place
• AI model configuration wizard: extracted from the tree-view modal into its own standalone curses module (ai_config_screen.py) — cleaner UX, no longer tied to the taxonomy viewer
• API server: ster api command starts a local JSON + WebSocket server; host and port are persisted in ~/.config/ster/server_config.json and read at startup — no more hardcoded address
• Bearer token management: token is visible in Setup / Options (hidden by default, toggle with Enter); change server URL or port triggers an in-screen restart reminder
• Server startup from config: ster serve / ster api now read host and port from the saved config rather than hardcoded defaults

0.4.3

• VOWL graph visualisation: replaced the old D3 force graph with a full VOWL-style renderer — classes as circles, object-property edges with floating label boxes, hollow subClassOf arrowhead, light theme
• Datatype properties: amber dashed edges to amber rectangle nodes; functional properties show 0..1 cardinality on their edge box
• Per-class individual toggle: click the count badge on a class circle to show/hide its individuals; "Hide/show all individuals" button in the sidebar; badge enlarges on hover to signal it is clickable
• Focused graph from tree view: select any OWL class and choose "⊙ Open Graph Viz" to open a browser graph centred on that class, showing only its subclasses (transitive) and their individuals
• Graph overview panel: counts (classes, individuals, properties) now reflect what is actually displayed in the current graph rather than the full ontology totals
• Hierarchical layout: OWL-only graphs (full and focused) use a depth-based hierarchical lane layout; force layout for SKOS and mixed ontologies

0.4.0

• OWL class quality stats: label/comment coverage, instance count, and property fill rates shown inline on each class node in the OWL hierarchy — mirrors SKOS completion labels on concept trees