sourced-evidence 0.1.0__tar.gz

sourced_evidence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+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.

sourced_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sourced-evidence
+Version: 0.1.0
+Summary: Per-claim grounded/contradicted/unverified checking of LLM output against its own source context -- never a blended trust score.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/sourced
+Project-URL: Source, https://github.com/MaXiMo000/sourced
+Project-URL: Issues, https://github.com/MaXiMo000/sourced/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/sourced/releases
+Keywords: verification,grounding,llm,rag,evidence,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sourced
+
+[![ci](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml)
+
+**Checks an LLM's output against its own source context, claim by claim --
+`grounded`, `contradicted`, or `unverified`, never one blended trust score.**
+
+A RAG pipeline retrieves the right documents and still generates a sentence
+those documents don't support -- a wrong number, an entity the source never
+mentions, a stat close enough to sound plausible. Most RAG evaluation
+scores *retrieval quality*: did the right chunks come back. Almost nothing
+checks the *output* sentence by sentence against what was actually
+retrieved. `sourced` does that second, narrower thing.
+
+```
+$ sourced check output.txt source.txt
+[OK] Microsoft reported revenue of $56 billion.
+[XX] Microsoft grew 40% year over year.
+       claims 40% near 'Microsoft', but the source's own text near that
+       entity says ['56', '8%']
+[??] The outlook remains uncertain.
+       no checkable numbers, quoted text, or capitalized entities in this claim
+
+1 grounded, 1 contradicted, 1 unverified
+```
+
+(That transcript is real output, not illustrative -- `source.txt` says growth
+was 8%; note the second claim repeats "Microsoft" by name rather than
+saying "it," because pronoun coreference isn't resolved -- see "What this
+does NOT do.")
+
+## Install
+
+```
+pip install sourced-evidence   # the command it installs is `sourced`
+```
+
+(`sourced` was already taken on PyPI -- same story as `receipt-evidence`,
+`providence-evidence`, and `custody-evidence` in this portfolio.)
+
+## Use
+
+```
+sourced check <output-file> <source-file> [source-file ...] [--json]
+```
+
+`output-file` is the LLM's generated text. `source-file`(s) are the
+context it was supposed to be grounded in -- the retrieved chunks, the
+document it summarized, the transcript it's answering questions about.
+Multiple source files are concatenated before checking.
+
+Exit code is `1` only if any claim is `contradicted` -- same convention as
+[`receipt`](https://github.com/MaXiMo000/receipt) and
+[`invariant`](https://github.com/MaXiMo000/invariant): `unverified` is a
+legitimate "can't tell," not a failure.
+
+## How a claim gets checked
+
+1. **Split into claims.** Every sentence in the output is one claim
+   candidate -- no attempt to tell a factual assertion from an opinion or
+   a hedge (`sourced/claims.py`).
+2. **Extract signals.** Numbers, quoted substrings, and capitalized
+   entity-shaped phrases (`sourced/signals.py`) -- the concrete, matchable
+   facts a source text either does or doesn't contain.
+3. **Classify against the source** (`sourced/check.py`):
+   - **`grounded`** -- every number, quote, and entity in the claim appears
+     in the source.
+   - **`contradicted`** -- a claim's number doesn't appear in the source at
+     all, but an entity from the *same claim* does, near a *different*
+     number. Narrow on purpose: this only fires when there's a real shared
+     anchor pinning the comparison to the same subject, never "two
+     different numbers exist somewhere in a long document."
+   - **`unverified`** -- everything else: no checkable signals in the claim
+     at all, or some signal simply isn't found anywhere in the source.
+
+## What this does NOT do
+
+This is the part worth reading before trusting a result.
+
+- **No semantic understanding, no paraphrase matching.** "Revenue was $56
+  billion" and "the company made fifty-six billion dollars" are the same
+  fact and this will not see it that way -- it matches strings and
+  numbers, not meaning. A real semantic entailment checker needs a
+  language model; that's real future work (an optional LLM-backed
+  adjudication pass, the same shape `invariant`'s cascade or LabLedger's
+  Gemini stage already use elsewhere in this portfolio -- degrade
+  gracefully without it, don't require it), not built here.
+- **No real named-entity recognition.** `signals.proper_nouns()` is a
+  capitalization heuristic, not a trained model. "Bank of America" splits
+  into `Bank` and `America` because a lowercase joiner breaks the
+  capitalized-word chain. Documented in `signals.py`, not hidden.
+- **No real sentence tokenizer.** `claims.split_claims()` is a regex.
+  "Dr. Smith signed the report." reads as two sentences. Ordinary prose
+  splits correctly; abbreviation-heavy text won't always.
+- **No pronoun or coreference resolution.** "Microsoft reported $56B. It
+  grew 40%." -- the second sentence's "It" is correctly excluded as an
+  entity (it's a pronoun, not a name), so there's no anchor to check that
+  claim's number against, and it comes back `unverified` rather than
+  `contradicted`. Each claim is checked entirely on its own; a real fix
+  needs coreference resolution, real NLP work of its own, not attempted
+  here.
+- **Contradiction detection is deliberately conservative**, and that cuts
+  both ways: a real contradiction with no shared entity to anchor on comes
+  back `unverified`, not `contradicted` -- this will under-report
+  contradictions before it will over-report them. That's the intended
+  trade for a tool whose whole point is not manufacturing false
+  accusations against a source.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_claims.py     # sentence splitting
+python tests/test_signals.py    # number/quote/entity extraction
+python tests/test_check.py      # the grounded/contradicted/unverified decision
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Several exist specifically because a first pass got something
+wrong and testing against ordinary prose (not synthetic numbers-only
+input) caught it -- e.g. a number regex that swallowed a following
+sentence period (`"42."` parsed as the number `42.`), a sentence-
+initial entity ("Microsoft" opening a sentence) needing case-insensitive
+matching against a source that uses the same word lowercase mid-sentence,
+without that leniency being used for anything else, and (found live
+during a later audit) American-style closing punctuation putting the
+period *inside* a quote (`"four hours."` not `"four hours".`) silently
+merging two sentences into one claim -- the sentence-end regex only ever
+checked for `[.!?]` immediately before the split point, never a quote
+mark sitting in front of it.
+
+MIT licensed.

sourced_evidence-0.1.0/README.md

@@ -0,0 +1,132 @@
+# sourced
+
+[![ci](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml)
+
+**Checks an LLM's output against its own source context, claim by claim --
+`grounded`, `contradicted`, or `unverified`, never one blended trust score.**
+
+A RAG pipeline retrieves the right documents and still generates a sentence
+those documents don't support -- a wrong number, an entity the source never
+mentions, a stat close enough to sound plausible. Most RAG evaluation
+scores *retrieval quality*: did the right chunks come back. Almost nothing
+checks the *output* sentence by sentence against what was actually
+retrieved. `sourced` does that second, narrower thing.
+
+```
+$ sourced check output.txt source.txt
+[OK] Microsoft reported revenue of $56 billion.
+[XX] Microsoft grew 40% year over year.
+       claims 40% near 'Microsoft', but the source's own text near that
+       entity says ['56', '8%']
+[??] The outlook remains uncertain.
+       no checkable numbers, quoted text, or capitalized entities in this claim
+
+1 grounded, 1 contradicted, 1 unverified
+```
+
+(That transcript is real output, not illustrative -- `source.txt` says growth
+was 8%; note the second claim repeats "Microsoft" by name rather than
+saying "it," because pronoun coreference isn't resolved -- see "What this
+does NOT do.")
+
+## Install
+
+```
+pip install sourced-evidence   # the command it installs is `sourced`
+```
+
+(`sourced` was already taken on PyPI -- same story as `receipt-evidence`,
+`providence-evidence`, and `custody-evidence` in this portfolio.)
+
+## Use
+
+```
+sourced check <output-file> <source-file> [source-file ...] [--json]
+```
+
+`output-file` is the LLM's generated text. `source-file`(s) are the
+context it was supposed to be grounded in -- the retrieved chunks, the
+document it summarized, the transcript it's answering questions about.
+Multiple source files are concatenated before checking.
+
+Exit code is `1` only if any claim is `contradicted` -- same convention as
+[`receipt`](https://github.com/MaXiMo000/receipt) and
+[`invariant`](https://github.com/MaXiMo000/invariant): `unverified` is a
+legitimate "can't tell," not a failure.
+
+## How a claim gets checked
+
+1. **Split into claims.** Every sentence in the output is one claim
+   candidate -- no attempt to tell a factual assertion from an opinion or
+   a hedge (`sourced/claims.py`).
+2. **Extract signals.** Numbers, quoted substrings, and capitalized
+   entity-shaped phrases (`sourced/signals.py`) -- the concrete, matchable
+   facts a source text either does or doesn't contain.
+3. **Classify against the source** (`sourced/check.py`):
+   - **`grounded`** -- every number, quote, and entity in the claim appears
+     in the source.
+   - **`contradicted`** -- a claim's number doesn't appear in the source at
+     all, but an entity from the *same claim* does, near a *different*
+     number. Narrow on purpose: this only fires when there's a real shared
+     anchor pinning the comparison to the same subject, never "two
+     different numbers exist somewhere in a long document."
+   - **`unverified`** -- everything else: no checkable signals in the claim
+     at all, or some signal simply isn't found anywhere in the source.
+
+## What this does NOT do
+
+This is the part worth reading before trusting a result.
+
+- **No semantic understanding, no paraphrase matching.** "Revenue was $56
+  billion" and "the company made fifty-six billion dollars" are the same
+  fact and this will not see it that way -- it matches strings and
+  numbers, not meaning. A real semantic entailment checker needs a
+  language model; that's real future work (an optional LLM-backed
+  adjudication pass, the same shape `invariant`'s cascade or LabLedger's
+  Gemini stage already use elsewhere in this portfolio -- degrade
+  gracefully without it, don't require it), not built here.
+- **No real named-entity recognition.** `signals.proper_nouns()` is a
+  capitalization heuristic, not a trained model. "Bank of America" splits
+  into `Bank` and `America` because a lowercase joiner breaks the
+  capitalized-word chain. Documented in `signals.py`, not hidden.
+- **No real sentence tokenizer.** `claims.split_claims()` is a regex.
+  "Dr. Smith signed the report." reads as two sentences. Ordinary prose
+  splits correctly; abbreviation-heavy text won't always.
+- **No pronoun or coreference resolution.** "Microsoft reported $56B. It
+  grew 40%." -- the second sentence's "It" is correctly excluded as an
+  entity (it's a pronoun, not a name), so there's no anchor to check that
+  claim's number against, and it comes back `unverified` rather than
+  `contradicted`. Each claim is checked entirely on its own; a real fix
+  needs coreference resolution, real NLP work of its own, not attempted
+  here.
+- **Contradiction detection is deliberately conservative**, and that cuts
+  both ways: a real contradiction with no shared entity to anchor on comes
+  back `unverified`, not `contradicted` -- this will under-report
+  contradictions before it will over-report them. That's the intended
+  trade for a tool whose whole point is not manufacturing false
+  accusations against a source.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_claims.py     # sentence splitting
+python tests/test_signals.py    # number/quote/entity extraction
+python tests/test_check.py      # the grounded/contradicted/unverified decision
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Several exist specifically because a first pass got something
+wrong and testing against ordinary prose (not synthetic numbers-only
+input) caught it -- e.g. a number regex that swallowed a following
+sentence period (`"42."` parsed as the number `42.`), a sentence-
+initial entity ("Microsoft" opening a sentence) needing case-insensitive
+matching against a source that uses the same word lowercase mid-sentence,
+without that leniency being used for anything else, and (found live
+during a later audit) American-style closing punctuation putting the
+period *inside* a quote (`"four hours."` not `"four hours".`) silently
+merging two sentences into one claim -- the sentence-end regex only ever
+checked for `[.!?]` immediately before the split point, never a quote
+mark sitting in front of it.
+
+MIT licensed.

sourced_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+# "sourced" was already taken on PyPI, same story as receipt/providence/
+# custody before it (checked, not assumed). The installed command stays
+# the short name -- python-dateutil installs `dateutil`, this installs
+# `sourced`.
+name = "sourced-evidence"
+version = "0.1.0"
+description = "Per-claim grounded/contradicted/unverified checking of LLM output against its own source context -- never a blended trust score."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["verification", "grounding", "llm", "rag", "evidence", "provenance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+# Stdlib only -- see README's "What this doesn't do": this is a lexical
+# overlap checker, not a semantic one, on purpose, and needs no LLM API of
+# its own to run.
+dependencies = []
+
+urls.Homepage = "https://github.com/MaXiMo000/sourced"
+urls.Source = "https://github.com/MaXiMo000/sourced"
+urls.Issues = "https://github.com/MaXiMo000/sourced/issues"
+urls.Changelog = "https://github.com/MaXiMo000/sourced/releases"
+
+[project.scripts]
+sourced = "sourced.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sourced*"]

sourced_evidence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sourced_evidence-0.1.0/sourced/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sourced_evidence-0.1.0/sourced/check.py

@@ -0,0 +1,96 @@
+"""Check one claim against source text: grounded, contradicted, or
+unverified -- never a blended trust score. See README for exactly what
+each status means, and what this deliberately does not attempt (semantic
+entailment, paraphrase matching -- see "What this doesn't do").
+"""
+from __future__ import annotations
+
+from . import signals
+from .claims import split_claims
+
+GROUNDED, CONTRADICTED, UNVERIFIED = "grounded", "contradicted", "unverified"
+
+
+def _window(text: str, index: int, radius: int = 60) -> str:
+    return text[max(0, index - radius): index + radius]
+
+
+def check_claim(claim: str, source: str) -> dict:
+    nums = signals.numbers(claim)
+    ents = signals.proper_nouns(claim)
+    quoted = signals.quotes(claim)
+
+    if not nums and not ents and not quoted:
+        return {
+            "claim": claim, "status": UNVERIFIED,
+            "detail": "no checkable numbers, quoted text, or capitalized entities in this claim",
+            "signals": {"numbers": [], "entities": [], "quotes": []},
+        }
+
+    # Contradiction: a number in the claim doesn't appear anywhere in the
+    # source, but an entity from the same claim does, near a *different*
+    # number. Narrow and conservative on purpose -- this only fires when
+    # there's a real anchor (a shared entity) pinning the comparison to the
+    # same subject, not "any two different numbers exist somewhere in a
+    # long document," which would be a false-contradiction machine.
+    contradictions = []
+    for ent in ents:
+        idx = source.find(ent)
+        if idx == -1:
+            continue
+        nearby_nums = signals.numbers(_window(source, idx))
+        for n in nums:
+            if n not in source and nearby_nums and n not in nearby_nums:
+                contradictions.append({
+                    "claim_number": n, "entity": ent,
+                    "source_numbers_nearby": nearby_nums,
+                })
+
+    if contradictions:
+        first = contradictions[0]
+        return {
+            "claim": claim, "status": CONTRADICTED,
+            "detail": (f"claims {first['claim_number']} near '{first['entity']}', but "
+                       f"the source's own text near that entity says "
+                       f"{first['source_numbers_nearby']}"),
+            "signals": {"numbers": nums, "entities": ents, "quotes": quoted},
+            "contradictions": contradictions,
+        }
+
+    missing_numbers = [n for n in nums if n not in source]
+    # Case-insensitive here, unlike the contradiction anchor above: a
+    # sentence-initial entity like "Revenue" is only capitalized because of
+    # its position, and the same word appears lowercase mid-sentence in
+    # most real source text ("Q3 revenue was..."). Exact-case matching
+    # would report a real match as "missing" for no reason other than
+    # capitalization -- a worse failure for a grounding check than being
+    # slightly lenient. Contradiction anchoring stays case-sensitive
+    # (source.find(ent) above) precisely because it needs to be stricter.
+    source_lower = source.lower()
+    missing_entities = [e for e in ents if e.lower() not in source_lower]
+    missing_quotes = [q for q in quoted if q not in source]
+    total = len(nums) + len(ents) + len(quoted)
+    missing = len(missing_numbers) + len(missing_entities) + len(missing_quotes)
+
+    if missing == 0:
+        return {
+            "claim": claim, "status": GROUNDED,
+            "detail": "every number, entity, and quoted phrase in this claim appears in the source",
+            "signals": {"numbers": nums, "entities": ents, "quotes": quoted},
+        }
+    return {
+        "claim": claim, "status": UNVERIFIED,
+        "detail": (f"{missing}/{total} signal(s) not found in the source -- "
+                   f"numbers {missing_numbers}, entities {missing_entities}, "
+                   f"quotes {missing_quotes}"),
+        "signals": {"numbers": nums, "entities": ents, "quotes": quoted},
+    }
+
+
+def check_output(output_text: str, source_text: str) -> dict:
+    """Every sentence in `output_text`, checked against `source_text`."""
+    results = [check_claim(c, source_text) for c in split_claims(output_text)]
+    counts = {GROUNDED: 0, CONTRADICTED: 0, UNVERIFIED: 0}
+    for r in results:
+        counts[r["status"]] += 1
+    return {"claims": results, "counts": counts}

sourced_evidence-0.1.0/sourced/claims.py

@@ -0,0 +1,44 @@
+"""Split LLM output into claim candidates.
+
+A "claim" here is just a sentence -- no attempt to distinguish a factual
+assertion from an opinion, a question, or a hedge ("it seems that...").
+That distinction is real NLP work of its own, and is explicitly out of
+scope for v1 (see README's "What this doesn't do"). Treating every
+sentence as a checkable claim means the tool never silently skips
+something it should have checked, at the cost of also "checking" sentences
+that were never factual assertions to begin with -- those simply come back
+`unverified`, which is the correct, honest answer for a sentence with
+nothing in it to check.
+"""
+from __future__ import annotations
+
+import re
+
+# Split on sentence-ending punctuation followed by whitespace and what looks
+# like the start of a new sentence (a capital letter, a digit, or a quote).
+# Deliberately a regex, not a real sentence tokenizer (spaCy/nltk): this
+# portfolio stays dependency-free where a regex handles ordinary prose well
+# enough. It will over-split or under-split on abbreviations ("Dr. Smith
+# arrived.") and decimal numbers at a sentence boundary -- a stated
+# limitation, not a silent one; see README.
+#
+# The lookbehind has two alternatives, not one optional closing-quote/paren
+# character, because Python's re requires a fixed-width lookbehind: a
+# quantifier inside (?<=...) is a SyntaxError. Both alternatives here are
+# individually fixed-width (1 char, then 2 chars) -- the quantifier just
+# isn't inside the lookbehind itself.
+#
+# The second alternative is the fix for a real bug: American-style closing
+# punctuation puts the period *inside* the quote ("four hours." not "four
+# hours".), so the character immediately before the split point is the
+# quote mark, not [.!?] -- the single-alternative version never matched
+# there at all, silently merging two sentences into one claim.
+_SENTENCE_END = re.compile(r'(?:(?<=[.!?])|(?<=[.!?][\'")\]]))\s+(?=[A-Z0-9"\'])')
+
+
+def split_claims(text: str) -> list[str]:
+    text = text.strip()
+    if not text:
+        return []
+    parts = _SENTENCE_END.split(text)
+    return [p.strip() for p in parts if p.strip()]

sourced_evidence-0.1.0/sourced/cli.py

@@ -0,0 +1,64 @@
+"""sourced check <output-file> <source-file> [source-file ...] [--json]"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+
+from .check import check_output
+
+_TAG = {"grounded": "OK", "contradicted": "XX", "unverified": "??"}
+
+
+def _read(path: str) -> str:
+    """A missing file, a directory given by mistake, or binary/undecodable
+    content is a wrong argument, not a crash -- every sibling tool in this
+    portfolio treats a bad file path as an actionable error message, not a
+    traceback (found by testing this against an actual typo'd path, the
+    same way providence's malformed-JSON crash was found)."""
+    try:
+        return pathlib.Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        sys.exit(f"sourced: no such file: {path}")
+    except IsADirectoryError:
+        sys.exit(f"sourced: {path} is a directory, not a file")
+    except UnicodeDecodeError as exc:
+        sys.exit(f"sourced: {path} is not valid UTF-8 text ({exc})")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sourced")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check_p = sub.add_parser(
+        "check", help="check each sentence of an LLM output against source text")
+    check_p.add_argument("output_file", help="the LLM's output, one claim per sentence")
+    check_p.add_argument("source_files", nargs="+", help="the context it should be grounded in")
+    check_p.add_argument("--json", action="store_true", help="print the full report as JSON")
+
+    args = parser.parse_args(argv)
+
+    output_text = _read(args.output_file)
+    source_text = "\n".join(_read(f) for f in args.source_files)
+    report = check_output(output_text, source_text)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        for r in report["claims"]:
+            print(f"[{_TAG[r['status']]}] {r['claim']}")
+            if r["status"] != "grounded":
+                print(f"       {r['detail']}")
+        c = report["counts"]
+        print(f"\n{c['grounded']} grounded, {c['contradicted']} contradicted, "
+              f"{c['unverified']} unverified")
+
+    # Same convention as receipt/invariant: unverified is a legitimate "we
+    # can't tell," not a failure -- only a contradiction (a claim actively
+    # at odds with its own source) is a nonzero exit.
+    return 1 if report["counts"]["contradicted"] > 0 else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sourced_evidence-0.1.0/sourced/signals.py

@@ -0,0 +1,67 @@
+"""Extract the checkable content out of one claim: numbers, quoted
+substrings, and proper-noun-shaped phrases. These are the concrete,
+matchable facts a source text either does or doesn't contain -- the part
+of "grounded vs unverified" that string matching can actually answer,
+without needing to understand what the sentence means.
+"""
+from __future__ import annotations
+
+import re
+
+# The fractional part requires a digit after the dot, not just an optional
+# dot -- `\.?\d*` alone would swallow a following sentence period into the
+# match ("42." at the end of a sentence reading as the number "42." instead
+# of "42"), a real bug caught by testing this against ordinary prose, not
+# synthetic numbers-only input.
+_NUMBER = re.compile(r'-?\d[\d,]*(?:\.\d+)?%?')
+_QUOTED = re.compile(r'"([^"]{3,})"|\'([^\']{3,})\'')
+# A run of 1+ capitalized words -- a cheap proper-noun/entity proxy, not real
+# named-entity recognition. Multi-word runs ("Bank of America" -- capitalized
+# words joined by lowercase function words still read as one run since the
+# regex only requires the *first* letter of each word to be uppercase and
+# skips over up to one lowercase joiner... actually it doesn't: this simple
+# version only chains directly-adjacent capitalized words. "Bank of America"
+# would be seen as two separate entities, "Bank" and "America" -- a real,
+# stated limitation of not doing real NER, not a bug to silently paper over.
+_PROPER_NOUN = re.compile(r'\b[A-Z][a-zA-Z0-9]*(?:\s+[A-Z][a-zA-Z0-9]*)*\b')
+
+# Common capitalized function words that are never an entity on their own
+# (they're excluded even mid-sentence, e.g. "and The company" -- "The" is
+# still not a proper noun there). This is the only filter single-word
+# candidates get; see proper_nouns()'s docstring for why sentence position
+# isn't used to filter them too.
+_STOPWORD_CAPS = {
+    "The", "A", "An", "This", "That", "These", "Those", "It", "In", "On",
+    "At", "For", "As", "Is", "Was", "Were", "There", "Here", "But", "And",
+}
+
+
+def numbers(text: str) -> list[str]:
+    return [m.group().replace(",", "") for m in _NUMBER.finditer(text)]
+
+
+def quotes(text: str) -> list[str]:
+    return [m.group(1) or m.group(2) for m in _QUOTED.finditer(text)]
+
+
+def proper_nouns(text: str) -> list[str]:
+    """Multi-word capitalized runs are kept unconditionally (rarely a false
+    positive). A single capitalized word is kept unless it's a common
+    capitalized function word (the stoplist) -- deliberately NOT excluded
+    just for being sentence-initial: "Microsoft reported revenue of $70
+    billion" is exactly the shape this tool most needs to anchor a
+    contradiction check on, and Microsoft-as-subject is sentence-initial in
+    ordinary prose far more often than not. The real cost is the flip side:
+    an ordinary sentence-initial common noun ("Revenue grew...") gets
+    treated as a pseudo-entity too. That's an accepted, stated trade --
+    it only ever contributes to a *coverage* check ("Revenue" trivially
+    tends to appear in a source that's also about revenue), and it does
+    not on its own manufacture a contradiction the way a false anchor with
+    a genuinely different number nearby would.
+    """
+    found = []
+    for m in _PROPER_NOUN.finditer(text):
+        phrase = m.group()
+        if " " in phrase or phrase not in _STOPWORD_CAPS:
+            found.append(phrase)
+    return found

sourced_evidence-0.1.0/sourced_evidence.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sourced-evidence
+Version: 0.1.0
+Summary: Per-claim grounded/contradicted/unverified checking of LLM output against its own source context -- never a blended trust score.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/sourced
+Project-URL: Source, https://github.com/MaXiMo000/sourced
+Project-URL: Issues, https://github.com/MaXiMo000/sourced/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/sourced/releases
+Keywords: verification,grounding,llm,rag,evidence,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sourced
+
+[![ci](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/sourced/actions/workflows/ci.yml)
+
+**Checks an LLM's output against its own source context, claim by claim --
+`grounded`, `contradicted`, or `unverified`, never one blended trust score.**
+
+A RAG pipeline retrieves the right documents and still generates a sentence
+those documents don't support -- a wrong number, an entity the source never
+mentions, a stat close enough to sound plausible. Most RAG evaluation
+scores *retrieval quality*: did the right chunks come back. Almost nothing
+checks the *output* sentence by sentence against what was actually
+retrieved. `sourced` does that second, narrower thing.
+
+```
+$ sourced check output.txt source.txt
+[OK] Microsoft reported revenue of $56 billion.
+[XX] Microsoft grew 40% year over year.
+       claims 40% near 'Microsoft', but the source's own text near that
+       entity says ['56', '8%']
+[??] The outlook remains uncertain.
+       no checkable numbers, quoted text, or capitalized entities in this claim
+
+1 grounded, 1 contradicted, 1 unverified
+```
+
+(That transcript is real output, not illustrative -- `source.txt` says growth
+was 8%; note the second claim repeats "Microsoft" by name rather than
+saying "it," because pronoun coreference isn't resolved -- see "What this
+does NOT do.")
+
+## Install
+
+```
+pip install sourced-evidence   # the command it installs is `sourced`
+```
+
+(`sourced` was already taken on PyPI -- same story as `receipt-evidence`,
+`providence-evidence`, and `custody-evidence` in this portfolio.)
+
+## Use
+
+```
+sourced check <output-file> <source-file> [source-file ...] [--json]
+```
+
+`output-file` is the LLM's generated text. `source-file`(s) are the
+context it was supposed to be grounded in -- the retrieved chunks, the
+document it summarized, the transcript it's answering questions about.
+Multiple source files are concatenated before checking.
+
+Exit code is `1` only if any claim is `contradicted` -- same convention as
+[`receipt`](https://github.com/MaXiMo000/receipt) and
+[`invariant`](https://github.com/MaXiMo000/invariant): `unverified` is a
+legitimate "can't tell," not a failure.
+
+## How a claim gets checked
+
+1. **Split into claims.** Every sentence in the output is one claim
+   candidate -- no attempt to tell a factual assertion from an opinion or
+   a hedge (`sourced/claims.py`).
+2. **Extract signals.** Numbers, quoted substrings, and capitalized
+   entity-shaped phrases (`sourced/signals.py`) -- the concrete, matchable
+   facts a source text either does or doesn't contain.
+3. **Classify against the source** (`sourced/check.py`):
+   - **`grounded`** -- every number, quote, and entity in the claim appears
+     in the source.
+   - **`contradicted`** -- a claim's number doesn't appear in the source at
+     all, but an entity from the *same claim* does, near a *different*
+     number. Narrow on purpose: this only fires when there's a real shared
+     anchor pinning the comparison to the same subject, never "two
+     different numbers exist somewhere in a long document."
+   - **`unverified`** -- everything else: no checkable signals in the claim
+     at all, or some signal simply isn't found anywhere in the source.
+
+## What this does NOT do
+
+This is the part worth reading before trusting a result.
+
+- **No semantic understanding, no paraphrase matching.** "Revenue was $56
+  billion" and "the company made fifty-six billion dollars" are the same
+  fact and this will not see it that way -- it matches strings and
+  numbers, not meaning. A real semantic entailment checker needs a
+  language model; that's real future work (an optional LLM-backed
+  adjudication pass, the same shape `invariant`'s cascade or LabLedger's
+  Gemini stage already use elsewhere in this portfolio -- degrade
+  gracefully without it, don't require it), not built here.
+- **No real named-entity recognition.** `signals.proper_nouns()` is a
+  capitalization heuristic, not a trained model. "Bank of America" splits
+  into `Bank` and `America` because a lowercase joiner breaks the
+  capitalized-word chain. Documented in `signals.py`, not hidden.
+- **No real sentence tokenizer.** `claims.split_claims()` is a regex.
+  "Dr. Smith signed the report." reads as two sentences. Ordinary prose
+  splits correctly; abbreviation-heavy text won't always.
+- **No pronoun or coreference resolution.** "Microsoft reported $56B. It
+  grew 40%." -- the second sentence's "It" is correctly excluded as an
+  entity (it's a pronoun, not a name), so there's no anchor to check that
+  claim's number against, and it comes back `unverified` rather than
+  `contradicted`. Each claim is checked entirely on its own; a real fix
+  needs coreference resolution, real NLP work of its own, not attempted
+  here.
+- **Contradiction detection is deliberately conservative**, and that cuts
+  both ways: a real contradiction with no shared entity to anchor on comes
+  back `unverified`, not `contradicted` -- this will under-report
+  contradictions before it will over-report them. That's the intended
+  trade for a tool whose whole point is not manufacturing false
+  accusations against a source.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_claims.py     # sentence splitting
+python tests/test_signals.py    # number/quote/entity extraction
+python tests/test_check.py      # the grounded/contradicted/unverified decision
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Several exist specifically because a first pass got something
+wrong and testing against ordinary prose (not synthetic numbers-only
+input) caught it -- e.g. a number regex that swallowed a following
+sentence period (`"42."` parsed as the number `42.`), a sentence-
+initial entity ("Microsoft" opening a sentence) needing case-insensitive
+matching against a source that uses the same word lowercase mid-sentence,
+without that leniency being used for anything else, and (found live
+during a later audit) American-style closing punctuation putting the
+period *inside* a quote (`"four hours."` not `"four hours".`) silently
+merging two sentences into one claim -- the sentence-end regex only ever
+checked for `[.!?]` immediately before the split point, never a quote
+mark sitting in front of it.
+
+MIT licensed.

sourced_evidence-0.1.0/sourced_evidence.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+sourced/__init__.py
+sourced/check.py
+sourced/claims.py
+sourced/cli.py
+sourced/signals.py
+sourced_evidence.egg-info/PKG-INFO
+sourced_evidence.egg-info/SOURCES.txt
+sourced_evidence.egg-info/dependency_links.txt
+sourced_evidence.egg-info/entry_points.txt
+sourced_evidence.egg-info/top_level.txt
+tests/test_check.py
+tests/test_claims.py
+tests/test_cli.py
+tests/test_signals.py

sourced_evidence-0.1.0/sourced_evidence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sourced_evidence-0.1.0/sourced_evidence.egg-info/entry_points.txt

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

sourced_evidence-0.1.0/sourced_evidence.egg-info/top_level.txt

@@ -0,0 +1 @@
+sourced

sourced_evidence-0.1.0/tests/test_check.py

@@ -0,0 +1,84 @@
+"""Run: python tests/test_check.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from sourced.check import CONTRADICTED, GROUNDED, UNVERIFIED, check_claim, check_output
+
+
+class TestCheckClaim(unittest.TestCase):
+    def test_claim_with_no_signals_is_unverified(self):
+        r = check_claim("The company grew nicely this quarter.", "Some unrelated source text.")
+        self.assertEqual(r["status"], UNVERIFIED)
+        self.assertIn("no checkable", r["detail"])
+
+    def test_number_found_verbatim_in_source_is_grounded(self):
+        """Also the entity-case-insensitivity regression test: "Revenue" is
+        a pseudo-entity purely because it's sentence-initial, and the
+        source only has it lowercase ("Q3 revenue was..."). Case-sensitive
+        entity matching used to report this real match as "missing" for no
+        reason other than capitalization, dragging an otherwise-grounded
+        claim down to unverified."""
+        source = "Q3 revenue was $42 million, up from $38 million a year ago."
+        r = check_claim("Revenue was $42 million.", source)
+        self.assertEqual(r["status"], GROUNDED)
+
+    def test_number_absent_from_source_with_no_anchor_is_unverified_not_contradicted(self):
+        """No shared entity to pin the comparison on -- this can only say
+        'not found', not 'the source disagrees'."""
+        source = "The company had a strong quarter overall."
+        r = check_claim("Revenue was $42 million.", source)
+        self.assertEqual(r["status"], UNVERIFIED)
+
+    def test_entity_present_with_a_different_number_nearby_is_contradicted(self):
+        source = "Microsoft reported revenue of $56 billion for the quarter."
+        r = check_claim("Microsoft reported revenue of $70 billion.", source)
+        self.assertEqual(r["status"], CONTRADICTED)
+        self.assertEqual(r["contradictions"][0]["entity"], "Microsoft")
+        self.assertIn("56", r["contradictions"][0]["source_numbers_nearby"])
+
+    def test_entity_present_with_the_same_number_is_grounded_not_contradicted(self):
+        source = "Microsoft reported revenue of $56 billion for the quarter."
+        r = check_claim("Microsoft reported revenue of $56 billion.", source)
+        self.assertEqual(r["status"], GROUNDED)
+
+    def test_quoted_phrase_present_verbatim_is_grounded(self):
+        source = 'The CEO said "we exceeded every target this year."'
+        r = check_claim('The CEO said "we exceeded every target this year."', source)
+        self.assertEqual(r["status"], GROUNDED)
+
+    def test_quoted_phrase_not_in_source_is_unverified(self):
+        source = "The CEO discussed the results at length."
+        r = check_claim('The CEO said "this was our best year ever."', source)
+        self.assertEqual(r["status"], UNVERIFIED)
+        self.assertIn("this was our best year ever", r["detail"])
+
+    def test_entity_only_partially_covered_is_unverified(self):
+        source = "Apple's revenue grew steadily."
+        r = check_claim("Apple and Microsoft both grew revenue.", source)
+        self.assertEqual(r["status"], UNVERIFIED)
+        self.assertIn("Microsoft", r["detail"])
+
+
+class TestCheckOutput(unittest.TestCase):
+    def test_multiple_claims_are_each_checked_independently(self):
+        source = "Microsoft reported revenue of $56 billion. Apple grew 8%."
+        output = "Microsoft reported revenue of $56 billion. Apple grew 40%. The mood was upbeat."
+        report = check_output(output, source)
+        self.assertEqual(len(report["claims"]), 3)
+        statuses = [c["status"] for c in report["claims"]]
+        self.assertEqual(statuses, [GROUNDED, CONTRADICTED, UNVERIFIED])
+        self.assertEqual(report["counts"], {"grounded": 1, "contradicted": 1, "unverified": 1})
+
+    def test_empty_output_is_zero_claims_not_an_error(self):
+        report = check_output("", "some source")
+        self.assertEqual(report["claims"], [])
+        self.assertEqual(report["counts"], {"grounded": 0, "contradicted": 0, "unverified": 0})
+
+
+if __name__ == "__main__":
+    unittest.main()

sourced_evidence-0.1.0/tests/test_claims.py

@@ -0,0 +1,78 @@
+"""Run: python tests/test_claims.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from sourced.claims import split_claims
+
+
+class TestSplitClaims(unittest.TestCase):
+    def test_empty_text_is_no_claims(self):
+        self.assertEqual(split_claims(""), [])
+        self.assertEqual(split_claims("   "), [])
+
+    def test_single_sentence_is_one_claim(self):
+        self.assertEqual(split_claims("Revenue grew 12% in Q3."),
+                          ["Revenue grew 12% in Q3."])
+
+    def test_multiple_sentences_split_on_terminal_punctuation(self):
+        text = "Revenue grew 12% in Q3. Costs fell slightly. Margins improved."
+        self.assertEqual(split_claims(text), [
+            "Revenue grew 12% in Q3.",
+            "Costs fell slightly.",
+            "Margins improved.",
+        ])
+
+    def test_question_marks_and_exclamations_also_split(self):
+        text = "Did revenue grow? Yes, by 12%! That beat expectations."
+        self.assertEqual(len(split_claims(text)), 3)
+
+    def test_a_decimal_number_does_not_split_mid_sentence(self):
+        """3.14 is not two sentences -- the split only fires when a capital,
+        digit, or quote follows the punctuation+space, and a lowercase
+        continuation (or no space at all, as in a decimal) doesn't count."""
+        text = "Pi is approximately 3.14 and shows up everywhere."
+        self.assertEqual(split_claims(text), [text])
+
+    def test_known_limitation_abbreviations_over_split(self):
+        """Documented, not hidden: 'Dr. Smith' reads as two sentences,
+        since this is a regex, not a real tokenizer that knows abbreviations."""
+        text = "Dr. Smith signed the report."
+        self.assertEqual(len(split_claims(text)), 2)
+
+    def test_a_period_inside_a_closing_quote_still_splits(self):
+        """Real bug, found live: American-style punctuation puts the period
+        *inside* the quote ("four hours." not "four hours".), so the
+        character right before the split point is the quote mark, not
+        [.!?] -- the original lookbehind only ever checked for [.!?]
+        directly, so this silently merged two claims into one."""
+        text = 'The report said the outage lasted "four hours." The team resolved it by noon.'
+        self.assertEqual(split_claims(text), [
+            'The report said the outage lasted "four hours."',
+            "The team resolved it by noon.",
+        ])
+
+    def test_a_period_outside_a_closing_quote_still_splits(self):
+        """The other quoting convention already worked (the period itself
+        sits right before the space) -- pinned so a future regex change
+        can't fix one convention by breaking the other."""
+        text = 'The report said the outage lasted "four hours". The team resolved it by noon.'
+        self.assertEqual(split_claims(text), [
+            'The report said the outage lasted "four hours".',
+            "The team resolved it by noon.",
+        ])
+
+    def test_a_period_inside_a_closing_paren_still_splits(self):
+        text = "She said it works (allegedly.) Then it broke."
+        self.assertEqual(split_claims(text), [
+            "She said it works (allegedly.)",
+            "Then it broke.",
+        ])
+
+
+if __name__ == "__main__":
+    unittest.main()

sourced_evidence-0.1.0/tests/test_cli.py

@@ -0,0 +1,90 @@
+"""Run: python tests/test_cli.py
+
+Exercises the real CLI entry point end to end -- real temp files, real
+argv, real stdout capture -- not just the pure check_output() function
+underneath it.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from sourced.cli import main
+
+
+class TestCli(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = pathlib.Path(self.tmp.name)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _write(self, name: str, content: str) -> str:
+        p = self.dir / name
+        p.write_text(content, encoding="utf-8")
+        return str(p)
+
+    def test_exit_zero_when_nothing_contradicted(self):
+        output = self._write("output.txt", "Microsoft reported revenue of $56 billion.")
+        source = self._write("source.txt", "Microsoft reported revenue of $56 billion.")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", output, source])
+        self.assertEqual(code, 0)
+        self.assertIn("1 grounded", buf.getvalue())
+
+    def test_exit_one_when_a_claim_is_contradicted(self):
+        output = self._write("output.txt", "Microsoft reported revenue of $70 billion.")
+        source = self._write("source.txt", "Microsoft reported revenue of $56 billion.")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", output, source])
+        self.assertEqual(code, 1)
+        self.assertIn("1 contradicted", buf.getvalue())
+
+    def test_multiple_source_files_are_concatenated(self):
+        output = self._write("output.txt", "Microsoft reported revenue of $56 billion.")
+        s1 = self._write("s1.txt", "Some unrelated background.")
+        s2 = self._write("s2.txt", "Microsoft reported revenue of $56 billion.")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", output, s1, s2])
+        self.assertEqual(code, 0)
+        self.assertIn("1 grounded", buf.getvalue())
+
+    def test_missing_source_file_is_a_clean_error_not_a_traceback(self):
+        """Found by testing an actual typo'd path, the same way
+        providence's malformed-JSON crash was found: a missing file used
+        to raise FileNotFoundError straight out of main()."""
+        output = self._write("output.txt", "A claim.")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", output, str(self.dir / "nope.txt")])
+        self.assertIn("no such file", str(ctx.exception))
+
+    def test_a_directory_given_instead_of_a_file_is_a_clean_error(self):
+        output = self._write("output.txt", "A claim.")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", output, str(self.dir)])
+        self.assertIn("is a directory", str(ctx.exception))
+
+    def test_json_flag_prints_the_full_report(self):
+        output = self._write("output.txt", "Microsoft reported revenue of $56 billion.")
+        source = self._write("source.txt", "Microsoft reported revenue of $56 billion.")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", output, source, "--json"])
+        report = json.loads(buf.getvalue())
+        self.assertEqual(report["counts"]["grounded"], 1)
+        self.assertEqual(report["claims"][0]["status"], "grounded")
+
+
+if __name__ == "__main__":
+    unittest.main()

sourced_evidence-0.1.0/tests/test_signals.py

@@ -0,0 +1,84 @@
+"""Run: python tests/test_signals.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from sourced import signals
+
+
+class TestNumbers(unittest.TestCase):
+    def test_plain_integer(self):
+        self.assertEqual(signals.numbers("Revenue was 42."), ["42"])
+
+    def test_decimal_and_percent(self):
+        self.assertEqual(signals.numbers("Grew 12.5% this quarter."), ["12.5%"])
+
+    def test_comma_thousands_separator_is_normalized(self):
+        self.assertEqual(signals.numbers("Sold 1,200,000 units."), ["1200000"])
+
+    def test_negative_number(self):
+        self.assertEqual(signals.numbers("Margin fell -3.2%."), ["-3.2%"])
+
+    def test_no_numbers(self):
+        self.assertEqual(signals.numbers("Revenue grew nicely."), [])
+
+
+class TestQuotes(unittest.TestCase):
+    def test_double_quoted_phrase(self):
+        self.assertEqual(signals.quotes('The CEO called it "a record quarter."'),
+                          ["a record quarter."])
+
+    def test_single_quoted_phrase(self):
+        self.assertEqual(signals.quotes("She called it 'a turning point'."),
+                          ["a turning point"])
+
+    def test_short_quotes_under_three_chars_are_ignored(self):
+        """A stray apostrophe pair around one letter isn't a quoted claim
+        worth checking -- e.g. a possessive or a contraction fragment."""
+        self.assertEqual(signals.quotes("It's 'a' small win."), [])
+
+    def test_no_quotes(self):
+        self.assertEqual(signals.quotes("Revenue grew 12%."), [])
+
+
+class TestProperNouns(unittest.TestCase):
+    def test_lowercase_joiner_splits_a_real_multiword_entity(self):
+        """Documented limitation, not a bug: real NER would see one entity,
+        'Bank of America'. This regex only chains directly-adjacent
+        capitalized words, so 'of' breaks the chain -- 'Bank' (sentence-
+        initial, so excluded) and 'America' (kept) come out separately."""
+        self.assertEqual(signals.proper_nouns("Bank of America reported earnings."),
+                          ["Bank", "America"])
+
+    def test_adjacent_capitalized_words_do_chain(self):
+        self.assertEqual(signals.proper_nouns("It involved New York City directly."),
+                          ["New York City"])
+
+    def test_sentence_initial_subject_is_kept_as_a_candidate_entity(self):
+        """Deliberate, not a miss: 'Microsoft reported X' is exactly the
+        subject-first shape a contradiction check needs to anchor on, and
+        excluding anything sentence-initial would silently drop it. The
+        real cost -- an ordinary sentence-initial common noun like
+        'Revenue' also becomes a pseudo-entity -- is accepted and
+        documented in signals.py, not hidden."""
+        self.assertEqual(signals.proper_nouns("Revenue grew 12% in Q3."), ["Revenue", "Q3"])
+
+    def test_stopword_caps_excluded_even_sentence_initial(self):
+        self.assertEqual(signals.proper_nouns("The company grew 12% in Q3."), ["Q3"])
+
+    def test_midsentence_single_capitalized_word_is_kept(self):
+        self.assertIn("Microsoft", signals.proper_nouns("The deal involved Microsoft directly."))
+
+    def test_stopword_caps_excluded_even_midsentence(self):
+        self.assertNotIn("The", signals.proper_nouns("It grew, and The company noted it."))
+
+    def test_no_entities(self):
+        self.assertEqual(signals.proper_nouns("revenue grew twelve percent"), [])
+
+
+if __name__ == "__main__":
+    unittest.main()