qwen-sci 0.2.2__py3-none-any.whl

src/agents/research_plan_author/bibtex_renderer.py

@@ -0,0 +1,252 @@
+"""Provenance-bounded, deterministic BibTeX rendering for Author documents."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from .latex_safety import LatexSafetyError, escape_latex_text, validate_citation_key
+
+
+BIBTEX_RENDER_SCHEMA_VERSION = "research_plan_author_bibtex_render_v1"
+
+
+class BibtexRenderError(RuntimeError):
+    """Raised when a cited source lacks sufficient provenance-backed metadata."""
+
+
+@dataclass(frozen=True)
+class BibtexRenderResult:
+    content: str
+    emitted_keys: tuple[str, ...]
+    emitted_entries: tuple[dict[str, Any], ...]
+    needs_completion: tuple[dict[str, Any], ...]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": BIBTEX_RENDER_SCHEMA_VERSION,
+            "emitted_keys": list(self.emitted_keys),
+            "emitted_entries": [deepcopy(entry) for entry in self.emitted_entries],
+            "needs_completion": [deepcopy(entry) for entry in self.needs_completion],
+        }
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return re.sub(r"\s+", " ", str(value or "")).strip()
+
+
+def _authors(value: object) -> list[str]:
+    raw_authors = value if isinstance(value, list) else []
+    authors: list[str] = []
+    for raw_author in raw_authors:
+        if isinstance(raw_author, Mapping):
+            name = _text(raw_author.get("display_name") or raw_author.get("name") or raw_author.get("author"))
+        else:
+            name = _text(raw_author)
+        if name and name not in authors:
+            authors.append(name)
+    return authors
+
+
+def _paper_metadata(document: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
+    """Resolve source records already frozen into the document or its source registry."""
+
+    registry: dict[str, dict[str, Any]] = {}
+    for raw in document.get("citation_registry") or []:
+        record = _mapping(raw)
+        source_id = _text(record.get("source_id"))
+        if source_id:
+            registry[source_id] = record
+    return registry
+
+
+def _field(record: Mapping[str, Any], name: str) -> object:
+    if name in record:
+        return record.get(name)
+    metadata = _mapping(record.get("bibliographic_metadata"))
+    return metadata.get(name)
+
+
+def _completion_record(record: Mapping[str, Any], *, key: str, reason: str) -> dict[str, Any]:
+    return {
+        "citation_key": key,
+        "source_id": _text(record.get("source_id")),
+        "title": _text(_field(record, "title")),
+        "doi": _text(_field(record, "doi")),
+        "reason": reason,
+        "required_fields": ["authors", "title", "year", "venue"],
+        "status": "bibliography_needs_completion",
+    }
+
+
+def _bib_value(value: object, *, label: str) -> str:
+    text = _text(value)
+    if not text:
+        raise BibtexRenderError(f"missing required BibTeX {label}")
+    try:
+        return escape_latex_text(
+            text,
+            label=f"BibTeX {label}",
+        )
+    except LatexSafetyError as error:
+        raise BibtexRenderError(str(error)) from error
+
+
+def _render_entry(record: Mapping[str, Any], *, key: str) -> tuple[str | None, dict[str, Any] | None]:
+    authors = _authors(_field(record, "authors"))
+    title = _text(_field(record, "title"))
+    year = _text(_field(record, "year"))
+    venue = _text(_field(record, "venue"))
+    missing = [
+        label
+        for label, value in (("authors", authors), ("title", title), ("year", year), ("venue", venue))
+        if not value
+    ]
+    if missing:
+        return None, _completion_record(record, key=key, reason="missing_metadata:" + ",".join(missing))
+    try:
+        rendered_authors = [_bib_value(authors[0], label="author")]
+        if len(authors) > 1:
+            # BibTeX's standard `others` marker lets IEEEtran.bst typeset
+            # “First Author et al.” without keeping a long author list alive.
+            rendered_authors.append("others")
+        fields = [
+            ("author", " and ".join(rendered_authors)),
+            ("title", _bib_value(title, label="title")),
+            ("journal", _bib_value(venue, label="venue")),
+            ("year", _bib_value(year, label="year")),
+        ]
+        doi = _text(_field(record, "doi"))
+        url = _text(_field(record, "url"))
+        if doi:
+            fields.append(("doi", _bib_value(doi, label="doi")))
+        if url:
+            fields.append(("url", _bib_value(url, label="URL")))
+    except BibtexRenderError as error:
+        return None, _completion_record(record, key=key, reason=f"unsafe_metadata:{error}")
+    rendered = "@article{" + key + ",\n" + ",\n".join(
+        f"  {name} = {{{value}}}" for name, value in fields
+    ) + "\n}\n"
+    return rendered, None
+
+
+def render_bibtex(
+    document: Mapping[str, Any],
+    *,
+    include_uncited: bool = False,
+) -> BibtexRenderResult:
+    """Emit only cited, fully identified records unless preflighting metadata."""
+
+    registry = _paper_metadata(document)
+    required_keys = required_citation_keys(document)
+    emitted: list[tuple[str, str, dict[str, Any]]] = []
+    completion: list[dict[str, Any]] = []
+    seen_keys: set[str] = set()
+    for raw in document.get("citation_registry") or []:
+        record = _mapping(raw)
+        key_raw = _text(record.get("citation_key"))
+        if not key_raw:
+            continue
+        try:
+            key = validate_citation_key(key_raw)
+        except LatexSafetyError as error:
+            raise BibtexRenderError(str(error)) from error
+        if key in seen_keys:
+            raise BibtexRenderError(f"duplicate citation key in frozen document: {key}")
+        seen_keys.add(key)
+        if not include_uncited and key not in required_keys:
+            continue
+        source_id = _text(record.get("source_id"))
+        source_record = registry.get(source_id, record)
+        entry, needs_completion = _render_entry(source_record, key=key)
+        if entry is None:
+            if needs_completion is not None:
+                completion.append(needs_completion)
+            continue
+        emitted.append(
+            (
+                key,
+                entry,
+                {
+                    "citation_key": key,
+                    "source_id": source_id,
+                    "title": _text(_field(source_record, "title")),
+                    "doi": _text(_field(source_record, "doi")),
+                },
+            )
+        )
+    emitted.sort(key=lambda item: item[0])
+    completion.sort(key=lambda item: (item["citation_key"], item["source_id"]))
+    return BibtexRenderResult(
+        content="\n".join(entry.rstrip() for _key, entry, _metadata in emitted) + ("\n" if emitted else ""),
+        emitted_keys=tuple(key for key, _entry, _metadata in emitted),
+        emitted_entries=tuple(metadata for _key, _entry, metadata in emitted),
+        needs_completion=tuple(completion),
+    )
+
+
+def bibliography_preflight_errors(citations: object) -> list[str]:
+    """Report malformed citation identities before composition begins.
+
+    Metadata completeness is intentionally deferred until composition has fixed
+    which records are actually cited. An unused incomplete registry record must
+    not prevent Author from drafting the document.
+    """
+
+    records = [_mapping(raw) for raw in citations or [] if isinstance(raw, Mapping)]
+    errors: list[str] = []
+    seen_keys: set[str] = set()
+    for index, record in enumerate(records):
+        citation_key = _text(record.get("citation_key"))
+        source_id = _text(record.get("source_id"))
+        if not source_id:
+            errors.append(f"citation registry record {index} is missing source_id")
+        try:
+            normalized_key = validate_citation_key(citation_key)
+        except LatexSafetyError as error:
+            errors.append(str(error))
+            continue
+        if normalized_key in seen_keys:
+            errors.append(f"duplicate citation key in frozen document: {normalized_key}")
+        seen_keys.add(normalized_key)
+    return sorted(set(errors))
+
+
+def required_citation_keys(document: Mapping[str, Any]) -> set[str]:
+    """Return all claim-level citation keys without interpreting LLM prose."""
+
+    keys: set[str] = set()
+    for raw in document.get("claim_provenance") or []:
+        record = _mapping(raw)
+        for value in record.get("citation_keys") or []:
+            try:
+                keys.add(validate_citation_key(value))
+            except LatexSafetyError as error:
+                raise BibtexRenderError(str(error)) from error
+    return keys
+
+
+def ensure_citation_coverage(document: Mapping[str, Any], result: BibtexRenderResult) -> None:
+    missing = sorted(required_citation_keys(document) - set(result.emitted_keys))
+    if missing:
+        raise BibtexRenderError(
+            "document cites records that cannot be rendered without inventing metadata: " + ", ".join(missing)
+        )
+
+
+__all__ = [
+    "BIBTEX_RENDER_SCHEMA_VERSION",
+    "BibtexRenderError",
+    "BibtexRenderResult",
+    "bibliography_preflight_errors",
+    "ensure_citation_coverage",
+    "render_bibtex",
+    "required_citation_keys",
+]

src/agents/research_plan_author/contract_repair.py

@@ -0,0 +1,131 @@
+"""One constrained repair path for malformed Author LLM JSON contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from copy import deepcopy
+import json
+import re
+from typing import Any
+
+from .llm_json import call_required_json
+
+
+AUTHOR_CONTRACT_REPAIR_AUDIT_SCHEMA_VERSION = "research_plan_author_contract_repair_audit_v1"
+class AuthorContractRepairError(RuntimeError):
+    """Carries a private artifact audit when a single permitted repair fails."""
+
+    def __init__(self, message: str, *, audit: Mapping[str, Any]) -> None:
+        super().__init__(message)
+        self.audit = deepcopy(dict(audit))
+
+
+def _contains_forbidden_reference(value: object) -> bool:
+    text = json.dumps(value, ensure_ascii=False, sort_keys=True) if isinstance(value, (dict, list)) else str(value or "")
+    return bool(re.search(r"\b(?:doi|https?://|arxiv:|pmid)\b", text, flags=re.IGNORECASE))
+
+
+def validate_author_contract_repair(
+    initial: Mapping[str, Any],
+    repaired: Mapping[str, Any],
+) -> list[str]:
+    """Reject unsafe new bibliographic identifiers while allowing source-bounded prose repairs."""
+
+    errors: list[str] = []
+    if _contains_forbidden_reference(repaired) and not _contains_forbidden_reference(initial):
+        errors.append("contract repair introduced a bibliographic identifier or URL")
+    return errors
+
+
+def build_author_contract_repair_prompt(
+    *,
+    artifact_kind: str,
+    initial_candidate: Mapping[str, Any],
+    validation_errors: list[str],
+    allowed_structural_strings: set[str],
+    contract_schema: Mapping[str, Any] | None = None,
+) -> str:
+    """Tell the LLM exactly what contract repair may and may not do."""
+
+    payload = {
+        "artifact_kind": artifact_kind,
+        "target_contract_schema": deepcopy(dict(contract_schema)) if isinstance(contract_schema, Mapping) else {},
+        "initial_candidate": dict(initial_candidate),
+        "validation_errors": list(validation_errors),
+        "allowed_structural_strings": sorted(allowed_structural_strings),
+    }
+    instructions = """You are performing one constrained JSON contract repair for a research-plan authoring stage. Return exactly one repaired artifact object and nothing else.
+
+The `target_contract_schema` is the output contract. Your response must be the artifact described by that schema, not the INPUT_JSON envelope. Never return `artifact_kind`, `target_contract_schema`, `initial_candidate`, `validation_errors`, or `allowed_structural_strings` as top-level output fields unless the target schema explicitly requires them.
+
+You may correct required fields, enum values, IDs, references, route membership, duplicate identifiers, and source-bounded prose. You must not add literature, citations, DOI, URLs, author names, numerical values, methods, sample sizes, instruments, definitions, lemmas, results, observations, proof claims, counterexamples, or verification claims that are absent from the supplied context. Do not upgrade a proposed or unverified statement. If an error cannot be fixed under these constraints, preserve the relevant value and let validation fail.
+
+INPUT_JSON:
+"""
+    return instructions + json.dumps(payload, ensure_ascii=False, sort_keys=True)
+
+
+def repair_once(
+    *,
+    artifact_kind: str,
+    initial_candidate: Mapping[str, Any],
+    validation_errors: list[str],
+    llm_call: Callable[..., object] | None,
+    validate: Callable[[Mapping[str, Any]], list[str]],
+    allowed_structural_strings: set[str] | None = None,
+    contract_schema: Mapping[str, Any] | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Attempt precisely one repair; raw candidates stay in the returned audit only."""
+
+    allowed = set(allowed_structural_strings or set())
+    audit: dict[str, Any] = {
+        "schema_version": AUTHOR_CONTRACT_REPAIR_AUDIT_SCHEMA_VERSION,
+        "artifact_kind": artifact_kind,
+        "repair_attempted": True,
+        "initial_candidate": deepcopy(dict(initial_candidate)),
+        "initial_validation_errors": list(validation_errors),
+        "repair_status": "PENDING",
+        "repair_validation_errors": [],
+        "constraints": [
+            "Only JSON structure, enum values, IDs, references, and source-bounded prose may be repaired.",
+            "No facts, sources, citations, DOI, numerical values, methods, results, proof claims, or verification claims may be added.",
+        ],
+    }
+    try:
+        repaired = call_required_json(
+            llm_call,
+            build_author_contract_repair_prompt(
+                artifact_kind=artifact_kind,
+                initial_candidate=initial_candidate,
+                validation_errors=validation_errors,
+                allowed_structural_strings=allowed,
+                contract_schema=contract_schema,
+            ),
+            stage=f"{artifact_kind}_contract_repair",
+        )
+    except Exception as error:
+        audit["repair_status"] = "LLM_FAILURE"
+        audit["repair_error"] = f"{type(error).__name__}: {error}"
+        raise AuthorContractRepairError(f"{artifact_kind}: constrained contract repair failed", audit=audit) from error
+    repair_errors = validate_author_contract_repair(initial_candidate, repaired)
+    repair_errors.extend(validate(repaired))
+    if repair_errors:
+        audit["repair_status"] = "REJECTED"
+        audit["repair_validation_errors"] = sorted(set(repair_errors))
+        audit["repaired_candidate"] = deepcopy(repaired)
+        raise AuthorContractRepairError(
+            f"{artifact_kind}: constrained repair produced an invalid JSON contract: " + "; ".join(sorted(set(repair_errors))),
+            audit=audit,
+        )
+    audit["repair_status"] = "REPAIRED"
+    audit["repaired_candidate"] = deepcopy(repaired)
+    return repaired, audit
+
+
+__all__ = [
+    "AUTHOR_CONTRACT_REPAIR_AUDIT_SCHEMA_VERSION",
+    "AuthorContractRepairError",
+    "build_author_contract_repair_prompt",
+    "repair_once",
+    "validate_author_contract_repair",
+]