qwen-sci 0.2.2__py3-none-any.whl

src/pipeline/multimodal_evidence/perception.py

@@ -0,0 +1,277 @@
+"""Constrained qwen3-vl-plus perception for explicitly supplied data only."""
+
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from src.llm.vision import QwenVisionClient, resolve_vision_settings
+
+from .contract import MultimodalInputError, MultimodalInputSpec
+from .rendering import PreviewRenderError, render_png_preview, supports_remote_preview
+from .safety import violates_noncausal_policy
+
+
+QWEN3_VL_PLUS = "qwen3-vl-plus"
+_FOCUSES = ("mechanism", "measurement", "boundary", "contradiction", "theory")
+OBSERVATION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "finding": {"type": "string", "minLength": 4, "maxLength": 700},
+        "candidate_explanation": {"type": "string", "minLength": 4, "maxLength": 700},
+        "alternative_explanations": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 3,
+            "items": {"type": "string", "minLength": 3, "maxLength": 400},
+        },
+        "discriminating_prediction": {"type": "string", "minLength": 4, "maxLength": 500},
+        "falsifier": {"type": "string", "minLength": 4, "maxLength": 500},
+        "claim_limits": {"type": "string", "minLength": 8, "maxLength": 500},
+        "confidence": {"type": "string", "enum": ["low", "medium", "high"]},
+        "focus": {"type": "string", "enum": list(_FOCUSES)},
+    },
+    "required": [
+        "finding",
+        "candidate_explanation",
+        "alternative_explanations",
+        "discriminating_prediction",
+        "falsifier",
+        "claim_limits",
+        "confidence",
+        "focus",
+    ],
+    "additionalProperties": False,
+}
+
+
+def run_remote_perception(
+    *,
+    input_spec: MultimodalInputSpec,
+    local_context: Mapping[str, Any],
+    config: Any,
+    max_calls: int,
+    max_preview_pixels: int,
+    max_preview_bytes: int,
+    client_factory: Callable[..., Any] | None = None,
+) -> tuple[list[dict[str, Any]], list[str], dict[str, str]]:
+    """Return validated observation cards without retaining previews or raw replies."""
+
+    if not bool(local_context.get("remote_perception_authorized")):
+        return [], [], {}
+    if max_calls < 1:
+        raise MultimodalInputError("max_vl_calls must be at least 1 when remote perception is enabled.")
+    settings = _resolve_pinned_vision_settings(config)
+    factory = client_factory or QwenVisionClient
+    client = factory(
+        model=settings["model"],
+        provider=settings["provider"],
+        api_key=settings["api_key"],
+        base_url=settings["base_url"],
+        timeout=settings["timeout"],
+        config=config,
+    )
+    records_by_id = {record.record_id: record for record in input_spec.records}
+    findings_by_id = {
+        str(finding.get("record_id")): finding
+        for finding in local_context.get("native_findings", [])
+        if isinstance(finding, Mapping) and finding.get("status") == "success"
+    }
+    selected_ids = {
+        str(record_id)
+        for record_id in local_context.get("selected_record_ids", [])
+        if str(record_id) in records_by_id and str(record_id) in findings_by_id
+    }
+    selected_records = [
+        record
+        for record in sorted(input_spec.records, key=lambda item: item.input_index)
+        if record.record_id in selected_ids
+    ]
+    previewable_records = [
+        record for record in selected_records if supports_remote_preview(record)
+    ]
+    candidates = _representative_preview_records(previewable_records)
+    observations: list[dict[str, Any]] = []
+    limitations: list[str] = []
+    sent_record_ids: list[str] = []
+    remote_call_count = 0
+    for record in candidates:
+        if remote_call_count >= max_calls:
+            break
+        record_id = record.record_id
+        finding = findings_by_id[record_id]
+        try:
+            preview = render_png_preview(
+                record,
+                finding,
+                max_pixels=max_preview_pixels,
+                max_bytes=max_preview_bytes,
+            )
+        except PreviewRenderError as exc:
+            limitations.append(f"Record {record_id} was not sent for remote perception: {exc}")
+            continue
+        try:
+            response = client.describe_json(
+                preview,
+                prompt=_observation_prompt(record.modality),
+                schema=OBSERVATION_SCHEMA,
+                media_type="image/png",
+                max_tokens=min(int(settings["max_tokens"]), 1200),
+            )
+        except Exception as exc:
+            raise MultimodalInputError(
+                "Remote perception failed for an explicitly authorized preview; no fallback model was used."
+            ) from exc
+        remote_call_count += 1
+        sent_record_ids.append(record_id)
+        observation = _sanitize_observation(response, record_id=record_id, modality=record.modality)
+        if observation is None:
+            limitations.append(
+                f"Record {record_id} returned an observation outside the non-causal claim policy."
+            )
+            continue
+        observations.append(observation)
+    unsupported_modalities = sorted(
+        {record.modality for record in selected_records if not supports_remote_preview(record)}
+    )
+    if unsupported_modalities:
+        limitations.append(
+            "Selected records for these modalities have no Batch B remote preview and remained local-only: "
+            + ", ".join(unsupported_modalities)
+        )
+    if len(candidates) > max_calls:
+        excluded_record_ids = [record.record_id for record in candidates[max_calls:]]
+        limitations.append(
+            f"Remote perception used the configured budget of {max_calls} stratified cross-modality previews; "
+            f"eligible record IDs deferred by budget: {', '.join(excluded_record_ids)}."
+        )
+    return observations, limitations, {
+        "provider": settings["provider"],
+        "model": settings["model"],
+        "record_ids": sent_record_ids,
+    }
+
+
+def _representative_preview_records(
+    records: Sequence[Any],
+) -> list[Any]:
+    """Round-robin selected records across modalities and metadata strata."""
+
+    by_modality: "OrderedDict[str, list[Any]]" = OrderedDict()
+    for record in records:
+        by_modality.setdefault(record.modality, []).append(record)
+    modality_queues: "OrderedDict[str, list[Any]]" = OrderedDict()
+    for modality, modality_records in by_modality.items():
+        by_stratum: "OrderedDict[tuple[str, str, str, str], list[Any]]" = OrderedDict()
+        for record in modality_records:
+            metadata = record.metadata
+            stratum = tuple(
+                str(metadata.get(key, ""))
+                for key in ("label", "group", "condition", "timepoint")
+            )
+            by_stratum.setdefault(stratum, []).append(record)
+        queue: list[Any] = []
+        round_index = 0
+        while True:
+            added = False
+            for stratum_records in by_stratum.values():
+                if round_index < len(stratum_records):
+                    queue.append(stratum_records[round_index])
+                    added = True
+            if not added:
+                break
+            round_index += 1
+        modality_queues[modality] = queue
+    ordered: list[Any] = []
+    round_index = 0
+    while True:
+        added = False
+        for queue in modality_queues.values():
+            if round_index < len(queue):
+                ordered.append(queue[round_index])
+                added = True
+        if not added:
+            return ordered
+        round_index += 1
+
+
+def _resolve_pinned_vision_settings(config: Any) -> dict[str, Any]:
+    multimodal = _multimodal_settings(config)
+    configured_model = str(multimodal.get("quality_model") or "").strip()
+    if configured_model != QWEN3_VL_PLUS:
+        raise MultimodalInputError(
+            "Remote multimodal perception requires survey.multimodal_evidence.quality_model=qwen3-vl-plus."
+        )
+    try:
+        settings = resolve_vision_settings(config, batch=False)
+    except Exception as exc:
+        raise MultimodalInputError("Remote vision settings could not be resolved.") from exc
+    if str(settings.get("model") or "").strip() != QWEN3_VL_PLUS:
+        raise MultimodalInputError(
+            "Remote multimodal perception is pinned to qwen3-vl-plus; batch or flash models are not permitted."
+        )
+    if str(settings.get("provider") or "").strip().casefold() != "qwen":
+        raise MultimodalInputError(
+            "Remote multimodal perception requires the Qwen provider for qwen3-vl-plus."
+        )
+    return dict(settings)
+
+
+def _multimodal_settings(config: Any) -> Mapping[str, Any]:
+    survey = config.get("survey") if hasattr(config, "get") and config.get("survey") is not None else config
+    settings = survey.get("multimodal_evidence", {}) if hasattr(survey, "get") else {}
+    return settings if isinstance(settings, Mapping) or hasattr(settings, "get") else {}
+
+
+def _observation_prompt(modality: str) -> str:
+    return f"""You are reviewing one sanitized PNG preview derived from an explicitly supplied {modality} record.
+Return exactly one JSON object matching the provided schema. Treat only visible preview content as evidence.
+
+Rules:
+- Describe a local pattern, not a settled scientific result. Never claim causality, universality, priority, or proof.
+- Provide a tentative candidate explanation, at least one competing explanation, one discriminating prediction, and one falsifier.
+- State clear limits: this is one bounded representative preview and cannot identify people, patients, identities, raw records, or metadata.
+- Do not transcribe raw data, infer hidden values, or mention file names or paths.
+- Use concise scientific English; use confidence=low unless the visible preview itself is unambiguous.
+"""
+
+
+def _sanitize_observation(
+    value: Mapping[str, Any],
+    *,
+    record_id: str,
+    modality: str,
+) -> dict[str, Any] | None:
+    raw = dict(value)
+    text_fields = (
+        "finding",
+        "candidate_explanation",
+        "discriminating_prediction",
+        "falsifier",
+        "claim_limits",
+    )
+    normalized = {key: _clean_text(raw.get(key), limit=700) for key in text_fields}
+    alternatives = [
+        _clean_text(item, limit=400)
+        for item in raw.get("alternative_explanations", [])
+        if _clean_text(item, limit=400)
+    ][:3]
+    if not all(normalized.values()) or not alternatives:
+        return None
+    if any(violates_noncausal_policy(item) for item in [*normalized.values(), *alternatives]):
+        return None
+    return {
+        "observation_id": "",
+        "record_ids": [record_id],
+        "modality": modality,
+        **normalized,
+        "alternative_explanations": alternatives,
+        "confidence": str(raw.get("confidence") or "low"),
+        "focus": str(raw.get("focus") or "mechanism"),
+    }
+
+
+def _clean_text(value: Any, *, limit: int) -> str:
+    return re.sub(r"\s+", " ", str(value or "").strip())[:limit]

src/pipeline/multimodal_evidence/query_binding.py

@@ -0,0 +1,65 @@
+"""External epistemic bindings for data-anchored SH query variants."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+SUPPORTED_EPISTEMIC_ROLES = frozenset(
+    {
+        "support",
+        "counter",
+        "alternative_explanation",
+        "boundary",
+        "measurement_confound",
+        "discriminating_test",
+    }
+)
+
+
+def normalize_query_variant_bindings(value: Any) -> list[dict[str, str]]:
+    """Validate outer-only metadata without expanding the SH schema."""
+
+    if value is None:
+        return []
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise ValueError("query_variant_bindings must be a list.")
+    bindings: list[dict[str, str]] = []
+    seen: set[tuple[str, str, str]] = set()
+    for index, item in enumerate(value, start=1):
+        if not isinstance(item, Mapping):
+            raise ValueError(f"query_variant_binding {index} must be an object.")
+        binding = {
+            "sub_hypothesis_id": _text(item.get("sub_hypothesis_id"), limit=120),
+            "slot_name": _text(item.get("slot_name"), limit=160),
+            "query_variant_id": _text(item.get("query_variant_id"), limit=80),
+            "epistemic_role": _text(item.get("epistemic_role"), limit=80).casefold(),
+            "evidence_mode": _text(item.get("evidence_mode"), limit=80).casefold(),
+            "required_result": _text(item.get("required_result"), limit=700),
+            "claim_id": _text(item.get("claim_id"), limit=120),
+        }
+        if not all(binding[key] for key in ("sub_hypothesis_id", "slot_name", "query_variant_id", "epistemic_role", "required_result", "claim_id")):
+            raise ValueError(f"query_variant_binding {index} has a missing required field.")
+        if binding["epistemic_role"] not in SUPPORTED_EPISTEMIC_ROLES:
+            raise ValueError(
+                f"query_variant_binding {index} has unsupported epistemic_role '{binding['epistemic_role']}'."
+            )
+        key = (binding["sub_hypothesis_id"], binding["slot_name"], binding["query_variant_id"])
+        if key in seen:
+            raise ValueError(f"Duplicate query_variant_binding for {'.'.join(key)}.")
+        seen.add(key)
+        bindings.append(binding)
+    return bindings
+
+
+def query_binding_lookup(value: Any) -> dict[tuple[str, str, str], dict[str, str]]:
+    return {
+        (binding["sub_hypothesis_id"], binding["slot_name"], binding["query_variant_id"]): binding
+        for binding in normalize_query_variant_bindings(value)
+    }
+
+
+def _text(value: Any, *, limit: int) -> str:
+    return re.sub(r"\s+", " ", str(value or "").strip())[:limit]

src/pipeline/multimodal_evidence/rendering.py

@@ -0,0 +1,120 @@
+"""Build bounded, metadata-free in-memory previews for remote perception."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any, Mapping
+
+from .contract import ValidatedMultimodalRecord
+
+
+_PREVIEWABLE_MODALITIES = frozenset({"image", "signal", "audio", "threeD", "trajectory"})
+
+
+class PreviewRenderError(ValueError):
+    """Raised when a selected record cannot become a bounded PNG preview."""
+
+
+def supports_remote_preview(record: ValidatedMultimodalRecord) -> bool:
+    return record.modality in _PREVIEWABLE_MODALITIES
+
+
+def render_png_preview(
+    record: ValidatedMultimodalRecord,
+    native_finding: Mapping[str, Any],
+    *,
+    max_pixels: int,
+    max_bytes: int,
+) -> bytes:
+    """Return a re-encoded PNG held only in memory.
+
+    Image records retain their pixels but lose source metadata. Other allowed
+    modalities become an aggregate-only card, so no source samples or table
+    contents are sent to a remote model.
+    """
+
+    if max_pixels < 1 or max_bytes < 1:
+        raise PreviewRenderError("Preview limits must be positive.")
+    if not supports_remote_preview(record):
+        raise PreviewRenderError("The selected modality has no remote preview in Batch B.")
+    if record.modality == "image":
+        return _render_image(record, max_pixels=max_pixels, max_bytes=max_bytes)
+    return _render_aggregate_card(
+        record,
+        native_finding,
+        max_pixels=max_pixels,
+        max_bytes=max_bytes,
+    )
+
+
+def _render_image(
+    record: ValidatedMultimodalRecord,
+    *,
+    max_pixels: int,
+    max_bytes: int,
+) -> bytes:
+    try:
+        from PIL import Image, ImageOps
+    except ImportError as exc:
+        raise PreviewRenderError("Pillow is required to prepare image previews.") from exc
+
+    try:
+        with Image.open(record.source_path) as source:
+            source.load()
+            transformed = ImageOps.exif_transpose(source).convert("RGB")
+            clean = Image.new("RGB", transformed.size)
+            clean.paste(transformed)
+    except Exception as exc:
+        raise PreviewRenderError("The selected image could not be rendered safely.") from exc
+    return _encode_bounded_png(clean, max_pixels=max_pixels, max_bytes=max_bytes)
+
+
+def _render_aggregate_card(
+    record: ValidatedMultimodalRecord,
+    native_finding: Mapping[str, Any],
+    *,
+    max_pixels: int,
+    max_bytes: int,
+) -> bytes:
+    try:
+        from PIL import Image, ImageDraw
+    except ImportError as exc:
+        raise PreviewRenderError("Pillow is required to prepare aggregate previews.") from exc
+
+    metrics = native_finding.get("metrics")
+    metric_count = len(metrics) if isinstance(metrics, Mapping) else 0
+    image = Image.new("RGB", (960, 540), "white")
+    draw = ImageDraw.Draw(image)
+    draw.rectangle((0, 0, 960, 86), fill=(20, 55, 93))
+    draw.text((34, 28), "Aggregate multimodal preview", fill="white")
+    draw.text((34, 130), f"Modality: {record.modality}", fill=(24, 24, 24))
+    draw.text((34, 184), "This visual contains bounded local summary metadata only.", fill=(24, 24, 24))
+    draw.text((34, 222), "Individual records, samples, and source paths are not included.", fill=(24, 24, 24))
+    draw.text((34, 286), f"Local aggregate metric groups available: {metric_count}", fill=(24, 24, 24))
+    draw.text((34, 390), "Interpret only visible aggregate structure; do not infer causality.", fill=(112, 38, 38))
+    return _encode_bounded_png(image, max_pixels=max_pixels, max_bytes=max_bytes)
+
+
+def _encode_bounded_png(image: Any, *, max_pixels: int, max_bytes: int) -> bytes:
+    width, height = image.size
+    if width < 1 or height < 1:
+        raise PreviewRenderError("Preview image dimensions must be positive.")
+    if width * height > max_pixels:
+        scale = (max_pixels / float(width * height)) ** 0.5
+        resampling = getattr(getattr(image, "Resampling", None), "LANCZOS", 1)
+        image = image.resize(
+            (max(1, int(width * scale)), max(1, int(height * scale))),
+            resampling,
+        )
+    resampling = getattr(getattr(image, "Resampling", None), "LANCZOS", 1)
+    for _ in range(6):
+        buffer = BytesIO()
+        image.save(buffer, format="PNG", optimize=True)
+        payload = buffer.getvalue()
+        if len(payload) <= max_bytes:
+            return payload
+        width, height = image.size
+        if width == 1 and height == 1:
+            break
+        image = image.resize((max(1, int(width * 0.7)), max(1, int(height * 0.7))), resampling)
+    raise PreviewRenderError("The sanitized PNG preview exceeds the configured byte limit.")

src/pipeline/multimodal_evidence/safety.py

@@ -0,0 +1,42 @@
+"""Shared lexical guard for local observations that must remain non-causal."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_PROHIBITED_ASSERTIONS = (
+    re.compile(
+        r"\b(?:proves?|proven|establishes?|confirms?|demonstrates?|"
+        r"universally?|first[- ]ever)\b",
+        flags=re.IGNORECASE,
+    ),
+    re.compile(
+        r"\b(?:causes?|causal(?:ly)?|drives?|leads?\s+to|induces?|"
+        r"results?\s+in|produces?|creates?|determines?|mediates?|triggers?|"
+        r"gives?\s+rise\s+to|is responsible for)\b",
+        flags=re.IGNORECASE,
+    ),
+    re.compile(r"\b(?:shows?|indicates?|suggests?)\s+that\b", flags=re.IGNORECASE),
+)
+
+
+def violates_noncausal_policy(value: Any) -> bool:
+    text = str(value or "")
+    for pattern in _PROHIBITED_ASSERTIONS:
+        for match in pattern.finditer(text):
+            if _is_explicitly_tentative(text, match.start()):
+                continue
+            return True
+    return False
+
+
+def _is_explicitly_tentative(text: str, start: int) -> bool:
+    prefix = text[max(0, start - 36) : start].casefold()
+    return bool(
+        re.search(
+            r"\b(?:may|might|could|can|possibly|potentially)\s+(?:\w+\s+){0,2}$",
+            prefix,
+        )
+    )

src/pipeline/multimodal_evidence/sampling.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Iterable
+
+from .contract import ValidatedMultimodalRecord
+
+
+@dataclass(frozen=True)
+class SamplingResult:
+    records: tuple[ValidatedMultimodalRecord, ...]
+    policy: str
+    truncated_strata_by_modality: dict[str, int]
+
+    @property
+    def selected_record_ids(self) -> list[str]:
+        return [record.record_id for record in self.records]
+
+
+def _stratum_key(record: ValidatedMultimodalRecord) -> tuple[str, str, str, str]:
+    metadata = record.metadata
+    return tuple(str(metadata.get(key, "")) for key in ("label", "group", "condition", "timepoint"))
+
+
+def select_stratified_records(
+    records: Iterable[ValidatedMultimodalRecord],
+    *,
+    max_records_per_modality: int,
+) -> SamplingResult:
+    if max_records_per_modality < 1:
+        raise ValueError("max_records_per_modality must be at least 1.")
+    by_modality: "OrderedDict[str, list[ValidatedMultimodalRecord]]" = OrderedDict()
+    for record in sorted(records, key=lambda item: item.input_index):
+        by_modality.setdefault(record.modality, []).append(record)
+
+    selected: list[ValidatedMultimodalRecord] = []
+    truncated_strata_by_modality: dict[str, int] = {}
+    for modality, modality_records in by_modality.items():
+        strata: "OrderedDict[tuple[str, str, str, str], list[ValidatedMultimodalRecord]]" = OrderedDict()
+        for record in modality_records:
+            strata.setdefault(_stratum_key(record), []).append(record)
+        stratum_records = list(strata.values())
+        if len(stratum_records) > max_records_per_modality:
+            truncated_strata_by_modality[modality] = len(stratum_records) - max_records_per_modality
+        modality_selected: list[ValidatedMultimodalRecord] = [
+            group[0] for group in stratum_records[:max_records_per_modality]
+        ]
+        next_indices = [1 for _ in modality_selected]
+        while len(modality_selected) < max_records_per_modality:
+            added = False
+            for group_index, group in enumerate(stratum_records[:max_records_per_modality]):
+                next_index = next_indices[group_index]
+                if next_index >= len(group):
+                    continue
+                modality_selected.append(group[next_index])
+                next_indices[group_index] += 1
+                added = True
+                if len(modality_selected) >= max_records_per_modality:
+                    break
+            if not added:
+                break
+        selected.extend(modality_selected)
+
+    return SamplingResult(
+        records=tuple(sorted(selected, key=lambda item: item.input_index)),
+        policy="stratified_by_label_group_condition_timepoint_round_robin_v1",
+        truncated_strata_by_modality=truncated_strata_by_modality,
+    )