How richardoberdieck/opti_fit works
Project Type and Purpose
• This is an open-source Python CLI tool/library (“opti_fit”) for computing optimal string-matching thresholds via various mathematical models (simple, relaxed, combination) using Gurobi as the solver. It bundles:
• Data (raw CSV/.mst)
• Model definitions (Python modules under opti_fit/models)
• Runner scripts (CLI entrypoints under opti_fit/runners)
• Utility functions (opti_fit/utils)
• Documentation site powered by MkDocs (mkdocs.yml + docs/…)
• Tests and CI workflows
Key Components
a. CLI Layer
• hatch-managed entrypoints (hatch run simple|relaxed|combination|compare)
• Shell wrapper (runs.sh)
b. Runner Modules (opti_fit/runners/*.py)
• Parse CLI args
• Invoke dataset loading & model building
• Dispatch job to solver (Gurobi)
• Collect and persist results (JSON under results/)
c. Model Layer (opti_fit/models/*.py)
• simple_model.py, relaxed_model.py, models.py (algorithm-combination)
• Variables, constraints, objectives for each variant
d. Utility Layer (opti_fit/utils/*.py)
• dataset_utils: load/compress/prepare datasets
• model_utils: common model-building helpers
• runner_utils: result formatting & storage
e. Data & Results
• Raw data in data/
• Output JSON in results/
f. Documentation & CI
• MkDocs site (docs/, mkdocs.yml)
• GitHub Actions workflows (.github/workflows/*.yaml)
• Pre-commit config, tests under tests/
Relationships & Data Flow
1. User invokes CLI (hatch run … or runs.sh)
2. Runner module parses options → calls dataset_utils to load data
3. Runner passes data + parameters to the chosen Model class
4. Model module constructs a Gurobi model via model_utils
5. Model is solved by Gurobi (external service)
6. runner_utils formats and writes the output JSON to results/
7. Optionally, generate images via generate_images.py or build docs via MkDocs
Architectural Patterns & Principles
• Layered architecture (CLI → Runners → Models → Utils → Solver)
• Separation of concerns: data loading vs. model definition vs. result handling
• Extensibility: add new model by dropping in opti_fit/models/new_model.py and corresponding runner
• Configuration via pyproject.toml and environment variables (gurobi.env)
• CI/CD pipeline for tests, linting, and docs publishing
• “opti_fit” package containing Models / Runners / Utils
• “Infrastructure” containing Gurobi, file system (data/results), CI/CD, Docs host