qwen-sci 0.2.2__py3-none-any.whl

src/agents/research_plan_author/section_router.py

@@ -0,0 +1,209 @@
+"""Deterministic, cross-discipline section routing for research-plan writing."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Mapping
+
+
+AUTHOR_TEMPLATE_FAMILIES = (
+    "computational_digital",
+    "mathematics_theory",
+    "materials_chemical",
+    "engineering_energy",
+    "earth_environment_agro",
+    "life_veterinary",
+    "clinical_health",
+)
+
+_DISCIPLINE_TEMPLATE = {
+    "17": "computational_digital",
+    "26": "mathematics_theory",
+    "15": "materials_chemical",
+    "16": "materials_chemical",
+    "25": "materials_chemical",
+    "21": "engineering_energy",
+    "22": "engineering_energy",
+    "11": "earth_environment_agro",
+    "19": "earth_environment_agro",
+    "23": "earth_environment_agro",
+    "13": "life_veterinary",
+    "24": "life_veterinary",
+    "28": "life_veterinary",
+    "30": "life_veterinary",
+    "34": "life_veterinary",
+    "27": "clinical_health",
+    "29": "clinical_health",
+    "35": "clinical_health",
+    "36": "clinical_health",
+}
+
+_COMMON_ROUTES = (
+    ("abstract", "Abstract", "abstract", ("planned_contribution", "expected_outcome")),
+    ("introduction", "Introduction", "sections", ("background", "research_gap", "planned_contribution", "design_assumption")),
+    ("survey_and_research_gap", "Background, Survey, and Research Gap", "sections", ("background", "survey_evidence", "research_gap")),
+    ("research_questions_and_contributions", "Research Questions and Planned Contributions", "sections", ("research_question", "planned_contribution", "design_assumption")),
+    ("idea_origin_and_selection", "Idea Source Checkpoints and Direction Selection Audit", "sections", ("idea_provenance", "design_assumption")),
+    ("formal_problem_and_hypotheses", "Problem Definition, Assumptions, and Hypotheses", "sections", ("formal_definition", "formal_proposition", "hypothesis", "design_assumption")),
+    ("study_design_and_methods", "Study Design and Methods", "sections", ("planned_method", "design_assumption", "needs_human_input")),
+    ("expected_outcomes", "Expected Outcome Branches and Conditional Conclusions", "sections", ("expected_outcome", "conditional_conclusion")),
+    ("risk_limitations_and_review", "Risks, Limitations, and Human Review Requirements", "sections", ("limitation", "needs_human_input", "review_requirement")),
+    ("references", "References", "sections", ("citation_inventory",)),
+    ("appendix_idea_evolution", "Idea Source Checkpoints and Direction Selection Audit", "appendices", ("idea_provenance",)),
+    ("appendix_variables_and_definitions", "Variables, Symbols, and Operational Definitions", "appendices", ("formal_definition", "planned_method", "design_assumption", "needs_human_input")),
+    ("appendix_evidence_and_review", "Evidence Coverage, Unknown Items, and Review Checklist", "appendices", ("survey_evidence", "limitation", "review_requirement", "needs_human_input")),
+)
+
+_TEMPLATE_ROUTES = {
+    "computational_digital": (
+        ("computational_evaluation_protocol", "Data, Baselines, Ablations, and Robustness", ("planned_method", "design_assumption", "needs_human_input")),
+    ),
+    "mathematics_theory": (
+        ("definitions_and_propositions", "Definitions, Propositions, and Proof Obligations", ("formal_definition", "formal_proposition", "proof_obligation")),
+        ("forward_derivation_and_counterexamples", "Forward Derivation and Counterexample Search Plan", ("forward_derivation", "counterexample_plan", "limitation")),
+    ),
+    "materials_chemical": (
+        ("materials_and_characterization", "Material System, Characterization, and DOE Plan", ("planned_method", "design_assumption", "needs_human_input")),
+    ),
+    "engineering_energy": (
+        ("system_boundary_and_validation", "System Boundary, Constraints, and Layered Validation", ("planned_method", "design_assumption", "needs_human_input")),
+    ),
+    "earth_environment_agro": (
+        ("spatiotemporal_design", "Spatiotemporal Units, Sampling Frame, and Environmental Covariates", ("planned_method", "design_assumption", "needs_human_input")),
+    ),
+    "life_veterinary": (
+        ("model_controls_and_repeats", "Model System, Controls, Assays, and Replicates", ("planned_method", "design_assumption", "needs_human_input", "review_requirement")),
+    ),
+    "clinical_health": (
+        ("pico_endpoints_and_governance", "PICO, Endpoints, Bias Control, and Governance", ("planned_method", "design_assumption", "needs_human_input", "review_requirement")),
+    ),
+}
+
+_MATHEMATICS_THEORY_ROUTE_ROLES = {
+    "formal_problem_and_hypotheses": "candidate_theorem_entry",
+    "definitions_and_propositions": "theory_control_panel",
+    "forward_derivation_and_counterexamples": "derivation_and_falsification",
+    "expected_outcomes": "preregistered_decision_protocol",
+    "risk_limitations_and_review": "release_and_review_protocol",
+    "appendix_variables_and_definitions": "energy_condition_boundary_defense",
+}
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def resolve_author_template(author_input: Mapping[str, Any]) -> str:
+    """Resolve one author template from upstream routing, then declared disciplines."""
+
+    provenance = _mapping(author_input.get("provenance"))
+    configured = _text(provenance.get("template_id"))
+    if configured in AUTHOR_TEMPLATE_FAMILIES:
+        return configured
+    composition = _mapping(author_input.get("template_composition"))
+    configured = _text(composition.get("template_id"))
+    if configured in AUTHOR_TEMPLATE_FAMILIES:
+        return configured
+    disciplines = provenance.get("discipline_ids") if isinstance(provenance.get("discipline_ids"), list) else []
+    if "31" in {_text(item) for item in disciplines}:
+        selected = _mapping(author_input.get("selected_direction"))
+        context = " ".join(
+            _text(value).casefold()
+            for value in (
+                selected.get("title"),
+                selected.get("central_hypothesis"),
+                selected.get("mechanism_or_relation"),
+            )
+        )
+        return "mathematics_theory" if any(term in context for term in ("theorem", "proof", "derivation", "counterexample", "formal")) else "engineering_energy"
+    for discipline_id in disciplines:
+        resolved = _DISCIPLINE_TEMPLATE.get(_text(discipline_id))
+        if resolved:
+            return resolved
+    return "computational_digital"
+
+
+def route_author_sections(author_input: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a fixed route that the LLM may fill but never expand or reorder."""
+
+    template_family = resolve_author_template(author_input)
+    template_routes = _TEMPLATE_ROUTES[template_family]
+    routes: list[dict[str, Any]] = []
+    for section_id, title, target, claim_kinds in _COMMON_ROUTES:
+        if section_id == "references":
+            for extra_id, extra_title, extra_claim_kinds in template_routes:
+                template_route = {
+                    "section_id": extra_id,
+                    "title": extra_title,
+                    "target": "sections",
+                    "applicability": "required",
+                    "allowed_claim_kinds": list(extra_claim_kinds),
+                }
+                theory_role = _MATHEMATICS_THEORY_ROUTE_ROLES.get(extra_id) if template_family == "mathematics_theory" else ""
+                if theory_role:
+                    template_route["theory_role"] = theory_role
+                routes.append(template_route)
+        route = {
+            "section_id": section_id,
+            "title": title,
+            "target": target,
+            "applicability": "required" if section_id != "appendix_idea_evolution" else "optional",
+            "allowed_claim_kinds": list(claim_kinds),
+        }
+        theory_role = (
+            _MATHEMATICS_THEORY_ROUTE_ROLES.get(section_id)
+            if template_family == "mathematics_theory"
+            else ""
+        )
+        if theory_role:
+            route["theory_role"] = theory_role
+        routes.append(route)
+    if template_family == "mathematics_theory":
+        for route in routes:
+            if route.get("section_id") == "appendix_variables_and_definitions":
+                route["title"] = "Energy-Condition Taxonomy, Symbols, and Boundary Defense"
+        appendix_order = {
+            "appendix_variables_and_definitions": 0,
+            "appendix_idea_evolution": 1,
+            "appendix_evidence_and_review": 2,
+        }
+        routes = sorted(
+            enumerate(routes),
+            key=lambda item: (
+                1 if item[1].get("target") == "appendices" else 0,
+                appendix_order.get(_text(item[1].get("section_id")), 99),
+                item[0],
+            ),
+        )
+        routes = [route for _index, route in routes]
+    return {
+        "schema_version": "research_plan_author_section_routing_v1",
+        "template_family": template_family,
+        "routes": routes,
+        "theory_sampling_power_status": "not_applicable" if template_family == "mathematics_theory" else "route_specific",
+    }
+
+
+def required_route_ids(routing: Mapping[str, Any]) -> list[str]:
+    return [
+        _text(route.get("section_id"))
+        for route in routing.get("routes") or []
+        if isinstance(route, Mapping) and _text(route.get("applicability")) == "required"
+    ]
+
+
+def route_copy(routing: Mapping[str, Any]) -> dict[str, Any]:
+    return deepcopy(dict(routing))
+
+
+__all__ = [
+    "AUTHOR_TEMPLATE_FAMILIES",
+    "required_route_ids",
+    "resolve_author_template",
+    "route_author_sections",
+    "route_copy",
+]

src/agents/research_plan_author/semantic_validator.py

@@ -0,0 +1,254 @@
+"""Cross-section semantic validation for a proposal-only Research Plan document."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .contracts import (
+    AUTHORING_LANGUAGE,
+    validate_research_plan_document,
+)
+from .latex_safety import (
+    contains_observed_result_language,
+)
+from .section_router import required_route_ids
+from .theory_spine import theory_spine_internal_ids_in_text
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _canonical(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+
+def validate_composed_research_plan(
+    document: object,
+    *,
+    preparation: Mapping[str, Any],
+    routing: Mapping[str, Any],
+    source_registry: Mapping[str, Any],
+) -> list[str]:
+    """Reject forged identifiers and scientific-status upgrades only.
+
+    Writing quality, route recommendations, evidence-card wording, and
+    cross-section repetition are deliberately handled as non-blocking quality
+    concerns.  This final pass protects the proposal boundary rather than
+    restricting legitimate synthesis of upstream artifacts.
+    """
+
+    errors = validate_research_plan_document(document)
+    if not isinstance(document, Mapping):
+        return errors
+    payload = dict(document)
+    if payload.get("document_status") != "PROPOSAL_NO_OBSERVED_RESULTS":
+        errors.append("composed document must remain PROPOSAL_NO_OBSERVED_RESULTS")
+    if payload.get("language") != AUTHORING_LANGUAGE:
+        errors.append("composed document language must be English")
+    metadata = _mapping(payload.get("document_metadata"))
+    for text_field in (metadata.get("title"), payload.get("abstract", {}).get("text") if isinstance(payload.get("abstract"), Mapping) else ""):
+        if contains_observed_result_language(text_field):
+            errors.append("composed document presents an observed result in visible prose")
+    all_sections = [
+        section
+        for section in [*(payload.get("sections") or []), *(payload.get("appendices") or [])]
+        if isinstance(section, Mapping)
+    ]
+    document_block_kinds = {
+        f"{_text(section.get('section_id'))}:{_text(block.get('block_id'))}": _text(block.get("kind"))
+        for section in all_sections
+        if _text(section.get("section_id"))
+        for block in section.get("blocks") or []
+        if isinstance(block, Mapping) and _text(block.get("block_id"))
+    }
+    section_ids = {_text(section.get("section_id")) for section in all_sections}
+    theory_unit_ids: set[str] = set()
+    theory_spine = _mapping(preparation.get("theory_spine"))
+    for collection_name, identifier_field in (
+        ("lemma_units", "lemma_id"),
+        ("proof_obligations", "proof_obligation_id"),
+        ("falsifiers", "falsifier_id"),
+        ("decision_branches", "branch_id"),
+    ):
+        theory_unit_ids.update(
+            _text(record.get(identifier_field))
+            for record in theory_spine.get(collection_name) or []
+            if isinstance(record, Mapping) and _text(record.get(identifier_field))
+        )
+    blueprint_sections = {
+        _text(section.get("section_id")): _mapping(section)
+        for section in _mapping(payload.get("authoring_blueprint")).get("sections") or []
+        if isinstance(section, Mapping) and _text(section.get("section_id"))
+    }
+    required_ids = set(required_route_ids(routing))
+    if "abstract" in required_ids:
+        abstract = _mapping(payload.get("abstract"))
+        if not _text(abstract.get("text")):
+            errors.append("composed document omits required abstract content")
+        elif not {_text(claim_id) for claim_id in abstract.get("claim_ids") or [] if _text(claim_id)}:
+            errors.append("composed document abstract must reference at least one claim ID")
+        required_ids.remove("abstract")
+    missing = required_ids - section_ids
+    if missing:
+        errors.append(f"composed document omits required routed sections: {sorted(missing)}")
+    for visible_label, text_value in (
+        ("document title", metadata.get("title")),
+        ("abstract", _mapping(payload.get("abstract")).get("text")),
+        *(("keyword", keyword) for keyword in payload.get("keywords") or []),
+    ):
+        private_ids = theory_spine_internal_ids_in_text(text_value)
+        if private_ids:
+            errors.append(f"{visible_label} exposes private theory identifiers: {private_ids}")
+    claims = [claim for claim in payload.get("claim_provenance") or [] if isinstance(claim, Mapping)]
+    claim_ids = [_text(claim.get("claim_id")) for claim in claims]
+    if len(claim_ids) != len(set(claim_ids)):
+        errors.append("document contains duplicate claim_id values")
+    claim_id_set = set(claim_ids)
+    for section in all_sections:
+        section_id = _text(section.get("section_id"))
+        allowed_theory_units = {
+            _text(unit_id)
+            for field_name in ("lemma_ids", "proof_obligation_ids", "falsifier_ids", "decision_branch_ids")
+            for unit_id in _mapping(blueprint_sections.get(section_id)).get("theory_unit_references", {}).get(field_name, [])
+            if _text(unit_id)
+        }
+        private_ids = theory_spine_internal_ids_in_text(section.get("title"))
+        if private_ids:
+            errors.append(f"section {section_id} title exposes private theory identifiers: {private_ids}")
+        blocks = [block for block in section.get("blocks") or [] if isinstance(block, Mapping)]
+        block_kinds = {
+            _text(block.get("block_id")): _text(block.get("kind")) for block in blocks
+        }
+        for block in blocks:
+            block_id = _text(block.get("block_id")) or "unnamed"
+            block_text = _text(block.get("text"))
+            for field_name in ("heading", "text"):
+                private_ids = theory_spine_internal_ids_in_text(block.get(field_name))
+                if private_ids:
+                    errors.append(
+                        f"section block {block_id} exposes private theory identifiers in {field_name}: {private_ids}"
+                    )
+            if not (section_id == "references" and block_id == "bibliography") and contains_observed_result_language(block_text):
+                errors.append(f"section block {block_id} presents an observed result")
+            block_claim_ids = {_text(claim_id) for claim_id in block.get("claim_ids") or [] if _text(claim_id)}
+            if block_text and not block_claim_ids:
+                errors.append(f"section block {block_id} must reference at least one claim ID")
+            unknown_claims = block_claim_ids - claim_id_set
+            if unknown_claims:
+                errors.append(f"section block {block.get('block_id')} references unknown claims")
+            reference_ids = {
+                _text(reference_id)
+                for reference_id in block.get("reference_block_ids") or []
+                if _text(reference_id)
+            }
+            local_references = {reference_id for reference_id in reference_ids if ":" not in reference_id}
+            scoped_references = reference_ids - local_references
+            if (local_references - set(block_kinds)) or (scoped_references - set(document_block_kinds)):
+                errors.append(f"section block {block_id} references an unknown equation block")
+            if any(
+                (reference_id in block_kinds and block_kinds.get(reference_id) != "equation")
+                or (
+                    reference_id in document_block_kinds
+                    and document_block_kinds.get(reference_id) != "equation"
+                )
+                for reference_id in reference_ids
+            ):
+                errors.append(f"section block {block_id} cross-references a non-equation block")
+            unknown_theory_units = {
+                _text(unit_id)
+                for unit_id in block.get("theory_unit_ids") or []
+                if _text(unit_id)
+            } - theory_unit_ids
+            if unknown_theory_units:
+                errors.append(f"section block {block_id} references an unknown theory unit")
+            nonlocal_theory_units = {
+                _text(unit_id)
+                for unit_id in block.get("theory_unit_ids") or []
+                if _text(unit_id)
+            } & theory_unit_ids - allowed_theory_units
+            if nonlocal_theory_units:
+                errors.append(f"section block {block_id} references a theory unit outside its section slice")
+    allowed_sources = set(source_registry.get("allowed_source_ids") or [])
+    allowed_anchors = set(source_registry.get("allowed_survey_anchor_ids") or [])
+    cards = _mapping(source_registry.get("evidence_cards_by_id"))
+    allowed_card_ids = set(cards)
+    citation_keys = {
+        _text(record.get("citation_key"))
+        for record in payload.get("citation_registry") or []
+        if isinstance(record, Mapping)
+    }
+    formal_ids: set[str] = set()
+    frozen = _mapping(_mapping(preparation.get("source_bundle")).get("author_context"))
+    plan = _mapping(frozen.get("formal_reasoning"))
+    for collection, field in (("definitions", "definition_id"), ("assumptions", "assumption_id"), ("propositions", "proposition_id"), ("proof_obligations", "obligation_id")):
+        formal_ids.update(_text(item.get(field)) for item in plan.get(collection) or [] if isinstance(item, Mapping))
+    formal_ids.update(_text(item.get("step_id")) for item in _mapping(plan.get("forward_derivation")).get("steps") or [] if isinstance(item, Mapping))
+    branch_ids = {
+        _text(branch.get("branch_id"))
+        for branch in frozen.get("outcome_branches") or []
+        if isinstance(branch, Mapping)
+    }
+    for claim in claims:
+        claim_id = _text(claim.get("claim_id"))
+        claim_kind = _text(claim.get("claim_kind"))
+        qualification = _text(claim.get("qualification"))
+        statement = _text(claim.get("statement"))
+        if claim_kind == "observed_result" or contains_observed_result_language(statement):
+            errors.append(f"claim {claim_id} presents an observed result")
+        if set(claim.get("source_ids") or []) - allowed_sources:
+            errors.append(f"claim {claim_id} has an unregistered source")
+        if set(claim.get("survey_anchor_ids") or []) - allowed_anchors:
+            errors.append(f"claim {claim_id} has an unregistered survey anchor")
+        if set(claim.get("evidence_card_ids") or []) - allowed_card_ids:
+            errors.append(f"claim {claim_id} has an unregistered evidence card")
+        if set(claim.get("formal_reference_ids") or []) - formal_ids:
+            errors.append(f"claim {claim_id} has an unregistered formal reference")
+        if set(claim.get("citation_keys") or []) - citation_keys:
+            errors.append(f"claim {claim_id} has an invented citation key")
+        if claim_kind == "expected_outcome":
+            if qualification != "expected_not_observed" or not set(claim.get("outcome_branch_ids") or []):
+                errors.append(f"expected outcome claim {claim_id} is not a conditional branch")
+            if set(claim.get("outcome_branch_ids") or []) - branch_ids:
+                errors.append(f"expected outcome claim {claim_id} references an unknown outcome branch")
+    final_unknowns = payload.get("open_items") if isinstance(payload.get("open_items"), list) else []
+    final_reviews = payload.get("review_items") if isinstance(payload.get("review_items"), list) else []
+    expected_unknown_ids = {str(item.get("source_item_id") or "") for item in source_registry.get("unknown_items") or [] if isinstance(item, Mapping)}
+    expected_review_ids = {str(item.get("source_item_id") or "") for item in source_registry.get("review_items") or [] if isinstance(item, Mapping)}
+    final_unknown_id_list = [str(item.get("source_item_id") or "") for item in final_unknowns if isinstance(item, Mapping)]
+    final_review_id_list = [str(item.get("source_item_id") or "") for item in final_reviews if isinstance(item, Mapping)]
+    final_unknown_ids = set(final_unknown_id_list)
+    final_review_ids = set(final_review_id_list)
+    if final_unknown_ids != expected_unknown_ids:
+        errors.append("composed document dropped or invented an upstream unknown item")
+    if final_review_ids != expected_review_ids:
+        errors.append("composed document dropped or invented an upstream human-review item")
+    if len(final_unknown_id_list) != len(final_unknown_ids) or len(final_review_id_list) != len(final_review_ids):
+        errors.append("composed document repeats an upstream unknown or human-review item")
+    for item in final_unknowns:
+        if isinstance(item, Mapping) and item.get("status") != "needs_human_input":
+            errors.append("composed document open_items must use status=needs_human_input")
+    for item in final_reviews:
+        if isinstance(item, Mapping) and item.get("status") != "review_required":
+            errors.append("composed document review_items must use status=review_required")
+    if routing.get("template_family") == "mathematics_theory":
+        if _mapping(payload.get("source_manifest")).get("theory_sampling_power_status") != "not_applicable":
+            errors.append("mathematics/theory sampling and power must be recorded as not_applicable")
+        methods_text = " ".join(
+            _text(block.get("text"))
+            for section in all_sections
+            if _text(section.get("section_id")) == "study_design_and_methods"
+            for block in section.get("blocks") or []
+            if isinstance(block, Mapping)
+        ).casefold()
+        if ("sample size" in methods_text or "statistical power" in methods_text) and "not applicable" not in methods_text:
+            errors.append("mathematics/theory sampling and power must remain not_applicable")
+    return sorted(set(errors))
+
+
+__all__ = ["validate_composed_research_plan"]

src/agents/research_plan_author/source_bundle.py

@@ -0,0 +1,46 @@
+"""Build the bounded, traceable source bundle consumed by later Author stages."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Mapping
+
+from .contracts import AUTHORING_LANGUAGE, AUTHOR_SOURCE_BUNDLE_SCHEMA, AUTHOR_SOURCE_BUNDLE_SCHEMA_VERSION
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def build_author_source_bundle(
+    author_input: Mapping[str, Any],
+    *,
+    author_input_path: str,
+    author_input_identity: Mapping[str, Any],
+    survey_sources: Mapping[str, Any],
+    survey_binding: Mapping[str, Any],
+    idea_evolution: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Create a source-addressable bundle without parsing human-readable Markdown."""
+
+    provenance = _mapping(author_input.get("provenance"))
+    bundle = {
+        "schema_version": AUTHOR_SOURCE_BUNDLE_SCHEMA_VERSION,
+        "language": AUTHORING_LANGUAGE,
+        "source_design_id": _text(author_input.get("source_design_id")),
+        "selected_direction_id": _text(provenance.get("selected_direction_id")),
+        "author_input_path": _text(author_input_path),
+        "author_input_identity": deepcopy(dict(author_input_identity)),
+        "author_context": deepcopy(dict(author_input)),
+        "survey_sources": deepcopy(dict(survey_sources)),
+        "survey_binding": deepcopy(dict(survey_binding)),
+        "idea_evolution": deepcopy(dict(idea_evolution)),
+    }
+    return bundle
+
+
+__all__ = ["AUTHOR_SOURCE_BUNDLE_SCHEMA", "build_author_source_bundle"]