bidreader 0.2.0__py3-none-any.whl

bidreader/__init__.py

@@ -0,0 +1,3 @@
+from .extract import read, Doc
+__all__ = ["read", "Doc"]
+__version__ = "0.2.0"

bidreader/cli.py

@@ -0,0 +1,39 @@
+"""`bidreader <file.pdf>` — print an estimator report, or `--json` for piping."""
+import sys, json
+from .extract import read
+
+
+def main():
+    args = [a for a in sys.argv[1:]]
+    as_json = "--json" in args
+    paths = [a for a in args if not a.startswith("-")]
+    if not paths:
+        print("usage: bidreader <document.pdf> [--json]"); sys.exit(1)
+    d = read(paths[0])
+    if as_json:
+        print(d.to_json()); return
+    print("=" * 74)
+    print(f"BIDREADER  |  {d['_source']}  ({d['_pages']}p)")
+    print("=" * 74)
+    print(f"{d.get('doc_type','?')}  |  {d.get('vendor','?')}  |  trade: {d.get('trade','?')}  |  {d.get('currency','')}")
+    print(f"Project: {d.get('project','?')}")
+    print(f"\nLINE ITEMS ({len(d.line_items)}):")
+    for li in d.line_items:
+        amt = ('$' + format(li['amount'], ',.2f')) if li.get('amount') is not None else ''
+        print(f"  {str(li.get('section') or '-'):10s}{str(li.get('description',''))[:40]:41s}"
+              f"{str(li.get('qty') or ''):>8s}{str(li.get('unit') or ''):>5s}{amt:>13s}  p{li.get('page','?')}")
+    if d.get('bid_total'):
+        print(f"  {'BID TOTAL':56s}{'$' + format(d['bid_total'], ',.2f'):>13s}")
+    print(f"\n!!  EXCLUSIONS CAUGHT ({len(d.exclusions)}):")
+    for e in d.exclusions:
+        print(f"   - {e.get('item','?')}  (page {e.get('page','?')})")
+        print(f"       \"{e.get('quote','')[:120]}\"")
+        print(f"       risk: {e.get('risk','')}")
+    if d.scope_gaps:
+        print(f"\nSCOPE GAPS TO CONFIRM ({len(d.scope_gaps)}):")
+        for g in d.scope_gaps:
+            print(f"   - {g.get('missing','')} -- {g.get('why','')}")
+
+
+if __name__ == "__main__":
+    main()

bidreader/extract.py

@@ -0,0 +1,97 @@
+"""
+BidReader — read messy construction documents (sub-quotes, bid packages, spec
+sections, schedules) into clean structured data, and CATCH the scope gaps /
+exclusions vendors bury. Every value cites its page + the exact source text.
+
+The valued, repeated estimator pain (r/Construction, 498 upvotes): not the
+takeoff — it's wrangling "crime-scene formatting" PDFs into clean tables and
+finding the one line where a sub quietly excluded something in size-8 font.
+
+LLM-native (works today). Provider-agnostic key from env: REQUESTY / OPENROUTER
+/ GEMINI. MIT.
+"""
+from __future__ import annotations
+import os, json, ssl, urllib.request, certifi
+import fitz
+
+SSLCTX = ssl.create_default_context(cafile=certifi.where())
+MODEL = os.environ.get("BID_MODEL", "google/gemini-2.5-flash")
+
+SCHEMA_PROMPT = """You are a construction estimating assistant reading a vendor/subcontractor document
+(quote, bid, proposal, spec section, or schedule). Read the TEXT (page-tagged) and return STRICT JSON only:
+{
+ "doc_type": "<sub-quote|bid package|spec section|schedule|invoice|other>",
+ "vendor": "<company or null>", "project": "<project/title or null>",
+ "trade": "<trade e.g. Drywall, Electrical or null>", "currency": "<e.g. USD or null>",
+ "bid_total": <number or null>,
+ "line_items": [{"section":"<csi/section or null>","description":"<text>","qty":<num|null>,"unit":"<EA/SF/LF/LS|null>","unit_price":<num|null>,"amount":<num|null>,"page":<int>}],
+ "exclusions": [{"item":"<short label>","quote":"<EXACT text as written>","page":<int>,"risk":"<one line: why this matters / who eats the cost>"}],
+ "assumptions": [{"text":"<exact>","page":<int>}],
+ "alternates": [{"text":"<exact>","amount":<num|null>,"page":<int>}],
+ "scope_gaps": [{"missing":"<scope likely NOT covered>","why":"<why an estimator should confirm>"}],
+ "notes": "<one line on confidence/legibility>"
+}
+Rules: exclusions are CRITICAL — hunt everywhere, including fine print, footnotes, "by others", "not included",
+"excludes", "assumes", "clarifications". Quote them verbatim with the page. Do not invent values; use null if unsure.
+For scope_gaps, infer trade-standard scope a vendor commonly omits that is NOT mentioned in this doc."""
+
+
+def _page_text(doc):
+    parts = []
+    for i, p in enumerate(doc):
+        t = p.get_text().strip()
+        if t:
+            parts.append(f"[PAGE {i+1}]\n{t}")
+    return "\n\n".join(parts)
+
+
+def _llm(text):
+    rq = os.environ.get("REQUESTY_API_KEY"); ork = os.environ.get("OPENROUTER_API_KEY")
+    gk = os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
+    user = SCHEMA_PROMPT + "\n\n=== DOCUMENT TEXT ===\n" + text[:120000]
+    if rq: base, key = "https://router.requesty.ai/v1/chat/completions", rq
+    elif ork: base, key = "https://openrouter.ai/api/v1/chat/completions", ork
+    elif gk:
+        m = MODEL.split("/")[-1]
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{m}:generateContent?key={gk}"
+        body = {"contents":[{"parts":[{"text":user}]}],
+                "generationConfig":{"response_mime_type":"application/json","temperature":0}}
+        req = urllib.request.Request(url, data=json.dumps(body).encode(), headers={"Content-Type":"application/json"})
+        r = json.load(urllib.request.urlopen(req, timeout=180, context=SSLCTX))
+        return _clean(r["candidates"][0]["content"]["parts"][0]["text"])
+    else:
+        raise RuntimeError("Set REQUESTY_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY")
+    body = {"model": MODEL, "temperature": 0, "max_tokens": 16000, "reasoning_effort": "low",
+            "messages": [{"role": "user", "content": user}]}
+    req = urllib.request.Request(base, data=json.dumps(body).encode(),
+                                 headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+    r = json.load(urllib.request.urlopen(req, timeout=180, context=SSLCTX))
+    return _clean(r["choices"][0]["message"]["content"])
+
+
+def _clean(s):
+    s = s.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+    return json.loads(s)
+
+
+class Doc(dict):
+    """Result with convenience accessors."""
+    @property
+    def line_items(self): return self.get("line_items", [])
+    @property
+    def exclusions(self): return self.get("exclusions", [])
+    @property
+    def scope_gaps(self): return self.get("scope_gaps", [])
+    def to_json(self, **kw): return json.dumps(self, indent=2, **kw)
+
+
+def read(path: str) -> Doc:
+    """Read a construction PDF into structured, page-cited data."""
+    doc = fitz.open(path)
+    text = _page_text(doc)
+    if len(text) < 40:
+        raise RuntimeError("No extractable text (scanned PDF) — vision OCR path TODO.")
+    data = _llm(text)
+    data["_source"] = path.split("/")[-1]
+    data["_pages"] = doc.page_count
+    return Doc(data)

bidreader/mcp_server.py

@@ -0,0 +1,61 @@
+"""BidReader MCP server — lets any agent (Claude Desktop, Cursor, etc.) read a
+construction document and get structured data + caught exclusions.
+
+Run:  bidreader-mcp           (stdio transport)
+Needs an LLM key in env: REQUESTY_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY.
+
+Claude Desktop / Cursor config:
+  {"mcpServers": {"bidreader": {"command": "bidreader-mcp",
+     "env": {"REQUESTY_API_KEY": "rqsty-..."}}}}
+"""
+from __future__ import annotations
+import os
+from mcp.server.fastmcp import FastMCP
+from .extract import read
+
+mcp = FastMCP("bidreader")
+
+
+def _check_key():
+    if not (os.environ.get("REQUESTY_API_KEY") or os.environ.get("OPENROUTER_API_KEY")
+            or os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")):
+        raise RuntimeError("No LLM key in env (REQUESTY_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY).")
+
+
+@mcp.tool()
+def read_document(path: str) -> dict:
+    """Read a construction PDF (sub-quote, bid package, spec section, schedule) into
+    clean structured data: line_items, exclusions, assumptions, alternates, scope_gaps —
+    every value cited to its page. `path` is an absolute path to a local PDF.
+    Returns the full structured object."""
+    _check_key()
+    return dict(read(path))
+
+
+@mcp.tool()
+def catch_exclusions(path: str) -> dict:
+    """Scan a construction quote/spec PDF for scope EXCLUSIONS and gaps a vendor buried
+    (fine print, 'by others', 'not included'). Returns {exclusions:[{item,quote,page,risk}],
+    scope_gaps:[{missing,why}]} — what an estimator must confirm before bidding."""
+    _check_key()
+    d = read(path)
+    return {"vendor": d.get("vendor"), "trade": d.get("trade"),
+            "exclusions": d.get("exclusions", []), "scope_gaps": d.get("scope_gaps", [])}
+
+
+@mcp.tool()
+def extract_line_items(path: str) -> dict:
+    """Extract priced line items (section, description, qty, unit, amount, page) and the
+    bid total from a construction quote/bid PDF. Returns {bid_total, currency, line_items}."""
+    _check_key()
+    d = read(path)
+    return {"bid_total": d.get("bid_total"), "currency": d.get("currency"),
+            "line_items": d.get("line_items", [])}
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

bidreader-0.2.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: bidreader
+Version: 0.2.0
+Summary: Read messy construction sub-quotes, bid packages & spec PDFs into clean structured data — and catch the scope gaps/exclusions vendors bury. Every value cited to its page.
+Author-email: Anmol <anmol@attentive.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/anmolsam/bidreader
+Project-URL: Issues, https://github.com/anmolsam/bidreader/issues
+Keywords: construction,estimating,takeoff,subcontractor,bid,quote,scope,exclusions,spec,AEC,preconstruction,BOQ,LLM,MCP
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: certifi>=2024.0
+Provides-Extra: tables
+Requires-Dist: pdfplumber>=0.11; extra == "tables"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# BidReader
+
+**Read messy construction sub-quotes, bid packages & spec PDFs into clean structured data — and catch the scope gaps and exclusions vendors bury in the fine print.** Every value is cited to its page and exact source text.
+
+MIT · `pip install bidreader` · works on the PDFs estimators actually get.
+
+> *"Manually typing numbers from a PDF into Excel because the formatting is a crime scene… hunting for the one line where a sub quietly excluded 'trash removal' in size-8 font."* — r/Construction (498 upvotes)
+
+BidReader is that junior who never sleeps: it doesn't write anything new — it finds what's already there and points to it.
+
+---
+
+## What it does
+
+```bash
+pip install bidreader
+export REQUESTY_API_KEY=...        # or OPENROUTER_API_KEY / GEMINI_API_KEY (free tier works)
+bidreader sub_quote.pdf
+```
+
+```python
+from bidreader import read
+doc = read("sub_quote.pdf")
+doc.line_items     # [{section, description, qty, unit, amount, page}, ...]
+doc.exclusions     # [{item, quote, page, risk}, ...]   <- the stuff they buried
+doc.scope_gaps     # trade-standard scope NOT mentioned (confirm before you bid)
+doc.to_json()
+```
+
+## Real output (drywall sub-quote, exclusion buried in size-7 font)
+
+```
+LINE ITEMS (5):
+  09 22 16  Metal stud framing, 3-5/8" 25ga walls   12400 SF   $35,340.00  p1
+  09 29 00  5/8" Type X gypsum board, both faces     24800 SF   $40,920.00  p1
+  09 29 00  Tape & finish, Level 4                   24800 SF   $23,560.00  p1
+  ...                                                 BID TOTAL  $121,628.00
+
+!!  EXCLUSIONS CAUGHT (4):
+  - Fire-stopping/firecaulking  (page 1)
+      "this proposal EXCLUDES fire-stopping/firecaulking at rated assemblies"
+      risk: life-safety scope; another trade or a change order eats this cost.
+  - Debris removal/haul-off  (page 1)
+      "removal/haul-off of construction debris (by others)"
+  ...
+
+SCOPE GAPS TO CONFIRM (5):
+  - Acoustic ceiling tiles -- grid framing is included but the tiles within it are not.
+  - Rough carpentry blocking/backing for fixtures -- not mentioned.
+```
+
+## Why
+
+The construction-AI gold rush is all building the same crowded, resisted thing — autonomous *takeoff*. The loudest, most-repeated, **unmet** estimator pain is upstream and downstream of it: turning crime-scene PDFs into clean data and **catching what subs quietly excluded**. No permissive library does this. BidReader is that primitive.
+
+- **MIT** — depend on it inside your commercial estimating/BIM product (no AGPL/NC contamination).
+- **Provider-agnostic** — Requesty, OpenRouter, or Google AI Studio (free tier).
+- **Cited** — every number traces to a page + the exact source text. Trust is the real adoption blocker; this is built for it.
+
+## Use it from an AI agent (MCP)
+
+Any MCP client — Claude Desktop, Cursor, etc. — can call BidReader:
+
+```bash
+pip install "bidreader[mcp]"
+```
+```json
+{
+  "mcpServers": {
+    "bidreader": {
+      "command": "bidreader-mcp",
+      "env": { "REQUESTY_API_KEY": "rqsty-..." }
+    }
+  }
+}
+```
+Tools exposed: `read_document(path)`, `catch_exclusions(path)`, `extract_line_items(path)`.
+Now your agent can answer *"which subs excluded fire-stopping?"* across a bid folder.
+
+## Roadmap
+- Scanned-PDF vision OCR path · revision/addendum **diff** ("what changed between Addendum 3 and 4") · `bidreader-mcp` server (any agent can call it) · Excel/CSV export · multi-quote leveling (compare subs side-by-side).
+
+## License
+MIT.

bidreader-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+bidreader/__init__.py,sha256=6FpDOl5Uqo_AwzdfdHJN0cWPHZnwSUoWjH8JVIRzMi8,79
+bidreader/cli.py,sha256=WroAYRpr8HZmQPzj3u66zSzCQ_z22BZ-EMvNGfT_T54,1673
+bidreader/extract.py,sha256=tUIpntnxvoelEKmjCfGp-mFM5thgGouD9IcQRHM7HVE,4820
+bidreader/mcp_server.py,sha256=NbtzNQC5WwGR88MpK18y1N089EzELzoQjVqo8WkOP70,2239
+bidreader-0.2.0.dist-info/licenses/LICENSE,sha256=TEAVtI0pnzQzIFRnRSYuB_UdXGIKEYa0EEtn0kc-vdw,1062
+bidreader-0.2.0.dist-info/METADATA,sha256=5Rl2GffwhCdC_fn8gZNDrDezfdPg3lcX5gYZ5sfwTog,4539
+bidreader-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bidreader-0.2.0.dist-info/entry_points.txt,sha256=FNi7_QrwF3dEQc8hXUDkU1-eoMrSQaLtKJC93-LANbE,91
+bidreader-0.2.0.dist-info/top_level.txt,sha256=7w-Do-kKxkje0iLiLhIrmGcDqcZWvMe1zI9EVBMaSCg,10
+bidreader-0.2.0.dist-info/RECORD,,

bidreader-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bidreader-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bidreader = bidreader.cli:main
+bidreader-mcp = bidreader.mcp_server:main

bidreader-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anmol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bidreader-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bidreader