accessible-math-reader 0.1.0__py3-none-any.whl

accessible_math_reader/__init__.py

@@ -0,0 +1,64 @@
+"""!
+@file __init__.py
+@brief Accessible Math Reader - Screen-reader-first math accessibility toolkit.
+
+@details
+This package provides tools for converting mathematical notation
+(LaTeX, MathML, and plaintext/Unicode math) into accessible formats
+including speech output and Braille notation.
+
+@section usage Public API Usage
+
+@code{.py}
+from accessible_math_reader import MathReader, VerbosityLevel
+
+# Create a reader instance
+reader = MathReader()
+
+# Convert LaTeX to speech text
+speech = reader.to_speech(r"\\frac{a}{b}")
+# Output: "a divided by b"
+
+# Convert to Nemeth Braille
+braille = reader.to_braille(r"\\frac{a}{b}", notation="nemeth")
+# Output: "⠹⠁⠌⠃⠼"
+
+# Generate audio file
+reader.to_audio(r"\\frac{a}{b}", output_path="output.mp3")
+@endcode
+
+@author Accessible Math Reader Contributors
+@version 0.1.0
+@date 2025
+@copyright MIT License
+"""
+
+from accessible_math_reader.core.parser import MathParser
+from accessible_math_reader.core.semantic import SemanticNode, NodeType
+from accessible_math_reader.core.renderer import MathRenderer
+from accessible_math_reader.speech.engine import SpeechEngine
+from accessible_math_reader.speech.rules import SpeechRuleSet, VerbosityLevel
+from accessible_math_reader.braille.nemeth import NemethConverter
+from accessible_math_reader.braille.ueb import UEBConverter
+from accessible_math_reader.config import Config
+from accessible_math_reader.reader import MathReader
+
+__version__ = "0.1.0"
+__all__ = [
+    # Main interface
+    "MathReader",
+    # Core components  
+    "MathParser",
+    "SemanticNode",
+    "NodeType",
+    "MathRenderer",
+    # Speech
+    "SpeechEngine",
+    "SpeechRuleSet",
+    "VerbosityLevel",
+    # Braille
+    "NemethConverter",
+    "UEBConverter",
+    # Configuration
+    "Config",
+]

accessible_math_reader/api/__init__.py

@@ -0,0 +1,16 @@
+"""!
+@file api/__init__.py
+@brief REST API subsystem for Accessible Math Reader.
+
+@details
+Provides a versioned REST API (``/api/v1/``) as a Flask Blueprint
+that can be registered on any Flask application.  Includes optional
+authentication, rate limiting, and Prometheus metrics.
+
+@author Accessible Math Reader Contributors
+@version 0.2.0
+"""
+
+from accessible_math_reader.api.app import create_api_blueprint
+
+__all__ = ["create_api_blueprint"]

accessible_math_reader/api/app.py

@@ -0,0 +1,315 @@
+"""!
+@file api/app.py
+@brief REST API Blueprint for Accessible Math Reader.
+
+@details
+Exposes the full AMR pipeline as a versioned JSON REST API.
+
+Endpoints (all under ``/api/v1/``):
+  POST /api/v1/speech     — convert math to spoken English
+  POST /api/v1/braille    — convert math to Braille
+  POST /api/v1/structure  — return the semantic AST as JSON
+  POST /api/v1/audio      — synthesise speech and return MP3 binary
+  POST /api/v1/validate   — run accessibility validation
+
+Infrastructure routes (mounted at root):
+  GET  /health            — liveness probe  (Feature 6)
+  GET  /readiness         — readiness probe (Feature 6)
+  GET  /metrics           — Prometheus text exposition (Feature 7)
+
+All conversion endpoints reuse ``MathReader`` from the core library —
+no logic is duplicated.
+
+@author Accessible Math Reader Contributors
+@version 0.2.0
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import tempfile
+import time
+from typing import Any
+
+from flask import Blueprint, Response, jsonify, request, send_file
+
+from accessible_math_reader.api.errors import (
+    ErrorCode,
+    error_response,
+    register_error_handlers,
+)
+from accessible_math_reader.api.middleware import rate_limit, require_api_key
+from accessible_math_reader.api.schemas import (
+    braille_response,
+    speech_response,
+    structure_response,
+    validate_math_request,
+    validation_response,
+)
+from accessible_math_reader.observability.metrics import MetricsCollector
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Module-level singletons (instantiated at import time)
+# ---------------------------------------------------------------------------
+
+_metrics = MetricsCollector()
+
+
+# ---------------------------------------------------------------------------
+# Blueprint factory
+# ---------------------------------------------------------------------------
+
+def create_api_blueprint() -> Blueprint:
+    """!
+    @brief Create and return the REST API Blueprint.
+
+    @details
+    Register this blueprint on any Flask app:
+
+    @code{.py}
+    from accessible_math_reader.api import create_api_blueprint
+
+    app = Flask(__name__)
+    app.register_blueprint(create_api_blueprint())
+    @endcode
+
+    @return Configured Flask Blueprint
+    """
+    bp = Blueprint("amr_api", __name__)
+    register_error_handlers(bp)
+
+    # ── Lazy reader accessor ──────────────────────────────────────
+    _reader_cache: dict[str, Any] = {}
+
+    def _get_reader() -> Any:
+        """Get or create a shared MathReader instance."""
+        if "reader" not in _reader_cache:
+            from accessible_math_reader.reader import MathReader
+            _reader_cache["reader"] = MathReader()
+        return _reader_cache["reader"]
+
+    # ══════════════════════════════════════════════════════════════
+    # Conversion Endpoints  (/api/v1/…)
+    # ══════════════════════════════════════════════════════════════
+
+    @bp.route("/api/v1/speech", methods=["POST"])
+    @require_api_key
+    @rate_limit
+    def api_speech() -> Any:
+        """!
+        @brief Convert math input to spoken English text.
+
+        @details
+        Accepts JSON: ``{"input": "...", "format": "auto"}``
+        Returns JSON: ``{"speech": "...", "input": "..."}``
+        """
+        _metrics.inc_request("speech")
+        data = request.get_json(silent=True)
+        err, params = validate_math_request(data)
+        if err:
+            return error_response(err, ErrorCode.VALIDATION_ERROR, 400)
+
+        try:
+            reader = _get_reader()
+            with _metrics.timer("speech"):
+                text = reader.to_speech(params["input"])
+            return jsonify(speech_response(text, params["input"]))
+        except Exception as exc:
+            logger.exception("Speech conversion failed")
+            _metrics.inc_error("speech_error")
+            return error_response(
+                str(exc), ErrorCode.PARSE_ERROR, 422
+            )
+
+    @bp.route("/api/v1/braille", methods=["POST"])
+    @require_api_key
+    @rate_limit
+    def api_braille() -> Any:
+        """!
+        @brief Convert math input to Braille notation.
+
+        @details
+        Accepts JSON: ``{"input": "...", "notation": "nemeth"}``
+        Returns JSON: ``{"braille": "...", "notation": "...", "input": "..."}``
+        """
+        _metrics.inc_request("braille")
+        data = request.get_json(silent=True)
+        err, params = validate_math_request(data)
+        if err:
+            return error_response(err, ErrorCode.VALIDATION_ERROR, 400)
+
+        try:
+            reader = _get_reader()
+            with _metrics.timer("braille"):
+                text = reader.to_braille(
+                    params["input"], notation=params["notation"]
+                )
+            return jsonify(
+                braille_response(text, params["notation"], params["input"])
+            )
+        except Exception as exc:
+            logger.exception("Braille conversion failed")
+            _metrics.inc_error("braille_error")
+            return error_response(
+                str(exc), ErrorCode.PARSE_ERROR, 422
+            )
+
+    @bp.route("/api/v1/structure", methods=["POST"])
+    @require_api_key
+    @rate_limit
+    def api_structure() -> Any:
+        """!
+        @brief Return the semantic AST of a math expression as JSON.
+
+        @details
+        Accepts JSON: ``{"input": "..."}``
+        Returns JSON: ``{"structure": {...}, "input": "..."}``
+        """
+        _metrics.inc_request("structure")
+        data = request.get_json(silent=True)
+        err, params = validate_math_request(data)
+        if err:
+            return error_response(err, ErrorCode.VALIDATION_ERROR, 400)
+
+        try:
+            reader = _get_reader()
+            with _metrics.timer("structure"):
+                struct = reader.get_structure(params["input"])
+            return jsonify(structure_response(struct, params["input"]))
+        except Exception as exc:
+            logger.exception("Structure extraction failed")
+            _metrics.inc_error("structure_error")
+            return error_response(
+                str(exc), ErrorCode.PARSE_ERROR, 422
+            )
+
+    @bp.route("/api/v1/audio", methods=["POST"])
+    @require_api_key
+    @rate_limit
+    def api_audio() -> Any:
+        """!
+        @brief Synthesise math speech and return an MP3 file.
+
+        @details
+        Accepts JSON: ``{"input": "..."}``
+        Returns: binary MP3 with ``Content-Type: audio/mpeg``
+        """
+        _metrics.inc_request("audio")
+        data = request.get_json(silent=True)
+        err, params = validate_math_request(data)
+        if err:
+            return error_response(err, ErrorCode.VALIDATION_ERROR, 400)
+
+        try:
+            reader = _get_reader()
+            with _metrics.timer("audio"):
+                # Create a temp file for the audio
+                tmp = tempfile.NamedTemporaryFile(
+                    suffix=".mp3", delete=False
+                )
+                tmp_path = tmp.name
+                tmp.close()
+                reader.to_audio(params["input"], tmp_path)
+
+            return send_file(
+                tmp_path,
+                mimetype="audio/mpeg",
+                as_attachment=True,
+                download_name="speech.mp3",
+            )
+        except Exception as exc:
+            logger.exception("Audio synthesis failed")
+            _metrics.inc_error("audio_error")
+            return error_response(
+                str(exc), ErrorCode.INTERNAL_ERROR, 500
+            )
+
+    @bp.route("/api/v1/validate", methods=["POST"])
+    @require_api_key
+    @rate_limit
+    def api_validate() -> Any:
+        """!
+        @brief Run accessibility validation on a math expression.
+
+        @details
+        Accepts JSON: ``{"input": "..."}``
+        Returns JSON:
+        @code{.json}
+        {
+          "wcag_violations": [],
+          "missing_semantic_structure": [],
+          "aria_warnings": [],
+          "valid": true
+        }
+        @endcode
+        """
+        _metrics.inc_request("validate")
+        data = request.get_json(silent=True)
+        err, params = validate_math_request(data)
+        if err:
+            return error_response(err, ErrorCode.VALIDATION_ERROR, 400)
+
+        try:
+            from accessible_math_reader.validation.validator import (
+                MathValidator,
+            )
+
+            with _metrics.timer("validate"):
+                validator = MathValidator()
+                results = validator.validate_expression(params["input"])
+            return jsonify(validation_response(results))
+        except Exception as exc:
+            logger.exception("Validation failed")
+            _metrics.inc_error("validate_error")
+            return error_response(
+                str(exc), ErrorCode.INTERNAL_ERROR, 500
+            )
+
+    # ══════════════════════════════════════════════════════════════
+    # Infrastructure Endpoints  (Feature 6 — Kubernetes)
+    # ══════════════════════════════════════════════════════════════
+
+    @bp.route("/health", methods=["GET"])
+    def health() -> Any:
+        """!
+        @brief Liveness probe — returns 200 if the process is alive.
+        """
+        return jsonify({"status": "healthy", "timestamp": time.time()})
+
+    @bp.route("/readiness", methods=["GET"])
+    def readiness() -> Any:
+        """!
+        @brief Readiness probe — returns 200 if the service can accept requests.
+
+        @details
+        Checks that the core pipeline can be initialised.  Returns 503
+        if something is wrong.
+        """
+        try:
+            _get_reader()
+            return jsonify({"status": "ready", "timestamp": time.time()})
+        except Exception as exc:
+            return jsonify({
+                "status": "not ready",
+                "error": str(exc),
+                "timestamp": time.time(),
+            }), 503
+
+    @bp.route("/metrics", methods=["GET"])
+    def metrics() -> Any:
+        """!
+        @brief Prometheus metrics endpoint.
+
+        @details
+        Returns metrics in Prometheus text exposition format.
+        """
+        return Response(
+            _metrics.render(),
+            mimetype="text/plain; version=0.0.4; charset=utf-8",
+        )
+
+    return bp

accessible_math_reader/api/errors.py

@@ -0,0 +1,118 @@
+"""!
+@file api/errors.py
+@brief Structured JSON error responses for the REST API.
+
+@details
+Provides standardised error response formatting and Flask error
+handler registration so that all API errors return consistent JSON.
+
+Response format:
+@code{.json}
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE",
+  "details": {}
+}
+@endcode
+
+@author Accessible Math Reader Contributors
+@version 0.2.0
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from flask import jsonify
+
+
+# ---------------------------------------------------------------------------
+# Error codes
+# ---------------------------------------------------------------------------
+
+class ErrorCode:
+    """Machine-readable error codes returned in the ``code`` field."""
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    PARSE_ERROR = "PARSE_ERROR"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    AUTH_INVALID = "AUTH_INVALID"
+    RATE_LIMITED = "RATE_LIMITED"
+    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE"
+    NOT_FOUND = "NOT_FOUND"
+
+
+# ---------------------------------------------------------------------------
+# Response helpers
+# ---------------------------------------------------------------------------
+
+def error_response(
+    message: str,
+    code: str,
+    status: int = 400,
+    details: Optional[dict[str, Any]] = None,
+) -> tuple:
+    """!
+    @brief Build a JSON error response tuple.
+
+    @param message  Human-readable error description
+    @param code     Machine-readable error code from ``ErrorCode``
+    @param status   HTTP status code (default 400)
+    @param details  Optional extra context
+    @return (response, status_code) tuple suitable for Flask
+    """
+    body: dict[str, Any] = {
+        "error": message,
+        "code": code,
+    }
+    if details:
+        body["details"] = details
+    return jsonify(body), status
+
+
+# ---------------------------------------------------------------------------
+# Flask error handler registration
+# ---------------------------------------------------------------------------
+
+def register_error_handlers(app_or_bp: Any) -> None:
+    """!
+    @brief Register JSON error handlers on a Flask app or Blueprint.
+
+    @param app_or_bp  Flask app or Blueprint instance
+    """
+
+    @app_or_bp.errorhandler(400)
+    def bad_request(exc: Any) -> tuple:
+        return error_response(
+            str(exc), ErrorCode.VALIDATION_ERROR, 400
+        )
+
+    @app_or_bp.errorhandler(404)
+    def not_found(exc: Any) -> tuple:
+        return error_response(
+            "Endpoint not found", ErrorCode.NOT_FOUND, 404
+        )
+
+    @app_or_bp.errorhandler(413)
+    def payload_too_large(exc: Any) -> tuple:
+        return error_response(
+            "Request payload exceeds size limit",
+            ErrorCode.PAYLOAD_TOO_LARGE,
+            413,
+        )
+
+    @app_or_bp.errorhandler(429)
+    def rate_limited(exc: Any) -> tuple:
+        return error_response(
+            "Rate limit exceeded — please retry later",
+            ErrorCode.RATE_LIMITED,
+            429,
+        )
+
+    @app_or_bp.errorhandler(500)
+    def internal_error(exc: Any) -> tuple:
+        return error_response(
+            "Internal server error",
+            ErrorCode.INTERNAL_ERROR,
+            500,
+        )

accessible_math_reader/api/middleware.py

@@ -0,0 +1,172 @@
+"""!
+@file api/middleware.py
+@brief Optional authentication and rate-limiting middleware.
+
+@details
+Provides two Flask decorators that can be applied to API endpoints:
+  - ``require_api_key`` — checks ``X-API-Key`` header against a
+    configured list of valid keys.
+  - ``rate_limit``      — enforces a per-IP sliding-window request
+    limit using an in-memory store (no Redis required).
+
+Both are **disabled by default** and controlled via environment
+variables.  Self-hosted users should leave ``AMR_ENABLE_AUTH`` and
+``AMR_ENABLE_RATE_LIMIT`` as ``false`` for zero overhead.
+
+Environment variables:
+  AMR_ENABLE_AUTH     — "true" to require API keys (default: false)
+  AMR_API_KEYS        — comma-separated list of valid keys
+  AMR_ENABLE_RATE_LIMIT — "true" to enable (default: false)
+  AMR_RATE_LIMIT      — "<count>/<period>" e.g. "100/minute" (default)
+
+@author Accessible Math Reader Contributors
+@version 0.2.0
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import time
+from collections import defaultdict
+from threading import Lock
+from typing import Any, Callable
+
+from flask import request
+
+from accessible_math_reader.api.errors import ErrorCode, error_response
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Authentication
+# ═══════════════════════════════════════════════════════════════════════════
+
+def _auth_enabled() -> bool:
+    """Check if API-key authentication is turned on."""
+    return os.environ.get("AMR_ENABLE_AUTH", "false").lower() == "true"
+
+
+def _valid_keys() -> set[str]:
+    """Parse the comma-separated list of valid API keys."""
+    raw = os.environ.get("AMR_API_KEYS", "")
+    return {k.strip() for k in raw.split(",") if k.strip()}
+
+
+def require_api_key(fn: Callable) -> Callable:
+    """!
+    @brief Decorator: reject requests missing a valid ``X-API-Key`` header.
+
+    @details
+    When ``AMR_ENABLE_AUTH=true``, every decorated endpoint requires
+    the header ``X-API-Key: <key>`` where ``<key>`` is one of the
+    values in the ``AMR_API_KEYS`` environment variable.
+
+    When authentication is disabled (the default), this decorator
+    is a transparent pass-through.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if not _auth_enabled():
+            return fn(*args, **kwargs)
+
+        key = request.headers.get("X-API-Key", "")
+        keys = _valid_keys()
+        if not keys:
+            # No keys configured — treat as misconfiguration, deny all
+            return error_response(
+                "Authentication is enabled but no API keys are configured",
+                ErrorCode.INTERNAL_ERROR,
+                500,
+            )
+        if key not in keys:
+            return error_response(
+                "Missing or invalid API key",
+                ErrorCode.AUTH_INVALID,
+                401,
+            )
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Rate Limiting
+# ═══════════════════════════════════════════════════════════════════════════
+
+# In-memory sliding window — per IP
+_rate_lock = Lock()
+_rate_store: dict[str, list[float]] = defaultdict(list)
+
+
+def _parse_rate_limit() -> tuple[int, float]:
+    """!
+    @brief Parse ``AMR_RATE_LIMIT`` into (count, window_seconds).
+
+    @details
+    Accepted formats:
+      - "100/minute"  →  (100, 60)
+      - "1000/hour"   →  (1000, 3600)
+      - "10/second"   →  (10, 1)
+
+    Defaults to 100/minute.
+
+    @return Tuple of (max_requests, window_in_seconds)
+    """
+    raw = os.environ.get("AMR_RATE_LIMIT", "100/minute")
+    try:
+        count_str, period = raw.strip().split("/")
+        count = int(count_str)
+    except (ValueError, IndexError):
+        return 100, 60.0
+
+    period_map = {
+        "second": 1.0,
+        "minute": 60.0,
+        "hour": 3600.0,
+        "day": 86400.0,
+    }
+    window = period_map.get(period.lower(), 60.0)
+    return count, window
+
+
+def rate_limit(fn: Callable) -> Callable:
+    """!
+    @brief Decorator: enforce per-IP request rate limiting.
+
+    @details
+    Uses an in-memory sliding window.  When ``AMR_ENABLE_RATE_LIMIT``
+    is ``false`` (the default), this decorator is a transparent
+    pass-through.
+
+    The limit is configured via ``AMR_RATE_LIMIT`` (e.g. "100/minute").
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if os.environ.get(
+            "AMR_ENABLE_RATE_LIMIT", "false"
+        ).lower() != "true":
+            return fn(*args, **kwargs)
+
+        ip = request.remote_addr or "unknown"
+        max_requests, window = _parse_rate_limit()
+        now = time.time()
+        cutoff = now - window
+
+        with _rate_lock:
+            # Prune old entries
+            _rate_store[ip] = [
+                t for t in _rate_store[ip] if t > cutoff
+            ]
+            if len(_rate_store[ip]) >= max_requests:
+                return error_response(
+                    "Rate limit exceeded — please retry later",
+                    ErrorCode.RATE_LIMITED,
+                    429,
+                )
+            _rate_store[ip].append(now)
+
+        return fn(*args, **kwargs)
+
+    return wrapper