Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
176 commits
Select commit Hold shift + click to select a range
a9fa7ba
diet: run as a deployed model
chriscoey Nov 13, 2026
0548ea9
factory_production: run as a deployed model
chriscoey Nov 13, 2026
eaa14ca
bom-reachability: run as a deployed model
chriscoey Nov 13, 2026
852661d
diet, factory_production: note that teardown keeps the schemas
chriscoey Nov 13, 2026
b0fde5e
bom-reachability: persist assembly depth with a deployed rule
chriscoey Nov 13, 2026
9b1ddd5
factory_production: check the returned factory and product keys
chriscoey Nov 14, 2026
75b3c91
ad_spend_allocation: run as a deployed model
chriscoey Nov 14, 2026
bace2e2
campaign_roi: run as a deployed model
chriscoey Nov 14, 2026
5471eb6
network_flow_planning: run as a deployed model
chriscoey Nov 14, 2026
0c46d58
production_planning: run as a deployed model
chriscoey Nov 14, 2026
79c79b8
retail_markdown: run as a deployed model
chriscoey Nov 14, 2026
6be82ea
supply_chain_transport: run as a deployed model
chriscoey Nov 14, 2026
9236031
planogram_optimization: run as a deployed model
chriscoey Nov 14, 2026
8d2f576
pod_placement: run as a deployed model
chriscoey Nov 14, 2026
49e6280
product_configurator: run as a deployed model
chriscoey Nov 14, 2026
6d1e9ba
shift_assignment: run as a deployed model
chriscoey Nov 14, 2026
21b1aaf
synthetic_eligibility_records: run as a deployed model
chriscoey Nov 14, 2026
f4e3846
synthetic_order_lifecycle: run as a deployed model
chriscoey Nov 14, 2026
885781c
commercial_underwriting: run as a deployed model
chriscoey Nov 14, 2026
3d32af7
shipment_compliance: run as a deployed model
chriscoey Nov 14, 2026
08b25fa
sample-template: run as a deployed model
chriscoey Nov 14, 2026
be86691
entity_resolution: run as a deployed model
chriscoey Nov 14, 2026
8b3a2c3
cybersecurity-attack-paths: run as a deployed model
chriscoey Nov 14, 2026
cf07676
it-dependency-mapping: run as a deployed model
chriscoey Nov 14, 2026
482c537
transaction_screening_local: run as a deployed model
chriscoey Nov 14, 2026
22eb813
money_laundering_motif_detection: run as a deployed model
chriscoey Nov 14, 2026
a3bd877
simple-start: run as a deployed model
chriscoey Nov 14, 2026
5da5b2a
financial_index_replication: run as a deployed model
chriscoey Nov 14, 2026
ae173af
cell_tower_coverage: run as a deployed model
chriscoey Nov 14, 2026
0de996b
test_data_generation: run as a deployed model
chriscoey Nov 14, 2026
5400728
traveling_salesman: run as a deployed model
chriscoey Nov 14, 2026
f9dd30b
water_allocation: run as a deployed model
chriscoey Nov 14, 2026
df5e0c6
warehouse_allocation: run as a deployed model
chriscoey Nov 14, 2026
991a7e8
cybersecurity-attack-paths, it-dependency-mapping: name the release l…
chriscoey Nov 14, 2026
6118c9c
disease-outbreak-prevention: run as a deployed model
chriscoey Nov 14, 2026
529cd39
humanitarian-aid-supply-chain: run as a deployed model
chriscoey Nov 14, 2026
8899414
wildlife-conservation-network: run as a deployed model
chriscoey Nov 14, 2026
e80b0e2
patient_cohort_recruitment: run as a deployed model
chriscoey Nov 14, 2026
3788b9e
book_slate_recommendation: run as a deployed model
chriscoey Nov 14, 2026
85a20d4
defect_root_cause: run as a deployed model
chriscoey Nov 14, 2026
6a5602d
book_slate_recommendation: describe the deployed status check
chriscoey Nov 14, 2026
e35e438
diet: split into a deployed model package and a query
chriscoey Nov 14, 2026
154f0c5
factory_production: split into a deployed model package and a query
chriscoey Nov 14, 2026
6f7dc41
entity_resolution: deploy the model package and query it
chriscoey Nov 14, 2026
a0c1f68
diet, factory_production, entity_resolution: name the public schema b…
chriscoey Nov 14, 2026
52a42d7
bom-reachability: deploy the model package and query the deployment
chriscoey Nov 14, 2026
84b35c6
money_laundering_motif_detection: deploy one model with all three motifs
chriscoey Nov 14, 2026
1cdf2f8
money_laundering_motif_detection: keep placeholders out of Quickstart…
chriscoey Nov 14, 2026
e312e89
ad_spend_allocation: split into a deployed model package and a query
chriscoey Nov 14, 2026
11fdec0
campaign_roi: split into a deployed model package and a query
chriscoey Nov 14, 2026
6fb8d2a
cell_tower_coverage: split into a deployed model package and a query
chriscoey Nov 14, 2026
caf9e80
network_flow_planning: split into a deployed model package and a query
chriscoey Nov 14, 2026
b3a504b
planogram_optimization: split into a deployed model package and a query
chriscoey Nov 14, 2026
e6e8de4
pod_placement: split into a deployed model package and a query
chriscoey Nov 14, 2026
aa21bea
product_configurator: split into a deployed model package and a query
chriscoey Nov 14, 2026
6a65b6d
traveling_salesman: split into a deployed model package and a query
chriscoey Nov 14, 2026
cd8356e
water_allocation: split into a deployed model package and a query
chriscoey Nov 14, 2026
0293513
production_planning: split into a deployed model package and a query
chriscoey Nov 14, 2026
7b4257f
shift_assignment: split into a deployed model package and a query
chriscoey Nov 14, 2026
dfe3adb
retail_markdown: split into a deployed model package and a query
chriscoey Nov 14, 2026
12f5b2f
supply_chain_transport: split into a deployed model package and a query
chriscoey Nov 14, 2026
c7b031e
synthetic_eligibility_records: split into a deployed model package an…
chriscoey Nov 14, 2026
ffe35be
test_data_generation: split into a deployed model package and a query
chriscoey Nov 14, 2026
d6cc10b
cybersecurity-attack-paths: deploy the model package and query it
chriscoey Nov 14, 2026
33a51b4
it-dependency-mapping: deploy the model package and query it
chriscoey Nov 14, 2026
959d669
shipment_compliance: deploy the model package and query it
chriscoey Nov 14, 2026
75eb6f7
shipment_compliance: say model, not script, in the module docstring
chriscoey Nov 14, 2026
abbdfc8
financial_index_replication: deploy the model package and query it
chriscoey Nov 14, 2026
b7721b6
commercial_underwriting: deploy the model package and query it
chriscoey Nov 14, 2026
16ac91e
defect_root_cause: deploy the model package and query it
chriscoey Nov 14, 2026
5502f2e
sample-template: split the starter into a deployed model and a query
chriscoey Nov 14, 2026
fc73649
commercial_underwriting: keep the tier checks as warnings
chriscoey Nov 14, 2026
77cf569
Describe the model package and queries layout in the contributor docs
chriscoey Nov 14, 2026
012539b
warehouse_allocation: split into a deployed model package and a query
chriscoey Nov 14, 2026
0b5f7b9
patient_cohort_recruitment: split into a deployed model package and a…
chriscoey Nov 14, 2026
fb47325
synthetic_order_lifecycle: split into a deployed model package and a …
chriscoey Nov 14, 2026
3c6acdb
book_slate_recommendation: split into a deployed model package and a …
chriscoey Nov 14, 2026
52185fb
disease-outbreak-prevention: split into a deployed model package and …
chriscoey Nov 14, 2026
484407b
humanitarian-aid-supply-chain: split into a deployed model package an…
chriscoey Nov 14, 2026
2e0a290
wildlife-conservation-network: split into a deployed model package an…
chriscoey Nov 14, 2026
44ce5c5
Point the entity_resolution contract test at its query module
chriscoey Nov 14, 2026
9bbd2b2
Allow existing templates a single-module model package
chriscoey Nov 14, 2026
4a95946
planogram_optimization: say when the demand-table guard runs
chriscoey Nov 14, 2026
c8ae391
sample-template: say how to start from the starter, which has no ZIP
chriscoey Nov 14, 2026
a9ee88d
synthetic_eligibility_records: keep the note that verify() skips implies
chriscoey Nov 14, 2026
1a9a8f0
entity_resolution: report every figure from the deployed model
chriscoey Nov 14, 2026
3a7b465
financial_index_replication: read returns, sector weights and turnove…
chriscoey Nov 14, 2026
57b4471
synthetic_eligibility_records: stop the report on an unexpected termi…
chriscoey Nov 14, 2026
a90c443
money_laundering_motif_detection: keep the non-deploy scripts
chriscoey Nov 14, 2026
fbaadab
Keep the financial_index_replication walkthrough to six steps
chriscoey Nov 14, 2026
7b819f6
Keep model packages to the schema, source, and reasoning split
chriscoey Nov 14, 2026
a365802
Split the diet model into schema, source, and reasoning modules
chriscoey Nov 14, 2026
506f00d
Split the warehouse_allocation model into schema, source, and reasoni…
chriscoey Nov 14, 2026
a9f9502
Deploy the fraud_detection_rules notebook model and query it
chriscoey Nov 14, 2026
0441800
Drop the fraud notebook's repeated final query
chriscoey Nov 14, 2026
95f14be
Split the product_configurator model into schema, source, and reasoni…
chriscoey Nov 14, 2026
7caec06
Split the synthetic_eligibility_records model into schema, source, an…
chriscoey Nov 14, 2026
c2750ba
Split the bom-reachability model into schema, source, and reasoning m…
chriscoey Nov 14, 2026
b6881bc
Split the network_flow_planning model into schema, source, and reason…
chriscoey Nov 14, 2026
f87a9ff
Split the ad_spend_allocation model into schema, source, and reasonin…
chriscoey Nov 14, 2026
caa80ed
Split the retail_markdown model into schema, source, and reasoning mo…
chriscoey Nov 14, 2026
371a8f5
demand_forecasting: deploy the model, train the GNN, query the forecast
chriscoey Nov 14, 2026
3777f86
Split the planogram_optimization model into schema, source, and reaso…
chriscoey Nov 14, 2026
8ff2ecb
Split the campaign_roi model into schema, source, and reasoning modules
chriscoey Nov 14, 2026
ba7db62
Publish the diet solve status and objective from the model
chriscoey Nov 14, 2026
6cde471
Merge exemplar branch into conform batch 1
chriscoey Nov 14, 2026
f8ca91d
Merge remote-tracking branch 'origin/coey/tpl-conform-ex' into coey/t…
chriscoey Nov 14, 2026
a9590e3
Merge the revised conform exemplar
chriscoey Nov 14, 2026
e06af4f
Publish the network_flow_planning solve status and objective from the…
chriscoey Nov 14, 2026
e8da8ec
Publish the retail_markdown solve status and objective from the model
chriscoey Nov 14, 2026
77ad395
Publish the ad_spend_allocation solve status and objective from the m…
chriscoey Nov 14, 2026
983d18e
Split the pod_placement model into schema, source, and reasoning modules
chriscoey Nov 14, 2026
35b9d50
Split the shift_assignment model into schema, source, and reasoning m…
chriscoey Nov 14, 2026
28b9d34
Publish the campaign_roi solve status and objective from the model
chriscoey Nov 14, 2026
b49fc04
Publish the planogram_optimization solve status and objective from th…
chriscoey Nov 14, 2026
c6e6bd5
Describe the bom-reachability model package modules in the README
chriscoey Nov 14, 2026
3f7c2bf
Publish the product_configurator solve status and solution count from…
chriscoey Nov 14, 2026
ffeedc4
Split the production_planning model into schema, source, and reasonin…
chriscoey Nov 14, 2026
7ab98b0
Publish the synthetic_eligibility_records solve status and solution c…
chriscoey Nov 14, 2026
4be4b50
Split the supply_chain_transport model into schema, source, and reaso…
chriscoey Nov 14, 2026
199371c
Publish the warehouse_allocation solve status and objective from the …
chriscoey Nov 14, 2026
82e5727
Split the test_data_generation model into schema, source, and reasoni…
chriscoey Nov 14, 2026
011e291
Split the cell_tower_coverage model into schema, source, and reasonin…
chriscoey Nov 14, 2026
a58d523
Split the it-dependency-mapping model into schema, source, and reason…
chriscoey Nov 14, 2026
2859c96
Split the traveling_salesman model into schema, source, and reasoning…
chriscoey Nov 14, 2026
bd1af4d
Split the commercial_underwriting model into schema, source, and reas…
chriscoey Nov 14, 2026
8d052c4
Split the water_allocation model into schema, source, and reasoning m…
chriscoey Nov 14, 2026
d496bf5
Split the patient_cohort_recruitment model into schema, source, and r…
chriscoey Nov 14, 2026
1fbe9df
Split the shipment_compliance model into schema, source, and reasonin…
chriscoey Nov 14, 2026
59bfad6
Split the cybersecurity-attack-paths model into schema, source, and r…
chriscoey Nov 14, 2026
f35939f
subscriber_retention: deploy the model, train the GNN, query the chur…
chriscoey Nov 14, 2026
991248f
Split the disease-outbreak-prevention model into schema, source, and …
chriscoey Nov 14, 2026
6c7116a
Split the factory_production model into schema, source, and reasoning…
chriscoey Nov 14, 2026
1cf5dbd
Split the synthetic_order_lifecycle model into schema, source, and re…
chriscoey Nov 14, 2026
a146348
Split the humanitarian-aid-supply-chain model into schema, source, an…
chriscoey Nov 14, 2026
2c1d2eb
Split the defect_root_cause model into schema, source, and reasoning …
chriscoey Nov 14, 2026
4f5b961
Split the wildlife-conservation-network model into schema, source, an…
chriscoey Nov 14, 2026
098fe5d
Merge remote-tracking branch 'origin/coey/templates-relationalai-2.1'…
chriscoey Nov 14, 2026
ac4ef66
Split the book_slate_recommendation model into schema, source, and re…
chriscoey Nov 14, 2026
7f3c8eb
Print the financial_index_replication solve result and import in ruff…
chriscoey Nov 14, 2026
cba5c17
Split the entity_resolution model into schema, source, and reasoning …
chriscoey Nov 14, 2026
6a7c07b
Merge remote-tracking branch 'origin/coey/tpl-conform-b3' into coey/t…
chriscoey Nov 14, 2026
b486db2
Merge remote-tracking branch 'origin/coey/tpl-conform-b2' into coey/t…
chriscoey Nov 14, 2026
e4c7118
Merge remote-tracking branch 'origin/coey/tpl-conform-b1' into coey/t…
chriscoey Nov 14, 2026
e3a9c99
Merge remote-tracking branch 'origin/coey/tpl-fraud-nb' into coey/tem…
chriscoey Nov 14, 2026
e0971aa
Merge remote-tracking branch 'origin/coey/templates-relationalai-2.1'…
chriscoey Nov 14, 2026
842a1cc
energy_grid_planning: deploy the model and query the report
chriscoey Nov 14, 2026
6bf67ae
telco_network_recovery: deploy the model, train the GNN, query the plan
chriscoey Nov 14, 2026
06b2018
fraud-detection: deploy the model, train the GNN, query the audit queue
chriscoey Nov 14, 2026
4b25019
Merge remote-tracking branch 'origin/coey/templates-deploy-mode-2.1' …
chriscoey Nov 14, 2026
a518679
datacenter_compute_allocation: deploy the model, train the GNN, query…
chriscoey Nov 14, 2026
638c2cf
Merge remote-tracking branch 'origin/coey/tpl-gnn-g1' into coey/templ…
chriscoey Nov 15, 2026
71945f1
Merge commit 'a518679' into coey/templates-deploy-mode-2.1
chriscoey Nov 15, 2026
c5e4ccb
Fix template page anchors and mark fraud-detection as deployed
chriscoey Nov 15, 2026
766a365
Stop reports on a missing solution and default empty totals to zero
chriscoey Nov 15, 2026
4af9872
Show deployment prerequisites on template pages and fix stale docs
chriscoey Nov 15, 2026
3546364
Ask for path and tower counts in telco's call-path runbook step
chriscoey Nov 15, 2026
69551a2
Publish energy_grid_planning's marginal value and knee point as rules
chriscoey Nov 15, 2026
12acac3
Say plainly when entity_resolution and product_configurator have no s…
chriscoey Nov 15, 2026
5fb698a
Mark a single knee in energy_grid_planning, and none on a rising fron…
chriscoey Nov 15, 2026
6c0324c
Document the train step in the deployed-template Quickstart contract
chriscoey Nov 15, 2026
7f506eb
Merge remote-tracking branch 'origin/coey/templates-relationalai-2.1'…
chriscoey Nov 15, 2026
6d46741
Publish the factory_production marginals through the model
chriscoey Nov 19, 2026
655915a
Publish the product_configurator builds through the model
chriscoey Nov 19, 2026
8699e06
Publish the synthetic_eligibility_records records through the model
chriscoey Nov 19, 2026
f62c889
Publish the entity_resolution graph size through the model
chriscoey Nov 19, 2026
ddce495
Publish the wildlife-conservation-network graph results through the m…
chriscoey Nov 19, 2026
826c4f8
Publish the disease-outbreak-prevention graph results through the model
chriscoey Nov 19, 2026
6c00815
Publish the humanitarian-aid-supply-chain graph results through the m…
chriscoey Nov 19, 2026
3e7b019
Publish the defect_root_cause graph size and formulation counts throu…
chriscoey Nov 19, 2026
8723d92
Publish the energy_grid_planning corridors through the model
chriscoey Nov 19, 2026
2382a6f
Publish the bom-reachability graph results and assembly chains throug…
chriscoey Nov 19, 2026
bf7bb28
Publish the cybersecurity-attack-paths paths through the model
chriscoey Nov 19, 2026
b74f594
Publish the it-dependency-mapping dependency paths through the model
chriscoey Nov 19, 2026
ae67f53
Publish the warehouse_allocation components through the model
chriscoey Nov 19, 2026
8f38f97
Merge remote-tracking branch 'origin/coey/templates-relationalai-2.1'…
chriscoey Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
18 changes: 11 additions & 7 deletions .agents/skills/template-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -38,7 +38,8 @@ removed while the template remains.
│ ├── __init__.py
│ ├── schema.py
│ └── source.py
├── <runner>.py
├── queries/
│ └── <name>.py
├── runbook.md
├── pyproject.toml
└── data/
Expand All @@ -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/<name>.py`, which imports from `model`, declares
nothing, and runs as `python -m queries.<name>`.
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
Expand All @@ -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
Expand Down
16 changes: 15 additions & 1 deletion .agents/skills/template-authoring/resources/template-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<name>`, 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
Expand Down Expand Up @@ -149,7 +163,7 @@ guide links:

```yaml
focus:
file: runner.py
file: queries/report.py
anchors:
- start: "# Stage 3: Optimize"
end: "# Stage 4: Report"
Expand Down
3 changes: 2 additions & 1 deletion .github/prompts/cleanup-template-code.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>.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.
Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/create-template-readme.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/review-template.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
22 changes: 13 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 `<template_name>.py` or a notebook
- `queries/<name>.py` modules that read the deployed model, run as `python -m queries.<name>`
- `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/<name>.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

Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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 <your_template_name> sample-template
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<template>.py` or a notebook
- `model/`, the model package that `rai models deploy --path model` deploys, and `queries/`, one module per report, run as `python -m queries.<name>` (a few templates use a single script or a notebook instead)
- `data/` containing sample input data when the template uses local files
- `runbook.md` with ordered prompts to recreate or adapt the template using a coding agent with RelationalAI skills (multi-reasoner templates)

Expand Down Expand Up @@ -151,7 +151,7 @@ The exact setup is documented in each template's README, but the workflow is con
2. Create a virtual environment inside that folder.
3. Install the template's dependencies.
4. Configure RelationalAI access if the template connects to a live environment.
5. Run the script or notebook described in the template README.
5. Deploy the model and run its queries, or run the script or notebook, as the template README describes.

Example workflow:

Expand Down Expand Up @@ -179,7 +179,7 @@ Most templates are designed to be runnable and inspectable without additional re
To add or update a template:

1. Copy [`sample-template/`](sample-template/) to a new root-level directory.
2. Implement the model, runner, sample data, and metadata.
2. Implement the model package, queries, sample data, and metadata.
3. Replace the README placeholders with template-specific content.
4. Review the result before opening a pull request.

Expand Down
Loading
Loading