Metadata-Version: 2.4
Name: meerax
Version: 1.7.3
Summary: Shared ML utilities — LLM providers, evaluation metrics, visualization, and report generation for Sameer Maurya's projects and organization.
Author: Sameer Maurya
License-Expression: MIT
Project-URL: Homepage, https://github.com/mauryasameer/the-forge
Project-URL: Repository, https://github.com/mauryasameer/the-forge
Project-URL: Issues, https://github.com/mauryasameer/the-forge/issues
Project-URL: Changelog, https://github.com/mauryasameer/the-forge/blob/main/CHANGELOG.md
Keywords: machine-learning,llm,evaluation,visualization
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: matplotlib>=3.8
Requires-Dist: scikit-learn>=1.4
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == "llm"
Requires-Dist: openai>=1.55; extra == "llm"
Requires-Dist: ollama>=0.3; extra == "llm"
Provides-Extra: stats
Requires-Dist: statsmodels>=0.14; extra == "stats"
Provides-Extra: nlp
Requires-Dist: nltk>=3.9; extra == "nlp"
Provides-Extra: imbalance
Requires-Dist: imbalanced-learn>=0.12; extra == "imbalance"
Provides-Extra: vision
Requires-Dist: torch>=2.2; extra == "vision"
Requires-Dist: torchvision>=0.17; extra == "vision"
Requires-Dist: pillow>=10.2; extra == "vision"
Provides-Extra: parquet
Requires-Dist: pyarrow>=15; extra == "parquet"
Provides-Extra: all
Requires-Dist: meerax[llm]; extra == "all"
Requires-Dist: meerax[stats]; extra == "all"
Requires-Dist: meerax[nlp]; extra == "all"
Requires-Dist: meerax[imbalance]; extra == "all"
Requires-Dist: meerax[vision]; extra == "all"
Requires-Dist: meerax[parquet]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff==0.16.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# meerax

![Version](https://img.shields.io/badge/version-1.7.3-c8a96e)
![Python](https://img.shields.io/badge/python-3.12-00e5cc)
![License](https://img.shields.io/badge/license-MIT-informational)

Shared ML utilities — LLM providers, evaluation metrics, visualization, and report generation.
Used as an in-house dependency across all of Sameer Maurya's ML projects and organization.
Source repo: [the-forge](https://github.com/mauryasameer/the-forge) — kept its original name;
only the installable package was renamed to `meerax`.

CI gates on mypy (`strict = true`, with 2 narrowly-scoped `# type: ignore` exceptions for known
third-party stub gaps) and a minimum 85% test coverage — both enforced on every PR, not just
checked locally.

## Install

```bash
pip install meerax
```

Or pin in `requirements.txt`:

```
meerax==1.7.3
```

## Modules

| Module | What it gives you |
|---|---|
| `meerax.llm` | Swap-in LLM backends — Claude, OpenAI, Ollama behind one interface, text or images |
| `meerax.eval.classification` | F1, AUC-ROC, precision, recall in one call |
| `meerax.eval.timeseries` | RMSE, MAPE, SMAPE, ADF stationarity test |
| `meerax.eval.text` | BLEU-4, ROUGE-L for caption / summary quality |
| `meerax.viz` | Dark-themed matplotlib plots (confusion matrix, ROC, forecast, decomposition) |
| `meerax.data` | CSV/parquet loaders with schema validation, stratified + time splits, SMOTE |
| `meerax.report` | Self-contained dark-themed HTML model-card report builder |
| `meerax.logging` | One-call structured logger factory |
| `meerax.vision` | Image folder dataset loader (PyTorch) + translation-grid plotting (torch or numpy/TF images) |

## Scaffolding Projects

Every project in the ecosystem follows the same PROJECT_STANDARDS.md layout and depends on
`meerax`. The `meerax` CLI (installed alongside the package) generates or retrofits that layout:

```bash
# brand-new project
meerax new my-project --path ~/dev

# retrofit an existing, non-empty directory — additive only, never overwrites
cd ~/dev/my-existing-notebook-project
meerax init
```

`meerax new` creates the full `src/{core,providers,services,utils,data}` + `tests/` + CI
skeleton, pins `requirements.txt` to the current `meerax` release, and runs `git init`. The
generated `ci.yml` calls this repo's [reusable CI workflow](.github/workflows/reusable-ci.yml)
instead of embedding its own copy, so fixes to the shared CI logic reach every project that
uses it without needing to be manually reapplied. Also generates `.github/dependabot.yml`
(pip + github-actions, weekly) so dependency pins don't quietly go stale.

Both `new` and `init` accept `--template llm-report`, which adds a real, runnable example on
top of the bare skeleton — the "call an LLM, build an HTML report" shape that's shown up twice
already (trend-whisperer, pixel-drift). It's genuinely functional code with real tests, not
stub methods to fill in:

```bash
meerax new my-app --template llm-report
cd my-app && pip install -r requirements.txt
python -m src.app --prompt "Summarize this quarter's churn" --llm-provider ollama
```

`meerax init` fills in whatever's missing from that same layout without touching files that
already exist, and reports any top-level files it doesn't recognize (e.g. notebooks) so you can
move them into `src/` by hand.

`meerax doctor` checks an existing project against PROJECT_STANDARDS.md — no Python version
matrix, no committed `docs/specs`/`docs/plans`, a LICENSE file, VERSION/README/CHANGELOG
consistency, Dependabot configured, and whether the project's `meerax` pin is current:

```bash
cd ~/dev/my-project
meerax doctor
```

Exits non-zero if anything fails, so it's safe to run in CI.

`meerax bump <version>` updates VERSION, the README version badge, and inserts a dated
CHANGELOG heading in one step — the exact multi-file edit that's caused version-badge drift
more than once across this ecosystem's history:

```bash
meerax bump 1.2.0
```

It doesn't write CHANGELOG content or a compare-link footer — those need someone who actually
knows what changed.

## Quick Start

```python
from meerax.llm import ClaudeProvider, PromptTemplate
from meerax.eval import evaluate_classifier
from meerax.viz import apply_meerax_theme
from meerax.report import ReportBuilder, ReportSection

# LLM: swap provider without changing downstream code
llm = ClaudeProvider()                         # or OpenAIProvider() / OllamaProvider()
tpl = PromptTemplate("Explain {finding} to a risk manager in 3 sentences.")
response = llm.generate(tpl.render(finding="high AUC-ROC with low recall"))

# Eval
metrics = evaluate_classifier(y_true, y_pred, y_prob=probabilities)
print(metrics)
# Accuracy : 0.9823
# F1       : 0.8741
# AUC-ROC  : 0.9912

# Viz + Report
apply_meerax_theme()
rb = ReportBuilder("Fraud Detection — Model Report v0.1.0")
rb.add_section(ReportSection(
    title="Performance",
    metrics=metrics.to_dict(),
    content=response.content,
))
rb.save("reports/model_report.html")
```

## LLM Provider Interface

All providers implement `LLMProvider.generate()` and `.chat()`. Swap with one line:

```python
from meerax.llm import ClaudeProvider, OpenAIProvider, OllamaProvider

llm = ClaudeProvider()    # needs ANTHROPIC_API_KEY
llm = OpenAIProvider()    # needs OPENAI_API_KEY
llm = OllamaProvider()    # needs Ollama running locally
```

## Benchmarks

Self-contained benchmark scripts in `benchmarks/`:

| Script | Description |
|---|---|
| `kv_cache_benchmark.py` | KV caching simulation at GPT-2 Medium scale |

## Project Structure

```
the-forge/
├── meerax/              # Installable package
│   ├── llm/            # LLM provider abstraction
│   ├── eval/            # Evaluation metrics
│   ├── viz/             # Visualization utilities
│   ├── data/            # Data loading, splitting, resampling
│   ├── report/          # HTML report builder
│   ├── scaffold/        # Project skeleton templates + create/retrofit logic
│   ├── cli.py           # `meerax new` / `init` / `doctor` / `bump` command entry point
│   ├── doctor.py        # PROJECT_STANDARDS.md compliance checks
│   ├── release.py       # VERSION/README badge/CHANGELOG bump helper
│   ├── vision/          # Image dataset loader + translation-grid plotting
│   └── logging.py       # Structured logger
├── benchmarks/          # Standalone ML benchmark scripts
├── tests/
│   ├── unit/            # 143 unit tests, zero external deps
│   └── integration/     # 4 cross-module pipeline tests
├── ARCHITECTURE.md
├── SECURITY.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── VERSION
```

---

[sameer-portfolio](https://github.com/mauryasameer/sameer-portfolio) · [mauryasameer.com](https://www.mauryasameer.com)
