laya-cli 0.1.0__tar.gz

laya_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install (no heavy ML deps for mocked tests)
+        run: |
+          uv sync --group test
+          # For mocked tests we don't need the real torch/laya weights;
+          # uv sync already installed deps, but tests mock laya.
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format
+        run: uv run ruff format --check .
+      - name: Tests (mocked, no model download)
+        run: uv run pytest --cov --cov-report=term-missing
+
+  test-real-model:
+    runs-on: ubuntu-latest
+    if: contains(github.event.head_commit.message, '[real-model]')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync
+      - run: uv run pytest -m slow --cov --cov-report=term-missing

laya_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_USERNAME: __token__
+          UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

laya_cli-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.whl
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Mypy, Ruff
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# HF cache / models (do not commit weights)
+models/
+*.safetensors
+*.bin
+
+# Local
+.env
+*.log
+tmp/

laya_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

laya_cli-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License 2.0
+
+Copyright (c) 2026 laya-cli contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Upstream Laya is Apache-2.0 by Convai Innovations (https://github.com/NandhaKishorM/laya).

laya_cli-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: laya-cli
+Version: 0.1.0
+Summary: Ergonomic CLI for Laya — typed decisions for humans and AI agents (predict, batch, presets, shortlist, router)
+Project-URL: Homepage, https://github.com/MIt9/laya-cli
+Project-URL: Repository, https://github.com/MIt9/laya-cli.git
+Project-URL: Issues, https://github.com/MIt9/laya-cli/issues
+Author: MIt9
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,cli,decision-model,guardrails,laya,router,triage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.20.0
+Requires-Dist: laya>=0.3.4
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: safetensors>=0.4.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: transformers>=4.48.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ✨ Laya CLI (`laya-cli`)
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Built with uv](https://img.shields.io/badge/built%20with-uv-purple.svg)](https://github.com/astral-sh/uv)
+
+A modern, high-performance CLI for [Laya](https://github.com/NandhaKishorM/laya) — **typed decisions** (`choice`/`score`/`noul`) in one forward pass, designed for **Humans** (Rich table output) and **AI Agents / Classifiers** (Machine-readable `--json` & JSONL).
+
+---
+
+## ⚡ Key Features
+
+* 🤖 **Typed Decisions in One Pass**: `choice` (top label + probs), `score` (ordinal), `noul` (P(true)) — no generation, no hallucination, ~33ms on T4, 7ms/q batched
+* 🧭 **Router-Aware Multilingual**: `laya.Router(preload=True)` auto-detects script/language in <0.5ms and dispatches to `laya` (English, 512 ctx) vs `laya-multilingual` (100+ langs, 1024 ctx); warns if `--router` without `--lang`
+* 🧹 **Embedding Shortlist for High-Cardinality**: `--shortlist-k 20` via `laya.predict_shortlist` + `embed_fn_from_agent` (Banking77 77 opts → 3 tokens/opt without shortlist → shortlist fixes)
+* 🔍 **Preset Library**: `triage` / `email` / `guard` / `moderation` / `router` — direct `laya.*_questions()` passthrough, mergeable with `--questions file.json` and `--questions-inline`
+* 📦 **Streaming Batch Mode**: `classify`/`predict --input` loads model **once** + warmup, streams JSONL (`--state-field` verbatim, no silent `(photographer: Name)` injection)
+* 🔧 **Post-Filter & Eval**: `filter --where "on_topic>=0.4" --sort -on_topic` and `evaluate` (accuracy, passing @ threshold, precision, escalation rate)
+
+---
+
+## 🚀 Global Installation
+
+### Option 1: Install globally via `uv` (Recommended)
+
+```bash
+uv tool install laya-cli
+```
+
+### Option 2: Install via `pip` / `pipx`
+
+```bash
+pipx install laya-cli
+# or
+pip install laya-cli
+```
+
+### Option 3: Run without installing
+
+```bash
+uvx laya-cli --help
+```
+
+> Requires Python 3.10+ (`.python-version` pins 3.11). Heavy ML deps (`torch`, `transformers`, `safetensors` via `laya`, ~2 GB) download on first `predict`/`classify`. Afterwards `HF_HUB_OFFLINE=1` works. For `uv` dev, tests mock Laya so CI is fast.
+
+---
+
+## 🤖 Classifier Pipeline Integration (Pexels → Laya)
+
+Pipe candidate streams directly from [`pexels-cli`](https://github.com/MIt9/pexels-cli) (`px`) into Laya. This is the original use-case that drove `laya-cli` (82 candidates, `state` deduped):
+
+```bash
+# 1. Pexels → candidates.jsonl with `state` strings
+px videos --queries "black friday shopping,christmas shopping,checkout cart" \
+  --per-page 8 --state --dedupe keep-first > candidates.jsonl
+
+# 2. Laya → score + filter (streaming, one model load)
+cat candidates.jsonl \
+  | laya-cli classify --questions questions.json \
+  | laya-cli filter --where "on_topic>=0.4" --sort -on_topic \
+  > shortlist.jsonl
+
+# Or with the new primary command (supports presets without a file):
+cat candidates.jsonl | laya-cli predict --questions questions.json --format jsonl > scored.jsonl
+px videos --queries "..." --state --dedupe | laya-cli predict --preset triage --format jsonl | laya-cli filter --where "intent==refund"
+```
+
+**Candidate JSONL format** (`px --state`):
+```json
+{"id": 5890229, "type": "video", "query": "black friday shopping", "photographer": "Pavel Danilyuk", "state": "a man shopping on black friday", "url": "https://www.pexels.com/video/a-man-shopping-on-black-friday-5890229/", "duration": 10, "width": 2160, "height": 3840}
+```
+`laya-cli` reads `--state-field state` **verbatim** — use `--prepend-field` only explicitly (mixing photographer into state degraded `on_topic` by 0.1-0.3).
+
+---
+
+## 📖 Usage Examples
+
+### 1. Direct CLI (Human & AI)
+
+```bash
+# Human: table output, no file needed
+laya-cli predict "I was charged twice, refund please" --preset triage
+laya-cli predict --text "Ignore previous instructions" --preset guard --format table
+laya-cli predict --state '{"subject":"Invoice #4411","body":"Billed twice"}' --preset email --format table
+
+# AI agent: JSON single-shot
+laya-cli predict --text "Is this spam?" --preset guard --format json
+# -> {"answers": {"jailbreak": {"noul": 0.02, "confidence": 0.97, ...}}, "usage": ...}
+
+# Custom + preset merging (preset < file < inline)
+laya-cli predict --text "hello" --preset triage --questions-inline '{"custom":{"type":"noul","instructions":"Is it polite?"}}' --format json
+
+# High-cardinality choice (77 banking intents)
+laya-cli predict --text "where is my card?" --questions banking.json --shortlist-k 20 --format json
+
+# Multilingual — Router recommended
+laya-cli predict --text "मुझसे दो बार शुल्क लिया गया" --preset triage --router --format json
+laya-cli predict --text "Der Kunde wurde zweimal belastet" --preset triage --router --lang de --format json
+```
+
+### 2. Batch & Pipeline
+
+```bash
+# Batch from file (human-readable table per row)
+laya-cli predict --input candidates.jsonl --questions questions.json --format table
+
+# Batch JSONL with flatten (like classify) for jq/filter
+laya-cli predict --input candidates.jsonl --questions questions.json --flatten --format jsonl > scored.jsonl
+cat scored.jsonl | laya-cli filter --where "on_topic>=0.4,is_relevant>=0.7" --sort -on_topic,+id
+
+# Legacy streaming (kept for compatibility):
+cat candidates.jsonl | laya-cli classify --questions questions.json | laya-cli filter --where "on_topic>=0.4" --sort -on_topic > shortlist.jsonl
+```
+
+### 3. Presets & Info
+
+```bash
+laya-cli questions list --format table
+laya-cli questions triage > questions.json      # also: email, guard, moderation, router
+laya-cli presets guard | laya-cli predict --text "test" --questions /dev/stdin
+
+laya-cli info                                    # python/torch/cuda/mps + cache
+laya-cli evaluate --questions questions.json --labeled labeled.jsonl --label-field label --threshold 0.5
+```
+
+---
+
+## 🛠 Development
+
+```bash
+uv sync --group dev          # hatchling + ruff/mypy/pytest
+uv run ruff check .          # lint (E/F/W/I, line-length 120)
+uv run ruff format .         # format
+uv run pytest -q             # 26 tests, mocked laya (no model download)
+uv run pytest --cov=src/laya_cli --cov-report=term-missing
+uv build                     # hatchling -> dist/*.whl + sdist (src/ layout)
+```
+
+Repo layout: `src/laya_cli/`, `tests/`, `pyproject.toml` (hatchling + `dependency-groups`), `uv.lock`, `.python-version` 3.11, `.github/workflows/ci.yml` + `publish.yml`.
+
+---
+
+## 📄 License
+
+Apache-2.0 — same as [Laya](https://github.com/NandhaKishorM/laya) upstream. See [LICENSE](LICENSE).
+
+This project is not affiliated with Convai Innovations. Laya weights are Apache-2.0 and hosted on Hugging Face (`convaiinnovations/laya`).

laya_cli-0.1.0/README.md

@@ -0,0 +1,147 @@
+# ✨ Laya CLI (`laya-cli`)
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Built with uv](https://img.shields.io/badge/built%20with-uv-purple.svg)](https://github.com/astral-sh/uv)
+
+A modern, high-performance CLI for [Laya](https://github.com/NandhaKishorM/laya) — **typed decisions** (`choice`/`score`/`noul`) in one forward pass, designed for **Humans** (Rich table output) and **AI Agents / Classifiers** (Machine-readable `--json` & JSONL).
+
+---
+
+## ⚡ Key Features
+
+* 🤖 **Typed Decisions in One Pass**: `choice` (top label + probs), `score` (ordinal), `noul` (P(true)) — no generation, no hallucination, ~33ms on T4, 7ms/q batched
+* 🧭 **Router-Aware Multilingual**: `laya.Router(preload=True)` auto-detects script/language in <0.5ms and dispatches to `laya` (English, 512 ctx) vs `laya-multilingual` (100+ langs, 1024 ctx); warns if `--router` without `--lang`
+* 🧹 **Embedding Shortlist for High-Cardinality**: `--shortlist-k 20` via `laya.predict_shortlist` + `embed_fn_from_agent` (Banking77 77 opts → 3 tokens/opt without shortlist → shortlist fixes)
+* 🔍 **Preset Library**: `triage` / `email` / `guard` / `moderation` / `router` — direct `laya.*_questions()` passthrough, mergeable with `--questions file.json` and `--questions-inline`
+* 📦 **Streaming Batch Mode**: `classify`/`predict --input` loads model **once** + warmup, streams JSONL (`--state-field` verbatim, no silent `(photographer: Name)` injection)
+* 🔧 **Post-Filter & Eval**: `filter --where "on_topic>=0.4" --sort -on_topic` and `evaluate` (accuracy, passing @ threshold, precision, escalation rate)
+
+---
+
+## 🚀 Global Installation
+
+### Option 1: Install globally via `uv` (Recommended)
+
+```bash
+uv tool install laya-cli
+```
+
+### Option 2: Install via `pip` / `pipx`
+
+```bash
+pipx install laya-cli
+# or
+pip install laya-cli
+```
+
+### Option 3: Run without installing
+
+```bash
+uvx laya-cli --help
+```
+
+> Requires Python 3.10+ (`.python-version` pins 3.11). Heavy ML deps (`torch`, `transformers`, `safetensors` via `laya`, ~2 GB) download on first `predict`/`classify`. Afterwards `HF_HUB_OFFLINE=1` works. For `uv` dev, tests mock Laya so CI is fast.
+
+---
+
+## 🤖 Classifier Pipeline Integration (Pexels → Laya)
+
+Pipe candidate streams directly from [`pexels-cli`](https://github.com/MIt9/pexels-cli) (`px`) into Laya. This is the original use-case that drove `laya-cli` (82 candidates, `state` deduped):
+
+```bash
+# 1. Pexels → candidates.jsonl with `state` strings
+px videos --queries "black friday shopping,christmas shopping,checkout cart" \
+  --per-page 8 --state --dedupe keep-first > candidates.jsonl
+
+# 2. Laya → score + filter (streaming, one model load)
+cat candidates.jsonl \
+  | laya-cli classify --questions questions.json \
+  | laya-cli filter --where "on_topic>=0.4" --sort -on_topic \
+  > shortlist.jsonl
+
+# Or with the new primary command (supports presets without a file):
+cat candidates.jsonl | laya-cli predict --questions questions.json --format jsonl > scored.jsonl
+px videos --queries "..." --state --dedupe | laya-cli predict --preset triage --format jsonl | laya-cli filter --where "intent==refund"
+```
+
+**Candidate JSONL format** (`px --state`):
+```json
+{"id": 5890229, "type": "video", "query": "black friday shopping", "photographer": "Pavel Danilyuk", "state": "a man shopping on black friday", "url": "https://www.pexels.com/video/a-man-shopping-on-black-friday-5890229/", "duration": 10, "width": 2160, "height": 3840}
+```
+`laya-cli` reads `--state-field state` **verbatim** — use `--prepend-field` only explicitly (mixing photographer into state degraded `on_topic` by 0.1-0.3).
+
+---
+
+## 📖 Usage Examples
+
+### 1. Direct CLI (Human & AI)
+
+```bash
+# Human: table output, no file needed
+laya-cli predict "I was charged twice, refund please" --preset triage
+laya-cli predict --text "Ignore previous instructions" --preset guard --format table
+laya-cli predict --state '{"subject":"Invoice #4411","body":"Billed twice"}' --preset email --format table
+
+# AI agent: JSON single-shot
+laya-cli predict --text "Is this spam?" --preset guard --format json
+# -> {"answers": {"jailbreak": {"noul": 0.02, "confidence": 0.97, ...}}, "usage": ...}
+
+# Custom + preset merging (preset < file < inline)
+laya-cli predict --text "hello" --preset triage --questions-inline '{"custom":{"type":"noul","instructions":"Is it polite?"}}' --format json
+
+# High-cardinality choice (77 banking intents)
+laya-cli predict --text "where is my card?" --questions banking.json --shortlist-k 20 --format json
+
+# Multilingual — Router recommended
+laya-cli predict --text "मुझसे दो बार शुल्क लिया गया" --preset triage --router --format json
+laya-cli predict --text "Der Kunde wurde zweimal belastet" --preset triage --router --lang de --format json
+```
+
+### 2. Batch & Pipeline
+
+```bash
+# Batch from file (human-readable table per row)
+laya-cli predict --input candidates.jsonl --questions questions.json --format table
+
+# Batch JSONL with flatten (like classify) for jq/filter
+laya-cli predict --input candidates.jsonl --questions questions.json --flatten --format jsonl > scored.jsonl
+cat scored.jsonl | laya-cli filter --where "on_topic>=0.4,is_relevant>=0.7" --sort -on_topic,+id
+
+# Legacy streaming (kept for compatibility):
+cat candidates.jsonl | laya-cli classify --questions questions.json | laya-cli filter --where "on_topic>=0.4" --sort -on_topic > shortlist.jsonl
+```
+
+### 3. Presets & Info
+
+```bash
+laya-cli questions list --format table
+laya-cli questions triage > questions.json      # also: email, guard, moderation, router
+laya-cli presets guard | laya-cli predict --text "test" --questions /dev/stdin
+
+laya-cli info                                    # python/torch/cuda/mps + cache
+laya-cli evaluate --questions questions.json --labeled labeled.jsonl --label-field label --threshold 0.5
+```
+
+---
+
+## 🛠 Development
+
+```bash
+uv sync --group dev          # hatchling + ruff/mypy/pytest
+uv run ruff check .          # lint (E/F/W/I, line-length 120)
+uv run ruff format .         # format
+uv run pytest -q             # 26 tests, mocked laya (no model download)
+uv run pytest --cov=src/laya_cli --cov-report=term-missing
+uv build                     # hatchling -> dist/*.whl + sdist (src/ layout)
+```
+
+Repo layout: `src/laya_cli/`, `tests/`, `pyproject.toml` (hatchling + `dependency-groups`), `uv.lock`, `.python-version` 3.11, `.github/workflows/ci.yml` + `publish.yml`.
+
+---
+
+## 📄 License
+
+Apache-2.0 — same as [Laya](https://github.com/NandhaKishorM/laya) upstream. See [LICENSE](LICENSE).
+
+This project is not affiliated with Convai Innovations. Laya weights are Apache-2.0 and hosted on Hugging Face (`convaiinnovations/laya`).

laya_cli-0.1.0/TASK.md

@@ -0,0 +1,128 @@
+# laya-cli — задача на реалізацію
+
+## Навіщо
+
+Зараз щоразу, коли треба класифікувати список кандидатів (текстів/футажу/тікетів) через
+[Laya](https://github.com/NandhaKishorM/laya) (`pip install laya`, non-generative typed-decision
+модель), пишеться одноразовий python-скрипт: завантажити модель, прогнати цикл `agent.predict()`,
+зібрати результат, відсортувати/відфільтрувати, відформатувати звіт. Реальний кейс, з якого
+виросла ця задача: відбір стокового відео (Pexels, через `px` CLI) під відео-епізод — 82
+кандидати, кожен з коротким текстовим описом (`state`), треба відфільтрувати релевантні.
+
+Мета — винести цю повторювану частину в окремий CLI (`laya-cli`), який приймає JSONL на stdin
+(кожен рядок — кандидат з текстовим полем), питання в JSON-файлі, і віддає JSONL з доданими
+відповідями на stdout. Стрімовий Unix-style інструмент, що ставиться в пайплайн з будь-чим,
+що вміє JSONL (наприклад `px videos --state`).
+
+```bash
+px videos --queries "..." --state --dedupe keep-first \
+  | laya-cli classify --questions questions.json \
+  | laya-cli filter --where "on_topic>=0.4" --sort -on_topic \
+  > scored.jsonl
+```
+
+Референс по тому, як правильно юзати Laya (питання, чекпоінти, калібрація, пастки) —
+`~/.claude/skills/laya-integration/SKILL.md` на цій машині. Реалізація мусить слідувати
+принципам звідти, не вигадувати заново.
+
+## Технічна база
+
+- Python, `pip install laya` як залежність (тягне torch/transformers — важке, тому окремий
+  проєкт, а не додаток до легких CLI типу px).
+- `laya.load("convaiinnovations/laya", subfolder=...)` для конкретного чекпоінта,
+  `laya.Router(preload=True)` коли треба авто-вибір мови/чекпоінта.
+- Модель вантажиться **один раз** на весь запуск CLI, не на кожен рядок вводу. Перший виклик
+  після завантаження — прогрів (throwaway `predict`) перед основним циклом, це у skill описано
+  explicitно ("Warm up").
+
+## Команди
+
+### `laya-cli classify --questions <file.json> [--state-field state] [--model ...] [--lang ...] [--device ...]`
+
+- Читає JSONL з stdin, рядок за рядком.
+- Для кожного рядка бере текст з поля `--state-field` (дефолт `state`) **як є, без жодних
+  домішок** — не конкатенувати нічого свого до цього тексту. Урок з реального кейсу: коли
+  джерело (px) саме собі домішало `(photographer: Ім'я)` в текст, on_topic-скор Laya падав
+  на 0.1-0.3 на тих самих кадрах (виміряно). Цей інструмент не повторює ту помилку і не додає
+  нічого до `state` мовчки. Якщо хтось хоче domішати контекст — окремий явний флаг
+  `--prepend-field <name>` (не дефолт, задокументувати ризик у `--help`).
+- `--questions file.json` — той самий словник, що приймає `agent.predict(state, questions)`
+  (типи `choice`/`score`/`noul`, кожне питання — `type`, `instructions`, `criteria`). Формат
+  identичний до того, що описано в SKILL.md, ніякого власного DSL зверху.
+- Виводить у stdout той самий вхідний об'єкт + додані поля з відповідей: для `choice` —
+  `{question_id}` = обране значення, `{question_id}_p` = ймовірність обраного,
+  `{question_id}_probs` = весь розподіл (опційно, за `--full-probs`, дефолт вимкнено щоб не
+  роздувати рядки); для `score` — `{question_id}_score`; для `noul` — `{question_id}` = P(true).
+  `{question_id}_confidence` завжди додається.
+- `--model` — hf repo id, дефолт `convaiinnovations/laya` (English checkpoint).
+- `--subfolder` — `multilingual` / `typed-decisions` / порожньо (bundle).
+- `--lang` — примусова мова для `laya.Router` (якщо заданий `--router`); без цього флагу
+  Router сам детектить мову, а на мовах поза {en,fr,de,es,pt,it,nl} мовчки лягає на English
+  checkpoint — тому CLI мусить **попереджати в stderr**, коли `--router` активний і `--lang`
+  не заданий, з посиланням на це обмеження (SKILL.md розділ "Router").
+- `--device` — `cpu`/`mps`/`cuda`, прокидається напряму в `laya.load(device=...)`.
+- Concurrency: сам CLI однопотоковий по дизайну (один процес, послідовний цикл по stdin) —
+  жодних тредів/asyncio, це не потрібно й лише ускладнить lock-семантику з skill
+  ("guard predict with a lock, one GPU serves one forward pass at a time").
+
+### `laya-cli filter --where "<expr>" [--sort -field,+field2]`
+
+- Легкий пост-фільтр/сортувальник над JSONL з stdout команди `classify` (або будь-яким JSONL
+  з числовими полями). `--where` — прості порівняння (`field>=0.4`, `field==value`,
+  `field!=value`), можна кілька через кому (AND). `--sort` — список полів, `-` префікс = desc.
+- Це заміняє ручний python-скрипт сортування/фільтрації, який я сам писав під кожен кейс
+  (`build_shortlist*.py`).
+- Не вигадувати повноцінну query-мову (jq вже існує для складного) — тільки прості
+  порівняння, найчастіший випадок.
+
+### `laya-cli questions <preset>`
+
+- Друкує в stdout готовий `questions.json` з вбудованих пресетів Laya:
+  `triage`, `email`, `guard`, `moderation`, `router` — прямий прокид
+  `laya.triage_questions()` / `laya.email_questions()` / `laya.guard_questions()` /
+  `laya.moderation_questions()` / `laya.router_questions()` у JSON, щоб було з чого стартувати
+  й відредагувати руками, а не читати python-докстрінги.
+
+### `laya-cli evaluate --questions <file.json> --labeled <file.jsonl> --field <question_id>`
+
+- Реалізація розділу skill "Evaluate before shipping": вхід — JSONL з `state` +
+  колонкою правильної відповіді (`--label-field`, дефолт `label`), прогонити класифікацію,
+  порахувати accuracy per question, скільки % проходить поріг (`--threshold`, дефолт 0.5) і
+  скільки з тих, що пройшли, правильні (precision @ threshold). Вивід — короткий текстовий
+  звіт у stdout (не JSONL), саме той, що треба показати юзеру перед тим як довіряти цифрам
+  ("Tell the user the measured numbers and the escalation rate, not just that it works" —
+  пряма цитата зі skill).
+- Це не про калібрацію температури (то окремо, нижче) — це про "чи взагалі working" на
+  реальних прикладах юзера, мінімальний обов'язковий крок перед тим, як шортлист комусь
+  показати.
+
+## Explicitly НЕ в MVP (не робити, поки не попросять)
+
+- Калібрація температури (`agent.temperature` fit під NLL) — skill описує процедуру, це
+  окрема команда `laya-cli calibrate`, але вона складніша (потребує NLL-оптимізацію,
+  тестовий split) — робити тільки якщо `evaluate` покаже, що calibration реально потрібна.
+  Не будувати наперед.
+- HTTP-сервер / sidecar-режим (skill згадує FastAPI-приклад для не-python стеків) — YAGNI,
+  поки немає не-python консюмера. `classify` як stdin/stdout CLI покриває поточний кейс
+  (px | laya-cli).
+- Власна DB/кеш результатів між запусками — CLI stateless, вхід/вихід через JSONL-файли,
+  версіонування кешу — задача того, хто його викликає (git, файли в проєкті).
+- Multi-model ensemble / голосування кількох чекпоінтів — не було в жодному реальному кейсі.
+
+## Acceptance criteria
+
+- [ ] `laya-cli classify` не додає нічого до тексту `state` за замовчуванням (перевірити на
+      прикладі: вхід і те, що фактично йде в `agent.predict`, ідентичні substring).
+- [ ] Модель вантажиться рівно раз за запуск (лог/таймер підтверджує — не 82 завантаження на
+      82 рядки).
+- [ ] `classify | filter --where "on_topic>=0.4" --sort -on_topic` відтворює той самий
+      результат, що я зараз отримую вручну через `build_shortlist*.py` на тому ж вхідному
+      наборі.
+- [ ] `questions triage` (і решта пресетів) видає валідний JSON, який приймає `classify`
+      без правок.
+- [ ] `evaluate` на 20-50 розмічених прикладів дає числа (accuracy, поріг-precision), а не
+      просто "ok".
+- [ ] Без мережі (з прогрітим HF-кешем, `HF_HUB_OFFLINE=1`) CLI працює — інструмент має
+      прокидати цю env-змінну прозоро, не блокувати офлайн-роботу.
+- [ ] `--help` на кожній команді — з прикладом виклику, як у px (уже показав, що це реально
+      корисно при перевірці).