# Cite v0.2.0 - Table of Contents

> Finds what you describe in a document, such as failures in a log or hallucinations in a RAG answer. Every finding is grounded in the exact passages it cites. Judges with a decision model, not a generative LLM.

## Pages

- [Cite](readme.md)
- [Changelog](changelog.md)

- Guides
  - [Writing policies](writing-policies.md)
  - [How judging works](how-judging-works.md)

- Tutorials
  - [Checking RAG answers against their sources](checking-rag-answers.md)
  - [Filtering RAG retrieval results](filtering-rag-results.md)
  - [Triaging logs](triaging-logs.md)
  - [Checking support calls against procedure](checking-support-calls.md)
  - [Finding sponsor segments](finding-sponsor-segments.md)
  - [Labelling allergens in recipes](labelling-allergens.md)

## Modules

- Core API
  - [Cite](Cite.md): Finds what a policy describes in a document and cites the caller's own
passages behind each finding, unchanged.
  - [Cite.Citation](Cite.Citation.md): One passage a finding cites or dropped: the caller's passage, unchanged,
its verdict, and the confirm answer that decided it.
  - [Cite.Error](Cite.Error.md): A failed request: the concern it was judging (`nil` for a screening
window), the passages it covered, and the reason. A failed request is
never a verdict. It lands in `Cite.Report.errors` and nowhere else.
  - [Cite.Finding](Cite.Finding.md): A judged finding: its concern and category, the verdict, the raw answers
to its checks and descriptors, the passages it cites, and those its
confirm dropped. Every passage it gathered is in `evidence` or `dropped`.
  - [Cite.Passage](Cite.Passage.md): One unit of a `Cite.Source`: the caller's id, exact text, and meta.
  - [Cite.Policy](Cite.Policy.md): A policy: what the source is judged against, declared once in a module.
  - [Cite.Report](Cite.Report.md): What `Cite.judge/4` returns
  - [Cite.Source](Cite.Source.md): The document as the caller's list of passages. Built by `Cite.source/2`,
which documents `as` and `show`. Only the meta keys `show` names reach the
model. The rest of `meta` stays with the caller.

- Providers
  - [Cite.Provider](Cite.Provider.md): A decision-model provider: builds a handle, then answers one wire-shaped
request per call.
  - [Cite.Provider.TypeSafe](Cite.Provider.TypeSafe.md): TypeSafe System One over HTTP (`POST /v1/systemone`).
  - [Cite.Wire.Object](Cite.Wire.Object.md): A JSON object whose key order survives encoding.

- Internal
  - [Cite.Answer](Cite.Answer.md): Reply maps to values.
  - [Cite.Gather](Cite.Gather.md): Between the rounds, no model call: the screen's scores become the findings
to judge, by fixed rules. Pure. Internal.

  - [Cite.Gathered](Cite.Gathered.md): A finding gathered for judging, before round 2 makes it a `Cite.Finding`:
its concern, the passages it would cite in source order, and the passage
filling each role (concerns built from factors). Internal.

  - [Cite.Judge](Cite.Judge.md): Round 2, minus the client call: a gathered finding becomes one request on
its own evidence, and the reply becomes a `Cite.Finding` under the verdict
rules. Pure. Internal.

  - [Cite.Placeholder](Cite.Placeholder.md): `{name}` placeholders in question text, and the backticked paths they
expand to.
  - [Cite.Policy.Build](Cite.Policy.Build.md): Compiles a policy's declarations to its `Cite.Policy.Terms`, the data the
rounds read, persists them on the module, and reads them back (`read/1`).
A Spark persister: it runs after `Cite.Policy.Checks`, so every
declaration it sees is valid. Internal.

  - [Cite.Policy.Check](Cite.Policy.Check.md): A compiled check: its name, whether its roles must be distinct passages,
the roles its question names, and the question. Internal.

  - [Cite.Policy.Checks](Cite.Policy.Checks.md): The compile-time checks on a policy. A Spark transformer, not a verifier:
Spark reports a failed verifier as a warning, and a mistake in a policy
must stop the build. Runs before `Cite.Policy.Build`, so Build only ever
sees a valid policy. Internal.

  - [Cite.Policy.Concern](Cite.Policy.Concern.md): One compiled concern: screened directly (`detect` and `confirm`) or built
from factors (`roles` and `checks`). Internal.

  - [Cite.Policy.Dsl](Cite.Policy.Dsl.md): The Spark extension behind `use Cite.Policy`: its declarations.
`Cite.Policy.Checks` validates the structs they build (defined in
`lib/cite/policy/dsl/entities.ex`) and `Cite.Policy.Build` compiles them to
a policy's `Cite.Policy.Terms`. The `describe` and `doc` texts here are the
DSL reference in `Cite.Policy`'s docs. Internal.

  - [Cite.Policy.Question](Cite.Policy.Question.md): One compiled question: its type, its text with placeholders unexpanded,
its optional focus, and its criteria. Internal.

  - [Cite.Policy.Role](Cite.Policy.Role.md): A compiled role: its name, the factor that fills it, and its flags. Internal.
  - [Cite.Policy.Terms](Cite.Policy.Terms.md): A policy's terms: its filters, concerns, factors, and descriptors as data,
defaults filled in, compiled from the module that declares them. What the
rounds read. Built by `Cite.Policy.Build`; read it with
`Cite.Policy.Build.read/1`. Internal.

  - [Cite.Round](Cite.Round.md): Sends one round's requests: runs a function on each item, up to
`concurrency` at once, and returns the results in item order.
  - [Cite.Run](Cite.Run.md): One judging run, passed through every step of `Cite.judge/4`. It starts as
what the caller gave, validated once. Each step then fills in its part:
round 1 fills `screen`, gathering fills `gathered`, and round 2 fills
`findings`. Both rounds add their `errors`, `usages`, and `models`.
Internal; use `Cite.judge/4`.

  - [Cite.Screen](Cite.Screen.md): Round 1, minus the client call: every detect asked of every passage, a
window of passages per request, and the replies folded into scores. Pure.
Internal.

  - [Cite.Wire](Cite.Wire.md): Values to request maps.

