awtax 0.1.0__tar.gz

awtax-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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.

awtax-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: awtax
+Version: 0.1.0
+Summary: Turn any tax PDF -- returns, W-2, 1099, statements, even scans -- into structured data you can check.
+Author: Aitherium
+License: MIT
+Project-URL: Homepage, https://github.com/Aitherium/awtax
+Keywords: tax,pdf,extraction,ocr,1040,w-2,aither-world
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymupdf>=1.24
+Provides-Extra: vision
+Requires-Dist: awvision>=0.1; extra == "vision"
+Provides-Extra: ocr
+Dynamic: license-file
+
+# awtax
+
+**Turn any tax PDF — returns, W-2, 1099, statements, even scans — into structured data you can check.**
+
+Your own tax data gets locked inside one vendor's encrypted format, and a filed return or a
+mailed W-2 is a PDF nobody's code can read — half of them are scans with no text layer at all.
+Getting your own numbers back out means re-typing them or re-buying the app that sealed them.
+
+`awtax` reads the document. It does **not** give tax advice — it hands you every figure, the page
+it came from, and whether the arithmetic checks out.
+
+```bash
+git clone https://github.com/Aitherium/awtax && cd awtax && pip install -e .
+awtax path/to/return.pdf          # -> structured JSON on stdout
+```
+
+> Not on PyPI yet, so `pip install awtax` does **not** work — that name resolves
+> to nothing today. Install from the clone until a release exists.
+
+## What you get
+
+- **Provider-neutral schema** — every figure carries its `page`, its `source` (`text` / `vision` /
+  `ocr`), and a `confidence`. A tax number with no provenance is a number nobody can check.
+- **Arithmetic self-checks** — `taxable = AGI − deduction`, `refund = payments − tax`. A figure that
+  fails the identity it is defined by is **flagged**, not trusted. The CLI exits `3` when anything
+  needs review — silence is not a pass.
+- **Scans handled** — a page with no text layer routes to [`awvision`](../awvision) (a vision model
+  reads the form fields *structurally*, far better than raw OCR), with a local `tesseract` fallback
+  for fully-offline use. If neither is available you get an explicit `needs_review` — **never a
+  silent zero.** (That silent-zero-on-a-scan failure is exactly what this fixes.)
+
+## Scan backends (optional)
+
+| backend | how | when |
+|---|---|---|
+| **awvision** (preferred) | `pip install -e '.[vision]'` from the clone, pass `--endpoint` | a vision model extracts fields as JSON |
+| **tesseract** (offline fallback) | install the `tesseract` system binary | no network / no vision endpoint |
+| neither | — | pages return `needs_review` with a reason |
+
+## Where awtax stops, and the premium packs begin
+
+awtax is the open-source **extraction core**. Preparation, deduction discovery, worksheets, ledgers
+and CPA-ready output are the premium **TaxDesk** agent / skill / tool packs that compose on top via
+`awpack` / `awskills`. awtax reads; the packs advise.
+
+## Status
+
+`0.1.0` — reads native-text 1040 pages and scanned W-2s, self-validates, degrades gracefully.
+Known next work: 1040-vs-1040-X disambiguation on multi-form packets, richer 1099 coverage,
+and native-text W-2 parsing. MIT licensed.

awtax-0.1.0/README.md

@@ -0,0 +1,50 @@
+# awtax
+
+**Turn any tax PDF — returns, W-2, 1099, statements, even scans — into structured data you can check.**
+
+Your own tax data gets locked inside one vendor's encrypted format, and a filed return or a
+mailed W-2 is a PDF nobody's code can read — half of them are scans with no text layer at all.
+Getting your own numbers back out means re-typing them or re-buying the app that sealed them.
+
+`awtax` reads the document. It does **not** give tax advice — it hands you every figure, the page
+it came from, and whether the arithmetic checks out.
+
+```bash
+git clone https://github.com/Aitherium/awtax && cd awtax && pip install -e .
+awtax path/to/return.pdf          # -> structured JSON on stdout
+```
+
+> Not on PyPI yet, so `pip install awtax` does **not** work — that name resolves
+> to nothing today. Install from the clone until a release exists.
+
+## What you get
+
+- **Provider-neutral schema** — every figure carries its `page`, its `source` (`text` / `vision` /
+  `ocr`), and a `confidence`. A tax number with no provenance is a number nobody can check.
+- **Arithmetic self-checks** — `taxable = AGI − deduction`, `refund = payments − tax`. A figure that
+  fails the identity it is defined by is **flagged**, not trusted. The CLI exits `3` when anything
+  needs review — silence is not a pass.
+- **Scans handled** — a page with no text layer routes to [`awvision`](../awvision) (a vision model
+  reads the form fields *structurally*, far better than raw OCR), with a local `tesseract` fallback
+  for fully-offline use. If neither is available you get an explicit `needs_review` — **never a
+  silent zero.** (That silent-zero-on-a-scan failure is exactly what this fixes.)
+
+## Scan backends (optional)
+
+| backend | how | when |
+|---|---|---|
+| **awvision** (preferred) | `pip install -e '.[vision]'` from the clone, pass `--endpoint` | a vision model extracts fields as JSON |
+| **tesseract** (offline fallback) | install the `tesseract` system binary | no network / no vision endpoint |
+| neither | — | pages return `needs_review` with a reason |
+
+## Where awtax stops, and the premium packs begin
+
+awtax is the open-source **extraction core**. Preparation, deduction discovery, worksheets, ledgers
+and CPA-ready output are the premium **TaxDesk** agent / skill / tool packs that compose on top via
+`awpack` / `awskills`. awtax reads; the packs advise.
+
+## Status
+
+`0.1.0` — reads native-text 1040 pages and scanned W-2s, self-validates, degrades gracefully.
+Known next work: 1040-vs-1040-X disambiguation on multi-form packets, richer 1099 coverage,
+and native-text W-2 parsing. MIT licensed.

awtax-0.1.0/awtax/__init__.py

@@ -0,0 +1,15 @@
+"""awtax -- turn any tax PDF into structured data you can check.
+
+Open-source extraction core. Point it at a tax PDF (a filed return, a W-2, a 1099,
+a statement -- scans included) and get every figure out as a provider-neutral schema
+with per-figure provenance and arithmetic self-checks. It reads a document; it does
+not give tax advice. Preparation, deduction discovery, worksheets and filing are the
+premium TaxDesk packs that compose on top.
+"""
+from __future__ import annotations
+
+from .extract import extract
+from .schema import Document, Extraction, Figure
+
+__all__ = ["extract", "Extraction", "Document", "Figure", "__version__"]
+__version__ = "0.1.0"

awtax-0.1.0/awtax/cli.py

@@ -0,0 +1,51 @@
+"""awtax command-line: `awtax path/to/return.pdf` -> JSON on stdout."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .extract import extract
+
+
+def main(argv: list[str] | None = None) -> int:
+    # GENERATED doctor intercept (gen_aw_doctor.py) -- do not edit
+    _dv = locals().get("argv")
+    if (_dv if _dv is not None else __import__("sys").argv[1:])[:1] == ["doctor"]:
+        from ._doctor import report
+        return report()
+    # GENERATED repo-state intercept (gen_aw_doctor.py) -- do not edit
+    try:
+        from awgit import state as _aw_state
+    except Exception:
+        _aw_state = None
+    if _aw_state is not None:
+        _sv = locals().get("argv")
+        if _aw_state.cli_banner(_sv if _sv is not None else __import__("sys").argv[1:]):
+            return 0
+    ap = argparse.ArgumentParser(
+        prog="awtax",
+        description="Turn any tax PDF into structured data you can check.",
+    )
+    ap.add_argument("pdf", help="path to a tax PDF (return, W-2, 1099, statement)")
+    ap.add_argument("--endpoint", default=None, help="awvision endpoint for scanned pages")
+    ap.add_argument("--model", default=None, help="vision model override")
+    ap.add_argument("--indent", type=int, default=2)
+    args = ap.parse_args(argv)
+
+    try:
+        result = extract(args.pdf, endpoint=args.endpoint, model=args.model)
+    except FileNotFoundError:
+        print(f"awtax: no such file: {args.pdf}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # pragma: no cover
+        print(f"awtax: failed to read {args.pdf}: {exc}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(result.to_dict(), indent=args.indent))
+    # exit 3 (not 0) when anything needs human review -- silence is not a pass
+    return 3 if result.to_dict()["needs_review"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

awtax-0.1.0/awtax/extract.py

@@ -0,0 +1,218 @@
+"""The extraction core: any tax PDF -> a provider-neutral, self-checked schema.
+
+Native-text pages are parsed directly (PyMuPDF). Scanned pages route to awvision
+(ocr.py). Every recognized document runs arithmetic cross-checks -- a tax number
+that does not satisfy the identity it is defined by (taxable = AGI - deduction,
+refund = payments - tax) is flagged, not trusted. That self-validation is what let
+this code read a real 2024 return this session and *prove* the figures pair
+correctly instead of asserting a fragile label->value guess.
+"""
+from __future__ import annotations
+
+import re
+
+from .ocr import (
+    extract_fields_via_vision,
+    extract_text_via_local_ocr,
+    vision_available,
+)
+from .schema import Document, Extraction, Figure
+
+_MONEY = re.compile(r"^-?\d[\d,]*\.?$")
+_SCAN_TEXT_THRESHOLD = 40  # a page with fewer chars than this is treated as a scan
+
+
+def _num(tok: str) -> float | None:
+    try:
+        return float(tok.replace(",", "").rstrip("."))
+    except ValueError:
+        return None
+
+
+def _page_text(page) -> str:
+    return page.get_text().replace("\xa0", " ").replace(" ", " ")
+
+
+
+
+# --- Form 1040 -------------------------------------------------------------
+
+_1040_LINES = {
+    "total_income": r"total income",
+    "adjusted_gross_income": r"adjusted gross income",
+    "standard_deduction": r"standard deduction or itemized",
+    "taxable_income": r"taxable income",
+    "tax": r"Tax \(see instructions\)",
+    "total_tax": r"total tax",
+    "withholding": r"federal income tax withheld",
+    "total_payments": r"total payments",
+    "refund": r"amount you overpaid|refunded to you",
+    "amount_owed": r"amount you owe",
+}
+
+
+def _extract_1040(doc_pages, pdf, form: str = "1040") -> Document:
+    d = Document(form=form, pages=[p + 1 for p in doc_pages])
+    for pi in doc_pages:
+        page = pdf[pi]
+        words = page.get_text("words")  # (x0, y0, x1, y1, text, block, line, wordno)
+        # On a real IRS 1040 the line DESCRIPTION and its filled AMOUNT are not in one
+        # token row -- the description sits in a y-BAND, and the amount is in the right
+        # column. So for each amount, reconstruct its label from every word within a
+        # small y-band and to the LEFT of the amount (its own line, whatever the
+        # baseline jitter), then match. Amount->label direction + the arithmetic
+        # cross-check below guard against a wrong pairing producing a wrong number.
+        amounts = [
+            (w[0], (w[1] + w[3]) / 2, w[4])
+            for w in words
+            if _MONEY.match(w[4]) and w[0] > 380 and ("." in w[4] or "," in w[4]) and len(w[4]) > 2
+        ]
+        for ax, ay, atok in amounts:
+            band = [
+                w[4]
+                for w in words
+                if abs((w[1] + w[3]) / 2 - ay) <= 8 and w[2] <= ax and not _MONEY.match(w[4])
+            ]
+            label = " ".join(band)
+            for key, pat in _1040_LINES.items():
+                if key in d.figures:
+                    continue
+                if re.search(pat, label, re.I):
+                    d.figures[key] = Figure(_num(atok), key, page=pi + 1, source="text")
+                    break
+    if not d.figures:
+        d.warnings.append(
+            f"{form}: recognized the form but extracted no figures "
+            "(label/value pairing did not resolve) -- needs review"
+        )
+    _crosscheck_1040(d)
+    return d
+
+
+def _crosscheck_1040(d: Document) -> None:
+    def g(k):
+        f = d.figures.get(k)
+        return f.value if f and isinstance(f.value, (int, float)) else None
+
+    agi, sd, ti = g("adjusted_gross_income"), g("standard_deduction"), g("taxable_income")
+    if None not in (agi, sd, ti):
+        (d.checks if abs(agi - sd - ti) < 1 else d.warnings).append(
+            f"taxable_income = AGI - deduction ({agi:.0f} - {sd:.0f} = {ti:.0f})"
+        )
+    pay, tax, ref = g("total_payments"), g("total_tax"), g("refund")
+    if None not in (pay, tax, ref):
+        (d.checks if abs(pay - tax - ref) < 1 else d.warnings).append(
+            f"refund = payments - total_tax ({pay:.0f} - {tax:.0f} = {ref:.0f})"
+        )
+
+
+# --- W-2 -------------------------------------------------------------------
+
+_W2_BOXES = {
+    "wages_box1": "box 1 wages, tips, other compensation",
+    "fed_withheld_box2": "box 2 federal income tax withheld",
+    "ss_wages_box3": "box 3 social security wages",
+    "ss_tax_box4": "box 4 social security tax withheld",
+    "medicare_wages_box5": "box 5 medicare wages and tips",
+    "medicare_tax_box6": "box 6 medicare tax withheld",
+    "state_wages_box16": "box 16 state wages",
+    "state_tax_box17": "box 17 state income tax",
+}
+
+
+def _extract_w2(doc_pages, pdf, *, endpoint=None, model=None) -> Document:
+    d = Document(form="W-2", pages=[p + 1 for p in doc_pages])
+    pi = doc_pages[0]
+    text = _page_text(pdf[pi])
+    if len(text.strip()) >= _SCAN_TEXT_THRESHOLD:
+        d.warnings.append("native-text W-2 parsing not yet implemented; use vision")
+        return d
+    # scanned -> vision first, then offline OCR, else needs_review (never silent zeros)
+    q = "This is a US W-2 wage and tax statement. Extract: " + "; ".join(
+        f"{k} ({desc})" for k, desc in _W2_BOXES.items()
+    )
+    fields: dict = {}
+    src = "vision"
+    if vision_available():
+        try:
+            fields = extract_fields_via_vision(pdf.name, pi, q, endpoint=endpoint, model=model)
+        except Exception as exc:
+            # any vision failure (unavailable, timeout, bad reply) degrades to OCR /
+            # needs_review -- a scanned form must never crash the whole extraction
+            d.warnings.append(f"vision path failed ({type(exc).__name__}); fell back")
+            fields = {}
+    if not fields:
+        raw = extract_text_via_local_ocr(pdf.name, pi)
+        if raw:
+            fields = _w2_from_ocr_text(raw)
+            src = "ocr"
+    if not fields:
+        d.warnings.append("scanned W-2 and no vision/OCR backend available -- needs review")
+        return d
+    for k in _W2_BOXES:
+        if k in fields and fields[k] not in (None, ""):
+            d.figures[k] = Figure(_num_any(fields[k]), k, page=pi + 1, source=src, confidence=0.8)
+    return d
+
+
+def _num_any(v):
+    if isinstance(v, (int, float)):
+        return float(v)
+    return _num(str(v))
+
+
+def _w2_from_ocr_text(text: str) -> dict:
+    """Best-effort parse of raw OCR text into the box values (offline fallback)."""
+    out: dict[str, float] = {}
+    # Fallback is deliberately conservative: label-anchored, not positional guessing.
+    for line in text.splitlines():
+        low = line.lower()
+        for k, desc in _W2_BOXES.items():
+            hint = desc.split("(")[0]
+            frag = hint.replace("box 1 ", "").replace("box 2 ", "")[:12]
+            if frag and frag in low:
+                m = re.search(r"(\d[\d,]*\.\d\d)", line)
+                if m:
+                    out[k] = _num(m.group(1))
+    return out
+
+
+# --- form recognition + entry point ---------------------------------------
+
+def _is_amended(text: str) -> bool:
+    # A 1040-X page mentions "Form 1040" in its BODY ("from Form 1040 or 1040-SR"),
+    # so a negative-lookahead on the header alone misclassifies it as a primary 1040.
+    # Detect the amendment markers directly instead.
+    return bool(re.search(r"1040-?X|Amended U\.S|Correct amount|column A\b", text, re.I))
+
+
+def _classify_pages(pdf) -> dict[str, list[int]]:
+    groups: dict[str, list[int]] = {}
+    for i, page in enumerate(pdf):
+        t = _page_text(page)
+        has_1040 = re.search(r"Form\s*1040\b", t) and re.search(r"adjusted gross income", t, re.I)
+        if _is_amended(t) and (has_1040 or re.search(r"total tax", t, re.I)):
+            groups.setdefault("1040-X", []).append(i)
+        elif has_1040:
+            groups.setdefault("1040", []).append(i)
+        elif re.search(r"W-?2\b.*Wage", t) or len(t.strip()) < _SCAN_TEXT_THRESHOLD:
+            groups.setdefault("W-2", []).append(i)
+    return groups
+
+
+def extract(pdf_path: str, *, endpoint: str | None = None, model: str | None = None) -> Extraction:
+    """Read a tax PDF into a self-checked, provider-neutral schema."""
+    import fitz  # PyMuPDF
+
+    pdf = fitz.open(pdf_path)
+    result = Extraction(source_path=pdf_path, page_count=len(pdf))
+    groups = _classify_pages(pdf)
+    if "1040" in groups:
+        result.documents.append(_extract_1040(groups["1040"], pdf))
+    if "1040-X" in groups:
+        result.documents.append(_extract_1040(groups["1040-X"], pdf, form="1040-X"))
+    if "W-2" in groups:
+        result.documents.append(
+            _extract_w2(groups["W-2"], pdf, endpoint=endpoint, model=model)
+        )
+    return result

awtax-0.1.0/awtax/ocr.py

@@ -0,0 +1,110 @@
+"""Reading pages that have no text layer (scans, photos of a mailed form).
+
+awtax does NOT bundle an OCR engine. The aw* stack already has a vision brick --
+`awvision` -- and a vision model extracts form fields *structurally* (it can answer
+"what is in box 1?"), which is strictly better than raw OCR text you then have to
+re-parse. So the primary path is awvision; a local OCR engine (tesseract) is only an
+offline fallback for a stranger who has neither a vision endpoint nor a network.
+
+Both paths are optional. If neither is available, the caller gets a clear
+`needs_review` signal rather than a silent zero -- the exact failure mode
+(TaxDesk's parse_w2_pdf returning all-zeros on a scan) that awtax exists to fix.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from typing import Any
+
+
+class VisionUnavailableError(RuntimeError):
+    pass
+
+
+def _render_page_png(pdf_path: str, page_index: int, dpi: int = 300) -> str:
+    """Render one page to a temp PNG, return its path. Requires PyMuPDF."""
+    import fitz  # PyMuPDF
+
+    doc = fitz.open(pdf_path)
+    pix = doc[page_index].get_pixmap(dpi=dpi)
+    out = os.path.join(tempfile.gettempdir(), f"awtax_p{page_index}.png")
+    pix.save(out)
+    return out
+
+
+def _coerce_json(text: str) -> dict[str, Any]:
+    """Pull the first JSON object out of a model reply, tolerating prose around it."""
+    if isinstance(text, dict):
+        return text
+    m = re.search(r"\{.*\}", str(text), re.S)
+    if not m:
+        return {}
+    try:
+        return json.loads(m.group(0))
+    except Exception:
+        return {}
+
+
+def vision_available() -> bool:
+    try:
+        import awvision  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def local_ocr_available() -> bool:
+    return shutil.which("tesseract") is not None
+
+
+def extract_fields_via_vision(
+    pdf_path: str,
+    page_index: int,
+    question: str,
+    *,
+    endpoint: str | None = None,
+    model: str | None = None,
+) -> dict[str, Any]:
+    """Ask the awvision plane to read a scanned page; return a JSON object of fields.
+
+    Raises VisionUnavailableError if awvision is not installed / no endpoint resolves,
+    so the caller can fall back rather than treat an outage as an empty form.
+    """
+    try:
+        from awvision import ask_vision  # type: ignore
+    except Exception as exc:  # pragma: no cover - import guard
+        raise VisionUnavailableError(f"awvision not available: {exc}") from exc
+
+    png = _render_page_png(pdf_path, page_index)
+    prompt = (
+        f"{question}\n\n"
+        "Return ONLY a compact JSON object mapping each field name to its value. "
+        "Use numbers for money (no $ or commas). If a field is absent, omit it."
+    )
+    answer = ask_vision(png, prompt, endpoint=endpoint, model=model)
+    return _coerce_json(answer)
+
+
+def extract_text_via_local_ocr(pdf_path: str, page_index: int) -> str:
+    """Offline fallback: render the page and run tesseract, returning raw text.
+
+    Returns '' if tesseract is not installed -- never raises, because the caller
+    treats empty text as needs_review, not as a valid empty form.
+    """
+    if not local_ocr_available():
+        return ""
+    png = _render_page_png(pdf_path, page_index)
+    try:
+        out = subprocess.run(
+            ["tesseract", png, "stdout", "--psm", "6"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        return out.stdout or ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""

awtax-0.1.0/awtax/schema.py

@@ -0,0 +1,72 @@
+"""Provider-neutral tax-document schema.
+
+Every extracted figure carries where it came from (page) and how confident we are,
+because a tax number with no provenance is a number nobody can check. This is the
+whole point of awtax: not "trust the vendor's sealed file", but "here is every value,
+and the page it sits on".
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+
+@dataclass
+class Figure:
+    """One extracted monetary/identifier value with provenance."""
+    value: float | str | None
+    label: str
+    page: int | None = None          # 1-indexed source page
+    source: str = "text"             # 'text' (native PDF text) | 'vision' | 'ocr'
+    confidence: float = 1.0          # 0..1
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Document:
+    """A single recognized tax document within a PDF (a 1040, a W-2, a 1099...)."""
+    form: str                        # e.g. '1040', '1040-X', 'W-2', '1099-INT'
+    tax_year: int | None = None
+    figures: dict[str, Figure] = field(default_factory=dict)
+    checks: list[str] = field(default_factory=list)      # arithmetic cross-checks that PASSED
+    warnings: list[str] = field(default_factory=list)    # cross-checks that FAILED / needs_review
+    pages: list[int] = field(default_factory=list)
+
+    @property
+    def needs_review(self) -> bool:
+        # A recognized form that yielded NO figures is not "clean" -- it is a failed
+        # read. Reporting it clean is the silent-zero failure awtax exists to prevent.
+        return (
+            not self.figures
+            or bool(self.warnings)
+            or any(f.confidence < 0.75 for f in self.figures.values())
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "form": self.form,
+            "tax_year": self.tax_year,
+            "pages": self.pages,
+            "figures": {k: v.to_dict() for k, v in self.figures.items()},
+            "checks": self.checks,
+            "warnings": self.warnings,
+            "needs_review": self.needs_review,
+        }
+
+
+@dataclass
+class Extraction:
+    """The full result of reading one tax PDF."""
+    source_path: str
+    page_count: int
+    documents: list[Document] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_path": self.source_path,
+            "page_count": self.page_count,
+            "documents": [d.to_dict() for d in self.documents],
+            "needs_review": any(d.needs_review for d in self.documents),
+        }

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

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: awtax
+Version: 0.1.0
+Summary: Turn any tax PDF -- returns, W-2, 1099, statements, even scans -- into structured data you can check.
+Author: Aitherium
+License: MIT
+Project-URL: Homepage, https://github.com/Aitherium/awtax
+Keywords: tax,pdf,extraction,ocr,1040,w-2,aither-world
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymupdf>=1.24
+Provides-Extra: vision
+Requires-Dist: awvision>=0.1; extra == "vision"
+Provides-Extra: ocr
+Dynamic: license-file
+
+# awtax
+
+**Turn any tax PDF — returns, W-2, 1099, statements, even scans — into structured data you can check.**
+
+Your own tax data gets locked inside one vendor's encrypted format, and a filed return or a
+mailed W-2 is a PDF nobody's code can read — half of them are scans with no text layer at all.
+Getting your own numbers back out means re-typing them or re-buying the app that sealed them.
+
+`awtax` reads the document. It does **not** give tax advice — it hands you every figure, the page
+it came from, and whether the arithmetic checks out.
+
+```bash
+git clone https://github.com/Aitherium/awtax && cd awtax && pip install -e .
+awtax path/to/return.pdf          # -> structured JSON on stdout
+```
+
+> Not on PyPI yet, so `pip install awtax` does **not** work — that name resolves
+> to nothing today. Install from the clone until a release exists.
+
+## What you get
+
+- **Provider-neutral schema** — every figure carries its `page`, its `source` (`text` / `vision` /
+  `ocr`), and a `confidence`. A tax number with no provenance is a number nobody can check.
+- **Arithmetic self-checks** — `taxable = AGI − deduction`, `refund = payments − tax`. A figure that
+  fails the identity it is defined by is **flagged**, not trusted. The CLI exits `3` when anything
+  needs review — silence is not a pass.
+- **Scans handled** — a page with no text layer routes to [`awvision`](../awvision) (a vision model
+  reads the form fields *structurally*, far better than raw OCR), with a local `tesseract` fallback
+  for fully-offline use. If neither is available you get an explicit `needs_review` — **never a
+  silent zero.** (That silent-zero-on-a-scan failure is exactly what this fixes.)
+
+## Scan backends (optional)
+
+| backend | how | when |
+|---|---|---|
+| **awvision** (preferred) | `pip install -e '.[vision]'` from the clone, pass `--endpoint` | a vision model extracts fields as JSON |
+| **tesseract** (offline fallback) | install the `tesseract` system binary | no network / no vision endpoint |
+| neither | — | pages return `needs_review` with a reason |
+
+## Where awtax stops, and the premium packs begin
+
+awtax is the open-source **extraction core**. Preparation, deduction discovery, worksheets, ledgers
+and CPA-ready output are the premium **TaxDesk** agent / skill / tool packs that compose on top via
+`awpack` / `awskills`. awtax reads; the packs advise.
+
+## Status
+
+`0.1.0` — reads native-text 1040 pages and scanned W-2s, self-validates, degrades gracefully.
+Known next work: 1040-vs-1040-X disambiguation on multi-form packets, richer 1099 coverage,
+and native-text W-2 parsing. MIT licensed.

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

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+awtax/__init__.py
+awtax/cli.py
+awtax/extract.py
+awtax/ocr.py
+awtax/schema.py
+awtax.egg-info/PKG-INFO
+awtax.egg-info/SOURCES.txt
+awtax.egg-info/dependency_links.txt
+awtax.egg-info/entry_points.txt
+awtax.egg-info/requires.txt
+awtax.egg-info/top_level.txt
+tests/test_extract.py

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

@@ -0,0 +1 @@
+

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

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

awtax-0.1.0/awtax.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pymupdf>=1.24
+
+[ocr]
+
+[vision]
+awvision>=0.1

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

@@ -0,0 +1 @@
+awtax

awtax-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "awtax"
+version = "0.1.0"
+description = "Turn any tax PDF -- returns, W-2, 1099, statements, even scans -- into structured data you can check."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Aitherium" }]
+keywords = ["tax", "pdf", "extraction", "ocr", "1040", "w-2", "aither-world"]
+dependencies = [
+    "pymupdf>=1.24",
+]
+
+[project.optional-dependencies]
+# Scanned pages read best through the aw* vision brick; tesseract is the offline fallback.
+vision = ["awvision>=0.1"]
+ocr = []  # tesseract is a system binary, not a pip dep -- documented in README
+
+[project.scripts]
+awtax = "awtax.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Aitherium/awtax"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["awtax*"]

awtax-0.1.0/setup.cfg

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

awtax-0.1.0/tests/test_extract.py

@@ -0,0 +1,130 @@
+"""awtax tests. Build a synthetic native-text 1040 page so the core is provable
+without shipping anyone's real return, and assert the arithmetic self-check both
+PASSES on consistent numbers and FLAGS inconsistent ones (the property that makes
+the extraction trustworthy rather than a fragile label->value guess).
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+
+import pytest
+
+fitz = pytest.importorskip("fitz")
+
+from awtax import extract  # noqa: E402
+from awtax.schema import Document  # noqa: E402
+from awtax.extract import _crosscheck_1040  # noqa: E402
+from awtax.schema import Figure  # noqa: E402
+
+
+def _make_1040(agi, deduction, taxable, tmp):
+    """Render a minimal 1040-shaped page: label on the left, amount in the right column."""
+    doc = fitz.open()
+    page = doc.new_page(width=612, height=792)
+    rows = [
+        (400, "11 This is your adjusted gross income", f"{agi:,.0f}."),
+        (430, "12 Standard deduction or itemized deductions", f"{deduction:,.0f}."),
+        (460, "15 This is your taxable income", f"{taxable:,.0f}."),
+    ]
+    page.insert_text((36, 60), "Form 1040 (2024)")
+    page.insert_text((36, 80), "adjusted gross income")  # classifier anchor
+    for y, label, amt in rows:
+        page.insert_text((36, y), label, fontsize=9)
+        page.insert_text((500, y), amt, fontsize=9)  # right column (x>380)
+    path = os.path.join(tmp, "synthetic_1040.pdf")
+    doc.save(path)
+    return path
+
+
+def test_1040_extraction_and_passing_crosscheck(tmp_path):
+    path = _make_1040(171890, 21900, 149990, str(tmp_path))
+    result = extract(path)
+    forms = {d.form: d for d in result.documents}
+    assert "1040" in forms, "1040 page should be recognized"
+    d = forms["1040"]
+    assert d.figures["adjusted_gross_income"].value == 171890
+    assert d.figures["taxable_income"].value == 149990
+    # 171890 - 21900 == 149990 -> the identity holds -> recorded as a passed check
+    assert any("taxable_income = AGI - deduction" in c for c in d.checks)
+    assert not d.warnings
+
+
+def test_crosscheck_flags_inconsistent_numbers():
+    d = Document(form="1040")
+    d.figures["adjusted_gross_income"] = Figure(100000, "agi")
+    d.figures["standard_deduction"] = Figure(20000, "sd")
+    d.figures["taxable_income"] = Figure(75000, "ti")  # WRONG: should be 80000
+    _crosscheck_1040(d)
+    assert d.warnings, "an inconsistent taxable-income must be flagged, not trusted"
+    assert d.needs_review
+
+
+def _make_1040x(tmp):
+    """A Form 1040-X page: it mentions 'Form 1040' in its body, which is exactly why
+    a naive header lookahead misclassifies it as the primary return."""
+    doc = fitz.open()
+    page = doc.new_page(width=612, height=792)
+    page.insert_text((36, 60), "Form 1040-X  Amended U.S. Individual Income Tax Return")
+    page.insert_text((36, 80), "adjusted gross income")            # 1040 anchor (bait)
+    page.insert_text((36, 100), "amounts from Form 1040 or 1040-SR, column A  Correct amount")
+    page.insert_text((36, 130), "11 Total tax", fontsize=9)
+    page.insert_text((500, 130), "25,347.", fontsize=9)
+    path = os.path.join(tmp, "synthetic_1040x.pdf")
+    doc.save(path)
+    return path
+
+
+def _make_1040_offset_baseline(agi, deduction, taxable, tmp):
+    """A 1040 page where the amount sits on a DIFFERENT text baseline than its label --
+    which is how a real IRS form renders (right-column values are not row-aligned to the
+    left labels). This is the case the naive same-row pairing missed on the real return."""
+    doc = fitz.open()
+    page = doc.new_page(width=612, height=792)
+    page.insert_text((36, 60), "Form 1040 (2024)")
+    page.insert_text((36, 80), "adjusted gross income")
+    rows = [
+        (400, "11 This is your adjusted gross income", agi),
+        (430, "12 Standard deduction or itemized deductions", deduction),
+        (460, "15 This is your taxable income", taxable),
+    ]
+    for y, label, amt in rows:
+        page.insert_text((36, y), label, fontsize=9)
+        page.insert_text((505, y + 3), f"{amt:,.0f}.", fontsize=9)  # +3px baseline offset
+    path = os.path.join(tmp, "synthetic_1040_offset.pdf")
+    doc.save(path)
+    return path
+
+
+def test_1040_reads_offset_baseline_and_crosschecks(tmp_path):
+    # regression for the real return: labels and values on different baselines must
+    # still pair, and the arithmetic identity must hold -> proves correct pairing.
+    path = _make_1040_offset_baseline(171890, 21900, 149990, str(tmp_path))
+    d = {x.form: x for x in extract(path).documents}["1040"]
+    assert d.figures["adjusted_gross_income"].value == 171890
+    assert d.figures["standard_deduction"].value == 21900
+    assert d.figures["taxable_income"].value == 149990
+    assert any("AGI - deduction" in c for c in d.checks)
+    assert not d.needs_review
+
+
+def test_1040x_is_not_classified_as_primary_1040(tmp_path):
+    # regression: on a real 61-page packet the amended page was read AS the 1040.
+    path = _make_1040x(str(tmp_path))
+    result = extract(path)
+    forms = {d.form for d in result.documents}
+    assert "1040-X" in forms, "the amended page must be recognized as 1040-X"
+    assert "1040" not in forms, "a 1040-X page must NOT be misread as the primary 1040"
+
+
+def test_empty_recognized_form_needs_review():
+    # a recognized form with zero figures must NOT report clean (silent-zero guard)
+    d = Document(form="1040")
+    assert d.needs_review is True
+
+
+def test_needs_review_exit_signal(tmp_path):
+    # a doc with a failed check must surface needs_review True
+    path = _make_1040(100000, 20000, 75000, str(tmp_path))  # inconsistent on purpose
+    result = extract(path)
+    assert result.to_dict()["needs_review"] is True