gaik-project/gaik-toolkit/generate-structured-reports

Generating structured reports with gaik

Requires: AZURE_API_KEY and AZURE_ENDPOINT, or OPENAI_API_KEY, set as environment variables (the Azure OpenAI or OpenAI workflow). If a key is missing, ask the user to set it as an environment variable; never ask for the key in the chat and never write it into a file. The default provider is openai (LLM_PROVIDER or --provider selects another). The curator, writer and reviewer models come from the spec's models, else GAIK_REPORT_CURATOR_MODEL, GAIK_REPORT_WRITER_MODEL and GAIK_REPORT_REVIEWER_MODEL, else the defaults for the provider (see the README). The skill passes no reasoning effort; the user can set it in the spec's settings for models that support it. preflight --check-provider prints the models each step will use; name them, and the provider, in your summary.

This skill writes a report with gaik's ReportWriter, one checked stage at a time:

1. Normalize: every source file becomes Markdown text that keeps its file name.
2. Curate: for each section, fact units (a summary and the exact quote it came from),

the required items no source covers, and the conflicts between sources. Every quote is checked against its source.

1. Synthesize: each section is written from its own facts only and checked by a reviewer

model; summaries are written from the sections they depend on.

Run the pipeline. Do not imitate it. Every stage runs through scripts/run_report.py, which calls gaik. Never write the report yourself from the sources, never curate facts by reading the files, and never fall back to one writing call when a stage fails. The helper cannot reach ReportWriter.run(), so the single-call baseline is not available.

pip install "gaik[report-writer]"     # and Pandoc, for Word output
python <skill>/scripts/run_report.py --help

Anthropic, Google and LiteLLM need their own gaik extra (llm-anthropic, llm-google, llm-litellm). The helper installs a missing one itself, with pip install "gaik[<extra>]", when it loads the provider config, and says so on stderr; tell the user in your summary if it did. If the install fails it stops and prints the command to run. Recordings and video also need ffmpeg on the PATH, and on Python 3.13 or later the audioop-lts package (pip install "audioop-lts; python_version >= '3.13'"); without them normalizing a recording fails. Install them before the first run with recordings, and ask before installing anything. The Docling and PyTorch warnings on documents are not errors; install them only if the user needs richer PDF parsing (the skill's README, "Installing the skill").

<skill> is this skill's installed directory. The helper reads the provider's credentials from the environment (get_llm_config): never put a key in the spec or on the command line.

Workflow

Keep a task list with these steps. Use a fresh run folder for each report, holding report_spec.json and workspace/. Where it goes is the first intake question (below).

1. Intake

First ask where to save the outputs, before writing any file:

• Output location. Offer two choices: a new folder in the user's home directory,

~/report-runs/<name>/ (the default, created on the user's yes), or a folder the user names. <name> is a short slug for the report; tell the user the full path. A folder the user names is the parent: create <name>/ inside it unless the user says to use the folder as it is, and never write into a folder that already holds a different report's run. The run folder holds the spec, the workspace, copies of the inputs and the finished report. The user's original files stay where they are. Skip the question only when the request already names the location.

Then ask only what changes the report:

• Sources: which files are evidence. Keep three roles apart: evidence (the facts),

template (the structure, agreed in step 5) and sample (style, length and tone; its facts never reach the report). A filled earlier report is ambiguous: ask whether it is the template, the sample, or both. It is evidence only if the user says so.

• Title, purpose, audience, language. description in the spec is not sent to any model,

so put whatever must shape the text into instructions.

• Source priority. Do not invent one. Without one, put every source in primary and

write the no-hierarchy instruction from references/report-spec.md. With one, map it to primary/secondary and also state it in instructions. Add the gap-marker sentences from the same reference too. If the user gives a sample and an instruction of theirs (such as covering everything) conflicts with the sample's length, point it out and ask which wins.

• Citations. Ask whether the report should cite, for each fact, its source file and place.

Yes is the default; skip the question when the request or a given spec already says (settings.citations). If yes, leave settings.citations at true and add the citation sentence from references/report-spec.md to instructions. If no, set settings.citations to false, leave the citation sentence out, and tell the user that the report will not show where each fact came from.

• Output: Markdown always; Word if the user wants it. When they do, check for Pandoc:

python <skill>/scripts/install_pandoc.py --check. If Pandoc is missing, tell the user it is not installed and ask whether to install it now, saying that this downloads it from the internet into a per-user folder, with no administrator rights. If they agree, run python <skill>/scripts/install_pandoc.py and confirm that it reports Pandoc found. If they do not agree, or the install fails, set settings.docx to false and tell the user that the report will be Markdown only. Never install Pandoc without their yes.

These answers become the first proposal. Every value they set (sources, instructions, title and the rest) is shown again for the user to accept or change: the run settings in step 2, the whole spec in step 5.

• Provider and cost. Explain once that recordings and images cost model calls during

normalization, and that curation and synthesis call models for every section. Get the go-ahead once; do not ask before every call.

2. The spec for normalization

Write report_spec.json beside workspace/ from the intake answers; source paths are relative to the spec's folder. Keys and rules: references/report-spec.md. The sections are decided after normalization (step 5), so for now give the spec one placeholder section, {"id": "draft", "title": "Draft", "instructions": "Placeholder until the structure is agreed."}. If the user gave a spec JSON with sections, keep them: they are reviewed in step 5 like a template. Normalization never reads the sections.

Normalization does read sources, models.vision, models.transcription and settings.transcription_language, so the run settings are agreed now, before any paid call:

python <skill>/scripts/run_report.py propose-spec --spec SPEC --workspace WS --provider P --out spec_proposal.json

It writes the whole spec, every key spelled out, to spec_proposal.json and prints it as a review list. It keeps what the spec sets and fills the rest with the defaults: models for the selected provider (--provider, else LLM_PROVIDER, else openai; table in references/report-spec.md) and the run settings below. Show the user the sources, sample_report, models and settings groups (step 5, "Reviewing the spec"), apply any change to spec_proposal.json, and, once they accept, write it with apply-spec (step 5).

3. Preflight

python <skill>/scripts/run_report.py preflight --spec SPEC --workspace WS --check-provider

It costs nothing. It loads the spec with ReportSpec.load() and adds the checks the library makes only after money is spent, or never: PDF pages with no text layer (and pages with so little text they may be scans), duplicate file names, unsupported files, recordings with a provider that cannot transcribe them, a missing Pandoc (when it is reported and the user wants Word, offer the install as in step 1; otherwise set settings.docx to false), and any input placed inside the workspace's stage folders, which the stages delete. Fix every error. Show the user each warning that changes the report, such as pages that will be missing.

4. Normalize

python <skill>/scripts/run_report.py normalize --spec SPEC --workspace WS

Read the result: each file's converter and text length. A file is never skipped: if one fails, the stage fails. Read the normalized texts in workspace/normalized/ before step 5, and check a transcript's names, addresses and numbers against the other sources: every speech model mishears some of them, especially names it has not seen. Never correct one on your own. Propose each correction to the user with the source that supports it and, once they agree, make it in the normalized text and keep a note of it (references/review-and-resume.md). What no other source settles stays as transcribed.

5. The report spec, agreed in chat

The user reviews the whole spec, not only the section titles and prompts: every value is proposed, shown, and either accepted as it is or changed by the user. Draft the sections first (below), then propose the spec:

python <skill>/scripts/run_report.py propose-spec --spec SPEC --workspace WS --provider P --structure structure.json --out spec_proposal.json

--structure takes the drafted sections ({"title", "prompt", "required_items", "summary_of"}, as below); the helper makes their ids and turns summary_of into depends_on. Then edit spec_proposal.json so that every field holds your proposal, as follows.

What to propose for each field: