meridian-regression 0.1.0__tar.gz

meridian_regression-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell(New-Item *)",
+      "PowerShell(pip install *)",
+      "PowerShell(cd \"C:\\\\Users\\\\VijayMandavilli\\\\OneDrive - Cognida Pvt Limited\\\\Desktop\\\\Tinkering\\\\meridian\"; $env:DEEPSEEK_API_KEY = \"sk-d95291da521d43ab8db825b8d2a4461e\"; $env:PYTHONIOENCODING = \"utf-8\"; python scripts/generate_golden_dataset.py 2>&1)"
+    ]
+  }
+}

meridian_regression-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+*.egg
+
+# test cache
+.pytest_cache/
+.coverage
+htmlcov/
+
+# sentence-transformers model cache (large, re-downloadable)
+# .cache/
+
+# generated reports (reproducible from golden dataset)
+reports/
+
+# populated golden dataset — contains API outputs, regenerate with scripts/generate_golden_dataset.py
+datasets/golden_50.json
+
+# paper build artefacts
+paper/*.aux
+paper/*.bbl
+paper/*.blg
+paper/*.log
+paper/*.out
+paper/*.pdf
+paper/*.synctex.gz
+paper/*.toc

meridian_regression-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: meridian-regression
+Version: 0.1.0
+Summary: Local, embedding-based LLM model equivalence scoring for migration validation
+Project-URL: Repository, https://github.com/mandavillivijay/meridian
+Author-email: Vijay Mandavilli <mvijayfromvizag@gmail.com>
+License: MIT
+Keywords: embeddings,equivalence,llm,model-migration,nlp,regression-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sentence-transformers>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MERIDIAN
+
+**Model Equivalence and Regression via Intent Drift In AI Networks**
+
+A lightweight Python library for validating LLM model equivalence when a vendor deprecates a model and you need to migrate to a replacement.
+
+---
+
+## The Problem
+
+When OpenAI deprecates `gpt-4-0613` or Anthropic retires `claude-2`, enterprise teams have no established, reusable methodology to validate that the replacement produces semantically equivalent outputs for their specific workload. Traditional software testing checks exact outputs — useless for non-deterministic LLM responses. Existing benchmarks (MMLU, HELM) measure absolute capability, not relative equivalence between two specific models on your use case.
+
+## How MERIDIAN Is Different
+
+Recent work ([arXiv:2604.27082](https://arxiv.org/abs/2604.27082), [arXiv:2507.05573](https://arxiv.org/abs/2507.05573), [arXiv:2604.27789](https://arxiv.org/abs/2604.27789)) describes migration validation processes using LLM-as-judge evaluation or human review. MERIDIAN takes a different approach:
+
+| | Existing approaches | MERIDIAN |
+|---|---|---|
+| **Scoring method** | LLM-as-judge or human eval | Sentence-transformer cosine similarity |
+| **Cloud dependency** | Requires API calls to score | Runs entirely locally |
+| **Cost** | Per-token API cost to evaluate | Free after model download |
+| **Reproducibility** | Non-deterministic (LLM judge) | Deterministic |
+| **Framing** | Evaluation problem | Regression testing problem |
+| **Format** | Research process descriptions | Reusable open-source library |
+
+**Core insight:** embed old and new model outputs using a sentence-transformer, compute cosine similarity, and flag pairs below a drift threshold. Same technique as [canvas-heal](https://pypi.org/project/canvas-heal/) (UI locator healing), different problem surface.
+
+## Three-Tier Gate
+
+```
+Cosine Similarity
+─────────────────────────────────────────────────────────
+0.0 ──────────── 0.75 ──────────── 0.92 ──────────── 1.0
+     DRIFTED          REVIEW              EQUIVALENT
+     (flag)         (human eye)          (auto-pass)
+```
+
+Thresholds are configurable. Defaults (0.92 / 0.75) are starting points — calibrate them against a small human-labeled set for your domain. See the accompanying paper for a calibration procedure derived from the deepseek-chat (V3) → deepseek-reasoner (R1) empirical study.
+
+## Installation
+
+```bash
+pip install meridian-regression
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mandavillivijay/meridian
+cd meridian
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+### 1. Build your golden dataset
+
+Create a JSON file with outputs from both models for each prompt:
+
+```json
+[
+  {
+    "prompt": "What is the capital of France?",
+    "intent": "factual",
+    "old_output": "The capital of France is Paris.",
+    "new_output": "Paris is the capital city of France."
+  }
+]
+```
+
+Intent categories: `factual`, `generative`, `classification`, `structured_output`.
+
+Run your old model and new model on the same prompts, save the outputs. MERIDIAN doesn't call any APIs — you bring the outputs.
+
+### 2. Run the pipeline
+
+```python
+from meridian.runner import run
+
+report = run("datasets/my_golden_set.json")
+print(report.summary)
+# "94.0% of outputs are semantically equivalent, 4.0% show minor drift
+#  requiring human review, 2.0% show significant drift (regression flagged)."
+```
+
+### 3. Use the report
+
+```python
+print(f"Equivalent: {report.equivalent_pct}%")
+print(f"Wilson 95% CI: [{report.wilson_lower:.3f}, {report.wilson_upper:.3f}]")
+```
+
+JSON and markdown reports are written to `reports/` automatically.
+
+## Advanced Usage
+
+```python
+from meridian.runner import run
+
+report = run(
+    "datasets/my_golden_set.json",
+    sample_n=50,              # stratified sample of 50 prompts
+    seed=42,                  # reproducible sampling
+    equivalent_threshold=0.90,
+    review_threshold=0.70,
+    report_stem="sonnet_migration_v2",
+)
+```
+
+### Using modules directly
+
+```python
+from meridian.sampler import load, stratified_sample
+from meridian.scorer import DriftScorer
+from meridian.reporter import Reporter
+
+records = load("datasets/my_golden_set.json")
+records = stratified_sample(records, n=50, seed=42)
+
+scorer = DriftScorer()
+results = scorer.score_all(records)
+
+reporter = Reporter()
+report = reporter.build(results)
+reporter.write(report, stem="my_run")
+```
+
+### Bringing your own adapter
+
+If you want to populate outputs programmatically rather than from a JSON file, implement the `ModelAdapter` protocol:
+
+```python
+from meridian.adapters.base import ModelAdapter
+
+class MyAdapter:
+    def complete(self, prompt: str) -> str:
+        # call your model here
+        ...
+    def name(self) -> str:
+        return "my-model-v2"
+```
+
+## Project Structure
+
+```
+meridian/
+├── meridian/
+│   ├── models.py       # Pydantic data models
+│   ├── embedder.py     # Sentence-transformer wrapper (singleton)
+│   ├── scorer.py       # Three-tier drift gate
+│   ├── reporter.py     # Aggregate verdict + JSON/markdown output
+│   ├── sampler.py      # Dataset loading + stratified sampling
+│   ├── runner.py       # End-to-end pipeline entry point
+│   └── adapters/
+│       └── base.py     # ModelAdapter Protocol (extension point)
+├── datasets/           # Example golden datasets
+├── reports/            # Generated reports
+└── tests/              # pytest suite (106 tests)
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Author
+
+Vijay Mandavilli — Quality Engineering Lead, Cognida AI, Hyderabad, India
+
+## License
+
+MIT

meridian_regression-0.1.0/README.md

@@ -0,0 +1,173 @@
+# MERIDIAN
+
+**Model Equivalence and Regression via Intent Drift In AI Networks**
+
+A lightweight Python library for validating LLM model equivalence when a vendor deprecates a model and you need to migrate to a replacement.
+
+---
+
+## The Problem
+
+When OpenAI deprecates `gpt-4-0613` or Anthropic retires `claude-2`, enterprise teams have no established, reusable methodology to validate that the replacement produces semantically equivalent outputs for their specific workload. Traditional software testing checks exact outputs — useless for non-deterministic LLM responses. Existing benchmarks (MMLU, HELM) measure absolute capability, not relative equivalence between two specific models on your use case.
+
+## How MERIDIAN Is Different
+
+Recent work ([arXiv:2604.27082](https://arxiv.org/abs/2604.27082), [arXiv:2507.05573](https://arxiv.org/abs/2507.05573), [arXiv:2604.27789](https://arxiv.org/abs/2604.27789)) describes migration validation processes using LLM-as-judge evaluation or human review. MERIDIAN takes a different approach:
+
+| | Existing approaches | MERIDIAN |
+|---|---|---|
+| **Scoring method** | LLM-as-judge or human eval | Sentence-transformer cosine similarity |
+| **Cloud dependency** | Requires API calls to score | Runs entirely locally |
+| **Cost** | Per-token API cost to evaluate | Free after model download |
+| **Reproducibility** | Non-deterministic (LLM judge) | Deterministic |
+| **Framing** | Evaluation problem | Regression testing problem |
+| **Format** | Research process descriptions | Reusable open-source library |
+
+**Core insight:** embed old and new model outputs using a sentence-transformer, compute cosine similarity, and flag pairs below a drift threshold. Same technique as [canvas-heal](https://pypi.org/project/canvas-heal/) (UI locator healing), different problem surface.
+
+## Three-Tier Gate
+
+```
+Cosine Similarity
+─────────────────────────────────────────────────────────
+0.0 ──────────── 0.75 ──────────── 0.92 ──────────── 1.0
+     DRIFTED          REVIEW              EQUIVALENT
+     (flag)         (human eye)          (auto-pass)
+```
+
+Thresholds are configurable. Defaults (0.92 / 0.75) are starting points — calibrate them against a small human-labeled set for your domain. See the accompanying paper for a calibration procedure derived from the deepseek-chat (V3) → deepseek-reasoner (R1) empirical study.
+
+## Installation
+
+```bash
+pip install meridian-regression
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mandavillivijay/meridian
+cd meridian
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+### 1. Build your golden dataset
+
+Create a JSON file with outputs from both models for each prompt:
+
+```json
+[
+  {
+    "prompt": "What is the capital of France?",
+    "intent": "factual",
+    "old_output": "The capital of France is Paris.",
+    "new_output": "Paris is the capital city of France."
+  }
+]
+```
+
+Intent categories: `factual`, `generative`, `classification`, `structured_output`.
+
+Run your old model and new model on the same prompts, save the outputs. MERIDIAN doesn't call any APIs — you bring the outputs.
+
+### 2. Run the pipeline
+
+```python
+from meridian.runner import run
+
+report = run("datasets/my_golden_set.json")
+print(report.summary)
+# "94.0% of outputs are semantically equivalent, 4.0% show minor drift
+#  requiring human review, 2.0% show significant drift (regression flagged)."
+```
+
+### 3. Use the report
+
+```python
+print(f"Equivalent: {report.equivalent_pct}%")
+print(f"Wilson 95% CI: [{report.wilson_lower:.3f}, {report.wilson_upper:.3f}]")
+```
+
+JSON and markdown reports are written to `reports/` automatically.
+
+## Advanced Usage
+
+```python
+from meridian.runner import run
+
+report = run(
+    "datasets/my_golden_set.json",
+    sample_n=50,              # stratified sample of 50 prompts
+    seed=42,                  # reproducible sampling
+    equivalent_threshold=0.90,
+    review_threshold=0.70,
+    report_stem="sonnet_migration_v2",
+)
+```
+
+### Using modules directly
+
+```python
+from meridian.sampler import load, stratified_sample
+from meridian.scorer import DriftScorer
+from meridian.reporter import Reporter
+
+records = load("datasets/my_golden_set.json")
+records = stratified_sample(records, n=50, seed=42)
+
+scorer = DriftScorer()
+results = scorer.score_all(records)
+
+reporter = Reporter()
+report = reporter.build(results)
+reporter.write(report, stem="my_run")
+```
+
+### Bringing your own adapter
+
+If you want to populate outputs programmatically rather than from a JSON file, implement the `ModelAdapter` protocol:
+
+```python
+from meridian.adapters.base import ModelAdapter
+
+class MyAdapter:
+    def complete(self, prompt: str) -> str:
+        # call your model here
+        ...
+    def name(self) -> str:
+        return "my-model-v2"
+```
+
+## Project Structure
+
+```
+meridian/
+├── meridian/
+│   ├── models.py       # Pydantic data models
+│   ├── embedder.py     # Sentence-transformer wrapper (singleton)
+│   ├── scorer.py       # Three-tier drift gate
+│   ├── reporter.py     # Aggregate verdict + JSON/markdown output
+│   ├── sampler.py      # Dataset loading + stratified sampling
+│   ├── runner.py       # End-to-end pipeline entry point
+│   └── adapters/
+│       └── base.py     # ModelAdapter Protocol (extension point)
+├── datasets/           # Example golden datasets
+├── reports/            # Generated reports
+└── tests/              # pytest suite (106 tests)
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Author
+
+Vijay Mandavilli — Quality Engineering Lead, Cognida AI, Hyderabad, India
+
+## License
+
+MIT

meridian_regression-0.1.0/datasets/example.json

@@ -0,0 +1,50 @@
+[
+  {
+    "prompt": "What is the capital of France?",
+    "intent": "factual",
+    "old_output": "The capital of France is Paris.",
+    "new_output": "Paris is the capital city of France."
+  },
+  {
+    "prompt": "What year did World War II end?",
+    "intent": "factual",
+    "old_output": "World War II ended in 1945.",
+    "new_output": "The Second World War ended in 1945."
+  },
+  {
+    "prompt": "Write a short poem about the ocean.",
+    "intent": "generative",
+    "old_output": "Waves crash upon the shore,\nSalt and sea forever more.\nDepths unknown beneath the blue,\nOcean vast and ever true.",
+    "new_output": "The ocean breathes in endless tides,\nA world of wonder where life resides.\nCrashing waves on ancient stone,\nThe sea reminds us we're not alone."
+  },
+  {
+    "prompt": "Write a one-sentence tagline for a coffee brand.",
+    "intent": "generative",
+    "old_output": "Wake up to the world's finest brew.",
+    "new_output": "Start every morning with something extraordinary."
+  },
+  {
+    "prompt": "Is the following review positive or negative? 'The service was slow but the food was amazing.'",
+    "intent": "classification",
+    "old_output": "Mixed — the review contains both a negative sentiment (slow service) and a positive sentiment (amazing food).",
+    "new_output": "This is a mixed review: negative about service speed, positive about food quality."
+  },
+  {
+    "prompt": "Classify the following text as spam or not spam: 'Congratulations! You have won a $1000 gift card. Click here to claim.'",
+    "intent": "classification",
+    "old_output": "Spam",
+    "new_output": "This is spam."
+  },
+  {
+    "prompt": "Extract the name, date, and amount from this invoice text: 'Invoice for John Smith dated 2024-03-15, total $450.00'",
+    "intent": "structured_output",
+    "old_output": "{\"name\": \"John Smith\", \"date\": \"2024-03-15\", \"amount\": \"$450.00\"}",
+    "new_output": "{\"name\": \"John Smith\", \"date\": \"2024-03-15\", \"amount\": 450.00}"
+  },
+  {
+    "prompt": "Return a JSON object with keys 'celsius' and 'fahrenheit' for 100 degrees Celsius.",
+    "intent": "structured_output",
+    "old_output": "{\"celsius\": 100, \"fahrenheit\": 212}",
+    "new_output": "{\"celsius\": 100, \"fahrenheit\": 212.0}"
+  }
+]

meridian_regression-0.1.0/datasets/golden_50_template.json

@@ -0,0 +1,55 @@
+[
+  {"prompt": "What is the capital of Japan?", "intent": "factual"},
+  {"prompt": "In what year did the Berlin Wall fall?", "intent": "factual"},
+  {"prompt": "What is the chemical symbol for gold?", "intent": "factual"},
+  {"prompt": "Who wrote the novel '1984'?", "intent": "factual"},
+  {"prompt": "What is the speed of light in a vacuum, in metres per second?", "intent": "factual"},
+  {"prompt": "How many bones are in the adult human body?", "intent": "factual"},
+  {"prompt": "What is the largest planet in our solar system?", "intent": "factual"},
+  {"prompt": "What is the Pythagorean theorem?", "intent": "factual"},
+  {"prompt": "Who painted the Mona Lisa?", "intent": "factual"},
+  {"prompt": "What does DNA stand for?", "intent": "factual"},
+  {"prompt": "What is the square root of 144?", "intent": "factual"},
+  {"prompt": "Which country has the largest land area in the world?", "intent": "factual"},
+  {"prompt": "What is the boiling point of water at standard atmospheric pressure in Celsius?", "intent": "factual"},
+
+  {"prompt": "Write a two-sentence product description for a noise-cancelling coffee thermos.", "intent": "generative"},
+  {"prompt": "Write a short poem (4 lines) about the feeling of finishing a long project.", "intent": "generative"},
+  {"prompt": "Draft a one-paragraph 'About Us' section for a small bakery in a coastal town.", "intent": "generative"},
+  {"prompt": "Write three bullet points summarising why sleep is important for cognitive performance.", "intent": "generative"},
+  {"prompt": "Write a one-sentence tagline for a fintech app that helps freelancers track invoices.", "intent": "generative"},
+  {"prompt": "Write a polite two-sentence email declining a meeting invitation due to a scheduling conflict.", "intent": "generative"},
+  {"prompt": "Summarise the concept of compound interest in two sentences aimed at a teenager.", "intent": "generative"},
+  {"prompt": "Write a motivational opening line for a data science conference keynote speech.", "intent": "generative"},
+  {"prompt": "Describe the taste of a mango to someone who has never eaten one, in two sentences.", "intent": "generative"},
+  {"prompt": "Write a one-paragraph explanation of what machine learning is for a non-technical business audience.", "intent": "generative"},
+  {"prompt": "Write a three-sentence plot summary for a thriller novel set in a remote Antarctic research station.", "intent": "generative"},
+  {"prompt": "Write a friendly out-of-office auto-reply message for a one-week vacation.", "intent": "generative"},
+
+  {"prompt": "Classify the sentiment of this review as positive, negative, or mixed: 'The hotel room was spotless and the view was stunning, but the checkout process took forever.'", "intent": "classification"},
+  {"prompt": "Is the following email spam or not spam? 'Hi, your package #4821 is ready for collection at the depot. Please bring your ID.'", "intent": "classification"},
+  {"prompt": "Classify the topic of this sentence into one of: technology, sports, politics, or entertainment. 'The new smartphone model features a 200-megapixel camera and a foldable display.'", "intent": "classification"},
+  {"prompt": "Is this customer message a complaint, a question, or a compliment? 'I have been waiting three weeks for my refund and nobody is responding to my emails.'", "intent": "classification"},
+  {"prompt": "Classify the urgency of this support ticket as high, medium, or low: 'Our production database is returning errors and the entire platform is down for all users.'", "intent": "classification"},
+  {"prompt": "Classify the sentiment of this tweet as positive, negative, or neutral: 'Just landed in Seoul. The airport is massive but the signage is surprisingly clear.'", "intent": "classification"},
+  {"prompt": "Is the following statement a fact or an opinion? 'Electric vehicles produce zero direct emissions during operation.'", "intent": "classification"},
+  {"prompt": "Classify this job title into one of: engineering, marketing, finance, or operations. 'Growth Hacker'", "intent": "classification"},
+  {"prompt": "Is the following code comment helpful or unhelpful? '# increment i by 1'", "intent": "classification"},
+  {"prompt": "Classify the following question as open-ended or closed-ended: 'What do you think the biggest challenge in AI safety is?'", "intent": "classification"},
+  {"prompt": "Classify the reading level of this sentence as elementary, intermediate, or advanced: 'The mitochondria are the organelles responsible for cellular respiration and ATP synthesis.'", "intent": "classification"},
+  {"prompt": "Is this news headline clickbait or not clickbait? 'Scientists discover new species of deep-sea fish near hydrothermal vents in the Pacific.'", "intent": "classification"},
+
+  {"prompt": "Extract the following fields as a JSON object from this text: name, company, and email. Text: 'Please reach out to Sarah Chen at Vertex Labs — her email is schen@vertexlabs.io'", "intent": "structured_output"},
+  {"prompt": "Return a JSON object with keys 'fahrenheit' and 'celsius' for a temperature of 98.6 degrees Fahrenheit.", "intent": "structured_output"},
+  {"prompt": "Parse the following address into a JSON object with keys: street, city, state, zip. Address: '742 Evergreen Terrace, Springfield, IL 62701'", "intent": "structured_output"},
+  {"prompt": "Extract all action items from this meeting note as a JSON array of strings. Note: 'Alice will update the roadmap by Friday. Bob needs to send the budget proposal. The team should review the new designs before Thursday.'", "intent": "structured_output"},
+  {"prompt": "Convert this sentence into a JSON object with keys 'subject', 'verb', 'object': 'The engineer deployed the service.'", "intent": "structured_output"},
+  {"prompt": "Return a JSON array listing the ingredients mentioned in this recipe snippet: 'Combine two cups of flour, one egg, half a cup of sugar, and a teaspoon of vanilla extract in a bowl.'", "intent": "structured_output"},
+  {"prompt": "Extract the event details from this text as a JSON object with keys: event_name, date, location. Text: 'Join us for the Annual Tech Summit on 15 September 2025 at the Grand Hyatt, San Francisco.'", "intent": "structured_output"},
+  {"prompt": "Return a JSON object with keys 'principal', 'rate', 'years', 'final_amount' for this scenario: $5000 invested at 6% annual interest for 10 years with annual compounding.", "intent": "structured_output"},
+  {"prompt": "Parse this log line into a JSON object with keys: timestamp, level, message. Log: '[2024-11-03 14:22:01] ERROR: Database connection timeout after 30s'", "intent": "structured_output"},
+  {"prompt": "Return a JSON object representing this person's details: 'Dr. Priya Nair, aged 41, works as a cardiologist at Apollo Hospital in Chennai.'", "intent": "structured_output"},
+  {"prompt": "Extract all dates mentioned in this paragraph as a JSON array in ISO 8601 format. Text: 'The contract was signed on March 3rd 2023, with a review scheduled for June 15 2023 and final delivery on 1 December 2023.'", "intent": "structured_output"},
+  {"prompt": "Return a JSON object summarising this product review with keys: rating (1-5), pros (array), cons (array). Review: 'Great battery life and the camera is exceptional. However, it runs hot during gaming and the charger is sold separately. I'd give it a 4 out of 5.'", "intent": "structured_output"},
+  {"prompt": "Convert this table row into a JSON object with keys: employee_id, name, department, salary. Row: '1042 | Arjun Mehta | Engineering | 95000'", "intent": "structured_output"}
+]

meridian_regression-0.1.0/meridian/__init__.py

@@ -0,0 +1,26 @@
+from meridian.runner import run
+from meridian.scorer import DriftScorer
+from meridian.reporter import Reporter
+from meridian.sampler import load, stratified_sample
+from meridian.embedder import Embedder
+from meridian.models import (
+    PromptRecord,
+    DriftResult,
+    EquivalenceReport,
+    IntentCategory,
+    TierVerdict,
+)
+
+__all__ = [
+    "run",
+    "DriftScorer",
+    "Reporter",
+    "load",
+    "stratified_sample",
+    "Embedder",
+    "PromptRecord",
+    "DriftResult",
+    "EquivalenceReport",
+    "IntentCategory",
+    "TierVerdict",
+]

meridian_regression-0.1.0/meridian/adapters/base.py

@@ -0,0 +1,17 @@
+"""
+ModelAdapter Protocol — extension point for users who want to call a live model
+during dataset construction rather than loading pre-populated JSON.
+
+MERIDIAN itself does not depend on any LLM SDK. If you want to wire up a model,
+implement this Protocol and pass it to DatasetSampler.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ModelAdapter(Protocol):
+    def complete(self, prompt: str) -> str: ...
+    def name(self) -> str: ...

meridian_regression-0.1.0/meridian/embedder.py

@@ -0,0 +1,51 @@
+"""
+Local sentence-transformer embedder.
+
+Runs entirely on-device — no API calls, no cloud dependency. This is a deliberate
+design choice: unlike LLM-as-judge migration validators, MERIDIAN's scoring step
+is free, fast, and deterministic.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+_DEFAULT_MODEL = "all-MiniLM-L6-v2"
+
+# Module-level cache: one loaded model per model name per process.
+_instances: dict[str, "Embedder"] = {}
+
+
+class Embedder:
+    """Singleton-per-model-name wrapper around SentenceTransformer."""
+
+    def __new__(cls, model_name: str = _DEFAULT_MODEL) -> "Embedder":
+        if model_name not in _instances:
+            instance = super().__new__(cls)
+            instance._model_name = model_name
+            instance._model = SentenceTransformer(model_name)
+            _instances[model_name] = instance
+        return _instances[model_name]
+
+    def embed(self, text: Union[str, list[str]]) -> np.ndarray:
+        """Return L2-normalised embeddings as a float32 numpy array.
+
+        Single string → shape (dim,). List of strings → shape (n, dim).
+        """
+        single = isinstance(text, str)
+        inputs = [text] if single else text
+        if not inputs:
+            return np.empty((0, self.embedding_dim), dtype=np.float32)
+        vectors = self._model.encode(inputs, normalize_embeddings=True, convert_to_numpy=True)
+        return vectors[0] if single else vectors
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+    @property
+    def embedding_dim(self) -> int:
+        return self._model.get_sentence_embedding_dimension()