dataforge-07-evals 0.1.0__py3-none-any.whl

dataforge_07_evals-0.1.0.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: dataforge_07_evals
+Version: 0.1.0
+Summary: Agent-agnostic evaluation harness for data-quality repair agents.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Aegis15/dataforge
+Project-URL: Repository, https://github.com/Aegis15/dataforge
+Project-URL: Documentation, https://dataforge.praneshrajan15.workers.dev/playground
+Keywords: data-quality,evaluation,agents,benchmarks,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas>=2.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tenacity>=8.3
+Requires-Dist: typer>=0.12
+Provides-Extra: dataforge
+Requires-Dist: dataforge_07>=0.1.0; extra == "dataforge"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pandas-stubs>=2.2; extra == "dev"
+Provides-Extra: all
+Requires-Dist: dataforge_07_evals[dataforge,dev]; extra == "all"
+Provides-Extra: hf
+Requires-Dist: transformers>=4.44; extra == "hf"
+Requires-Dist: torch>=2.3; extra == "hf"
+Requires-Dist: accelerate>=0.33; extra == "hf"
+
+# dataforge-evals
+
+`dataforge-evals` is an agent-agnostic evaluation harness for data-quality repair agents.
+
+It gives any agent the same task, accepts only proposed cell fixes, and lets the grader compute exact precision, recall, F1, steps, failures, and free-tier quota usage. The harness can load DataForge's canonical Hospital, Flights, and Beers benchmark tasks when `dataforge_07` is installed, while the import namespace remains `dataforge` for the 0.1 line.
+The PyPI package is not published yet; use the source install instructions
+below until release ownership is configured.
+
+```bash
+pip install -e ".[dev]"
+dataforge-evals run --agent mock --dataset synthetic --trials 3
+```
+
+## Install
+
+### From source (development)
+
+```bash
+python -m venv .venv
+# Linux/macOS:
+source .venv/bin/activate
+# Windows PowerShell:
+.\.venv\Scripts\Activate.ps1
+
+pip install -e ".[dev]"
+```
+
+### With canonical DataForge datasets
+
+```bash
+pip install -e "../data_quality_env"
+dataforge-evals run --agent mock --dataset hospital --trials 3
+```
+
+## Run a provider
+
+```bash
+set GROQ_API_KEY=...
+dataforge-evals run --agent groq-llama-70b --dataset hospital --trials 3 --output reports/groq-hospital.md
+```
+
+### Bounded Groq smoke test
+
+Use a single synthetic trial to verify Groq wiring without turning the smoke
+check into a benchmark:
+
+```bash
+dataforge-evals run --agent groq-llama-70b --dataset synthetic --trials 1 --seed 0 --timeout-s 20 --output reports/groq-synthetic-smoke.md --output-json reports/groq-synthetic-smoke.json
+```
+
+For this smoke path, `trials_completed=1` and `Failures=none` prove the
+integration completed successfully. F1 is a quality signal for the model's
+proposed repairs, not the API health check. The JSON report includes the
+normalized proposed `fixes` for debugging; Markdown stays summary-only.
+
+### Built-in adapters
+
+| Agent ID | Provider | Required Setup |
+| --- | --- | --- |
+| `mock` | local deterministic oracle for tests | none |
+| `groq-llama-70b` | Groq | `GROQ_API_KEY` |
+| `gemini-flash` | Gemini | `GEMINI_API_KEY` |
+| `cerebras-llama` | Cerebras | `CEREBRAS_API_KEY` |
+| `openrouter` | OpenRouter | `OPENROUTER_API_KEY` |
+| `local-ollama` | local Ollama OpenAI-compatible endpoint | Ollama server on `localhost:11434` |
+| `hf-local` | Hugging Face Transformers | optional `HF_TOKEN`; install `.[hf]` |
+
+### Evaluating the historical DataForge SFT checkpoint
+
+Use `hf-local` for base-vs-SFT checks with the same exact-match grader used by
+hosted providers:
+
+```bash
+pip install -e ".[hf]"
+dataforge-evals run --agent hf-local --dataset synthetic --trials 1 \
+  --model-id Praneshrajan15/DataForge-0.5B-SFT \
+  --output reports/dataforge-sft-smoke.md \
+  --output-json reports/dataforge-sft-smoke.json
+```
+
+If `--model-id` is omitted, the adapter uses `DATAFORGE_EVAL_MODEL`, then the
+authenticated `HF_TOKEN` user's `DataForge-0.5B-SFT`, then
+`Praneshrajan15/DataForge-0.5B-SFT`.
+
+### Discover agents and datasets
+
+```bash
+dataforge-evals list-agents
+dataforge-evals list-datasets
+```
+
+## Custom CSV-pair evaluation
+
+Bring your own dirty and clean CSV files:
+
+```bash
+dataforge-evals run --agent mock --dataset my-data \
+    --dirty-csv path/to/dirty.csv \
+    --clean-csv path/to/clean.csv \
+    --trials 3
+```
+
+The dirty and clean CSVs must have the same number of rows and columns. Column names are taken from the clean file.
+
+## Agent protocol
+
+Any agent can plug in by implementing:
+
+```python
+from dataforge_evals import AgentTask, Fix
+
+class MyAgent:
+    name = "my-agent"
+
+    def run(self, task: AgentTask) -> list[Fix]:
+        return [Fix(row=0, column="Score", new_value="4.5", reason="example")]
+```
+
+Agents never report their own score. They return candidate fixes only. The grader is the only source of truth.
+Normal agents receive a label-hidden `AgentTask`; only the built-in `mock`
+oracle used by tests is marked to receive full ground truth.
+
+### What agents receive
+
+- `task.name` — dataset identifier
+- `task.dirty_df` — pandas DataFrame with data-quality issues (all values as strings)
+- `task.canonical_columns` — ordered column names from the clean reference
+- `task.metadata` — provenance and descriptive metadata
+
+### What agents return
+
+Either a `list[Fix]` or an `AgentRunResult` with usage accounting:
+
+```python
+from dataforge_evals import AgentRunResult, Fix, Usage
+
+return AgentRunResult(
+    fixes=[Fix(row=0, column="Score", new_value="4.5")],
+    usage=Usage(calls=1, prompt_tokens=500, completion_tokens=100, quota_units=0.001),
+    steps=1,
+    model="my-model-v1",
+)
+```
+
+## What is graded
+
+A `Fix` is correct only when `(row, column, new_value)` exactly matches a ground-truth dirty-to-clean cell correction. Duplicate predictions for the same cell use last-write-wins normalization. A wrong value on the right cell counts as both a false positive and a false negative.
+
+## Quota accounting
+
+Each report uses provider-normalized free-tier quota units rather than dollars. Built-in adapters record raw calls, prompt tokens, completion tokens, and quota units.
+
+Provider-specific normalization (as of 2026-05-01):
+
+| Provider | Free-tier basis | 1 quota unit = |
+| --- | --- | --- |
+| Groq | 14,400 RPD | 1 request |
+| Gemini | 1,500 RPD | 1 request |
+| Cerebras | 1,000 RPD | 1 request |
+| OpenRouter | Nominal 1,000 RPD | 1 request |
+| Ollama | unlimited (local) | always 0 |
+
+On HTTP 429, the adapter waits with exponential backoff and logs `waiting N seconds for quota reset` to stderr. It does not fall back to another provider because fallback would contaminate the comparison.
+
+## Reproducibility
+
+Each report records:
+
+- `dataforge-evals` commit hash
+- `dataforge` source commit hash when canonical datasets are loaded through DataForge
+- exact seeds
+- provider model identifiers
+- UTC run date
+- dependency versions (pandas, pydantic, httpx, etc.)
+- an explicit nondeterminism note
+
+Deterministic and mock agents reproduce exactly from the recorded seeds. Hosted LLM providers may still change outputs because providers can update model weights, routing, safety systems, or tokenization without notice.
+
+### Reproducibility limitations
+
+- Provider model identifiers (e.g., `llama-3.3-70b-versatile`) may point to different weights on different dates.
+- Token counts and quota units depend on provider-side tokenization, which can change.
+- Network latency, rate limiting, and provider availability affect runtime measurements.
+- Temperature 0 does not guarantee determinism across all providers.
+
+## Not a leaderboard by default
+
+Only compare reports when dataset versions, seeds, provider model identifiers, run date, and prompt/adapter code are identical. Otherwise the report is an evaluation artifact, not a leaderboard row.
+
+## When dataforge-evals is the wrong tool
+
+Do not use `dataforge-evals` if:
+
+- **Your agent operates on streaming data** — the harness is batch-oriented and expects a complete dirty DataFrame.
+- **You need end-to-end pipeline evaluation** — this tool evaluates cell-level repair accuracy, not detection, diagnosis, or pipeline orchestration.
+- **Your ground truth is fuzzy or approximate** — the grader uses exact string match. If multiple correct values exist for a cell, you need a custom grader.
+- **You need sub-second latency benchmarking** — the harness measures wall-clock time but is not designed as a latency benchmarking tool.
+- **Your data is > 100K rows** — the harness loads the full DataFrame into memory and passes it to agents. For large-scale evaluation, sample first.
+
+## Development
+
+```bash
+make setup     # pip install -e ".[dev]"
+make lint      # ruff check
+make format    # ruff format --check
+make type      # mypy --strict
+make test      # pytest
+make test-cov  # pytest with coverage
+make smoke     # end-to-end smoke test with mock agent
+```
+
+## Environment Variables
+
+Provider keys belong in a root `.env` file (gitignored) loaded with `python-dotenv`:
+
+- `GROQ_API_KEY`
+- `GEMINI_API_KEY`
+- `CEREBRAS_API_KEY`
+- `OPENROUTER_API_KEY`
+
+## License
+
+Apache-2.0.

dataforge_07_evals-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+dataforge_evals/__init__.py,sha256=DnQGiVeXrBPvnOimCab6KxHirNsqu2iqd-wN1xQzI-g,844
+dataforge_evals/cli.py,sha256=A2GwU2Du0N5q3VWHwZ2YM5l5g424HnzpNSFTD8o_jEY,11078
+dataforge_evals/grader.py,sha256=0tsvXhTIMBBSKnxfgjfHbkaiNaS4aai2mHbN5aocwuI,5241
+dataforge_evals/harness.py,sha256=Fb3rLgh5U-aIJnqcmdSPTgRjJqQYJvpPuvhW--e8lqk,14597
+dataforge_evals/py.typed,sha256=umvyuNnMuIqk4trirUMN2k3zkXXle1csrUNb-H4-iog,65
+dataforge_evals/repair_contract.py,sha256=-6g-5fiRKHwZDIQ_cYMiWWXzEGM0lNTteb7oFM-agdw,11598
+dataforge_evals/report.py,sha256=-0VnQgRVy_-dEJeeJBq84YUaHNDuHUS0OIBAqnjfNhk,6469
+dataforge_evals/tasks.py,sha256=AYPbxonDqJ5_-Yw1zQHomd9DAKrmd3RW5pRHWCKSj0Q,9310
+dataforge_evals/agents/__init__.py,sha256=rbuME8zQrlMQsHdpUrqUthtAI-DZZPax_OkXKQT8RKw,412
+dataforge_evals/agents/base.py,sha256=SoTmJFL99M0CWN_YaexAtAJlGP0iuSRT437-jm7_IUk,7600
+dataforge_evals/agents/cerebras_llama.py,sha256=_DDwT6Gd9OXwtRXovdmpZMh4DHLUV2EtekZl7rMHOn8,2268
+dataforge_evals/agents/gemini_flash.py,sha256=gBAJijxL58U3qhWXxAcHlcPGw_xR4l5mC0xfCh4ITgk,5965
+dataforge_evals/agents/groq_llama.py,sha256=IBeomteTaPgkZ46iZO2YKSW9SE8Ki0mnmvD8OMPM7LQ,2287
+dataforge_evals/agents/hf_local.py,sha256=lPXbkduG4G5VJIVQ64haMWDy32BqHdtJbS7Z1E9deSk,8326
+dataforge_evals/agents/local_ollama.py,sha256=5JDTYQ5fRWyp5fKkHqhv8TLmvPt5K-9bPcjYBxLxj-U,2008
+dataforge_evals/agents/mock.py,sha256=GlsYdpHUyhN6zGnjIOshUpPogJCE_hhfvk3MRMHRxFE,1400
+dataforge_evals/agents/openrouter.py,sha256=iTY-AH-i3HW9pPjfzcze2CW1ufZ4Z1T0hT7pnVqRw8s,2290
+dataforge_evals/agents/provider_base.py,sha256=1W9WLjjIsQJ7HkBI_y0AbYdKRpKnPjkVe2zfDPGTZPQ,11643
+dataforge_07_evals-0.1.0.dist-info/METADATA,sha256=MAxqSo-z3jaYC2RJYT6sjpCwB9fnx_TEuFPs8HIuzrA,9669
+dataforge_07_evals-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dataforge_07_evals-0.1.0.dist-info/entry_points.txt,sha256=-sylQUAkVa_SrzMCztTHJcPqBm1934IBt70N0lOnZ7w,104
+dataforge_07_evals-0.1.0.dist-info/top_level.txt,sha256=3e16aDQIlTzh-A41CGEfnIy3up3eNtOM7EGWuV0pEdM,16
+dataforge_07_evals-0.1.0.dist-info/RECORD,,

dataforge_07_evals-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dataforge_07_evals-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dataforge-evals = dataforge_evals.cli:app
+dataforge15-evals = dataforge_evals.cli:app

dataforge_07_evals-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dataforge_evals

dataforge_evals/__init__.py

@@ -0,0 +1,37 @@
+"""dataforge-evals: agent-agnostic evaluation harness for data-quality repair agents."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from dataforge_evals.agents.base import (
+    Agent,
+    AgentRunResult,
+    AgentTask,
+    Fix,
+    GroundTruthCell,
+    Task,
+    Usage,
+)
+from dataforge_evals.grader import Grade
+
+for _distribution_name in ("dataforge_07_evals", "dataforge-evals", "dataforge15-evals"):
+    try:
+        __version__: str = version(_distribution_name)
+        break
+    except PackageNotFoundError:
+        continue
+else:  # pragma: no cover - editable install normally has metadata
+    __version__ = "0.0.0-dev"
+
+__all__ = [
+    "Agent",
+    "AgentRunResult",
+    "AgentTask",
+    "Fix",
+    "Grade",
+    "GroundTruthCell",
+    "Task",
+    "Usage",
+    "__version__",
+]

dataforge_evals/agents/__init__.py

@@ -0,0 +1,23 @@
+"""Agent adapter re-exports for the dataforge-evals public API."""
+
+from dataforge_evals.agents.base import (
+    Agent,
+    AgentRunResult,
+    AgentTask,
+    Fix,
+    GroundTruthCell,
+    Task,
+    Usage,
+)
+from dataforge_evals.agents.hf_local import HfLocalAgent
+
+__all__ = [
+    "Agent",
+    "AgentRunResult",
+    "AgentTask",
+    "Fix",
+    "GroundTruthCell",
+    "HfLocalAgent",
+    "Task",
+    "Usage",
+]

dataforge_evals/agents/base.py

@@ -0,0 +1,208 @@
+"""Public data models and agent protocol for dataforge-evals.
+
+This module defines the stable public contract that every agent adapter,
+the grader, the harness, and external consumers depend on. Changes to
+these types require a spec update and version bump.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+import pandas as pd
+from pydantic import BaseModel, Field
+
+InferabilityLabel = Literal[
+    "deterministic_normalization",
+    "context_derivable",
+    "external_reference_required",
+    "not_inferable_from_prompt",
+]
+
+
+class Fix(BaseModel):
+    """One proposed cell repair emitted by an agent.
+
+    A fix identifies a single cell by ``(row, column)`` and proposes
+    ``new_value`` as the corrected content. The ``reason`` field is for
+    human audit and observability — it is never used for scoring.
+
+    Attributes:
+        row: Zero-based row index in the dirty DataFrame.
+        column: Column name in the canonical column set.
+        new_value: Proposed corrected cell value as a string.
+        reason: Human-readable rationale for the repair proposal.
+    """
+
+    row: int = Field(ge=0, description="Zero-based row index in the dirty DataFrame.")
+    column: str = Field(min_length=1, description="Column name in the canonical column set.")
+    new_value: str = Field(description="Proposed corrected cell value as a string.")
+    reason: str = Field(
+        default="agent proposal",
+        min_length=1,
+        description="Human-readable rationale for the repair proposal.",
+    )
+
+    model_config = {"frozen": True}
+
+    def __repr__(self) -> str:
+        return f"Fix(row={self.row}, column={self.column!r}, new_value={self.new_value!r})"
+
+
+class GroundTruthCell(BaseModel):
+    """One canonical dirty-to-clean cell correction used for grading.
+
+    Ground-truth cells are computed from aligned dirty/clean DataFrames
+    and represent the authoritative answer the grader scores against.
+
+    Attributes:
+        row: Zero-based row index in the aligned DataFrames.
+        column: Column name from the canonical (clean) column set.
+        dirty_value: The original incorrect cell content.
+        clean_value: The authoritative corrected cell content.
+    """
+
+    row: int = Field(ge=0, description="Zero-based row index.")
+    column: str = Field(min_length=1, description="Canonical column name.")
+    dirty_value: str = Field(description="Original incorrect cell content.")
+    clean_value: str = Field(description="Authoritative corrected cell content.")
+
+    model_config = {"frozen": True}
+
+    def __repr__(self) -> str:
+        return (
+            f"GroundTruthCell(row={self.row}, column={self.column!r}, "
+            f"dirty={self.dirty_value!r} -> clean={self.clean_value!r})"
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class AgentTask:
+    """A label-hidden data-quality repair task passed to normal agents.
+
+    This is the public runtime view of an evaluation task. It deliberately
+    omits ground-truth labels; the harness keeps labels separately for grading.
+
+    Attributes:
+        name: Human-readable task identifier (e.g. ``"hospital"``).
+        dirty_df: The DataFrame containing data-quality issues.
+        canonical_columns: Ordered column names from the clean reference.
+        metadata: Provenance and descriptive metadata for reporting.
+    """
+
+    name: str
+    dirty_df: pd.DataFrame
+    canonical_columns: tuple[str, ...]
+    metadata: dict[str, str | int | float | tuple[str, ...]]
+    inferability: InferabilityLabel = "deterministic_normalization"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Task(AgentTask):
+    """Full grading task retained inside the harness and oracle tests only.
+
+    Normal agents receive ``AgentTask``. Only adapters explicitly marked with
+    ``uses_ground_truth = True`` receive this full task.
+    """
+
+    ground_truth: tuple[GroundTruthCell, ...]
+
+
+class Usage(BaseModel):
+    """Provider usage accounting for one agent run.
+
+    Tracks raw API call counts, token consumption, and a provider-normalized
+    free-tier quota fraction. The ``quota_units`` field represents a
+    fraction of the provider's free-tier allocation consumed, enabling
+    cross-provider cost comparison on a common scale.
+
+    Attributes:
+        calls: Number of HTTP requests made to the provider.
+        prompt_tokens: Total prompt/input tokens consumed.
+        completion_tokens: Total completion/output tokens consumed.
+        quota_units: Provider-normalized free-tier fraction consumed.
+    """
+
+    calls: int = Field(default=0, ge=0, description="Number of HTTP requests made.")
+    prompt_tokens: int = Field(default=0, ge=0, description="Total prompt/input tokens.")
+    completion_tokens: int = Field(default=0, ge=0, description="Total completion/output tokens.")
+    quota_units: float = Field(
+        default=0.0, ge=0.0, description="Provider-normalized quota fraction."
+    )
+
+    model_config = {"frozen": True}
+
+    def __repr__(self) -> str:
+        return (
+            f"Usage(calls={self.calls}, prompt={self.prompt_tokens}, "
+            f"completion={self.completion_tokens}, quota={self.quota_units:.4f})"
+        )
+
+    def __add__(self, other: Usage) -> Usage:
+        """Accumulate usage across multiple API calls within a single run.
+
+        Args:
+            other: Another Usage instance to merge.
+
+        Returns:
+            A new Usage with summed fields.
+        """
+        return Usage(
+            calls=self.calls + other.calls,
+            prompt_tokens=self.prompt_tokens + other.prompt_tokens,
+            completion_tokens=self.completion_tokens + other.completion_tokens,
+            quota_units=round(self.quota_units + other.quota_units, 4),
+        )
+
+
+class AgentRunResult(BaseModel):
+    """Normalized result returned by built-in adapters.
+
+    Wraps the agent's proposed fixes alongside usage accounting,
+    step count, and optional model identification for reproducibility.
+
+    Attributes:
+        fixes: Ordered list of proposed cell repairs.
+        usage: Provider usage accounting for this run.
+        steps: Number of reasoning steps the agent performed.
+        model: Provider model identifier for reproducibility.
+        warnings: Non-fatal diagnostic messages from the adapter.
+    """
+
+    fixes: list[Fix]
+    usage: Usage = Field(default_factory=Usage)
+    steps: int = Field(default=1, ge=0, description="Reasoning steps performed.")
+    model: str | None = Field(default=None, description="Provider model identifier.")
+    warnings: list[str] = Field(default_factory=list)
+
+
+@runtime_checkable
+class Agent(Protocol):
+    """Protocol implemented by every data-quality repair agent adapter.
+
+    Any object with a ``name`` attribute and a ``run`` method matching
+    this signature can be used as an agent in the evaluation harness.
+    The agent receives a ``Task`` and returns proposed ``Fix`` objects.
+    Agents must never set their own metrics — the grader is the sole
+    source of truth.
+
+    Example:
+        >>> class MyAgent:
+        ...     name = "my-agent"
+        ...     def run(self, task: Task) -> list[Fix]:
+        ...         return [Fix(row=0, column="Score", new_value="4.5")]
+    """
+
+    name: str
+
+    def run(self, task: AgentTask) -> list[Fix] | AgentRunResult:
+        """Run the agent on a task and return proposed fixes.
+
+        Args:
+            task: The data-quality repair task to evaluate.
+
+        Returns:
+            A list of Fix objects or an AgentRunResult with usage accounting.
+        """
+        ...

dataforge_evals/agents/cerebras_llama.py

@@ -0,0 +1,65 @@
+"""Cerebras-hosted Llama adapter for data-quality repair evaluation.
+
+Cerebras free tier (as of 2026-05-01): 30 RPM, 1,000 RPD on Llama 3.1 70B.
+Quota unit = fraction of the daily request allocation consumed per API call.
+"""
+
+from __future__ import annotations
+
+from dataforge_evals.agents.provider_base import ChatProviderAgent
+
+# Cerebras free-tier daily request limit (as of 2026-05-01).
+_CEREBRAS_FREE_DAILY_REQUESTS = 1_000
+
+
+class CerebrasLlamaAgent(ChatProviderAgent):
+    """Cerebras-hosted Llama adapter for data-quality repair evaluation.
+
+    Uses the Cerebras OpenAI-compatible endpoint with Llama 3.1 70B.
+    Quota units are normalized against the free-tier daily request allocation.
+
+    Attributes:
+        name: CLI identifier ``"cerebras-llama"``.
+        provider: ``"cerebras"``.
+    """
+
+    name = "cerebras-llama"
+    provider = "cerebras"
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        model: str = "llama3.1-70b",
+        http_timeout_s: float = 15.0,
+    ) -> None:
+        """Initialize the Cerebras adapter.
+
+        Args:
+            api_key: Cerebras API key (``CEREBRAS_API_KEY``).
+            model: Cerebras model identifier.
+            http_timeout_s: Per-request HTTP timeout in seconds.
+        """
+        super().__init__(api_key=api_key, model=model, http_timeout_s=http_timeout_s)
+
+    @property
+    def endpoint(self) -> str:
+        """Return the Cerebras OpenAI-compatible endpoint."""
+        return "https://api.cerebras.ai/v1/chat/completions"
+
+    def headers(self) -> dict[str, str]:
+        """Return Cerebras authorization headers."""
+        return {"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"}
+
+    def quota_units(self, *, calls: int, prompt_tokens: int, completion_tokens: int) -> float:
+        """Cerebras quota: fraction of daily request allocation.
+
+        Args:
+            calls: Number of HTTP requests made.
+            prompt_tokens: Prompt tokens (tracked but not primary quota dimension).
+            completion_tokens: Completion tokens (tracked but not primary quota dimension).
+
+        Returns:
+            Fraction of free-tier daily request quota consumed.
+        """
+        return round(calls / _CEREBRAS_FREE_DAILY_REQUESTS, 6)