Guides — pick your path

Eight common jobs, one foundry. Select yours: every card below states who it is for, the minimal command, what you get, and the limitation you should know before you start. Tabs work from the keyboard (arrow keys) and without JavaScript.

PDF → SFT Preference / DPO KTO Grounded eval set MCP agents Fully offline Team deployment Hugging Face

Who it's for: ML engineers turning permitted PDFs — handbooks, manuals, papers — into supervised fine-tuning data.

knovaryn run --project proj_… \
  --family factual_explanation:1.0 --target 200
knovaryn dataset export proj_… --format openai_chat

Expected result: an SFT dataset (JSONL, Parquet, TRL, OpenAI chat…) whose every accepted example carries evidence references back to source spans — Docling-parsed PDFs yield exact_page/exact_bbox precision.

Limitation: PDF parsing uses the optional docling extra; scanned documents depend on OCR quality.

Full guide →

Who it's for: alignment practitioners building DPO datasets where the rejected response is meaningfully wrong, not trivially separable.

# start a pipeline with a preference topology, then:
knovaryn dataset export proj_… --format trl_preference

Expected result: (prompt, chosen, rejected) triples grounded in permitted sources, rejected responses produced with a controlled negative strategy and their defect recorded — so pairs teach something and stay auditable.

Limitation: defect labels make review efficient; they don't remove the need to spot-check pairs yourself.

Full guide →

Who it's for: teams using KTO's simpler signal — desirable/undesirable labels instead of paired responses.

knovaryn dataset export proj_… --format kto

Expected result: a KTO-format export from the same canonical, provenance-linked dataset version you would ship anywhere else — same gates, same evidence chain.

Limitation: KTO wants a sensible desirable/undesirable balance; the balancer helps, but policy thresholds are yours to choose.

Preference-data guidance →

Who it's for: evaluation leads building QA sets where every answer must be supported by persisted evidence.

# start a pipeline with an evaluation (grounded QA) topology, then:
knovaryn dataset export proj_… --format evaluation

Expected result: question/answer examples that only export if the answer resolves through lineage to evidence in a permitted source document; ungrounded rows are quarantined with reason codes.

Limitation: coverage follows your sources — questions can only be as good as the corpus behind them.

Full guide →

Who it's for: agent developers who want dataset tooling callable from Claude Desktop, an IDE agent, or any MCP client.

knovaryn mcp          # stdio transport for local clients
knovaryn mcp --transport streamable-http --port 8080

Expected result: the full tool catalogue — projects, sources, estimates, pipelines, lineage walks, reviews, versions, exports — driven conversationally; compatibility tested against MCP SDK 1.x and 2.x (ADR-0007).

Limitation: the server binds locally by default; exposing it beyond localhost requires the hardening checklist.

Full guide →

Who it's for: anyone with privacy constraints, an air-gapped machine, or just no provider account yet.

pip install knovaryn
knovaryn demo --examples 20 --json

Expected result: the entire loop — ingest, parse, generate, gate, version, export — on bundled samples via the deterministic fake provider. No API keys, no network, byte-for-byte reproducible.

Limitation: fake-provider output proves plumbing, not training signal; real datasets need a real endpoint.

Ten-minute quickstart →

Who it's for: platform/data teams running one shared Knovaryn instance for many contributors.

docker compose -f deploy/compose/compose.prod.yaml up

Expected result: PostgreSQL + S3-compatible storage behind the API, worker pool, and web console — with authentication scopes, tenancy, and per-principal rate limiting; the same application core as single-machine mode.

Limitation: you operate it: backups, upgrades, and secrets are your responsibility (restore is tested — see the backup runbook).

Deployment profiles →

Who it's for: anyone who wants to drive the loop from a browser — no CLI required.

knovaryn server    # http://127.0.0.1:8080 — local-only by default

Expected result: the local web console: create projects and sources, queue pipelines, read quality reports, apply reviews, and export — every button calling the same REST control plane the CLI uses. The header's health/auth status is always visible, the layout reflows to a single column on phones, and the theme follows your system's light/dark preference.

Limitation: the console is a local operator surface; it binds to loopback unless you follow the hardening checklist.

See it in the quickstart →

Who it's for: teams publishing curated datasets to the Hugging Face Hub with provenance intact.

pip install "knovaryn[hub]"
knovaryn dataset publish proj_… org/dataset-name    # dry-run by default

Expected result: a Hub-friendly export of the frozen version plus a staged publish with dataset card and provenance — nothing reaches the Hub unless you explicitly authorize it.

Limitation: the license report that gates publication records rights; it is not legal clearance.

Full guide →

All guides

Guide	What it covers
Quickstart	Full offline loop in ~10 minutes, no API keys
First real project	A real provider, budgets, and a production-shaped run
PDF to SFT dataset	Permitted PDFs → gated instruction data
Build DPO preference data	Grounded, controlled-negative preference pairs
Grounded QA datasets	Evidence-backed evaluation data
MCP clients	Drive everything from an MCP client
MCP training-data server	Serving datasets to training agents over MCP
Hugging Face export	Hub layout + dry-run-by-default publish