tmr-gates 0.1.1__tar.gz

tmr_gates-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: publish
+# Builds the package and publishes it to PyPI through trusted publishing
+# (no API token in the repository). The PyPI project must list this workflow
+# as a trusted publisher: owner vzolot, repository tmr-gates, workflow
+# publish.yml, environment pypi.
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .[test] build
+      - run: pytest -q
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tmr_gates-0.1.1/.github/workflows/tests.yml

@@ -0,0 +1,15 @@
+name: tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e .[test]
+      - run: pytest -q

tmr_gates-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.venv/

tmr_gates-0.1.1/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.1 (2026-10-24)
+
+- All inline comments translated into English; no change in behaviour, the tests are unchanged.
+- Publishing workflow for PyPI (trusted publishing on a version tag).
+
+## 0.1.0 (2026-10-23)
+
+First release, extracted unchanged from the pipeline of The Machine Record.
+
+- `evaluate()`, `precheck_sources()`, `precheck_verification()`: the publication gates.
+- Source tiers for US, UK, EU, Japan, Korea, China and government domains.
+- Court-record policy: a lone court document with full text can carry a case.
+- `strip_private_names()`: removes names of private individuals from public text.
+- Tests ported from the pipeline (66 checks).

tmr_gates-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Zolotukhin, The Machine Record
+
+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.

tmr_gates-0.1.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: tmr-gates
+Version: 0.1.1
+Summary: Publication gates of The Machine Record: deterministic rules that decide whether a verified robot incident may be published.
+Project-URL: Homepage, https://themachinerecord.com/methodology
+Project-URL: Repository, https://github.com/vzolot/tmr-gates
+Project-URL: Registry, https://themachinerecord.com
+Author-email: Volodymyr Zolotukhin <hello@themachinerecord.com>
+License: MIT
+License-File: LICENSE
+Keywords: fact-checking,incident,journalism,registry,robotics,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Filters
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tmr-gates
+
+The publication gates of [The Machine Record](https://themachinerecord.com), an open register of safety incidents involving commercial robots, as a standalone Python package with no dependencies.
+
+The register publishes without human pre-moderation. A language model answers one question, "do these sources describe the same real-world event, and how well", and an adversarial pass looks for defamation, satire, unattributed accusations and stale news. Everything after that is rules. This package is those rules: they decide whether a verified event may be published, what evidence a grave allegation needs, which sources count, and which names must never appear in public text. Every rule is deterministic, documented here and covered by tests, so anyone can run the register's own cases through the same gates and get the same decisions.
+
+The code is extracted unchanged from the production pipeline. The inline comments record why each rule exists, usually a case in the register that went wrong without it; this README documents the rules themselves.
+
+## Install
+
+```
+pip install tmr-gates
+```
+
+or straight from the repository:
+
+```
+pip install git+https://github.com/vzolot/tmr-gates@v0.1.1
+```
+
+Python 3.9 or newer. No runtime dependencies.
+
+## Use
+
+```python
+from datetime import date
+from tmr_gates import default_config, evaluate, precheck_sources, strip_private_names
+
+cfg = default_config()
+
+sources = [
+    {"url": "https://www.reuters.com/...", "domain": "reuters.com", "tier": 1,
+     "published_at": "2026-05-02", "article_text": "..."},
+    {"url": "https://www.localpaper.com/...", "domain": "localpaper.com", "tier": 2,
+     "published_at": "2026-05-03", "article_text": "..."},
+]
+
+# Cheap checks before paying for a model call: enough independent domains, not all tier 3.
+pre = precheck_sources(cfg=cfg, sources=sources)
+assert pre.publish, pre.reasons
+
+verification = {          # the model's cross-verification of the sources
+    "same_event": True,
+    "verification_score": 0.91,
+    "incident_type": "injury",
+    "disagreements": [],
+}
+adversarial = {"risk_score": 0.1, "blocking": []}   # the adversarial pass
+
+decision = evaluate(
+    cfg=cfg, sources=sources, verification=verification, adversarial=adversarial,
+    company="Robot Co.", severity="minor_injury",
+    date_of_incident="2026-05-01", date_precision="day", today=date(2026, 5, 4),
+)
+print(decision.publish, decision.reasons, decision.checks)
+
+# Public text never carries the names of private individuals.
+clean = strip_private_names("Worker John Smith, 34, was pinned by the arm.")
+```
+
+`Decision.publish` is the verdict, `Decision.reasons` lists every failed rule, and `Decision.checks` records what each rule saw, so a refusal can be audited without rerunning anything.
+
+## The rules
+
+`evaluate()` applies them in this order. Each failure is recorded; the decision fails if any rule fails.
+
+| # | Rule | Config key, default |
+|---|------|---------------------|
+| 0 | Kill switch. When auto-publishing is off nothing passes. The register's circuit breaker flips this when the share of disputed cases rises. | `auto_publish`, true |
+| 1 | The sources describe the same event, according to the model's cross-verification. | |
+| 2 | Enough independent domains. Syndication copies, subdomains and link shorteners of one outlet count once. A court record with full text is a primary document and suffices alone. | `min_independent_domains`, 2 |
+| 3 | At least one tier 1 or tier 2 source among the independent domains. Tier 3 (social networks, blogs, tabloids, aggregators) is never enough on its own and is not counted as corroboration. | |
+| 4 | A death or serious injury attributed to a named company needs three independent sources, one of them tier 1. A court record waives this: the allegation is the filing itself, on the record. | `grave_severities`, `grave_min_sources` 3, `grave_requires_tier1` true |
+| 4a | The event is an incident at all, not a product launch, a demo or an opinion piece; a commercial robot or automated machine is the subject. | |
+| 5 | No material disagreement between sources on company, model, date, place, severity or what happened. Silence is not a contradiction; a wording difference that is explained is not a contradiction. | |
+| 6 | Verification score at or above the threshold, risk score at or below the ceiling. Court records get a lower score bar and a higher risk ceiling. | `min_verification_score` 0.80, `max_risk_score` 0.35, `court_min_verification_score` 0.75, `court_max_risk_score` 0.75 |
+| 7 | No blocking flag from the adversarial pass: satire or fake, defamation pattern, single source behind many wrappers, named private individual, unattributed accusation, stale event presented as new. For court records the last three are waived and recorded, because a complaint is by nature an attributed accusation about named people on a past date. | |
+| 8 | Date sanity. The date of the incident is known to the day or the month, is not in the future, and is not later than the earliest publication by more than two days. | |
+
+`precheck_sources()` runs rules 2 and 3 before any model call, and `precheck_verification()` runs 1, 4a, 5, 6 and 8 after the first model pass, so a bundle that cannot pass is never sent to the expensive adversarial pass. Both are strict subsets of `evaluate()`: they can only reject what it would reject.
+
+### Source tiers
+
+`tier_of(domain)` returns 1, 2 or 3.
+
+- Tier 1: wire agencies, national outlets and public broadcasters in the US, UK, Germany, France, Italy, Spain, the Netherlands, Poland, Japan, Korea, Hong Kong and Taiwan; regulators and courts through government suffixes (`.gov`, `.gouv.fr`, `.bund.de`, `.go.jp`, `.go.kr`, `.europa.eu` and others); court dockets on CourtListener.
+- Tier 2: every unknown domain, on purpose. Regional papers are where most incidents first appear, and demoting the unknown would switch corroboration off. The price of that assumption is paid by rule 4, where it matters most.
+- Tier 3: social networks, blogs, video platforms, tabloids, content farms and syndication portals that republish other outlets' text under their own domain.
+
+The lists live in `tmr_gates/tiers.py` and are the register's editorial judgement, published so it can be argued with.
+
+### Court records
+
+`court_document(sources)` is true when a source is a docket on courtlistener.com with at least 1,500 characters of text. Such a record can carry a case alone (rule 2), waives the three-source rule for grave allegations (rule 4) and three adversarial flags (rule 7), and is judged against its own thresholds (rule 6). The reasoning: a filed complaint is a primary document, attributed by definition, and its allegations are reported as allegations.
+
+### Private individuals
+
+`strip_private_names(text)` removes the names of private people from public text while keeping company names, places, public officials by role, and product names. It is a regular-expression stripper with explicit lists of protected forms (facilities, roads, months, corporate suffixes, known places). Names of officials, spokespeople and company representatives are kept when their role is stated. The register also runs a defamation rewriter before this; the stripper is the last line.
+
+## How The Machine Record uses it
+
+The production pipeline imports this package and applies the gates to every candidate case after capture, corroboration and two model passes. Thresholds come from a database table so the circuit breaker can change them without a deploy. The methodology page at [themachinerecord.com/methodology](https://themachinerecord.com/methodology) describes the same rules in prose; this package is the executable version.
+
+## Tests
+
+```
+pip install -e .[test]
+pytest -q
+```
+
+The tests are the acceptance criteria of the register: a tabloid alone never passes, a death attributed to a named company needs three sources and a tier 1, a future date fails, a court record passes with the flags a complaint always carries, and the stripper removes a named patient but keeps a hospital named after a person.
+
+## Licence
+
+MIT. The case data of the register is published separately under CC BY 4.0 at [vzolot/machine-record-data](https://github.com/vzolot/machine-record-data).

tmr_gates-0.1.1/README.md

@@ -0,0 +1,115 @@
+# tmr-gates
+
+The publication gates of [The Machine Record](https://themachinerecord.com), an open register of safety incidents involving commercial robots, as a standalone Python package with no dependencies.
+
+The register publishes without human pre-moderation. A language model answers one question, "do these sources describe the same real-world event, and how well", and an adversarial pass looks for defamation, satire, unattributed accusations and stale news. Everything after that is rules. This package is those rules: they decide whether a verified event may be published, what evidence a grave allegation needs, which sources count, and which names must never appear in public text. Every rule is deterministic, documented here and covered by tests, so anyone can run the register's own cases through the same gates and get the same decisions.
+
+The code is extracted unchanged from the production pipeline. The inline comments record why each rule exists, usually a case in the register that went wrong without it; this README documents the rules themselves.
+
+## Install
+
+```
+pip install tmr-gates
+```
+
+or straight from the repository:
+
+```
+pip install git+https://github.com/vzolot/tmr-gates@v0.1.1
+```
+
+Python 3.9 or newer. No runtime dependencies.
+
+## Use
+
+```python
+from datetime import date
+from tmr_gates import default_config, evaluate, precheck_sources, strip_private_names
+
+cfg = default_config()
+
+sources = [
+    {"url": "https://www.reuters.com/...", "domain": "reuters.com", "tier": 1,
+     "published_at": "2026-05-02", "article_text": "..."},
+    {"url": "https://www.localpaper.com/...", "domain": "localpaper.com", "tier": 2,
+     "published_at": "2026-05-03", "article_text": "..."},
+]
+
+# Cheap checks before paying for a model call: enough independent domains, not all tier 3.
+pre = precheck_sources(cfg=cfg, sources=sources)
+assert pre.publish, pre.reasons
+
+verification = {          # the model's cross-verification of the sources
+    "same_event": True,
+    "verification_score": 0.91,
+    "incident_type": "injury",
+    "disagreements": [],
+}
+adversarial = {"risk_score": 0.1, "blocking": []}   # the adversarial pass
+
+decision = evaluate(
+    cfg=cfg, sources=sources, verification=verification, adversarial=adversarial,
+    company="Robot Co.", severity="minor_injury",
+    date_of_incident="2026-05-01", date_precision="day", today=date(2026, 5, 4),
+)
+print(decision.publish, decision.reasons, decision.checks)
+
+# Public text never carries the names of private individuals.
+clean = strip_private_names("Worker John Smith, 34, was pinned by the arm.")
+```
+
+`Decision.publish` is the verdict, `Decision.reasons` lists every failed rule, and `Decision.checks` records what each rule saw, so a refusal can be audited without rerunning anything.
+
+## The rules
+
+`evaluate()` applies them in this order. Each failure is recorded; the decision fails if any rule fails.
+
+| # | Rule | Config key, default |
+|---|------|---------------------|
+| 0 | Kill switch. When auto-publishing is off nothing passes. The register's circuit breaker flips this when the share of disputed cases rises. | `auto_publish`, true |
+| 1 | The sources describe the same event, according to the model's cross-verification. | |
+| 2 | Enough independent domains. Syndication copies, subdomains and link shorteners of one outlet count once. A court record with full text is a primary document and suffices alone. | `min_independent_domains`, 2 |
+| 3 | At least one tier 1 or tier 2 source among the independent domains. Tier 3 (social networks, blogs, tabloids, aggregators) is never enough on its own and is not counted as corroboration. | |
+| 4 | A death or serious injury attributed to a named company needs three independent sources, one of them tier 1. A court record waives this: the allegation is the filing itself, on the record. | `grave_severities`, `grave_min_sources` 3, `grave_requires_tier1` true |
+| 4a | The event is an incident at all, not a product launch, a demo or an opinion piece; a commercial robot or automated machine is the subject. | |
+| 5 | No material disagreement between sources on company, model, date, place, severity or what happened. Silence is not a contradiction; a wording difference that is explained is not a contradiction. | |
+| 6 | Verification score at or above the threshold, risk score at or below the ceiling. Court records get a lower score bar and a higher risk ceiling. | `min_verification_score` 0.80, `max_risk_score` 0.35, `court_min_verification_score` 0.75, `court_max_risk_score` 0.75 |
+| 7 | No blocking flag from the adversarial pass: satire or fake, defamation pattern, single source behind many wrappers, named private individual, unattributed accusation, stale event presented as new. For court records the last three are waived and recorded, because a complaint is by nature an attributed accusation about named people on a past date. | |
+| 8 | Date sanity. The date of the incident is known to the day or the month, is not in the future, and is not later than the earliest publication by more than two days. | |
+
+`precheck_sources()` runs rules 2 and 3 before any model call, and `precheck_verification()` runs 1, 4a, 5, 6 and 8 after the first model pass, so a bundle that cannot pass is never sent to the expensive adversarial pass. Both are strict subsets of `evaluate()`: they can only reject what it would reject.
+
+### Source tiers
+
+`tier_of(domain)` returns 1, 2 or 3.
+
+- Tier 1: wire agencies, national outlets and public broadcasters in the US, UK, Germany, France, Italy, Spain, the Netherlands, Poland, Japan, Korea, Hong Kong and Taiwan; regulators and courts through government suffixes (`.gov`, `.gouv.fr`, `.bund.de`, `.go.jp`, `.go.kr`, `.europa.eu` and others); court dockets on CourtListener.
+- Tier 2: every unknown domain, on purpose. Regional papers are where most incidents first appear, and demoting the unknown would switch corroboration off. The price of that assumption is paid by rule 4, where it matters most.
+- Tier 3: social networks, blogs, video platforms, tabloids, content farms and syndication portals that republish other outlets' text under their own domain.
+
+The lists live in `tmr_gates/tiers.py` and are the register's editorial judgement, published so it can be argued with.
+
+### Court records
+
+`court_document(sources)` is true when a source is a docket on courtlistener.com with at least 1,500 characters of text. Such a record can carry a case alone (rule 2), waives the three-source rule for grave allegations (rule 4) and three adversarial flags (rule 7), and is judged against its own thresholds (rule 6). The reasoning: a filed complaint is a primary document, attributed by definition, and its allegations are reported as allegations.
+
+### Private individuals
+
+`strip_private_names(text)` removes the names of private people from public text while keeping company names, places, public officials by role, and product names. It is a regular-expression stripper with explicit lists of protected forms (facilities, roads, months, corporate suffixes, known places). Names of officials, spokespeople and company representatives are kept when their role is stated. The register also runs a defamation rewriter before this; the stripper is the last line.
+
+## How The Machine Record uses it
+
+The production pipeline imports this package and applies the gates to every candidate case after capture, corroboration and two model passes. Thresholds come from a database table so the circuit breaker can change them without a deploy. The methodology page at [themachinerecord.com/methodology](https://themachinerecord.com/methodology) describes the same rules in prose; this package is the executable version.
+
+## Tests
+
+```
+pip install -e .[test]
+pytest -q
+```
+
+The tests are the acceptance criteria of the register: a tabloid alone never passes, a death attributed to a named company needs three sources and a tier 1, a future date fails, a court record passes with the flags a complaint always carries, and the stripper removes a named patient but keeps a hospital named after a person.
+
+## Licence
+
+MIT. The case data of the register is published separately under CC BY 4.0 at [vzolot/machine-record-data](https://github.com/vzolot/machine-record-data).

tmr_gates-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tmr-gates"
+version = "0.1.1"
+description = "Publication gates of The Machine Record: deterministic rules that decide whether a verified robot incident may be published."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Volodymyr Zolotukhin", email = "hello@themachinerecord.com" }]
+keywords = ["verification", "journalism", "robotics", "incident", "registry", "fact-checking"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Text Processing :: Filters",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://themachinerecord.com/methodology"
+Repository = "https://github.com/vzolot/tmr-gates"
+Registry = "https://themachinerecord.com"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tmr_gates"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

tmr_gates-0.1.1/src/tmr_gates/__init__.py

@@ -0,0 +1,27 @@
+"""tmr-gates: the publication gates of The Machine Record as a standalone package."""
+from .config import DEFAULTS, Config, default_config
+from .gates import (
+    COURT_NON_BLOCKING,
+    Decision,
+    check_is_incident,
+    check_robot_subject,
+    court_document,
+    evaluate,
+    independent_domains,
+    material_disagreements,
+    min_score,
+    precheck_sources,
+    precheck_verification,
+    required_domains,
+    strip_private_names,
+)
+from .tiers import GOV_SUFFIXES, TIER1_DOMAINS, TIER3_DOMAINS, TIER3_HINTS, tier_of
+
+__version__ = "0.1.0"
+__all__ = [
+    "COURT_NON_BLOCKING", "DEFAULTS", "Config", "Decision", "GOV_SUFFIXES", "TIER1_DOMAINS",
+    "TIER3_DOMAINS", "TIER3_HINTS", "check_is_incident", "check_robot_subject", "court_document",
+    "default_config", "evaluate", "independent_domains", "material_disagreements", "min_score",
+    "precheck_sources", "precheck_verification", "required_domains", "strip_private_names",
+    "tier_of",
+]

tmr_gates-0.1.1/src/tmr_gates/config.py

@@ -0,0 +1,45 @@
+"""Thresholds the gates read. The Machine Record keeps the live values in a
+database table so its circuit breaker can switch auto-publishing off without a
+deploy; this package only needs a mapping with the same keys.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULTS: dict[str, Any] = {
+    # Kill switch: when False, evaluate() never returns publish=True.
+    "auto_publish": True,
+    # Minimum cross-verification score from the model for press sources.
+    "min_verification_score": 0.80,
+    # A lone court document with full text is a primary record; lower bar.
+    "court_min_verification_score": 0.75,
+    # Maximum risk score from the adversarial pass for press sources.
+    "max_risk_score": 0.35,
+    # Court documents are allowed a higher risk score because the "accusation"
+    # is the filing itself, attributed and on the record.
+    "court_max_risk_score": 0.75,
+    # Independent domains required before anything is published.
+    "min_independent_domains": 2,
+    # Severities for which a named company needs three sources and a tier 1.
+    "grave_severities": ["serious_injury", "fatality"],
+    "grave_min_sources": 3,
+    "grave_requires_tier1": True,
+}
+
+
+@dataclass
+class Config:
+    """A mapping of thresholds with DEFAULTS behind it."""
+
+    values: dict[str, Any]
+
+    def __getitem__(self, key: str) -> Any:
+        return self.values.get(key, DEFAULTS.get(key))
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.values.get(key, DEFAULTS.get(key, default))
+
+
+def default_config() -> Config:
+    return Config(dict(DEFAULTS))