NokaMan

NokaMan assesses language-learning ability across multiple skills and languages — CEFR-style bands, rubrics, and JSON reports ready for learning apps.

Product: mergeos-bounties/NokaMan

---

Table of contents

• Highlights
• Desktop GUI (Qt)
• Screenshots
• Quick start
• CLI reference
• App integration contracts
• Languages & rubrics
• Supported language catalog
• Language sample guide
• Offline speaking fluency rubric
• Diagrams
• Repository layout
• Development
• Contributing
• Docs: CEFR expected_cefr field mapping table
• MergeOS bounties
• License

---

Highlights

Mode	Description
Multi-skill eval	Vocabulary, grammar, reading, writing, listening, speaking proxies
CEFR-style bands	Map scores → A1–C2 style levels (scaffold)
Multi-language	EN, KO, JA, VI, ZH (+ extend via rubrics)
JSON reports	Save under OUT_DIR for app integration
Offline demo	nokaman demo --lang en end-to-end
Desktop GUI	Modern PySide6 app (nokaman-gui)

---

Desktop GUI (Qt)

Modern dark PySide6 demo — multi-skill evaluation, languages, free-text scoring, samples, rubrics, toy calibration.

pip install -e ".[gui]"
nokaman-gui
# or: nokaman gui

Full multi-skill demo

Supported languages & frameworks

Evaluate free text / samples / placement

Bundled samples + batch metrics

Skill rubrics

Toy calibration

---

Screenshots

CLI / terminal captures:

Evaluation demo	Languages
English multi-skill demo	Supported languages registry

---

Quick start

cd NokaMan
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev,gui]"

nokaman version
nokaman languages list
nokaman demo --lang en
nokaman rubrics list
nokaman-gui

For a browser demo that talks to the local FastAPI app, see web/README.md.

---

CLI reference

Command	Purpose
nokaman version	Version + language codes
nokaman demo -l en	Full multi-skill evaluation demo
nokaman languages list	Supported languages + frameworks
nokaman languages coverage	Language x skill sample coverage matrix
nokaman rubrics list [-l en]	Skill rubrics
nokaman rubrics explain -l en	Print rubric skill weights, notes, frameworks, and bands
nokaman eval text …	Evaluate free text
nokaman eval batch --out data/out/batch.json	Score every sample and write a JSON CEFR hit-rate report
nokaman train …	Toy calibration with config/report exports
nokaman gui / nokaman-gui	Qt desktop app (needs .[gui])
nokaman serve	Optional FastAPI

nokaman demo -l vi
nokaman demo -l ko
nokaman eval batch --out data/out/batch.json
nokaman train toy --config configs/example.yaml
nokaman-gui

---

App integration contracts

NokaMan publishes stable contracts for mobile and web apps under schemas/ and sdk/typescript/. They mirror the real FastAPI and SDK payloads, so app teams can validate data and type responses without reverse-engineering demo output.

Contract	Runtime source
schemas/assess_text_request.schema.json	POST /assess/text request body
schemas/assess_text_response.schema.json	POST /assess/text and assess_for_app(..., multi_skill=false)
schemas/demo_response.schema.json	GET /assess/demo/{lang} and demo_payload()
sdk/typescript/index.ts	TypeScript interfaces for request and response payloads

Optional FastAPI endpoints:

Endpoint	Purpose
GET /languages	List supported language codes, display names, and frameworks
POST /assess	App-facing text assessment alias
POST /assess/text	Text assessment with language, text, and skill
GET /assess/demo/{lang}	Multi-skill demo payload
POST /assess/placement	Placement score from multiple answers

Example TypeScript use:

import type { AssessTextRequest, AssessTextResponse } from "./sdk/typescript";

const body: AssessTextRequest = {
  language: "en",
  text: "I practice English every morning.",
  skill: "writing",
};

const response = await fetch("/assess/text", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body),
});

const assessment = (await response.json()) as AssessTextResponse;
console.log(assessment.cefr, assessment.score, assessment.framework_bands);

---

Languages & rubrics

Rubrics and samples live under data/. Extend by adding rubric JSON + samples, then register in nokaman.rubrics.registry. See docs/LANGUAGES.md for the supported language catalog, CEFR/JLPT/TOPIK/HSK mappings, and language-pack extension steps. See docs/SAMPLES.md for the sample JSON schema, expected_cefr semantics, naming rules, and offline verification commands. See docs/SPEAKING_FLUENCY.md for the transcript-only speaking rubric and its limitations.

Code	Typical use
en	English (default demo)
vi	Vietnamese
ko / ja / zh	East Asian tracks

---

Diagrams

System architecture and workflow — full width. Open the HTML files for dark/light theme and export (PNG/SVG).

Architecture

Open interactive diagram

Workflow

Open interactive diagram

Generated with archify.

---

Repository layout

src/nokaman/
  cli.py
  gui/            # PySide6 desktop demo (nokaman-gui)
  eval/           # pipeline, metrics, placement
  rubrics/        # language metadata + skills
  data/loader.py
  train/toy_train.py
web/              # no-build browser demo for the FastAPI app
docs/screenshots/
docs/diagrams/

---

Development

pytest -q
ruff check src tests
nokaman demo -l en
python scripts/capture_gui_shots.py   # refresh GUI screenshots

Contributing

See CONTRIBUTING.md for local setup, test commands, the good-first-issue path, and the MergeOS bounty claim flow.

---

MergeOS bounties

Star + claim bounty → PR to master with demo JSON / screenshots → MRG 25–200.
See CONTRIBUTING.md for the contributor path and org policy on mergeos.

---

License

MIT · MergeOS / ThanhTrucSolutions