Metadata-Version: 2.4
Name: clara-opt
Version: 0.2.1
Summary: Solver-intrinsic explanations and reoptimization for linear programming
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: counterfactual-explanations,explainable-optimization,linear-programming,optimization,reoptimization,sensitivity-analysis,simplex-method
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 :: Information Analysis
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'
Requires-Dist: scipy>=1.10; 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 solver-intrinsic explanation framework for linear programming. CLARA extracts
explanations directly from the simplex basis inverse $B^{-1}$ — without machine
learning surrogates, without inverse formulations — and unifies factual and
counterfactual perspectives on LP explainability within a single geometric framework.

## What CLARA does

CLARA contributes two central capabilities, complemented by two supporting modules:

- **Factual–counterfactual duality** — a formal bound showing that the basis
  robustness $d_0$, computable in $O(mn)$ time from $B^{-1}$ alone, lower-bounds
  the cost of any basis-changing counterfactual explanation. Connects classical
  sensitivity analysis with counterfactual explanations for optimization.
- **Reoptimization pipeline** — automatic change detection, Oguz-bound impact
  analysis, warm-start method selection (primal simplex, dual simplex, or
  parametric LP), and structured diff reports.
- **Simultaneous sensitivity regions** (supporting) — Chebyshev center of the
  basis-preserving polyhedron, the geometric foundation of the duality bound.
- **Objective-change attribution** (supporting) — first-order and Shapley
  decomposition that annotates diff reports during reoptimization.

CLARA also offers two solver backends:

- **Internal Revised Simplex** — full transparency, retains $B^{-1}$ at every
  pivot for downstream analysis (practical for $n \le 100$).
- **HiGHS** — production-grade reference solver; CLARA reconstructs $B^{-1}$
  from the reported basis for larger problems.

## 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, basis-inverse extraction, explanation modules, CLI
- [ ] v0.5.0 — MIP (Branch-and-Bound), counterfactual computation via $d_0$
  warm-start, TUI
- [ ] v1.0.0 — Incremental reoptimization, parametric LP, streaming
- [ ] v2.0.0 — LLM-augmented natural-language explanations, web UI

## Academic Use

CLARA contributes to the explainability of mathematical optimization solvers,
a research area surveyed by De Bock et al. (2024) in the XAIOR framework.

A manuscript describing the framework is in preparation. Citation information
will be added here when a preprint or peer-reviewed version is available.

## License

MIT © 2026 Yoonsik