MARKDOWN SOURCE
# AGENTS.md Guidance for coding agents working in this repository. ## Project `dec_mod` (Local Decisions) is a local-only Actix Web service that turns text into structured decisions with the `fastino/GLiNER2.5-Decide` checkpoint. The HTTP surface lives in `src/server`, the request validation and response shaping in `src/decisions`, and the model port in `src/engine`. It both classifies text into labels (`/v1/classify_text`) and extracts values for named properties (`/v1/extract`). ## The model is a port, not a wrapper There is no Python. `src/engine` is a Rust port of the pieces of `gliner2` that a classification call actually uses: | Rust | Python it mirrors | | --- | --- | | `engine::tokenizer::WordSplitter` | `gliner2.processing.word_splitter.WhitespaceTokenSplitter` | | `engine::tokenizer::Tokenizer` | the checkpoint's `AutoTokenizer`, loaded from `tokenizer.json` | | `engine::schema::schema_tokens` / `prepare` | `gliner2.processor.SchemaTransformer._transform_schema` and `_format_input_with_mapping` | | `engine::deberta::Encoder` | `transformers` `modeling_deberta_v2.DebertaV2Model` | | `engine::schema::classify_scores` | `gliner2.inference.runtime._extract_classification_result` | | `engine::span::SpanHead` | `gliner2.layers` `CountLSTM`, `SpanMarkerV0`, `create_projection_layer` | | `engine::extract::decode` | `gliner2.inference.runtime._find_spans` + `candidate_decoder.finalize_spans` | Anything that changes behaviour in one of those must change in the other; keep the doc comments pointing at the Python names so the two stay greppable. ## Model documentation - **Decision model docs: [docs/gliner2-5-decide.md](docs/gliner2-5-decide.md)** — the reference for `fastino/GLiNER2.5-Decide`: the label-set call shape (single-label, multi-head, multi-label with `cls_threshold`, labels with descriptions, ordinal scales), the supported task families, and the 60.2% exact-match baseline on `fastino/fast-decisions`. Every example in it is replayed by `tests/documented_examples.rs`, and `tests/benchmark.rs` reproduces that 60.2% with this engine. The outputs printed in the document are illustrative, not authoritative: when the engine and the document disagree on an example, the benchmark decides who is right. ## Rules - No new dependency without a reason, and the reason goes in `THIRD-PARTY-LICENSES.md`. - The service stays local: no request content leaves the machine. - The checkpoint is never committed, built into the image, or downloaded at build time. It lives in `MODEL_DIR` (default `<STORAGE_DIR>/<MODEL_REPO>`) and is fetched on startup when missing, with resume. `storage/` is git-ignored and `mise.toml` points `STORAGE_DIR` at the checkout. - Tests are `#[cfg(test)]` modules colocated with the code they cover; `tests/documented_examples.rs` holds the end-to-end checks and skips itself when no checkpoint is present. - Clippy runs at `pedantic` with `-D warnings`: prefer `?` over `.unwrap()`, and `log::warn!` before returning a bad-request error. - Update `README.md` when routes, request/response shapes, or configuration change. ## Commands - `mise run dev` — serve on `:8080`, downloading the checkpoint on first start. - `mise run verify` — `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test`. - `cargo test` alone is fine; the integration tests skip when `MODEL_DIR` is empty.
AGENTS.md
Guidance for coding agents working in this repository.
Project
dec_mod (Local Decisions) is a local-only Actix Web service that turns text into structured
decisions with the fastino/GLiNER2.5-Decide checkpoint. The HTTP surface lives in
src/server, the request validation and response shaping in src/decisions, and the model
port in src/engine. It both classifies text into labels (/v1/classify_text) and extracts
values for named properties (/v1/extract).
The model is a port, not a wrapper
There is no Python. src/engine is a Rust port of the pieces of gliner2 that a
classification call actually uses:
| Rust | Python it mirrors |
|---|---|
engine::tokenizer::WordSplitter | gliner2.processing.word_splitter.WhitespaceTokenSplitter |
engine::tokenizer::Tokenizer | the checkpoint's AutoTokenizer, loaded from tokenizer.json |
engine::schema::schema_tokens / prepare | gliner2.processor.SchemaTransformer._transform_schema and _format_input_with_mapping |
engine::deberta::Encoder | transformers modeling_deberta_v2.DebertaV2Model |
engine::schema::classify_scores | gliner2.inference.runtime._extract_classification_result |
engine::span::SpanHead | gliner2.layers CountLSTM, SpanMarkerV0, create_projection_layer |
engine::extract::decode | gliner2.inference.runtime._find_spans + candidate_decoder.finalize_spans |
Anything that changes behaviour in one of those must change in the other; keep the doc comments pointing at the Python names so the two stay greppable.
Model documentation
- Decision model docs: docs/gliner2-5-decide.md — the reference for
fastino/GLiNER2.5-Decide: the label-set call shape (single-label, multi-head, multi-label withcls_threshold, labels with descriptions, ordinal scales), the supported task families, and the 60.2% exact-match baseline onfastino/fast-decisions. Every example in it is replayed bytests/documented_examples.rs, andtests/benchmark.rsreproduces that 60.2% with this engine. The outputs printed in the document are illustrative, not authoritative: when the engine and the document disagree on an example, the benchmark decides who is right.
Rules
- No new dependency without a reason, and the reason goes in
THIRD-PARTY-LICENSES.md. - The service stays local: no request content leaves the machine.
- The checkpoint is never committed, built into the image, or downloaded at build time. It lives in
MODEL_DIR(default<STORAGE_DIR>/<MODEL_REPO>) and is fetched on startup when missing, with resume.storage/is git-ignored andmise.tomlpointsSTORAGE_DIRat the checkout. - Tests are
#[cfg(test)]modules colocated with the code they cover;tests/documented_examples.rsholds the end-to-end checks and skips itself when no checkpoint is present. - Clippy runs at
pedanticwith-D warnings: prefer?over.unwrap(), andlog::warn!before returning a bad-request error. - Update
README.mdwhen routes, request/response shapes, or configuration change.
Commands
mise run dev— serve on:8080, downloading the checkpoint on first start.mise run verify—cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo test.cargo testalone is fine; the integration tests skip whenMODEL_DIRis empty.