clara-opt 0.1.0__tar.gz

clara_opt-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Claude
+CLAUDE.md
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+*.whl
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# LaTeX (xelatex)
+*.aux
+*.bbl
+*.bcf
+*.blg
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.run.xml
+*.synctex.gz
+*.toc
+*.lof
+*.lot
+*.nav
+*.snm
+*.vrb
+*.xdv
+
+# Benchmark results (keep only final/)
+benchmarks/results/*
+!benchmarks/results/final/
+
+# OS
+.DS_Store
+Thumbs.db

clara_opt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to CLARA
+
+## Development Setup
+
+```bash
+git clone https://github.com/yoonsik-jung-opt/clara-opt.git
+cd clara-opt
+python3.10 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Code Style
+
+- Python 3.10+, type hints required on all public functions
+- Format: `ruff format clara/ tests/`
+- Lint: `ruff check clara/ tests/`
+- Tests: `pytest tests/`
+
+## Branch Convention
+
+- `feat/*` — new features
+- `fix/*` — bug fixes
+- `bench/*` — benchmarks
+- `paper/*` — paper writing
+- All PRs target `dev` branch
+
+## Commit Convention
+
+`feat:`, `fix:`, `test:`, `bench:`, `paper:`, `docs:`, `refactor:`, `ci:`, `chore:`
+
+## Testing
+
+Every new feature must include tests. Run the full suite before submitting:
+
+```bash
+pytest tests/ -v
+```
+
+Cross-validation tests compare Internal Simplex vs HiGHS — both engines
+must agree on optimal values, duals, and sensitivity ranges.

clara_opt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoonsik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clara_opt-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: clara-opt
+Version: 0.1.0
+Summary: A white-box optimization solver that explains why solutions are optimal, when reoptimization is needed, and what changed.
+Project-URL: Homepage, https://github.com/yoonsikyang/clara-opt
+Project-URL: Repository, https://github.com/yoonsikyang/clara-opt
+Project-URL: Issues, https://github.com/yoonsikyang/clara-opt/issues
+Author: Yoonsik Yang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: explainability,linear-programming,operations-research,optimization,reoptimization,sensitivity-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: highspy>=1.7
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CLARA — Classical LP Analysis for Reoptimization and Attribution
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+
+A white-box optimization solver that explains why solutions are optimal,
+when reoptimization is needed, and what changed.
+
+## Features
+
+- **Solver-intrinsic explanations** — not post-hoc ML surrogate, but direct
+  interpretation of basis, dual values, and sensitivity ranges
+- **Dual backend** — Internal Revised Simplex (full transparency, step-by-step trace)
+  or HiGHS (performance for large problems)
+- **Three explanation levels** mapped to the XAIOR framework (De Bock et al., 2024):
+  - *Understandability*: Which constraints are binding? What resources are fully used?
+  - *Justifiability*: Why is each variable at this value? What's the reduced cost?
+  - *Actionability*: What can change without breaking the solution? Where to invest?
+- **CLI and Python API** — `clara explain problem.lp` or import as library
+
+## Installation
+
+```bash
+pip install clara-opt
+```
+
+For development:
+
+```bash
+git clone https://github.com/yoonsik-jung-opt/clara-opt.git
+cd clara-opt
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Explain a production planning problem
+clara explain examples/production.lp
+
+# Brief summary
+clara explain problem.lp --level brief
+
+# JSON output
+clara explain problem.lp --format json
+
+# Use HiGHS engine for larger problems
+clara explain problem.lp --engine highs
+
+# Solve only (no explanation)
+clara solve problem.lp
+
+# Problem info
+clara info problem.lp
+```
+
+### Python API
+
+```python
+from clara.io import read_lp
+from clara.engine.simplex import RevisedSimplex
+from clara.explain import Explainer
+
+problem = read_lp("problem.lp")
+state = RevisedSimplex(problem).solve()
+report = Explainer().explain(state, problem=problem)
+print(report.to_text())
+```
+
+## Roadmap
+
+- [x] v0.1.0 — LP solver + explainer + CLI (you are here)
+- [ ] v0.5.0 — MIP (Branch-and-Bound), counterfactual analysis, TUI
+- [ ] v1.0.0 — Incremental reoptimization, parametric LP, streaming
+- [ ] v2.0.0 — LLM hybrid explanations, web UI
+
+## Academic Use
+
+CLARA fills a gap identified in the XAIOR framework (De Bock et al., 2024, EJOR):
+explainable AI for mathematical optimization solvers. If you use CLARA in research,
+please cite:
+
+```
+(citation TBD — paper in preparation for Mathematical Programming Computation)
+```
+
+## License
+
+MIT © 2026 Yoonsik

clara_opt-0.1.0/README.md

@@ -0,0 +1,89 @@
+# CLARA — Classical LP Analysis for Reoptimization and Attribution
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+
+A white-box optimization solver that explains why solutions are optimal,
+when reoptimization is needed, and what changed.
+
+## Features
+
+- **Solver-intrinsic explanations** — not post-hoc ML surrogate, but direct
+  interpretation of basis, dual values, and sensitivity ranges
+- **Dual backend** — Internal Revised Simplex (full transparency, step-by-step trace)
+  or HiGHS (performance for large problems)
+- **Three explanation levels** mapped to the XAIOR framework (De Bock et al., 2024):
+  - *Understandability*: Which constraints are binding? What resources are fully used?
+  - *Justifiability*: Why is each variable at this value? What's the reduced cost?
+  - *Actionability*: What can change without breaking the solution? Where to invest?
+- **CLI and Python API** — `clara explain problem.lp` or import as library
+
+## Installation
+
+```bash
+pip install clara-opt
+```
+
+For development:
+
+```bash
+git clone https://github.com/yoonsik-jung-opt/clara-opt.git
+cd clara-opt
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Explain a production planning problem
+clara explain examples/production.lp
+
+# Brief summary
+clara explain problem.lp --level brief
+
+# JSON output
+clara explain problem.lp --format json
+
+# Use HiGHS engine for larger problems
+clara explain problem.lp --engine highs
+
+# Solve only (no explanation)
+clara solve problem.lp
+
+# Problem info
+clara info problem.lp
+```
+
+### Python API
+
+```python
+from clara.io import read_lp
+from clara.engine.simplex import RevisedSimplex
+from clara.explain import Explainer
+
+problem = read_lp("problem.lp")
+state = RevisedSimplex(problem).solve()
+report = Explainer().explain(state, problem=problem)
+print(report.to_text())
+```
+
+## Roadmap
+
+- [x] v0.1.0 — LP solver + explainer + CLI (you are here)
+- [ ] v0.5.0 — MIP (Branch-and-Bound), counterfactual analysis, TUI
+- [ ] v1.0.0 — Incremental reoptimization, parametric LP, streaming
+- [ ] v2.0.0 — LLM hybrid explanations, web UI
+
+## Academic Use
+
+CLARA fills a gap identified in the XAIOR framework (De Bock et al., 2024, EJOR):
+explainable AI for mathematical optimization solvers. If you use CLARA in research,
+please cite:
+
+```
+(citation TBD — paper in preparation for Mathematical Programming Computation)
+```
+
+## License
+
+MIT © 2026 Yoonsik

clara_opt-0.1.0/clara/__init__.py

@@ -0,0 +1,3 @@
+"""CLARA — Classical LP Analysis for Reoptimization and Attribution."""
+
+__version__ = "0.1.0"

clara_opt-0.1.0/clara/cli.py

@@ -0,0 +1,198 @@
+"""CLARA command-line interface.
+
+Pipeline: LP Parser → Solve Engine → Explainer → Output
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from clara.io.lp_parser import LPParseError, read_lp
+from clara.engine.simplex import RevisedSimplex
+from clara.explain.explainer import Explainer
+from clara.explain.types import DetailLevel
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="clara")
+def main():
+    """CLARA — Classical LP Analysis for Reoptimization and Attribution.
+
+    A white-box optimization solver that explains why solutions are optimal,
+    when reoptimization is needed, and what changed.
+    """
+    pass
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--engine", type=click.Choice(["internal", "highs"]),
+              default="internal", help="Solve engine.")
+@click.option("--level", type=click.Choice(["brief", "detailed"]),
+              default="detailed", help="Explanation detail level.")
+@click.option("--format", "fmt", type=click.Choice(["text", "json"]),
+              default="text", help="Output format.")
+@click.option("--output", "-o", type=click.Path(), default=None,
+              help="Write output to file.")
+@click.option("--quiet", "-q", is_flag=True, help="Suppress header.")
+def explain(file, engine, level, fmt, output, quiet):
+    """Solve an LP and explain the solution."""
+    problem = _parse_file(file)
+    state = _solve(problem, engine)
+
+    if not state.is_optimal:
+        click.secho(f"Problem is {state.status.name}.", fg="yellow", err=True)
+        sys.exit(1)
+
+    detail = DetailLevel.BRIEF if level == "brief" else DetailLevel.DETAILED
+    explainer = Explainer()
+    report = explainer.explain(state, level=detail, problem=problem)
+
+    if fmt == "json":
+        text = report.to_json()
+    else:
+        text = report.to_text(level=detail)
+        if quiet:
+            text = _strip_header(text)
+
+    _write_output(text, output)
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--engine", type=click.Choice(["internal", "highs"]),
+              default="internal")
+@click.option("--format", "fmt", type=click.Choice(["text", "json"]),
+              default="text")
+@click.option("--output", "-o", type=click.Path(), default=None)
+def solve(file, engine, fmt, output):
+    """Solve an LP without explanation (quick mode)."""
+    problem = _parse_file(file)
+    state = _solve(problem, engine)
+
+    if fmt == "json":
+        text = state.to_json()
+    else:
+        text = _format_solve_text(state)
+
+    _write_output(text, output)
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+def info(file):
+    """Show problem statistics without solving."""
+    problem = _parse_file(file)
+    nonzeros = int((problem.A != 0).sum())
+    lines = [
+        f"Problem: {problem.name}",
+        f"Variables: {problem.num_variables}",
+        f"Constraints: {problem.num_constraints}",
+        f"Nonzeros: {nonzeros}",
+    ]
+    click.echo("\n".join(lines))
+
+
+@main.command(name="what-if", hidden=True)
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+def what_if(file):
+    """[Phase 1.5] Interactive what-if analysis."""
+    click.secho("what-if is not yet implemented (Phase 1.5).", fg="yellow")
+
+
+@main.command(hidden=True)
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--params", type=click.Path(exists=True))
+def watch(file, params):
+    """[Phase 2] Stream parameter changes and reoptimize."""
+    click.secho("watch is not yet implemented (Phase 2).", fg="yellow")
+
+
+# ============================================================
+# Helpers
+# ============================================================
+
+def _parse_file(filepath: str):
+    """Parse LP file with user-friendly error handling."""
+    try:
+        return read_lp(filepath)
+    except LPParseError as e:
+        click.secho(f"Parse error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+def _solve(problem, engine_name: str):
+    """Solve with the selected engine."""
+    solver = _make_engine(engine_name)
+    state = solver.solve()
+    return state
+
+
+def _make_engine(engine_name: str):
+    """Factory for solve engines. Returns a solver instance (not yet solved)."""
+    # For now, we need the problem to create the solver.
+    # This is handled differently — _solve creates the engine with the problem.
+    raise NotImplementedError  # not used directly
+
+
+def _solve(problem, engine_name: str):
+    """Solve with the selected engine."""
+    if engine_name == "highs":
+        try:
+            from clara.engine.highs_backend import HiGHSBackend
+            return HiGHSBackend().solve(problem)
+        except (ImportError, ModuleNotFoundError):
+            click.secho(
+                "HiGHS backend not yet available. Using internal engine.",
+                fg="yellow", err=True,
+            )
+
+    solver = RevisedSimplex(problem)
+    return solver.solve()
+
+
+def _format_solve_text(state) -> str:
+    """Minimal text output for `clara solve`."""
+    lines = [f"Optimal value: {state.optimal_value:.4f}"]
+    for v in state.variables:
+        lines.append(f"  {v.name} = {v.value:.4f}")
+    lines.append(
+        f"Solved in {state.iteration_count} iterations, "
+        f"{state.solve_time_seconds:.3f}s ({state.engine.name})"
+    )
+    return "\n".join(lines)
+
+
+def _strip_header(text: str) -> str:
+    """Remove header section (everything before double newline after header)."""
+    # Header is between two ═ lines, skip past the second one
+    lines = text.split("\n")
+    sep_count = 0
+    start = 0
+    for i, line in enumerate(lines):
+        if line.startswith("\u2550"):
+            sep_count += 1
+            if sep_count == 2:
+                start = i + 1
+                break
+    # Skip blank line after header
+    while start < len(lines) and not lines[start].strip():
+        start += 1
+    return "\n".join(lines[start:])
+
+
+def _write_output(text: str, output_path: Optional[str]) -> None:
+    """Write to file or stdout."""
+    if output_path:
+        try:
+            Path(output_path).write_text(text)
+            click.secho(f"Written to {output_path}", fg="green", err=True)
+        except IOError as e:
+            click.secho(f"Write error: {e}", fg="red", err=True)
+            sys.exit(1)
+    else:
+        click.echo(text)

clara_opt-0.1.0/clara/engine/__init__.py

@@ -0,0 +1 @@
+"""Solver engine."""