feat: add qr extractor

app/api/v1/json_extract.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from app.api.deps import require_auth
+from app.core.logger import get_logger
+from app.services.json_service import extract_json
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+MAX_CONTENT_LENGTH = 10_000_000
+
+
+class ExtractJsonRequest(BaseModel):
+    content: str = Field(
+        ...,
+        description="Dirty string content potentially containing JSON wrapped in markdown, conversational text, etc.",
+        min_length=1,
+    )
+    limit: Optional[int] = Field(
+        default=None,
+        ge=1,
+        le=100,
+        description="Maximum number of JSON objects to extract. Omit for all.",
+    )
+    mode: str = Field(
+        default="all",
+        pattern=r"^(first|all)$",
+        description="'first' returns only the first JSON object; 'all' returns all extracted objects.",
+    )
+
+
+class ExtractJsonResponse(BaseModel):
+    success: bool
+    time_ms: float
+    data: Any = None
+    count: int = 0
+    error_message: Optional[str] = None
+
+
+@router.post(
+    "/json/extract",
+    response_model=ExtractJsonResponse,
+    summary="Extract JSON from dirty/markdown content",
+    description=(
+        "Accepts string content that may contain JSON embedded in markdown code fences "
+        "(```json), XML-style <json> tags, or mixed with conversational text. "
+        "Returns cleaned, parsed JSON objects. Handles malformed JSON via a repair pipeline "
+        "that fixes trailing commas, unquoted keys, single-quote strings, JS comments, etc."
+    ),
+)
+async def extract_json_endpoint(
+    body: ExtractJsonRequest,
+    token: str = Depends(require_auth),
+) -> ExtractJsonResponse:
+    start = time.perf_counter()
+
+    content_length = len(body.content)
+    if content_length > MAX_CONTENT_LENGTH:
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        raise HTTPException(
+            status_code=413,
+            detail=ExtractJsonResponse(
+                success=False,
+                time_ms=elapsed,
+                data=None,
+                count=0,
+                error_message=f"Content exceeds maximum length of {MAX_CONTENT_LENGTH:,} characters.",
+            ).model_dump(),
+        )
+
+    effective_limit = 1 if body.mode == "first" else body.limit
+
+    result = extract_json(body.content, limit=effective_limit)
+
+    elapsed = round((time.perf_counter() - start) * 1000, 3)
+
+    if not result.success:
+        logger.warning(
+            "JSON extraction returned no results",
+            extra={
+                "input_length": content_length,
+                "mode": body.mode,
+                "time_ms": elapsed,
+            },
+        )
+        raise HTTPException(
+            status_code=422,
+            detail=ExtractJsonResponse(
+                success=False,
+                time_ms=elapsed,
+                data=None,
+                count=0,
+                error_message=result.error_message or "No JSON content could be extracted from the provided input.",
+            ).model_dump(),
+        )
+
+    response_data = result.data[0] if body.mode == "first" else result.data
+
+    logger.info(
+        "JSON extraction successful",
+        extra={
+            "count": result.total_extracted,
+            "method": result.extraction_method,
+            "input_length": content_length,
+            "time_ms": elapsed,
+        },
+    )
+
+    return ExtractJsonResponse(
+        success=True,
+        time_ms=elapsed,
+        data=response_data,
+        count=result.total_extracted,
+        error_message=None,
+    )

app/api/v1/qr_decoder.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from pydantic import BaseModel, Field
+
+from app.api.deps import require_auth
+from app.core.logger import get_logger
+from app.services.qr_decoder_service import QRDecoderService
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+MAX_UPLOAD_BYTES = 20 * 1024 * 1024
+
+_service = QRDecoderService()
+
+
+class QRDecodeUrlRequest(BaseModel):
+    url: str = Field(
+        ...,
+        description="Public URL of the QR code image to decode",
+    )
+
+
+class DecodedQR(BaseModel):
+    data: str
+    type: str = "QRCODE"
+    bounding_box: Optional[List[List[float]]] = None
+    decoder: Optional[str] = None
+
+
+class QRDecodeResponse(BaseModel):
+    success: bool
+    time_ms: float
+    decoded: List[DecodedQR]
+    count: int
+    error_message: Optional[str] = None
+
+
+@router.post(
+    "/qr-decode/file",
+    response_model=QRDecodeResponse,
+    summary="Decode QR code from an uploaded image file",
+    description="Upload an image file containing a QR code and get its decoded content.",
+)
+async def decode_qr_file(
+    file: UploadFile = File(..., description="Image file containing a QR code"),
+    token: str = Depends(require_auth),
+) -> QRDecodeResponse:
+    start = time.perf_counter()
+
+    if not file.content_type or not file.content_type.startswith("image/"):
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        raise HTTPException(
+            status_code=400,
+            detail=QRDecodeResponse(
+                success=False, time_ms=elapsed, decoded=[], count=0,
+                error_message="Uploaded file must be an image.",
+            ).model_dump(),
+        )
+
+    raw = await file.read()
+    if len(raw) == 0:
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        raise HTTPException(
+            status_code=400,
+            detail=QRDecodeResponse(
+                success=False, time_ms=elapsed, decoded=[], count=0,
+                error_message="Uploaded file is empty.",
+            ).model_dump(),
+        )
+    if len(raw) > MAX_UPLOAD_BYTES:
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        raise HTTPException(
+            status_code=413,
+            detail=QRDecodeResponse(
+                success=False, time_ms=elapsed, decoded=[], count=0,
+                error_message=f"File exceeds maximum size of {MAX_UPLOAD_BYTES // (1024 * 1024)} MB.",
+            ).model_dump(),
+        )
+
+    result = await _service.decode_from_bytes(raw, source_label=file.filename or "upload")
+
+    if not result.success:
+        logger.warning("QR decode failed for uploaded file", extra={
+            "filename": file.filename, "error": result.error_message,
+        })
+        raise HTTPException(
+            status_code=422,
+            detail=QRDecodeResponse(
+                success=False, time_ms=result.processing_time_ms, decoded=[], count=0,
+                error_message=result.error_message,
+            ).model_dump(),
+        )
+
+    items = [DecodedQR(**item) for item in result.decoded_data]
+    logger.info("QR decode successful", extra={
+        "filename": file.filename, "count": len(items),
+    })
+    return QRDecodeResponse(
+        success=True, time_ms=result.processing_time_ms,
+        decoded=items, count=len(items), error_message=None,
+    )
+
+
+@router.post(
+    "/qr-decode/url",
+    response_model=QRDecodeResponse,
+    summary="Decode QR code from an image URL",
+    description="Provide a public URL to an image containing a QR code and get its decoded content.",
+)
+async def decode_qr_url(
+    body: QRDecodeUrlRequest,
+    token: str = Depends(require_auth),
+) -> QRDecodeResponse:
+    start = time.perf_counter()
+
+    if not body.url.lower().startswith(("http://", "https://")):
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        raise HTTPException(
+            status_code=400,
+            detail=QRDecodeResponse(
+                success=False, time_ms=elapsed, decoded=[], count=0,
+                error_message="URL must start with http:// or https://.",
+            ).model_dump(),
+        )
+
+    result = await _service.decode_from_url(body.url)
+
+    if not result.success:
+        logger.warning("QR decode failed for URL", extra={
+            "url": body.url, "error": result.error_message,
+        })
+        raise HTTPException(
+            status_code=422,
+            detail=QRDecodeResponse(
+                success=False, time_ms=result.processing_time_ms, decoded=[], count=0,
+                error_message=result.error_message,
+            ).model_dump(),
+        )
+
+    items = [DecodedQR(**item) for item in result.decoded_data]
+    logger.info("QR decode successful", extra={
+        "url": body.url, "count": len(items),
+    })
+    return QRDecodeResponse(
+        success=True, time_ms=result.processing_time_ms,
+        decoded=items, count=len(items), error_message=None,
+    )

app/api/v1/router.py

@@ -11,6 +11,8 @@ from app.api.v1 import (
     csv_analysis,
     database,
     embeddings,
+    json_extract,
+    qr_decoder,
     qr_generator,
     reconcile,
     scraper,
@@ -46,5 +48,7 @@ api_v1_router.include_router(chat.router, tags=["Chat"])
 api_v1_router.include_router(vector_stores.router, tags=["Vector Stores"])
 api_v1_router.include_router(webhook_socket.router, tags=["Webhook / Socket"])
 api_v1_router.include_router(csv_analysis.router, tags=["CSV Analysis"])
+api_v1_router.include_router(json_extract.router, tags=["JSON Extractor"])
+api_v1_router.include_router(qr_decoder.router, tags=["QR Decoder"])
 api_v1_router.include_router(qr_generator.router, tags=["QR Generator"])
 api_v1_router.include_router(url_shortener.router, tags=["URL Shortener"])

app/services/json_service.py

@@ -0,0 +1,612 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+MAX_CONTENT_LENGTH = 10_000_000
+MAX_REPAIR_PASSES = 6
+MAX_RESULTS = 100
+
+
+class ExtractionResult:
+    def __init__(
+        self,
+        success: bool,
+        data: List[Any],
+        time_ms: float,
+        error_message: Optional[str] = None,
+        extraction_method: Optional[str] = None,
+        total_extracted: int = 0,
+        input_length: int = 0,
+    ):
+        self.success = success
+        self.data = data
+        self.time_ms = time_ms
+        self.error_message = error_message
+        self.extraction_method = extraction_method
+        self.total_extracted = total_extracted
+        self.input_length = input_length
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "success": self.success,
+            "data": self.data,
+            "time_ms": self.time_ms,
+            "error_message": self.error_message,
+            "extraction_method": self.extraction_method,
+            "total_extracted": self.total_extracted,
+            "input_length": self.input_length,
+        }
+
+
+def _purge_nan_inf(obj: Any) -> Any:
+    if isinstance(obj, float):
+        if obj != obj or obj == float("inf") or obj == -float("inf"):
+            return None
+        return obj
+    if isinstance(obj, dict):
+        return {k: _purge_nan_inf(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_purge_nan_inf(v) for v in obj]
+    return obj
+
+
+def _safe_json_parse(raw: str) -> Optional[Any]:
+    if not raw or len(raw) == 0:
+        return None
+    try:
+        parsed = json.loads(raw)
+        return _purge_nan_inf(parsed)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def _is_meaningful(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, bool):
+        return True
+    if isinstance(value, (int, float)):
+        return True
+    if isinstance(value, str):
+        return len(value.strip()) > 0
+    if isinstance(value, (list, tuple)):
+        return len(value) > 0
+    if isinstance(value, dict):
+        return len(value) > 0
+    return False
+
+
+def _is_trivial(value: Any) -> bool:
+    if isinstance(value, (list, tuple)):
+        return len(value) == 0
+    if isinstance(value, dict):
+        return len(value) == 0
+    return False
+
+
+def _normalize_whitespace(raw: str) -> str:
+    result = raw
+    result = result.replace("\r\n", "\n")
+    result = result.replace("\r", "\n")
+    result = result.replace("\t", "  ")
+    result = result.replace("\u00a0", " ")
+    result = re.sub(r"[\u200b-\u200d]", "", result)
+    result = result.replace("\ufeff", "")
+    return result
+
+
+def _strip_bom(raw: str) -> str:
+    if raw and ord(raw[0]) == 0xFEFF:
+        return raw[1:]
+    return raw
+
+
+def _repair_trailing_commas(raw: str) -> str:
+    result = raw
+    prev = None
+    passes = 0
+    while result != prev and passes < MAX_REPAIR_PASSES:
+        prev = result
+        result = re.sub(r",(\s*[}\]])", r"\1", result)
+        passes += 1
+    return result
+
+
+def _repair_leading_commas(raw: str) -> str:
+    return re.sub(r"([\[{])\s*,", r"\1", raw)
+
+
+def _repair_double_commas(raw: str) -> str:
+    return re.sub(r",(\s*),", r",\1", raw)
+
+
+def _quote_unquoted_keys(raw: str) -> str:
+    return re.sub(r'([{,]\s*)([A-Za-z_$][A-Za-z0-9_$]*)\s*:', r'\1"\2":', raw)
+
+
+def _replace_single_quote_strings(raw: str) -> str:
+    def _replace(m: re.Match) -> str:
+        inner = m.group(1)
+        escaped = inner.replace('"', '\\"')
+        return f': "{escaped}"'
+    return re.sub(r":\s*'((?:[^'\\]|\\.)*)'", _replace, raw)
+
+
+def _replace_single_quote_keys(raw: str) -> str:
+    def _replace(m: re.Match) -> str:
+        pre, key, post = m.group(1), m.group(2), m.group(3)
+        escaped = key.replace('"', '\\"')
+        return f'{pre}"{escaped}"{post}'
+    return re.sub(r"([{,]\s*)'((?:[^'\\]|\\.)*)'(\s*:)", _replace, raw)
+
+
+def _fix_ellipsis_values(raw: str) -> str:
+    return re.sub(r":\s*\.\.\.", ": null", raw)
+
+
+def _fix_undefined_values(raw: str) -> str:
+    return re.sub(r":\s*undefined\b", ": null", raw, flags=re.IGNORECASE)
+
+
+def _fix_nan_values(raw: str) -> str:
+    return re.sub(r":\s*NaN\b", ": null", raw)
+
+
+def _fix_infinity_values(raw: str) -> str:
+    return re.sub(r":\s*-?Infinity\b", ": null", raw)
+
+
+def _fix_hex_numbers(raw: str) -> str:
+    def _replace(m: re.Match) -> str:
+        hex_val = m.group(1)
+        return f": {int(hex_val, 16)}"
+    return re.sub(r":\s*(0x[0-9a-fA-F]+)", _replace, raw)
+
+
+def _strip_js_comments(raw: str) -> str:
+    result = re.sub(r"//[^\n]*", "", raw)
+    result = re.sub(r"/\*[\s\S]*?\*/", "", result)
+    return result
+
+
+def _remove_bare_string_entries(raw: str) -> str:
+    lines = raw.split("\n")
+    cleaned: List[str] = []
+
+    for i, line in enumerate(lines):
+        trimmed = line.strip()
+        is_bare = bool(re.match(r'^"[^"]*",?\s*$', trimmed)) and ":" not in trimmed
+        if is_bare:
+            if cleaned:
+                cleaned[-1] = re.sub(r",\s*$", "", cleaned[-1])
+            continue
+        cleaned.append(line)
+
+    return "\n".join(cleaned)
+
+
+def _fix_single_element_bare_objects(raw: str) -> str:
+    def _replace(m: re.Match) -> str:
+        content = m.group(1)
+        if ":" in content:
+            return m.group(0)
+        return "{}"
+    return re.sub(r'\{\s*"([^"]+)"\s*\}', _replace, raw)
+
+
+def _fix_missing_commas(raw: str) -> str:
+    result = raw
+    result = re.sub(r'("\s*)\n(\s*")', r'\1,\n\2', result)
+    result = re.sub(r"(\d)\n(\s*\")", r'\1,\n\2', result)
+    result = re.sub(r'("\s*)\n(\s*\d)', r'\1,\n\2', result)
+    result = re.sub(r"(\})\n(\s*\{)", r'\1,\n\2', result)
+    result = re.sub(r"(\])\n(\s*\[)", r'\1,\n\2', result)
+    return result
+
+
+def _apply_repair_pipeline(raw: str) -> str:
+    result = raw
+    result = _strip_js_comments(result)
+    result = _remove_bare_string_entries(result)
+    result = _fix_single_element_bare_objects(result)
+    result = _replace_single_quote_keys(result)
+    result = _replace_single_quote_strings(result)
+    result = _quote_unquoted_keys(result)
+    result = _fix_ellipsis_values(result)
+    result = _fix_undefined_values(result)
+    result = _fix_nan_values(result)
+    result = _fix_infinity_values(result)
+    result = _fix_hex_numbers(result)
+    result = _repair_leading_commas(result)
+    result = _repair_trailing_commas(result)
+    result = _repair_double_commas(result)
+    result = _fix_missing_commas(result)
+    return result
+
+
+def _truncate_to_balanced(raw: str) -> str:
+    if not raw:
+        return raw
+    opener = raw[0]
+    if opener not in ("{", "["):
+        return raw
+    closer = "}" if opener == "{" else "]"
+
+    depth = 0
+    in_string = False
+    escape = False
+
+    for i, char in enumerate(raw):
+        if in_string:
+            if escape:
+                escape = False
+            elif char == "\\":
+                escape = True
+            elif char == '"':
+                in_string = False
+            continue
+
+        if char == '"':
+            in_string = True
+            continue
+
+        if char == opener:
+            depth += 1
+        elif char == closer:
+            depth -= 1
+            if depth == 0:
+                return raw[: i + 1]
+
+    return raw
+
+
+def _close_unclosed_structures(raw: str) -> str:
+    stack: List[str] = []
+    in_string = False
+    escape = False
+
+    for char in raw:
+        if in_string:
+            if escape:
+                escape = False
+            elif char == "\\":
+                escape = True
+            elif char == '"':
+                in_string = False
+            continue
+
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            stack.append("}")
+        elif char == "[":
+            stack.append("]")
+        elif char == "}" or char == "]":
+            if stack and stack[-1] == char:
+                stack.pop()
+
+    if not stack:
+        return raw
+
+    result = raw.rstrip()
+    result = re.sub(r",\s*$", "", result)
+
+    for closer in reversed(stack):
+        result += closer
+
+    return result
+
+
+def _try_parse_with_repair(raw: str) -> Optional[Any]:
+    trimmed = raw.strip()
+    if not trimmed:
+        return None
+
+    direct = _safe_json_parse(trimmed)
+    if direct is not None:
+        return direct
+
+    repaired = _apply_repair_pipeline(trimmed)
+
+    after_repair = _safe_json_parse(repaired)
+    if after_repair is not None:
+        return after_repair
+
+    truncated = _truncate_to_balanced(repaired)
+    after_truncate = _safe_json_parse(truncated)
+    if after_truncate is not None:
+        return after_truncate
+
+    closed = _close_unclosed_structures(repaired)
+    after_close = _safe_json_parse(closed)
+    if after_close is not None:
+        return after_close
+
+    closed_truncated = _close_unclosed_structures(truncated)
+    return _safe_json_parse(closed_truncated)
+
+
+def _find_balanced_closing(text: str, start: int) -> int:
+    opener = text[start]
+    if opener not in ("{", "["):
+        return -1
+    closer = "}" if opener == "{" else "]"
+
+    depth = 0
+    in_string = False
+    escape = False
+
+    for i in range(start, len(text)):
+        char = text[i]
+
+        if in_string:
+            if escape:
+                escape = False
+            elif char == "\\":
+                escape = True
+            elif char == '"':
+                in_string = False
+            continue
+
+        if char == '"':
+            in_string = True
+            continue
+
+        if char == opener:
+            depth += 1
+        elif char == closer:
+            depth -= 1
+            if depth == 0:
+                return i
+
+    return -1
+
+
+def _extract_from_fenced_blocks(content: str) -> Tuple[List[Any], List[Tuple[int, int]]]:
+    results: List[Any] = []
+    covered_ranges: List[Tuple[int, int]] = []
+
+    patterns = [
+        re.compile(r"```json\s*\n?(.*?)```", re.DOTALL),
+        re.compile(r"```javascript\s*\n?(.*?)```", re.DOTALL),
+        re.compile(r"```js\s*\n?(.*?)```", re.DOTALL),
+        re.compile(r"```typescript\s*\n?(.*?)```", re.DOTALL),
+        re.compile(r"```ts\s*\n?(.*?)```", re.DOTALL),
+        re.compile(r"```(.*?)```", re.DOTALL),
+        re.compile(r"~~~json\s*\n?(.*?)~~~", re.DOTALL),
+        re.compile(r"~~~(.*?)~~~", re.DOTALL),
+    ]
+
+    seen_ranges: set = set()
+
+    for pattern in patterns:
+        for match in pattern.finditer(content):
+            range_key = (match.start(), match.end())
+            if range_key in seen_ranges:
+                continue
+            seen_ranges.add(range_key)
+
+            raw = match.group(1).strip() if match.lastindex else match.group(1).strip()
+            if not raw:
+                continue
+
+            parsed = _try_parse_with_repair(raw)
+            if parsed is not None and not _is_trivial(parsed):
+                results.append(parsed)
+                covered_ranges.append(range_key)
+
+    return results, covered_ranges
+
+
+def _extract_from_json_tags(content: str) -> Tuple[List[Any], List[Tuple[int, int]]]:
+    results: List[Any] = []
+    covered_ranges: List[Tuple[int, int]] = []
+
+    pattern = re.compile(r"<json[^>]*>(.*?)</json>", re.DOTALL)
+
+    for match in pattern.finditer(content):
+        raw = match.group(1).strip()
+        if not raw:
+            continue
+
+        parsed = _try_parse_with_repair(raw)
+        if parsed is not None and not _is_trivial(parsed):
+            results.append(parsed)
+            covered_ranges.append((match.start(), match.end()))
+
+    return results, covered_ranges
+
+
+def _is_inside_range(index: int, ranges: List[Tuple[int, int]]) -> bool:
+    for start, end in ranges:
+        if start <= index <= end:
+            return True
+    return False
+
+
+def _extract_balanced_json(content: str, skip_ranges: List[Tuple[int, int]]) -> List[Any]:
+    results: List[Any] = []
+    cursor = 0
+
+    while cursor < len(content):
+        if _is_inside_range(cursor, skip_ranges):
+            cursor += 1
+            continue
+
+        char = content[cursor]
+        if char not in ("{", "["):
+            cursor += 1
+            continue
+
+        end = _find_balanced_closing(content, cursor)
+        if end != -1:
+            candidate = content[cursor : end + 1]
+            if len(candidate) >= 2:
+                parsed = _try_parse_with_repair(candidate)
+                if parsed is not None and not _is_trivial(parsed):
+                    results.append(parsed)
+                    cursor = end + 1
+                    continue
+        else:
+            partial = content[cursor:]
+            if len(partial) >= 2:
+                parsed = _try_parse_with_repair(partial)
+                if parsed is not None and not _is_trivial(parsed):
+                    results.append(parsed)
+                    break
+
+        cursor += 1
+
+    return results
+
+
+def _extract_json_lines(content: str, skip_ranges: List[Tuple[int, int]]) -> List[Any]:
+    results: List[Any] = []
+    offset = 0
+
+    for line in content.split("\n"):
+        line_start = offset
+        offset += len(line) + 1
+
+        if _is_inside_range(line_start, skip_ranges):
+            continue
+
+        trimmed = line.strip()
+        if not trimmed.startswith("{") and not trimmed.startswith("["):
+            continue
+
+        parsed = _safe_json_parse(trimmed)
+        if parsed is not None and not _is_trivial(parsed):
+            results.append(parsed)
+
+    return results
+
+
+def _extract_entire_content(content: str) -> List[Any]:
+    trimmed = content.strip()
+    if not trimmed.startswith("{") and not trimmed.startswith("["):
+        return []
+
+    parsed = _try_parse_with_repair(trimmed)
+    if parsed is not None and not _is_trivial(parsed):
+        return [parsed]
+    return []
+
+
+def _deduplicate(items: List[Any]) -> List[Any]:
+    seen: set = set()
+    result: List[Any] = []
+    for item in items:
+        key = json.dumps(item, sort_keys=True, default=str)
+        if key not in seen:
+            seen.add(key)
+            result.append(item)
+    return result
+
+
+def _remove_contained_subsets(items: List[Any]) -> List[Any]:
+    serialized = [json.dumps(item, sort_keys=True, default=str) for item in items]
+    result: List[Any] = []
+
+    for i, current in enumerate(serialized):
+        if not current:
+            continue
+        is_contained = any(
+            j != i and other and len(other) > len(current) and current in other
+            for j, other in enumerate(serialized)
+        )
+        if not is_contained:
+            result.append(items[i])
+
+    return result
+
+
+def extract_json_from_content(content: Any, limit: Optional[int] = None) -> List[Any]:
+    if not isinstance(content, str):
+        return []
+
+    normalized = _strip_bom(_normalize_whitespace(content))
+
+    if len(normalized) == 0:
+        return []
+    if len(normalized) > MAX_CONTENT_LENGTH:
+        logger.warning("Content exceeds maximum length of %d", MAX_CONTENT_LENGTH)
+        return []
+
+    entire = _extract_entire_content(normalized)
+    if entire:
+        filtered = [v for v in entire if _is_meaningful(v)]
+        return filtered[:limit] if limit else filtered
+
+    fenced_results, fenced_ranges = _extract_from_fenced_blocks(normalized)
+    tag_results, tag_ranges = _extract_from_json_tags(normalized)
+
+    all_skip_ranges = fenced_ranges + tag_ranges
+
+    balanced_results = _extract_balanced_json(normalized, all_skip_ranges)
+    line_results = _extract_json_lines(normalized, all_skip_ranges)
+
+    combined = fenced_results + tag_results + balanced_results + line_results
+
+    meaningful = [v for v in combined if _is_meaningful(v)]
+    deduplicated = _deduplicate(meaningful)
+    filtered = _remove_contained_subsets(deduplicated)
+
+    return filtered[:limit] if limit else filtered
+
+
+def extract_first_json(content: Any) -> Optional[Any]:
+    results = extract_json_from_content(content, limit=1)
+    return results[0] if results else None
+
+
+def extract_json(content: Any, limit: Optional[int] = None) -> ExtractionResult:
+    start = time.perf_counter()
+
+    try:
+        data = extract_json_from_content(content, limit)
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+
+        method: Optional[str] = None
+        if data:
+            if isinstance(content, str):
+                trimmed = content.strip()
+                if trimmed.startswith("{") or trimmed.startswith("["):
+                    method = "entire-content"
+                elif "```" in content or "~~~" in content:
+                    method = "fenced-blocks"
+                elif "<json" in content:
+                    method = "json-tags"
+                else:
+                    method = "balanced-json"
+            else:
+                method = "unknown"
+
+        return ExtractionResult(
+            success=len(data) > 0,
+            data=data,
+            time_ms=elapsed,
+            error_message=None if data else "No JSON content could be extracted",
+            extraction_method=method,
+            total_extracted=len(data),
+            input_length=len(content) if isinstance(content, str) else 0,
+        )
+    except Exception as exc:
+        elapsed = round((time.perf_counter() - start) * 1000, 3)
+        logger.exception("extract_json failed")
+        return ExtractionResult(
+            success=False,
+            data=[],
+            time_ms=elapsed,
+            error_message=str(exc),
+            extraction_method=None,
+            total_extracted=0,
+            input_length=len(content) if isinstance(content, str) else 0,
+        )

app/services/qr_decoder_service.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import io
+import ipaddress
+import os
+import socket
+import time
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+import cv2
+import httpx
+import numpy as np
+from PIL import Image, UnidentifiedImageError
+
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+try:
+    from pyzbar import pyzbar
+    PYZBAR_AVAILABLE = True
+except Exception:
+    PYZBAR_AVAILABLE = False
+
+
+class QRCodeExtractionError(Exception):
+    pass
+
+
+class QRDecoderResult:
+    def __init__(
+        self,
+        success: bool,
+        decoded_data: List[Dict[str, Any]],
+        error_message: Optional[str] = None,
+        processing_time_ms: float = 0.0,
+    ):
+        self.success = success
+        self.decoded_data = decoded_data
+        self.error_message = error_message
+        self.processing_time_ms = processing_time_ms
+
+
+class _PreprocessingPipeline:
+    """Collection of static preprocessing strategies for QR code images.
+    
+    Each strategy returns (preprocessed_image, label) or None if not applicable.
+    Strategies are tried in order from fastest/least destructive to most aggressive.
+    """
+
+    @staticmethod
+    def original(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        return (image, "original")
+
+    @staticmethod
+    def grayscale(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        if image.shape[2] == 3:
+            return (cv2.cvtColor(image, cv2.COLOR_BGR2GRAY), "grayscale")
+        return (image, "grayscale")
+
+    @staticmethod
+    def otsu_threshold(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+        _, binary = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        return (binary, "otsu")
+
+    @staticmethod
+    def adaptive_threshold(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+        binary = cv2.adaptiveThreshold(
+            blurred, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 51, 2
+        )
+        return (binary, "adaptive")
+
+    @staticmethod
+    def clahe(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
+        enhanced = clahe.apply(gray)
+        return (enhanced, "clahe")
+
+    @staticmethod
+    def unsharp_mask(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        blurred = cv2.GaussianBlur(gray, (0, 0), 3.0)
+        sharpened = cv2.addWeighted(gray, 1.5, blurred, -0.5, 0)
+        return (sharpened, "unsharp")
+
+    @staticmethod
+    def inverted_otsu(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+        _, binary = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        inverted = cv2.bitwise_not(binary)
+        return (inverted, "inverted_otsu")
+
+    @staticmethod
+    def morphological_clean(image: np.ndarray) -> Optional[Tuple[np.ndarray, str]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        kernel = np.ones((3, 3), np.uint8)
+        cleaned = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
+        cleaned = cv2.morphologyEx(cleaned, cv2.MORPH_OPEN, kernel)
+        return (cleaned, "morphological")
+
+    @classmethod
+    def all_strategies(cls) -> List[Any]:
+        return [
+            cls.original,
+            cls.grayscale,
+            cls.otsu_threshold,
+            cls.adaptive_threshold,
+            cls.clahe,
+            cls.unsharp_mask,
+            cls.inverted_otsu,
+            cls.morphological_clean,
+        ]
+
+
+class QRDecoderService:
+    def __init__(
+        self,
+        timeout: float = 30.0,
+        max_file_size_mb: float = 20.0,
+        allow_private_network_urls: bool = False,
+    ) -> None:
+        self._timeout = timeout
+        self._max_file_size = int(max_file_size_mb * 1024 * 1024)
+        self._allow_private_network_urls = allow_private_network_urls
+        self._detector = cv2.QRCodeDetector()
+        self._preprocessing = _PreprocessingPipeline()
+
+    # ------------------------------------------------------------------
+    # Public API  (all public methods are async)
+    # ------------------------------------------------------------------
+
+    async def extract(self, source: str) -> QRDecoderResult:
+        if self._is_url(source):
+            return await self.decode_from_url(source)
+        return await self.decode_from_file(source)
+
+    async def decode_from_file(self, file_path: str) -> QRDecoderResult:
+        start = time.perf_counter()
+        try:
+            if not os.path.isfile(file_path):
+                elapsed = round((time.perf_counter() - start) * 1000, 3)
+                return QRDecoderResult(False, [], f"File not found: {file_path}", elapsed)
+            with open(file_path, "rb") as f:
+                raw = f.read()
+            return await self.decode_from_bytes(raw, source_label=file_path)
+        except QRCodeExtractionError as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            return QRDecoderResult(False, [], str(exc), elapsed)
+        except Exception as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            logger.exception("Unexpected error decoding QR file")
+            return QRDecoderResult(False, [], f"Processing failed: {exc}", elapsed)
+
+    async def decode_from_bytes(
+        self, image_bytes: bytes, source_label: str = "<bytes>"
+    ) -> QRDecoderResult:
+        start = time.perf_counter()
+        try:
+            if len(image_bytes) > self._max_file_size:
+                elapsed = round((time.perf_counter() - start) * 1000, 3)
+                return QRDecoderResult(
+                    False, [],
+                    f"Image exceeds maximum size of {self._max_file_size // (1024 * 1024)} MB.",
+                    elapsed,
+                )
+
+            image = await self._load_cv_image_async(image_bytes, source_label)
+            result = await self._decode_async(image, source_label)
+            result.processing_time_ms = round((time.perf_counter() - start) * 1000, 3)
+            return result
+        except QRCodeExtractionError as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            return QRDecoderResult(False, [], str(exc), elapsed)
+        except Exception as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            logger.exception("Unexpected error decoding QR bytes")
+            return QRDecoderResult(False, [], f"Processing failed: {exc}", elapsed)
+
+    async def decode_from_url(self, image_url: str) -> QRDecoderResult:
+        start = time.perf_counter()
+        try:
+            if not self._is_url(image_url):
+                elapsed = round((time.perf_counter() - start) * 1000, 3)
+                return QRDecoderResult(
+                    False, [], f"Not a valid http(s) URL: {image_url}", elapsed
+                )
+
+            self._validate_url_is_safe(image_url)
+            raw = await self._download(image_url)
+            result = await self.decode_from_bytes(raw, source_label=image_url)
+            result.processing_time_ms = round((time.perf_counter() - start) * 1000, 3)
+            return result
+        except QRCodeExtractionError as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            return QRDecoderResult(False, [], str(exc), elapsed)
+        except Exception as exc:
+            elapsed = round((time.perf_counter() - start) * 1000, 3)
+            logger.exception("Unexpected error decoding QR from URL")
+            return QRDecoderResult(False, [], f"Processing failed: {exc}", elapsed)
+
+    # ------------------------------------------------------------------
+    # Async wrappers for CPU-bound OpenCV/PIL operations
+    # ------------------------------------------------------------------
+
+    async def _load_cv_image_async(self, raw_bytes: bytes, origin: str) -> np.ndarray:
+        loop = asyncio_get_loop()
+        return await loop.run_in_executor(None, self._load_cv_image, raw_bytes, origin)
+
+    async def _decode_async(
+        self, image: np.ndarray, source: str
+    ) -> QRDecoderResult:
+        loop = asyncio_get_loop()
+        return await loop.run_in_executor(None, self._decode_sync, image, source)
+
+    # ------------------------------------------------------------------
+    # Synchronous CPU-bound implementations
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_cv_image(raw_bytes: bytes, origin: str) -> np.ndarray:
+        try:
+            pil_image = Image.open(io.BytesIO(raw_bytes))
+            pil_image.load()
+        except UnidentifiedImageError as exc:
+            raise QRCodeExtractionError(
+                f"'{origin}' is not a readable image file"
+            ) from exc
+        except Exception as exc:
+            raise QRCodeExtractionError(
+                f"Could not open image '{origin}': {exc}"
+            ) from exc
+
+        rgb = pil_image.convert("RGB")
+        arr = np.array(rgb)
+        return cv2.cvtColor(arr, cv2.COLOR_RGB2BGR)
+
+    def _decode_sync(self, image: np.ndarray, source: str) -> QRDecoderResult:
+        results = self._decode_with_multi_strategy(image)
+
+        if not results and PYZBAR_AVAILABLE:
+            results = self._decode_with_pyzbar(image)
+
+        if not results:
+            return QRDecoderResult(
+                success=False,
+                decoded_data=[],
+                error_message=(
+                    "No QR code could be detected in the image. "
+                    "Make sure the image is clear, in-frame, and not "
+                    "excessively skewed or low-resolution."
+                ),
+            )
+
+        return QRDecoderResult(success=True, decoded_data=results)
+
+    def _decode_with_multi_strategy(
+        self, image: np.ndarray
+    ) -> List[Dict[str, Any]]:
+        tried_strategies: List[str] = []
+        seen_data: set = set()
+
+        for strategy in _PreprocessingPipeline.all_strategies():
+            processed = strategy(image)
+            if processed is None:
+                continue
+            preprocessed_img, label = processed
+            tried_strategies.append(label)
+
+            try:
+                ok, decoded_info, points, _ = (
+                    self._detector.detectAndDecodeMulti(preprocessed_img)
+                )
+            except cv2.error:
+                ok, decoded_info, points = False, [], None
+
+            if ok:
+                results = []
+                for i, data in enumerate(decoded_info):
+                    if data and data not in seen_data:
+                        seen_data.add(data)
+                        bbox = (
+                            points[i].tolist() if points is not None else None
+                        )
+                        results.append({
+                            "data": data,
+                            "type": "QRCODE",
+                            "bounding_box": bbox,
+                            "decoder": f"opencv_{label}",
+                        })
+                if results:
+                    return results
+
+            try:
+                data, points, _ = self._detector.detectAndDecode(preprocessed_img)
+            except cv2.error:
+                data, points = "", None
+
+            if data and data not in seen_data:
+                seen_data.add(data)
+                bbox = points.tolist() if points is not None else None
+                return [{
+                    "data": data,
+                    "type": "QRCODE",
+                    "bounding_box": bbox,
+                    "decoder": f"opencv_{label}",
+                }]
+
+        logger.debug("All OpenCV strategies failed: %s", tried_strategies)
+        return []
+
+    @staticmethod
+    def _decode_with_pyzbar(image: np.ndarray) -> List[Dict[str, Any]]:
+        results: List[Dict[str, Any]] = []
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        for obj in pyzbar.decode(gray):
+            try:
+                data = obj.data.decode("utf-8")
+            except UnicodeDecodeError:
+                data = obj.data.decode("latin-1", errors="replace")
+            bbox = [[p.x, p.y] for p in obj.polygon] if obj.polygon else None
+            results.append({
+                "data": data,
+                "type": obj.type,
+                "bounding_box": bbox,
+                "decoder": "pyzbar",
+            })
+        return results
+
+    # ------------------------------------------------------------------
+    # URL handling
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _is_url(source: str) -> bool:
+        try:
+            parsed = urlparse(source)
+            return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+        except Exception:
+            return False
+
+    def _validate_url_is_safe(self, url: str) -> None:
+        if self._allow_private_network_urls:
+            return
+
+        hostname = urlparse(url).hostname
+        if not hostname:
+            raise QRCodeExtractionError("URL has no hostname")
+
+        try:
+            resolved = socket.getaddrinfo(hostname, None)
+        except socket.gaierror as exc:
+            raise QRCodeExtractionError(
+                f"Could not resolve host '{hostname}': {exc}"
+            ) from exc
+
+        for family, _, _, _, sockaddr in resolved:
+            ip_str = sockaddr[0]
+            try:
+                ip_obj = ipaddress.ip_address(ip_str)
+            except ValueError:
+                continue
+            if (
+                ip_obj.is_private
+                or ip_obj.is_loopback
+                or ip_obj.is_link_local
+                or ip_obj.is_reserved
+            ):
+                raise QRCodeExtractionError(
+                    f"Refusing to fetch URL: host resolves to a "
+                    f"non-public address ({ip_str})"
+                )
+
+    async def _download(self, url: str) -> bytes:
+        try:
+            async with httpx.AsyncClient(
+                timeout=self._timeout, follow_redirects=True
+            ) as client:
+                async with client.stream("GET", url) as resp:
+                    resp.raise_for_status()
+
+                    content_length = resp.headers.get("Content-Length")
+                    if content_length is not None:
+                        try:
+                            if int(content_length) > self._max_file_size:
+                                raise QRCodeExtractionError(
+                                    f"Remote file too large "
+                                    f"(Content-Length={content_length} bytes)"
+                                )
+                        except ValueError:
+                            pass
+
+                    chunks = []
+                    total = 0
+                    async for chunk in resp.aiter_bytes(chunk_size=65536):
+                        total += len(chunk)
+                        if total > self._max_file_size:
+                            raise QRCodeExtractionError(
+                                f"Download exceeded max allowed size "
+                                f"of {self._max_file_size} bytes"
+                            )
+                        chunks.append(chunk)
+
+                    data = b"".join(chunks)
+                    if not data:
+                        raise QRCodeExtractionError(
+                            "Downloaded content was empty"
+                        )
+                    return data
+        except httpx.HTTPStatusError as exc:
+            raise QRCodeExtractionError(
+                f"Failed to fetch image from URL: HTTP {exc.response.status_code}"
+            ) from exc
+        except httpx.RequestError as exc:
+            raise QRCodeExtractionError(
+                f"Failed to fetch image from URL: {exc}"
+            ) from exc
+
+
+def asyncio_get_loop():
+    import asyncio
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.new_event_loop()

app/utils/json_utils.py

@@ -1,53 +1,16 @@
 from __future__ import annotations
 
-import json
 import logging
-import re
 from typing import Any, List, Optional
 
 logger = logging.getLogger(__name__)
 
 
 def extract_json_blocks(text: str) -> List[Any]:
-    blocks: List[Any] = []
-
-    stripped = text.strip()
-    try:
-        blocks.append(json.loads(stripped))
-        return blocks
-    except json.JSONDecodeError:
-        pass
-
-    pattern = r"```json\s*\n?(.*?)```"
-    for match in re.findall(pattern, text, re.DOTALL):
-        stripped = match.strip()
-        if stripped:
-            try:
-                blocks.append(json.loads(stripped))
-            except json.JSONDecodeError:
-                logger.warning("Failed to parse JSON block: %s", stripped[:100])
-
-    if not blocks:
-        for delim in (("{", "}"), ("[", "]")):
-            start = text.find(delim[0])
-            end = text.rfind(delim[1])
-            if start != -1 and end != -1 and end > start:
-                candidate = text[start : end + 1]
-                try:
-                    blocks.append(json.loads(candidate))
-                except json.JSONDecodeError:
-                    pass
-
-    return blocks
+    from app.services.json_service import extract_json_from_content as _extract
+    return _extract(text)
 
 
 def extract_single_json(text: str) -> Optional[Any]:
-    """Extract a single JSON value from text, optimized for structured output.
-
-    Tries in order:
-    1. Parse entire text as JSON
-    2. Extract from ```json code fences
-    3. Find first {..} or [..] block
-    """
-    blocks = extract_json_blocks(text)
-    return blocks[0] if blocks else None
+    from app.services.json_service import extract_first_json as _extract
+    return _extract(text)

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "qrcode[pil]>=8.0"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

requirements.txt

@@ -10,6 +10,9 @@ numpy>=1.26.0
 rapidocr-onnxruntime>=1.4.4
 onnxruntime>=1.18.0
 pillow>=10.0.0
+
+# QR / image processing
+opencv-python-headless>=4.9.0
 pypdfium2>=4.30.0
 pandas>=2.0.0
 matplotlib>=3.8.0
@@ -58,3 +61,6 @@ Unidecode>=1.3.8
 
 # JSON Schema validation
 jsonschema>=4.21.0
+
+# QR code generation (testing)
+qrcode[pil]>=8.0