sciwrite-lint 0.2.0__py3-none-any.whl

sciwrite_lint/report.py

@@ -0,0 +1,163 @@
+"""Output formatters: terminal (rich) and JSON."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from sciwrite_lint.models import Finding
+
+# ---------------------------------------------------------------------------
+# Level styling
+# ---------------------------------------------------------------------------
+
+_LEVEL_STYLE = {
+    "error": ("bold red", "red"),
+    "warning": ("bold yellow", "yellow"),
+    "info": ("bold blue", "blue"),
+}
+
+_LEVEL_LABEL = {
+    "error": "ERROR",
+    "warning": "WARN",
+    "info": "INFO",
+}
+
+
+# ---------------------------------------------------------------------------
+# Terminal (rich) output
+# ---------------------------------------------------------------------------
+
+
+def format_terminal(
+    findings: list[Finding],
+    file: str,
+    color: bool = True,
+    out: TextIO = sys.stdout,
+) -> None:
+    """Print findings using rich for styled terminal output."""
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.table import Table
+    from rich.text import Text
+
+    console = Console(file=out, force_terminal=color, no_color=not color)
+
+    if not findings:
+        console.print(f"{file} — no issues found.")
+        return
+
+    errors = sum(1 for f in findings if f.level == "error")
+    warnings = sum(1 for f in findings if f.level == "warning")
+    infos = sum(1 for f in findings if f.level == "info")
+
+    # Build findings table
+    table = Table(
+        show_header=False,
+        box=None,
+        padding=(0, 1),
+        expand=True,
+    )
+    table.add_column("level", width=5, no_wrap=True)
+    table.add_column("rule", style="bold", no_wrap=True)
+    table.add_column("detail", ratio=1)
+
+    for f in findings:
+        label_style, border_style = _LEVEL_STYLE[f.level]
+        label = Text(_LEVEL_LABEL[f.level], style=label_style)
+
+        # Location suffix
+        loc = ""
+        if f.line:
+            loc = f" [dim]line {f.line}[/dim]"
+        elif f.file:
+            loc = f" [dim]{f.file}[/dim]"
+
+        rule_text = Text.from_markup(f"{f.rule_id}{loc}")
+
+        # Message + context
+        detail = Text(f.message)
+        if f.context:
+            detail.append("\n")
+            detail.append(f.context, style="dim")
+
+        table.add_row(label, rule_text, detail)
+
+    # Panel border color: red if errors, yellow if only warnings, blue if only info
+    if errors:
+        border = "red"
+    elif warnings:
+        border = "yellow"
+    else:
+        border = "blue"
+
+    # Summary subtitle
+    parts = []
+    if errors:
+        parts.append(f"[red]{errors} error{'s' if errors != 1 else ''}[/red]")
+    if warnings:
+        parts.append(
+            f"[yellow]{warnings} warning{'s' if warnings != 1 else ''}[/yellow]"
+        )
+    if infos:
+        parts.append(f"[blue]{infos} info[/blue]")
+    subtitle = " · ".join(parts)
+
+    panel = Panel(
+        table,
+        title=f"[bold]{file}[/bold] — {len(findings)} issues",
+        subtitle=subtitle,
+        border_style=border,
+        padding=(0, 1),
+    )
+    console.print(panel)
+
+
+# ---------------------------------------------------------------------------
+# JSON output
+# ---------------------------------------------------------------------------
+
+
+def format_json(findings: list[Finding], file: str) -> str:
+    """Return findings as JSON string."""
+    data = {
+        "file": file,
+        "total": len(findings),
+        "errors": sum(1 for f in findings if f.level == "error"),
+        "warnings": sum(1 for f in findings if f.level == "warning"),
+        "infos": sum(1 for f in findings if f.level == "info"),
+        "findings": [
+            {
+                "level": f.level,
+                "rule_id": f.rule_id,
+                "message": f.message,
+                "file": f.file,
+                "line": f.line,
+                "context": f.context,
+            }
+            for f in findings
+        ],
+    }
+    return json.dumps(data, indent=2)
+
+
+def format_findings(
+    findings: list[Finding],
+    label: str,
+    fmt: str | None = None,
+    color: bool = True,
+) -> None:
+    """Dispatch findings to the appropriate formatter.
+
+    Args:
+        findings: List of findings to output.
+        label: File/paper label for the output header.
+        fmt: Output format — "terminal" (default) or "json".
+        color: Whether to use colored terminal output.
+    """
+    fmt = fmt or "terminal"
+    if fmt == "json":
+        print(format_json(findings, label))
+    else:
+        format_terminal(findings, label, color=color)

sciwrite_lint/schemas.py

@@ -0,0 +1,260 @@
+"""Pydantic models for vLLM structured output schemas.
+
+Every string field has a generous ``max_length`` (chars) set at ~2x natural
+output length. This tells vLLM's constrained decoder how much space each
+field gets, so the JSON structure completes within ``max_tokens``. The limits
+are ceilings — the model writes naturally below them.
+
+Conservative token math: at worst-case 3 chars/token, the total constrained
+response for the largest schema (ClaimVerdict) is ~192 tokens, leaving 3904
+of 4096 max_tokens for thinking.
+
+To get the JSON schema dict for vLLM::
+
+    from sciwrite_lint.schemas import ClaimVerdict, vllm_schema
+    schema = vllm_schema(ClaimVerdict)
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Citation purpose categories — single source of truth
+# ---------------------------------------------------------------------------
+
+# Canonical ordered dict: purpose → (short description, verification question).
+# Every consumer (prompts, schemas, weights, verify questions) derives from this.
+CITATION_PURPOSES: OrderedDict[str, tuple[str, str]] = OrderedDict(
+    [
+        (
+            "evidence",
+            (
+                "The sentence states a specific, quantitative or empirical finding and cites this source as proof. Remove the citation and the claim loses its support",
+                "Does this source contain data, findings, or arguments that support the specific factual claim being made?",
+            ),
+        ),
+        (
+            "example",
+            (
+                "The cited work is a case or instance being discussed to illustrate a broader point. The sentence talks ABOUT the cited work as a story or case — it does not credit authorship. E.g. 'the graphene paper was a curiosity before it was a Nobel Prize'",
+                "Is this the work being cited as an illustrative example? The source does not need to support the broader claim — it only needs to be the example described.",
+            ),
+        ),
+        (
+            "attribution",
+            (
+                "The sentence names WHO created a term, concept, or idea — the focus is on crediting the person, not explaining what the concept means. E.g. 'X was introduced by [cite]'",
+                "Is this source where the term, concept, or idea being attributed was originally introduced?",
+            ),
+        ),
+        (
+            "tool",
+            (
+                "Names a software tool, library, system, or dataset used in this work",
+                "Does this source describe or document the tool, system, or dataset being referenced?",
+            ),
+        ),
+        (
+            "method",
+            (
+                "The sentence describes a methodology, algorithm, or approach adopted from this source. The focus is on HOW something is done, not on what a concept means",
+                "Does this source describe the methodology or approach being referenced?",
+            ),
+        ),
+        (
+            "definition",
+            (
+                "The sentence explains WHAT a concept means, citing this source as the authority for the definition. Look for 'as defined by', 'the notion of X as', or explicit criteria/thresholds from the source",
+                "Does this source contain the definition being cited?",
+            ),
+        ),
+        (
+            "contrast",
+            (
+                "Presents a finding or approach that this paper disagrees with, compares against, or improves upon",
+                "Does this source present findings, methods, or claims that the citing paper disagrees with, improves upon, or tests against?",
+            ),
+        ),
+        (
+            "context",
+            (
+                "The citation decorates a general statement — remove it and the sentence still makes the same point. Typical: 'X has been applied to A [cite], B [cite]' or 'there has been growing interest in [cite]'. No specific finding from this source is used",
+                "Is this source relevant to the topic being discussed?",
+            ),
+        ),
+    ]
+)
+
+# Tuple of valid purpose names (for Literal type construction and validation).
+CITATION_PURPOSE_NAMES: tuple[str, ...] = tuple(CITATION_PURPOSES.keys())
+
+# Pre-built dicts for common access patterns.
+PURPOSE_DESCRIPTIONS: dict[str, str] = {k: v[0] for k, v in CITATION_PURPOSES.items()}
+VERIFY_QUESTIONS: dict[str, str] = {k: v[1] for k, v in CITATION_PURPOSES.items()}
+
+# Type alias — Literal can't be built dynamically, so we spell it out once here.
+CitationPurposeLiteral = Literal[
+    "evidence",
+    "example",
+    "attribution",
+    "tool",
+    "method",
+    "definition",
+    "contrast",
+    "context",
+]
+
+
+def vllm_schema(model: type[BaseModel]) -> dict[str, Any]:
+    """Generate a JSON schema dict for vLLM's constrained decoder.
+
+    Inlines ``$ref`` references (vLLM doesn't resolve ``$defs``) and strips
+    Pydantic metadata (``title``, ``description``) to keep the schema compact.
+    """
+    raw = model.model_json_schema()
+    defs = raw.pop("$defs", {})
+
+    def _resolve(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            if "$ref" in obj:
+                ref_name = obj["$ref"].rsplit("/", 1)[-1]
+                return _resolve(defs[ref_name])
+            return {k: _resolve(v) for k, v in obj.items() if k != "title"}
+        if isinstance(obj, list):
+            return [_resolve(v) for v in obj]
+        return obj
+
+    return _resolve(raw)
+
+
+# ---------------------------------------------------------------------------
+# Claim verification (eval_claims.py)
+# ---------------------------------------------------------------------------
+
+
+class CitationClassify(BaseModel):
+    """Citation purpose classification (sentence-level)."""
+
+    purpose: CitationPurposeLiteral
+    reasoning: str = Field(max_length=400)
+
+
+class ClaimVerdict(BaseModel):
+    """Claim-vs-source verification result."""
+
+    verdict: Literal[
+        "SUPPORTS",
+        "PARTIALLY_SUPPORTS",
+        "NOT_SUPPORTED",
+        "CANNOT_DETERMINE",
+    ]
+    confidence: float = Field(ge=0.0, le=1.0)
+    relevant_quote: str = Field(max_length=500)
+    explanation: str = Field(max_length=500)
+
+
+class NarrowContext(BaseModel):
+    """Extracted sentence(s) for a citation from a paragraph."""
+
+    sentences: str = Field(max_length=400)
+
+
+# ---------------------------------------------------------------------------
+# Cross-section consistency (checks/cross_section_consistency.py)
+# ---------------------------------------------------------------------------
+
+
+class Contradiction(BaseModel):
+    """A single contradiction between two sections."""
+
+    type: str = Field(max_length=100)
+    section_a_says: str = Field(max_length=400)
+    section_b_says: str = Field(max_length=400)
+    explanation: str = Field(max_length=400)
+    is_genuine: bool = Field(
+        description="true ONLY if the two passages actively disagree"
+    )
+
+
+class ConsistencyResult(BaseModel):
+    """Cross-section consistency check result."""
+
+    contradictions: list[Contradiction]
+
+
+# ---------------------------------------------------------------------------
+# Structure promises (checks/structure_promises.py)
+# ---------------------------------------------------------------------------
+
+
+class ContribCount(BaseModel):
+    """Contribution count mismatch check result."""
+
+    claimed_count: int
+    listed_count: int
+    mismatch: bool
+    explanation: str = Field(max_length=400)
+
+
+# ---------------------------------------------------------------------------
+# Claim taxonomy (claims.py)
+# ---------------------------------------------------------------------------
+
+
+class ClaimClassification(BaseModel):
+    """5-dimension claim taxonomy classification."""
+
+    type: Literal["prediction", "explanation", "reproduction", "synthesis"]
+    specificity: Literal["quantified", "directional", "vague"]
+    testability: Literal["falsifiable", "unfalsifiable", "tautological"]
+    support: Literal["severe_test", "weak_test", "no_test", "post_hoc"]
+    scope: Literal["cross_domain", "within_domain", "within_paper"]
+
+
+# ---------------------------------------------------------------------------
+# Laudan problem-solving (scoring/contribution.py)
+# ---------------------------------------------------------------------------
+
+
+class LaudanProblemSolving(BaseModel):
+    """Laudan problem-solving effectiveness score."""
+
+    num_problems_solved: int = Field(ge=0)
+    num_acknowledged: int = Field(ge=0)
+    num_unacknowledged: int = Field(ge=0)
+    score: float = Field(ge=0.0, le=1.0)
+
+
+# ---------------------------------------------------------------------------
+# Venue matching (references/matching.py)
+# ---------------------------------------------------------------------------
+
+
+class VenueMatch(BaseModel):
+    """Venue name confirmation result."""
+
+    same_venue: bool
+
+
+# ---------------------------------------------------------------------------
+# Full-paper consistency (checks/full_paper_consistency.py)
+# ---------------------------------------------------------------------------
+
+
+class FullPaperIssue(BaseModel):
+    """A single issue found by a full-paper consistency check."""
+
+    description: str = Field(max_length=300)
+    evidence: str = Field(max_length=300)
+    location: str = Field(max_length=100)
+    is_genuine: bool = Field(description="true ONLY for clear, unambiguous issues")
+
+
+class FullPaperIssueList(BaseModel):
+    """Result from a full-paper consistency check."""
+
+    issues: list[FullPaperIssue]

sciwrite_lint/scoring/__init__.py

@@ -0,0 +1 @@
+"""Scoring: SciLint Score computation, chain verification, contribution axes, and calibration."""