sooth 0.2.1__py3-none-any.whl

sooth/__init__.py

@@ -0,0 +1,21 @@
+"""Sooth — verify AI-generated text against source material."""
+
+from sooth.claims import Claim, split_claims
+from sooth.report import exit_code, log_record, render_markdown
+from sooth.verify import MODEL, Verdict, VerifyError, map_verdict, verify_claims
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MODEL",
+    "Claim",
+    "Verdict",
+    "VerifyError",
+    "__version__",
+    "exit_code",
+    "log_record",
+    "map_verdict",
+    "render_markdown",
+    "split_claims",
+    "verify_claims",
+]

sooth/claims.py

@@ -0,0 +1,59 @@
+"""Split draft text into claims. Pure functions, no I/O."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# ponytail: regex splitter — mis-splits abbreviations/quotes; upgrade to clause-level when real drafts demand
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+")
+_HEADING = re.compile(r"^\s{0,3}#{1,6}\s")
+_BULLET = re.compile(r"^\s*(?:[-*•]|\d+[.)])\s+")
+_BOLD_ONLY = re.compile(r"^\*\*[^*]+\*\*:?\s*$")  # **Label** or **Label:** — heading, not a claim
+_MIN_WORDS = 4
+
+
+@dataclass(frozen=True)
+class Claim:
+    id: str
+    text: str
+    line: int
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A source sentence — an evidence candidate."""
+    id: str
+    text: str
+    line: int
+    source: str
+
+
+def _iter_sentences(text: str) -> list[tuple[int, str]]:
+    """(line_no, sentence) pairs — shared by claim and segment splitting."""
+    out: list[tuple[int, str]] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        if _HEADING.match(raw):
+            continue
+        line = _BULLET.sub("", raw).strip()
+        if not line or _BOLD_ONLY.match(line):
+            continue
+        line = line.replace("**", "")
+        for sentence in _SENTENCE_SPLIT.split(line):
+            s = sentence.strip()
+            if not s or s.endswith("?") or len(s.split()) < _MIN_WORDS:
+                continue
+            out.append((lineno, s))
+    return out
+
+
+def split_claims(text: str) -> list[Claim]:
+    """Return checkable-looking sentences as claims. Skips headings, questions, fragments."""
+    return [Claim(id=f"c{i + 1}", text=s, line=ln)
+            for i, (ln, s) in enumerate(_iter_sentences(text))]
+
+
+def split_segments(text: str, source: str, start_index: int = 1) -> list[Segment]:
+    """Source sentences as evidence candidates. Ids continue from start_index (s{n})."""
+    return [Segment(id=f"s{start_index + i}", text=s, line=ln, source=source)
+            for i, (ln, s) in enumerate(_iter_sentences(text))]

sooth/cli.py

@@ -0,0 +1,78 @@
+"""CLI: sooth. File I/O, exit codes, --log writer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from sooth.claims import split_claims
+from sooth.report import exit_code, log_record, render_markdown, render_plain
+from sooth.verify import DEFAULT_THRESHOLD, VerifyError, verify_claims
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="sooth",
+        description="Verify AI-generated text against source material. "
+                    "Each claim gets PASS / FAIL / REVIEW with calibrated probabilities.",
+    )
+    p.add_argument("--source", action="append", required=True, metavar="FILE",
+                   help="ground-truth source file (repeatable)")
+    p.add_argument("--text", required=True, metavar="FILE", help="AI-generated draft to check")
+    p.add_argument("--confidence", type=float, default=DEFAULT_THRESHOLD, metavar="T",
+                   help=f"REVIEW below this confidence (default {DEFAULT_THRESHOLD})")
+    p.add_argument("--format", choices=["md", "plain"], default="md", help="report format")
+    p.add_argument("-o", "--output", metavar="FILE", help="write report to file instead of stdout")
+    p.add_argument("--log", metavar="FILE", help="append full judgment trace as one JSONL line")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        sources = [(path, Path(path).read_text(encoding="utf-8")) for path in args.source]
+        draft = Path(args.text).read_text(encoding="utf-8")
+    except OSError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 3
+    if not draft.strip():
+        print("error: empty draft", file=sys.stderr)
+        return 3
+    if any(not text.strip() for _, text in sources):
+        print("error: empty source file", file=sys.stderr)
+        return 3
+
+    claims = split_claims(draft)
+    if not claims:
+        print("error: no claims found in draft", file=sys.stderr)
+        return 3
+
+    try:
+        result = verify_claims(claims, sources, threshold=args.confidence)
+    except VerifyError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 3
+
+    report = (render_markdown if args.format == "md" else render_plain)(
+        result.verdicts, threshold=args.confidence
+    )
+    if args.output:
+        Path(args.output).write_text(report, encoding="utf-8")
+    else:
+        print(report, end="")
+
+    if args.log:
+        record = log_record(result, threshold=args.confidence,
+                            sources=[path for path, _ in sources], draft=args.text)
+        record["ts"] = datetime.now(UTC).isoformat(timespec="seconds")
+        with Path(args.log).open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record) + "\n")
+
+    return exit_code(result.verdicts)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sooth/report.py

@@ -0,0 +1,125 @@
+"""Render verdicts to text and build the JSONL log record. Pure functions."""
+
+from __future__ import annotations
+
+from sooth.verify import FAIL, PASS, REVIEW, UNCHECKABLE, Verdict, VerifyResult
+
+_BAR_WIDTH = 8
+_MARK = {PASS: "✅ PASS", FAIL: "❌ FAIL", REVIEW: "⚠️ REVIEW", UNCHECKABLE: "➖ UNCHECKABLE"}
+_PLAIN = {PASS: "PASS", FAIL: "FAIL", REVIEW: "REVIEW", UNCHECKABLE: "UNCHECKABLE"}
+
+
+def bar(p: float, width: int = _BAR_WIDTH) -> str:
+    filled = round(p * width)
+    return "█" * filled + "░" * (width - filled)
+
+
+def _why(v: Verdict) -> str:
+    if v.kind == UNCHECKABLE:
+        return f"P(checkable)={v.p_checkable:.2f}"
+    parts = []
+    if v.probabilities:
+        parts.append(" / ".join(f"{k} {p:.2f}" for k, p in v.probabilities.items()))
+    if v.details_p is not None and v.details_p < 1.0:
+        parts.append(f"details {v.details_p:.2f}")
+    if v.missing_numbers:
+        parts.append("missing #s: " + ", ".join(v.missing_numbers))
+    return " · ".join(parts)
+
+
+def _p(v: Verdict) -> float:
+    return v.p_checkable if v.kind == UNCHECKABLE else (v.confidence or 0.0)
+
+
+def counts(verdicts: list[Verdict]) -> dict[str, int]:
+    tallies = {PASS: 0, FAIL: 0, REVIEW: 0, UNCHECKABLE: 0}
+    for v in verdicts:
+        tallies[v.kind] += 1
+    return tallies
+
+
+def _evidence(v: Verdict) -> str:
+    if not v.evidence_text:
+        return ""
+    snippet = v.evidence_text if len(v.evidence_text) <= 60 else v.evidence_text[:57] + "…"
+    return f'`{v.evidence_source}:{v.evidence_line}` "{snippet}"'
+
+
+def render_markdown(verdicts: list[Verdict], threshold: float) -> str:
+    t = counts(verdicts)
+    lines = [
+        "# Sooth\n",
+        (
+            f"**PASS {t[PASS]} · FAIL {t[FAIL]} · REVIEW {t[REVIEW]} · UNCHECKABLE {t[UNCHECKABLE]}**"
+            f" — threshold {threshold:.2f}\n"
+        ),
+        "| # | Claim | Verdict | P | Why (P distribution) | Evidence |",
+        "|---|-------|---------|---|----------------------|----------|",
+    ]
+    for i, v in enumerate(verdicts, start=1):
+        claim = v.claim_text.replace("|", "\\|")
+        lines.append(f"| {i} | {claim} | {_MARK[v.kind]} | {bar(_p(v))} {_p(v):.2f} | {_why(v)} | {_evidence(v)} |")
+    needs = [v for v in verdicts if v.kind in (REVIEW, UNCHECKABLE)]
+    if needs:
+        lines += ["\n## Needs review\n"]
+        lines += [f"- line {v.line}: {v.claim_text}" for v in needs]
+    return "\n".join(lines) + "\n"
+
+
+def render_plain(verdicts: list[Verdict], threshold: float) -> str:
+    t = counts(verdicts)
+    lines = [
+        (
+            f"PASS {t[PASS]}  FAIL {t[FAIL]}  REVIEW {t[REVIEW]}  UNCHECKABLE {t[UNCHECKABLE]}"
+            f"  (threshold {threshold:.2f})"
+        )
+    ]
+    for v in verdicts:
+        lines.append(f"{_PLAIN[v.kind]:<11} {_p(v):.2f}  line {v.line}  {v.claim_text}")
+    return "\n".join(lines) + "\n"
+
+
+def exit_code(verdicts: list[Verdict]) -> int:
+    """0 clean, 1 any FAIL, 2 any REVIEW (no FAIL). UNCHECKABLE never fails CI."""
+    kinds = {v.kind for v in verdicts}
+    if FAIL in kinds:
+        return 1
+    if REVIEW in kinds:
+        return 2
+    return 0
+
+
+def log_record(result: VerifyResult, threshold: float, sources: list[str], draft: str) -> dict:
+    """One JSONL line per run. Full probability distributions — the decision-ledger seed."""
+    return {
+        "model": result.model,
+        "threshold": threshold,
+        "sources": sources,
+        "draft": draft,
+        "usage": dict(result.usage),
+        "results": [
+            {
+                "id": v.claim_id,
+                "text": v.claim_text,
+                "line": v.line,
+                "kind": v.kind,
+                "p_checkable": v.p_checkable,
+                "choice": v.choice,
+                "probabilities": dict(v.probabilities),
+                "confidence": v.confidence,
+                "details_p": v.details_p,
+                "missing_numbers": list(v.missing_numbers),
+                "evidence": (
+                    {
+                        "id": v.evidence_id,
+                        "text": v.evidence_text,
+                        "line": v.evidence_line,
+                        "source": v.evidence_source,
+                    }
+                    if v.evidence_text
+                    else None
+                ),
+            }
+            for v in result.verdicts
+        ],
+    }

sooth/verify.py

@@ -0,0 +1,266 @@
+"""Build Jev questions, call the API, map answers to verdicts. Mapping is pure."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+
+from sooth.claims import Claim, Segment, split_segments
+
+# pin: thresholds in docs are tuned against this build; bump = re-run calibration
+MODEL = "jev-1.13.0"
+BATCH = 30  # claims per request; 2 questions each, stays far under the 64k token cap
+CHECKABLE_FLOOR = 0.5
+DEFAULT_THRESHOLD = 0.7
+
+PASS = "PASS"
+FAIL = "FAIL"
+REVIEW = "REVIEW"
+UNCHECKABLE = "UNCHECKABLE"
+
+DETAIL_FLOOR = 0.5  # PASS needs both supports-confidence and this detail-match probability
+EVIDENCE_CANDIDATES = 6  # code-prefiltered spans offered per claim (pre-parsed cookbook)
+
+_NUM = re.compile(r"\d+(?:[.,]\d+)*")
+
+
+def extract_numbers(text: str) -> set[str]:
+    """Number tokens in raw and separator-stripped form ('27,5' → '27,5' + '275')."""
+    out: set[str] = set()
+    for m in _NUM.finditer(text):
+        out.add(m.group())
+        out.add(m.group().replace(".", "").replace(",", ""))
+    return out
+
+
+def missing_numbers(claim_text: str, source_texts: list[str]) -> list[str]:
+    """Claim numbers absent from every source — deterministic smuggle detector."""
+    source_nums = extract_numbers(" ".join(source_texts))
+    missing = []
+    for m in _NUM.finditer(claim_text):
+        raw = m.group()
+        if raw not in source_nums and raw.replace(".", "").replace(",", "") not in source_nums:
+            missing.append(raw)
+    return missing
+
+
+def evidence_candidates(claim_text: str, segments: list[Segment],
+                        top: int = EVIDENCE_CANDIDATES) -> list[Segment]:
+    """Rank source segments by word overlap, numbers weighted. Pure pre-filter."""
+    nums = extract_numbers(claim_text)
+    words = {w.lower() for w in re.findall(r"[A-Za-zÀ-ÿ]{4,}", claim_text)}
+    scored = []
+    for seg in segments:
+        seg_nums = extract_numbers(seg.text)
+        seg_words = {w.lower() for w in re.findall(r"[A-Za-zÀ-ÿ]{4,}", seg.text)}
+        score = len(words & seg_words) + 3 * len(nums & seg_nums)
+        scored.append((score, seg))
+    scored.sort(key=lambda t: -t[0])
+    return [seg for score, seg in scored[:top] if score > 0] or segments[:top]
+
+
+class VerifyError(Exception):
+    """Config or API failure — CLI prints one line and exits 3."""
+
+
+@dataclass(frozen=True)
+class Verdict:
+    claim_id: str
+    claim_text: str
+    line: int
+    kind: str
+    p_checkable: float | None = None
+    choice: str | None = None
+    probabilities: dict[str, float] = field(default_factory=dict)
+    confidence: float | None = None
+    details_p: float | None = None
+    missing_numbers: tuple[str, ...] = ()
+    evidence_id: str | None = None
+    evidence_text: str | None = None
+    evidence_line: int | None = None
+    evidence_source: str | None = None
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    verdicts: list[Verdict]
+    model: str
+    usage: dict[str, int | None]
+
+
+def map_verdict(claim: Claim, p_checkable: float, choice: str, probabilities: dict[str, float],
+                confidence: float, threshold: float) -> Verdict:
+    """Verdict rules (PRD): checkable floor, then confidence gate, then choice."""
+    if p_checkable < CHECKABLE_FLOOR:
+        kind = UNCHECKABLE
+    elif confidence < threshold:
+        kind = REVIEW
+    elif choice == "supports":
+        kind = PASS
+    elif choice == "contradicts":
+        kind = FAIL
+    else:
+        kind = REVIEW  # not_found
+    return Verdict(
+        claim_id=claim.id,
+        claim_text=claim.text,
+        line=claim.line,
+        kind=kind,
+        p_checkable=p_checkable,
+        choice=choice,
+        probabilities=dict(probabilities),
+        confidence=confidence,
+    )
+
+
+def apply_safeguards(verdict: Verdict, details_p: float | None,
+                     missing: list[str]) -> Verdict:
+    """Demote PASS when detail-gate is low or claim numbers are absent from sources."""
+    kind = verdict.kind
+    if kind == PASS and ((details_p is not None and details_p < DETAIL_FLOOR) or missing):
+        kind = REVIEW
+    return Verdict(
+        claim_id=verdict.claim_id,
+        claim_text=verdict.claim_text,
+        line=verdict.line,
+        kind=kind,
+        p_checkable=verdict.p_checkable,
+        choice=verdict.choice,
+        probabilities=verdict.probabilities,
+        confidence=verdict.confidence,
+        details_p=details_p,
+        missing_numbers=tuple(missing),
+    )
+
+
+def attach_evidence(verdict: Verdict, segments_by_id: dict[str, Segment],
+                    chosen: str | None) -> Verdict:
+    """Attach the span the model selected ('none' or unknown id → no evidence)."""
+    seg = segments_by_id.get(chosen or "")
+    return Verdict(
+        claim_id=verdict.claim_id,
+        claim_text=verdict.claim_text,
+        line=verdict.line,
+        kind=verdict.kind,
+        p_checkable=verdict.p_checkable,
+        choice=verdict.choice,
+        probabilities=verdict.probabilities,
+        confidence=verdict.confidence,
+        details_p=verdict.details_p,
+        missing_numbers=verdict.missing_numbers,
+        evidence_id=seg.id if seg else None,
+        evidence_text=seg.text if seg else None,
+        evidence_line=seg.line if seg else None,
+        evidence_source=seg.source if seg else None,
+    )
+
+
+def build_state(claims: list[Claim], sources: list[tuple[str, str]],
+                segments: list[Segment]) -> dict:
+    return {
+        "sources": [{"name": name, "text": text} for name, text in sources],
+        "claims": [{"id": c.id, "text": c.text} for c in claims],
+        "segments": [{"id": s.id, "text": s.text} for s in segments],
+    }
+
+
+def build_questions(claims: list[Claim], cands: dict[str, list[Segment]] | None = None) -> dict:
+    """Four questions per claim, fan-out in one call. Question dicts match the SDK's raw form."""
+    cands = cands or {}
+    questions: dict = {}
+    for c in claims:
+        questions[f"{c.id}_checkable"] = {
+            "type": "noul",
+            "instructions": (
+                f"Statement: {c.text}\n\n"
+                "Is the statement a concrete factual claim that the evidence in `sources` "
+                "could support or contradict? No for opinions, vague praise, questions, "
+                "or promises about the future."
+            ),
+        }
+        questions[f"{c.id}_verdict"] = {
+            "type": "choice",
+            "instructions": (
+                f"Statement: {c.text}\n\n"
+                "Does the evidence in `sources` support the statement?"
+            ),
+            "criteria": {
+                "supports": "The sources state or clearly imply the statement is true.",
+                "contradicts": "The sources state or clearly imply the statement is false.",
+                "not_found": (
+                    "The sources do not address the statement either way, or the topic is absent."
+                ),
+            },
+        }
+        questions[f"{c.id}_details"] = {
+            "type": "noul",
+            "instructions": (
+                f"Statement: {c.text}\n\n"
+                "Does EVERY specific detail in the statement — names, numbers, dates, "
+                "quantities, and comparisons such as 'more than' or 'about' — exactly "
+                "match the evidence in `sources`? No if any detail is absent, slightly "
+                "altered, or hedged differently than the sources."
+            ),
+        }
+        span_criteria = {s.id: s.text[:80] for s in cands.get(c.id, [])}
+        span_criteria["none"] = "No segment is relevant to the statement."
+        questions[f"{c.id}_evidence"] = {
+            "type": "choice",
+            "instructions": (
+                f"Statement: {c.text}\n\n"
+                "Which candidate segment best supports or contradicts the statement? "
+                "Full text of each id is in `segments`. Choose 'none' if no segment "
+                "is relevant."
+            ),
+            "criteria": span_criteria,
+        }
+    return questions
+
+
+def verify_claims(claims: list[Claim], sources: list[tuple[str, str]],
+                  threshold: float = DEFAULT_THRESHOLD) -> VerifyResult:
+    """Batch claims through Jev and return verdicts. The only network entry point."""
+    if not os.environ.get("TYPESAFE_API_KEY"):
+        raise VerifyError("TYPESAFE_API_KEY not set (get a key at console.typesafe.ai)")
+    try:
+        from typesafe_sdk import TypeSafeClient
+    except ImportError as e:  # pragma: no cover
+        raise VerifyError("typesafe-sdk not installed (pip install typesafe-sdk)") from e
+
+    verdicts: list[Verdict] = []
+    usage = {"input_tokens": 0, "output_tokens": 0}
+    model = MODEL
+    segments: list[Segment] = []
+    for name, text in sources:
+        segments.extend(split_segments(text, name, start_index=len(segments) + 1))
+    by_id = {s.id: s for s in segments}
+    cands = {c.id: evidence_candidates(c.text, segments) for c in claims}
+    try:
+        with TypeSafeClient(model=MODEL) as client:
+            for start in range(0, len(claims), BATCH):
+                chunk = claims[start:start + BATCH]
+                resp = client.system_one(
+                    state=build_state(chunk, sources, segments),
+                    questions=build_questions(chunk, cands),
+                )
+                model = resp.model
+                if resp.usage:
+                    usage["input_tokens"] = (usage["input_tokens"] or 0) + (resp.usage.input_tokens or 0)
+                    usage["output_tokens"] = (usage["output_tokens"] or 0) + (resp.usage.output_tokens or 0)
+                for c in chunk:
+                    noul = resp.nouls[f"{c.id}_checkable"].noul
+                    details_p = resp.nouls[f"{c.id}_details"].noul
+                    ans = resp.choices[f"{c.id}_verdict"]
+                    verdict = map_verdict(
+                        c, noul, ans.choice, ans.probabilities, ans.confidence, threshold
+                    )
+                    missing = missing_numbers(c.text, [t for _, t in sources])
+                    verdict = apply_safeguards(verdict, details_p, missing)
+                    chosen = resp.choices[f"{c.id}_evidence"].choice
+                    verdicts.append(attach_evidence(verdict, by_id, chosen))
+    except VerifyError:
+        raise
+    except Exception as e:  # SDK error hierarchy; keep CLI free of SDK imports
+        raise VerifyError(f"Jev call failed: {e}") from e
+    return VerifyResult(verdicts=verdicts, model=model, usage=usage)

sooth-0.2.1.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: sooth
+Version: 0.2.1
+Summary: Verify AI-generated text against source material. Claim-by-claim trust reports powered by Jev (TypeSafe System One).
+Project-URL: Homepage, https://github.com/naufalhilmiaji/sooth
+Project-URL: Documentation, https://github.com/naufalhilmiaji/sooth/tree/main/docs
+Author-email: Naufal Hilmiaji <nhilmiaji@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,jev,llm,trust,typesafe,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: typesafe-sdk
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sooth
+
+Verify AI-generated text against source material. Claim-by-claim **PASS / FAIL / REVIEW**, with calibrated probabilities you can act on in CI.
+
+Built on [Jev](https://docs.typesafe.ai) (TypeSafe System One) — typed judgments and probabilities instead of generated prose. Every verdict shows its probability distribution, and the combination rules are plain code you can read. No black box.
+
+```
+sooth --source policy.md --text draft-reply.md
+```
+
+Real output (planted errors in the draft vs a news source):
+
+```
+# Sooth
+
+**PASS 2 · FAIL 3 · REVIEW 1 · UNCHECKABLE 1** — threshold 0.70
+
+| # | Claim | Verdict | P | Why (P distribution) | Evidence |
+|---|-------|---------|---|----------------------|----------|
+| 3 | BNBR baru menuntaskan rights issue bernilai besar di harga Rp 33. | ❌ FAIL | ████████ 1.00 | contradicts 1.00 / not_found 0.00 / supports 0.00 · details 0.01 · missing #s: 33 | `examples/news-1.md:25` "Saham ini juga baru menyelesaikan rights issue dalam juml…" |
+| 5 | BUMI hanya perlu turun sekitar 10% untuk menyentuh level Rp 50. | ❌ FAIL | ████████ 1.00 | contradicts 1.00 / not_found 0.00 / supports 0.00 · details 0.01 · missing #s: 10 | `examples/news-1.md:23` "Adapun PT Bumi Resources Tbk (BUMI) di sekitar Rp192 haru…" |
+| 6 | BEI juga menetapkan batas atas harga saham Rp 5.000 per saham. | ⚠️ REVIEW | ████████ 1.00 | contradicts 0.00 / not_found 1.00 / supports 0.00 · details 0.02 · missing #s: 5.000 |  |
+| 7 | Para investor ritel sangat senang dengan aturan baru ini. | ➖ UNCHECKABLE | ██░░░░░░ 0.24 | P(checkable)=0.24 |  |
+```
+
+## Why
+
+AI writes fast, nobody checks. Claims ship wrong. Sooth checks each claim against the evidence you give it — and when it is unsure, it says `REVIEW` instead of guessing.
+
+## Install
+
+```bash
+pip install sooth          # or: pip install -e ".[dev]" from source
+export TYPESAFE_API_KEY=...       # get one at console.typesafe.ai
+```
+
+## Usage
+
+```bash
+sooth --source docs/policy.md --source tickets/t123.md --text draft-reply.md
+
+# CI-friendly exit codes
+sooth --source policy.md --text draft.md --format plain
+#   0 = clean  ·  1 = any FAIL  ·  2 = any REVIEW  ·  3 = usage/config error
+
+# Options
+#   --confidence T   REVIEW below this confidence (default 0.7)
+#   --format md|plain
+#   -o FILE          write report to file
+#   --log FILE       append full judgment trace (one JSONL line per run)
+```
+
+## How it works
+
+1. Draft is split into claims (one sentence each).
+2. Each claim gets three questions to Jev, all fanned out in parallel batches: *is this checkable?*, *does the source support it?* (`supports` / `contradicts` / `not_found`), and *do all details match exactly?*
+3. Verdicts are mapped in code: uncheckable → `UNCHECKABLE`; low confidence → `REVIEW`; then `PASS` / `FAIL`. Safeguards demote `PASS` to `REVIEW` when details drift or claim numbers are absent from the source (checked in plain code).
+4. The report shows the full probability distribution per claim — not just a label.
+
+The decision logic lives in [`src/sooth/verify.py`](src/sooth/verify.py) in a dozen readable lines. Change thresholds and rules there, not in prompts.
+
+## Known limits (alpha)
+
+- Safeguards catch most drift and smuggling: claim numbers absent from the source demote `PASS` to `REVIEW`, and a detail-match gate flags altered hedges ("about 74%" → "over 74%"). Not perfect — read the `Why` column before trusting a verdict.
+- Derived numbers (totals, values computed outside the source) look "missing" and land in `REVIEW`.
+- Source + questions must fit ~64k tokens — split long documents yourself.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python3 tests/test_core.py     # pure checks, no network
+pytest                         # same suite
+bash tests/smoke.sh            # live smoke (needs TYPESAFE_API_KEY)
+PYTHONPATH=src python3 tests/calibrate.py   # live calibration, 30 labeled claims
+```
+
+Docs: [PRD](docs/PRD.md) · [Design](docs/DESIGN.md) · [Testing](docs/TESTING.md)
+
+## Roadmap
+
+- v0.2 shipped: source-span evidence (the exact source line behind each verdict, shown in the report)
+- later: hosted web app — paste UI, history, team review queues
+
+## License
+
+MIT © Naufal Hilmiaji. Powered by [TypeSafe](https://typesafe.ai) / Jev.

sooth-0.2.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sooth/__init__.py,sha256=hEgypQMjarNxUCn3oVY09t_5na41QwCJMsCvb9jIaGY,492
+sooth/claims.py,sha256=Utqha_gOp0HvPB0iZO667ii2YLyHtqBpGcjpUfcJ6Fo,1987
+sooth/cli.py,sha256=7qgEdNVDKilkC7w7BBYJJCsBNY890psu4jw7OhijSSQ,2969
+sooth/report.py,sha256=xpZp1694dDSamqgdtcrOgfUq9fcMNOyQ2ZGR-lK9pUo,4362
+sooth/verify.py,sha256=FTZuhWAi34mIuDq4n5ozwLIO1xoSj3Ts5qoZmPzyvQo,10511
+sooth-0.2.1.dist-info/METADATA,sha256=Vv-DulbG13G31JGWVAOc0oYmcCX1mYcsM30bL3UC-jw,5273
+sooth-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sooth-0.2.1.dist-info/entry_points.txt,sha256=Fw9Hmw3hgbtOjKZSuZFbDeQR3JGIGqoFHxjm5XJgGgc,41
+sooth-0.2.1.dist-info/licenses/LICENSE,sha256=9-6ggiqSH88kkwEsXzI7bjpJ_eIO8wUNZ7o-1fejOhs,1072
+sooth-0.2.1.dist-info/RECORD,,

sooth-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

sooth-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sooth = sooth.cli:main

sooth-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naufal Hilmiaji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.