TermKit

Concept-first infrastructure and a local-first workbench for professional terminology.

Curate evidence, review semantic changes, build immutable terminology packs, and compile deterministic runtime indexes—without tying your data to one model or translation provider.

简体中文 · Studio architecture · TermSpec · TermPack format

Important

TermKit is pre-alpha. TermSpec 0.2 and the local Studio are implemented as the long-term architecture, but public compatibility is not guaranteed until 1.0.

TermKit Studio keeps concept identity, multilingual lexical entries, evidence, relations and revision state visible in one dense workspace. Canonical files do not change until an explicit ChangeSet passes validation and is applied.

What TermKit is

TermKit treats a termbase as governed knowledge rather than a table of bilingual word pairs. One language-neutral concept owns definitions, domain membership, relations, provenance and lifecycle state; each language-specific name is a separate lexical entry with its own status, policy, sense and evidence.

Concept → Evidence → Curation → Review → Package → Runtime

The repository contains three product surfaces:

• TermKit Core — TermSpec 0.2, deterministic TermPack tooling, Forge contracts, Exchange planning, dependency locks, and provider-neutral runtime.
• TermKit Studio — the official local-first React/FastAPI workbench for concepts, candidates, review, sources, relations, exchange, runtime and releases.
• TermRegistry — immutable package discovery and verified local installation; a hosted registry is deliberately not required.

Studio is not a SaaS dashboard. It opens a terminology repository on your own machine. YAML and JSONL remain canonical; the workspace SQLite database is a derived editing/index layer, and every semantic edit is an auditable ChangeSet.

Highlights

• Concept-first modeling — represent one meaning once, then attach any number of BCP 47 language entries, definitions, relations and evidence.
• Governed curation — draft semantic operations, review language and domain decisions independently, and keep rationale plus revision history.
• Standards-aware exchange — map CSV/XLSX, normalize TBX and SKOS, preview identity conflicts, and expose OpenRefine Reconciliation API v0.2.
• Deterministic runtime — resolve dependencies, write an exact lock, compile FTS5 plus an Aho–Corasick matcher, and explain every terminology decision.
• Local by default — canonical data stays Git-friendly and Studio binds to loopback; no hosted account or proprietary database is required.

Quick start

From a source checkout, requirements are Python 3.11+, uv, Bun 1.3+, and Git:

uv sync --all-extras
cd apps/studio && bun install --frozen-lockfile && bun run build && cd ../..
uv run termkit studio examples/packs/demo-hydraulics

Studio opens at http://127.0.0.1:8765/studio. It binds to loopback by default; non-loopback hosting requires an explicit override because Studio has no hosted authentication boundary. Release wheels embed the production Studio build, so installed users only need termkit[studio]; Bun is a contributor dependency.

Core workflows remain available without the UI:

uv run termkit validate examples/packs/demo-hydraulics
uv run termkit pack build examples/packs/demo-hydraulics --output dist/
uv run termkit runtime compile \
  --pack examples/packs/demo-hydraulics \
  --output dist/demo-hydraulics.termdb \
  --lock-output dist/termkit.lock
uv run termkit resolve \
  "The boom cylinder is controlled by the pilot valve." \
  --pack examples/packs/demo-hydraulics \
  --source-language en \
  --target-language zh-Hans

Studio workflow

Workspace	Purpose
Concepts	Faceted, virtualized concept and multilingual lexical editing
Candidates	Context-first reconciliation of Forge output into concepts
Review	PR-style semantic diffs with separate language/domain decisions
Sources	Provenance, authority, content identity and rights inspection
Relations	Hierarchy-first browsing plus governed relation ChangeSets
Exchange	CSV/XLSX mapping wizard and normalized TBX/SKOS import planning
Runtime	Explainable resolve/check plus independent .termdb compilation
Releases	Validation gates and deterministic build/verification

⌘K / Ctrl+K opens the command palette. The interface is intentionally dense, quiet and keyboard-friendly; machine assistance belongs behind Forge and reconciliation capabilities, not at the center of the product.

Studio opens in Simplified Chinese by default. Use the language switch in the top bar to move between 中文 and English; the preference is stored locally in the browser and never changes canonical terminology data.

Review semantic changes

Every edit is autosaved as one atomic ChangeSet. Draft Inbox is the shared continuation point for inspecting, submitting, rebasing, applying or discarding work without implying that canonical files have already changed.

A draft is an ordered semantic diff rather than an opaque form submission. Language and domain reviewers decide separately, provide rationale, and approve the same ChangeSet before canonical source is updated.

Explain runtime decisions

Runtime Lab shows source offsets, concept identity, selected pack, target term, policy and evidence. The same bounded result can be consumed through the Python API, local HTTP API or a compiled .termdb index.

Validate and build immutable releases

Release gates validate schema, references, languages, evidence and rights before building a deterministic .termpack; the produced archive is verified in the same workflow and reported with its SHA-256 digest.

Curation lifecycle

source revision → corpus → Forge candidates → reconciliation
       → ChangeSet → language/domain review → canonical source
       → TermPack + lock → compiled runtime index

Machine or plugin output never becomes approved terminology directly. It first produces candidates with occurrence context and quality signals; a curator then matches an existing concept, creates a concept, attaches a lexical entry, defers, merges or rejects the proposal. See Studio, Exchange and Runtime for the complete workflows.

Architecture

canonical YAML + JSONL
        │ open / hash / index
        ▼
workspace.sqlite ── draft ChangeSet ── review ── validated atomic write
        │                                           │
        │ candidate/review/history                   ▼
        └──────────────────────────────────── canonical source
                                                    │
                         build TermPack / resolve dependencies / lock
                                                    ▼
                      immutable .termpack       derived .termdb
                                                FTS5 + matcher

The two SQLite files have different ownership and lifecycles:

• .termkit/workspace.sqlite contains local editing state, candidates, review decisions and derived canonical indexes;
• .termkit/runtime/*.termdb contains only resolved pack data, FTS5 search and a serialized deterministic Aho–Corasick matcher.

See architecture.md and the accepted Studio architecture for invariants.

Repository map

apps/studio/            React + TypeScript + Vite workbench
src/termkit/spec/       TermSpec 0.2 semantic contracts and JSON Schema
src/termkit/workspace/  Alembic-backed local application engine
src/termkit/forge/      Reproducible candidate pipeline and plugin ports
src/termkit/exchange/   CSV/XLSX/TBX/SKOS parsing and reconciliation plans
src/termkit/runtime/    Resolution, QA, dependency locks, FTS and matcher compiler
src/termkit/pack/       Canonical loading, validation and deterministic archives
src/termkit/registry/   Verified immutable package installation
src/termkit/server/     Local FastAPI and Studio API adapters
examples/               Original test fixtures, never the production data catalog

Official original seed data lives in the separate sibling TermKit-Packs repository. Its dependency hierarchy covers mechanical engineering/hydraulics/ construction machinery and machine learning/computer vision/object detection.

Development

uv run ruff check .
uv run mypy src
uv run python scripts/export_schemas.py --check
uv run pytest --cov
cd apps/studio && bun run check && bun run test && bun run build
cd ../.. && uv run python scripts/embed_studio_assets.py --check && uv build

Read CONTRIBUTING.md, AGENTS.md, and development.md before structural changes.

Trust and non-goals

TermPacks are untrusted data and never contain executable plugins. Reference-only or restricted sources cannot ship excerpts. Studio is local-only by default and must not be exposed directly to the public internet.

TermKit does not bundle scraped/proprietary termbases, automatically approve machine proposals, invent a custom TBX dialect, or turn terminology curation into a chat-first AI product. Multi-tenant SaaS and a plugin marketplace remain outside the current security boundary.

License

TermKit software is available under the MIT License. Packs and source materials are independent works and must declare their own licenses.