iso-tollgate 0.1.0__tar.gz

iso_tollgate-0.1.0/.github/actions/validate/action.yml

@@ -0,0 +1,54 @@
+name: "Tollgate ISO 20022 Validator"
+description: >
+  Validates pacs.008 ISO 20022 payment files in CI, catching the gap
+  between schema-valid and network-acceptable before they're merged or
+  deployed. Fails the build on any error-severity finding.
+author: "Arun"
+branding:
+  icon: "shield"
+  color: "blue"
+
+inputs:
+  path:
+    description: >
+      Glob pattern or path to the pacs.008 XML file(s) to validate.
+      Supports a single file or a glob (e.g. "payments/**/*.xml").
+    required: true
+  fail-on-warning:
+    description: >
+      If "true", treat warning-severity findings (e.g. truncation
+      heuristics) as build failures too, not just errors. Default
+      "false" -- warnings are heuristic signals, not certain
+      failures, per Tollgate's own severity design; most CI pipelines
+      should not hard-fail on a heuristic.
+    required: false
+    default: "false"
+  python-version:
+    description: "Python version to set up for running Tollgate."
+    required: false
+    default: "3.11"
+
+outputs:
+  has-errors:
+    description: "true if any error-severity violation was found across all checked files."
+    value: ${{ steps.run-tollgate.outputs.has-errors }}
+  results-json:
+    description: "Combined JSON results for all checked files."
+    value: ${{ steps.run-tollgate.outputs.results-json }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install Tollgate
+      shell: bash
+      run: pip install iso-tollgate
+
+    - name: Run Tollgate against matched files
+      id: run-tollgate
+      shell: bash
+      run: python3 "${{ github.action_path }}/scripts/run_validation.py" "${{ inputs.path }}" "${{ inputs.fail-on-warning }}"

iso_tollgate-0.1.0/.github/actions/validate/scripts/run_validation.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Helper script for the Tollgate GitHub Action.
+
+Pulled out of action.yml deliberately: embedding multi-line Python
+inside a bash heredoc inside a YAML block scalar is fragile and hard
+to read -- a real YAML syntax error was found in an earlier draft of
+action.yml caused by exactly this nesting. A standalone script is
+easier to test, easier to read, and avoids YAML/bash/Python
+quoting interactions entirely.
+
+Usage:
+    python3 run_validation.py "<glob-pattern>" <fail-on-warning: true|false>
+
+Exits 1 if any file has an error-severity violation (or a warning,
+if fail-on-warning is true). Prints the combined results as JSON to
+stdout, and writes outputs to $GITHUB_OUTPUT if that env var is set.
+"""
+
+import glob
+import json
+import os
+import subprocess
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("Usage: run_validation.py <glob-pattern> <fail-on-warning>", file=sys.stderr)
+        return 1
+
+    pattern, fail_on_warning_str = sys.argv[1], sys.argv[2]
+    fail_on_warning = fail_on_warning_str.strip().lower() == "true"
+
+    files = sorted(glob.glob(pattern, recursive=True))
+    if not files:
+        print(f"::error::No files matched path pattern: {pattern}")
+        return 1
+
+    combined_results = []
+    overall_has_errors = False
+
+    for file_path in files:
+        print(f"Validating {file_path}...")
+        proc = subprocess.run(
+            ["tollgate", "validate", file_path, "--json"],
+            capture_output=True,
+            text=True,
+        )
+
+        try:
+            entry = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            print(f"::error file={file_path}::Tollgate produced unparseable output: {proc.stdout!r}")
+            overall_has_errors = True
+            continue
+
+        entry["file"] = file_path
+        combined_results.append(entry)
+
+        if entry.get("has_errors"):
+            print(f"::error file={file_path}::Tollgate found error-severity violation(s)")
+            overall_has_errors = True
+
+        if entry.get("has_warnings") and fail_on_warning:
+            print(f"::error file={file_path}::Tollgate found warning-severity finding(s) (fail-on-warning enabled)")
+            overall_has_errors = True
+
+    results_json = json.dumps(combined_results)
+
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output:
+        with open(github_output, "a") as f:
+            f.write(f"has-errors={'true' if overall_has_errors else 'false'}\n")
+            f.write("results-json<<TOLLGATE_EOF\n")
+            f.write(results_json + "\n")
+            f.write("TOLLGATE_EOF\n")
+
+    print(results_json)
+    return 1 if overall_has_errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

iso_tollgate-0.1.0/.github/workflows/example-consumer-usage.yml

@@ -0,0 +1,26 @@
+name: Validate payment files
+
+# Example workflow for repos that GENERATE or transform pacs.008 files
+# and want to catch problems before merge/deploy -- not Tollgate's own
+# CI (Tollgate's own tests run via pytest directly, see below).
+#
+# Copy this file into .github/workflows/ in YOUR repo, adjust the
+# `path` glob to match where your pacs.008 files live, and remove the
+# parts referencing this being an example.
+
+on:
+  pull_request:
+    paths:
+      - "payments/**/*.xml"  # adjust to your repo's actual file locations
+
+jobs:
+  validate-payments:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate pacs.008 files with Tollgate
+        uses: iso-tollgate/tollgate/.github/actions/validate@main
+        with:
+          path: "payments/**/*.xml"
+          fail-on-warning: "false"

iso_tollgate-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Tollgate with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        # No ANTHROPIC_API_KEY in CI -- the three live-API tests in
+        # test_explainer.py skip automatically without one (see their
+        # skipif markers). This means CI verifies every deterministic
+        # rule, the generator, the eval harness's scoring logic, and
+        # the CLI/library API -- everything except the one part that
+        # genuinely requires a paid, live model call. That's a
+        # deliberate, documented gap, not an oversight.
+        run: pytest tests/ -v

iso_tollgate-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+.pytest_cache/
+.coverage
+htmlcov/
+
+.env
+*.env.local
+
+.vscode/
+.idea/
+*.swp
+
+tests/evals/eval_results/*.json
+!tests/evals/eval_results/.gitkeep
+
+.DS_Store

iso_tollgate-0.1.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+Read this before doing any work in this repo. It encodes hard-won lessons from building Tollgate, not aspirational rules — every item here exists because skipping it caused a real, found bug.
+
+## What this project is
+
+A pre-submission safety gate for ISO 20022 pacs.008 payment messages. Catches messages that pass XSD schema validation but would still be rejected (or silently misinterpreted) by a real payment network. v1 scope is pacs.008.001.08 only — do not add a second message type without an explicit decision to do so.
+
+## The core discipline: research and verify before writing code
+
+Every validation rule in this project traces to a primary or clearly-identified source — see `docs/SOURCES.md`. Before adding a new rule:
+
+1. Research the gotcha properly. Don't guess at field names, currency lists, or thresholds — find a real source (regulator documentation, the standard's own publisher, official schema definitions).
+2. Verify the claim against the actual vendored XSD (`src/tollgate/schemas/pacs.008.001.08.xsd`) before writing detection logic. Multiple sessions found that secondary sources (blog posts, even careful research notes) contained claims that didn't hold up against the real schema — the FAIM-tag claim in `mandatory_gap_rule.py`'s history is the canonical example; it was replaced with a fully-verified UETR finding instead of shipping an unconfirmed citation.
+3. If a primary source can't be directly verified (e.g. blocked by network access, paywalled), say so explicitly in the code and in `SOURCES.md` rather than asserting confidence you don't have. See the currency_rule.py honest-limitation note for the pattern.
+4. Write the rule, then **test it against deliberately adversarial input before trusting it** — not just the happy path. Every one of this project's six rules had at least one real bug found this way:
+   - `charset_rule.py`: the original character-set regex was missing a plain space character, meaning it would have flagged ordinary text like "Tomas Becker" as a violation.
+   - `truncation_rule.py`: a naive version would have flagged any field at exactly 35/70 chars, including fields whose own legitimate maximum IS 35/70 — caught by reasoning through the design before writing code, not by a failing test.
+   - `address_rule.py`: agent roles (DbtrAgt, etc.) nest their address one level deeper than party roles — a naive `role_tag/PstlAdr` search would have silently missed every agent-role violation.
+   - `currency_rule.py`: testing it against the generator's own clean baseline output surfaced a real, pre-existing generator bug (JPY amounts always formatted with 2 decimal places, when JPY supports 0) that had been silently wrong since the project's first session.
+   - `xsd_validator.py`: the exception handler let a raw Python stack trace reach the user for non-XML input, and separately, leaked a local filesystem path into an error message for a different malformed-input case.
+
+If you find yourself trusting a docstring's claim ("X is handled," "Y is verified") without running code to confirm it — stop and verify first. This has been wrong multiple times in this project's history.
+
+## Severity discipline
+
+- `severity="error"`: a deterministic, schema-level-confident violation (XSD failure, character set violation, address structure violation, missing network-mandatory field).
+- `severity="warning"`: a heuristic signal, not a certainty (truncation suspicion, currency decimal mismatch where the failure mode is "might be silently misinterpreted" rather than "will be rejected"). Never upgrade a warning to an error just to make output look more decisive — the uncertainty is real and the explanation layer needs to communicate it honestly.
+
+## The deterministic/AI split — do not blur this
+
+Validation logic (does X violate a rule) is deterministic Python, never an LLM call. The AI layer (`explain/explainer.py`) only narrates an already-detected violation in plain English — it never decides whether something is wrong. `--explain` is opt-in (flag), not default, because it's a real billed API call; the five-then-six deterministic checks are free and local.
+
+**Data handling, non-negotiable:** `Violation.raw_value` (which can contain a real name, address, or other sensitive field content) must never be sent to the Anthropic API. It's fine in local output (CLI report, JSON, markdown) — the restriction is specifically about the network boundary. See `docs/SOURCES.md#data-handling-ai-boundary` and `tests/test_data_handling.py` for the enforced/tested version of this rule. If you're touching `explain/prompts.py` or `explain/explainer.py`, re-read this before changing what gets sent.
+
+## Adding a new validation rule: the checklist
+
+1. Research + cite in `docs/SOURCES.md` first.
+2. Verify against the real vendored XSD before writing detection code.
+3. Add a `RuleId` enum value in `validation/models.py`.
+4. Write the rule module (`validation/<name>_rule.py`), following the existing pattern: a `_local_path()` helper for readable field paths, walk-by-structural-property (attribute presence, tag name, or tree depth) rather than assuming a fixed shape until you've checked the schema.
+5. Write a real injector in `generator/synthetic_fixtures.py`'s `_INJECTORS` dict — every `RuleId` needs one, or `tollgate generate` and the eval harness will break for that rule (this has happened — adding a RuleId without wiring it into every consumer is a real, recurring integration gap).
+6. Wire the new check into `api.py`'s `_run_all_checks()` — this is the actual source of truth the CLI and library both call into.
+7. Wire it into the eval harness (`tests/evals/eval_harness.py`): `RULE_ID_SYNONYMS`, `DETECTOR_FOR_RULE`, `_run_detector_for_rule`.
+8. Write tests proving: (a) a clean baseline has zero violations across several seeds, (b) the showcase case (schema-valid, rule-invalid) with an actual XSD validation run alongside it to prove the gap, (c) no false positive on a legitimate edge case that resembles the violation but isn't one.
+9. Run the FULL test suite, not just the new file — adding a RuleId touches shared enums and dicts that other tests assert against.
+
+## Testing conventions
+
+- Always `cp -r source/. dest/` (trailing `/.`) when copying the repo for a clean test environment — `cp -r source/* dest/` silently skips dotfiles/dotdirs (`.github/`, `.gitignore`), which has caused confusion mid-session before.
+- `pip install -e ".[dev]"` then `pytest tests/` for the full suite.
+- `tests/test_explainer.py` has 3 tests gated by `ANTHROPIC_API_KEY` — they skip cleanly without one. Don't treat a skip as a failure; don't treat a skip as "verified" either. As of 2026-06-21 these have been live-verified once on a real machine with a real key — if you change `explainer.py` or `prompts.py`, re-run them for real before trusting the change.
+- On macOS, `pip`/`pytest` may need `python3 -m pip` / `python3 -m pytest`, and a venv is required if you hit "externally-managed-environment" (`python3 -m venv .venv && source .venv/bin/activate`). See `TROUBLESHOOTING.md`.
+
+## Repo layout
+
+- `github.com/iso-tollgate/tollgate` — main repo
+- `github.com/iso-tollgate/homebrew-tollgate` — Homebrew tap, scaffolded but not live (needs a real PyPI release with sdist + sha256 first)
+- Not yet published to PyPI as of this writing — see `docs/SOURCES.md` and session history for the dry-run build verification already done (sdist/wheel build correctly, schema file is bundled, `twine check` passes).
+
+## Don't
+
+- Don't add a feature "because it'd be nice" without checking it against the original brief's scope discipline (one message type, pre-submission sanity check, not a SWIFT-certified compliance tool).
+- Don't claim a rule is sourced without an actual citation in `docs/SOURCES.md`.
+- Don't trust that "all tests pass" after adding a RuleId without running the FULL suite — shared mappings break silently otherwise.
+- Don't write AI-sounding filler in README/docs. Real examples, real verified command output, no invented case studies.

iso_tollgate-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Tollgate's credibility rests on one thing: every rule traces to a real source, and every claim has been tested, not assumed. That's not a style preference — it's the whole point of the project. If you're adding a rule, a fix, or a feature, the norms below exist to keep that true.
+
+## The non-negotiable: source every rule
+
+If you're adding a new validation rule, it needs a citation in [`docs/SOURCES.md`](docs/SOURCES.md) before it ships — a primary source where possible (a regulator's own documentation, the official XSD, SWIFT's own specifications), or a clearly-identified secondary source with the gap stated honestly if a primary source isn't available.
+
+Don't add a rule based on something you half-remember or a claim you found in someone else's blog post without checking it yourself. This project has already found and corrected one rule that was built on an unverified secondhand citation (see `docs/SOURCES.md`'s `fedwire-faim-comparison` entry, kept visible specifically as an example of what *not* to ship) — that correction is part of the project's history on purpose, so the bar stays visible.
+
+## Test against real generated fixtures, not assumptions
+
+Every rule module has a corresponding test file that runs the rule against output from `generator/synthetic_fixtures.py` — not hand-written XML strings, not mocked data. If you're fixing a bug, write a regression test that would have caught it, using the same generator.
+
+This project has a real track record of bugs found specifically by testing rather than trusting:
+- A character-set rule that flagged completely normal text as a violation because the allowed-character list was missing a plain space
+- An address rule that assumed every party type stored its address at the same nesting depth, which would have silently missed every bank-address violation
+- A truncation rule that would have false-positived on values legitimately using a field's own real maximum length — caught by reasoning through the design before any code was written
+- An AI explanation layer that sent a real person's name to a third-party API, found by checking what data actually left the machine
+
+None of these were caught by code review or by the implementation "looking right." They were caught by deliberately running the code against real or adversarial input and checking the actual output. Do the same for anything you add.
+
+## The deterministic-check / AI-narration split is load-bearing
+
+Validation logic (does this violate a rule) must be deterministic code — no AI in `validation/*.py`. AI only narrates an *already-detected* violation, in `explain/explainer.py`, via a single API call with no tool use or agentic loop. This split exists so the eval harness can score explanations against known ground truth, and so nothing in this tool can be second-guessed as "is this a real finding or a model's guess." If you're tempted to use AI to *detect* something rather than explain something already detected, that's the wrong layer — open an issue and discuss first.
+
+## Data handling boundary
+
+Never send `Violation.raw_value` (or any field content) across the network to a third-party API by default. See `docs/SOURCES.md`'s `data-handling-ai-boundary` section and `tests/test_data_handling.py` for what this means in practice and how it's verified — that test mocks the API client and inspects the actual payload sent, which is the standard to match for any change touching the explain layer.
+
+## Before opening a PR
+
+- Run the full test suite: `pytest tests/`. It should pass without an `ANTHROPIC_API_KEY` set — the 3 live-API tests in `test_explainer.py` skip automatically without one; that's expected, not a failure.
+- If you're touching anything in `explain/`, also run with a real `ANTHROPIC_API_KEY` set at least once before merging, since that's the one part of the codebase that can't be fully verified by the deterministic suite alone.
+- If you're adding a rule, confirm it's cited in `docs/SOURCES.md` and that your test file exercises both the violation case and a clean-message case (no false positives).
+
+## Scope
+
+v1 covers exactly one message type: pacs.008.001.08. If you want to add a second message type or extend beyond what's documented in [`docs/why.md`](docs/why.md)'s "what it explicitly does not do" section, raise it as an issue first — that's a scope decision, not just a code change.

iso_tollgate-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

iso_tollgate-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: iso-tollgate
+Version: 0.1.0
+Summary: Pre-submission safety gate for ISO 20022 payment messages. Catches the gap between schema-valid and network-acceptable before you submit.
+Project-URL: Homepage, https://github.com/iso-tollgate/tollgate
+Project-URL: Repository, https://github.com/iso-tollgate/tollgate
+Project-URL: Issues, https://github.com/iso-tollgate/tollgate/issues
+Project-URL: Documentation, https://github.com/iso-tollgate/tollgate/blob/main/docs/usage.md
+Author: Arun
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: fedwire,iso20022,pacs.008,payments,swift,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: lxml>=5.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Requires-Dist: xmlschema>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tollgate
+
+**Catches ISO 20022 payment messages that pass schema validation and still get rejected by the network — before you find out the hard way.**
+
+[![Tests](https://img.shields.io/badge/tests-163%20passing-brightgreen)](#status) [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
+A pacs.008 payment message can be 100% valid XML, pass every XSD check, and still bounce off a real clearing network — because some of the rules that matter live outside the schema entirely. Tollgate catches that gap.
+
+## Quickstart
+
+```bash
+git clone https://github.com/iso-tollgate/tollgate.git
+cd tollgate
+pip install -e .
+```
+
+```bash
+tollgate validate payment.xml
+```
+
+```
+1 error(s), 0 warning(s) found in payment.xml:
+
+ERROR charset_violation -- FIToFICstmrCdtTrf/CdtTrfTxInf/Dbtr/Nm
+  Contains character(s) outside SWIFT's character set X: 'ü'. This is
+  schema-valid XML (ISO 20022 permits full Unicode) but SWIFT's network
+  layer restricts allowed characters independently of the schema --
+  this will not be caught by XSD validation alone.
+```
+
+That's a real example, not a mockup — every command in this README was actually run before being written down. No payment file handy? Generate one:
+
+```bash
+tollgate generate --count 1 --rule-id charset_violation --output-dir /tmp/fixtures
+tollgate validate /tmp/fixtures/charset_violation_0.xml
+```
+
+→ **[Full usage guide](docs/usage.md)** — every command, every flag, the Python library API, batch directory checking, the GitHub Action
+→ **[Why this exists](docs/why.md)** — the dated deadline behind it, the AI design philosophy, what was found and fixed during development
+→ **[Sources](docs/SOURCES.md)** — every rule traced to a citation
+
+## What it checks
+
+One message type in v1: **pacs.008.001.08**, the FI-to-FI customer credit transfer used across Fedwire, CHIPS, and SWIFT CBPR+.
+
+| Check | Catches |
+|---|---|
+| Schema validity | Standard XSD structural validation. The floor everything else stands on. |
+| SWIFT character set | A character outside SWIFT's allowed set — schema-valid, network-invalid. |
+| Address structure | Free-format addresses used where structure is required, or line counts the schema allows but a network's guidelines don't. |
+| Truncation signals | A value landing at exactly 35 or 70 characters — old legacy line limits — in a field with a much higher modern limit. Reported as a warning, not a certainty. |
+| Network-mandatory gaps | Fields the schema marks optional that a real network requires in practice (e.g. UETR for Fedwire). |
+
+Every rule traces to a primary source — see [`docs/SOURCES.md`](docs/SOURCES.md). No rule ships without one.
+
+## Not a compliance tool
+
+Tollgate is a developer-facing sanity check, not a replacement for SWIFT certification or MyStandards testing. It covers one message type, checks structure and format (not business logic like BIC reachability), and is explicit in [`docs/why.md`](docs/why.md) about every limitation found during development. If it can't catch something, the docs say so.
+
+## Three ways to use it
+
+| | |
+|---|---|
+| **CLI** | `tollgate validate payment.xml` · `tollgate validate-dir payments/` |
+| **Python library** | `from tollgate import check_message, check_file, check_directory` |
+| **CI** | `uses: iso-tollgate/tollgate/.github/actions/validate@main` |
+
+Details and examples for all three: [`docs/usage.md`](docs/usage.md).
+
+## Status
+
+166 tests passing (163 deterministic/local + 3 live API tests, all confirmed passing against the real Anthropic API), 0 skipped when an `ANTHROPIC_API_KEY` is set — and 163 passing with the 3 API tests skipping cleanly when it isn't, so the full deterministic suite (every validation rule, the generator, the eval harness, both APIs) needs zero API key to verify.
+
+`--explain` has been live-tested against the real model: it correctly names the violated field and cause, and correctly hedges on warning-severity (heuristic) findings rather than asserting them as certain failures — verified, not assumed.
+
+Not yet on PyPI or Homebrew — clone-and-install is the path for now. A Homebrew tap is scaffolded in [`homebrew-tollgate/`](https://github.com/iso-tollgate/homebrew-tollgate) for once a tagged release exists.
+
+## License
+
+Apache 2.0. See [`LICENSE`](LICENSE).