morphml 1.0.0__py3-none-any.whl

morphml/api/client.py

@@ -0,0 +1,338 @@
+"""API client library for MorphML.
+
+Provides a Python client for interacting with the MorphML REST API.
+
+Example:
+    >>> from morphml.api.client import MorphMLClient
+    >>> client = MorphMLClient("http://localhost:8000")
+    >>> experiments = client.list_experiments()
+    >>> exp = client.create_experiment("my-experiment", search_space={...})
+"""
+
+from typing import Any, Dict, List, Optional
+
+import requests
+from requests.exceptions import RequestException
+
+from morphml.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class MorphMLClient:
+    """
+    Python client for MorphML REST API.
+
+    Provides convenient methods for all API endpoints.
+
+    Attributes:
+        base_url: Base URL of the API
+        token: Optional authentication token
+        session: Requests session
+
+    Example:
+        >>> client = MorphMLClient("http://localhost:8000")
+        >>> client.login("user@example.com", "password")
+        >>> experiments = client.list_experiments()
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8000", token: Optional[str] = None):
+        """
+        Initialize API client.
+
+        Args:
+            base_url: Base URL of the API
+            token: Optional authentication token
+        """
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.session = requests.Session()
+
+        if token:
+            self.session.headers.update({"Authorization": f"Bearer {token}"})
+
+        logger.info(f"Initialized MorphML client for {base_url}")
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        """
+        Make HTTP request to API.
+
+        Args:
+            method: HTTP method
+            endpoint: API endpoint
+            **kwargs: Additional request arguments
+
+        Returns:
+            Response JSON
+
+        Raises:
+            RequestException: If request fails
+        """
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            response = self.session.request(method, url, **kwargs)
+            response.raise_for_status()
+            return response.json()
+
+        except RequestException as e:
+            logger.error(f"API request failed: {e}")
+            raise
+
+    def login(self, username: str, password: str) -> str:
+        """
+        Login and get authentication token.
+
+        Args:
+            username: Username
+            password: Password
+
+        Returns:
+            Access token
+
+        Example:
+            >>> token = client.login("user@example.com", "password")
+        """
+        response = self._request(
+            "POST", "/api/v1/auth/login", json={"username": username, "password": password}
+        )
+
+        self.token = response["access_token"]
+        self.session.headers.update({"Authorization": f"Bearer {self.token}"})
+
+        logger.info(f"Logged in as {username}")
+
+        return self.token
+
+    # Experiment endpoints
+
+    def create_experiment(
+        self,
+        name: str,
+        search_space: Dict[str, Any],
+        optimizer: str = "genetic",
+        budget: int = 500,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a new experiment.
+
+        Args:
+            name: Experiment name
+            search_space: Search space configuration
+            optimizer: Optimizer type
+            budget: Evaluation budget
+            config: Optional additional configuration
+
+        Returns:
+            Created experiment
+
+        Example:
+            >>> exp = client.create_experiment(
+            ...     "cifar10-search",
+            ...     search_space={"layers": [...]},
+            ...     optimizer="genetic"
+            ... )
+        """
+        return self._request(
+            "POST",
+            "/api/v1/experiments",
+            json={
+                "name": name,
+                "search_space": search_space,
+                "optimizer": optimizer,
+                "budget": budget,
+                "config": config or {},
+            },
+        )
+
+    def list_experiments(
+        self, status: Optional[str] = None, limit: int = 100, offset: int = 0
+    ) -> List[Dict[str, Any]]:
+        """
+        List experiments.
+
+        Args:
+            status: Optional status filter
+            limit: Maximum results
+            offset: Offset for pagination
+
+        Returns:
+            List of experiments
+
+        Example:
+            >>> experiments = client.list_experiments(status="running")
+        """
+        params = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+
+        return self._request("GET", "/api/v1/experiments", params=params)
+
+    def get_experiment(self, experiment_id: str) -> Dict[str, Any]:
+        """
+        Get experiment details.
+
+        Args:
+            experiment_id: Experiment ID
+
+        Returns:
+            Experiment details
+
+        Example:
+            >>> exp = client.get_experiment("exp_abc123")
+        """
+        return self._request("GET", f"/api/v1/experiments/{experiment_id}")
+
+    def start_experiment(self, experiment_id: str) -> Dict[str, Any]:
+        """
+        Start an experiment.
+
+        Args:
+            experiment_id: Experiment ID
+
+        Returns:
+            Updated experiment
+
+        Example:
+            >>> client.start_experiment("exp_abc123")
+        """
+        return self._request("POST", f"/api/v1/experiments/{experiment_id}/start")
+
+    def stop_experiment(self, experiment_id: str) -> Dict[str, Any]:
+        """
+        Stop a running experiment.
+
+        Args:
+            experiment_id: Experiment ID
+
+        Returns:
+            Updated experiment
+
+        Example:
+            >>> client.stop_experiment("exp_abc123")
+        """
+        return self._request("POST", f"/api/v1/experiments/{experiment_id}/stop")
+
+    def delete_experiment(self, experiment_id: str) -> None:
+        """
+        Delete an experiment.
+
+        Args:
+            experiment_id: Experiment ID
+
+        Example:
+            >>> client.delete_experiment("exp_abc123")
+        """
+        self._request("DELETE", f"/api/v1/experiments/{experiment_id}")
+        logger.info(f"Deleted experiment: {experiment_id}")
+
+    # Architecture endpoints
+
+    def list_architectures(
+        self,
+        experiment_id: Optional[str] = None,
+        min_fitness: Optional[float] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """
+        List architectures.
+
+        Args:
+            experiment_id: Optional experiment filter
+            min_fitness: Optional minimum fitness filter
+            limit: Maximum results
+            offset: Offset for pagination
+
+        Returns:
+            List of architectures
+
+        Example:
+            >>> archs = client.list_architectures(
+            ...     experiment_id="exp_abc123",
+            ...     min_fitness=0.9
+            ... )
+        """
+        params = {"limit": limit, "offset": offset}
+        if experiment_id:
+            params["experiment_id"] = experiment_id
+        if min_fitness is not None:
+            params["min_fitness"] = min_fitness
+
+        return self._request("GET", "/api/v1/architectures", params=params)
+
+    def get_architecture(self, architecture_id: str) -> Dict[str, Any]:
+        """
+        Get architecture details.
+
+        Args:
+            architecture_id: Architecture ID
+
+        Returns:
+            Architecture details
+
+        Example:
+            >>> arch = client.get_architecture("arch_xyz789")
+        """
+        return self._request("GET", f"/api/v1/architectures/{architecture_id}")
+
+    # Utility methods
+
+    def health_check(self) -> Dict[str, Any]:
+        """
+        Check API health.
+
+        Returns:
+            Health status
+
+        Example:
+            >>> health = client.health_check()
+            >>> print(health["status"])
+        """
+        return self._request("GET", "/health")
+
+    def get_optimizers(self) -> List[Dict[str, Any]]:
+        """
+        Get list of available optimizers.
+
+        Returns:
+            List of optimizer information
+
+        Example:
+            >>> optimizers = client.get_optimizers()
+            >>> for opt in optimizers:
+            ...     print(opt["name"])
+        """
+        return self._request("GET", "/api/v1/optimizers")
+
+
+def create_client(
+    base_url: str = "http://localhost:8000",
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+) -> MorphMLClient:
+    """
+    Create and optionally authenticate API client.
+
+    Args:
+        base_url: Base URL of the API
+        username: Optional username for authentication
+        password: Optional password for authentication
+
+    Returns:
+        MorphMLClient instance
+
+    Example:
+        >>> client = create_client(
+        ...     "http://localhost:8000",
+        ...     "user@example.com",
+        ...     "password"
+        ... )
+    """
+    client = MorphMLClient(base_url)
+
+    if username and password:
+        client.login(username, password)
+
+    return client

morphml/api/models.py

@@ -0,0 +1,132 @@
+"""Pydantic models for API requests and responses."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ExperimentCreate(BaseModel):
+    """Request model for creating an experiment."""
+
+    name: str = Field(..., description="Experiment name")
+    search_space_config: Dict[str, Any] = Field(..., description="Search space configuration")
+    optimizer_type: str = Field("genetic", description="Optimizer type")
+    optimizer_config: Dict[str, Any] = Field(
+        default_factory=dict, description="Optimizer configuration"
+    )
+    budget: int = Field(100, description="Evaluation budget")
+    constraints: Optional[List[Dict[str, Any]]] = Field(None, description="Constraints")
+
+    class Config:
+        schema_extra = {
+            "example": {
+                "name": "cifar10-search",
+                "search_space_config": {
+                    "layers": [
+                        {"type": "input", "shape": [3, 32, 32]},
+                        {"type": "conv2d", "filters": [32, 64], "kernel_size": 3},
+                        {"type": "flatten"},
+                        {"type": "dense", "units": [128, 256]},
+                    ]
+                },
+                "optimizer_type": "genetic",
+                "optimizer_config": {"population_size": 20, "num_generations": 50},
+                "budget": 1000,
+            }
+        }
+
+
+class ExperimentResponse(BaseModel):
+    """Response model for experiment."""
+
+    id: str
+    name: str
+    status: str  # pending, running, completed, failed
+    created_at: datetime
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    best_fitness: Optional[float] = None
+    generations_completed: int = 0
+    total_generations: int
+
+    class Config:
+        schema_extra = {
+            "example": {
+                "id": "exp_123abc",
+                "name": "cifar10-search",
+                "status": "running",
+                "created_at": "2024-11-11T05:00:00Z",
+                "started_at": "2024-11-11T05:01:00Z",
+                "best_fitness": 0.9523,
+                "generations_completed": 25,
+                "total_generations": 50,
+            }
+        }
+
+
+class ArchitectureResponse(BaseModel):
+    """Response model for architecture."""
+
+    id: str
+    experiment_id: str
+    fitness: float
+    parameters: int
+    depth: int
+    nodes: int
+    edges: int
+    created_at: datetime
+    graph_data: Optional[Dict[str, Any]] = None
+
+    class Config:
+        schema_extra = {
+            "example": {
+                "id": "arch_456def",
+                "experiment_id": "exp_123abc",
+                "fitness": 0.9523,
+                "parameters": 1234567,
+                "depth": 8,
+                "nodes": 12,
+                "edges": 11,
+                "created_at": "2024-11-11T05:15:00Z",
+            }
+        }
+
+
+class SearchSpaceCreate(BaseModel):
+    """Request model for creating a search space."""
+
+    name: str
+    layers: List[Dict[str, Any]]
+    constraints: Optional[List[Dict[str, Any]]] = None
+
+
+class OptimizerInfo(BaseModel):
+    """Information about an optimizer."""
+
+    name: str
+    type: str
+    description: str
+    parameters: Dict[str, Any]
+
+    class Config:
+        schema_extra = {
+            "example": {
+                "name": "GeneticAlgorithm",
+                "type": "evolutionary",
+                "description": "Genetic algorithm for neural architecture search",
+                "parameters": {
+                    "population_size": {"type": "int", "default": 20},
+                    "num_generations": {"type": "int", "default": 50},
+                    "mutation_rate": {"type": "float", "default": 0.2},
+                },
+            }
+        }
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str
+    version: str
+    timestamp: datetime

morphml/api/rate_limit.py

@@ -0,0 +1,192 @@
+"""Rate limiting middleware for MorphML API.
+
+Prevents API abuse by limiting request rates per client.
+
+Example:
+    >>> from morphml.api.rate_limit import RateLimitMiddleware
+    >>> app.add_middleware(RateLimitMiddleware, requests_per_minute=60)
+"""
+
+import time
+from datetime import datetime, timedelta
+from typing import Dict, Tuple
+
+try:
+    from fastapi import HTTPException, Request, status
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+    Request = None
+    HTTPException = None
+    BaseHTTPMiddleware = None
+
+from morphml.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class RateLimiter:
+    """
+    Simple in-memory rate limiter.
+
+    Tracks request counts per client IP address.
+
+    Attributes:
+        requests_per_minute: Maximum requests per minute
+        requests: Dictionary tracking requests per IP
+    """
+
+    def __init__(self, requests_per_minute: int = 60):
+        """
+        Initialize rate limiter.
+
+        Args:
+            requests_per_minute: Maximum requests per minute per IP
+        """
+        self.requests_per_minute = requests_per_minute
+        self.requests: Dict[str, list] = {}
+        self.cleanup_interval = 60  # Cleanup old entries every 60 seconds
+        self.last_cleanup = time.time()
+
+    def is_allowed(self, client_ip: str) -> Tuple[bool, int]:
+        """
+        Check if request is allowed for client.
+
+        Args:
+            client_ip: Client IP address
+
+        Returns:
+            Tuple of (is_allowed, remaining_requests)
+        """
+        now = datetime.now()
+        minute_ago = now - timedelta(minutes=1)
+
+        # Cleanup old entries periodically
+        if time.time() - self.last_cleanup > self.cleanup_interval:
+            self._cleanup()
+
+        # Get or create request list for this IP
+        if client_ip not in self.requests:
+            self.requests[client_ip] = []
+
+        # Remove requests older than 1 minute
+        self.requests[client_ip] = [
+            req_time for req_time in self.requests[client_ip] if req_time > minute_ago
+        ]
+
+        # Check if limit exceeded
+        request_count = len(self.requests[client_ip])
+
+        if request_count >= self.requests_per_minute:
+            return False, 0
+
+        # Add current request
+        self.requests[client_ip].append(now)
+
+        remaining = self.requests_per_minute - request_count - 1
+
+        return True, remaining
+
+    def _cleanup(self):
+        """Remove old entries to prevent memory leak."""
+        now = datetime.now()
+        minute_ago = now - timedelta(minutes=1)
+
+        # Remove IPs with no recent requests
+        ips_to_remove = []
+        for ip, req_times in self.requests.items():
+            recent_requests = [t for t in req_times if t > minute_ago]
+            if not recent_requests:
+                ips_to_remove.append(ip)
+            else:
+                self.requests[ip] = recent_requests
+
+        for ip in ips_to_remove:
+            del self.requests[ip]
+
+        self.last_cleanup = time.time()
+
+        if ips_to_remove:
+            logger.debug(f"Cleaned up {len(ips_to_remove)} inactive IPs")
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware if FASTAPI_AVAILABLE else object):
+    """
+    FastAPI middleware for rate limiting.
+
+    Automatically limits requests per client IP.
+
+    Example:
+        >>> app.add_middleware(
+        ...     RateLimitMiddleware,
+        ...     requests_per_minute=60
+        ... )
+    """
+
+    def __init__(self, app, requests_per_minute: int = 60):
+        """
+        Initialize middleware.
+
+        Args:
+            app: FastAPI application
+            requests_per_minute: Maximum requests per minute
+        """
+        if not FASTAPI_AVAILABLE:
+            raise ImportError("FastAPI required for rate limiting")
+
+        super().__init__(app)
+        self.limiter = RateLimiter(requests_per_minute)
+        logger.info(f"Rate limiting enabled: {requests_per_minute} requests/minute")
+
+    async def dispatch(self, request: Request, call_next):
+        """
+        Process request with rate limiting.
+
+        Args:
+            request: Incoming request
+            call_next: Next middleware/handler
+
+        Returns:
+            Response
+        """
+        # Get client IP
+        client_ip = request.client.host
+
+        # Check rate limit
+        allowed, remaining = self.limiter.is_allowed(client_ip)
+
+        if not allowed:
+            logger.warning(f"Rate limit exceeded for {client_ip}")
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+                headers={"Retry-After": "60"},
+            )
+
+        # Process request
+        response = await call_next(request)
+
+        # Add rate limit headers
+        response.headers["X-RateLimit-Limit"] = str(self.limiter.requests_per_minute)
+        response.headers["X-RateLimit-Remaining"] = str(remaining)
+
+        return response
+
+
+def create_rate_limiter(requests_per_minute: int = 60) -> RateLimiter:
+    """
+    Create a rate limiter instance.
+
+    Args:
+        requests_per_minute: Maximum requests per minute
+
+    Returns:
+        RateLimiter instance
+
+    Example:
+        >>> limiter = create_rate_limiter(100)
+        >>> allowed, remaining = limiter.is_allowed("192.168.1.1")
+    """
+    return RateLimiter(requests_per_minute)

morphml/benchmarking/__init__.py

@@ -0,0 +1,36 @@
+"""Benchmarking and comparison tools for optimizer evaluation.
+
+This module provides tools to systematically compare and evaluate
+different optimization algorithms.
+
+Features:
+- Optimizer comparison with statistical analysis
+- Convergence visualization
+- Sample efficiency analysis
+- Result reporting
+
+Example:
+    >>> from morphml.benchmarking import OptimizerComparison, compare_optimizers
+    >>> from morphml.optimizers import GeneticAlgorithm, optimize_with_pso
+    >>>
+    >>> # Quick comparison
+    >>> results = compare_optimizers(
+    ...     optimizers={
+    ...         'GA': GeneticAlgorithm(space, config),
+    ...         'PSO': ParticleSwarmOptimizer(space, config)
+    ...     },
+    ...     search_space=space,
+    ...     evaluator=my_evaluator,
+    ...     budget=100
+    ... )
+"""
+
+from morphml.benchmarking.comparison import (
+    OptimizerComparison,
+    compare_optimizers,
+)
+
+__all__ = [
+    "OptimizerComparison",
+    "compare_optimizers",
+]