lims-data-quality 0.1.0__py3-none-any.whl

lims_data_quality-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: lims-data-quality
+Version: 0.1.0
+Summary: Validate lab/LIMS data files before they hit your pipeline
+Author: Sri Gorantla
+License: MIT
+Project-URL: Homepage, https://github.com/sriranga13/lims-data-quality
+Keywords: lims,lab,data-quality,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: openpyxl>=3.1
+Dynamic: license-file
+
+# lims-data-quality
+
+Validate lab/LIMS data files before they hit your pipeline — schema checks, row-level error reports, audit trails.
+
+`lims-dq` checks CSV/Excel exports against a JSON schema (required columns, dtypes, ranges, regex ID patterns, allowed values) and tells you exactly which row, which column, and why it failed. Every run can append a tamper-evident audit entry (timestamp, file hash, rule set version, pass/fail counts) — a nod to 21 CFR Part 11 style traceability.
+
+## Install
+
+```bash
+pip install lims-data-quality
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/sriranga13/lims-data-quality.git
+cd lims-data-quality
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+1. Describe your file with a schema (`schema.json`):
+
+```json
+{
+  "name": "lims-export",
+  "version": "1.0.0",
+  "columns": {
+    "sample_id":     { "dtype": "string", "required": true, "pattern": "^SMP-[0-9]{6}$" },
+    "concentration": { "dtype": "float",  "required": true, "min": 0.0, "max": 100.0 },
+    "unit":          { "dtype": "string", "required": true, "allowed": ["mg/L", "ug/mL", "ng/uL"] },
+    "analyzed_at":   { "dtype": "date",   "required": false },
+    "replicates":    { "dtype": "int",    "required": false, "min": 1, "max": 12 }
+  }
+}
+```
+
+2. Validate:
+
+```bash
+lims-dq validate samples.csv --schema schema.json
+```
+
+Sample output:
+
+```
+lims-dq report: samples.csv
+ruleset: lims-export v1.0.0
+rows checked: 5 | passed: 3 | failed: 2 | errors: 7
+
+  row  column             rule               message
+------------------------------------------------------------------------
+    4  analyzed_at        dtype              'not-a-date' is not a recognizable date
+    4  concentration      constraint         '150.0' is above maximum 100.0
+    4  replicates         constraint         '0' is below minimum 1
+    4  sample_id          constraint         'BAD-ID' does not match pattern '^SMP-[0-9]{6}$'
+    4  unit               constraint         'kg' is not one of ['mg/L', 'ug/mL', 'ng/uL']
+    5  concentration      required           required value is missing
+    5  replicates         constraint         '13' is above maximum 12
+```
+
+3. Machine-readable report and audit trail:
+
+```bash
+lims-dq validate samples.csv --schema schema.json \
+    --report report.json \
+    --audit-log audit.jsonl
+```
+
+- `--report` writes the full report (summary counts + every error) as JSON.
+- `--audit-log` appends one JSON-lines entry per run: UTC timestamp, SHA-256 of the input file, rule set name/version, rows checked/passed/failed, error count. Re-running against a modified file produces a different hash, so entries are tamper-evident.
+
+Exit codes: `0` = all rows pass, `1` = validation failures, `2` = usage/file errors.
+
+## Schema reference
+
+| Key        | Applies to        | Meaning                                          |
+|------------|-------------------|--------------------------------------------------|
+| `dtype`    | all               | `string`, `int`, `float`, or `date`              |
+| `required` | all               | missing values fail (missing column fails too)   |
+| `pattern`  | all               | regex the full value must match                  |
+| `min`/`max`| `int`, `float`    | inclusive numeric bounds                          |
+| `allowed`  | all               | value must be one of the listed strings          |
+
+Columns present in the file but absent from the schema are flagged as `unexpected_column` errors unless you pass `--no-strict`.
+
+## Use as a library
+
+```python
+from lims_dq import load_schema, validate_dataframe, ErrorReport
+
+ruleset = load_schema("schema.json")
+import pandas as pd
+df = pd.read_csv("samples.csv", dtype=str)
+errors = validate_dataframe(df, ruleset)
+report = ErrorReport("samples.csv", ruleset.name, ruleset.version, len(df), errors)
+print(report.to_text())   # or report.to_json()
+```
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e . && pip install pytest
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lims_data_quality-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lims_data_quality-0.1.0.dist-info/licenses/LICENSE,sha256=4J9t3O8u6I-R7Iit0ZN6GP_3B7FiCHqA0EjHF9psjZQ,1069
+lims_dq/__init__.py,sha256=UHE7KQZYlGG8vMIriyuiM661EGphK0sgwTxRoVn2qF8,527
+lims_dq/audit.py,sha256=JhXekTK8HnqWBiYFg19WDORpiFy5fj7l6rJnkMpEt2Q,2533
+lims_dq/cli.py,sha256=oC-3ykihNwTulhoUNjC0ONz5YIv7SA9MjB1aw-C0xC0,3993
+lims_dq/report.py,sha256=hEl9sVuQX5FzMMx5WnkJ9Z9wpayoj72oRkH9mk0vPv0,2704
+lims_dq/schema.py,sha256=p6t31egUJ7_qQmCsAxX6g2erVL-3nf2HhHXIA7SSwqk,4616
+lims_dq/validators.py,sha256=ghP9zMjvk94Fijlqlh8EH9HNAThgjh4usCx5ARwuUgg,5284
+lims_data_quality-0.1.0.dist-info/METADATA,sha256=3yQVNwyTDEdA7U-YMOmszW3epWZUB1X4Dh2WO0u34PE,4683
+lims_data_quality-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+lims_data_quality-0.1.0.dist-info/entry_points.txt,sha256=Eje_pmk5RNACBYdtHsq1SsiMI0GIBEoST8K2OrJKMGQ,45
+lims_data_quality-0.1.0.dist-info/top_level.txt,sha256=MGHywZMUvDpSpvKF21_nI5ya8sBkrjznRwwaJFaf9Oc,8
+lims_data_quality-0.1.0.dist-info/RECORD,,

lims_data_quality-0.1.0.dist-info/WHEEL

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

lims_data_quality-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lims-dq = lims_dq.cli:main

lims_data_quality-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sri Gorantla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lims_data_quality-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lims_dq

lims_dq/__init__.py

@@ -0,0 +1,21 @@
+"""lims-dq: validate lab/LIMS data files before they enter your pipeline."""
+
+from .audit import AuditEntry, read_audit_log, write_audit_log
+from .report import ErrorReport, ValidationError
+from .schema import Rule, RuleSet, SchemaError, load_schema
+from .validators import validate_dataframe
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuditEntry",
+    "ErrorReport",
+    "Rule",
+    "RuleSet",
+    "SchemaError",
+    "ValidationError",
+    "load_schema",
+    "read_audit_log",
+    "validate_dataframe",
+    "write_audit_log",
+]

lims_dq/audit.py

@@ -0,0 +1,88 @@
+"""Minimal audit trail: who validated what, when, against which rules.
+
+Each validation run appends one JSON-lines entry recording the UTC
+timestamp, the SHA-256 hash of the input file, the rule set name and
+version, and the pass/fail counts. The file hash makes the entry
+tamper-evident: re-running against a modified file produces a different
+hash. A nod to 21 CFR Part 11 style traceability — not a compliance
+certification.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AuditEntry:
+    timestamp_utc: str
+    filename: str
+    file_sha256: str
+    ruleset_name: str
+    ruleset_version: str
+    rows_checked: int
+    rows_passed: int
+    rows_failed: int
+    error_count: int
+    passed: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def sha256_of_file(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_entry(
+    *,
+    filename: str | Path,
+    ruleset_name: str,
+    ruleset_version: str,
+    rows_checked: int,
+    rows_passed: int,
+    rows_failed: int,
+    error_count: int,
+) -> AuditEntry:
+    path = Path(filename)
+    return AuditEntry(
+        timestamp_utc=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        filename=path.name,
+        file_sha256=sha256_of_file(path),
+        ruleset_name=ruleset_name,
+        ruleset_version=ruleset_version,
+        rows_checked=rows_checked,
+        rows_passed=rows_passed,
+        rows_failed=rows_failed,
+        error_count=error_count,
+        passed=error_count == 0,
+    )
+
+
+def write_audit_log(entry: AuditEntry, log_path: str | Path) -> None:
+    """Append one entry (as a single JSON line) to the audit log."""
+    log_path = Path(log_path)
+    if log_path.parent != Path("."):
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(log_path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry.to_dict()) + "\n")
+
+
+def read_audit_log(log_path: str | Path) -> list[dict[str, Any]]:
+    """Read all entries from a JSON-lines audit log."""
+    entries = []
+    with open(log_path, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                entries.append(json.loads(line))
+    return entries

lims_dq/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface: ``lims-dq validate data.csv --schema schema.json``.
+
+Exit codes: 0 = all rows pass, 1 = validation failures found,
+2 = usage or file errors (missing file, bad schema, unreadable data).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from . import __version__
+from .audit import build_entry, write_audit_log
+from .report import ErrorReport
+from .schema import SchemaError, load_schema
+from .validators import validate_dataframe
+
+SUPPORTED_SUFFIXES = {".csv", ".xlsx", ".xls"}
+
+
+def load_data_file(path: Path) -> pd.DataFrame:
+    suffix = path.suffix.lower()
+    if suffix == ".csv":
+        return pd.read_csv(path, dtype=str)
+    if suffix in (".xlsx", ".xls"):
+        return pd.read_excel(path, dtype=str)
+    raise ValueError(
+        f"unsupported file type {path.suffix!r} "
+        f"(expected one of {sorted(SUPPORTED_SUFFIXES)})"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lims-dq",
+        description="Validate lab/LIMS data files against a schema before they "
+        "enter your pipeline.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    validate = sub.add_parser(
+        "validate", help="Validate a data file against a schema."
+    )
+    validate.add_argument("data_file", help="CSV or Excel file to validate")
+    validate.add_argument(
+        "--schema", required=True, help="Path to the schema JSON file"
+    )
+    validate.add_argument(
+        "--report",
+        default=None,
+        help="Write the full error report as JSON to this path",
+    )
+    validate.add_argument(
+        "--audit-log",
+        default=None,
+        help="Append a JSON-lines audit entry to this log file",
+    )
+    validate.add_argument(
+        "--no-strict",
+        action="store_true",
+        help="Do not flag columns missing from the schema",
+    )
+    return parser
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    data_path = Path(args.data_file)
+    if not data_path.is_file():
+        print(f"error: data file not found: {data_path}", file=sys.stderr)
+        return 2
+    try:
+        ruleset = load_schema(args.schema)
+    except SchemaError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    try:
+        df = load_data_file(data_path)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # unreadable file, bad encoding, ...
+        print(f"error: could not read {data_path}: {exc}", file=sys.stderr)
+        return 2
+
+    errors = validate_dataframe(df, ruleset, strict=not args.no_strict)
+    report = ErrorReport(
+        filename=data_path.name,
+        ruleset_name=ruleset.name,
+        ruleset_version=ruleset.version,
+        rows_checked=len(df),
+        errors=errors,
+    )
+    print(report.to_text())
+
+    if args.report:
+        Path(args.report).write_text(report.to_json() + "\n", encoding="utf-8")
+        print(f"\nJSON report written to {args.report}")
+
+    if args.audit_log:
+        entry = build_entry(
+            filename=data_path,
+            ruleset_name=ruleset.name,
+            ruleset_version=ruleset.version,
+            rows_checked=report.rows_checked,
+            rows_passed=report.rows_passed,
+            rows_failed=report.rows_failed,
+            error_count=len(errors),
+        )
+        write_audit_log(entry, args.audit_log)
+        print(f"audit entry appended to {args.audit_log}")
+
+    return 0 if report.passed else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "validate":
+        return cmd_validate(args)
+    parser.error(f"unknown command {args.command!r}")
+    return 2  # unreachable
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lims_dq/report.py

@@ -0,0 +1,88 @@
+"""Row-level error reports: console text and JSON."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class ValidationError:
+    """A single failed check.
+
+    ``row`` is the 1-based data-row number (row 1 = first row under the
+    header); ``row=0`` means the problem is file-level (e.g. a missing
+    column) rather than tied to a data row.
+    """
+
+    row: int
+    column: str
+    value: Any
+    rule: str
+    message: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ErrorReport:
+    """Aggregated result of validating one file."""
+
+    filename: str
+    ruleset_name: str
+    ruleset_version: str
+    rows_checked: int
+    errors: list[ValidationError]
+
+    @property
+    def passed(self) -> bool:
+        return not self.errors
+
+    @property
+    def rows_failed(self) -> int:
+        return len({e.row for e in self.errors if e.row > 0})
+
+    @property
+    def rows_passed(self) -> int:
+        return self.rows_checked - self.rows_failed
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "filename": self.filename,
+            "ruleset": {"name": self.ruleset_name, "version": self.ruleset_version},
+            "summary": {
+                "passed": self.passed,
+                "rows_checked": self.rows_checked,
+                "rows_passed": self.rows_passed,
+                "rows_failed": self.rows_failed,
+                "error_count": len(self.errors),
+                "errors_by_rule": dict(Counter(e.rule for e in self.errors)),
+                "errors_by_column": dict(Counter(e.column for e in self.errors)),
+            },
+            "errors": [e.to_dict() for e in self.errors],
+        }
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+    def to_text(self) -> str:
+        lines = [
+            f"lims-dq report: {self.filename}",
+            f"ruleset: {self.ruleset_name} v{self.ruleset_version}",
+            f"rows checked: {self.rows_checked} | "
+            f"passed: {self.rows_passed} | failed: {self.rows_failed} | "
+            f"errors: {len(self.errors)}",
+        ]
+        if self.passed:
+            lines.append("PASS: all rows satisfy the schema.")
+            return "\n".join(lines)
+        lines.append("")
+        lines.append(f"{'row':>5}  {'column':<18} {'rule':<18} message")
+        lines.append("-" * 72)
+        for e in self.errors:
+            row = "file" if e.row == 0 else str(e.row)
+            lines.append(f"{row:>5}  {e.column:<18} {e.rule:<18} {e.message}")
+        return "\n".join(lines)

lims_dq/schema.py

@@ -0,0 +1,135 @@
+"""Schema loading and validation for lims-dq.
+
+A schema is a JSON document describing the columns a data file must have::
+
+    {
+        "name": "lims-export",
+        "version": "1.0.0",
+        "columns": {
+            "sample_id":     {"dtype": "string", "required": true,
+                              "pattern": "^SMP-[0-9]{6}$"},
+            "concentration": {"dtype": "float", "required": true,
+                              "min": 0.0, "max": 100.0},
+            "unit":          {"dtype": "string", "required": true,
+                              "allowed": ["mg/L", "ug/mL", "ng/uL"]},
+            "analyzed_at":   {"dtype": "date", "required": false}
+        }
+    }
+
+Supported dtypes: ``string``, ``int``, ``float``, ``date``.
+Supported constraints: ``required``, ``pattern`` (regex, full match),
+``min``/``max`` (numeric dtypes only), ``allowed`` (enumerated values).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SUPPORTED_DTYPES = ("string", "int", "float", "date")
+
+
+class SchemaError(ValueError):
+    """Raised when a schema document is malformed."""
+
+
+@dataclass
+class Rule:
+    """Validation rule for a single column."""
+
+    name: str
+    dtype: str = "string"
+    required: bool = False
+    pattern: str | None = None
+    min: float | None = None
+    max: float | None = None
+    allowed: tuple[str, ...] | None = None
+    _regex: re.Pattern | None = field(default=None, repr=False, compare=False)
+
+    def compile(self) -> "Rule":
+        if self.pattern is not None:
+            try:
+                self._regex = re.compile(self.pattern)
+            except re.error as exc:
+                raise SchemaError(
+                    f"column {self.name!r}: invalid regex {self.pattern!r}: {exc}"
+                ) from exc
+        return self
+
+    def matches_pattern(self, value: str) -> bool:
+        assert self._regex is not None
+        return self._regex.fullmatch(value) is not None
+
+
+@dataclass
+class RuleSet:
+    """A named, versioned collection of column rules."""
+
+    name: str
+    version: str
+    rules: dict[str, Rule]
+
+    def required_columns(self) -> list[str]:
+        return [n for n, r in self.rules.items() if r.required]
+
+
+def _coerce_rule(name: str, spec: Any) -> Rule:
+    if not isinstance(spec, dict):
+        raise SchemaError(f"column {name!r}: rule must be an object, got {type(spec).__name__}")
+    dtype = spec.get("dtype", "string")
+    if dtype not in SUPPORTED_DTYPES:
+        raise SchemaError(
+            f"column {name!r}: unsupported dtype {dtype!r} "
+            f"(expected one of {SUPPORTED_DTYPES})"
+        )
+    unknown = set(spec) - {"dtype", "required", "pattern", "min", "max", "allowed"}
+    if unknown:
+        raise SchemaError(f"column {name!r}: unknown keys {sorted(unknown)}")
+
+    min_v = spec.get("min")
+    max_v = spec.get("max")
+    if (min_v is not None or max_v is not None) and dtype not in ("int", "float"):
+        raise SchemaError(f"column {name!r}: min/max only apply to int/float dtypes")
+    if min_v is not None and max_v is not None and min_v > max_v:
+        raise SchemaError(f"column {name!r}: min ({min_v}) > max ({max_v})")
+
+    allowed = spec.get("allowed")
+    if allowed is not None:
+        if not isinstance(allowed, list) or not allowed:
+            raise SchemaError(f"column {name!r}: 'allowed' must be a non-empty list")
+        allowed = tuple(str(v) for v in allowed)
+
+    return Rule(
+        name=name,
+        dtype=dtype,
+        required=bool(spec.get("required", False)),
+        pattern=spec.get("pattern"),
+        min=min_v,
+        max=max_v,
+        allowed=allowed,
+    ).compile()
+
+
+def load_schema(path: str | Path) -> RuleSet:
+    """Load and validate a schema JSON file, returning a RuleSet."""
+    path = Path(path)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise SchemaError(f"schema file not found: {path}") from None
+    except json.JSONDecodeError as exc:
+        raise SchemaError(f"schema file {path} is not valid JSON: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise SchemaError("schema must be a JSON object")
+    columns = raw.get("columns")
+    if not isinstance(columns, dict) or not columns:
+        raise SchemaError("schema must define a non-empty 'columns' object")
+    rules = {name: _coerce_rule(name, spec) for name, spec in columns.items()}
+    return RuleSet(
+        name=str(raw.get("name", path.stem)),
+        version=str(raw.get("version", "0.0.0")),
+        rules=rules,
+    )

lims_dq/validators.py

@@ -0,0 +1,145 @@
+"""Row-level validators: check a DataFrame against a RuleSet.
+
+Every problem found becomes a :class:`ValidationError` carrying the
+1-based data-row number (row 1 = first row beneath the header), the column
+name, the offending value, the rule that failed, and a human message.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .schema import Rule, RuleSet
+from .report import ValidationError
+
+
+def _is_missing(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, float) and pd.isna(value):
+        return True
+    if isinstance(value, str) and value.strip() == "":
+        return True
+    return False
+
+
+def _check_dtype(rule: Rule, value: Any) -> str | None:
+    """Return an error message if value violates rule.dtype, else None."""
+    text = str(value).strip()
+    if rule.dtype == "string":
+        return None
+    if rule.dtype == "int":
+        try:
+            if not float(text).is_integer():
+                return f"{value!r} is not an integer"
+        except (ValueError, OverflowError):
+            return f"{value!r} is not an integer"
+        return None
+    if rule.dtype == "float":
+        try:
+            float(text)
+        except (ValueError, OverflowError):
+            return f"{value!r} is not a number"
+        return None
+    if rule.dtype == "date":
+        if pd.to_datetime(text, errors="coerce") is pd.NaT:  # noqa: E711
+            return f"{value!r} is not a recognizable date"
+        return None
+    return None  # unreachable: schema layer guards dtypes
+
+
+def _check_constraints(rule: Rule, value: Any) -> list[str]:
+    """Check pattern/min/max/allowed constraints; return error messages."""
+    problems: list[str] = []
+    text = str(value).strip()
+    if rule.pattern is not None and not rule.matches_pattern(text):
+        problems.append(f"{value!r} does not match pattern {rule.pattern!r}")
+    if rule.dtype in ("int", "float"):
+        number = float(text)  # safe: dtype check ran first
+        if rule.min is not None and number < rule.min:
+            problems.append(f"{value!r} is below minimum {rule.min}")
+        if rule.max is not None and number > rule.max:
+            problems.append(f"{value!r} is above maximum {rule.max}")
+    if rule.allowed is not None and text not in rule.allowed:
+        problems.append(f"{value!r} is not one of {list(rule.allowed)}")
+    return problems
+
+
+def validate_dataframe(
+    df: pd.DataFrame, ruleset: RuleSet, *, strict: bool = True
+) -> list[ValidationError]:
+    """Validate every cell of ``df`` against ``ruleset``.
+
+    ``strict=True`` (default) also flags columns present in the file but
+    absent from the schema as ``unexpected_column`` errors.
+    """
+    errors: list[ValidationError] = []
+
+    for name, rule in ruleset.rules.items():
+        if rule.required and name not in df.columns:
+            errors.append(
+                ValidationError(
+                    row=0,
+                    column=name,
+                    value=None,
+                    rule="required_column",
+                    message=f"required column {name!r} is missing from the file",
+                )
+            )
+
+    if strict:
+        for column in df.columns:
+            if column not in ruleset.rules:
+                errors.append(
+                    ValidationError(
+                        row=0,
+                        column=str(column),
+                        value=None,
+                        rule="unexpected_column",
+                        message=f"column {str(column)!r} is not defined in the schema",
+                    )
+                )
+
+    for idx, (_, record) in enumerate(df.iterrows()):
+        row_num = idx + 1  # 1-based data row
+        for name, rule in ruleset.rules.items():
+            if name not in df.columns:
+                continue  # already reported as missing column
+            value = record[name]
+            if _is_missing(value):
+                if rule.required:
+                    errors.append(
+                        ValidationError(
+                            row=row_num,
+                            column=name,
+                            value=None,
+                            rule="required",
+                            message="required value is missing",
+                        )
+                    )
+                continue
+            dtype_problem = _check_dtype(rule, value)
+            if dtype_problem is not None:
+                errors.append(
+                    ValidationError(
+                        row=row_num,
+                        column=name,
+                        value=value if not pd.isna(value) else None,
+                        rule="dtype",
+                        message=dtype_problem,
+                    )
+                )
+                continue  # skip constraint checks on wrongly-typed values
+            for problem in _check_constraints(rule, value):
+                errors.append(
+                    ValidationError(
+                        row=row_num,
+                        column=name,
+                        value=value if not pd.isna(value) else None,
+                        rule="constraint",
+                        message=problem,
+                    )
+                )
+    return errors