diff --git a/.agents/skills/template-authoring/SKILL.md b/.agents/skills/template-authoring/SKILL.md index 2ef97b70..495ca2da 100644 --- a/.agents/skills/template-authoring/SKILL.md +++ b/.agents/skills/template-authoring/SKILL.md @@ -24,7 +24,7 @@ removed while the template remains. ## Required workflow -1. Read the entire template directory, including its runner, `pyproject.toml`, +1. Read the entire template directory, including its queries, `pyproject.toml`, README, runbook, data files, and existing sidecar. 1. Preserve the entrypoint, solver choices, constraints, thresholds, output labels, and data semantics unless the request explicitly changes them. @@ -38,7 +38,8 @@ removed while the template remains. │ ├── __init__.py │ ├── schema.py │ └── source.py - ├── .py + ├── queries/ + │ └── .py ├── runbook.md ├── pyproject.toml └── data/ @@ -49,12 +50,15 @@ removed while the template remains. relationships with direct `model.Concept`, `model.Property`, and `model.Relationship` calls. 1. Put source reads, normalization, and base-fact mappings in - `model/source.py`. Keep solver declarations, derived reasoning, result - queries, and reporting in the runner. + `model/source.py`. `rai models deploy --path model` deploys what the + package declares, so put solver declarations and derived reasoning in the + package too (for example `model/reasoning.py`). Keep result queries and + reporting in `queries/.py`, which imports from `model`, declares + nothing, and runs as `python -m queries.`. 1. Re-export the model and stable schema symbols from `model/__init__.py`. A single-source template may load its source on import. A multi-source - template must expose explicit loader functions and let each runner choose - the correct one. + template must expose explicit loader functions and let each entry point + choose the correct one. 1. Keep README commands, code links, `runbook.md`, and `template-docs.yaml` aligned with the final paths and symbols. 1. Follow [the sidecar contract](./resources/template-docs.md) and select only @@ -73,7 +77,7 @@ provides the model explorer and walkthrough. - Explain the problem before implementation details. - For a long-form README, put the solution flow in **What you'll build** and - use **What's included** to identify the schema, source, runner, runbook, + use **What's included** to identify the schema, source, queries, runbook, sample data, and outputs. - When the sidecar sets `page.download_and_run_from_readme: true`, a README may contain only **What this template is for** and **Quickstart**, plus an diff --git a/.agents/skills/template-authoring/resources/template-docs.md b/.agents/skills/template-authoring/resources/template-docs.md index 400b6cc4..0d730411 100644 --- a/.agents/skills/template-authoring/resources/template-docs.md +++ b/.agents/skills/template-authoring/resources/template-docs.md @@ -49,6 +49,20 @@ sample_data: install, configure with the Start building with PyRel configuration builder, and run. Keep any representative output directly after its runner command. Templates without this flag retain their existing rendering. +- `deployment: true` (optional, requires `download_and_run_from_readme: true`) + marks a template that deploys its model. The Quickstart then has seven ordered + steps: download, Python environment, install, configure, deploy (one `bash` + block containing exactly `rai models deploy --path model`), query (one `bash` + block per report containing exactly `python -m queries.`, each optionally + followed by a `text` output block), and tear down (`rai models teardown`, then + `rai models teardown --force`). A template that trains a GNN adds an eighth + step between deploy and query: one `bash` block containing exactly + `python train.py`, optionally followed by a `text` output block, and then only + paragraphs, such as the refresh that makes the deployed model predict with + the new version. List the README's `prerequisites` section in + `lead_from_readme`: the page renders only the lead sections and the generated + Quickstart, so the deployment setup the Quickstart points to appears only + through the lead. - `omit_readme_preamble: true` (optional) excludes the text before the first README `##` heading from the enhanced HTML and Markdown pages. Use it when the README opens with links to its own generated model explorer and @@ -149,7 +163,7 @@ guide links: ```yaml focus: - file: runner.py + file: queries/report.py anchors: - start: "# Stage 3: Optimize" end: "# Stage 4: Report" diff --git a/.github/prompts/cleanup-template-code.prompt.md b/.github/prompts/cleanup-template-code.prompt.md index c773fc7b..cf2eb4d7 100644 --- a/.github/prompts/cleanup-template-code.prompt.md +++ b/.github/prompts/cleanup-template-code.prompt.md @@ -20,7 +20,8 @@ dependencies. For a model-package refactor: - Move model creation and stable declarations to `model/schema.py`. - Move reads, normalization, and base-fact mappings to `model/source.py`. - Re-export stable symbols through `model/__init__.py`. -- Keep derived reasoning, solves, queries, and reporting in the runner. +- Keep derived reasoning and solver declarations in the model package, and + result queries and reporting in `queries/.py`. - Update README, runbook, and any existing `template-docs.yaml` references. - Do not force an existing README-only template to adopt the sidecar unless the request explicitly includes migration. diff --git a/.github/prompts/create-template-readme.prompt.md b/.github/prompts/create-template-readme.prompt.md index 2a93d913..2c704683 100644 --- a/.github/prompts/create-template-readme.prompt.md +++ b/.github/prompts/create-template-readme.prompt.md @@ -20,7 +20,7 @@ for a new template, a strict `template-docs.yaml` in the same change. - Keep the README complete and runnable from a fresh environment. - Begin with the business problem and outcome. - For a long-form README, keep the solution stages in **What you'll build**. - Name the model schema, source mapping, runner, runbook, sample data, and + Name the model schema, source mapping, queries, runbook, sample data, and outputs in **What's included**. - For a short enhanced README, use **What this template is for** and **Quickstart** with an opening link to its docs-page model and walkthrough. diff --git a/.github/prompts/review-template.prompt.md b/.github/prompts/review-template.prompt.md index 9cd8d471..1c7f5b36 100644 --- a/.github/prompts/review-template.prompt.md +++ b/.github/prompts/review-template.prompt.md @@ -18,7 +18,7 @@ Check: - Required files, entrypoint, pinned dependencies, and complete sample data. - README commands, paths, headings, expected output, and troubleshooting. -- `model/schema.py`, `model/source.py`, `model/__init__.py`, and runner +- `model/schema.py`, `model/source.py`, `model/__init__.py`, and `queries/` responsibility boundaries when the template uses the standard layout. - `runbook.md` consistency with the final code paths. - Every existing `template-docs.yaml` key, symbol, source, reference, anchor, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 341fc7e3..624e17f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,8 +53,8 @@ This repository uses Ruff to lint Python template code. ## Add a new template 1. Copy `sample-template/` to a new root-level directory named for your template. -2. Rename the main runner, package metadata, and starter identifiers so they match the folder name. -3. Implement the schema, source mappings, runner logic, sample data, and outputs. +2. Rename the query module, package metadata, and starter identifiers so they match the folder name. +3. Implement the schema, source mappings, reasoning, queries, sample data, and outputs. 4. Replace the starter README content and update every field in `template-docs.yaml`. 5. Run focused lint, compilation, policy, and index checks. 6. Run the template from a fresh environment and verify that the README Quickstart works as written. @@ -69,15 +69,19 @@ At a minimum, make sure your template includes: - `model/schema.py` for model creation and stable declarations - `model/source.py` for source reads, normalization, and base-fact mappings - `model/__init__.py` for stable exports -- a runnable entrypoint such as `.py` or a notebook +- `queries/.py` modules that read the deployed model, run as `python -m queries.` - `runbook.md` that uses the same paths, symbols, and commands - `data/` when the template reads local sample files - sample data and output paths that match both the code and the README -Keep solver declarations, derived reasoning, result queries, and reporting in -the runner. A template with one source mode may load it when `model` is -imported. A template with multiple source modes must expose explicit loader -functions and let each runner choose one. +`rai models deploy --path model` deploys what the `model` package declares, +so solver declarations and derived reasoning belong in the package too (for +example `model/reasoning.py`). Keep result queries and reporting in +`queries/.py`: each module imports from `model`, declares nothing, and +runs its report under `if __name__ == "__main__":`. A template with one +source mode may load it when `model` is imported. A template with multiple +source modes must expose explicit loader functions and let each entry point +choose one. ## Generated documentation sidecars @@ -129,7 +133,7 @@ commands, expected results, and any required data attribution in Quickstart. The README and generated run steps must agree. For a longer README, use **What's included** to name the schema, source, -runner, runbook, sample data, and outputs. Use small Markdown tables for +queries, runbook, sample data, and outputs. Use small Markdown tables for representative sample rows where helpful. > [!TIP] @@ -186,7 +190,7 @@ Before opening a PR, make sure you can complete this checklist from a clean envi ruff check */ ``` -1. Compile the changed runner and model package: +1. Compile the changed model package and queries: ```bash python -m compileall -q sample-template diff --git a/README.md b/README.md index 9f60fc37..6e33106d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Each template lives in its own root-level folder. Within a folder, you will usua - `README.md` with the problem statement, prerequisites, and run instructions - `pyproject.toml` for template-local dependencies -- a main runner such as `