meerax

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 — kept its original name; only the installable package was renamed to meerax.

CI gates on mypy (strict, zero ignored errors) and a minimum 85% test coverage — both enforced on every PR, not just checked locally.

Install

pip install meerax

Or pin in requirements.txt:

meerax==1.4.0

Modules

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:

# 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 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.

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:

cd ~/dev/my-project
meerax doctor

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

Quick Start

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:

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/:

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` command entry point
│   ├── doctor.py        # PROJECT_STANDARDS.md compliance checks
│   ├── vision/          # Image dataset loader + translation-grid plotting
│   └── logging.py       # Structured logger
├── benchmarks/          # Standalone ML benchmark scripts
├── tests/
│   ├── unit/            # 117 unit tests, zero external deps
│   └── integration/     # 3 cross-module pipeline tests
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── VERSION

sameer-portfolio · mauryasameer.com