docket-idp 0.1.0__py3-none-any.whl

docket/__init__.py

@@ -0,0 +1,92 @@
+__version__ = "0.1.0"
+
+from .export import (
+    ExportError,
+    export_document,
+    get_exporter,
+    list_exporters,
+    register_exporter,
+    export_to_1c_client_bank,
+    export_to_1c_enterprise_xml,
+    export_to_facturae_xml,
+    export_to_quickbooks_iif,
+    export_to_quickbooks_json,
+    export_to_sap_idoc,
+    export_to_sap_journal_csv,
+    export_to_ubl_xml,
+    export_to_xero_csv,
+    export_to_xero_json,
+    export_to_zugferd_xml,
+)
+from .matching import (
+    match_invoice_to_po,
+    match_invoices_to_contract,
+    match_receipt_to_transactions,
+    match_three_way,
+)
+from .forensics import analyze_document_forensics
+from .pipeline import process
+from .schemas import (
+    AcceptanceAct,
+    BankStatement,
+    BankTransaction,
+    Contract,
+    Discrepancy,
+    DiscrepancyType,
+    DocType,
+    DocumentForensicReport,
+    HandwrittenAnnotation,
+    Invoice,
+    MatchingStatus,
+    MatchResult,
+    PipelineResult,
+    PurchaseOrder,
+    Receipt,
+    SignatureDetection,
+    StampDetection,
+    Waybill,
+)
+
+__all__ = [
+    "__version__",
+    "process",
+    "export_document",
+    "ExportError",
+    "get_exporter",
+    "list_exporters",
+    "register_exporter",
+    "AcceptanceAct",
+    "BankStatement",
+    "BankTransaction",
+    "Contract",
+    "Discrepancy",
+    "DiscrepancyType",
+    "DocType",
+    "Invoice",
+    "MatchingStatus",
+    "MatchResult",
+    "PipelineResult",
+    "PurchaseOrder",
+    "Receipt",
+    "Waybill",
+    "match_invoice_to_po",
+    "match_invoices_to_contract",
+    "match_receipt_to_transactions",
+    "match_three_way",
+    "export_to_1c_client_bank",
+    "export_to_1c_enterprise_xml",
+    "export_to_facturae_xml",
+    "export_to_quickbooks_iif",
+    "export_to_quickbooks_json",
+    "export_to_sap_idoc",
+    "export_to_sap_journal_csv",
+    "export_to_ubl_xml",
+    "export_to_xero_csv",
+    "export_to_xero_json",
+    "export_to_zugferd_xml",
+    "analyze_document_forensics",
+    "DocumentForensicReport",
+    "StampDetection",
+    "SignatureDetection",
+    "HandwrittenAnnotation",
+]

docket/amounts.py

@@ -0,0 +1,68 @@
+"""Money parsing that survives crossing a border.
+
+`1.234,56` and `1,234.56` are the same amount written by a Spaniard and an
+American. Parsing one convention and hoping is how a validation layer ends
+up confidently comparing 25926.0 against 259.26 — which is exactly what
+this pipeline did before this module existed.
+
+Nothing here guesses a locale from the document. The convention is decided
+per number, from the number's own shape, because a single document can
+legitimately mix them (an English-language invoice issued in Barcelona) and
+because a locale guess is one more thing that can be silently wrong.
+"""
+from __future__ import annotations
+
+import re
+
+# A run of digits that may carry grouping and decimal marks. The lookarounds
+# keep it from biting into longer alphanumeric tokens — an IBAN or an order
+# number is not an amount.
+MONEY_RE = re.compile(r"(?<![\w.,])(\d[\d.,]*\d|\d)(?![\w])")
+
+
+def parse_amount(raw: str) -> float | None:
+    """Parse one money-looking token into a float, or None if it isn't one.
+
+    The rules, in order:
+      - both separators present -> whichever comes last is the decimal point
+        ("1.234,56" -> 1234.56, "1,234.56" -> 1234.56)
+      - one separator, exactly three digits after it, and nothing else that
+        looks decimal -> grouping ("1.234" and "1,234" are both 1234)
+      - one separator otherwise -> decimal point ("259,26" -> 259.26)
+    """
+    token = raw.strip().replace(" ", "").replace(" ", "")
+    if not token or not token[0].isdigit() or not token[-1].isdigit():
+        return None
+    if not re.fullmatch(r"[\d.,]+", token):
+        return None
+
+    has_dot, has_comma = "." in token, "," in token
+
+    if has_dot and has_comma:
+        decimal_sep = "." if token.rindex(".") > token.rindex(",") else ","
+        grouping_sep = "," if decimal_sep == "." else "."
+        token = token.replace(grouping_sep, "").replace(decimal_sep, ".")
+    elif has_dot or has_comma:
+        sep = "." if has_dot else ","
+        if token.count(sep) > 1:
+            token = token.replace(sep, "")  # 1.234.567 -> grouping only
+        else:
+            _, _, tail = token.partition(sep)
+            # Three trailing digits is grouping; two (or one, or four+) is a
+            # decimal fraction. Currencies don't group to three decimals.
+            token = token.replace(sep, "" if len(tail) == 3 else ".")
+
+    try:
+        return float(token)
+    except ValueError:
+        return None
+
+
+def amounts_in(text: str) -> list[float]:
+    """Every parseable money amount in a string, in order of appearance."""
+    values = []
+    for match in MONEY_RE.finditer(text):
+        value = parse_amount(match.group(1))
+        if value is not None:
+            values.append(value)
+    return values

docket/api.py

@@ -0,0 +1,212 @@
+"""FastAPI service with bounded concurrency, durable jobs and review workflow.
+
+Run it with `docket-api` (installed by `pip install "docket[api]"`) or
+`uvicorn docket.api:app`.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import Depends, FastAPI, File, Header, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from starlette.concurrency import run_in_threadpool
+
+from . import __version__, config, job_store, review_queue
+from .logging_setup import configure, get_logger
+from .pdf import page_count
+from .pipeline import process
+from .schemas import PipelineResult
+
+configure()
+log = get_logger()
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    for job in job_store.unfinished():
+        _schedule(job["job_id"])
+    yield
+
+
+app = FastAPI(
+    title="docket",
+    description="Extract, classify and validate structured data from business documents.",
+    version=__version__,
+    lifespan=lifespan,
+)
+
+_SUPPORTED_SUFFIXES = {".pdf", ".png", ".jpg", ".jpeg", ".tiff", ".bmp", ".txt", ".md"}
+_job_slots = asyncio.Semaphore(config.MAX_CONCURRENT_JOBS)
+_active_tasks: set[asyncio.Task] = set()
+_active_by_id: dict[str, asyncio.Task] = {}
+
+
+class ReviewUpdate(BaseModel):
+    status: str
+    corrections: dict | None = None
+    actor: str = "reviewer"
+    note: str | None = None
+
+
+def require_api_key(
+    authorization: str | None = Header(default=None),
+    x_api_key: str | None = Header(default=None),
+) -> None:
+    if config.API_KEY is None:
+        return
+    bearer = authorization.removeprefix("Bearer ") if authorization else None
+    if x_api_key != config.API_KEY and bearer != config.API_KEY:
+        raise HTTPException(401, "missing or invalid API key")
+
+
+async def _save_upload(file: UploadFile) -> Path:
+    suffix = Path(file.filename or "").suffix.lower()
+    if suffix not in _SUPPORTED_SUFFIXES:
+        raise HTTPException(400, f"unsupported file type: {suffix!r}")
+    config.JOB_UPLOADS_DIR.mkdir(parents=True, exist_ok=True)
+    path = config.JOB_UPLOADS_DIR / f"{uuid4().hex}{suffix}"
+    size = 0
+    try:
+        with path.open("wb") as handle:
+            while chunk := await file.read(1024 * 1024):
+                size += len(chunk)
+                if size > config.MAX_FILE_BYTES:
+                    raise HTTPException(413, f"file exceeds {config.MAX_FILE_BYTES} byte limit")
+                handle.write(chunk)
+        if suffix == ".pdf":
+            pages = page_count(path)
+            if pages > config.MAX_PDF_PAGES:
+                raise HTTPException(
+                    413, f"PDF has {pages} pages; limit is {config.MAX_PDF_PAGES}"
+                )
+        return path
+    except Exception:
+        path.unlink(missing_ok=True)
+        raise
+
+
+async def _run_job(job_id: str) -> dict:
+    job = job_store.get(job_id)
+    if job is None:
+        raise KeyError(job_id)
+    if job["status"] == "completed":
+        return job
+    async with _job_slots:
+        job_store.update(job_id, status="running", error=None)
+        try:
+            result = await run_in_threadpool(process, Path(job["path"]))
+        except Exception as exc:  # noqa: BLE001
+            log.exception("pipeline failed", extra={"job_id": job_id})
+            return job_store.update(job_id, status="failed", error=f"{type(exc).__name__}: {exc}")
+        return job_store.update(
+            job_id, status="completed", result=result.model_dump(mode="json"), error=None
+        )
+
+
+def _schedule(job_id: str) -> asyncio.Task:
+    existing = _active_by_id.get(job_id)
+    if existing is not None and not existing.done():
+        return existing
+    task = asyncio.create_task(_run_job(job_id))
+    _active_tasks.add(task)
+    _active_by_id[job_id] = task
+
+    def _finished(done: asyncio.Task) -> None:
+        _active_tasks.discard(done)
+        _active_by_id.pop(job_id, None)
+
+    task.add_done_callback(_finished)
+    return task
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.post("/process", response_model=PipelineResult, dependencies=[Depends(require_api_key)])
+async def process_document(
+    file: UploadFile = File(...),
+    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
+) -> PipelineResult:
+    path = await _save_upload(file)
+    job = job_store.create(path, file.filename or path.name, idempotency_key=idempotency_key)
+    if Path(job["path"]) != path:
+        path.unlink(missing_ok=True)
+    job = await _schedule(job["job_id"])
+    if job["status"] != "completed":
+        raise HTTPException(500, f"pipeline failed: {job['error']}")
+    return PipelineResult.model_validate(job["result"])
+
+
+@app.post("/jobs", status_code=202, dependencies=[Depends(require_api_key)])
+async def create_job(
+    file: UploadFile = File(...),
+    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
+) -> dict:
+    path = await _save_upload(file)
+    job = job_store.create(path, file.filename or path.name, idempotency_key=idempotency_key)
+    if Path(job["path"]) != path:
+        path.unlink(missing_ok=True)
+    if job["status"] in {"queued", "running"}:
+        _schedule(job["job_id"])
+    return job
+
+
+@app.get("/jobs/{job_id}", dependencies=[Depends(require_api_key)])
+def get_job(job_id: str) -> dict:
+    job = job_store.get(job_id)
+    if job is None:
+        raise HTTPException(404, "job not found")
+    return job
+
+
+@app.get("/review-queue", dependencies=[Depends(require_api_key)])
+def get_review_queue() -> list[dict]:
+    return review_queue.list_pending()
+
+
+@app.get("/review-queue/{document_id}", dependencies=[Depends(require_api_key)])
+def get_review(document_id: str) -> dict:
+    record = review_queue.get(document_id)
+    if record is None:
+        raise HTTPException(404, "review record not found")
+    return record
+
+
+@app.get("/review-queue/{document_id}/original", dependencies=[Depends(require_api_key)])
+def get_review_original(document_id: str) -> FileResponse:
+    record = review_queue.get(document_id)
+    if record is None or not record.get("original_path"):
+        raise HTTPException(404, "preserved original not found")
+    path = Path(record["original_path"])
+    if not path.is_file():
+        raise HTTPException(404, "preserved original not found")
+    return FileResponse(path, filename=path.name)
+
+
+@app.patch("/review-queue/{document_id}", dependencies=[Depends(require_api_key)])
+def update_review(document_id: str, update: ReviewUpdate) -> dict:
+    try:
+        return review_queue.update(document_id, **update.model_dump())
+    except KeyError as exc:
+        raise HTTPException(404, "review record not found") from exc
+    except ValueError as exc:
+        raise HTTPException(422, str(exc)) from exc
+
+
+def run() -> None:
+    """Console entry point: `docket-api [--host H] [--port P]`."""
+    import argparse
+
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Run the docket HTTP API.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    uvicorn.run(app, host=args.host, port=args.port)