Skip to content

Refactor four templates for generated documentation - #104

Merged
somacdivad merged 13 commits into
mainfrom
agents/template-refactor-and-docs-update-canonical
Oct 1, 2026
Merged

Refactor four templates for generated documentation#104
somacdivad merged 13 commits into
mainfrom
agents/template-refactor-and-docs-update-canonical

Conversation

@somacdivad

@somacdivad somacdivad commented Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Source and scope

Companion source changes for RelationalAI/relationalai-docs#914. This PR is based on the templates main history and currently points to 1eb2015. It updates four v1 templates and adds an opt-in authoring path. Existing README-only templates are not migrated.

What changed

  • Split each of the four semantic models into model/schema.py, model/source.py, and model/__init__.py, with the existing runners still owning solving and output. Aligned Financial Index Replication on ReturnMonth and Stock.monthly_return.
  • Added source-owned template-docs.yaml model explorers and guided walkthroughs. Each README retains What this template is for and a runnable Quickstart while linking to the generated model and walkthrough:
  • Expanded Portfolio Re-balancing to expose its complete nine-concept model. Concept-valued properties provide visual connections from Stock to Scenario and Regime, from Scenario to Regime, and from FrontierPoint to Scenario, with reader-facing road labels.
  • Reworked the Portfolio walkthrough into seven focused steps covering the shared schema, data connections, all four processing stages, and candidate selection. Stages 3 and 4 now make the cached allocation handoff explicit.
  • Updated the Portfolio runner to report the stock amounts and budget weights for the candidate portfolio selected in each of the six scenarios. Its README now uses a compact excerpt drawn from the verified connected-run output, and the final walkthrough step uses an exact contiguous excerpt.
  • Added a structured sample template, authoring skill and prompts, contributor guidance, refactor tests, changed-template sidecar policy, and CI checks. Regenerated both template indexes from the revised README descriptions.

Why

The sidecars keep model and walkthrough documentation with the code they explain. The shorter READMEs remain useful on GitHub, while their Quickstarts drive the docs-site run instructions instead of requiring a separately maintained copy. The expanded Portfolio model and walkthrough connect current holdings, market data, scenario allocations, risk summaries, and candidate stock amounts in one reader-facing explanation.

Risks

  • The companion docs branch must be built with RAI_TEMPLATES_REPO_BRANCH=agents/template-refactor-and-docs-update-canonical. A build using templates main will render the legacy pages until these PRs merge.
  • The Portfolio Quickstart now contains a compact representative excerpt from the verified run. The companion docs change renders that excerpt as console output.
  • Financial Index Replication renames a concept and relationship in the source model and runner to match the approved guide. Its optimizer still allows a selected stock to have zero invested weight.

How to verify

  • Ran Portfolio Re-balancing successfully with Python 3.12, PyRel 1.9.0, and a configured Snowflake project. All six scenarios selected p3.
  • Confirmed every line in the compact Portfolio README excerpt occurs in the verified 305-line stdout transcript from that run. Confirmed the final walkthrough output exactly matches a contiguous nine-line base_1000 excerpt.
  • uvx ruff check v1/portfolio_balancing passed.
  • Python compilation passed for the Portfolio runner and model package.
  • The companion docs repository passed 29 focused extraction, rendering, and component tests. The 9 tests affected by the final console-rendering change were rerun successfully.
  • npm run check passed with no errors and one existing deprecation hint.
  • Earlier branch-wide validation passed Ruff across sample-template scripts tests v0.13 v0.14 v1, Python unittest discovery, changed-template compilation, generated-index consistency, and the changed-template PR policy.

somacdivad and others added 4 commits September 24, 2026 09:51
@somacdivad
Add template authoring contract and validation
1724d7f 
What changed:
- Document the model-package, README, and enhanced sidecar authoring workflow.
- Add a runnable sample template, focused validation tests, and CI checks for new v1 sidecars.

Why:
- Give contributors a consistent way to create or update generated template documentation while preserving README-only templates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Refactor four enhanced templates and simplify their READMEs
504d5b2 
What changed:
- Split each semantic model into schema and source modules while retaining its runnable entrypoint.
- Add model-explorer and walkthrough sidecars, shorten GitHub READMEs to the approved introduction and Quickstart, and regenerate template indexes.
- Keep the Financial Index Replication model names aligned with its approved walkthrough.

Why:
- Let the documentation site generate model, download, and walkthrough sections from the canonical template source while the GitHub README remains runnable.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Expose the complete portfolio model
c2a2720 
What changed:
- Move portfolio concepts, properties, and relationships into the stable schema without changing their definitions.
- Add every portfolio concept and relationship to the model explorer sidecar, including unary rule and graph flags.
- Update the template authoring contract, walkthrough anchors, runbook, and schema coverage test.

Why:
- Let the generated visualizer represent the full portfolio model instead of only its source-backed base schema.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Align the portfolio walkthrough reference order
a65c4f0 
What changed:
- Reorder the compliance-step explanation to match the runner's reference order.

Why:
- Keep the generated walkthrough valid after moving relationship declarations into the stable schema.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Sep 29, 2026 •
edited
Loading

Copy link
Copy Markdown

The templates docs preview for this pull request has been deployed to Vercel!

✅ Preview: https://relationalai-docs-b8pk08gr3-relationalai.vercel.app/build/templates
🔍 Inspect: https://vercel.com/relationalai/relationalai-docs/BmKqBz95ooU1SYuFSggDBhHWXxPf

somacdivad and others added 9 commits September 29, 2026 15:02
@somacdivad
Label portfolio property roads
0341c15 
What changed:
- add reader-facing labels for the Scenario-to-Regime and FrontierPoint-to-Scenario property roads
- document property label overrides for template authors

Why:
- make concept-valued properties read like business relationships in the visualizer without changing model declarations

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Connect portfolio optimization properties
84fd2da 
What changed:
- label Stock scenario quantities and regime covariance as visual model connections
- document scalar-valued property road metadata and repeated concept inputs

Why:
- show how the stock universe connects to scenarios and regimes without changing the executable model

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Explain portfolio stages and candidate allocations
446e914 
What changed:
- Reworked the guided walkthrough around the schema, data loading, and four processing stages.
- Added a final report with stock amounts and weights for each scenario candidate.

Why:
- Connect the walkthrough to the executable pipeline and expose the allocations behind each selected summary.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Use verified portfolio allocation output
870238e 
What changed:
- Replaced the reproduced walkthrough allocation sample with values from a connected PyRel run.

Why:
- Keep the displayed candidate amounts, weights, returns, and volatility aligned with actual template output.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Align portfolio walkthrough with verified output
2360acd 
What changed:
- Refined the stage excerpts, references, and candidate-allocation explanation.
- Reused cached Stage 3 allocations and documented the exact connected-run output.

Why:
- Keep the walkthrough and runnable report aligned with the template’s actual behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Shorten enhanced template READMEs
1eb2015 
What changed:
- Link prominently to each complete template guide.
- Keep concise runnable Quickstarts with required access, dependencies, and success signals.
- Replace the Portfolio transcript with a verified representative excerpt.

Why:
- Keep GitHub entry points useful without duplicating the generated model explorers and walkthroughs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Flatten template source layout
8424455 
What changed:
- Move the current templates to the repository root and remove the legacy version trees.
- Update repository automation, validation, tests, and authoring guidance for the flat layout.

Why:
- Keep one canonical unversioned template collection while preserving docs artifact URLs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Build preview from companion docs branch
1d8e32b 
What changed:
- Check out the relationalai-docs PR branch in the templates preview workflow.

Why:
- The companion branch contains the flat-layout compatibility reader required by this templates PR before the docs change reaches main.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
Limit companion docs branch to PR 104
c8a0115 
What changed:
- Use the relationalai-docs companion branch only while rendering this pull request's preview.

Why:
- Future templates pull requests must return to docs main automatically after the paired migration lands.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@somacdivad
somacdivad marked this pull request as ready for review October 1, 2026 18:34
@somacdivad
somacdivad merged commit c6963dc into main Oct 1, 2026
3 checks passed
@somacdivad
somacdivad deleted the agents/template-refactor-and-docs-update-canonical branch October 1, 2026 18:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jablonskidev jablonskidev Awaiting requested review from jablonskidev jablonskidev is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@somacdivad