tabularmapper 1.0.2__tar.gz → 1.0.4__tar.gz

{tabularmapper-1.0.2/src/tabularmapper.egg-info → tabularmapper-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabularmapper
-Version: 1.0.2
+Version: 1.0.4
 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
@@ -165,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 |
@@ -272,6 +273,7 @@ app.include_router(router)
 |---|---|---|
 | `POST` | `/mapper/map` | upload an `.xlsx`, get the mapping + rows (JSON) |
 | `GET` | `/mapper/health` | `{status, ai_enabled}` |
+| `GET` | `/mapper/config` | config-builder web page — design a schema, export `config.json` |
 | `GET` | `/mapper/learn/pending` | debit/credit synonyms awaiting approval |
 | `POST` | `/mapper/learn/approve` | approve a pending synonym (`?phrase=&field=`) |
 | `POST` | `/mapper/learn/reject` | reject a pending synonym |
@@ -280,6 +282,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.2 → tabularmapper-1.0.4}/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 |
@@ -232,6 +233,7 @@ app.include_router(router)
 |---|---|---|
 | `POST` | `/mapper/map` | upload an `.xlsx`, get the mapping + rows (JSON) |
 | `GET` | `/mapper/health` | `{status, ai_enabled}` |
+| `GET` | `/mapper/config` | config-builder web page — design a schema, export `config.json` |
 | `GET` | `/mapper/learn/pending` | debit/credit synonyms awaiting approval |
 | `POST` | `/mapper/learn/approve` | approve a pending synonym (`?phrase=&field=`) |
 | `POST` | `/mapper/learn/reject` | reject a pending synonym |
@@ -240,6 +242,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.2 → tabularmapper-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabularmapper"
-version = "1.0.2"
+version = "1.0.4"
 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"
@@ -55,6 +55,11 @@ tabularmapper = "tabularmapper.cli:main"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+# Ship the config-builder page inside the wheel so GET /mapper/config works
+# from a pip-installed package (not just a source checkout).
+[tool.setuptools.package-data]
+tabularmapper = ["static/*.html"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

{tabularmapper-1.0.2 → tabularmapper-1.0.4}/src/tabularmapper/__init__.py

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

{tabularmapper-1.0.2 → tabularmapper-1.0.4}/src/tabularmapper/api.py

@@ -31,11 +31,12 @@ from __future__ import annotations
 import os
 from contextlib import asynccontextmanager
 from enum import Enum
+from importlib.resources import as_file, files
 from typing import Any, Optional
 
 from fastapi import APIRouter, FastAPI, File, HTTPException, Query, UploadFile
 from fastapi.concurrency import run_in_threadpool
-from fastapi.responses import Response
+from fastapi.responses import HTMLResponse, Response
 from pydantic import BaseModel
 
 from . import engine                    # imported as a module so OUTPUT_SCHEMA is read
@@ -45,6 +46,17 @@ 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)
@@ -128,6 +140,18 @@ async def health() -> dict:
     return {"status": "ok", "ai_enabled": state.matcher is not None}
 
 
+async def config_page() -> HTMLResponse:
+    """Serve the self-contained config-builder page bundled at
+    tabularmapper/static/index.html. Uses importlib.resources so it works even
+    when the package is imported from a zip/egg, not only an unpacked wheel."""
+    try:
+        resource = files("tabularmapper").joinpath("static", "index.html")
+        with as_file(resource) as path:
+            return HTMLResponse(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, ModuleNotFoundError):
+        raise HTTPException(status_code=404, detail="config builder page not found")
+
+
 async def map_statement(
     file: UploadFile = File(...),
     format: OutFormat = Query(
@@ -136,6 +160,13 @@ async def map_statement(
                     ".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.
 
@@ -143,18 +174,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
@@ -216,6 +251,8 @@ def make_router(prefix: Optional[str] = None, tags: Optional[list] = None) -> AP
         prefix = os.getenv("TABULARMAPPER_ROUTE_PREFIX", "/mapper")
     r = APIRouter(prefix=prefix.rstrip("/"), tags=tags or ["mapper"])
     r.add_api_route("/health", health, methods=["GET"])
+    r.add_api_route("/config", config_page, methods=["GET"],
+                    response_class=HTMLResponse, include_in_schema=False)
     r.add_api_route("/map", map_statement, methods=["POST"], response_model=MapResponse)
     r.add_api_route("/learn/pending", learn_pending, methods=["GET"])
     r.add_api_route("/learn/approve", learn_approve, methods=["POST"])

{tabularmapper-1.0.2 → tabularmapper-1.0.4}/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.2 → tabularmapper-1.0.4}/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.4/src/tabularmapper/static/index.html

@@ -0,0 +1,565 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Tabular Mapper</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script>
+        tailwind.config = {
+            theme: {
+                extend: {
+                    colors: {
+                        brand: {
+                            DEFAULT: '#ED0E4C',
+                            dark: '#C90B40',
+                            tint: '#FDE7EE',
+                        },
+                    },
+                },
+            },
+        };
+    </script>
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css" rel="stylesheet">
+    <style>
+        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
+        body {
+            font-family: 'Inter', system-ui, sans-serif;
+            background-color: #f7f8fa;
+        }
+
+        .code-font {
+            font-family: ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, monospace;
+        }
+
+        ::-webkit-scrollbar {
+            width: 8px;
+            height: 8px;
+        }
+        ::-webkit-scrollbar-track {
+            background: transparent;
+        }
+        ::-webkit-scrollbar-thumb {
+            background: #d4d7dd;
+            border-radius: 4px;
+        }
+        ::-webkit-scrollbar-thumb:hover {
+            background: #b9bdc6;
+        }
+        .code-panel ::-webkit-scrollbar-thumb {
+            background: #2a2f3a;
+        }
+        .code-panel ::-webkit-scrollbar-thumb:hover {
+            background: #3a404d;
+        }
+    </style>
+</head>
+<body class="h-screen flex flex-col overflow-hidden text-slate-800">
+
+    <!-- Header -->
+    <header class="bg-white border-b border-slate-200 h-14 flex items-center justify-between px-6 shrink-0">
+        <div class="flex items-center gap-2.5">
+            <div class="bg-brand text-white w-8 h-8 flex items-center justify-center rounded-lg">
+                <i class="fa-solid fa-layer-group text-sm"></i>
+            </div>
+            <div>
+                <h1 class="font-semibold text-[15px] leading-tight text-slate-900">Tabular Mapper</h1>
+                <p class="text-[11px] text-slate-400 leading-tight">xlsx mapping config</p>
+            </div>
+        </div>
+        <div class="flex items-center gap-2">
+            <input type="file" id="import-file" accept=".json,application/json" class="hidden" onchange="app.importFromFile(event)">
+            <button onclick="app.loadSample()" class="px-3 py-1.5 text-[13px] font-medium text-slate-600 border border-slate-200 rounded-lg hover:bg-slate-50 transition-colors">
+                <i class="fa-solid fa-table-list mr-1.5 text-xs"></i>Load sample
+            </button>
+            <button onclick="document.getElementById('import-file').click()" class="px-3 py-1.5 text-[13px] font-medium text-slate-600 border border-slate-200 rounded-lg hover:bg-slate-50 transition-colors">
+                <i class="fa-solid fa-upload mr-1.5 text-xs"></i>Import
+            </button>
+            <button onclick="app.exportToFile()" class="px-3 py-1.5 text-[13px] font-medium text-white bg-brand hover:bg-brand-dark rounded-lg transition-colors">
+                <i class="fa-solid fa-download mr-1.5 text-xs"></i>Export
+            </button>
+        </div>
+    </header>
+
+    <!-- Main Content -->
+    <div class="flex flex-1 overflow-hidden">
+
+        <!-- Left Panel: Editor -->
+        <div class="flex-1 flex flex-col min-w-0 overflow-y-auto">
+            <div class="p-6 max-w-4xl mx-auto w-full space-y-6 pb-16">
+
+                <!-- Fields -->
+                <section class="bg-white rounded-xl border border-slate-200 shadow-sm overflow-hidden">
+                    <div class="px-5 py-3.5 border-b border-slate-100 flex justify-between items-center">
+                        <div>
+                            <h2 class="font-semibold text-sm text-slate-800">Fields</h2>
+                            <p class="text-xs text-slate-400 mt-0.5">Header, type, description, synonyms, and the critical flag — all in one place.</p>
+                        </div>
+                        <button onclick="app.addField()" class="text-xs font-medium text-slate-600 border border-slate-200 px-2.5 py-1.5 rounded-lg hover:bg-slate-50 hover:text-brand hover:border-brand/40 transition-colors">
+                            <i class="fa-solid fa-plus mr-1 text-[10px]"></i>Add field
+                        </button>
+                    </div>
+
+                    <div class="p-5 space-y-3" id="fields-container"></div>
+
+                    <div id="add-field-footer" class="hidden px-5 pb-5">
+                        <button onclick="app.addField()" class="w-full py-2 border border-dashed border-slate-300 rounded-lg text-slate-500 text-[13px] font-medium hover:border-brand/50 hover:text-brand transition-colors">
+                            <i class="fa-solid fa-plus mr-1 text-[10px]"></i>Add field
+                        </button>
+                    </div>
+
+                    <div id="empty-state-schema" class="hidden py-14 text-center">
+                        <div class="inline-flex items-center justify-center w-10 h-10 rounded-full bg-slate-100 mb-3">
+                            <i class="fa-solid fa-table-list text-slate-400 text-sm"></i>
+                        </div>
+                        <p class="text-slate-500 text-sm mb-4">No schema loaded yet.</p>
+                        <div class="flex items-center justify-center gap-2">
+                            <button onclick="app.loadSample()" class="text-[13px] font-medium bg-brand hover:bg-brand-dark text-white px-3.5 py-1.5 rounded-lg transition-colors">Load sample data</button>
+                            <button onclick="document.getElementById('import-file').click()" class="text-[13px] font-medium text-slate-600 border border-slate-200 px-3.5 py-1.5 rounded-lg hover:bg-slate-50 transition-colors">Import schema.json</button>
+                            <button onclick="app.addField()" class="text-[13px] font-medium text-slate-600 border border-slate-200 px-3.5 py-1.5 rounded-lg hover:bg-slate-50 transition-colors">Start blank</button>
+                        </div>
+                    </div>
+                </section>
+
+                <!-- Require Any -->
+                <section class="bg-white rounded-xl border border-slate-200 shadow-sm overflow-hidden">
+                    <div class="px-5 py-3.5 border-b border-slate-100">
+                        <h2 class="font-semibold text-sm text-slate-800">Require any</h2>
+                        <p class="text-xs text-slate-400 mt-0.5">At least one field from each group must exist in the output.</p>
+                    </div>
+                    <div class="p-5 space-y-3" id="require-any-container"></div>
+                    <div class="px-5 pb-5">
+                        <button onclick="app.addRequireAnyGroup()" class="w-full py-2 border border-dashed border-slate-300 rounded-lg text-slate-500 text-[13px] font-medium hover:border-brand/50 hover:text-brand transition-colors">
+                            <i class="fa-solid fa-plus mr-1 text-[10px]"></i>Add group
+                        </button>
+                    </div>
+                </section>
+
+            </div>
+        </div>
+
+        <!-- Right Panel: Preview -->
+        <div class="code-panel w-[420px] bg-[#0d1117] flex flex-col shrink-0 border-l border-slate-200">
+            <div class="px-4 py-2.5 border-b border-white/10 flex justify-between items-center">
+                <span class="text-xs font-mono text-slate-400 code-font">schema.json</span>
+                <button onclick="app.copyToClipboard()" class="text-xs font-medium text-slate-300 border border-white/15 px-2.5 py-1 rounded-md hover:bg-white/10 transition-colors">
+                    <i class="fa-regular fa-copy mr-1.5 text-[10px]"></i>Copy
+                </button>
+            </div>
+            <div class="flex-1 overflow-auto p-4">
+                <pre class="code-font text-[13px] leading-relaxed"><code id="json-preview" class="text-slate-200"></code></pre>
+            </div>
+            <div class="px-4 py-2 border-t border-white/10 text-xs text-slate-500 flex justify-between code-font">
+                <span>live preview</span>
+                <span id="char-count">0 chars</span>
+            </div>
+        </div>
+
+    </div>
+
+    <!-- Toast Notification -->
+    <div id="toast" class="fixed bottom-6 right-6 bg-slate-800 text-white px-4 py-2.5 rounded-lg shadow-lg transform translate-y-20 opacity-0 transition-all duration-300 flex items-center gap-2.5 z-50 text-sm">
+        <i class="fa-solid fa-circle-check text-brand"></i>
+        <span id="toast-message">Action Successful</span>
+    </div>
+
+    <script>
+        const DEFAULT_DATA = {
+            "output_schema": [
+                {
+                    "field": "date",
+                    "header": "Date",
+                    "type": "date",
+                    "description": "The date the transaction was posted or executed. May appear as transaction date, value date, or posting date in source data — these can differ by 1-2 days for the same transaction; prefer transaction/posting date over value date unless the source only provides one."
+                },
+                {
+                    "field": "narration",
+                    "header": "Narration",
+                    "type": "string",
+                    "description": "Free-text description of the transaction, such as the payee, purpose, or transaction type (e.g., 'NEFT TRANSFER TO XYZ', 'ATM WITHDRAWAL'). Often the longest and most variably formatted field in the source; do not truncate or attempt to parse structured data out of it unless separately instructed."
+                },
+                {
+                    "field": "reference_number",
+                    "header": "Reference Number",
+                    "type": "string",
+                    "description": "A unique identifier for the transaction, such as a cheque number, UTR, RRN, or transaction ID. Frequently blank for cash, UPI, or POS transactions — absence is normal and should not be treated as a mapping failure."
+                },
+                {
+                    "field": "debit",
+                    "header": "Debit",
+                    "type": "currency",
+                    "description": "Amount withdrawn or paid out in this transaction. Should be blank or zero if the transaction is a credit. Strip currency symbols and thousand separators before parsing to numeric."
+                },
+                {
+                    "field": "credit",
+                    "header": "Credit",
+                    "type": "currency",
+                    "description": "Amount deposited or received in this transaction. Should be blank or zero if the transaction is a debit. Strip currency symbols and thousand separators before parsing to numeric."
+                }
+            ],
+            "synonyms": {
+                "date": ["date", "txn date", "transaction date", "value date", "posting date", "entry date", "book date", "date of transaction", "trans date", "value dt", "txn dt", "date/time", "date & time"],
+                "narration": ["narration", "description", "particulars", "transaction details", "transaction description", "details", "remarks", "memo", "transaction narration", "particulars/remarks", "desc", "transaction particulars", "purpose", "comments", "notes"],
+                "reference_number": ["reference number", "ref no", "ref number", "reference no", "reference", "cheque no", "cheque number", "chq no", "chq number", "instrument no", "instrument number", "transaction id", "txn id", "transaction reference", "transaction ref no", "utr", "utr no", "utr number", "rrn", "rrn number", "cheque/ref no", "cheque/ref number", "doc no", "document number", "voucher no", "voucher number", "receipt no", "receipt number", "transaction reference number"],
+                "debit": ["debit", "debit amount", "debit amt", "withdrawal", "withdrawal amount", "withdrawal amt", "dr", "dr amount", "amount debited", "amount withdrawn", "paid out", "debit (dr)", "debit(dr)", "outflow", "money out", "payment", "debits"],
+                "credit": ["credit", "credit amount", "credit amt", "deposit", "deposit amount", "deposit amt", "cr", "cr amount", "amount credited", "amount deposited", "paid in", "credit (cr)", "credit(cr)", "inflow", "money in", "receipt", "credits"]
+            },
+            "critical_fields": ["date", "narration"],
+            "require_any": [
+                ["debit", "credit"]
+            ]
+        };
+
+        class SchemaApp {
+            constructor() {
+                this.data = SchemaApp.emptyData();
+                this.init();
+            }
+
+            static emptyData() {
+                return { output_schema: [], synonyms: {}, critical_fields: [], require_any: [] };
+            }
+
+            static normalize(obj) {
+                obj = obj || {};
+                return {
+                    output_schema: Array.isArray(obj.output_schema) ? obj.output_schema : [],
+                    synonyms: (obj.synonyms && typeof obj.synonyms === 'object' && !Array.isArray(obj.synonyms)) ? obj.synonyms : {},
+                    critical_fields: Array.isArray(obj.critical_fields) ? obj.critical_fields : [],
+                    require_any: Array.isArray(obj.require_any) ? obj.require_any : [],
+                };
+            }
+
+            init() {
+                this.renderFields();
+                this.renderRequireAny();
+                this.updatePreview();
+            }
+
+            // --- Core Logic ---
+
+            getJSON() {
+                return this.data;
+            }
+
+            updatePreview() {
+                const json = JSON.stringify(this.data, null, 2);
+                document.getElementById('json-preview').textContent = json;
+                document.getElementById('char-count').textContent = `${json.length} chars`;
+            }
+
+            showToast(msg) {
+                const toast = document.getElementById('toast');
+                document.getElementById('toast-message').textContent = msg;
+                toast.classList.remove('translate-y-20', 'opacity-0');
+                setTimeout(() => {
+                    toast.classList.add('translate-y-20', 'opacity-0');
+                }, 3000);
+            }
+
+            loadSample() {
+                if (this.data.output_schema.length && !confirm("Load sample schema? This replaces the current schema.")) return;
+                this.data = JSON.parse(JSON.stringify(DEFAULT_DATA));
+                this.init();
+                this.showToast("Sample schema loaded");
+            }
+
+            importFromFile(event) {
+                const file = event.target.files[0];
+                if (!file) return;
+                const reader = new FileReader();
+                reader.onload = (e) => {
+                    try {
+                        this.data = SchemaApp.normalize(JSON.parse(e.target.result));
+                        this.init();
+                        this.showToast(`Imported ${file.name}`);
+                    } catch (err) {
+                        this.showToast("Could not import — not valid JSON");
+                    }
+                };
+                reader.readAsText(file);
+                event.target.value = '';
+            }
+
+            exportToFile() {
+                const json = JSON.stringify(this.data, null, 2);
+                const blob = new Blob([json], { type: 'application/json' });
+                const url = URL.createObjectURL(blob);
+                const a = document.createElement('a');
+                a.href = url;
+                a.download = 'schema.json';
+                document.body.appendChild(a);
+                a.click();
+                document.body.removeChild(a);
+                URL.revokeObjectURL(url);
+                this.showToast("schema.json exported");
+            }
+
+            copyToClipboard() {
+                navigator.clipboard.writeText(JSON.stringify(this.data, null, 2)).then(() => {
+                    this.showToast("JSON copied to clipboard");
+                });
+            }
+
+            // --- Fields (schema + synonyms + critical, unified) ---
+
+            renderFields() {
+                const container = document.getElementById('fields-container');
+                const empty = document.getElementById('empty-state-schema');
+                const footer = document.getElementById('add-field-footer');
+                container.innerHTML = '';
+
+                if (this.data.output_schema.length === 0) {
+                    empty.classList.remove('hidden');
+                    container.classList.add('hidden');
+                    footer.classList.add('hidden');
+                    return;
+                }
+                empty.classList.add('hidden');
+                container.classList.remove('hidden');
+                footer.classList.remove('hidden');
+
+                this.data.output_schema.forEach((field, index) => {
+                    const name = field.field;
+                    if (!this.data.synonyms[name]) this.data.synonyms[name] = [];
+                    const syns = this.data.synonyms[name];
+                    const isCritical = this.data.critical_fields.includes(name);
+
+                    const synTags = syns.map((syn, i) => `
+                        <span class="inline-flex items-center bg-white border border-slate-200 text-slate-600 text-xs px-2 py-0.5 rounded-md mr-1.5 mb-1.5">
+                            ${syn}
+                            <button onclick="app.removeSynonym('${name}', ${i})" class="ml-1.5 text-slate-300 hover:text-brand focus:outline-none">
+                                <i class="fa-solid fa-xmark text-[10px]"></i>
+                            </button>
+                        </span>`).join('');
+
+                    const card = document.createElement('div');
+                    card.className = "bg-slate-50 rounded-lg border border-slate-200 p-3.5";
+                    card.innerHTML = `
+                        <div class="flex flex-wrap items-center gap-2">
+                            <span class="text-xs text-slate-300 tabular-nums w-4 text-center shrink-0">${index + 1}</span>
+                            <input type="text" value="${field.field}" placeholder="field_id"
+                                onchange="app.updateField(${index}, 'field', this.value)"
+                                class="flex-1 min-w-[140px] bg-white border border-slate-300 rounded-md px-2.5 py-1.5 text-[13px] font-medium text-slate-700 outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 transition-colors">
+                            <input type="text" value="${field.header}" placeholder="Header"
+                                onchange="app.updateField(${index}, 'header', this.value)"
+                                class="flex-1 min-w-[140px] bg-white border border-slate-300 rounded-md px-2.5 py-1.5 text-[13px] text-slate-600 outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 transition-colors">
+                            <select onchange="app.updateField(${index}, 'type', this.value)"
+                                class="w-28 shrink-0 bg-white border border-slate-300 rounded-md px-2 py-1.5 text-[13px] text-slate-600 outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 cursor-pointer">
+                                <option value="string" ${field.type === 'string' ? 'selected' : ''}>string</option>
+                                <option value="date" ${field.type === 'date' ? 'selected' : ''}>date</option>
+                                <option value="currency" ${field.type === 'currency' ? 'selected' : ''}>currency</option>
+                                <option value="number" ${field.type === 'number' ? 'selected' : ''}>number</option>
+                                <option value="boolean" ${field.type === 'boolean' ? 'selected' : ''}>boolean</option>
+                            </select>
+                            <button onclick="app.toggleCritical('${name}')" title="Critical: must be present in the output"
+                                class="shrink-0 border text-[11px] font-medium px-2 py-1.5 rounded-md transition-colors ${isCritical ? 'bg-brand-tint text-brand border-brand/30' : 'bg-white text-slate-400 border-slate-200 hover:text-slate-600'}">
+                                <i class="fa-${isCritical ? 'solid' : 'regular'} fa-star text-[10px] mr-1"></i>Critical
+                            </button>
+                            <button onclick="app.removeField(${index})" title="Remove field"
+                                class="shrink-0 text-slate-300 hover:text-brand transition-colors p-1.5 rounded">
+                                <i class="fa-solid fa-trash-can text-xs"></i>
+                            </button>
+                        </div>
+                        <textarea onchange="app.updateField(${index}, 'description', this.value)"
+                            placeholder="Description — what this field means and how to map it"
+                            class="w-full mt-2 bg-white border border-slate-200 rounded-md px-2.5 py-1.5 text-[13px] text-slate-500 outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 transition-colors resize-none overflow-hidden"
+                            oninput="this.style.height=''; this.style.height=this.scrollHeight+'px'">${field.description || ''}</textarea>
+                        <div class="mt-2.5">
+                            <div class="flex items-center justify-between mb-1.5">
+                                <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">Synonyms</span>
+                                <span class="text-[11px] text-slate-400 code-font">${syns.length}</span>
+                            </div>
+                            <div class="flex flex-wrap">${synTags}</div>
+                            <div class="flex gap-2 mt-0.5">
+                                <input type="text" id="synonym-input-${name}" placeholder="Add synonym, press Enter..."
+                                    class="flex-1 bg-white border border-slate-300 text-slate-700 text-[13px] rounded-md focus:outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 px-2.5 py-1.5"
+                                    onkeypress="if(event.key==='Enter') app.addSynonym('${name}')">
+                                <button onclick="app.addSynonym('${name}')"
+                                    class="bg-white border border-slate-300 hover:bg-slate-100 hover:text-brand text-slate-600 rounded-md text-[13px] px-3 py-1.5 transition-colors">
+                                    <i class="fa-solid fa-plus text-xs"></i>
+                                </button>
+                            </div>
+                        </div>
+                    `;
+                    container.appendChild(card);
+                });
+
+                // Auto-size description textareas to fit their content
+                container.querySelectorAll('textarea').forEach(ta => {
+                    ta.style.height = '';
+                    ta.style.height = ta.scrollHeight + 'px';
+                });
+            }
+
+            addField() {
+                this.data.output_schema.push({ field: "new_field", header: "New Field", type: "string", description: "" });
+                this.renderFields();
+                this.renderRequireAny();
+                this.updatePreview();
+                // Focus the new field's id for immediate typing
+                const container = document.getElementById('fields-container');
+                const last = container.lastElementChild;
+                if (last) {
+                    last.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+                    const input = last.querySelector('input');
+                    if (input) { input.focus(); input.select(); }
+                }
+            }
+
+            removeField(index) {
+                const name = this.data.output_schema[index].field;
+                this.data.output_schema.splice(index, 1);
+                delete this.data.synonyms[name];
+                this.data.critical_fields = this.data.critical_fields.filter(f => f !== name);
+                this.data.require_any = this.data.require_any.map(g => g.filter(f => f !== name)).filter(g => g.length > 0);
+                this.renderFields();
+                this.renderRequireAny();
+                this.updatePreview();
+            }
+
+            updateField(index, key, value) {
+                const oldName = this.data.output_schema[index].field;
+                this.data.output_schema[index][key] = value;
+
+                if (key === 'field' && oldName !== value) {
+                    if (this.data.synonyms[oldName]) {
+                        this.data.synonyms[value] = this.data.synonyms[oldName];
+                        delete this.data.synonyms[oldName];
+                    }
+                    this.data.critical_fields = this.data.critical_fields.map(f => f === oldName ? value : f);
+                    this.data.require_any = this.data.require_any.map(g => g.map(f => f === oldName ? value : f));
+                    this.renderFields();
+                    this.renderRequireAny();
+                }
+                this.updatePreview();
+            }
+
+            toggleCritical(field) {
+                const i = this.data.critical_fields.indexOf(field);
+                if (i === -1) this.data.critical_fields.push(field);
+                else this.data.critical_fields.splice(i, 1);
+                this.renderFields();
+                this.updatePreview();
+            }
+
+            // --- Synonyms ---
+
+            addSynonym(field) {
+                const input = document.getElementById(`synonym-input-${field}`);
+                if (!input) return;
+                const value = input.value.trim().toLowerCase();
+                if (!value) return;
+                if (!this.data.synonyms[field]) this.data.synonyms[field] = [];
+                if (this.data.synonyms[field].includes(value)) {
+                    this.showToast("Synonym already exists");
+                    return;
+                }
+                this.data.synonyms[field].push(value);
+                this.renderFields();
+                this.updatePreview();
+                // Refocus the same input for rapid entry
+                const again = document.getElementById(`synonym-input-${field}`);
+                if (again) again.focus();
+            }
+
+            removeSynonym(field, index) {
+                this.data.synonyms[field].splice(index, 1);
+                this.renderFields();
+                this.updatePreview();
+            }
+
+            // --- Require Any ---
+
+            renderRequireAny() {
+                const container = document.getElementById('require-any-container');
+                container.innerHTML = '';
+
+                const currentFields = this.data.output_schema.map(f => f.field);
+
+                if (this.data.require_any.length === 0) {
+                    container.innerHTML = '<p class="text-xs text-slate-400">No groups yet. Add one to require at least one of a set of fields.</p>';
+                    return;
+                }
+
+                this.data.require_any.forEach((group, groupIndex) => {
+                    const groupDiv = document.createElement('div');
+                    groupDiv.className = "bg-slate-50 border border-slate-200 rounded-lg p-3 relative group";
+
+                    let tagsHtml = group.map((field, i) => {
+                        if (!currentFields.includes(field)) return '';
+                        return `
+                        <span class="inline-flex items-center bg-slate-100 text-slate-600 text-xs px-2 py-0.5 rounded-md border border-slate-200 mr-1.5 mb-1.5">
+                            ${field}
+                            <button onclick="app.removeRequireAnyField(${groupIndex}, ${i})" class="ml-1.5 text-slate-400 hover:text-brand">
+                                <i class="fa-solid fa-xmark text-[10px]"></i>
+                            </button>
+                        </span>
+                    `}).join('');
+
+                    let availableFields = currentFields.filter(f => !group.includes(f));
+                    let optionsHtml = availableFields.map(f => `<option value="${f}">${f}</option>`).join('');
+
+                    groupDiv.innerHTML = `
+                        <div class="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity">
+                            <button onclick="app.removeRequireAnyGroup(${groupIndex})" class="text-slate-400 hover:text-brand p-1">
+                                <i class="fa-solid fa-trash-can text-xs"></i>
+                            </button>
+                        </div>
+                        <div class="text-[11px] font-semibold text-slate-400 mb-2 uppercase tracking-wide">Group ${groupIndex + 1}</div>
+                        <div class="flex flex-wrap mb-1.5 min-h-[1.75rem]">
+                            ${tagsHtml}
+                        </div>
+                        <div class="flex gap-2 max-w-md">
+                            <select id="require-any-select-${groupIndex}" class="flex-1 bg-white border border-slate-300 text-slate-700 text-[13px] rounded-lg focus:outline-none focus:border-brand focus:ring-1 focus:ring-brand/20 block px-2.5 py-1.5">
+                                <option value="">Add field...</option>
+                                ${optionsHtml}
+                            </select>
+                            <button onclick="app.addRequireAnyField(${groupIndex})" class="bg-white border border-slate-300 hover:bg-slate-50 hover:text-brand text-slate-600 text-[13px] px-3 py-1.5 rounded-lg transition-colors">
+                                <i class="fa-solid fa-plus text-xs"></i>
+                            </button>
+                        </div>
+                    `;
+                    container.appendChild(groupDiv);
+                });
+            }
+
+            addRequireAnyGroup() {
+                this.data.require_any.push([]);
+                this.renderRequireAny();
+                this.updatePreview();
+            }
+
+            removeRequireAnyGroup(index) {
+                this.data.require_any.splice(index, 1);
+                this.renderRequireAny();
+                this.updatePreview();
+            }
+
+            addRequireAnyField(groupIndex) {
+                const select = document.getElementById(`require-any-select-${groupIndex}`);
+                const value = select.value;
+                if (value) {
+                    this.data.require_any[groupIndex].push(value);
+                    this.renderRequireAny();
+                    this.updatePreview();
+                }
+            }
+
+            removeRequireAnyField(groupIndex, fieldIndex) {
+                this.data.require_any[groupIndex].splice(fieldIndex, 1);
+                if (this.data.require_any[groupIndex].length === 0) {
+                    this.data.require_any.splice(groupIndex, 1);
+                }
+                this.renderRequireAny();
+                this.updatePreview();
+            }
+        }
+
+        // Initialize App
+        const app = new SchemaApp();
+
+    </script>
+</body>
+</html>

{tabularmapper-1.0.2 → tabularmapper-1.0.4/src/tabularmapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabularmapper
-Version: 1.0.2
+Version: 1.0.4
 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
@@ -165,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 |
@@ -272,6 +273,7 @@ app.include_router(router)
 |---|---|---|
 | `POST` | `/mapper/map` | upload an `.xlsx`, get the mapping + rows (JSON) |
 | `GET` | `/mapper/health` | `{status, ai_enabled}` |
+| `GET` | `/mapper/config` | config-builder web page — design a schema, export `config.json` |
 | `GET` | `/mapper/learn/pending` | debit/credit synonyms awaiting approval |
 | `POST` | `/mapper/learn/approve` | approve a pending synonym (`?phrase=&field=`) |
 | `POST` | `/mapper/learn/reject` | reject a pending synonym |
@@ -280,6 +282,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.2 → tabularmapper-1.0.4}/src/tabularmapper.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/tabularmapper.egg-info/dependency_links.txt
 src/tabularmapper.egg-info/entry_points.txt
 src/tabularmapper.egg-info/requires.txt
 src/tabularmapper.egg-info/top_level.txt
+src/tabularmapper/static/index.html
 tests/test_api.py
 tests/test_learn.py
 tests/test_mapper.py

{tabularmapper-1.0.2 → tabularmapper-1.0.4}/tests/test_api.py

@@ -107,10 +107,61 @@ 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_config_page_served(client):
+    r = client.get("/mapper/config")
+    assert r.status_code == 200
+    assert r.headers["content-type"].startswith("text/html")
+    assert "<!DOCTYPE html>" in r.text or "<html" in r.text.lower()
+
+
 def test_router_prefix_default_and_custom():
     import tabularmapper.api as api
     assert {r.path for r in api.router.routes} == {
-        "/mapper/health", "/mapper/map",
+        "/mapper/health", "/mapper/config", "/mapper/map",
         "/mapper/learn/pending", "/mapper/learn/approve", "/mapper/learn/reject"}
     custom = api.make_router("/catalog/")
     assert "/catalog/map" in {r.path for r in custom.routes}