Ginger Workbench Pro

English | 简体中文

Ginger Workbench Pro is a local research workbench for reading, annotating, and deciphering Ginger language data. It combines a self-describing dictionary, corpus review, gloss editing, POS inference, definition-reference graphs, research workspaces, segmentation, and HMM-assisted analysis in one tool.

What It Does

• Browse dictionary entries and structured definitions.
• Search by word prefix, infix, suffix, gloss, POS abbreviation, or definition reference.
• Replace known glosses in rendered Ginger definitions while keeping the source form visible.
• Review imported corpus passages, preserve line breaks, write translations, and favorite passages.
• Inspect inferred POS candidates and posterior probabilities from the constrained Baum-Welch HMM.
• Explore the definition-reference graph through overview, neighborhood, SCC-DAG, and workspace views.
• Collect words into named workspaces and arrange them with grid, DAG, radial, or force-directed layouts.
• Run arbitrary Ginger text through the shared Playground for segmentation and POS tagging.
• Import and export glosses as validated .gingerzh packages.
• Switch the UI between en-US and zh-CN; English is the default locale.

Architecture

Vue 3 + Vite + D3
        |
        | HTTP /api
        v
FastAPI
  |-- dictionary and gloss operations
  |-- corpus, translation, favorites, and collection
  |-- Ginger tokenization and HMM inference
  |-- definition-reference graph and workspace queries
  `-- local user-state persistence

Important directories:

Path	Purpose
backend/	FastAPI service, tokenizer, HMM pipeline, graph service, and user state
frontend/	Vue 3 + Vite + D3 application
data/	Dictionary, corpus source, checkpoints, and local state database
outputs/	Generated model databases, experiments, and reports
scripts/	Corpus import, tagging, packaging, and Windows build scripts
tests/	Python unit tests

The main frontend routes are / (dictionary), /corpus (corpus review), and /graph (reference graph). The UI locale is stored locally as ginger.locale; it does not alter dictionary, corpus, gloss, or translation data.

Requirements

• Python 3.13
• Node.js 24 and npm 11
• A prepared data/dictionary.sqlite
• A prepared HMM checkpoint under data/checkpoints/baum_welch/
• The generated HMM database under outputs/baum_welch/dictionary_temp.sqlite

Create the Python environment:

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install `
  numpy networkx fastapi uvicorn pydantic pystray pillow pyinstaller

Install frontend dependencies:

Set-Location .\frontend
npm ci
Set-Location ..

Run Locally

Start the FastAPI server from the repository root:

.\.venv\Scripts\python.exe -m uvicorn backend.app:app --reload

For production-style static hosting, build the frontend first:

Set-Location .\frontend
npm run build
Set-Location ..
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --reload

Open http://127.0.0.1:8000.

For Vite development with API proxying:

Set-Location .\frontend
npm run dev

Open the address printed by Vite, usually http://127.0.0.1:5173.

Tests And Build Checks

Run the Python suite:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Build the frontend:

Set-Location .\frontend
npm run build

The frontend localization supports only en-US and zh-CN. User-authored Ginger forms, glosses, and translations remain unchanged when the UI language changes. POS labels use the locale-specific charMap; English uses NUM, PREP, PRON, INT, QUEST, CONJ, REL, ADV, STORY, ADJ, V, and N.

Data Boundaries

The application is local and single-user. Dictionary edits and corpus translations update the local SQLite databases. UI settings, favorites, workspaces, and the selected locale are local preferences. Back up data/dictionary.sqlite, outputs/baum_welch/dictionary_temp.sqlite, checkpoints, and data/user_state.sqlite before large editing sessions.

The graph represents explicit references found in structured definitions. It is an investigation aid, not a confirmed semantic graph. HMM posterior probabilities describe POS preferences under the current constraints and training corpus; they are not gloss confidence scores.

Packaging For Windows

From the repository root in PowerShell 7:

pwsh.exe -NoLogo -NoProfile -File .\scripts\package_onedir.ps1

The output is written to release/GingerWorkbench/. Distribute the complete directory, not only the executable.

API

FastAPI documentation is available at http://127.0.0.1:8000/docs. The main API groups are dictionary entries and glosses, corpus entries and translations, /api/tag, graph overview/SCC/neighborhood endpoints, and /api/user-state.

Project Position

The workbench is designed to maximize auditable research coverage rather than pretend that one automatic answer is final. POS constraints provide local grammatical evidence, the reference graph exposes global dependencies, workspaces preserve investigation paths, and human researchers remain responsible for final interpretation.