localdesk 0.3.0__tar.gz

localdesk-0.3.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.venv
+__pycache__
+data
+artifacts
+work
+reports
+tests
+.env
+*.zip

localdesk-0.3.0/.gitattributes

@@ -0,0 +1,4 @@
+# Recipe/data hashes refer to LF bytes on every platform.
+* text=auto eol=lf
+*.gz binary
+*.png binary

localdesk-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install project and development tools
+        run: python -m pip install '.[dev,baseline,service]'
+      - name: Lint
+        run: ruff check .
+      - name: Format
+        run: ruff format --check .
+      - name: Test core, packaged model, notebook syntax and HTTP boundary
+        run: pytest -q
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: CLI smoke
+        run: localdesk predict 'File share access request'

localdesk-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+# Publishes with PyPI Trusted Publishing (OIDC): no API tokens are stored in GitHub.
+# A `v*` tag publishes to PyPI; a manual run publishes to TestPyPI for a dry run.
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install build tools
+        run: python -m pip install build==1.3.0 twine==7.0.0
+      - name: Tag must match the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python - <<'EOF'
+          import os, tomllib
+          version = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if tag != version:
+              raise SystemExit(f"tag v{tag} does not match pyproject version {version}")
+          EOF
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Check package metadata and README rendering
+        run: twine check --strict dist/*
+      - name: Smoke test the wheel without optional dependencies
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/localdesk predict 'File share access request'
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/localdesk
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/localdesk
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

localdesk-0.3.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+data/raw/
+data/zenodo/
+data/sms/
+artifacts/
+*.safetensors
+*.pt
+*.pth
+*.pickle
+*.h5
+.env
+.env.*
+.DS_Store
+data/banking77/
+data/clinc150/

localdesk-0.3.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-10-12
+
+First release on PyPI. The distribution is now named `localdesk`
+(previously `localdesk-decisions`, never published).
+
+### Added
+- `tfidf` CPU backend: hashed word 1–2 grams and character 3–5 grams with
+  sublinear TF-IDF and balanced logistic regression. Inference needs only the
+  standard library; artifacts store hash buckets, not a training vocabulary.
+  Shipped experiments use it.
+- Packaged TF-IDF demo model, now the default for `localdesk predict`, `serve`
+  and `evaluate` without `--model` (76.5% vs 69.5% accuracy on the IT holdout).
+  `--backend baseline` keeps the previous model.
+- Risk-coverage curves in every training report (coverage at 90/95/99%
+  accuracy, AURC) and out-of-scope analysis (review share, AUROC).
+- Banking77 and CLINC150 adapters with pinned sources and checksums, and
+  `scripts/publish_cpu_suite.py` for the four-dataset comparison.
+- Release workflow using PyPI Trusted Publishing; Python 3.12 in CI.
+
+### Changed
+- Concurrent API requests wait in a bounded queue (32 requests, 30 s) instead
+  of failing immediately with `MODEL_BUSY`.
+- A failed training run moves its record to `.failed-<id>-…` and frees the
+  run ID for a retry.
+- Optional dependencies use version ranges instead of exact pins; exact
+  tested versions stay in `uv.lock`. Tested at both ends of each range.
+- README rewritten around a quick start and measured results.
+
+### Fixed
+- A version that fails post-publish verification is withdrawn instead of
+  remaining under a completed run ID.
+- `localdesk runs` lists damaged registry entries as invalid instead of
+  aborting.
+- Dataset downloads read until EOF and retry truncated bodies.
+- `/metrics` declares a type for every counter; JSONL errors name the line.
+
+## [0.2.0] - 2026-10-11
+
+Configurable service: task/experiment JSON, immutable registry with quality
+gates, FastAPI inference API, operator dashboard, Qwen/Unsloth recipe and the
+comparative benchmark. Not published to PyPI.
+
+[0.3.0]: https://github.com/denis-samatov/localdesk/compare/52a3f7c...v0.3.0
+[0.2.0]: https://github.com/denis-samatov/localdesk/commit/52a3f7c

localdesk-0.3.0/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.13-slim
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 LOCALDESK_REGISTRY=/models
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE NOTICE.md ./
+COPY src ./src
+RUN python -m pip install --no-cache-dir '.[service]' && useradd --uid 10001 --create-home app
+USER 10001
+EXPOSE 8765
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/health/ready', timeout=3)"
+CMD ["uvicorn", "localdesk.api:application", "--factory", "--host", "0.0.0.0", "--port", "8765", "--no-access-log"]

localdesk-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Samatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

localdesk-0.3.0/NOTICE.md

@@ -0,0 +1,43 @@
+The project code and original notebook are MIT licensed.
+
+The training data are **Classification of IT Support Tickets**, Leonardo
+Santiago Benitez Pereira, Federal Institute of Santa Catarina, 2022, v2.
+Source: https://doi.org/10.5281/zenodo.7648117
+License: https://creativecommons.org/licenses/by/4.0/
+
+Changes made by this project: ID-based CSV joining; normalization for duplicate
+detection (NFKC, case folding, whitespace collapse); conservative grouping by
+PII-tag-stripped, tokenized and hashed baseline input features; duplicate and conflicting
+label removal; a calibration split from source training data; source EOL templates
+reserved as an unsupported-category challenge; conversion to Unsloth choice rows.
+The published linear baseline was trained on this adapted data. Keep this attribution
+with the baseline. Ticket texts are downloaded on demand and excluded from this Git repository.
+
+The second configured domain uses **SMS Spam Collection**, Tiago Almeida and
+Jos Hidalgo, UCI Machine Learning Repository, 2011.
+Source: https://doi.org/10.24432/C5CC84 — CC BY 4.0.
+Changes: verified archive extraction and conversion to id/text/label CSV;
+conservative equivalent-input deduplication and deterministic grouped splits.
+Original labels are retained. Raw SMS content is excluded from Git and serving logs.
+
+The third and fourth domains are downloaded on demand and excluded from Git:
+
+**Banking77**, Iñigo Casanueva, Tadas Temčinas, Daniela Gerz, Matthew Henderson
+and Ivan Vulić, "Efficient Intent Detection with Dual Sentence Encoders", 2020.
+Source: https://github.com/PolyAI-LDN/task-specific-datasets — CC BY 4.0.
+
+**CLINC150**, Stefan Larson, Anish Mahendran, Joseph J. Peper, Christopher Clarke,
+Andrew Lee, Parker Hill, Jonathan K. Kummerfeld, Kevin Leach, Michael A. Laurenzano,
+Lingjia Tang and Jason Mars, "An Evaluation Dataset for Intent Classification and
+Out-of-Scope Prediction", EMNLP 2019. Source: https://github.com/clinc/oos-eval —
+CC BY 3.0 (https://creativecommons.org/licenses/by/3.0/).
+
+Changes to both: verified extraction to id/text/label JSONL; collapsing of
+model-equivalent duplicates so no group crosses splits; dropping of conflicting
+labels; a deterministic calibration split from Banking77 training data; CLINC150
+out-of-scope test queries kept in a separate file. Original labels are retained.
+
+Optional Unsloth / Unsloth Zoo dependencies and the Qwen model retain their own
+licenses. No Unsloth implementation code or notebook content is copied into this
+repository. API integration does not relicense the upstream software. Consult the
+upstream licenses before redistribution or service deployment.

localdesk-0.3.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: localdesk
+Version: 0.3.0
+Summary: Calibrated text classification service that abstains when unsure: quality gates, immutable model registry, CPU TF-IDF and optional Qwen/Unsloth fine-tuning
+Project-URL: Homepage, https://github.com/denis-samatov/localdesk
+Project-URL: Documentation, https://github.com/denis-samatov/localdesk/tree/main/docs
+Project-URL: Changelog, https://github.com/denis-samatov/localdesk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/denis-samatov/localdesk/issues
+Author: Denis Samatov
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: abstention,calibration,fastapi,intent-detection,mlops,model-registry,selective-classification,text-classification,ticket-routing,unsloth
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Provides-Extra: baseline
+Requires-Dist: numpy<3,>=1.26; extra == 'baseline'
+Requires-Dist: scikit-learn<2,>=1.6; extra == 'baseline'
+Requires-Dist: scipy<2,>=1.13; extra == 'baseline'
+Provides-Extra: dev
+Requires-Dist: build==1.3.0; extra == 'dev'
+Requires-Dist: httpx2==2.13.1; extra == 'dev'
+Requires-Dist: pytest==8.4.2; extra == 'dev'
+Requires-Dist: ruff==0.13.3; extra == 'dev'
+Provides-Extra: service
+Requires-Dist: fastapi<1,>=0.115; extra == 'service'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'service'
+Description-Content-Type: text/markdown
+
+# LocalDesk
+
+**Train a text classifier that knows when it isn't sure, and ship it with receipts.**
+
+[![CI](https://github.com/denis-samatov/localdesk/actions/workflows/ci.yml/badge.svg)](https://github.com/denis-samatov/localdesk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/localdesk)](https://pypi.org/project/localdesk/)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/denis-samatov/localdesk/blob/main/LICENSE)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/denis-samatov/localdesk/blob/main/notebooks/benchmark_qwen.ipynb)
+
+LocalDesk turns a CSV or JSONL file and a JSON list of labels into a versioned,
+calibrated classification service that runs locally. It is built for routing:
+support tickets, intents, spam, triage queues. In those settings a confident
+wrong answer costs more than asking a human.
+
+- **Abstains instead of guessing.** Every prediction is either `route` or `review`,
+  based on calibrated confidence and the margin between the top two labels.
+- **Quality gates before deploy.** A version that misses your accuracy, macro-F1,
+  calibration or coverage thresholds cannot be promoted or served.
+- **Every version is reproducible and tamper-evident.** Each version is immutable
+  and pins the task, the data fingerprints, the report and the training plan with
+  SHA-256 checksums.
+- **CPU first, LLM when it pays off.** The default TF-IDF model trains in seconds,
+  reaches **91–99% accuracy on three of four public benchmarks**, and needs only the
+  Python standard library for inference. An optional Qwen + Unsloth LoRA recipe
+  gave a further **+5.7 pp accuracy** on the hardest one, real IT tickets.
+
+![LocalDesk operator dashboard](https://raw.githubusercontent.com/denis-samatov/localdesk/main/docs/service-demo.png)
+
+## Try it in 10 seconds
+
+The package ships with the TF-IDF demo model trained on real IT tickets
+(76.5% accuracy on the 524-ticket holdout, [report](https://github.com/denis-samatov/localdesk/blob/main/reports/demo.json)).
+Running a prediction has no runtime dependencies:
+
+```bash
+pip install localdesk
+localdesk predict "File share access request"
+localdesk predict "I can't open the shared finance folder"
+```
+
+A clear request is routed. An ambiguous one goes to a human with the reason
+attached (output abbreviated):
+
+```jsonc
+{"category": "Fileservice", "action": "route",  "probabilities": {"Fileservice": 0.999, ...}, "review_reasons": []}
+{"category": "Fileservice", "action": "review", "probabilities": {"Fileservice": 0.43, "Support general": 0.24, ...},
+ "review_reasons": ["low_confidence", "small_margin"]}
+```
+
+Run `localdesk serve` to open the same model in a local web page at `http://127.0.0.1:8765`.
+
+## Train on your own data (5 minutes)
+
+**1. Describe the task.** The labels are yours; nothing in the core is IT-specific.
+
+```json
+{
+  "id": "my-intents",
+  "version": "1",
+  "instructions": "Choose the intent of the message.",
+  "labels": {
+    "returns": "Requests to return a purchased item.",
+    "delivery": "Questions or problems with delivery.",
+    "other": "Other supported customer requests."
+  },
+  "min_confidence": 0.8,
+  "min_margin": 0.2
+}
+```
+
+**2. Point an experiment at your file and set the bar a model must clear.**
+
+```json
+{
+  "task": "my-task.json",
+  "dataset": {
+    "path": "my-records.csv",
+    "format": "csv",
+    "text_column": "message",
+    "label_column": "intent",
+    "id_column": "id"
+  },
+  "registry": "my-registry",
+  "training": {"backend": "tfidf"},
+  "gates": {"min_accuracy": 0.7, "min_macro_f1": 0.6, "max_ece": 0.1}
+}
+```
+
+**3. Validate, train, promote, serve.**
+
+```bash
+pip install 'localdesk[baseline,service]'   # training + HTTP API
+
+localdesk validate my-experiment.json            # checks labels, leakage, class support
+localdesk train my-experiment.json --run-id v1   # fit, calibrate, evaluate, gate
+localdesk runs --registry my-registry            # list versions and gate results
+localdesk promote v1 --registry my-registry      # refuses versions that failed gates
+localdesk api --registry my-registry --anonymous-local
+```
+
+Paths are relative to the experiment file. JSONL supports dotted fields such as
+`gold.category`, and you can supply explicit train/calibration/test files.
+Unknown labels, conflicting duplicates, groups that cross splits and typos in the
+configuration fail early with a clear message.
+
+## Results on real public data
+
+The same pipeline and commands on four public datasets. Only the configuration changes.
+Default `tfidf` backend, test sets never used for fitting or calibration:
+
+| Dataset | Labels | Test rows | Accuracy | Macro F1 | Auto-routed | Accuracy when routed |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| [IT Support Tickets](https://zenodo.org/records/7648117) | 6 | 524 | 76.5% | 72.9% | 60.5% | **92.4%** |
+| [UCI SMS Spam](https://archive.ics.uci.edu/dataset/228/sms+spam+collection) | 2 | 1,024 | 98.9% | 97.4% | 97.7% | **99.3%** |
+| [Banking77](https://github.com/PolyAI-LDN/task-specific-datasets) | 77 | 3,071 | 91.2% | 91.3% | 86.9% | **96.8%** |
+| [CLINC150](https://github.com/clinc/oos-eval) | 150 | 4,486 | 92.3% | 92.2% | 88.9% | **97.0%** |
+
+"Auto-routed" is the share of requests the model handled without a human under
+the task's fixed review policy, and "Accuracy when routed" is measured on those
+requests only. Compared with the legacy hashed baseline, TF-IDF adds 1.5–7.1 pp
+accuracy on every dataset and routes 2.6–16.4 pp more requests automatically
+([full comparison](https://github.com/denis-samatov/localdesk/blob/main/reports/cpu-suite.md)). Training takes 1–40 seconds on a laptop CPU.
+
+![Accuracy versus share of requests handled automatically](https://raw.githubusercontent.com/denis-samatov/localdesk/main/docs/risk-coverage.svg)
+
+The fewer requests the model takes, the more accurate it gets. On Banking77,
+TF-IDF keeps 95% accuracy on its most confident 93% of queries; the old baseline
+holds that accuracy on only 84%. These curves are read off the test sets: use them
+to choose a policy, then confirm it on your own data.
+
+**Queries outside every label.** CLINC150 includes 1,000 test queries that match
+none of its 150 intents and are never seen in training. Under the default policy,
+**85% of them go to human review** instead of receiving a wrong intent.
+
+To reproduce from a clone of this repository (the scripts download and checksum
+the public data):
+
+```bash
+pip install -e '.[baseline]'
+python scripts/prepare_data.py && python scripts/prepare_sms.py
+python scripts/prepare_banking77.py && python scripts/prepare_clinc150.py
+python scripts/publish_cpu_suite.py   # both CPU backends on all four datasets
+```
+
+**Fine-tuned Qwen vs classic baselines** (same 524 IT test rows, free Colab T4):
+
+| Method | Accuracy | Macro F1 | p50 latency |
+| --- | ---: | ---: | ---: |
+| Qwen 3.5 4B + LoRA (LocalDesk recipe) | **82.8%** | **80.6%** | 389 ms |
+| TF-IDF + SVM (tuned) | 77.1% | 73.5% | 1.8 ms |
+| TF-IDF + logistic regression | 77.7% | 74.0% | 2.1 ms |
+| Qwen 3.5 4B zero-shot | 55.3% | 54.1% | 251 ms |
+
+The accuracy gain over the SVM is +5.73 pp, with a paired-bootstrap 95% CI of
+[+2.48, +9.16] pp. Macro-F1 gain is +7.06 pp, with a 95% CI of [+3.31, +11.10] pp.
+Full protocol: [docs/BENCHMARK.md](https://github.com/denis-samatov/localdesk/blob/main/docs/BENCHMARK.md) · report:
+[reports/comparison-colab-it.md](https://github.com/denis-samatov/localdesk/blob/main/reports/comparison-colab-it.md) ·
+run it yourself: [Colab notebook](https://colab.research.google.com/github/denis-samatov/localdesk/blob/main/notebooks/benchmark_qwen.ipynb).
+
+These are reused public holdouts, not a field trial. Measure on your own data
+before relying on the numbers. [docs/VALIDATION.md](https://github.com/denis-samatov/localdesk/blob/main/docs/VALIDATION.md) lists
+exactly what was and wasn't verified.
+
+## How it works
+
+```mermaid
+flowchart LR
+  C[Task + experiment JSON] --> D[CSV / JSONL intake]
+  D --> V[Validate labels, group duplicates, isolate splits]
+  V --> T[Train: CPU TF-IDF or Qwen LoRA]
+  T --> K[Calibrate on a separate split]
+  K --> E[Evaluate on untouched test]
+  E --> G{Quality gates}
+  G -->|pass| R[Immutable version in registry]
+  G -->|fail| X[Kept for inspection, never served]
+  R --> P[promote / rollback]
+  P --> A[HTTP API + dashboard]
+```
+
+- **No leakage by construction.** Records that share a conversation or produce
+  identical model features are grouped together, and a group never spans
+  train/calibration/test.
+- **Training and serving are separate processes.** The HTTP API cannot upload
+  data, train or promote; it only answers predictions. Operators use the CLI.
+- **Promotion is an atomic pointer swap.** Rollback is `localdesk promote <older-run>`.
+  Workers verify every checksum on startup.
+
+More detail: [architecture and contracts](https://github.com/denis-samatov/localdesk/blob/main/docs/ARCHITECTURE.md) ·
+[training plan](https://github.com/denis-samatov/localdesk/blob/main/docs/TRAINING_PLAN.md).
+
+## HTTP API
+
+```bash
+export LOCALDESK_API_KEY=change-me
+localdesk api --registry my-registry          # or: docker compose up --build -d
+
+curl http://127.0.0.1:8765/v1/predictions \
+  -H "X-API-Key: $LOCALDESK_API_KEY" -H 'Content-Type: application/json' \
+  -d '{"text": "Where is my parcel?"}'
+```
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /v1/predictions`, `POST /v1/predictions/batch` | Decision, probabilities, model version and task hash |
+| `GET /v1/model`, `/v1/model/report`, `/v1/model/plan` | Active labels, measured quality, gates and training plan |
+| `GET /health/live`, `/health/ready` | Liveness; readiness only when a qualified model is loaded |
+| `GET /metrics` | Prometheus counters (no request bodies are logged) |
+
+Inference requests are queued and run one at a time, so a single process can
+safely hold a GPU model. The API key is compared in constant time, bodies are
+size- and time-limited, and anonymous mode accepts only loopback hosts and
+origins. The Docker setup runs as a non-root user with a read-only filesystem
+and models mounted read-only. See the [runbook](https://github.com/denis-samatov/localdesk/blob/main/docs/RUNBOOK.md).
+
+## Fine-tune Qwen with Unsloth (optional, CUDA)
+
+Swap the `training` block and keep the rest of the pipeline:
+
+```json
+"training": {"backend": "unsloth", "epochs": 2, "rank": 16, "batch_size": 2,
+             "gradient_accumulation": 4, "learning_rate": 0.0002}
+```
+
+The classification head is built from your label descriptions. Upstream
+revisions are pinned in `requirements-gpu.txt`. Training stops on skipped or
+truncated examples instead of silently degrading. Setup: [docs/TRAINING.md](https://github.com/denis-samatov/localdesk/blob/main/docs/TRAINING.md).
+GPU serving details: [docs/GPU_HTTP.md](https://github.com/denis-samatov/localdesk/blob/main/docs/GPU_HTTP.md).
+
+## Status
+
+LocalDesk is **v0.2, early but tested**. CI runs lint, formatting, the test suite,
+package build and a CLI smoke test on Linux, macOS and Windows with Python 3.11,
+3.12 and 3.13.
+
+Current scope is single-label text classification on a single node. Not included
+yet: multi-label targets, a hosted Qwen checkpoint you can download, multi-tenant
+isolation, and hot-swapping models without a restart.
+
+## Development
+
+```bash
+git clone https://github.com/denis-samatov/localdesk.git && cd localdesk
+uv sync --frozen --extra dev --extra baseline --extra service
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+```
+
+Issues and pull requests are welcome. Please include a test for any change in behaviour.
+
+## Documentation
+
+[Architecture](https://github.com/denis-samatov/localdesk/blob/main/docs/ARCHITECTURE.md) · [Runbook & API](https://github.com/denis-samatov/localdesk/blob/main/docs/RUNBOOK.md) ·
+[Datasets & provenance](https://github.com/denis-samatov/localdesk/blob/main/docs/DATASETS.md) · [Training](https://github.com/denis-samatov/localdesk/blob/main/docs/TRAINING.md) ·
+[Benchmark protocol](https://github.com/denis-samatov/localdesk/blob/main/docs/BENCHMARK.md) · [GPU HTTP check](https://github.com/denis-samatov/localdesk/blob/main/docs/GPU_HTTP.md) ·
+[Validation evidence](https://github.com/denis-samatov/localdesk/blob/main/docs/VALIDATION.md)
+
+## По-русски
+
+LocalDesk превращает CSV/JSONL и список меток в калиброванный сервис классификации
+текста с версиями и порогами качества. Модель отвечает «маршрутизировать» или
+«на ручной разбор», если не уверена. Ядро не привязано к домену: меняются только
+JSON-описание задачи и датасет. Обучение на CPU занимает секунды. Дообучение
+Qwen через Unsloth дало +5,7 п.п. точности к сильному TF-IDF baseline на реальных
+IT-заявках. На четырёх публичных датасетах (IT-заявки, SMS, Banking77, CLINC150)
+CPU-модель по умолчанию даёт от 76,5% до 98,9% точности, а 85% запросов вне всех
+категорий отправляет на ручной разбор. Качество на других языках и в других организациях нужно измерять
+отдельно.
+
+## License
+
+Code and notebooks: [MIT](https://github.com/denis-samatov/localdesk/blob/main/LICENSE). The bundled demo model and benchmarks use
+public datasets under CC BY 4.0; attribution is in [NOTICE.md](https://github.com/denis-samatov/localdesk/blob/main/NOTICE.md).
+Optional dependencies and model weights keep their own licenses.