Skip to content

MARKDOWN SOURCE

Raw
# 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:

RustPython it mirrors
engine::tokenizer::WordSplittergliner2.processing.word_splitter.WhitespaceTokenSplitter
engine::tokenizer::Tokenizerthe checkpoint's AutoTokenizer, loaded from tokenizer.json
engine::schema::schema_tokens / preparegliner2.processor.SchemaTransformer._transform_schema and _format_input_with_mapping
engine::deberta::Encodertransformers modeling_deberta_v2.DebertaV2Model
engine::schema::classify_scoresgliner2.inference.runtime._extract_classification_result
engine::span::SpanHeadgliner2.layers CountLSTM, SpanMarkerV0, create_projection_layer
engine::extract::decodegliner2.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 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.