python-rerouting-library 0.2.1__py3-none-any.whl

python_rerouting_library/__init__.py

@@ -0,0 +1,25 @@
+from .dispatcher import (
+    Dispatcher,
+    DispatchResult,
+)
+from .privacy import (
+    PrivacyDecision,
+    PrivacyDetector,
+)
+from .router import (
+    RouteDecision,
+    Router,
+)
+
+
+__all__ = [
+    "Router",
+    "RouteDecision",
+    "Dispatcher",
+    "DispatchResult",
+    "PrivacyDetector",
+    "PrivacyDecision",
+]
+
+
+__version__ = "0.2.1"

python_rerouting_library/backends/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from .cloud import CloudBackend
+    from .local_llama import LocalLlamaBackend
+
+
+__all__ = [
+    "LocalLlamaBackend",
+    "CloudBackend",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "CloudBackend":
+        from .cloud import CloudBackend
+
+        return CloudBackend
+
+    if name == "LocalLlamaBackend":
+        from .local_llama import LocalLlamaBackend
+
+        return LocalLlamaBackend
+
+    raise AttributeError(
+        f"module {__name__!r} has no attribute {name!r}"
+    )

python_rerouting_library/backends/cloud.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from openai import OpenAI
+
+from python_rerouting_library.exceptions import CloudBackendError
+
+
+class CloudBackend:
+    name = "cloud-api"
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        model: str,
+        api_key: str,
+        max_tokens: int = 1024,
+        temperature: float = 0.0,
+    ) -> None:
+        self.client = OpenAI(
+            base_url=base_url,
+            api_key=api_key,
+        )
+
+        self.model = model
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+    def generate(self, query: str) -> str:
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": query,
+                    }
+                ],
+                temperature=self.temperature,
+                max_completion_tokens=self.max_tokens,
+            )
+
+            content = response.choices[0].message.content
+
+            if not content:
+                raise CloudBackendError(
+                    "Cloud provider returned no text."
+                )
+
+            return content
+
+        except CloudBackendError:
+            raise
+
+        except Exception as exc:
+            raise CloudBackendError(
+                "Cloud API request failed."
+            ) from exc

python_rerouting_library/backends/local_llama.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from llama_cpp import Llama
+
+from python_rerouting_library.exceptions import LocalBackendError
+
+
+class LocalLlamaBackend:
+    name = "local-llama"
+
+    def __init__(
+        self,
+        *,
+        model_path: str | Path,
+        n_ctx: int = 4096,
+        n_threads: int | None = None,
+        max_tokens: int = 512,
+        temperature: float = 0.0,
+    ) -> None:
+        self.model_path = Path(model_path)
+
+        if not self.model_path.is_file():
+            raise FileNotFoundError(
+                f"Local Llama model was not found: {self.model_path}"
+            )
+
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+        try:
+            self._llm = Llama(
+                model_path=str(self.model_path),
+                n_ctx=n_ctx,
+                n_threads=n_threads,
+                verbose=False,
+            )
+
+        except Exception as exc:
+            raise LocalBackendError(
+                "Failed to load the local Llama model."
+            ) from exc
+
+    def generate(self, query: str) -> str:
+        try:
+            result = self._llm.create_chat_completion(
+                messages=[
+                    {
+                        "role": "user",
+                        "content": query,
+                    }
+                ],
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+            )
+
+            content = result["choices"][0]["message"]["content"]
+
+            if not content:
+                raise LocalBackendError(
+                    "Local Llama returned no text."
+                )
+
+            return content
+
+        except LocalBackendError:
+            raise
+
+        except Exception as exc:
+            raise LocalBackendError(
+                "Local Llama generation failed."
+            ) from exc
+        return result["choices"][0]["message"]["content"]

python_rerouting_library/config.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+    router_classifier_path: Path
+    llama_model_path: Path
+
+    cloud_api_key: str
+    cloud_base_url: str
+    cloud_model: str
+
+    local_max_tokens: int = 128
+    cloud_max_tokens: int = 256
+
+    router_simple_threshold: float = 0.40
+    router_complex_threshold: float = 0.60
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        llama_model_path = os.getenv(
+            "LLAMA_MODEL_PATH"
+        )
+
+        cloud_api_key = os.getenv(
+            "CLOUD_API_KEY"
+        )
+
+        router_classifier_path = os.getenv(
+            "ROUTER_CLASSIFIER_PATH"
+        )
+
+        if not llama_model_path:
+            raise RuntimeError(
+                "LLAMA_MODEL_PATH environment "
+                "variable is not set."
+            )
+
+        if not cloud_api_key:
+            raise RuntimeError(
+                "CLOUD_API_KEY environment "
+                "variable is not set."
+            )
+
+        if not router_classifier_path:
+            raise RuntimeError(
+                "ROUTER_CLASSIFIER_PATH environment "
+                "variable is not set. "
+                "python-rerouting-library does not "
+                "ship with a default complexity "
+                "classifier. Train a classifier with "
+                "'python -m "
+                "python_rerouting_library.training' "
+                "or provide your own compatible "
+                "classifier artifact, then set "
+                "ROUTER_CLASSIFIER_PATH to that file."
+            )
+
+        llama_path = Path(
+            llama_model_path
+        ).expanduser()
+
+        if not llama_path.is_file():
+            raise FileNotFoundError(
+                "Local Llama model was not found: "
+                f"{llama_path}"
+            )
+
+        router_path = Path(
+            router_classifier_path
+        ).expanduser()
+
+        if not router_path.is_file():
+            raise FileNotFoundError(
+                "Router classifier was not found: "
+                f"{router_path}. "
+                "python-rerouting-library does not "
+                "bundle a default classifier. "
+                "Train one or provide a compatible "
+                "classifier artifact and set "
+                "ROUTER_CLASSIFIER_PATH to its path."
+            )
+
+        cloud_base_url = os.getenv(
+            "CLOUD_BASE_URL",
+            "https://api.openai.com/v1",
+        )
+
+        cloud_model = os.getenv(
+            "CLOUD_MODEL",
+            "gpt-5.4-nano",
+        )
+
+        return cls(
+            router_classifier_path=router_path,
+            llama_model_path=llama_path,
+            cloud_api_key=cloud_api_key,
+            cloud_base_url=cloud_base_url,
+            cloud_model=cloud_model,
+            local_max_tokens=int(
+                os.getenv(
+                    "LOCAL_MAX_TOKENS",
+                    "128",
+                )
+            ),
+            cloud_max_tokens=int(
+                os.getenv(
+                    "CLOUD_MAX_TOKENS",
+                    "256",
+                )
+            ),
+            router_simple_threshold=float(
+                os.getenv(
+                    "ROUTER_SIMPLE_THRESHOLD",
+                    "0.40",
+                )
+            ),
+            router_complex_threshold=float(
+                os.getenv(
+                    "ROUTER_COMPLEX_THRESHOLD",
+                    "0.60",
+                )
+            ),
+        )

python_rerouting_library/dispatcher.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter
+from typing import Protocol
+
+from .exceptions import (
+    CloudBackendError,
+    DispatchError,
+    LocalBackendError,
+)
+from .privacy import PrivacyDetector
+from .router import RouteDecision, Router
+
+
+class Backend(Protocol):
+    name: str
+
+    def generate(
+        self,
+        query: str,
+    ) -> str:
+        ...
+
+
+@dataclass(frozen=True)
+class DispatchResult:
+    text: str
+    route: RouteDecision
+    backend_name: str
+    fallback_used: bool = False
+    privacy_categories: tuple[str, ...] = ()
+
+
+class Dispatcher:
+    def __init__(
+        self,
+        *,
+        router: Router,
+        simple_backend: Backend,
+        complex_backend: Backend,
+        privacy_detector: (
+            PrivacyDetector | None
+        ) = None,
+    ) -> None:
+        self.router = router
+
+        self.simple_backend = (
+            simple_backend
+        )
+
+        self.complex_backend = (
+            complex_backend
+        )
+
+        self.privacy_detector = (
+            privacy_detector
+            or PrivacyDetector()
+        )
+
+    def run(
+        self,
+        query: str,
+    ) -> DispatchResult:
+        privacy_start = perf_counter()
+
+        privacy_decision = (
+            self.privacy_detector.detect(
+                query
+            )
+        )
+
+        privacy_latency_ms = (
+            perf_counter()
+            - privacy_start
+        ) * 1000.0
+
+        # PRIVACY OVERRIDE:
+        # local execution only.
+        #
+        # Cloud fallback is intentionally
+        # prohibited for privacy-sensitive
+        # queries.
+        if privacy_decision.is_sensitive:
+            decision = RouteDecision(
+                label="privacy_override",
+                confidence=None,
+                complex_probability=None,
+                latency_ms=privacy_latency_ms,
+            )
+
+            try:
+                text = (
+                    self.simple_backend.generate(
+                        query
+                    )
+                )
+
+                return DispatchResult(
+                    text=text,
+                    route=decision,
+                    backend_name=(
+                        self.simple_backend.name
+                    ),
+                    fallback_used=False,
+                    privacy_categories=(
+                        privacy_decision.categories
+                    ),
+                )
+
+            except LocalBackendError as error:
+                raise DispatchError(
+                    "Privacy override requires "
+                    "local processing, but the "
+                    "local backend failed. "
+                    "Cloud fallback was not "
+                    "attempted."
+                ) from error
+
+        # Clean queries continue to the
+        # semantic complexity router.
+        decision = self.router.route(query)
+
+        # SIMPLE:
+        # local first, cloud fallback.
+        if decision.label == "simple":
+            try:
+                text = (
+                    self.simple_backend.generate(
+                        query
+                    )
+                )
+
+                return DispatchResult(
+                    text=text,
+                    route=decision,
+                    backend_name=(
+                        self.simple_backend.name
+                    ),
+                    fallback_used=False,
+                )
+
+            except LocalBackendError:
+                try:
+                    text = (
+                        self.complex_backend.generate(
+                            query
+                        )
+                    )
+
+                    return DispatchResult(
+                        text=text,
+                        route=decision,
+                        backend_name=(
+                            self.complex_backend.name
+                        ),
+                        fallback_used=True,
+                    )
+
+                except CloudBackendError as error:
+                    raise DispatchError(
+                        "Local backend failed "
+                        "and cloud fallback "
+                        "also failed."
+                    ) from error
+
+        # COMPLEX or UNCERTAIN:
+        # cloud only.
+        if decision.label in {
+            "complex",
+            "uncertain",
+        }:
+            try:
+                text = (
+                    self.complex_backend.generate(
+                        query
+                    )
+                )
+
+                return DispatchResult(
+                    text=text,
+                    route=decision,
+                    backend_name=(
+                        self.complex_backend.name
+                    ),
+                    fallback_used=False,
+                )
+
+            except CloudBackendError as error:
+                raise DispatchError(
+                    "Cloud backend failed for "
+                    "a query requiring cloud "
+                    "routing. Local fallback "
+                    "was not attempted."
+                ) from error
+
+        raise DispatchError(
+            "Unsupported route label: "
+            f"{decision.label!r}"
+        )

python_rerouting_library/exceptions.py

@@ -0,0 +1,18 @@
+class ReroutingLibraryError(Exception):
+    """Base exception for the routing library."""
+
+
+class BackendError(ReroutingLibraryError):
+    """Base exception for backend failures."""
+
+
+class LocalBackendError(BackendError):
+    """Local Llama backend failed."""
+
+
+class CloudBackendError(BackendError):
+    """Cloud backend failed."""
+
+
+class DispatchError(ReroutingLibraryError):
+    """Dispatcher could not complete the request."""

python_rerouting_library/privacy.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PrivacyDecision:
+    is_sensitive: bool
+    categories: tuple[str, ...]
+
+
+class PrivacyDetector:
+    """
+    Detect common sensitive-data patterns before cloud routing.
+
+    The detector returns only category names. It never returns
+    or logs the matched sensitive value.
+    """
+
+    _EMAIL_PATTERNS = (
+        re.compile(
+            r"\b[A-Za-z0-9._%+-]+@"
+            r"[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"
+        ),
+    )
+
+    _PHONE_PATTERNS = (
+        re.compile(
+            r"(?<!\d)"
+            r"(?:\+?1[\s.-]?)?"
+            r"(?:\(\d{3}\)|\d{3})"
+            r"[\s.-]?\d{3}"
+            r"[\s.-]?\d{4}"
+            r"(?!\d)"
+        ),
+    )
+
+    _SSN_PATTERNS = (
+        re.compile(
+            r"\b\d{3}-\d{2}-\d{4}\b"
+        ),
+    )
+
+    _API_KEY_PATTERNS = (
+        # OpenAI-style secret keys.
+        re.compile(
+            r"\bsk-[A-Za-z0-9_-]{20,}\b"
+        ),
+
+        # GitHub classic-style tokens.
+        re.compile(
+            r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"
+        ),
+
+        # GitHub fine-grained tokens.
+        re.compile(
+            r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"
+        ),
+
+        # Google API-key style.
+        re.compile(
+            r"\bAIza[A-Za-z0-9_-]{35}\b"
+        ),
+
+        # AWS access-key identifiers.
+        re.compile(
+            r"\bAKIA[0-9A-Z]{16}\b"
+        ),
+    )
+
+    _CREDIT_CARD_CANDIDATE = re.compile(
+        r"(?<!\d)"
+        r"(?:\d[ -]*?){12,18}\d"
+        r"(?!\d)"
+    )
+
+    def detect(self, text: str) -> PrivacyDecision:
+        if not isinstance(text, str):
+            raise TypeError(
+                "PrivacyDetector input must be a string."
+            )
+
+        categories: list[str] = []
+
+        if self._matches(
+            text,
+            self._EMAIL_PATTERNS,
+        ):
+            categories.append("email")
+
+        if self._matches(
+            text,
+            self._PHONE_PATTERNS,
+        ):
+            categories.append("phone")
+
+        if self._matches(
+            text,
+            self._SSN_PATTERNS,
+        ):
+            categories.append("ssn")
+
+        if self._matches(
+            text,
+            self._API_KEY_PATTERNS,
+        ):
+            categories.append("api_key")
+
+        if self._contains_credit_card(text):
+            categories.append("credit_card")
+
+        return PrivacyDecision(
+            is_sensitive=bool(categories),
+            categories=tuple(categories),
+        )
+
+    @staticmethod
+    def _matches(
+        text: str,
+        patterns: tuple[re.Pattern[str], ...],
+    ) -> bool:
+        return any(
+            pattern.search(text)
+            for pattern in patterns
+        )
+
+    def _contains_credit_card(
+        self,
+        text: str,
+    ) -> bool:
+        for match in self._CREDIT_CARD_CANDIDATE.finditer(
+            text
+        ):
+            digits = re.sub(
+                r"\D",
+                "",
+                match.group(0),
+            )
+
+            if not 13 <= len(digits) <= 19:
+                continue
+
+            if len(set(digits)) == 1:
+                continue
+
+            if self._passes_luhn(digits):
+                return True
+
+        return False
+
+    @staticmethod
+    def _passes_luhn(number: str) -> bool:
+        digits = [
+            int(character)
+            for character in number
+        ]
+
+        checksum = 0
+        parity = len(digits) % 2
+
+        for index, digit in enumerate(digits):
+            if index % 2 == parity:
+                digit *= 2
+
+                if digit > 9:
+                    digit -= 9
+
+            checksum += digit
+
+        return checksum % 10 == 0