allocator 1.0.0__py3-none-any.whl

allocator/api/route.py

@@ -0,0 +1,256 @@
+"""
+Modern routing API for allocator package.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..io.data_handler import DataHandler
+from .types import RouteResult
+
+
+def _solve_tsp_nearest_neighbor(distance_matrix: np.ndarray) -> tuple[float, list[int]]:
+    """
+    Solve TSP using nearest neighbor heuristic.
+
+    Args:
+        distance_matrix: Symmetric distance matrix
+
+    Returns:
+        Tuple of (total_distance, route)
+    """
+    n = len(distance_matrix)
+    if n == 0:
+        return 0.0, []
+    if n == 1:
+        return 0.0, [0]
+
+    # Start from node 0
+    unvisited = set(range(1, n))
+    route = [0]
+    current = 0
+    total_distance = 0.0
+
+    while unvisited:
+        # Find nearest unvisited node
+        nearest = min(unvisited, key=lambda x: distance_matrix[current, x])
+        total_distance += distance_matrix[current, nearest]
+        route.append(nearest)
+        unvisited.remove(nearest)
+        current = nearest
+
+    # Return to start
+    total_distance += distance_matrix[current, 0]
+    route.append(0)
+
+    return total_distance, route
+
+
+def shortest_path(
+    data: str | pd.DataFrame | np.ndarray | list,
+    method: str = "christofides",
+    distance: str = "euclidean",
+    **kwargs,
+) -> RouteResult:
+    """
+    Find shortest path through geographic points (TSP).
+
+    Args:
+        data: Input data (file path, DataFrame, numpy array, or list)
+        method: TSP solving method ('christofides', 'ortools', 'osrm', 'google')
+        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        **kwargs: Additional method-specific arguments
+
+    Returns:
+        RouteResult with optimal route and total distance
+
+    Example:
+        >>> result = shortest_path('points.csv', method='ortools')
+        >>> print(result.route)  # Optimal visiting order
+        >>> print(result.total_distance)  # Total route distance
+    """
+    # Load and standardize data
+    df = DataHandler.load_data(data)
+
+    if method == "christofides":
+        return tsp_christofides(df, distance=distance, **kwargs)
+    elif method == "ortools":
+        return tsp_ortools(df, distance=distance, **kwargs)
+    elif method == "osrm":
+        return tsp_osrm(df, **kwargs)
+    elif method == "google":
+        return tsp_google(df, **kwargs)
+    else:
+        raise ValueError(f"Unknown routing method: {method}")
+
+
+def tsp_christofides(
+    data: pd.DataFrame | np.ndarray, distance: str = "euclidean", **kwargs
+) -> RouteResult:
+    """
+    Solve TSP using Christofides algorithm (approximate).
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        distance: Distance metric
+        **kwargs: Additional arguments
+
+    Returns:
+        RouteResult with approximate optimal route
+    """
+    from ..core.routing import solve_tsp_christofides
+
+    # Load and standardize data
+    df = DataHandler.load_data(data)
+
+    # Extract coordinates
+    if "longitude" in df.columns and "latitude" in df.columns:
+        points = df[["longitude", "latitude"]].values
+    else:
+        raise ValueError("Data must contain 'longitude' and 'latitude' columns")
+
+    # Solve TSP
+    total_distance, route = solve_tsp_christofides(points, distance_method=distance, **kwargs)
+
+    # Create result DataFrame with route order
+    result_df = df.iloc[route].copy()
+    result_df["route_order"] = range(len(route))
+
+    return RouteResult(
+        route=route,
+        total_distance=total_distance,
+        data=result_df,
+        metadata={"method": "christofides", "distance": distance, "n_points": len(points)},
+    )
+
+
+def tsp_ortools(
+    data: pd.DataFrame | np.ndarray, distance: str = "euclidean", **kwargs
+) -> RouteResult:
+    """
+    Solve TSP using Google OR-Tools (exact for small problems).
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        distance: Distance metric
+        **kwargs: Additional arguments
+
+    Returns:
+        RouteResult with optimal route
+    """
+    from ..core.routing import solve_tsp_ortools
+
+    # Load and standardize data
+    df = DataHandler.load_data(data)
+
+    # Extract coordinates
+    if "longitude" in df.columns and "latitude" in df.columns:
+        points = df[["longitude", "latitude"]].values
+    else:
+        raise ValueError("Data must contain 'longitude' and 'latitude' columns")
+
+    # Solve TSP
+    total_distance, route = solve_tsp_ortools(points, distance_method=distance, **kwargs)
+
+    # Create result DataFrame with route order
+    result_df = df.iloc[route].copy()
+    result_df["route_order"] = range(len(route))
+
+    return RouteResult(
+        route=route,
+        total_distance=total_distance,
+        data=result_df,
+        metadata={"method": "ortools", "distance": distance, "n_points": len(points)},
+    )
+
+
+def tsp_osrm(
+    data: pd.DataFrame | np.ndarray, osrm_base_url: str | None = None, **kwargs
+) -> RouteResult:
+    """
+    Solve TSP using OSRM distance matrix and nearest neighbor heuristic.
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        osrm_base_url: Custom OSRM server URL
+        **kwargs: Additional arguments
+
+    Returns:
+        RouteResult with route using real road network
+    """
+    points = DataHandler.load_data(data)
+
+    if len(points) == 0:
+        raise ValueError("Cannot solve TSP with empty data")
+    if len(points) == 1:
+        route = [0]
+        total_distance = 0.0
+    else:
+        # Use OSRM distance matrix to solve TSP with nearest neighbor heuristic
+        from ..distances import osrm_distance_matrix
+
+        distances = osrm_distance_matrix(
+            points[["longitude", "latitude"]].values, osrm_base_url=osrm_base_url
+        )
+
+        total_distance, route = _solve_tsp_nearest_neighbor(distances)
+
+    # Create result DataFrame
+    result_df = points.copy()
+    result_df["route_order"] = [route.index(i) if i in route else -1 for i in range(len(points))]
+
+    return RouteResult(
+        route=route,
+        total_distance=total_distance,
+        data=result_df,
+        metadata={"method": "osrm", "osrm_base_url": osrm_base_url, "n_points": len(points)},
+    )
+
+
+def tsp_google(data: pd.DataFrame | np.ndarray, api_key: str, **kwargs) -> RouteResult:
+    """
+    Solve TSP using Google Maps distance matrix and nearest neighbor heuristic.
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        api_key: Google Maps API key
+        **kwargs: Additional arguments
+
+    Returns:
+        RouteResult with route using Google's road network
+    """
+    points = DataHandler.load_data(data)
+
+    if len(points) == 0:
+        raise ValueError("Cannot solve TSP with empty data")
+    if len(points) == 1:
+        route = [0]
+        total_distance = 0.0
+    else:
+        # Use Google Maps distance matrix to solve TSP with nearest neighbor heuristic
+        from ..distances import google_distance_matrix
+
+        distances = google_distance_matrix(
+            points[["longitude", "latitude"]].values,
+            api_key=api_key,
+            duration=False,  # Get distance, not duration
+        )
+
+        total_distance, route = _solve_tsp_nearest_neighbor(distances)
+
+    # Create result DataFrame
+    result_df = points.copy()
+    result_df["route_order"] = [route.index(i) if i in route else -1 for i in range(len(points))]
+
+    return RouteResult(
+        route=route,
+        total_distance=total_distance,
+        data=result_df,
+        metadata={
+            "method": "google",
+            "api_key": "***" if api_key else None,  # Don't log actual API key
+            "n_points": len(points),
+        },
+    )

allocator/api/types.py

@@ -0,0 +1,52 @@
+"""
+Type definitions and dataclasses for allocator API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class ClusterResult:
+    """Result of clustering operation."""
+
+    labels: np.ndarray
+    centroids: np.ndarray
+    n_iter: int
+    inertia: float | None
+    data: pd.DataFrame
+    converged: bool
+    metadata: dict[str, Any]
+
+
+@dataclass
+class SortResult:
+    """Result of sort by distance operation."""
+
+    data: pd.DataFrame
+    distance_matrix: np.ndarray | None
+    metadata: dict[str, Any]
+
+
+@dataclass
+class RouteResult:
+    """Result of shortest path operation."""
+
+    route: list[int]
+    total_distance: float
+    data: pd.DataFrame
+    metadata: dict[str, Any]
+
+
+@dataclass
+class ComparisonResult:
+    """Result of algorithm comparison."""
+
+    results: dict[str, ClusterResult]
+    statistics: pd.DataFrame
+    metadata: dict[str, Any]

allocator/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface."""

allocator/cli/cluster_cmd.py

@@ -0,0 +1,104 @@
+"""
+Clustering CLI commands.
+"""
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option("--n-clusters", "-n", type=int, required=True, help="Number of clusters")
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine", "osrm", "google"]),
+    help="Distance metric to use",
+)
+@click.option("--max-iter", type=int, default=300, help="Maximum number of iterations")
+@click.option("--random-state", type=int, help="Random seed for reproducibility")
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option("--centroids", "-c", type=click.Path(), help="Centroids output file path")
+@click.option("--plot", is_flag=True, help="Show clustering plot")
+@click.option("--save-plot", type=click.Path(), help="Save plot to file")
+@click.option(
+    "--format",
+    "output_format",
+    default="csv",
+    type=click.Choice(["csv", "json"]),
+    help="Output format",
+)
+@click.pass_context
+def kmeans(
+    ctx,
+    input_file,
+    n_clusters,
+    distance,
+    max_iter,
+    random_state,
+    output,
+    centroids,
+    plot,
+    save_plot,
+    output_format,
+):
+    """K-means clustering of geographic data."""
+    from ..api import kmeans as kmeans_func
+    from ..io.data_handler import DataHandler
+    from ..viz.plotting import plot_clusters
+
+    try:
+        # Run clustering
+        result = kmeans_func(
+            input_file,
+            n_clusters=n_clusters,
+            distance=distance,
+            max_iter=max_iter,
+            random_state=random_state,
+        )
+
+        if ctx.obj.get("verbose"):
+            console.print(f"[green]K-means converged: {result.converged}[/green]")
+            console.print(f"Iterations: {result.n_iter}")
+            if result.inertia:
+                console.print(f"Inertia: {result.inertia:.2f}")
+
+        # Save results
+        if output:
+            DataHandler.save_results(result, output, format=output_format)
+            console.print(f"[green]Results saved to {output}[/green]")
+
+        # Save centroids
+        if centroids:
+            import pandas as pd
+
+            centroids_df = pd.DataFrame(result.centroids, columns=["longitude", "latitude"])
+            if output_format == "csv":
+                centroids_df.to_csv(centroids, index=False)
+            else:
+                centroids_df.to_json(centroids, orient="records", indent=2)
+            console.print(f"[green]Centroids saved to {centroids}[/green]")
+
+        # Plotting
+        if plot or save_plot:
+            plot_clusters(
+                result.data,
+                result.labels,
+                result.centroids,
+                title=f"K-means Clustering (n={n_clusters})",
+                save_path=save_plot,
+                show=plot,
+            )
+            if save_plot:
+                console.print(f"[green]Plot saved to {save_plot}[/green]")
+
+        if not output:
+            console.print("\nFirst 10 results:")
+            console.print(result.data.head(10).to_string())
+
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e

allocator/cli/main.py

@@ -0,0 +1,170 @@
+"""
+Modern CLI interface for allocator package using Click.
+"""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from .. import __version__
+from .cluster_cmd import kmeans
+from .route_cmd import christofides, ortools, tsp
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
+@click.pass_context
+def cli(ctx, verbose):
+    """
+    Allocator v1.0 - Modern geographic task allocation, clustering, and routing.
+
+    Examples:
+        allocator cluster kmeans data.csv -n 5
+        allocator route tsp points.csv --method ortools
+        allocator sort points.csv --workers workers.csv
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+
+
+@cli.group()
+def cluster():
+    """Cluster geographic data points."""
+    pass
+
+
+@cli.group()
+def route():
+    """Find shortest paths through points (TSP)."""
+    pass
+
+
+cluster.add_command(kmeans)
+route.add_command(tsp)
+route.add_command(christofides)
+route.add_command(ortools)
+
+
+@cli.command()
+@click.argument("points", type=click.Path(exists=True))
+@click.option("--workers", "-w", type=click.Path(exists=True), help="Worker locations file")
+@click.option("--by-worker", is_flag=True, help="Sort points by worker instead of workers by point")
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine", "osrm", "google"]),
+    help="Distance metric to use",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option(
+    "--format",
+    "output_format",
+    default="csv",
+    type=click.Choice(["csv", "json"]),
+    help="Output format",
+)
+@click.pass_context
+def sort(ctx, points, workers, by_worker, distance, output, output_format):
+    """Sort points by distance to workers or assign to closest."""
+    from ..api import sort_by_distance
+    from ..io.data_handler import DataHandler
+
+    try:
+        if workers:
+            if by_worker:
+                result = sort_by_distance(points, workers, by_worker=True, distance=distance)
+            else:
+                result = sort_by_distance(points, workers, by_worker=False, distance=distance)
+        else:
+            console.print("[red]Error: --workers option is required[/red]")
+            raise click.Abort()
+
+        # Save results
+        if output:
+            DataHandler.save_results(result, output, format=output_format)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            console.print(result.data.head())
+
+        if ctx.obj["verbose"]:
+            console.print(f"Processed {len(result.data)} assignments")
+
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e
+
+
+@cli.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option(
+    "--algorithms",
+    "-a",
+    default="kmeans",
+    help="Comma-separated list of algorithms to compare",
+)
+@click.option("--n-clusters", "-n", type=int, required=True, help="Number of clusters")
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine", "osrm"]),
+    help="Distance metric to use",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file for comparison results")
+@click.pass_context
+def compare(ctx, input_file, algorithms, n_clusters, distance, output):
+    """Compare clustering algorithms."""
+    from ..api import cluster
+
+    try:
+        algos = [algo.strip() for algo in algorithms.split(",")]
+        results = {}
+
+        for algo in algos:
+            if algo in ["kmeans"]:
+                console.print(f"Running {algo} clustering...")
+                result = cluster(input_file, n_clusters=n_clusters, method=algo, distance=distance)
+                results[algo] = result
+            else:
+                console.print(f"[yellow]Warning: Unknown algorithm '{algo}', skipping[/yellow]")
+
+        # Create comparison table
+        table = Table(title="Clustering Comparison")
+        table.add_column("Algorithm", style="cyan")
+        table.add_column("Converged", style="green")
+        table.add_column("Iterations", style="magenta")
+        table.add_column("Inertia", style="yellow")
+
+        for algo, result in results.items():
+            converged = "Yes" if result.converged else "No"
+            iterations = str(result.n_iter)
+            inertia = f"{result.inertia:.2f}" if result.inertia else "N/A"
+            table.add_row(algo, converged, iterations, inertia)
+
+        console.print(table)
+
+        if output:
+            # Save detailed comparison
+            comparison_data = []
+            for algo, result in results.items():
+                df = result.data.copy()
+                df["algorithm"] = algo
+                comparison_data.append(df)
+
+            import pandas as pd
+
+            combined_df = pd.concat(comparison_data, ignore_index=True)
+            combined_df.to_csv(output, index=False)
+            console.print(f"[green]Detailed results saved to {output}[/green]")
+
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e
+
+
+if __name__ == "__main__":
+    cli()