juniper-data 0.4.2__py3-none-any.whl

juniper_data/__init__.py

@@ -0,0 +1,88 @@
+"""
+Juniper Data - Dataset generation and management service for the Juniper ecosystem.
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+try:
+    import arc_agi
+
+    ARC_AGI_AVAILABLE = True
+except ImportError:
+    ARC_AGI_AVAILABLE = False
+    arc_agi = None  # type: ignore[assignment]
+
+__version__ = "0.4.2"
+__author__ = "Paul Calnon"
+
+
+def get_arc_agi_env() -> bool:
+    """
+    Ensure ARC_AGI_ENV is available by loading environment variables if needed.
+
+    This function attempts to load environment variables from a `.env` file and then
+    returns whether the `ARC_AGI_ENV` environment variable is set.
+
+    Returns:
+        bool: True if ARC_AGI_ENV is set after loading, otherwise False.
+    """
+    # Attempt to load variables from a .env file, but base the result solely on
+    # whether ARC_AGI_ENV is present afterwards to provide consistent semantics.
+    load_dotenv()
+    return bool(os.getenv("ARC_AGI_ENV"))
+
+
+def reload_arc_agi_env() -> bool:
+    """
+    Reloads all of the Environment Variables from local OS env whether already loaded or not.
+
+    Returns:
+        bool: True if environment variables were loaded from a .env file, False otherwise.
+    """
+    return bool(load_dotenv())
+
+
+def get_arc_api_key() -> str | None:
+    """
+    Return the current value of the ARC_API_KEY environment variable as a string.
+    """
+    return os.getenv("ARC_API_KEY") or None
+
+
+def get_arc_agi_api_url() -> str | None:
+    """
+    Return the current value of the ARC_AGI_API as a URL/endpoint string.
+
+    Reading the environment at call time avoids import-time side effects
+    and makes it easier to adjust configuration in tests.
+    """
+    return os.getenv("ARC_AGI_API") or None
+
+
+def get_arc_agi_arcade() -> "arc_agi.Arcade | None":
+    """
+    Create and return an :class:`arc_agi.Arcade` instance configured from environment variables.
+
+    The API key is read from the environment via :func:`get_arc_api_key`, avoiding import-time
+    side effects and making it easier to adjust configuration in tests.
+
+    Raises:
+        ImportError: If the ``arc-agi`` package is not installed.
+    """
+    if not ARC_AGI_AVAILABLE:
+        raise ImportError("arc-agi package not installed. Install with: pip install 'juniper-data[arc-agi]'")
+    # Automatically uses ARC_API_KEY from environment:  arc = arc_agi.Arcade(), Or pass the API key explicitly
+    return arc_agi.Arcade(arc_api_key=get_arc_api_key()) or None
+
+
+# Deprecated
+def get_arc_agi_api() -> str | None:
+    """
+    Deprecated alias for :func:`get_arc_agi_api_url`.
+
+    This function returns the same value as :func:`get_arc_agi_api_url` and will be
+    removed in a future release. Use :func:`get_arc_agi_api_url` instead.
+    """
+    return get_arc_agi_api_url()

juniper_data/__main__.py

@@ -0,0 +1,78 @@
+"""Entry point for running the JuniperData API with uvicorn."""
+
+import argparse
+import sys
+
+
+def main() -> int:
+    """Run the JuniperData API server."""
+    try:
+        import uvicorn
+    except ImportError:
+        print("Error: uvicorn not installed. Install with: pip install 'juniper-data[api]'")
+        return 1
+
+    from juniper_data.api.settings import Settings
+
+    parser = argparse.ArgumentParser(
+        description="Run the JuniperData API server",
+        prog="python -m juniper_data",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=None,
+        help="Host to bind to (default: from settings, which default to 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Port to bind to (default: from settings or 8100)",
+    )
+    parser.add_argument(
+        "--storage-path",
+        type=str,
+        default=None,
+        help="Path to dataset storage directory",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        choices=["TRACE", "VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "FATAL"],
+        default=None,
+        help="Logging level",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development",
+    )
+
+    args = parser.parse_args()
+
+    settings = Settings()
+
+    host = args.host if args.host is not None else settings.host
+    port = args.port if args.port is not None else settings.port
+    log_level_source = args.log_level if args.log_level is not None else settings.log_level
+    log_level = log_level_source.lower()
+
+    if args.storage_path is not None:
+        import os
+
+        os.environ["JUNIPER_DATA_STORAGE_PATH"] = args.storage_path
+
+    uvicorn.run(
+        "juniper_data.api.app:app",
+        host=host,
+        port=port,
+        log_level=log_level,
+        reload=args.reload,
+    )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

juniper_data/api/__init__.py

@@ -0,0 +1,10 @@
+"""API module for Juniper Data service."""
+
+from .app import create_app
+from .settings import Settings, get_settings
+
+__all__ = [
+    "create_app",
+    "Settings",
+    "get_settings",
+]

juniper_data/api/app.py

@@ -0,0 +1,111 @@
+"""FastAPI application factory and configuration."""
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from juniper_data import __version__
+from juniper_data.storage import LocalFSDatasetStore
+
+from .middleware import SecurityMiddleware
+from .routes import datasets, generators, health
+from .security import APIKeyAuth, RateLimiter
+from .settings import Settings, get_settings
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan handler for startup/shutdown."""
+    settings: Settings = app.state.settings
+    storage_path = Path(settings.storage_path)
+    store = LocalFSDatasetStore(storage_path)
+    datasets.set_store(store)
+
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper(), logging.INFO),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+    logger = logging.getLogger("juniper_data")
+    logger.info(f"JuniperData API v{__version__} starting")
+    logger.info(f"Storage path: {storage_path.absolute()}")
+
+    yield
+
+    logger.info("JuniperData API shutting down")
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        settings: Optional settings override. If not provided,
+                  settings are loaded from environment variables.
+
+    Returns:
+        Configured FastAPI application instance.
+    """
+    if settings is None:
+        settings = get_settings()
+
+    app = FastAPI(
+        title="Juniper Data API",
+        description="Dataset generation and management service for the Juniper ecosystem",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    app.state.settings = settings
+
+    # Only allow credentialed CORS requests when origins are explicitly specified.
+    # Browsers do not permit Access-Control-Allow-Credentials: true with a wildcard
+    # origin (Access-Control-Allow-Origin: "*"), so the default ["*"] intentionally
+    # disables credentials unless concrete origins are configured.
+    allow_credentials = bool(settings.cors_origins) and "*" not in settings.cors_origins
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=allow_credentials,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    api_key_auth = APIKeyAuth(settings.api_keys)
+    rate_limiter = RateLimiter(
+        requests_per_minute=settings.rate_limit_requests_per_minute,
+        enabled=settings.rate_limit_enabled,
+    )
+    app.add_middleware(
+        SecurityMiddleware,
+        api_key_auth=api_key_auth,
+        rate_limiter=rate_limiter,
+    )
+
+    app.include_router(health.router, prefix="/v1")
+    app.include_router(generators.router, prefix="/v1")
+    app.include_router(datasets.router, prefix="/v1")
+
+    @app.exception_handler(ValueError)
+    async def value_error_handler(request: Request, exc: ValueError) -> JSONResponse:
+        return JSONResponse(
+            status_code=400,
+            content={"detail": str(exc)},
+        )
+
+    @app.exception_handler(Exception)
+    async def general_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        logging.getLogger("juniper_data").exception("Unhandled exception")
+        return JSONResponse(
+            status_code=500,
+            content={"detail": "Internal server error"},
+        )
+
+    return app
+
+
+app = create_app()

juniper_data/api/middleware.py

@@ -0,0 +1,95 @@
+"""FastAPI middleware for security and request processing."""
+
+from fastapi import HTTPException, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+from .security import APIKeyAuth, RateLimiter
+
+EXEMPT_PATHS = {
+    "/v1/health",
+    "/v1/health/live",
+    "/v1/health/ready",
+    "/docs",
+    "/openapi.json",
+    "/redoc",
+}
+
+
+class SecurityMiddleware(BaseHTTPMiddleware):
+    """Middleware for API key authentication and rate limiting.
+
+    Applies authentication and rate limiting to all requests except
+    explicitly exempt paths (health checks, docs).
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        api_key_auth: APIKeyAuth,
+        rate_limiter: RateLimiter,
+    ) -> None:
+        """Initialize the security middleware.
+
+        Args:
+            app: The ASGI application.
+            api_key_auth: API key authentication handler.
+            rate_limiter: Rate limiter instance.
+        """
+        super().__init__(app)
+        self._api_key_auth = api_key_auth
+        self._rate_limiter = rate_limiter
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        """Process the request through security checks.
+
+        Args:
+            request: The incoming request.
+            call_next: The next middleware/handler in the chain.
+
+        Returns:
+            The response from the application.
+        """
+        path = request.url.path
+
+        if self._is_exempt(path):
+            return await call_next(request)
+
+        api_key = None
+        try:
+            if self._api_key_auth.enabled:
+                api_key = await self._api_key_auth(request)
+
+            if self._rate_limiter.enabled:
+                await self._rate_limiter(request, api_key)
+        except HTTPException as exc:
+            return JSONResponse(
+                status_code=exc.status_code,
+                content={"detail": exc.detail},
+                headers=exc.headers,
+            )
+
+        response = await call_next(request)
+
+        if self._rate_limiter.enabled and hasattr(request.state, "rate_limit_remaining"):
+            response.headers["X-RateLimit-Limit"] = str(self._rate_limiter.limit)
+            response.headers["X-RateLimit-Remaining"] = str(request.state.rate_limit_remaining)
+            response.headers["X-RateLimit-Reset"] = str(request.state.rate_limit_reset)
+
+        return response
+
+    def _is_exempt(self, path: str) -> bool:
+        """Check if a path is exempt from security checks.
+
+        Args:
+            path: The request path.
+
+        Returns:
+            True if the path is exempt, False otherwise.
+        """
+        return path in EXEMPT_PATHS

juniper_data/api/routes/__init__.py

@@ -0,0 +1,9 @@
+"""API routes module."""
+
+from . import datasets, generators, health
+
+__all__ = [
+    "datasets",
+    "generators",
+    "health",
+]