docintel-platform 1.0.2__py3-none-any.whl

docintel/__init__.py

@@ -0,0 +1,6 @@
+"""Document intelligence platform."""
+
+from docintel.client import DocintelClient, DocintelError
+
+__version__ = "1.0.0"
+__all__ = ["DocintelClient", "DocintelError", "__version__"]

docintel/app.py

@@ -0,0 +1,45 @@
+"""Flask application factory."""
+
+from flask import Flask, jsonify
+
+from docintel import __version__
+from docintel.config import Config
+from docintel.auth.limiter import init_limiter
+from docintel.auth.middleware import register_auth
+from docintel.ops.logging import configure_logging
+from docintel.ops.middleware import register_request_hooks
+from docintel.routes.jobs import jobs_bp
+from docintel.routes.openapi_docs import docs_bp
+from docintel.routes.match import match_bp
+from docintel.routes.ops import ops_bp
+from docintel.routes.pdf import pdf_bp
+from docintel.routes.text import text_bp
+
+
+def create_app(config: type[Config] = Config) -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config)
+
+    configure_logging(config.LOG_LEVEL)
+    register_request_hooks(app)
+    register_auth(app)
+    init_limiter(app)
+
+    @app.get("/health")
+    def health():
+        return jsonify(
+            {
+                "status": "ok",
+                "service": "document-intelligence-platform",
+                "version": __version__,
+            }
+        )
+
+    app.register_blueprint(docs_bp)
+    app.register_blueprint(pdf_bp)
+    app.register_blueprint(jobs_bp)
+    app.register_blueprint(match_bp)
+    app.register_blueprint(text_bp)
+    app.register_blueprint(ops_bp)
+
+    return app

docintel/auth/__init__.py

@@ -0,0 +1,12 @@
+"""API authentication and rate limiting."""
+
+from docintel.auth.api_keys import auth_required, extract_bearer_token, validate_credentials
+from docintel.auth.limiter import init_limiter, limiter
+
+__all__ = [
+    "auth_required",
+    "extract_bearer_token",
+    "init_limiter",
+    "limiter",
+    "validate_credentials",
+]

docintel/auth/api_keys.py

@@ -0,0 +1,48 @@
+"""API key authentication."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    method: str
+    subject: str
+
+
+def _configured_keys() -> set[str]:
+    raw = os.getenv("DOCINTEL_API_KEYS", "")
+    return {item.strip() for item in raw.split(",") if item.strip()}
+
+
+def auth_required() -> bool:
+    if os.getenv("DOCINTEL_AUTH_REQUIRED", "false").lower() == "true":
+        return True
+    return bool(_configured_keys())
+
+
+def extract_bearer_token() -> str | None:
+    from flask import request
+
+    header = request.headers.get("Authorization", "").strip()
+    if not header.lower().startswith("bearer "):
+        return None
+    token = header[7:].strip()
+    return token or None
+
+
+def validate_api_key(token: str) -> AuthContext | None:
+    if token in _configured_keys():
+        return AuthContext(method="api_key", subject=token[:8])
+    return None
+
+
+def validate_credentials(token: str) -> AuthContext | None:
+    from docintel.auth.oidc import validate_oidc_token
+
+    api_match = validate_api_key(token)
+    if api_match is not None:
+        return api_match
+    return validate_oidc_token(token)

docintel/auth/limiter.py

@@ -0,0 +1,41 @@
+"""Redis-backed per-tenant rate limits."""
+
+from __future__ import annotations
+
+import os
+
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+
+from docintel.auth.api_keys import extract_bearer_token
+from docintel.jobs.store import redis_url
+
+
+def _rate_limit_key() -> str:
+    token = extract_bearer_token()
+    if token:
+        return f"key:{token[:12]}"
+    return get_remote_address()
+
+
+def rate_limits_enabled() -> bool:
+    return os.getenv("DOCINTEL_RATE_LIMIT_ENABLED", "true").lower() == "true"
+
+
+def storage_uri() -> str:
+    if rate_limits_enabled():
+        return redis_url()
+    return "memory://"
+
+
+limiter = Limiter(
+    key_func=_rate_limit_key,
+    default_limits=[],
+    storage_uri="memory://",
+    strategy="fixed-window",
+)
+
+
+def init_limiter(app) -> None:
+    app.config["RATELIMIT_STORAGE_URI"] = storage_uri()
+    limiter.init_app(app)

docintel/auth/middleware.py

@@ -0,0 +1,34 @@
+"""Authentication middleware for protected API routes."""
+
+from __future__ import annotations
+
+from flask import Flask, g, jsonify, request
+
+from docintel.auth.api_keys import auth_required, extract_bearer_token, validate_credentials
+
+PUBLIC_PREFIXES = ("/health", "/docs", "/openapi.json", "/metrics")
+
+
+def register_auth(app: Flask) -> None:
+    @app.before_request
+    def _enforce_api_auth():
+        if not auth_required():
+            return None
+
+        path = request.path or ""
+        if any(path == prefix or path.startswith(prefix + "/") for prefix in PUBLIC_PREFIXES):
+            return None
+
+        if not path.startswith("/v1/"):
+            return None
+
+        token = extract_bearer_token()
+        if not token:
+            return jsonify({"error": "Missing Authorization: Bearer <api_key> header."}), 401
+
+        context = validate_credentials(token)
+        if context is None:
+            return jsonify({"error": "Invalid API credentials."}), 401
+
+        g.auth_context = context
+        return None

docintel/auth/oidc.py

@@ -0,0 +1,45 @@
+"""Optional OIDC bearer token validation (Session 5 hook, no-op when unset)."""
+
+from __future__ import annotations
+
+import os
+
+from docintel.auth.api_keys import AuthContext
+
+
+def oidc_enabled() -> bool:
+    return bool(os.getenv("DOCINTEL_OIDC_ISSUER", "").strip())
+
+
+def validate_oidc_token(token: str) -> AuthContext | None:
+    if not oidc_enabled():
+        return None
+    if token.count(".") != 2:
+        return None
+
+    issuer = os.getenv("DOCINTEL_OIDC_ISSUER", "").strip()
+    audience = os.getenv("DOCINTEL_OIDC_AUDIENCE", "").strip() or None
+    jwks_url = os.getenv("DOCINTEL_OIDC_JWKS_URL", "").strip()
+    if not jwks_url and issuer:
+        jwks_url = issuer.rstrip("/") + "/.well-known/jwks.json"
+
+    try:
+        import jwt
+        from jwt import PyJWKClient
+    except ImportError as exc:
+        raise RuntimeError(
+            "OIDC auth requires PyJWT. Run: pip install -e '.[auth]'"
+        ) from exc
+
+    client = PyJWKClient(jwks_url)
+    signing_key = client.get_signing_key_from_jwt(token)
+    claims = jwt.decode(
+        token,
+        signing_key.key,
+        algorithms=["RS256", "ES256"],
+        audience=audience,
+        issuer=issuer,
+        options={"verify_aud": audience is not None},
+    )
+    subject = str(claims.get("sub") or claims.get("email") or "oidc-user")
+    return AuthContext(method="oidc", subject=subject)

docintel/cli.py

@@ -0,0 +1,21 @@
+"""CLI entry point."""
+
+import argparse
+
+from docintel.app import create_app
+from docintel.config import Config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the document intelligence API.")
+    parser.add_argument("--host", default=Config.HOST)
+    parser.add_argument("--port", type=int, default=Config.PORT)
+    parser.add_argument("--debug", action="store_true")
+    args = parser.parse_args()
+
+    app = create_app()
+    app.run(host=args.host, port=args.port, debug=args.debug)
+
+
+if __name__ == "__main__":
+    main()

docintel/client.py

@@ -0,0 +1,193 @@
+"""Python client for the Document Intelligence Platform REST API."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+import requests
+
+
+class DocintelError(Exception):
+    """Raised when the API returns an error response."""
+
+
+class DocintelClient:
+    """HTTP client for ``/v1/*`` document intelligence endpoints."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:5000",
+        api_key: str | None = None,
+        timeout: int = 120,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        if api_key:
+            self._session.headers["Authorization"] = f"Bearer {api_key}"
+
+    def _url(self, path: str) -> str:
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return f"{self.base_url}{path}"
+
+    def _raise_for_status(self, response: requests.Response) -> None:
+        if response.ok:
+            return
+        try:
+            payload = response.json()
+            message = payload.get("error", response.text)
+        except Exception:
+            message = response.text or f"HTTP {response.status_code}"
+        raise DocintelError(message)
+
+    def health(self) -> dict[str, Any]:
+        response = self._session.get(self._url("/health"), timeout=self.timeout)
+        self._raise_for_status(response)
+        return response.json()
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        response = self._session.get(self._url(f"/v1/jobs/{job_id}"), timeout=self.timeout)
+        self._raise_for_status(response)
+        return response.json()
+
+    def poll_job(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = 2.0,
+        timeout_seconds: float = 600.0,
+    ) -> dict[str, Any]:
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            payload = self.get_job(job_id)
+            status = payload.get("job_status")
+            if status == "completed":
+                return payload
+            if status == "failed":
+                raise DocintelError(payload.get("error", "Job failed"))
+            time.sleep(interval_seconds)
+        raise DocintelError(f"Job {job_id} timed out after {timeout_seconds}s")
+
+    def download(self, download_url: str) -> bytes:
+        response = self._session.get(self._url(download_url), timeout=self.timeout)
+        self._raise_for_status(response)
+        return response.content
+
+    def structure_pdf(
+        self,
+        pdf_path: str | Path,
+        *,
+        mode: str = "curate",
+        force_ocr: bool = False,
+        redact_before_llm: bool = False,
+        async_job: bool = False,
+        callback_url: str | None = None,
+        poll: bool = True,
+    ) -> dict[str, Any] | bytes:
+        path = Path(pdf_path)
+        params = {"async": "true"} if async_job else {}
+        data = {
+            "mode": mode,
+            "force_ocr": str(force_ocr).lower(),
+            "redact_before_llm": str(redact_before_llm).lower(),
+        }
+        if callback_url:
+            data["callback_url"] = callback_url
+        with path.open("rb") as handle:
+            response = self._session.post(
+                self._url("/v1/pdf/structure"),
+                params=params,
+                files={"file": (path.name, handle, "application/pdf")},
+                data=data,
+                timeout=self.timeout,
+            )
+        if response.status_code == 202:
+            payload = response.json()
+            if not poll:
+                return payload
+            payload = self.poll_job(payload["job_id"])
+            return self.download(payload["download_url"])
+        self._raise_for_status(response)
+        if "application/pdf" in response.headers.get("Content-Type", ""):
+            return response.content
+        return response.json()
+
+    def detect_sensitive(
+        self,
+        pdf_path: str | Path,
+        *,
+        action: str = "Highlight",
+        entities: str | None = None,
+        force_ocr: bool = False,
+        add_text_layer: bool = True,
+        async_job: bool = False,
+        callback_url: str | None = None,
+        response_format: str = "json",
+        poll: bool = True,
+    ) -> dict[str, Any] | bytes:
+        path = Path(pdf_path)
+        params: dict[str, str] = {}
+        if async_job:
+            params["async"] = "true"
+        if response_format == "json":
+            params["format"] = "json"
+        data: dict[str, str] = {
+            "action": action,
+            "force_ocr": str(force_ocr).lower(),
+            "add_text_layer": str(add_text_layer).lower(),
+        }
+        if entities:
+            data["entities"] = entities
+        if callback_url:
+            data["callback_url"] = callback_url
+        with path.open("rb") as handle:
+            response = self._session.post(
+                self._url("/v1/pdf/detect-sensitive"),
+                params=params,
+                files={"file": (path.name, handle, "application/pdf")},
+                data=data,
+                timeout=self.timeout,
+            )
+        if response.status_code == 202:
+            payload = response.json()
+            if not poll:
+                return payload
+            payload = self.poll_job(payload["job_id"])
+            if payload.get("download_url"):
+                return self.download(payload["download_url"])
+            return payload
+        self._raise_for_status(response)
+        if "application/pdf" in response.headers.get("Content-Type", ""):
+            return response.content
+        return response.json()
+
+    def match_resume(
+        self,
+        resume: str,
+        job_description: str,
+        *,
+        top_keywords: int = 25,
+    ) -> dict[str, Any]:
+        response = self._session.post(
+            self._url("/v1/match/resume"),
+            json={
+                "resume": resume,
+                "job_description": job_description,
+                "top_keywords": top_keywords,
+            },
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def summarize(self, text: str, *, sentences: int = 3) -> dict[str, Any]:
+        response = self._session.post(
+            self._url("/v1/text/summarize"),
+            json={"text": text, "sentences": sentences},
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()

docintel/config.py

@@ -0,0 +1,20 @@
+"""Application configuration."""
+
+import os
+
+
+class Config:
+    HOST = os.getenv("DOCINTEL_HOST", "127.0.0.1")
+    PORT = int(os.getenv("DOCINTEL_PORT", "5000"))
+    DEBUG = os.getenv("DOCINTEL_DEBUG", "false").lower() == "true"
+    UPLOAD_DIR = os.getenv("DOCINTEL_UPLOAD_DIR", "uploads")
+    LOG_LEVEL = os.getenv("DOCINTEL_LOG_LEVEL", "INFO")
+    REDIS_URL = os.getenv("DOCINTEL_REDIS_URL", "redis://localhost:6379/0")
+    JOBS_ENABLED = os.getenv("DOCINTEL_JOBS_ENABLED", "true").lower() == "true"
+    QUEUE_NAME = os.getenv("DOCINTEL_QUEUE_NAME", "docintel")
+    API_KEYS = os.getenv("DOCINTEL_API_KEYS", "")
+    AUTH_REQUIRED = os.getenv("DOCINTEL_AUTH_REQUIRED", "false").lower() == "true"
+    RATE_LIMIT_ENABLED = os.getenv("DOCINTEL_RATE_LIMIT_ENABLED", "true").lower() == "true"
+    OIDC_ISSUER = os.getenv("DOCINTEL_OIDC_ISSUER", "")
+    OIDC_AUDIENCE = os.getenv("DOCINTEL_OIDC_AUDIENCE", "")
+    OIDC_JWKS_URL = os.getenv("DOCINTEL_OIDC_JWKS_URL", "")

docintel/jobs/__init__.py

@@ -0,0 +1,16 @@
+"""Async job queue for long-running document tasks."""
+
+from docintel.jobs.models import JobRecord, JobStatus, JobType
+from docintel.jobs.store import get_job, jobs_enabled, ping_redis, save_job
+from docintel.jobs.tasks import create_queued_job
+
+__all__ = [
+    "JobRecord",
+    "JobStatus",
+    "JobType",
+    "create_queued_job",
+    "get_job",
+    "jobs_enabled",
+    "ping_redis",
+    "save_job",
+]

docintel/jobs/helpers.py

@@ -0,0 +1,38 @@
+"""Shared helpers for async job enqueue from HTTP routes."""
+
+from __future__ import annotations
+
+from flask import jsonify
+
+from docintel.jobs.models import JobType
+from docintel.jobs.store import jobs_enabled, ping_redis
+from docintel.jobs.tasks import create_queued_job
+
+
+def enqueue_async_response(
+    *,
+    job_id: str,
+    job_type: JobType,
+    callback_url: str | None,
+):
+    """Validate Redis and return a standard 202 async job payload."""
+    if not jobs_enabled():
+        return jsonify({"error": "Async jobs are disabled on this server."}), 503
+    if not ping_redis():
+        return jsonify(
+            {
+                "error": "Redis is not reachable. Start Redis or set DOCINTEL_REDIS_URL.",
+                "hint": "Use async=false for synchronous processing without a queue.",
+            }
+        ), 503
+
+    create_queued_job(job_id, job_type=job_type, callback_url=callback_url)
+    payload = {
+        "status": "ok",
+        "job_id": job_id,
+        "job_type": job_type.value,
+        "job_status": "queued",
+        "poll_url": f"/v1/jobs/{job_id}",
+        "message": "Job queued. Poll poll_url until job_status is completed.",
+    }
+    return jsonify(payload), 202

docintel/jobs/models.py

@@ -0,0 +1,78 @@
+"""Job status types for async document processing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+    @classmethod
+    def from_value(cls, value: str) -> "JobStatus":
+        normalized = value.strip().lower()
+        for status in cls:
+            if status.value == normalized:
+                return status
+        raise ValueError(f"Unknown job status: {value}")
+
+
+class JobType(str, Enum):
+    PDF_STRUCTURE = "pdf_structure"
+    PDF_DETECT_SENSITIVE = "pdf_detect_sensitive"
+
+
+@dataclass
+class JobRecord:
+    job_id: str
+    job_type: JobType
+    status: JobStatus
+    progress: int = 0
+    progress_message: str = ""
+    pages_done: int = 0
+    pages_total: int = 0
+    callback_url: str | None = None
+    download_url: str | None = None
+    error: str | None = None
+    result: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "job_id": self.job_id,
+            "job_type": self.job_type.value,
+            "job_status": self.status.value,
+            "progress": self.progress,
+            "progress_message": self.progress_message,
+            "pages_done": self.pages_done,
+            "pages_total": self.pages_total,
+        }
+        if self.callback_url:
+            payload["callback_url"] = self.callback_url
+        if self.download_url:
+            payload["download_url"] = self.download_url
+        if self.error:
+            payload["error"] = self.error
+        if self.result:
+            payload["result"] = self.result
+        return payload
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "JobRecord":
+        return cls(
+            job_id=str(payload["job_id"]),
+            job_type=JobType(payload["job_type"]),
+            status=JobStatus(payload.get("job_status", payload.get("status"))),
+            progress=int(payload.get("progress", 0)),
+            progress_message=str(payload.get("progress_message", "")),
+            pages_done=int(payload.get("pages_done", 0)),
+            pages_total=int(payload.get("pages_total", 0)),
+            callback_url=payload.get("callback_url"),
+            download_url=payload.get("download_url"),
+            error=payload.get("error"),
+            result=dict(payload.get("result") or {}),
+        )

docintel/jobs/queue.py

@@ -0,0 +1,75 @@
+"""RQ queue helpers."""
+
+from __future__ import annotations
+
+import os
+
+from docintel.jobs.store import redis_url
+
+QUEUE_NAME = os.getenv("DOCINTEL_QUEUE_NAME", "docintel")
+DEFAULT_RESULT_TTL = 60 * 60 * 24
+DEFAULT_FAILURE_TTL = 60 * 60 * 24
+
+
+def get_queue():
+    from redis import Redis
+    from rq import Queue
+
+    connection = Redis.from_url(redis_url())
+    return Queue(QUEUE_NAME, connection=connection)
+
+
+def enqueue_structure_job(
+    job_id: str,
+    input_path: str,
+    output_path: str,
+    mode: str,
+    force_ocr: bool,
+    output_filename: str,
+    redact_before_llm: bool = False,
+) -> None:
+    queue = get_queue()
+    queue.enqueue(
+        "docintel.jobs.tasks.run_structure_pdf_job",
+        job_id=job_id,
+        input_path=input_path,
+        output_path=output_path,
+        mode=mode,
+        force_ocr=force_ocr,
+        output_filename=output_filename,
+        redact_before_llm=redact_before_llm,
+        job_timeout=1800,
+        result_ttl=DEFAULT_RESULT_TTL,
+        failure_ttl=DEFAULT_FAILURE_TTL,
+    )
+
+
+def enqueue_detect_sensitive_job(
+    job_id: str,
+    input_path: str,
+    output_path: str,
+    output_filename: str,
+    action: str,
+    force_ocr: bool,
+    add_text_layer: bool,
+    min_score: float,
+    entities: list[str] | None = None,
+    pattern: str | None = None,
+) -> None:
+    queue = get_queue()
+    queue.enqueue(
+        "docintel.jobs.tasks.run_detect_sensitive_pdf_job",
+        job_id=job_id,
+        input_path=input_path,
+        output_path=output_path,
+        output_filename=output_filename,
+        action=action,
+        force_ocr=force_ocr,
+        add_text_layer=add_text_layer,
+        min_score=min_score,
+        entities=entities,
+        pattern=pattern,
+        job_timeout=1800,
+        result_ttl=DEFAULT_RESULT_TTL,
+        failure_ttl=DEFAULT_FAILURE_TTL,
+    )