From d79f9780a8ab049ed2424e10e6060c13f935ed2f Mon Sep 17 00:00:00 2001 From: Kshitij Duraphe Date: Fri, 15 May 2026 15:40:01 -0400 Subject: [PATCH] docs(schema): clarify that Option.insights may cite findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/specification.md | 2 ++ src/astra/datamodel/astra_pydantic.py | 2 +- src/astra/schema/analysis.yaml | 10 +++++++++- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 906b12f..c87557c 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -277,6 +277,8 @@ findings: Evidence is what lets a reader check a claim instead of simply accepting it. It can cite a paper, identify a passage in a source document, or point to an artifact produced by the analysis. The same structure works for prior insights and findings: a decision can say which insight supports it, and each insight can say exactly which source or output supports the claim. With evidence verification enabled, tools can check whether quoted text actually appears in the cited source. +An option's `insights:` list may cite either a `prior_insight` (external evidence motivating the choice) or a `finding` (a claim produced by this analysis that in turn justifies a downstream choice). Both kinds of `Insight` are equally valid evidence — the distinction is which side of the analysis the claim originated on. + ### Excluded options A rejected option can still be scientifically important. ASTRA lets authors keep it in the record while marking it as unavailable for valid universes. diff --git a/src/astra/datamodel/astra_pydantic.py b/src/astra/datamodel/astra_pydantic.py index a49a950..1399fcc 100644 --- a/src/astra/datamodel/astra_pydantic.py +++ b/src/astra/datamodel/astra_pydantic.py @@ -629,7 +629,7 @@ class Option(ConfiguredBaseModel): 'Analysis']} }) label: str = Field(default=..., description="""Human-readable name for the option""", json_schema_extra = { "linkml_meta": {'domain_of': ['Insight', 'Input', 'Output', 'Option', 'Decision']} }) description: Optional[str] = Field(default=None, description="""Detailed description of the option""", json_schema_extra = { "linkml_meta": {'domain_of': ['Universe', 'Input', 'Output', 'Option']} }) - insights: Optional[list[str]] = Field(default=None, description="""Insight IDs supporting this option""", json_schema_extra = { "linkml_meta": {'domain_of': ['InsightCollection', 'Option']} }) + insights: Optional[list[str]] = Field(default=None, description="""Insight IDs supporting this option. May reference entries from either ``prior_insights`` (external/literature claims that motivate the choice) or ``findings`` (claims produced by this analysis that in turn justify it). The semantic validator resolves bare ids against the union of those two maps at the node-local scope, and ``../id`` / ``../../id`` against the corresponding union at an ancestor scope (matching the ``../`` grammar used by ``Input.from`` and ``Decision.from``).""", json_schema_extra = { "linkml_meta": {'domain_of': ['InsightCollection', 'Option']} }) incompatible_with: Optional[list[str]] = Field(default=None, description="""Decision.option pairs that cannot be selected together""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} }) requires: Optional[list[str]] = Field(default=None, description="""Decision.option pairs that must also be selected""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} }) excluded: Optional[bool] = Field(default=None, description="""Whether this option was considered and rejected""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} }) diff --git a/src/astra/schema/analysis.yaml b/src/astra/schema/analysis.yaml index 31d1441..7f8689c 100644 --- a/src/astra/schema/analysis.yaml +++ b/src/astra/schema/analysis.yaml @@ -491,7 +491,15 @@ classes: description: Detailed description of the option insights: multivalued: true - description: Insight IDs supporting this option + description: >- + Insight IDs supporting this option. May reference entries from + either ``prior_insights`` (external/literature claims that + motivate the choice) or ``findings`` (claims produced by this + analysis that in turn justify it). The semantic validator + resolves bare ids against the union of those two maps at the + node-local scope, and ``../id`` / ``../../id`` against the + corresponding union at an ancestor scope (matching the ``../`` + grammar used by ``Input.from`` and ``Decision.from``). incompatible_with: multivalued: true description: Decision.option pairs that cannot be selected together