bilingual-lint 0.1.0__tar.gz

bilingual_lint-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.docx binary
+*.png binary

bilingual_lint-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

bilingual_lint-0.1.0/.gitignore

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

bilingual_lint-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 — 2026-11-12
+
+First version.
+
+- Input: two-column bilingual DOCX, or two separate DOCX files paired by
+  clause numbers, digit signatures and length.
+- Twelve rules, BI000 to BI011: numbers, amounts and currency, dates,
+  digits against words, durations and day types, clause references, missing or
+  untranslated text, defined terms and glossary, identifiers, the
+  prevailing-language clause, obligation and negation cues.
+- Language-neutral rules for any pair; word-based rules for English and Russian.
+- Console, JSON and Markdown reports; exit codes for use as a pipeline gate.
+- Optional model pass (`--llm`) for pairs the rules cannot settle. Off by default.
+  `--llm-scope all` sends every pair instead, to catch wording dropped from one
+  side when no number or term gives it away. Pairs with the same text on both
+  sides, or with no words, are skipped; headings and labels no longer come back
+  as "unclear".
+- After a first run over real two-column documents: times of day are compared
+  (`21:00` against `9 p.m.`); a currency named without an amount is compared;
+  a clause reference worded differently on one side no longer reads as a
+  number mismatch; a defined term matches its singular and plural and keeps
+  its capital letter; a Latin name kept on a non-Latin side is not reported as
+  untranslated; fewer false negation and obligation cues (`No. 15`, `unless`,
+  `shall be entitled to`).

bilingual_lint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for taking a look.
+
+## Setup
+
+```
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+```
+
+## Ground rules
+
+- **Rules first.** A check that can be done deterministically is done
+  deterministically. The model pass is for what rules cannot settle.
+- **Every rule has two tests:** a clean case that must stay silent and a defect
+  that must be found. A rule that cannot be made to fail is not a rule.
+- **No real documents.** Examples and fixtures are invented. Do not add client,
+  firm or personal data to the repository, in any form.
+- **Say what you could not read.** If the tool cannot determine something, it
+  reports that or stays silent. It does not guess.
+
+## Adding a language
+
+Add `src/bilingual_lint/wordlists/<code>.yaml` with the same keys as `en.yaml`.
+Entries are regular-expression fragments. The word-based rules pick the language
+up automatically once both languages of a pair have a wordlist. Add tests next
+to the existing English and Russian ones.
+
+## Adding a rule
+
+One file in `src/bilingual_lint/rules/`, one entry in `ALL_RULES`, one entry in
+`RULE_DEFAULTS`, one row in the README table, and tests.

bilingual_lint-0.1.0/LICENSE

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

bilingual_lint-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: bilingual-lint
+Version: 0.1.0
+Summary: A linter for bilingual legal documents — find where the two language versions of a contract disagree on numbers, dates, amounts, clauses and the prevailing language
+Project-URL: Homepage, https://github.com/kirillsakhin/bilingual-lint
+Project-URL: Issues, https://github.com/kirillsakhin/bilingual-lint/issues
+Project-URL: Changelog, https://github.com/kirillsakhin/bilingual-lint/blob/main/CHANGELOG.md
+Author: Kirill Sakhin
+License: MIT
+License-File: LICENSE
+Keywords: bilingual,contracts,docx,legal,legal-tech,linter,translation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Requires-Dist: python-docx>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# bilingual-lint
+
+[![CI](https://github.com/kirillsakhin/bilingual-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/kirillsakhin/bilingual-lint/actions/workflows/ci.yml)
+
+A linter for bilingual legal documents. Give it a contract in two languages and it
+reports where the two versions disagree: a different amount, a different date, a
+missing paragraph, a clause that makes English prevail on the left and Russian on
+the right. Deterministically, offline, the same way every time.
+
+## Why
+
+A bilingual contract is one deal written twice. Every number, date, deadline and
+party name has to be the same in both columns, and nobody enjoys checking that by
+eye on page 40.
+
+The obvious 2026 answer is "have an LLM compare the two versions". It helps with
+meaning, but it is the wrong tool for facts: it can pass a changed digit in one
+clause and flag the same thing in another, and two runs disagree with each other.
+
+So bilingual-lint does it the other way around. Rules check the facts: they catch
+the same defect every time, need no API key and send nothing anywhere. A model
+comes second, optionally, and by default only for the pairs the rules cannot
+settle.
+
+It does not judge translation style or quality. It checks what must be identical.
+
+## Install
+
+From a clone of this repository:
+
+```
+pip install -e .
+```
+
+Python 3.10 or newer. The optional model pass needs `pip install -e ".[llm]"`.
+
+## Quickstart
+
+A two-column bilingual DOCX:
+
+```
+bilingual-lint check contract.docx
+```
+
+A source file and its translation:
+
+```
+bilingual-lint check contract_en.docx contract_ru.docx
+```
+
+Against the bundled sample ([`examples/sample_en_ru.docx`](examples/sample_en_ru.docx),
+an invented contract with twelve planted defects), `--format md` gives, in part:
+
+```
+# bilingual-lint report
+
+- Mode: two-column, en / ru
+- Pairs checked: 13 (0 without a counterpart)
+- Findings: 12, 8 error, 3 warning, 1 info
+
+## BI002 · error · pair 4
+
+amounts differ — en only: 150,000 · ru only: 105 000
+
+## BI005 · error · pair 5
+
+duration day type differs — business against calendar days (en: 10, ru: 10)
+
+## BI010 · error · pair 9
+
+the two sides disagree on which language prevails — en side: en · ru side: ru
+
+## BI004 · error · pair 10
+
+digits and words disagree on the ru side — 3 against "двух"
+```
+
+The clean copy of the same contract ([`examples/clean_en_ru.docx`](examples/clean_en_ru.docx))
+produces no findings.
+
+Exit codes: `0` nothing at or above the threshold, `1` findings, `2` the input
+could not be read or the command was wrong. That makes it usable as a gate after
+a translation step.
+
+## Rules
+
+| Code | Checks | Default | Languages |
+|---|---|---|---|
+| BI000 | Notes about the file: tracked changes, comments, text outside the bilingual table | info | any |
+| BI001 | A number or percentage appears on one side only | error | any |
+| BI002 | A money amount or its currency differs, or the two sides name different currencies | error | any |
+| BI003 | A date or a time of day differs, or a date agrees only under one day/month reading (`02/03/2025`) | error | any |
+| BI004 | Digits and words disagree on the same side: `ten (15)` | error | en, ru |
+| BI005 | A time period differs in length, unit or day type (30 days vs 30 business days) | error | en, ru |
+| BI006 | A clause number or cross-reference differs | warning | any |
+| BI007 | A segment is missing, empty, untranslated or far off in length | error | any |
+| BI008 | A defined term or glossary term is rendered inconsistently | warning | en, ru |
+| BI009 | A registration number, IBAN, e-mail or URL differs | error | any |
+| BI010 | The prevailing-language clause is one-sided or contradicts itself | error | en, ru |
+| BI011 | Obligation, permission or negation wording differs (heuristic) | info | en, ru |
+
+"any" rules work for every language pair. The others need a wordlist and currently
+ship for English and Russian; for other pairs they are skipped, and the report
+says which.
+
+### How numbers are compared
+
+`1,000` is one thousand in English and exactly one in Russian. bilingual-lint does
+not guess: an ambiguous number keeps both readings and matches if either agrees
+with the other side. Set `strict_separators: true` to read each language by its
+own convention only.
+
+A number spelled out on one side (`two copies` / `2 экземпляра`) is not a defect.
+
+## Two separate files
+
+Paragraphs are paired deterministically: first at anchors (clause numbers and
+paragraphs with a unique set of digits), then by length between anchors. A
+paragraph with no partner becomes a finding. Each pair has a confidence value; for
+low-confidence pairs the report says "check the pairing first" and errors are
+shown as warnings.
+
+## Options
+
+```
+bilingual-lint check FILE [FILE]
+  --langs en,es         name the two languages (needed when they share a script)
+  --glossary terms.yaml term pairs to enforce:  - {en: Buyer, ru: Покупатель}
+  --config FILE         use this config file instead of ./.bilingual-lint.yaml
+  --format console|json|md
+  --output report.json
+  --fail-on error|warning
+  --rules BI001,BI010   run only these rules
+  --llm MODEL           optional model pass (see below)
+  --llm-gate            treat a model answer of "differs" as an error
+  --llm-scope SCOPE     flagged (default) or all
+bilingual-lint rules    list the rules
+bilingual-lint init     write a starter .bilingual-lint.yaml
+```
+
+## Optional model pass
+
+`--llm` sends only the pairs the rules flagged but could not settle (BI011 and
+low-confidence pairs) to a model through [litellm](https://github.com/BerriAI/litellm)
+and asks one question: do these two texts say the same thing? Answers are marked
+as model suggestions and do not change the exit code unless you pass `--llm-gate`.
+
+`--llm-scope all` sends every pair instead, up to `llm.max_pairs`. That is the
+only way to catch wording dropped from one side when no number or defined term
+gives it away, and it means the whole document goes to the provider. Pairs with
+nothing to compare (the same text on both sides, or no words at all) are not
+sent; the report counts them as skipped.
+
+**Without `--llm`, no text leaves your machine.** With it, the flagged pairs go to
+the provider of the model you chose. Decide whether that is acceptable for the
+document in front of you.
+
+## Limits
+
+- DOCX only. No PDF, no scanned documents.
+- Headers, footers, footnotes and text boxes anchored outside the body are not read.
+- Tracked changes are read as if accepted; the report says when a file has them.
+- Word-based rules exist for English and Russian only.
+- BI011 is a wordlist heuristic and will produce false flags; it is `info` for that reason.
+- In two-file mode a short missing paragraph next to a long one can be absorbed
+  into its neighbour instead of being reported as missing.
+- No accuracy figures are published yet. A benchmark on public bilingual texts
+  with planted defects is the next milestone; until then, treat the tool as a
+  second pair of eyes, not as proof that a document is clean.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+python examples/build_examples.py   # rebuild the example documents
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

bilingual_lint-0.1.0/README.md

@@ -0,0 +1,182 @@
+# bilingual-lint
+
+[![CI](https://github.com/kirillsakhin/bilingual-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/kirillsakhin/bilingual-lint/actions/workflows/ci.yml)
+
+A linter for bilingual legal documents. Give it a contract in two languages and it
+reports where the two versions disagree: a different amount, a different date, a
+missing paragraph, a clause that makes English prevail on the left and Russian on
+the right. Deterministically, offline, the same way every time.
+
+## Why
+
+A bilingual contract is one deal written twice. Every number, date, deadline and
+party name has to be the same in both columns, and nobody enjoys checking that by
+eye on page 40.
+
+The obvious 2026 answer is "have an LLM compare the two versions". It helps with
+meaning, but it is the wrong tool for facts: it can pass a changed digit in one
+clause and flag the same thing in another, and two runs disagree with each other.
+
+So bilingual-lint does it the other way around. Rules check the facts: they catch
+the same defect every time, need no API key and send nothing anywhere. A model
+comes second, optionally, and by default only for the pairs the rules cannot
+settle.
+
+It does not judge translation style or quality. It checks what must be identical.
+
+## Install
+
+From a clone of this repository:
+
+```
+pip install -e .
+```
+
+Python 3.10 or newer. The optional model pass needs `pip install -e ".[llm]"`.
+
+## Quickstart
+
+A two-column bilingual DOCX:
+
+```
+bilingual-lint check contract.docx
+```
+
+A source file and its translation:
+
+```
+bilingual-lint check contract_en.docx contract_ru.docx
+```
+
+Against the bundled sample ([`examples/sample_en_ru.docx`](examples/sample_en_ru.docx),
+an invented contract with twelve planted defects), `--format md` gives, in part:
+
+```
+# bilingual-lint report
+
+- Mode: two-column, en / ru
+- Pairs checked: 13 (0 without a counterpart)
+- Findings: 12, 8 error, 3 warning, 1 info
+
+## BI002 · error · pair 4
+
+amounts differ — en only: 150,000 · ru only: 105 000
+
+## BI005 · error · pair 5
+
+duration day type differs — business against calendar days (en: 10, ru: 10)
+
+## BI010 · error · pair 9
+
+the two sides disagree on which language prevails — en side: en · ru side: ru
+
+## BI004 · error · pair 10
+
+digits and words disagree on the ru side — 3 against "двух"
+```
+
+The clean copy of the same contract ([`examples/clean_en_ru.docx`](examples/clean_en_ru.docx))
+produces no findings.
+
+Exit codes: `0` nothing at or above the threshold, `1` findings, `2` the input
+could not be read or the command was wrong. That makes it usable as a gate after
+a translation step.
+
+## Rules
+
+| Code | Checks | Default | Languages |
+|---|---|---|---|
+| BI000 | Notes about the file: tracked changes, comments, text outside the bilingual table | info | any |
+| BI001 | A number or percentage appears on one side only | error | any |
+| BI002 | A money amount or its currency differs, or the two sides name different currencies | error | any |
+| BI003 | A date or a time of day differs, or a date agrees only under one day/month reading (`02/03/2025`) | error | any |
+| BI004 | Digits and words disagree on the same side: `ten (15)` | error | en, ru |
+| BI005 | A time period differs in length, unit or day type (30 days vs 30 business days) | error | en, ru |
+| BI006 | A clause number or cross-reference differs | warning | any |
+| BI007 | A segment is missing, empty, untranslated or far off in length | error | any |
+| BI008 | A defined term or glossary term is rendered inconsistently | warning | en, ru |
+| BI009 | A registration number, IBAN, e-mail or URL differs | error | any |
+| BI010 | The prevailing-language clause is one-sided or contradicts itself | error | en, ru |
+| BI011 | Obligation, permission or negation wording differs (heuristic) | info | en, ru |
+
+"any" rules work for every language pair. The others need a wordlist and currently
+ship for English and Russian; for other pairs they are skipped, and the report
+says which.
+
+### How numbers are compared
+
+`1,000` is one thousand in English and exactly one in Russian. bilingual-lint does
+not guess: an ambiguous number keeps both readings and matches if either agrees
+with the other side. Set `strict_separators: true` to read each language by its
+own convention only.
+
+A number spelled out on one side (`two copies` / `2 экземпляра`) is not a defect.
+
+## Two separate files
+
+Paragraphs are paired deterministically: first at anchors (clause numbers and
+paragraphs with a unique set of digits), then by length between anchors. A
+paragraph with no partner becomes a finding. Each pair has a confidence value; for
+low-confidence pairs the report says "check the pairing first" and errors are
+shown as warnings.
+
+## Options
+
+```
+bilingual-lint check FILE [FILE]
+  --langs en,es         name the two languages (needed when they share a script)
+  --glossary terms.yaml term pairs to enforce:  - {en: Buyer, ru: Покупатель}
+  --config FILE         use this config file instead of ./.bilingual-lint.yaml
+  --format console|json|md
+  --output report.json
+  --fail-on error|warning
+  --rules BI001,BI010   run only these rules
+  --llm MODEL           optional model pass (see below)
+  --llm-gate            treat a model answer of "differs" as an error
+  --llm-scope SCOPE     flagged (default) or all
+bilingual-lint rules    list the rules
+bilingual-lint init     write a starter .bilingual-lint.yaml
+```
+
+## Optional model pass
+
+`--llm` sends only the pairs the rules flagged but could not settle (BI011 and
+low-confidence pairs) to a model through [litellm](https://github.com/BerriAI/litellm)
+and asks one question: do these two texts say the same thing? Answers are marked
+as model suggestions and do not change the exit code unless you pass `--llm-gate`.
+
+`--llm-scope all` sends every pair instead, up to `llm.max_pairs`. That is the
+only way to catch wording dropped from one side when no number or defined term
+gives it away, and it means the whole document goes to the provider. Pairs with
+nothing to compare (the same text on both sides, or no words at all) are not
+sent; the report counts them as skipped.
+
+**Without `--llm`, no text leaves your machine.** With it, the flagged pairs go to
+the provider of the model you chose. Decide whether that is acceptable for the
+document in front of you.
+
+## Limits
+
+- DOCX only. No PDF, no scanned documents.
+- Headers, footers, footnotes and text boxes anchored outside the body are not read.
+- Tracked changes are read as if accepted; the report says when a file has them.
+- Word-based rules exist for English and Russian only.
+- BI011 is a wordlist heuristic and will produce false flags; it is `info` for that reason.
+- In two-file mode a short missing paragraph next to a long one can be absorbed
+  into its neighbour instead of being reported as missing.
+- No accuracy figures are published yet. A benchmark on public bilingual texts
+  with planted defects is the next milestone; until then, treat the tool as a
+  second pair of eyes, not as proof that a document is clean.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+python examples/build_examples.py   # rebuild the example documents
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).