docs(schema): clarify that Option.insights may cite findings (companion to astra-tools#89)#39
Open
ksd3 wants to merge 1 commit into
Open
Conversation
Option.insights resolution previously read as if only prior_insights were
valid targets; in practice an option may also cite a finding produced by
this analysis (claims-of-this-analysis-justifying-a-downstream-choice).
Both kinds of Insight are equally valid evidence — the distinction is
which side of the analysis the claim originated on.
LinkML cannot express cross-collection referential integrity ("id must
resolve in either of two keyed maps"), so this is documentation only;
the enforcement update lives in LightconeResearch/astra-tools (closes
LightconeResearch/astra-tools#70). The expanded description here makes
the broader intent legible to schema readers.
- Expand Option.insights description in analysis.yaml
- Mirror the updated description in the generated astra_pydantic.py
Field(description=...) so the datamodel docstring matches the source
schema until the next regen
- Add a clarifying sentence to docs/specification.md, prior_insights /
findings / evidence section
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the description of
Option.insightsinanalysis.yamlto make explicit that an option may cite either aprior_insight(external evidence motivating the choice) or afinding(a claim produced by this analysis that in turn justifies a downstream choice). Both are equally validInsights — the distinction is which side of the analysis the claim originated on.This is the schema/docs side of LightconeResearch/astra-tools#70. The enforcement side lives in astra-tools#89. LinkML cannot express cross-collection referential integrity ("id must resolve in one of two keyed maps"), so the constraint can only be documented here; the actual union lookup happens in the semantic validator.
Files
src/astra/schema/analysis.yaml—Option.insightsdescription expanded to describe the union scope and the../-grammardocs/specification.md— one new paragraph in the prior_insights/findings/evidence sectionsrc/astra/datamodel/astra_pydantic.py— only theField(description=...)text forOption.insightsis updated so the generated docstring matches the source schema until the next full regen. No shape/type changes. (The maintainers' release flow regenerates the rest; I intentionally avoided shipping incidental noise like ametamodel_versionbump from a newer-locally-installed linkml.)Test plan
pytest— 10 passed (no test regressions)tests/test_validation.py— 83 passed)