tabularmapper 1.0.1__tar.gz → 1.0.3__tar.gz

{tabularmapper-1.0.1/src/tabularmapper.egg-info → tabularmapper-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabularmapper
-Version: 1.0.1
+Version: 1.0.3
 Summary: Map any spreadsheet (.xlsx) to a schema you define — deterministic column mapping with an optional AI matcher
 Author-email: Karthikeyan Duraisamy <karthikeyanduraisamy@kultivateindia.com>
 License-Expression: MIT
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
@@ -163,6 +165,7 @@ All are optional; sensible defaults apply.
 | `TABULARMAPPER_LEARN_STORE` | `memory://` (no files) | where self-learned header synonyms live |
 | `TABULARMAPPER_CONFIG` | *(none — required)* | output template + synonyms JSON (file / `https://` / `s3://`) |
 | `TABULARMAPPER_ROUTE_PREFIX` | `/mapper` | FastAPI router path prefix |
+| `TABULARMAPPER_THRESHOLD` | `80` | fuzzy-accept gate (0–100); raise it to push borderline fuzzy matches to the AI matcher |
 | `OPENAI_API_KEY` | *(unset → AI off)* | enables the AI column matcher |
 | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | any OpenAI-compatible endpoint |
 | `OPENAI_MODEL` | `gpt-4o-mini` | model name |
@@ -278,6 +281,18 @@ app.include_router(router)
 blocking work in a threadpool. Store the original file to S3 in your own endpoint
 if you need it — the mapper stays out of AWS.
 
+Two query params shape the request:
+
+```bash
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=base64"    # json + a mapped .xlsx in file_base64
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=file" -OJ  # download the mapped .xlsx
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?threshold=90"     # stricter fuzzy gate for this call
+```
+
+`format` is `json` (default) / `base64` / `file`. `threshold` (0–100) overrides
+`TABULARMAPPER_THRESHOLD` for one request — raise it to send borderline fuzzy
+matches to the AI matcher instead of trusting them.
+
 The `/mapper` prefix is configurable (this is a general table→schema mapper, not
 just banks): set `TABULARMAPPER_ROUTE_PREFIX`, or build the router yourself:
 

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/README.md

@@ -125,6 +125,7 @@ All are optional; sensible defaults apply.
 | `TABULARMAPPER_LEARN_STORE` | `memory://` (no files) | where self-learned header synonyms live |
 | `TABULARMAPPER_CONFIG` | *(none — required)* | output template + synonyms JSON (file / `https://` / `s3://`) |
 | `TABULARMAPPER_ROUTE_PREFIX` | `/mapper` | FastAPI router path prefix |
+| `TABULARMAPPER_THRESHOLD` | `80` | fuzzy-accept gate (0–100); raise it to push borderline fuzzy matches to the AI matcher |
 | `OPENAI_API_KEY` | *(unset → AI off)* | enables the AI column matcher |
 | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | any OpenAI-compatible endpoint |
 | `OPENAI_MODEL` | `gpt-4o-mini` | model name |
@@ -240,6 +241,18 @@ app.include_router(router)
 blocking work in a threadpool. Store the original file to S3 in your own endpoint
 if you need it — the mapper stays out of AWS.
 
+Two query params shape the request:
+
+```bash
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=base64"    # json + a mapped .xlsx in file_base64
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=file" -OJ  # download the mapped .xlsx
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?threshold=90"     # stricter fuzzy gate for this call
+```
+
+`format` is `json` (default) / `base64` / `file`. `threshold` (0–100) overrides
+`TABULARMAPPER_THRESHOLD` for one request — raise it to send borderline fuzzy
+matches to the AI matcher instead of trusting them.
+
 The `/mapper` prefix is configurable (this is a general table→schema mapper, not
 just banks): set `TABULARMAPPER_ROUTE_PREFIX`, or build the router yourself:
 

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabularmapper"
-version = "1.0.1"
+version = "1.0.3"
 description = "Map any spreadsheet (.xlsx) to a schema you define — deterministic column mapping with an optional AI matcher"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -22,6 +22,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Office/Business",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/src/tabularmapper/__init__.py

@@ -44,7 +44,7 @@ from .schema import (
 )
 from .stores import open_store
 
-__version__ = "1.0.1"
+__version__ = "1.0.3"
 
 __all__ = [
     "process_file",

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/src/tabularmapper/api.py

@@ -30,6 +30,7 @@ from __future__ import annotations
 
 import os
 from contextlib import asynccontextmanager
+from enum import Enum
 from typing import Any, Optional
 
 from fastapi import APIRouter, FastAPI, File, HTTPException, Query, UploadFile
@@ -44,6 +45,24 @@ from .mapping_cache import MappingCache
 _XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 
 
+def _default_threshold() -> int:
+    """The fuzzy-accept gate (0-100). Below this, a column is left unmapped and,
+    if it's a critical field, the AI matcher is asked to fill it. Raise it to
+    push borderline fuzzy matches to the AI instead of trusting them. Read from
+    TABULARMAPPER_THRESHOLD at request time; falls back to 80."""
+    try:
+        return max(0, min(100, int(os.getenv("TABULARMAPPER_THRESHOLD", "80"))))
+    except (TypeError, ValueError):
+        return 80
+
+
+class OutFormat(str, Enum):
+    """Response shape for POST /map — rendered as a dropdown in the docs."""
+    json = "json"        # rows inline (default)
+    base64 = "base64"    # rows inline + a mapped .xlsx in file_base64
+    file = "file"        # download the .xlsx directly (binary, no JSON body)
+
+
 # --------------------------------------------------------------------------
 # Shared singletons (built once at startup)
 # --------------------------------------------------------------------------
@@ -122,13 +141,19 @@ async def health() -> dict:
 
 async def map_statement(
     file: UploadFile = File(...),
-    format: str = Query(
-        "json",
-        pattern="^(json|base64|file)$",
+    format: OutFormat = Query(
+        OutFormat.json,
         description="json = rows inline (default); base64 = rows inline + an "
                     ".xlsx encoded in file_base64; file = download the .xlsx "
                     "directly (binary, no JSON body).",
     ),
+    threshold: Optional[int] = Query(
+        None,
+        ge=0, le=100,
+        description="Fuzzy-accept gate 0-100. Overrides TABULARMAPPER_THRESHOLD "
+                    "(default 80) for this request. Raise it to send borderline "
+                    "fuzzy matches to the AI matcher instead of trusting them.",
+    ),
 ):
     """Upload a spreadsheet (.xlsx); get the standardized mapping + rows.
 
@@ -136,18 +161,22 @@ async def map_statement(
       * json    -> MapResponse with the rows in `transactions`
       * base64  -> same MapResponse, plus a mapped .xlsx in `file_base64`
       * file    -> the mapped .xlsx as a downloadable attachment
+
+    `threshold` (query) overrides the fuzzy gate for this one call; otherwise the
+    server default (TABULARMAPPER_THRESHOLD, else 80) is used.
     """
     name = (file.filename or "").lower()
     if not name.endswith((".xlsx", ".xls")):
         raise HTTPException(status_code=400, detail="expected an .xlsx/.xls file")
 
+    gate = threshold if threshold is not None else _default_threshold()
     data = await file.read()          # raw bytes, parsed in memory (never hits disk)
     try:
         # blocking work -> threadpool; process_stream reads straight from bytes
         res = await run_in_threadpool(
             process_stream, data,
             table_matcher=state.matcher, cache=state.cache,
-            learn_store=state.learn,
+            learn_store=state.learn, threshold=gate,
             source_label=file.filename or "<upload>",
         )
     except Exception as exc:  # noqa: BLE001

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/src/tabularmapper/engine.py

@@ -810,7 +810,10 @@ def _run(rows: list[list], source_label: str, out_path, llm_fallback,
 
     from_cache = False
     col_maps = None
-    schema_sig = _schema_signature()     # scope the cache to the active schema
+    # Scope the cache to the active schema AND the fuzzy gate: a different
+    # threshold can change which columns map, so it must not reuse a mapping
+    # computed at another threshold.
+    schema_sig = f"{_schema_signature()}:t{threshold}"
     if cache is not None:
         cached = cache.get(header, namespace=schema_sig)
         if cached is not None:

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/src/tabularmapper/schema.py

@@ -198,7 +198,7 @@ def _infer_type(field_key: str) -> str:
 def default_config() -> Config:
     """The built-in default: EMPTY. This is a general mapper, so with no config
     it maps nothing — you must provide an output_schema + synonyms (a file/URL via
-    BANK_MAPPER_CONFIG, a dict, or configure()). Use `bank_preset()` for the
+    TABULARMAPPER_CONFIG, a dict, or configure()). Use `bank_preset()` for the
     ready-made bank-statement schema."""
     return Config(output_schema=[], synonyms={}, critical_fields=[])
 

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/src/tabularmapper/stores.py

@@ -145,7 +145,7 @@ def _redis_proto_client(url: str, prefer: str = "redis"):
         return mod.from_url(u)                  # module-level from_url (both expose it)
     raise ImportError(
         "This cache backend needs the 'valkey' or 'redis' package. Install one "
-        "with:  pip install bank-statement-mapper[valkey]   (or [redis]). Both "
+        "with:  pip install tabularmapper[valkey]   (or [redis]). Both "
         "are optional — the default SQLite backend needs nothing extra."
     ) from last_err
 
@@ -188,7 +188,7 @@ class PostgresStore:
         except ImportError as exc:
             raise ImportError(
                 "The postgres cache backend needs the 'psycopg' package. Install "
-                "it with:  pip install bank-statement-mapper[postgres]. It is "
+                "it with:  pip install tabularmapper[postgres]. It is "
                 "optional — the default SQLite backend needs nothing extra."
             ) from exc
         self._table = table

{tabularmapper-1.0.1 → tabularmapper-1.0.3/src/tabularmapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabularmapper
-Version: 1.0.1
+Version: 1.0.3
 Summary: Map any spreadsheet (.xlsx) to a schema you define — deterministic column mapping with an optional AI matcher
 Author-email: Karthikeyan Duraisamy <karthikeyanduraisamy@kultivateindia.com>
 License-Expression: MIT
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
@@ -163,6 +165,7 @@ All are optional; sensible defaults apply.
 | `TABULARMAPPER_LEARN_STORE` | `memory://` (no files) | where self-learned header synonyms live |
 | `TABULARMAPPER_CONFIG` | *(none — required)* | output template + synonyms JSON (file / `https://` / `s3://`) |
 | `TABULARMAPPER_ROUTE_PREFIX` | `/mapper` | FastAPI router path prefix |
+| `TABULARMAPPER_THRESHOLD` | `80` | fuzzy-accept gate (0–100); raise it to push borderline fuzzy matches to the AI matcher |
 | `OPENAI_API_KEY` | *(unset → AI off)* | enables the AI column matcher |
 | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | any OpenAI-compatible endpoint |
 | `OPENAI_MODEL` | `gpt-4o-mini` | model name |
@@ -278,6 +281,18 @@ app.include_router(router)
 blocking work in a threadpool. Store the original file to S3 in your own endpoint
 if you need it — the mapper stays out of AWS.
 
+Two query params shape the request:
+
+```bash
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=base64"    # json + a mapped .xlsx in file_base64
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?format=file" -OJ  # download the mapped .xlsx
+curl -F file=@f.xlsx "http://localhost:8000/mapper/map?threshold=90"     # stricter fuzzy gate for this call
+```
+
+`format` is `json` (default) / `base64` / `file`. `threshold` (0–100) overrides
+`TABULARMAPPER_THRESHOLD` for one request — raise it to send borderline fuzzy
+matches to the AI matcher instead of trusting them.
+
 The `/mapper` prefix is configurable (this is a general table→schema mapper, not
 just banks): set `TABULARMAPPER_ROUTE_PREFIX`, or build the router yourself:
 

{tabularmapper-1.0.1 → tabularmapper-1.0.3}/tests/test_api.py

@@ -107,6 +107,50 @@ def test_map_rejects_non_xlsx(client):
     assert r.status_code == 400
 
 
+def _fuzzy_xlsx_bytes():
+    """A tiny bank sheet whose 'Descriptn' header only fuzzy-matches (score 90)."""
+    from openpyxl import Workbook
+    wb = Workbook(); ws = wb.active
+    ws.append(["Date", "Descriptn", "Debit", "Credit"])
+    ws.append(["01-06-2026", "Coffee", "150", ""])
+    ws.append(["02-06-2026", "Salary", "", "45000"])
+    buf = io.BytesIO(); wb.save(buf); return buf.getvalue()
+
+
+def test_map_threshold_query_changes_mapping(client):
+    payload = _fuzzy_xlsx_bytes()
+
+    # default gate (80): 'Descriptn' (score 90) is accepted as fuzzy
+    r = client.post("/mapper/map", files={"file": ("s.xlsx", io.BytesIO(payload))})
+    cols = {c["raw_header"]: c for c in r.json()["columns"]}
+    assert cols["Descriptn"]["field"] == "description"
+    assert cols["Descriptn"]["method"] == "fuzzy"
+
+    # raise the gate above 90: the same column now falls through -> unmapped
+    r = client.post("/mapper/map", params={"threshold": 95},
+                    files={"file": ("s.xlsx", io.BytesIO(payload))})
+    cols = {c["raw_header"]: c for c in r.json()["columns"]}
+    assert cols["Descriptn"]["field"] is None
+
+
+def test_map_threshold_out_of_range(client):
+    payload = _fuzzy_xlsx_bytes()
+    for bad in (150, -1):
+        r = client.post("/mapper/map", params={"threshold": bad},
+                        files={"file": ("s.xlsx", io.BytesIO(payload))})
+        assert r.status_code == 422       # ge=0 / le=100 validation
+
+
+def test_default_threshold_reads_env(monkeypatch):
+    import tabularmapper.api as api
+    monkeypatch.setenv("TABULARMAPPER_THRESHOLD", "90")
+    assert api._default_threshold() == 90
+    monkeypatch.setenv("TABULARMAPPER_THRESHOLD", "banana")   # invalid -> falls back
+    assert api._default_threshold() == 80
+    monkeypatch.delenv("TABULARMAPPER_THRESHOLD", raising=False)
+    assert api._default_threshold() == 80
+
+
 def test_router_prefix_default_and_custom():
     import tabularmapper.api as api
     assert {r.path for r in api.router.routes} == {