pyoptima 0.0.1__py3-none-any.whl

pyoptima/__init__.py

@@ -0,0 +1,34 @@
+"""
+PyOptima - Declarative Optimization Service
+
+A Python package for declarative optimization that accepts configuration files
+and performs optimizations using various solvers (CBC, GUROBI, GLPK).
+"""
+
+__version__ = "0.0.1"
+
+# Main optimization engine
+from pyoptima.optimization_engine import OptimizationEngine, OptimizationResult
+
+# Config parser
+from pyoptima.config_parser import parse_config, parse_config_file
+
+# Models
+from pyoptima.models.config import OptimizationConfig
+
+# Solvers
+from pyoptima.solvers import SolverType, get_solver
+
+__all__ = [
+    # Optimization Engine
+    "OptimizationEngine",
+    "OptimizationResult",
+    # Config Parser
+    "OptimizationConfig",
+    "parse_config",
+    "parse_config_file",
+    # Solvers
+    "SolverType",
+    "get_solver",
+]
+

pyoptima/cli.py

@@ -0,0 +1,124 @@
+"""
+Main CLI entry point for pyoptima commands.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pyoptima.optimization_engine import OptimizationEngine
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="PyOptima - Declarative Optimization Service",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # optimize subcommand
+    optimize_parser = subparsers.add_parser(
+        "optimize", help="Run optimization from configuration file"
+    )
+    optimize_parser.add_argument(
+        "config_file",
+        type=str,
+        help="Path to optimization configuration file (JSON)",
+    )
+    optimize_parser.add_argument(
+        "--output",
+        type=str,
+        help="Output file path for results (JSON format)",
+    )
+    optimize_parser.add_argument(
+        "--pretty",
+        action="store_true",
+        help="Pretty print output",
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    if args.command == "optimize":
+        return cmd_optimize(
+            config_file=args.config_file,
+            output=args.output,
+            pretty=args.pretty,
+        )
+    else:
+        parser.print_help()
+        return 1
+
+
+def cmd_optimize(config_file: str, output: str = None, pretty: bool = False) -> int:
+    """
+    Run optimization from configuration file.
+
+    Args:
+        config_file: Path to configuration file
+        output: Optional output file path
+        pretty: Whether to pretty print output
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    try:
+        # Create engine
+        engine = OptimizationEngine()
+
+        # Run optimization
+        result = engine.optimize_from_file(config_file)
+
+        # Convert to dictionary
+        result_dict = result.to_dict()
+
+        # Output results
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                if pretty:
+                    json.dump(result_dict, f, indent=2)
+                else:
+                    json.dump(result_dict, f)
+            print(f"✓ Results written to {output}")
+        else:
+            if pretty:
+                print(json.dumps(result_dict, indent=2))
+            else:
+                print(json.dumps(result_dict))
+
+        # Return appropriate exit code
+        if result.is_optimal():
+            return 0
+        else:
+            print(
+                f"⚠ Warning: Optimization did not find optimal solution. Status: {result.status}",
+                file=sys.stderr,
+            )
+            return 1
+
+    except FileNotFoundError as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        return 1
+    except RuntimeError as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}", file=sys.stderr)
+        import traceback
+
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

pyoptima/config_parser/__init__.py

@@ -0,0 +1,8 @@
+"""
+Configuration parser for optimization configs.
+"""
+
+from pyoptima.config_parser.parser import parse_config, parse_config_file
+
+__all__ = ["parse_config", "parse_config_file"]
+

pyoptima/config_parser/parser.py

@@ -0,0 +1,67 @@
+"""
+Parser for optimization configuration files.
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+from pyoptima.models.config import OptimizationConfig
+
+
+def parse_config(config_data: Dict[str, Any]) -> OptimizationConfig:
+    """
+    Parse optimization configuration from a dictionary.
+
+    Args:
+        config_data: Dictionary containing optimization configuration
+
+    Returns:
+        OptimizationConfig object
+
+    Raises:
+        ValueError: If configuration is invalid
+    """
+    try:
+        return OptimizationConfig(**config_data)
+    except Exception as e:
+        raise ValueError(f"Invalid optimization configuration: {e}") from e
+
+
+def parse_config_file(file_path: str) -> OptimizationConfig:
+    """
+    Load and parse an optimization configuration file (JSON).
+
+    Args:
+        file_path: Path to configuration file
+
+    Returns:
+        OptimizationConfig object
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file format is not supported or invalid
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {file_path}")
+
+    # Determine file format
+    suffix = path.suffix.lower()
+
+    if suffix == ".json":
+        with open(path, "r", encoding="utf-8") as f:
+            config_data = json.load(f)
+    else:
+        raise ValueError(
+            f"Unsupported file format: {suffix}. Supported formats: .json"
+        )
+
+    if not isinstance(config_data, dict):
+        raise ValueError(
+            f"Configuration file must contain a dictionary/object, got {type(config_data)}"
+        )
+
+    return parse_config(config_data)
+

pyoptima/models/__init__.py

@@ -0,0 +1,22 @@
+"""
+Pydantic models for optimization configuration.
+"""
+
+from pyoptima.models.config import (
+    Constraint,
+    Meta,
+    Objective,
+    OptimizationConfig,
+    OptimizationVariable,
+    Term,
+)
+
+__all__ = [
+    "OptimizationConfig",
+    "Meta",
+    "OptimizationVariable",
+    "Objective",
+    "Term",
+    "Constraint",
+]
+

pyoptima/models/config.py

@@ -0,0 +1,108 @@
+"""
+Pydantic models for optimization configuration.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Meta(BaseModel):
+    """Metadata for the optimization job."""
+
+    job_id: str = Field(..., description="Unique identifier for the optimization job")
+    solver: Literal["CBC", "GUROBI", "GLPK"] = Field(
+        ..., description="Solver to use for optimization"
+    )
+    time_limit_seconds: Optional[int] = Field(
+        None, description="Time limit for optimization in seconds"
+    )
+
+
+class OptimizationVariable(BaseModel):
+    """Definition of an optimization variable."""
+
+    id: str = Field(..., description="Unique identifier for the variable")
+    type: Literal["Continuous", "Binary", "Integer"] = Field(
+        ..., description="Type of the variable"
+    )
+    lb: Optional[float] = Field(None, description="Lower bound for the variable")
+    ub: Optional[float] = Field(None, description="Upper bound for the variable")
+
+
+class Term(BaseModel):
+    """A term in the objective or constraint expression."""
+
+    var: str = Field(..., description="Variable ID")
+    coef: float = Field(..., description="Coefficient for the variable")
+
+
+class Objective(BaseModel):
+    """Objective function definition."""
+
+    direction: Literal["Maximize", "Minimize"] = Field(
+        ..., description="Direction of optimization"
+    )
+    terms: List[Term] = Field(..., description="Terms in the objective function")
+
+
+class Constraint(BaseModel):
+    """A constraint in the optimization problem."""
+
+    id: str = Field(..., description="Unique identifier for the constraint")
+    lower_bound: Optional[float] = Field(
+        None, description="Lower bound for the constraint"
+    )
+    upper_bound: Optional[float] = Field(
+        None, description="Upper bound for the constraint"
+    )
+    terms: List[Term] = Field(..., description="Terms in the constraint expression")
+
+
+class OptimizationConfig(BaseModel):
+    """Complete optimization configuration."""
+
+    meta: Meta = Field(..., description="Metadata for the optimization job")
+    variables: List[OptimizationVariable] = Field(
+        ..., description="List of optimization variables"
+    )
+    objective: Objective = Field(..., description="Objective function")
+    constraints: List[Constraint] = Field(
+        default_factory=list, description="List of constraints"
+    )
+
+    class Config:
+        """Pydantic config."""
+
+        extra = "forbid"
+        json_schema_extra = {
+            "example": {
+                "meta": {
+                    "job_id": "portfolio-rebalance-001",
+                    "solver": "CBC",
+                    "time_limit_seconds": 30,
+                },
+                "variables": [
+                    {"id": "w_aapl", "type": "Continuous", "lb": 0, "ub": 0.5},
+                    {"id": "shift_john_1", "type": "Binary"},
+                ],
+                "objective": {
+                    "direction": "Maximize",
+                    "terms": [
+                        {"var": "w_aapl", "coef": 0.12},
+                        {"var": "shift_john_1", "coef": -10},
+                    ],
+                },
+                "constraints": [
+                    {
+                        "id": "budget_limit",
+                        "upper_bound": 1.0,
+                        "terms": [
+                            {"var": "w_aapl", "coef": 1},
+                            {"var": "w_msft", "coef": 1},
+                        ],
+                    },
+                ],
+            }
+        }
+

pyoptima/optimization_engine.py

@@ -0,0 +1,111 @@
+"""
+Main optimization engine that processes configurations and runs optimizations.
+"""
+
+from typing import Any, Dict, Optional
+
+from pyoptima.config_parser import parse_config_file
+from pyoptima.models.config import OptimizationConfig
+from pyoptima.solvers import SolverType, get_solver
+
+
+class OptimizationResult:
+    """Result of an optimization run."""
+
+    def __init__(
+        self,
+        status: str,
+        objective_value: Optional[float],
+        variables: Dict[str, float],
+        message: str,
+        job_id: str,
+    ):
+        """
+        Initialize optimization result.
+
+        Args:
+            status: Status of the optimization
+            objective_value: Objective function value (if optimal)
+            variables: Variable values (if optimal)
+            message: Status message
+            job_id: Job ID
+        """
+        self.status = status
+        self.objective_value = objective_value
+        self.variables = variables
+        self.message = message
+        self.job_id = job_id
+
+    def is_optimal(self) -> bool:
+        """Check if the solution is optimal."""
+        return self.status == "optimal"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary."""
+        return {
+            "job_id": self.job_id,
+            "status": self.status,
+            "objective_value": self.objective_value,
+            "variables": self.variables,
+            "message": self.message,
+        }
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"OptimizationResult(job_id={self.job_id}, status={self.status}, "
+            f"objective_value={self.objective_value})"
+        )
+
+
+class OptimizationEngine:
+    """Main engine for running optimizations from configuration files."""
+
+    def __init__(self):
+        """Initialize the optimization engine."""
+        pass
+
+    def optimize_from_file(self, config_file: str) -> OptimizationResult:
+        """
+        Run optimization from a configuration file.
+
+        Args:
+            config_file: Path to configuration file
+
+        Returns:
+            OptimizationResult object
+        """
+        config = parse_config_file(config_file)
+        return self.optimize(config)
+
+    def optimize(self, config: OptimizationConfig) -> OptimizationResult:
+        """
+        Run optimization from a configuration object.
+
+        Args:
+            config: Optimization configuration
+
+        Returns:
+            OptimizationResult object
+        """
+        # Get solver type
+        solver_type = SolverType(config.meta.solver)
+
+        # Get solver instance
+        solver = get_solver(
+            solver_type=solver_type,
+            time_limit_seconds=config.meta.time_limit_seconds,
+        )
+
+        # Solve
+        result_dict = solver.solve(config)
+
+        # Create result object
+        return OptimizationResult(
+            status=result_dict["status"],
+            objective_value=result_dict.get("objective_value"),
+            variables=result_dict.get("variables", {}),
+            message=str(result_dict.get("message", "")),
+            job_id=config.meta.job_id,
+        )
+

pyoptima/solvers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Solver abstraction layer for different optimization solvers.
+"""
+
+from pyoptima.solvers.base import Solver, SolverType
+from pyoptima.solvers.factory import get_solver
+
+__all__ = ["Solver", "SolverType", "get_solver"]
+

pyoptima/solvers/base.py

@@ -0,0 +1,60 @@
+"""
+Base solver interface and types.
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from pyoptima.models.config import OptimizationConfig
+
+
+class SolverType(str, Enum):
+    """Supported solver types."""
+
+    CBC = "CBC"
+    GUROBI = "GUROBI"
+    GLPK = "GLPK"
+
+
+class Solver(ABC):
+    """Abstract base class for optimization solvers."""
+
+    def __init__(self, time_limit_seconds: Optional[int] = None):
+        """
+        Initialize solver.
+
+        Args:
+            time_limit_seconds: Time limit for optimization in seconds
+        """
+        self.time_limit_seconds = time_limit_seconds
+
+    @abstractmethod
+    def solve(
+        self, config: OptimizationConfig
+    ) -> Dict[str, Any]:
+        """
+        Solve the optimization problem.
+
+        Args:
+            config: Optimization configuration
+
+        Returns:
+            Dictionary containing:
+                - status: str - Status of the optimization (e.g., "optimal", "infeasible", "unbounded")
+                - objective_value: float - Objective function value (if optimal)
+                - variables: Dict[str, float] - Variable values (if optimal)
+                - message: str - Status message
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the solver is available.
+
+        Returns:
+            True if solver is available, False otherwise
+        """
+        pass
+

pyoptima/solvers/cbc_solver.py

@@ -0,0 +1,117 @@
+"""
+CBC (COIN-OR Branch and Cut) solver implementation.
+"""
+
+from typing import Any, Dict, Optional
+
+try:
+    from pulp import LpMaximize, LpMinimize, LpProblem, LpStatus, lpSum, LpVariable
+    PULP_AVAILABLE = True
+except ImportError:
+    PULP_AVAILABLE = False
+
+from pyoptima.models.config import OptimizationConfig
+from pyoptima.solvers.base import Solver
+
+
+class CBCSolver(Solver):
+    """CBC solver implementation using PuLP."""
+
+    def is_available(self) -> bool:
+        """Check if CBC solver is available."""
+        return PULP_AVAILABLE
+
+    def solve(self, config: OptimizationConfig) -> Dict[str, Any]:
+        """
+        Solve the optimization problem using CBC.
+
+        Args:
+            config: Optimization configuration
+
+        Returns:
+            Dictionary with optimization results
+        """
+        if not self.is_available():
+            raise RuntimeError("CBC solver is not available. Install pulp: pip install pulp")
+
+        # Create PuLP problem
+        sense = LpMaximize if config.objective.direction == "Maximize" else LpMinimize
+        prob = LpProblem(config.meta.job_id, sense)
+
+        # Create variables
+        variables = {}
+        for var_def in config.variables:
+            if var_def.type == "Binary":
+                var = LpVariable(var_def.id, cat="Binary")
+            elif var_def.type == "Integer":
+                var = LpVariable(
+                    var_def.id,
+                    lowBound=var_def.lb,
+                    upBound=var_def.ub,
+                    cat="Integer",
+                )
+            else:  # Continuous
+                var = LpVariable(
+                    var_def.id,
+                    lowBound=var_def.lb,
+                    upBound=var_def.ub,
+                    cat="Continuous",
+                )
+            variables[var_def.id] = var
+
+        # Add objective
+        objective_terms = [
+            term.coef * variables[term.var] for term in config.objective.terms
+        ]
+        prob += lpSum(objective_terms)
+
+        # Add constraints
+        for constraint in config.constraints:
+            constraint_terms = [
+                term.coef * variables[term.var] for term in constraint.terms
+            ]
+            expr = lpSum(constraint_terms)
+
+            if constraint.lower_bound is not None and constraint.upper_bound is not None:
+                prob += expr >= constraint.lower_bound
+                prob += expr <= constraint.upper_bound
+            elif constraint.lower_bound is not None:
+                prob += expr >= constraint.lower_bound
+            elif constraint.upper_bound is not None:
+                prob += expr <= constraint.upper_bound
+
+        # Set time limit if specified
+        if self.time_limit_seconds:
+            # PuLP doesn't directly support time limits, but we can note it
+            # In practice, you might need to use solver-specific options
+            pass
+
+        # Solve
+        prob.solve(solver="CBC")
+
+        # Extract results
+        status_map = {
+            "Optimal": "optimal",
+            "Infeasible": "infeasible",
+            "Unbounded": "unbounded",
+            "Not Solved": "not_solved",
+        }
+
+        pulp_status = LpStatus[prob.status]
+        status = status_map.get(pulp_status, "unknown")
+
+        result = {
+            "status": status,
+            "message": pulp_status,
+            "objective_value": None,
+            "variables": {},
+        }
+
+        if status == "optimal":
+            result["objective_value"] = prob.objective.value()
+            result["variables"] = {
+                var_id: var.varValue for var_id, var in variables.items()
+            }
+
+        return result
+