---

name: reporting description: "Create and troubleshoot paperai 2.6.0 YAML reports in Markdown, CSV, or optional PDF annotation format, including generated columns and safe configuration validation." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Reporting

Use this route to turn an existing paperai corpus/index into a bounded report. Start with configuration for YAML and column semantics, workflows for staged runs, api-reference for Python calls, and cli-reference for the positional module CLI. Use troubleshooting before changing a model, corpus, or report definition.

Scope and routing

• Owns: Task.load, Task.queries, one-level Task.flatten, report YAML, standard/constant/generated columns, Execute.options/create/run, Markdown (md), CSV (csv), optional PDF annotation (ant), output naming, topn, threshold, indir, allsections, section, surround, matches, snippet, and column conversion helpers.
• Requires: a model directory containing articles.sqlite and a compatible saved txtai embeddings index. Use indexing for corpus schema, index construction, vector configuration, and compatibility.
• Delegates: search syntax, score filtering, grouping, and highlight internals to querying. Do not use this route to repair SQLite, build embeddings, or ingest source PDFs.

Safe route

1. Copy the minimal, standard-column YAML in configuration and replace every placeholder. Run the bundled the safe validator before loading a model; it parses YAML and checks shape only, without importing paperai, opening SQLite, or touching models.
2. Confirm the model directory and database/index prerequisites. For ant, also confirm a readable source directory and exact source basenames.
3. Run one narrow query with explicit topn and md. Add one generated field, then dtype/context controls, then switch to CSV or annotation.
4. Inspect output files with a Markdown/CSV parser and plan a fresh output directory or unique names: paperai opens outputs in write mode and does not prompt before replacement.

Fast facts

• Renderer values are exactly md, csv, and ant; missing render resolves to Markdown, while another value raises ValueError.
• A task path writes beside the YAML. Its root name is the Markdown/master output stem. Markdown is <name>.md; CSV creates one <query-name>.csv per top-level query and removes its temporary <name>.csv; annotation writes annotations/<Source> and removes its temporary <name>.ant.
• Standard columns are Id, Date, Study, Study Link, Journal, Source, Entry, and Matches. A constant column performs no model call. A generated column has query and optional question/controls.
• query: "*" enumerates all articles and can make topn ineffective. The query layer uses a default threshold of 0.25 when threshold is absent. Pass topn explicitly: in 2.6.0 Execute.options stores a missing value as None, which can defeat the nominal Report.build fallback of 50.
• section: true expands a match to the full same-named subsection; positive surround: N expands to nearby stored section rows. section wins if both are set. matches controls context snippets per generated field, not article count.
• qa is an Execute/CLI parameter but verified 2.6.0 filters it before RAG construction; set YAML options.llm for the effective RAG model selector. ant additionally requires txtmarker, PDFs, and matching Source names.

Keep long schemas, renderer details, workflows, and failure matrices in the linked references rather than expanding this router.