feat: add helper functions to enable dataframe exporting

Author: mcllerena

bindings/python/README.md

@@ -69,3 +69,44 @@ model.scenario("baseline", log_to_console=False)
 solution = model.run_scenario("baseline")
 assert solution.is_optimal()
 ```
+
+## Result Export To pandas/polars DataFrames
+
+Solve results can be exported directly to DataFrames for analysis workflows.
+
+- `solution.to_pandas(table="variables")`
+- `solution.to_polars(table="variables")`
+
+Supported `table` values are:
+
+- `"variables"`: one row per variable with primal value and reduced cost.
+- `"constraints"`: one row per constraint with dual value.
+- `"summary"`: one-row solve summary (status, objective, solve time).
+
+Example:
+
+```python
+solution = model.run_scenario("baseline")
+
+variables_df = solution.to_pandas(table="variables")
+constraints_df = solution.to_pandas(table="constraints")
+summary_df = solution.to_pandas(table="summary")
+
+variables_pl = solution.to_polars(table="variables")
+```
+
+Install optional dependencies as needed:
+
+```bash
+cd bindings/python
+uv pip install pandas
+uv pip install polars
+```
+
+or
+
+```bash
+cd bindings/python
+uv add pandas
+uv add polars
+```

bindings/python/arco/__init__.py

@@ -200,9 +200,80 @@ def _model_run_scenario(
     return self.solve(**solve_kwargs)
 
 
+def _solve_result_records(
+    self: _arco.SolveResult,
+    *,
+    table: str = "variables",
+) -> list[dict[str, object]]:
+    if table == "variables":
+        return [
+            {
+                "variable_id": idx,
+                "value": primal,
+                "reduced_cost": reduced_cost,
+            }
+            for idx, (primal, reduced_cost) in enumerate(
+                zip(self.primal_values, self.variable_duals, strict=True)
+            )
+        ]
+
+    if table == "constraints":
+        return [
+            {
+                "constraint_id": idx,
+                "dual": dual,
+            }
+            for idx, dual in enumerate(self.constraint_duals)
+        ]
+
+    if table == "summary":
+        return [
+            {
+                "status": self.status_string(),
+                "objective_value": self.objective_value,
+                "solve_time_seconds": self.solve_time_seconds(),
+                "is_optimal": self.is_optimal(),
+            }
+        ]
+
+    raise ValueError("table must be one of {'variables', 'constraints', 'summary'}")
+
+
+def _solve_result_to_pandas(
+    self: _arco.SolveResult,
+    *,
+    table: str = "variables",
+) -> object:
+    try:
+        import pandas as pd
+    except ModuleNotFoundError as exc:  # pragma: no cover - optional dependency
+        raise ModuleNotFoundError(
+            "to_pandas() requires pandas. Install with `uv add pandas` or `pip install pandas`."
+        ) from exc
+
+    return pd.DataFrame.from_records(_solve_result_records(self, table=table))
+
+
+def _solve_result_to_polars(
+    self: _arco.SolveResult,
+    *,
+    table: str = "variables",
+) -> object:
+    try:
+        import polars as pl
+    except ModuleNotFoundError as exc:  # pragma: no cover - optional dependency
+        raise ModuleNotFoundError(
+            "to_polars() requires polars. Install with `uv add polars` or `pip install polars`."
+        ) from exc
+
+    return pl.DataFrame(_solve_result_records(self, table=table))
+
+
 setattr(_arco.Model, "control", _model_control)
 setattr(_arco.Model, "scenario", _model_scenario)
 setattr(_arco.Model, "run_scenario", _model_run_scenario)
+setattr(_arco.SolveResult, "to_pandas", _solve_result_to_pandas)
+setattr(_arco.SolveResult, "to_polars", _solve_result_to_polars)
 
 
 if "block" not in __all__:

bindings/python/arco/arco.pyi

@@ -407,6 +407,8 @@ class SolveResult:
     def is_unbounded(self) -> bool: ...
     def status_string(self) -> str: ...
     def solve_time_seconds(self) -> float: ...
+    def to_pandas(self, *, table: str = "variables") -> object: ...
+    def to_polars(self, *, table: str = "variables") -> object: ...
 
 class VariableView:
     @property

bindings/python/tests/test_arco_stub_operators.py

@@ -119,3 +119,15 @@ def test_model_stub_exposes_scenario_declaration_signatures() -> None:
     _assert_signatures_present(
         block=model_block, expected_signatures=expected_signatures
     )
+
+    def test_solve_result_stub_exposes_dataframe_export_signatures() -> None:
+        source = (Path(__file__).resolve().parents[1] / "arco" / "arco.pyi").read_text()
+        solve_result_block = _class_block(source=source, class_name="SolveResult")
+        expected_signatures = [
+            'def to_pandas(self, *, table: str = "variables") -> object: ...',
+            'def to_polars(self, *, table: str = "variables") -> object: ...',
+        ]
+        _assert_signatures_present(
+            block=solve_result_block,
+            expected_signatures=expected_signatures,
+        )