docintel-platform 1.0.2__py3-none-any.whl

docintel/ops/metrics.py

@@ -0,0 +1,57 @@
+"""In-process request metrics (per worker in multi-process deployments)."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MetricsStore:
+    """Thread-safe counters for HTTP request observability."""
+
+    total_requests: int = 0
+    total_errors: int = 0
+    total_latency_ms: float = 0.0
+    requests_by_endpoint: dict[str, int] = field(default_factory=dict)
+    requests_by_status: dict[str, int] = field(default_factory=dict)
+    latency_by_endpoint_ms: dict[str, float] = field(default_factory=dict)
+    started_at: float = field(default_factory=time.time)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def record(self, endpoint: str, status_code: int, duration_ms: float) -> None:
+        key = endpoint or "unknown"
+        status = str(status_code)
+        with self._lock:
+            self.total_requests += 1
+            if status_code >= 400:
+                self.total_errors += 1
+            self.total_latency_ms += duration_ms
+            self.requests_by_endpoint[key] = self.requests_by_endpoint.get(key, 0) + 1
+            self.requests_by_status[status] = self.requests_by_status.get(status, 0) + 1
+            self.latency_by_endpoint_ms[key] = (
+                self.latency_by_endpoint_ms.get(key, 0.0) + duration_ms
+            )
+
+    def snapshot(self) -> dict[str, Any]:
+        uptime_seconds = max(time.time() - self.started_at, 0.001)
+        with self._lock:
+            total = self.total_requests
+            avg_latency = self.total_latency_ms / total if total else 0.0
+            return {
+                "total_requests": total,
+                "total_errors": self.total_errors,
+                "avg_latency_ms": round(avg_latency, 2),
+                "requests_per_second": round(total / uptime_seconds, 4),
+                "uptime_seconds": round(uptime_seconds, 2),
+                "requests_by_endpoint": dict(self.requests_by_endpoint),
+                "requests_by_status": dict(self.requests_by_status),
+                "latency_by_endpoint_ms": {
+                    key: round(value, 2) for key, value in self.latency_by_endpoint_ms.items()
+                },
+            }
+
+
+metrics_store = MetricsStore()

docintel/ops/middleware.py

@@ -0,0 +1,40 @@
+"""Request instrumentation hooks."""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from flask import Flask, g, request
+
+from docintel.ops.metrics import metrics_store
+
+logger = logging.getLogger("docintel.request")
+
+
+def register_request_hooks(app: Flask) -> None:
+  """Attach timing, logging, and metrics collection to each request."""
+
+  @app.before_request
+  def _start_timer() -> None:
+    g.request_start = time.perf_counter()
+
+  @app.after_request
+  def _record_request(response):
+    start = getattr(g, "request_start", None)
+    duration_ms = (time.perf_counter() - start) * 1000 if start is not None else 0.0
+    endpoint = request.endpoint or request.path
+
+    metrics_store.record(endpoint, response.status_code, duration_ms)
+
+    logger.info(
+      "request completed",
+      extra={
+        "method": request.method,
+        "path": request.path,
+        "endpoint": endpoint,
+        "status_code": response.status_code,
+        "duration_ms": round(duration_ms, 2),
+      },
+    )
+    return response

docintel/routes/__init__.py

@@ -0,0 +1 @@
+"""HTTP route blueprints."""

docintel/routes/jobs.py

@@ -0,0 +1,26 @@
+"""Async job status API."""
+
+from __future__ import annotations
+
+from flask import Blueprint, jsonify
+
+from docintel.auth.limiter import limiter
+from docintel.jobs.store import get_job
+
+jobs_bp = Blueprint("jobs", __name__, url_prefix="/v1/jobs")
+
+
+@jobs_bp.get("/<job_id>")
+@limiter.limit("600 per hour")
+def job_status(job_id: str):
+    """Poll async job status and download URL when complete."""
+    record = get_job(job_id)
+    if record is None:
+        return jsonify({"error": f"Job not found: {job_id}"}), 404
+
+    payload = {
+        "status": "ok",
+        **record.to_dict(),
+        "poll_url": f"/v1/jobs/{job_id}",
+    }
+    return jsonify(payload), 200

docintel/routes/match.py

@@ -0,0 +1,43 @@
+"""Resume matching API routes."""
+
+from flask import Blueprint, jsonify, request
+
+from docintel.auth.limiter import limiter
+from docintel.services.matching import match_resume_to_job
+
+match_bp = Blueprint("match", __name__, url_prefix="/v1/match")
+
+
+@match_bp.post("/resume")
+@limiter.limit("100 per hour")
+def match_resume():
+    """Score how well a resume matches a job description."""
+    payload = request.get_json(silent=True)
+    if not isinstance(payload, dict):
+        return jsonify({"error": "Request body must be JSON."}), 400
+
+    resume = payload.get("resume", "")
+    job_description = payload.get("job_description", "")
+    top_keywords = payload.get("top_keywords", 25)
+
+    if not isinstance(resume, str) or not isinstance(job_description, str):
+        return jsonify({"error": "Fields 'resume' and 'job_description' must be strings."}), 400
+
+    try:
+        top_keywords = int(top_keywords)
+    except (TypeError, ValueError):
+        return jsonify({"error": "Field 'top_keywords' must be an integer."}), 400
+
+    if top_keywords < 1 or top_keywords > 100:
+        return jsonify({"error": "Field 'top_keywords' must be between 1 and 100."}), 400
+
+    try:
+        result = match_resume_to_job(
+            resume=resume,
+            job_description=job_description,
+            top_keywords=top_keywords,
+        )
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    return jsonify({"status": "ok", **result.to_dict()}), 200

docintel/routes/openapi_docs.py

@@ -0,0 +1,57 @@
+"""OpenAPI specification and Swagger UI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from flask import Blueprint, Response, jsonify, render_template_string
+
+from docintel import __version__
+
+docs_bp = Blueprint("openapi", __name__)
+
+SWAGGER_UI_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <title>Document Intelligence API</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"/>
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+<script>
+  window.onload = () => {
+    SwaggerUIBundle({
+      url: '/openapi.json',
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis],
+    });
+  };
+</script>
+</body>
+</html>
+"""
+
+
+def _load_openapi_spec() -> dict:
+    spec_path = Path(__file__).resolve().parents[1] / "openapi" / "openapi.yaml"
+    with spec_path.open("r", encoding="utf-8") as handle:
+        spec = yaml.safe_load(handle)
+    spec.setdefault("info", {})
+    spec["info"]["version"] = __version__
+    return spec
+
+
+@docs_bp.get("/openapi.json")
+def openapi_json():
+    """Return the OpenAPI 3 specification."""
+    return jsonify(_load_openapi_spec())
+
+
+@docs_bp.get("/docs")
+def swagger_ui():
+    """Interactive Swagger UI for the REST API."""
+    return Response(render_template_string(SWAGGER_UI_HTML), mimetype="text/html")

docintel/routes/ops.py

@@ -0,0 +1,22 @@
+"""Operations endpoints (metrics)."""
+
+from flask import Blueprint, jsonify
+
+from docintel import __version__
+from docintel.ops.metrics import metrics_store
+
+ops_bp = Blueprint("ops", __name__)
+
+
+@ops_bp.get("/metrics")
+def metrics():
+  """Return in-process request counters and latency aggregates."""
+  payload = metrics_store.snapshot()
+  return jsonify(
+    {
+      "status": "ok",
+      "service": "document-intelligence-platform",
+      "version": __version__,
+      **payload,
+    }
+  )

docintel/routes/pdf.py

@@ -0,0 +1,420 @@
+"""PDF annotation API routes."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from flask import Blueprint, current_app, jsonify, request, send_file
+from werkzeug.utils import secure_filename
+
+from docintel.auth.limiter import limiter
+from docintel.services.pdf import (
+    Action,
+    DEFAULT_PII_ENTITIES,
+    StructureMode,
+    annotate_pdf,
+    detect_sensitive_pdf,
+    list_supported_entities,
+    structure_pdf,
+)
+
+pdf_bp = Blueprint("pdf", __name__, url_prefix="/v1/pdf")
+
+
+def _upload_dir() -> Path:
+    path = Path(current_app.config["UPLOAD_DIR"])
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _parse_pages(raw_pages: str | None) -> list[int] | None:
+    if not raw_pages or not raw_pages.strip():
+        return None
+    return [int(page.strip()) for page in raw_pages.split(",") if page.strip()]
+
+
+@pdf_bp.post("/annotate")
+@limiter.limit("60 per hour")
+def annotate():
+    """Search a PDF and apply highlight, redact, or other annotation actions."""
+    upload = request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"error": "Missing PDF file in form field 'file'."}), 400
+
+    filename = secure_filename(upload.filename)
+    if not filename.lower().endswith(".pdf"):
+        return jsonify({"error": "Only PDF files are supported."}), 400
+
+    action_raw = request.form.get("action", Action.HIGHLIGHT.value)
+    try:
+        action = Action.from_value(action_raw)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    pattern = request.form.get("pattern", "")
+    if action != Action.REMOVE and not pattern.strip():
+        return jsonify({"error": "Missing search pattern in form field 'pattern'."}), 400
+
+    try:
+        pages = _parse_pages(request.form.get("pages"))
+    except ValueError:
+        return jsonify({"error": "Invalid pages value. Use comma-separated page indexes."}), 400
+
+    job_id = uuid.uuid4().hex[:12]
+    work_dir = _upload_dir() / job_id
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    input_path = work_dir / filename
+    output_path = work_dir / f"annotated_{filename}"
+    upload.save(input_path)
+
+    try:
+        result = annotate_pdf(
+            input_file=input_path,
+            output_file=output_path,
+            pattern=pattern,
+            action=action,
+            pages=pages,
+        )
+    except FileNotFoundError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except PermissionError as exc:
+        return jsonify({"error": str(exc)}), 403
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    response_format = request.args.get("format", request.form.get("format", "file")).lower()
+
+    if response_format == "json":
+        payload = {
+            "status": "ok",
+            **result.to_dict(),
+            "download_url": f"/v1/pdf/files/{job_id}/{output_path.name}",
+        }
+        return jsonify(payload), 200
+
+    response = send_file(
+        output_path,
+        mimetype="application/pdf",
+        as_attachment=True,
+        download_name=output_path.name,
+    )
+    response.headers["X-Docintel-Matches"] = str(result.matches)
+    response.headers["X-Docintel-Pages-Processed"] = str(result.pages_processed)
+    response.headers["X-Docintel-Action"] = result.action.value
+    return response
+
+
+def _parse_entities(raw_entities: str | None) -> list[str] | None:
+    if not raw_entities or not raw_entities.strip():
+        return None
+    return [item.strip() for item in raw_entities.split(",") if item.strip()]
+
+
+@pdf_bp.get("/entities")
+@limiter.limit("120 per hour")
+def supported_entities():
+    """List Presidio entity types available for sensitive detection."""
+    try:
+        entities = list_supported_entities()
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 503
+
+    return jsonify(
+        {
+            "status": "ok",
+            "default_entities": list(DEFAULT_PII_ENTITIES),
+            "supported_entities": entities,
+        }
+    )
+
+
+@pdf_bp.post("/detect-sensitive")
+@limiter.limit("30 per hour")
+def detect_sensitive():
+    """
+    Detect PII with Presidio and annotate the PDF.
+
+    Auto-falls back to EasyOCR when native PDF text is empty (scanned documents).
+    """
+    upload = request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"error": "Missing PDF file in form field 'file'."}), 400
+
+    filename = secure_filename(upload.filename)
+    if not filename.lower().endswith(".pdf"):
+        return jsonify({"error": "Only PDF files are supported."}), 400
+
+    action_raw = request.form.get("action", Action.HIGHLIGHT.value)
+    try:
+        action = Action.from_value(action_raw)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    if action == Action.REMOVE:
+        return jsonify({"error": "Action 'Remove' is not supported for sensitive detection."}), 400
+
+    entities = _parse_entities(request.form.get("entities"))
+    pattern = request.form.get("pattern", "").strip() or None
+    force_ocr = request.form.get("force_ocr", "false").lower() == "true"
+    add_text_layer = request.form.get("add_text_layer", "true").lower() == "true"
+
+    try:
+        min_score = float(request.form.get("min_score", "0.35"))
+    except ValueError:
+        return jsonify({"error": "Field 'min_score' must be a number."}), 400
+
+    callback_url = request.form.get("callback_url", "").strip() or None
+    run_async = _parse_async_flag()
+
+    job_id = uuid.uuid4().hex[:12]
+    work_dir = _upload_dir() / job_id
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    input_path = work_dir / filename
+    output_path = work_dir / f"sensitive_{filename}"
+    upload.save(input_path)
+
+    if run_async:
+        return _enqueue_detect_sensitive_job(
+            job_id=job_id,
+            input_path=input_path,
+            output_path=output_path,
+            action=action,
+            entities=entities,
+            pattern=pattern,
+            force_ocr=force_ocr,
+            add_text_layer=add_text_layer,
+            min_score=min_score,
+            callback_url=callback_url,
+        )
+
+    try:
+        result = detect_sensitive_pdf(
+            input_file=input_path,
+            output_file=output_path,
+            entities=entities,
+            action=action,
+            force_ocr=force_ocr,
+            add_text_layer=add_text_layer,
+            pattern=pattern,
+            min_score=min_score,
+        )
+    except RuntimeError as exc:
+        return jsonify({"error": str(exc)}), 503
+    except FileNotFoundError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except PermissionError as exc:
+        return jsonify({"error": str(exc)}), 403
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    response_format = request.args.get("format", request.form.get("format", "file")).lower()
+
+    if response_format == "json":
+        payload = {
+            "status": "ok",
+            **result.to_dict(),
+            "download_url": f"/v1/pdf/files/{job_id}/{output_path.name}",
+        }
+        return jsonify(payload), 200
+
+    response = send_file(
+        output_path,
+        mimetype="application/pdf",
+        as_attachment=True,
+        download_name=output_path.name,
+    )
+    response.headers["X-Docintel-Matches"] = str(result.matches)
+    response.headers["X-Docintel-Pages-Processed"] = str(result.pages_processed)
+    response.headers["X-Docintel-OCR-Pages"] = ",".join(str(page) for page in result.ocr_pages)
+    response.headers["X-Docintel-Action"] = result.action.value
+    return response
+
+
+def _parse_async_flag() -> bool:
+    raw = request.args.get("async", request.form.get("async", "false"))
+    return str(raw).lower() == "true"
+
+
+@pdf_bp.post("/structure")
+@limiter.limit("20 per hour")
+def structure():
+    """
+    Structure an unstructured or scanned PDF with OCR and an LLM.
+
+    Returns a curated typeset PDF (curate) or the original with a searchable
+    invisible text layer (searchable).
+
+    Use ``async=true`` to queue the job and poll ``GET /v1/jobs/<job_id>``.
+    """
+    upload = request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"error": "Missing PDF file in form field 'file'."}), 400
+
+    filename = secure_filename(upload.filename)
+    if not filename.lower().endswith(".pdf"):
+        return jsonify({"error": "Only PDF files are supported."}), 400
+
+    mode_raw = request.form.get("mode", StructureMode.CURATE.value)
+    try:
+        mode = StructureMode.from_value(mode_raw)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    force_ocr = request.form.get("force_ocr", "false").lower() == "true"
+    redact_before_llm = request.form.get("redact_before_llm", "false").lower() == "true"
+    callback_url = request.form.get("callback_url", "").strip() or None
+    run_async = _parse_async_flag()
+
+    job_id = uuid.uuid4().hex[:12]
+    work_dir = _upload_dir() / job_id
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    input_path = work_dir / filename
+    output_path = work_dir / f"structured_{filename}"
+    upload.save(input_path)
+
+    if run_async:
+        return _enqueue_structure_job(
+            job_id=job_id,
+            input_path=input_path,
+            output_path=output_path,
+            mode=mode,
+            force_ocr=force_ocr,
+            redact_before_llm=redact_before_llm,
+            callback_url=callback_url,
+        )
+
+    try:
+        result = structure_pdf(
+            input_file=input_path,
+            output_file=output_path,
+            mode=mode,
+            force_ocr=force_ocr,
+            redact_before_llm=redact_before_llm,
+        )
+    except RuntimeError as exc:
+        return jsonify({"error": str(exc)}), 503
+    except FileNotFoundError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except PermissionError as exc:
+        return jsonify({"error": str(exc)}), 403
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    response_format = request.args.get("format", request.form.get("format", "file")).lower()
+
+    if response_format == "json":
+        payload = {
+            "status": "ok",
+            **result.to_dict(),
+            "download_url": f"/v1/pdf/files/{job_id}/{output_path.name}",
+        }
+        return jsonify(payload), 200
+
+    response = send_file(
+        output_path,
+        mimetype="application/pdf",
+        as_attachment=True,
+        download_name=output_path.name,
+    )
+    response.headers["X-Docintel-Pages-Processed"] = str(result.pages_processed)
+    response.headers["X-Docintel-OCR-Pages"] = ",".join(str(page) for page in result.ocr_pages)
+    response.headers["X-Docintel-Mode"] = result.mode.value
+    response.headers["X-Docintel-Document-Title"] = result.document_title
+    return response
+
+
+def _enqueue_structure_job(
+    *,
+    job_id: str,
+    input_path: Path,
+    output_path: Path,
+    mode: StructureMode,
+    force_ocr: bool,
+    redact_before_llm: bool,
+    callback_url: str | None,
+):
+    from docintel.jobs.helpers import enqueue_async_response
+    from docintel.jobs.models import JobType
+    from docintel.jobs.queue import enqueue_structure_job
+
+    accepted = enqueue_async_response(
+        job_id=job_id,
+        job_type=JobType.PDF_STRUCTURE,
+        callback_url=callback_url,
+    )
+    if accepted[1] != 202:
+        return accepted
+
+    enqueue_structure_job(
+        job_id=job_id,
+        input_path=str(input_path),
+        output_path=str(output_path),
+        mode=mode.value,
+        force_ocr=force_ocr,
+        output_filename=output_path.name,
+        redact_before_llm=redact_before_llm,
+    )
+    return accepted
+
+
+def _enqueue_detect_sensitive_job(
+    *,
+    job_id: str,
+    input_path: Path,
+    output_path: Path,
+    action: Action,
+    entities: list[str] | None,
+    pattern: str | None,
+    force_ocr: bool,
+    add_text_layer: bool,
+    min_score: float,
+    callback_url: str | None,
+):
+    from docintel.jobs.helpers import enqueue_async_response
+    from docintel.jobs.models import JobType
+    from docintel.jobs.queue import enqueue_detect_sensitive_job
+
+    accepted = enqueue_async_response(
+        job_id=job_id,
+        job_type=JobType.PDF_DETECT_SENSITIVE,
+        callback_url=callback_url,
+    )
+    if accepted[1] != 202:
+        return accepted
+
+    enqueue_detect_sensitive_job(
+        job_id=job_id,
+        input_path=str(input_path),
+        output_path=str(output_path),
+        output_filename=output_path.name,
+        action=action.value,
+        force_ocr=force_ocr,
+        add_text_layer=add_text_layer,
+        min_score=min_score,
+        entities=entities,
+        pattern=pattern,
+    )
+    return accepted
+
+
+@pdf_bp.get("/files/<job_id>/<filename>")
+@limiter.limit("200 per hour")
+def download_file(job_id: str, filename: str):
+    """Download a previously generated PDF when using JSON response mode."""
+    safe_job = secure_filename(job_id)
+    safe_name = secure_filename(filename)
+    file_path = _upload_dir() / safe_job / safe_name
+
+    if not file_path.is_file():
+        return jsonify({"error": "Annotated PDF not found."}), 404
+
+    return send_file(
+        file_path,
+        mimetype="application/pdf",
+        as_attachment=True,
+        download_name=safe_name,
+    )