Note
This repository is optimized for AI agents and automated workflows. Machine-readable specifications and integration notes can be found in llms.txt and SKILL.md.
Domain-neutral core engine for schema-bound, anonymizable report generation pipelines: extract source documents → build LLM prompt bound to a JSON schema → populate Word (.docx) template with structured LLM responses. Privacy modes switchable between mode="anonymized" and mode="plain".
flowchart LR
A["Source Documents\n(Word/PDF/Text/Excel)"] -->|prepare| B["Session Workspace\n(prompt.txt & data_bundled)"]
B -->|External LLM| C["JSON Response\n(report.json)"]
C -->|finish| D["Finalized Report\n(.docx in output_dir)"]
subgraph Privacy ["Privacy Protection Layer"]
E["anonymizer module\n(mode='anonymized')"]
end
E -.- B
| Feature | Description |
|---|---|
| Architecture | 3-phase pipeline (prepare → LLM → finish) |
| Privacy & Security | Fail-closed anonymization (mode="anonymized") via anonymizer module (≥0.2.5) or plain-text (mode="plain") |
| Templates | Word (.docx) template engine with {{PLACEHOLDERS}}, dynamic table rows, and checkbox toggling |
| Automation | Idempotent batch processor (process-inbox) for scheduled background execution |
| Output & Storage | Local-first publishing to designated output_dir with automatic timestamp collision protection |
pip install -r requirements.txt(Optional anonymization requires the separately installed anonymizer module >=0.2.5)
from report_forge.workflow import ReportWorkflow
workflow = ReportWorkflow()
# Phase 1: Read source documents and construct LLM prompt
prepared = workflow.prepare(
source_folder="source_docs/",
work_root="sessions/",
mode="plain",
)
# -> prepared.prompt_path contains the generated LLM prompt
# Phase 2: Execute external LLM (outside module boundary)
# Save JSON output to prepared.session_dir / "data_bundled" / "report.json"
# Phase 3: Validate JSON response, populate Word template, and finalize report
finished = workflow.finish(
session_dir=prepared.session_dir,
llm_json_path=prepared.session_dir / "data_bundled" / "report.json",
output_folder="output/final_report.docx",
)Anonymized Mode (
mode="anonymized", Default): When usingprepare(),real_name,birth_date, andpasswordare required arguments. Forfinish(),passwordis required. Theanonymizermodule (>=0.2.5) must be present in the Python environment (seeSKILL.md).
Optional key configurations in config.json or config.local.json:
output_dir: Automatically copies finalized reports to a central distribution directory.inbox_dir: Incoming pickup directory for the automated batch runnerprocess-inbox.
python -m report_forge process-inbox --work sessions/ --mode plain --dry-runPYTHONIOENCODING=utf-8 python -m pytest tests/ -qMIT License, see LICENSE.