groundextract 0.1.2__tar.gz

groundextract-0.1.2/.dockerignore

@@ -0,0 +1,34 @@
+# The Dockerfile uses an allowlist of COPY paths, so this file is only a second
+# line of defence (and keeps the build context small). Anything private listed
+# here is also absent from the image because it was never named for copying.
+.git
+.github
+.venv
+venv
+env
+**/__pycache__
+*.py[cod]
+*.egg-info
+build
+dist
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+coverage.xml
+htmlcov
+sbom
+# Private / unmasked sources — mirrors .gitignore. Never let these into a layer.
+local
+submission
+docs
+CLAUDE.md
+bench/sample_pdf/real_*
+.env
+.env.*
+*.local
+*.local.*
+.idea
+.vscode
+.DS_Store
+Thumbs.db

groundextract-0.1.2/.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# Code owners for GroundExtract-KR.
+# Listed owners are requested for review automatically on matching pull requests.
+# Syntax: https://docs.github.com/articles/about-code-owners
+
+# Default owner for everything in the repository.
+*                           @sos37591-prog
+
+# Trust boundary: the deterministic gate. Changes here can turn a discarded
+# hallucination into a verified one, so they always need an owner review.
+/groundextract/grounding.py @sos37591-prog
+/groundextract/rules.py     @sos37591-prog
+/groundextract/gate.py      @sos37591-prog
+/groundextract/models.py    @sos37591-prog
+
+# Domain invariants and the labeled benchmark that measures them.
+/rules/                     @sos37591-prog
+/bench/                     @sos37591-prog
+/groundextract/bench.py     @sos37591-prog
+
+# Public interfaces and supply chain.
+/groundextract/mcp_server.py @sos37591-prog
+/pyproject.toml              @sos37591-prog
+/.github/                    @sos37591-prog
+/SECURITY.md                 @sos37591-prog

groundextract-0.1.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,108 @@
+name: Bug report
+description: A wrong verdict, a crash, or anything that does not behave as documented
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report.
+
+        **Before you file:** if a *wrong number came out `verified`* (a gate bypass /
+        false negative), please do not open a public issue — report it privately via
+        [Security Advisory](https://github.com/sos37591-prog/groundextract-kr/security/advisories/new)
+        so the fix can ship before the technique is public. See [SECURITY.md](https://github.com/sos37591-prog/groundextract-kr/blob/main/SECURITY.md).
+
+        **Never paste real documents.** No real tax invoices, financial statements,
+        registration numbers, or personal data — reproduce with synthetic text.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight
+      options:
+        - label: This is not a gate bypass (a hallucinated value coming out `verified`) — those go to Security Advisories
+          required: true
+        - label: My reproduction uses synthetic data only, with no real personal or corporate information
+          required: true
+        - label: I searched existing issues and did not find a duplicate
+          required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - grounding (verbatim matching)
+        - rules (arithmetic rule engine / rule packs)
+        - gate (verdicts, confidence, sibling discard)
+        - bench (NumHall-KR, golden set generator)
+        - mcp_server
+        - llm / adapters (Ollama, Docling)
+        - viewer
+        - packaging / CI / docs
+        - not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you observed, and what you expected instead.
+      placeholder: |
+        `total` came out verified=... but I expected ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: |
+        The smallest self-contained snippet that shows the problem — document text,
+        extracted values, and `doc_type`. Synthetic data only.
+      render: python
+      value: |
+        from groundextract import ExtractedValue, load_rule_pack, run_gate
+
+        doc = "공급가액 1,000,000원\n세액 100,000원\n합계금액 1,100,000원"
+        pack = load_rule_pack("rules/tax_invoice.yaml")
+        values = [
+            ExtractedValue("supply", "1,000,000원", 1_000_000, "공급가액 1,000,000원"),
+        ]
+        for f in run_gate(values, doc, pack):
+            print(f.field, f.verdict.value, f.confidence, [c.detail for c in f.failed_checks])
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Actual output
+      description: Full traceback, or the verdicts and failed checks you got.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: "`python -c \"import groundextract; print(groundextract.__version__)\"`, or the commit SHA."
+      placeholder: "0.1.0 (or commit 5aeff8b)"
+    validations:
+      required: true
+
+  - type: input
+    id: env
+    attributes:
+      label: Python and OS
+      description: "`python -V` and your operating system."
+      placeholder: "Python 3.11.9 / Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Optional context — related issues, why the input is realistic, a suggested fix.

groundextract-0.1.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a gate bypass (security)
+    url: https://github.com/sos37591-prog/groundextract-kr/security/advisories/new
+    about: A wrong number that comes out `verified` is a false negative and the most serious bug class here. Report it privately, not as a public issue.
+  - name: Contributing guide and good first issues
+    url: https://github.com/sos37591-prog/groundextract-kr/blob/main/CONTRIBUTING.md
+    about: Dev setup, how to add a rule pack for a new document type, PR rules, and a list of good first issues.
+  - name: How the gate works (README)
+    url: https://github.com/sos37591-prog/groundextract-kr/blob/main/README.md
+    about: Quick start, the two disjoint checks, MCP usage, honest benchmark numbers, and known limitations.

groundextract-0.1.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,90 @@
+name: Feature request
+description: Propose a change to how the gate works, or a new capability
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Requesting support for a **new document type**? Use the
+        [Rule pack request](https://github.com/sos37591-prog/groundextract-kr/issues/new?template=rule_pack_request.yml)
+        template instead — it asks the right questions.
+
+        Two things shape what gets merged here:
+
+        - **Recall is the product.** A change that lets a wrong number through to
+          `verified` will not be accepted, however much precision it buys.
+        - **One runtime dependency.** PyYAML is the whole runtime dependency list.
+          Anything heavier has to live in an optional extra and be imported lazily.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What goes wrong today? Concrete situations beat abstract wishes.
+      placeholder: |
+        When a statement is printed in 천원 units, every arithmetic rule fires a false
+        violation, so a clean document comes out fully discarded.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should happen instead? Sketch the API or behavior if you can.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - grounding (verbatim matching)
+        - rules (rule engine expressiveness)
+        - gate (verdicts, confidence, fault localization)
+        - bench (metrics, golden set)
+        - mcp_server (tools, schema)
+        - llm / adapters
+        - viewer
+        - packaging / CI / docs
+    validations:
+      required: true
+
+  - type: dropdown
+    id: impact
+    attributes:
+      label: Effect on the benchmark
+      description: Your best guess. We report precision and recall movements in the open.
+      options:
+        - No effect on verdicts (tooling, docs, performance)
+        - Improves precision, recall unchanged at 100%
+        - Improves recall coverage (catches a class of error we currently miss)
+        - Trades recall for something else (needs strong justification)
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Including "why not just do it outside the gate?"
+
+  - type: input
+    id: deps
+    attributes:
+      label: New dependencies required
+      description: Name them, or write "none". Runtime dependencies beyond PyYAML are very unlikely to be accepted.
+      placeholder: "none"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Participation
+      options:
+        - label: I am willing to open a pull request for this
+        - label: I would like to discuss the design first

groundextract-0.1.2/.github/ISSUE_TEMPLATE/rule_pack_request.yml

@@ -0,0 +1,105 @@
+name: Rule pack request (new document type)
+description: Ask for — or propose — arithmetic invariants for a document type we don't support yet
+title: "rules: <document type>"
+labels: ["rule-pack", "enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A rule pack is how this project grows. It is one YAML file listing the
+        arithmetic identities a document type must satisfy, plus three registrations
+        (rule pack → extractor field specs → MCP doc-type enum). See
+        [CONTRIBUTING.md](https://github.com/sos37591-prog/groundextract-kr/blob/main/CONTRIBUTING.md#adding-a-rule-pack-new-document-type).
+
+        You do **not** need to know Python to file this. Domain knowledge — *which
+        numbers on this form must add up to which other numbers* — is the part we
+        cannot look up, and it is what makes a rule pack worth having.
+
+        Currently supported: `tax_invoice`, `statement` (trial balance),
+        `balance_sheet`.
+
+        **Do not attach a real document.** Retype the layout with made-up numbers.
+
+  - type: input
+    id: doc-type
+    attributes:
+      label: Document type
+      description: Korean name and the proposed `doc_type` identifier (snake_case, ASCII).
+      placeholder: "급여명세서 (payslip) → payslip"
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why this document type
+      description: |
+        Who processes it, at what volume, and what goes wrong when a number is wrong?
+        A wrong number that someone eventually pays for is the strongest case.
+      placeholder: |
+        Payslips are re-keyed into payroll every month; a misread deduction is only
+        caught at year-end settlement, if at all.
+    validations:
+      required: true
+
+  - type: textarea
+    id: fields
+    attributes:
+      label: Fields to extract
+      description: >-
+        One per line as `field_name: 한국어 라벨 (English gloss)`. Field names are
+        ASCII snake_case and are what the rules reference.
+      render: text
+      value: |
+        gross_pay: 지급총액 (gross pay)
+        total_deductions: 공제총액 (total deductions)
+        net_pay: 실지급액 (net pay)
+
+  - type: textarea
+    id: invariants
+    attributes:
+      label: Arithmetic invariants
+      description: |
+        The identities that must hold. Plain arithmetic is fine — someone can translate
+        it into YAML. Note any legal rounding tolerance (`tol`), since Korean forms
+        often round to the won.
+      render: text
+      value: |
+        net_pay = gross_pay - total_deductions        (tol 1 KRW)
+        gross_pay = sum of allowance line items       (tol 1 KRW)
+
+  - type: textarea
+    id: sample
+    attributes:
+      label: Synthetic sample document
+      description: |
+        Retype the layout as plain text with **made-up** numbers that satisfy the
+        invariants above. This becomes the test fixture — it is the single most useful
+        thing you can attach.
+      render: text
+      placeholder: |
+        급여명세서
+        지급총액   3,500,000원
+        공제총액     420,000원
+        실지급액   3,080,000원
+    validations:
+      required: true
+
+  - type: textarea
+    id: pitfalls
+    attributes:
+      label: Formatting pitfalls
+      description: |
+        Negative sign conventions (△, parentheses), unit headers (단위: 천원), full-width
+        digits, values split across columns, subtotals that legitimately do not add up.
+      placeholder: "Amounts are printed in 천원 units; deductions use △ for negatives."
+
+  - type: checkboxes
+    id: participation
+    attributes:
+      label: Participation
+      options:
+        - label: I can write the YAML rule pack and the test myself
+        - label: I can review a rule pack someone else writes, as a domain expert
+        - label: I confirm the sample above is synthetic and contains no real personal or corporate data
+          required: true

groundextract-0.1.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,69 @@
+<!--
+Thanks for contributing to GroundExtract-KR.
+One concern per PR. Delete sections that genuinely do not apply.
+-->
+
+## What and why
+
+<!-- What does this change, and what problem does it solve? Link the issue: Fixes #123 -->
+
+## Type of change
+
+- [ ] Bug fix (a wrong verdict, a crash, or documented behavior that wasn't true)
+- [ ] New rule pack / document type
+- [ ] New feature or behavior change
+- [ ] Docs only
+- [ ] Build, CI, or packaging
+
+## Verification
+
+```text
+python -m pytest -q      →
+python -m ruff check .   →
+```
+
+<!-- Paste the actual result lines. Both must be green. -->
+
+- [ ] `python -m pytest -q` passes
+- [ ] `python -m ruff check .` passes
+- [ ] New behavior has a test; a bug fix has a regression test that fails without the fix
+
+## Benchmark impact
+
+Run `python -m groundextract.bench` if this touches `grounding.py`, `rules.py`,
+`gate.py`, the rule packs, or the golden set. Paste before/after — we track these
+numbers in the open, including when they get worse.
+
+```text
+before:  NHR 19.9% -> 0.0% | recall 100.0% | precision 35.8% | grounded-accuracy 64.4%
+after:
+```
+
+- [ ] No benchmark change (this PR cannot affect verdicts)
+- [ ] Numbers changed and are pasted above, with `CHANGELOG.md` updated
+- [ ] **`Auto-Discard Recall` is still 100.0%** — if not, explain below why letting a
+      labeled bad value through is acceptable
+
+## Rule pack PRs only
+
+- [ ] `rules/<doc_type>.yaml` added (`doc_type` matches the filename stem)
+- [ ] `FIELD_SPECS["<doc_type>"]` added in `groundextract/llm/openweight.py`
+- [ ] `<doc_type>` added to `_DOC_TYPE_SCHEMA["enum"]` in `groundextract/mcp_server.py`
+- [ ] Test covering one clean document (all `verified`) and one violating document
+      (`discarded`)
+
+## Project invariants
+
+- [ ] No new **runtime** dependency (PyYAML is the whole list; heavier things go in an
+      optional extra and are imported lazily)
+- [ ] The gate path stays deterministic and offline — no randomness, no wall-clock
+      dependence, no network in `grounding.py` / `rules.py` / `gate.py`
+- [ ] No real documents, personal data, registration numbers, or company-identifying
+      information anywhere in the diff — fixtures are synthetic
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]` for user-visible changes
+- [ ] Docs updated if behavior or commands changed (`README.md` **and**
+      `README.ko.md` stay in sync)
+
+## Notes for reviewers
+
+<!-- Trade-offs you made, things you are unsure about, what to look at first. -->

groundextract-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# A moved tag would silently change what runs here, so third-party actions are
+# pinned to commit SHAs (the trailing comment records the human-readable tag).
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Test (pytest + coverage)
+        run: pytest -q --cov=groundextract --cov-report=term-missing
+
+  sbom:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: test
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package + SBOM tooling
+        run: |
+          python -m pip install --upgrade pip
+          # Install the extras a user can actually pull in, not just the runtime
+          # dep — the licence question lives in the optional surface. `docling`
+          # is left out deliberately: it drags in a multi-GB ML stack that would
+          # dominate this job, and it is scanned separately when it changes.
+          python -m pip install -e ".[fixture]"
+          python -m pip install pip-licenses cyclonedx-bom
+
+      - name: License allowlist (deny GPL/AGPL copyleft)
+        run: |
+          # Fail the build if a strong-copyleft license sneaks into deps.
+          pip-licenses --format=markdown --output-file=licenses.md
+          cat licenses.md
+          if pip-licenses --format=csv | grep -Ei 'GPL|AGPL' | grep -vi 'LGPL'; then
+            echo "::error::Disallowed copyleft license found in dependencies"; exit 1
+          fi
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          mkdir -p sbom
+          cyclonedx-py environment -o sbom/bom.cdx.json
+          echo "SBOM generated:"; head -c 400 sbom/bom.cdx.json; echo
+
+      - name: Upload SBOM artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: sbom
+          path: |
+            sbom/bom.cdx.json
+            licenses.md

groundextract-0.1.2/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# SBOM (CI-generated; regenerated each run)
+sbom/*.json
+
+# Notebooks / JS tooling (viewer is build-step-free today; keep it that way)
+.ipynb_checkpoints/
+node_modules/
+.tox/
+.nox/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Secrets / local env.
+# Patterns, not filenames: every rule below exists because *this* repository
+# handles real 세무·재무 documents, and a denylist of known names only protects
+# against the mistakes already made. `.env` alone missed `.env.production`;
+# `*.local` alone missed `config.local.json`.
+.env
+.env.*
+.envrc
+*.local
+*.local.*
+*.key
+*.pem
+*.pfx
+*.p12
+*token*
+credentials.json
+service-account.json
+
+# Runtime artifacts
+*.log
+*.sqlite
+*.db
+
+# Contest submission artifacts (개인정보/PII 포함 — keep out of public repo)
+submission/
+
+# Internal planning notes (직원 실명·IP·리소스 리스크 — 로컬 보관, 공개 저장소 제외)
+docs/
+
+# Local agent notes: contest schedule, submission paths, unreleased risks.
+# Do not rely on a global gitignore for this — it must be excluded on any machine.
+CLAUDE.md
+
+# Unmasked real sources (PII / 실제 기업 재무·세무 원본) — never commit.
+# Prefixed by convention rather than named one by one: the next real document
+# someone drops in must be excluded before it exists, not after.
+bench/sample_pdf/real_*
+local/