hfl 0.1.0__py3-none-any.whl

hfl/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""hfl - Run HuggingFace models locally like Ollama."""
+
+__version__ = "0.1.0"

hfl/api/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""API server module for hfl."""

hfl/api/converters.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""Request/response converters for API compatibility.
+
+Consolidates conversion logic between different API formats:
+- OpenAI API format
+- Ollama API format
+- Internal GenerationConfig
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hfl.engine.base import GenerationConfig
+
+if TYPE_CHECKING:
+    from hfl.api.schemas import ChatCompletionRequest, CompletionRequest
+
+
+def clamp(value: float | int, min_val: float | int, max_val: float | int) -> float | int:
+    """Clamp value to range [min_val, max_val].
+
+    Args:
+        value: Value to clamp
+        min_val: Minimum allowed value
+        max_val: Maximum allowed value
+
+    Returns:
+        Clamped value
+    """
+    return max(min_val, min(max_val, value))
+
+
+def openai_to_generation_config(
+    req: ChatCompletionRequest | CompletionRequest,
+) -> GenerationConfig:
+    """Convert OpenAI API request to GenerationConfig.
+
+    Args:
+        req: OpenAI-style request (ChatCompletionRequest or CompletionRequest)
+
+    Returns:
+        GenerationConfig for inference
+    """
+    # Handle stop sequences - can be string or list
+    stop = req.stop if isinstance(req.stop, list) else ([req.stop] if req.stop else None)
+
+    return GenerationConfig(
+        temperature=req.temperature,
+        top_p=req.top_p,
+        max_tokens=req.max_tokens or 2048,
+        stop=stop,
+        seed=req.seed or -1,
+    )
+
+
+def ollama_to_generation_config(options: dict[str, Any] | None) -> GenerationConfig:
+    """Convert Ollama options dict to GenerationConfig.
+
+    Validates and clamps all values to safe ranges per Ollama API spec.
+
+    Args:
+        options: Ollama-style options dict (may be None)
+
+    Returns:
+        GenerationConfig for inference
+    """
+    opts = options or {}
+
+    # Validate and clamp all values to safe ranges
+    temperature = clamp(float(opts.get("temperature", 0.7)), 0.0, 2.0)
+    top_p = clamp(float(opts.get("top_p", 0.9)), 0.0, 1.0)
+    top_k = clamp(int(opts.get("top_k", 40)), 1, 1000)
+    max_tokens = clamp(int(opts.get("num_predict", 2048)), 1, 128000)
+    repeat_penalty = clamp(float(opts.get("repeat_penalty", 1.1)), 0.0, 2.0)
+    seed = int(opts.get("seed", -1))
+
+    return GenerationConfig(
+        temperature=temperature,
+        top_p=top_p,
+        top_k=int(top_k),
+        max_tokens=int(max_tokens),
+        repeat_penalty=repeat_penalty,
+        seed=seed,
+        stop=opts.get("stop"),
+    )
+
+
+def generation_config_to_openai(config: GenerationConfig) -> dict[str, Any]:
+    """Convert GenerationConfig to OpenAI-style options dict.
+
+    Useful for logging or returning config in API responses.
+
+    Args:
+        config: Internal generation config
+
+    Returns:
+        OpenAI-style options dict
+    """
+    result: dict[str, Any] = {}
+
+    if config.temperature is not None:
+        result["temperature"] = config.temperature
+    if config.top_p is not None:
+        result["top_p"] = config.top_p
+    if config.max_tokens is not None:
+        result["max_tokens"] = config.max_tokens
+    if config.stop:
+        result["stop"] = config.stop
+    if config.seed is not None and config.seed != -1:
+        result["seed"] = config.seed
+
+    return result
+
+
+def generation_config_to_ollama(config: GenerationConfig) -> dict[str, Any]:
+    """Convert GenerationConfig to Ollama-style options dict.
+
+    Useful for logging or returning config in API responses.
+
+    Args:
+        config: Internal generation config
+
+    Returns:
+        Ollama-style options dict
+    """
+    result: dict[str, Any] = {}
+
+    if config.temperature is not None:
+        result["temperature"] = config.temperature
+    if config.top_p is not None:
+        result["top_p"] = config.top_p
+    if config.top_k is not None:
+        result["top_k"] = config.top_k
+    if config.max_tokens is not None:
+        result["num_predict"] = config.max_tokens
+    if config.repeat_penalty is not None:
+        result["repeat_penalty"] = config.repeat_penalty
+    if config.stop:
+        result["stop"] = config.stop
+    if config.seed is not None and config.seed != -1:
+        result["seed"] = config.seed
+
+    return result

hfl/api/deprecation.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""
+Deprecation utilities for API endpoints.
+
+Provides helpers for marking endpoints as deprecated with standard
+HTTP headers (Deprecation, Sunset) per RFC 8594.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from functools import wraps
+from typing import Any, Callable
+
+from fastapi import Response
+
+
+def add_deprecation_headers(
+    response: Response,
+    deprecated_at: str | None = None,
+    sunset: str | None = None,
+    alternative: str | None = None,
+) -> None:
+    """Add deprecation headers to a response.
+
+    Implements RFC 8594 deprecation header format.
+
+    Args:
+        response: FastAPI/Starlette Response object
+        deprecated_at: ISO 8601 date when deprecation started
+        sunset: ISO 8601 date when endpoint will be removed
+        alternative: URL or path to the replacement endpoint
+
+    Example:
+        >>> response = Response()
+        >>> add_deprecation_headers(
+        ...     response,
+        ...     deprecated_at="2026-01-01",
+        ...     sunset="2027-01-01",
+        ...     alternative="/v2/chat/completions"
+        ... )
+    """
+    response.headers["Deprecation"] = "true"
+
+    if deprecated_at:
+        # RFC 8594 format: "@" followed by Unix timestamp or HTTP date
+        try:
+            dt = datetime.fromisoformat(deprecated_at)
+            response.headers["Deprecation"] = f"@{int(dt.timestamp())}"
+        except ValueError:
+            response.headers["Deprecation"] = "true"
+
+    if sunset:
+        # Sunset header uses HTTP date format
+        try:
+            dt = datetime.fromisoformat(sunset)
+            response.headers["Sunset"] = dt.strftime("%a, %d %b %Y %H:%M:%S GMT")
+        except ValueError:
+            pass
+
+    if alternative:
+        # Link header for the replacement
+        response.headers["Link"] = f'<{alternative}>; rel="successor-version"'
+
+
+def deprecated_endpoint(
+    deprecated_at: str | None = None,
+    sunset: str | None = None,
+    alternative: str | None = None,
+    message: str | None = None,
+) -> Callable:
+    """Decorator to mark an endpoint as deprecated.
+
+    Adds deprecation headers to the response and includes
+    deprecation warning in the response body if applicable.
+
+    Args:
+        deprecated_at: ISO 8601 date when deprecation started
+        sunset: ISO 8601 date when endpoint will be removed
+        alternative: URL or path to the replacement endpoint
+        message: Custom deprecation message for response body
+
+    Example:
+        >>> @deprecated_endpoint(
+        ...     sunset="2027-01-01",
+        ...     alternative="/v2/generate",
+        ...     message="Use /v2/generate instead"
+        ... )
+        ... async def old_generate():
+        ...     return {"text": "..."}
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            result = await func(*args, **kwargs)
+
+            # Find response object if available
+            response = kwargs.get("response")
+            if response is None and hasattr(result, "headers"):
+                response = result
+
+            if response is not None:
+                add_deprecation_headers(
+                    response,
+                    deprecated_at=deprecated_at,
+                    sunset=sunset,
+                    alternative=alternative,
+                )
+
+            # If result is a dict, we can add deprecation warning
+            if isinstance(result, dict) and message:
+                result["_deprecation_warning"] = message
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def format_sunset_date(date: datetime) -> str:
+    """Format a datetime as an RFC 7231 HTTP date.
+
+    Args:
+        date: datetime object
+
+    Returns:
+        HTTP date string (e.g., "Mon, 01 Jan 2027 00:00:00 GMT")
+    """
+    return date.strftime("%a, %d %b %Y %H:%M:%S GMT")

hfl/api/errors.py

@@ -0,0 +1,278 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""
+Consistent error responses for HFL API.
+
+Provides structured error response format and factory functions
+for common error types.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from hfl.logging_config import get_request_id
+
+
+class ErrorDetail(BaseModel):
+    """Structured error response model.
+
+    Used for consistent error response format across all endpoints.
+    """
+
+    error: str
+    code: str
+    details: dict[str, Any] | None = None
+    request_id: str | None = None
+
+    model_config = {"extra": "forbid"}
+
+
+class HFLHTTPException(HTTPException):
+    """HTTP exception with structured error details.
+
+    Extends FastAPI's HTTPException with structured error format.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        error: str,
+        code: str,
+        details: dict[str, Any] | None = None,
+    ):
+        """Create structured HTTP exception.
+
+        Args:
+            status_code: HTTP status code
+            error: Human-readable error message
+            code: Machine-readable error code
+            details: Additional error details
+        """
+        detail = ErrorDetail(
+            error=error,
+            code=code,
+            details=details,
+            request_id=get_request_id(),
+        )
+        super().__init__(status_code=status_code, detail=detail.model_dump())
+        self.error_code = code
+
+
+# Common error factory functions
+
+
+def model_not_found(model_name: str) -> HFLHTTPException:
+    """Create 404 error for model not found.
+
+    Args:
+        model_name: Name of the model
+
+    Returns:
+        HFLHTTPException with 404 status
+    """
+    return HFLHTTPException(
+        status_code=404,
+        error=f"Model not found: {model_name}",
+        code="MODEL_NOT_FOUND",
+        details={"model": model_name},
+    )
+
+
+def model_type_mismatch(expected: str, got: str, model: str | None = None) -> HFLHTTPException:
+    """Create 400 error for model type mismatch.
+
+    Args:
+        expected: Expected model type
+        got: Actual model type
+        model: Model name (optional)
+
+    Returns:
+        HFLHTTPException with 400 status
+    """
+    details = {"expected": expected, "got": got}
+    if model:
+        details["model"] = model
+
+    return HFLHTTPException(
+        status_code=400,
+        error=f"Expected {expected} model, got {got}",
+        code="MODEL_TYPE_MISMATCH",
+        details=details,
+    )
+
+
+def validation_error(message: str, field: str | None = None) -> HFLHTTPException:
+    """Create 400 error for validation failure.
+
+    Args:
+        message: Validation error message
+        field: Field that failed validation (optional)
+
+    Returns:
+        HFLHTTPException with 400 status
+    """
+    return HFLHTTPException(
+        status_code=400,
+        error=message,
+        code="VALIDATION_ERROR",
+        details={"field": field} if field else None,
+    )
+
+
+def rate_limit_exceeded(retry_after: int, window_seconds: int | None = None) -> JSONResponse:
+    """Create 429 response for rate limit exceeded.
+
+    Args:
+        retry_after: Seconds until rate limit resets
+        window_seconds: Rate limit window (optional)
+
+    Returns:
+        JSONResponse with 429 status and Retry-After header
+    """
+    details = {"retry_after_seconds": retry_after}
+    if window_seconds:
+        details["window_seconds"] = window_seconds
+
+    return JSONResponse(
+        status_code=429,
+        content=ErrorDetail(
+            error="Rate limit exceeded",
+            code="RATE_LIMIT_EXCEEDED",
+            details=details,
+            request_id=get_request_id(),
+        ).model_dump(),
+        headers={"Retry-After": str(retry_after)},
+    )
+
+
+def unauthorized(message: str = "Authentication required") -> JSONResponse:
+    """Create 401 response for unauthorized access.
+
+    Args:
+        message: Error message
+
+    Returns:
+        JSONResponse with 401 status
+    """
+    return JSONResponse(
+        status_code=401,
+        content=ErrorDetail(
+            error=message,
+            code="UNAUTHORIZED",
+            request_id=get_request_id(),
+        ).model_dump(),
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+def forbidden(message: str = "Access denied") -> JSONResponse:
+    """Create 403 response for forbidden access.
+
+    Args:
+        message: Error message
+
+    Returns:
+        JSONResponse with 403 status
+    """
+    return JSONResponse(
+        status_code=403,
+        content=ErrorDetail(
+            error=message,
+            code="FORBIDDEN",
+            request_id=get_request_id(),
+        ).model_dump(),
+    )
+
+
+def internal_error(
+    message: str = "Internal server error",
+    error_type: str | None = None,
+) -> HFLHTTPException:
+    """Create 500 error for internal server errors.
+
+    Args:
+        message: Error message
+        error_type: Type of error (optional)
+
+    Returns:
+        HFLHTTPException with 500 status
+    """
+    return HFLHTTPException(
+        status_code=500,
+        error=message,
+        code="INTERNAL_ERROR",
+        details={"type": error_type} if error_type else None,
+    )
+
+
+def service_unavailable(
+    message: str = "Service temporarily unavailable",
+    retry_after: int | None = None,
+) -> JSONResponse:
+    """Create 503 response for service unavailable.
+
+    Args:
+        message: Error message
+        retry_after: Seconds until service may be available
+
+    Returns:
+        JSONResponse with 503 status
+    """
+    headers = {}
+    if retry_after:
+        headers["Retry-After"] = str(retry_after)
+
+    return JSONResponse(
+        status_code=503,
+        content=ErrorDetail(
+            error=message,
+            code="SERVICE_UNAVAILABLE",
+            details={"retry_after": retry_after} if retry_after else None,
+            request_id=get_request_id(),
+        ).model_dump(),
+        headers=headers if headers else None,
+    )
+
+
+def model_loading(model_name: str) -> JSONResponse:
+    """Create 503 response for model currently loading.
+
+    Args:
+        model_name: Name of the loading model
+
+    Returns:
+        JSONResponse with 503 status
+    """
+    return JSONResponse(
+        status_code=503,
+        content=ErrorDetail(
+            error=f"Model '{model_name}' is currently loading",
+            code="MODEL_LOADING",
+            details={"model": model_name},
+            request_id=get_request_id(),
+        ).model_dump(),
+        headers={"Retry-After": "5"},
+    )
+
+
+def timeout_error(operation: str, timeout_seconds: float) -> HFLHTTPException:
+    """Create 504 error for operation timeout.
+
+    Args:
+        operation: Name of the timed out operation
+        timeout_seconds: Timeout duration
+
+    Returns:
+        HFLHTTPException with 504 status
+    """
+    return HFLHTTPException(
+        status_code=504,
+        error=f"Operation '{operation}' timed out",
+        code="TIMEOUT",
+        details={"operation": operation, "timeout_seconds": timeout_seconds},
+    )

hfl/api/exception_handlers.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: HRUL-1.0
+# Copyright (c) 2026 Gabriel Galán Pelayo
+"""Global exception handlers for the FastAPI app.
+
+Maps domain exceptions (HFLError hierarchy) to HTTP responses,
+so routes can raise domain exceptions instead of HTTPException.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from hfl.exceptions import HFLError
+
+logger = logging.getLogger(__name__)
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register global exception handlers on the FastAPI app."""
+
+    @app.exception_handler(HFLError)
+    async def hfl_error_handler(request: Request, exc: HFLError) -> JSONResponse:
+        """Convert HFLError subclasses to structured HTTP responses."""
+        status_code = getattr(exc, "status_code", 500)
+
+        body: dict = {
+            "error": exc.message,
+            "code": type(exc).__name__,
+        }
+        if exc.details:
+            body["details"] = exc.details
+
+        if status_code >= 500:
+            logger.error("Unhandled HFLError: %s", exc)
+
+        return JSONResponse(status_code=status_code, content=body)