akad-framework 1.0.0__py3-none-any.whl

akad/__init__.py

@@ -0,0 +1,10 @@
+"""Akad — Data Contract Framework.
+
+Public API::
+
+    from akad import DataContractValidator, DataContractBreachError
+"""
+from akad.sdk import DataContractBreachError, DataContractValidator
+
+__all__ = ["DataContractValidator", "DataContractBreachError"]
+__version__ = "1.0.0"

akad/cli.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from akad.contract_loader import load_contract
+from akad.models.result import ValidationResult
+from akad.registry_client import RegistryClient
+
+app = typer.Typer(name="akad", help="Akad — Data Contract Framework CLI", no_args_is_help=True)
+
+
+@app.command()
+def validate(
+    contract:     Path = typer.Option(..., "--contract", "-c", help="Path to contract YAML"),
+    registry_url: str | None = typer.Option(None, "--registry-url", "-r", help="Registry URL"),
+    output:       str  = typer.Option("text", "--output", "-o", help="Output format: text|json"),
+) -> None:
+    """Validate a dataset against its contract."""
+    from akad.sdk import DataContractBreachError, DataContractValidator
+
+    try:
+        validator = DataContractValidator(
+            contract_path=contract,
+            registry_url=registry_url,
+            notifiers=[],  # CLI never sends notifications
+        )
+        result = validator.validate()
+    except DataContractBreachError as exc:
+        result = exc.result
+        _print_result(result, output)
+        raise typer.Exit(code=1) from exc
+    except Exception as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    _print_result(result, output)
+    if result.is_breach:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def publish(
+    contract:     Path = typer.Option(..., "--contract", "-c", help="Path to contract YAML"),
+    registry_url: str  = typer.Option(..., "--registry-url", "-r", help="Registry URL"),
+) -> None:
+    """Publish a contract to the registry."""
+    c = load_contract(contract)
+    client = RegistryClient(registry_url)
+    client.publish_contract(c)
+    typer.echo(f"Published {c.metadata.name} v{c.metadata.version}")
+
+
+@app.command()
+def check(
+    contract: Path = typer.Option(..., "--contract", "-c", help="Path to contract YAML"),
+) -> None:
+    """Validate contract YAML syntax without accessing data."""
+    try:
+        c = load_contract(contract)
+        typer.echo(f"OK  {c.metadata.name} v{c.metadata.version} — contract is valid")
+    except Exception as exc:
+        typer.echo(f"FAIL  {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command(name="list")
+def list_contracts(
+    registry_url: str = typer.Option(..., "--registry-url", "-r", help="Registry URL"),
+) -> None:
+    """List all contracts in the registry."""
+    import httpx
+    try:
+        data = httpx.get(f"{registry_url.rstrip('/')}/contracts/", timeout=10).json()
+        for c in data:
+            typer.echo(f"  {c['name']:40s}  v{c['version']}")
+    except Exception as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def history(
+    name:         str = typer.Option(..., "--name", "-n", help="Contract name"),
+    registry_url: str = typer.Option(..., "--registry-url", "-r", help="Registry URL"),
+    limit:        int = typer.Option(20, "--limit", "-l", help="Number of results"),
+) -> None:
+    """Show breach history for a contract."""
+    import httpx
+    try:
+        url  = f"{registry_url.rstrip('/')}/validation-results/?contract_name={name}&limit={limit}"
+        data = httpx.get(url, timeout=10).json()
+        for r in data:
+            icon = "✓" if r["overall_status"] == "COMPLIANT" else "✗"
+            typer.echo(f"  {icon} {r['validated_at']}  {r['overall_status']}")
+    except Exception as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def _print_result(result: ValidationResult, output: str) -> None:
+    if output == "json":
+        typer.echo(json.dumps({
+            "status":         result.overall_status.value,
+            "row_count":      result.row_count,
+            "failed_clauses": [c.to_dict() for c in result.failed_clauses],
+        }, indent=2))
+    else:
+        icon = "✓" if result.overall_status.value == "COMPLIANT" else "✗"
+        typer.echo(f"{icon} {result.contract_name} v{result.contract_version}: {result.overall_status.value}")
+        if result.failed_clauses:
+            typer.echo("Failed clauses:")
+            for c in result.failed_clauses:
+                target = f" [{c.clause_target}]" if c.clause_target else ""
+                typer.echo(f"  - [{c.clause_type}]{target} {c.message}")
+
+
+if __name__ == "__main__":
+    app()

akad/contract_loader.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from akad.models.contract import DataContract
+
+
+def load_contract(path: str | Path) -> DataContract:
+    """Load and validate a contract YAML file.
+
+    Raises pydantic.ValidationError with clear messages if the file is invalid.
+    """
+    with open(path, encoding="utf-8") as fh:
+        raw = yaml.safe_load(fh)
+    return DataContract.model_validate(raw)

akad/engine.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pandas as pd
+
+from akad.models.contract import DataContract
+from akad.models.result import ClauseResult, ClauseStatus, OverallStatus, ValidationResult
+from akad.readers.parquet_reader import ParquetReader
+from akad.readers.sql_reader import SQLReader
+from akad.validators.freshness_validator import FreshnessValidator
+from akad.validators.quality_validator import QualityValidator
+from akad.validators.schema_validator import SchemaValidator
+from akad.validators.volume_validator import VolumeValidator
+
+_READERS = {
+    "parquet": ParquetReader,
+    "sql":     SQLReader,
+}
+
+_DEFAULT_VALIDATORS = [
+    SchemaValidator(),
+    FreshnessValidator(),
+    VolumeValidator(),
+    QualityValidator(),
+]
+
+
+def validate(
+    contract: DataContract,
+    extra_validators: list | None = None,
+) -> ValidationResult:
+    """Run all validators against the dataset described in *contract*.
+
+    Reads data from storage. Use validate_dataframe() for unit-test-friendly validation
+    that skips the read step.
+    """
+    now = datetime.now(UTC)
+    location = str(contract.dataset.location or contract.dataset.table_name or "")
+
+    reader_cls = _READERS.get(contract.dataset.format)
+    if not reader_cls:
+        return ValidationResult(
+            contract_name=contract.metadata.name,
+            contract_version=contract.metadata.version,
+            dataset_location=location,
+            validated_at=now,
+            overall_status=OverallStatus.ERROR,
+            error_message=f"Unsupported dataset format: {contract.dataset.format}",
+        )
+
+    reader = reader_cls()
+
+    try:
+        df = reader.read(contract.dataset)
+    except Exception as exc:
+        return ValidationResult(
+            contract_name=contract.metadata.name,
+            contract_version=contract.metadata.version,
+            dataset_location=location,
+            validated_at=now,
+            overall_status=OverallStatus.ERROR,
+            error_message=f"Failed to read dataset: {exc}",
+        )
+
+    try:
+        last_modified: float | None = reader.get_last_modified(contract.dataset)
+    except Exception:
+        last_modified = None
+
+    return validate_dataframe(df, contract, extra_validators, last_modified, _now=now)
+
+
+def validate_dataframe(
+    df: pd.DataFrame,
+    contract: DataContract,
+    extra_validators: list | None = None,
+    reader_last_modified: float | None = None,
+    _now: datetime | None = None,
+) -> ValidationResult:
+    """Run all validators against a pre-loaded DataFrame.
+
+    Designed for unit and integration tests — callers supply the DataFrame directly,
+    no storage access needed.
+    """
+    now = _now or datetime.now(UTC)
+    location = str(contract.dataset.location or contract.dataset.table_name or "")
+
+    all_validators = _DEFAULT_VALIDATORS + (extra_validators or [])
+    all_clause_results: list[ClauseResult] = []
+
+    for v in all_validators:
+        try:
+            results = v.validate(df, contract, reader_last_modified)
+            all_clause_results.extend(results)
+        except Exception as exc:
+            all_clause_results.append(ClauseResult(
+                clause_type=type(v).__name__,
+                clause_target=None,
+                status=ClauseStatus.ERROR,
+                expected="validator to complete",
+                observed="validator raised exception",
+                message=str(exc),
+            ))
+
+    has_fail  = any(r.status == ClauseStatus.FAIL  for r in all_clause_results)
+    has_error = any(r.status == ClauseStatus.ERROR for r in all_clause_results)
+
+    if has_fail:
+        overall = OverallStatus.BREACH
+    elif has_error:
+        overall = OverallStatus.ERROR
+    else:
+        overall = OverallStatus.COMPLIANT
+
+    return ValidationResult(
+        contract_name=contract.metadata.name,
+        contract_version=contract.metadata.version,
+        dataset_location=location,
+        validated_at=now,
+        overall_status=overall,
+        clause_results=all_clause_results,
+        row_count=len(df),
+    )

akad/models/contract.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ColumnType(StrEnum):
+    STRING    = "string"
+    INTEGER   = "integer"
+    FLOAT     = "float"
+    BOOLEAN   = "boolean"
+    DATE      = "date"
+    TIMESTAMP = "timestamp"
+    DECIMAL   = "decimal"
+
+
+class ColumnSpec(BaseModel):
+    name:           str
+    type:           ColumnType
+    nullable:       bool = True
+    description:    str | None = None
+    allowed_values: list[str] | None = None
+
+
+class SchemaSpec(BaseModel):
+    enforce_no_extra_columns: bool = False
+    columns: list[ColumnSpec]
+
+
+class FreshnessSpec(BaseModel):
+    max_age_hours: float
+    check_column:  str | None = None
+
+
+class VolumeSpec(BaseModel):
+    min_rows: int | None = None
+    max_rows: int | None = None
+
+
+class QualityRule(BaseModel):
+    column:                   str
+    max_null_percentage:      float | None = None
+    max_duplicate_percentage: float | None = None
+    min_value:                float | None = None
+    max_value:                float | None = None
+
+
+class ConsumerSpec(BaseModel):
+    team:          str
+    email:         str
+    slack_webhook: str | None = None
+
+
+class OwnerSpec(BaseModel):
+    team:  str
+    email: str
+
+
+class MetadataSpec(BaseModel):
+    name:        str
+    version:     str
+    description: str | None = None
+    owner:       OwnerSpec
+    tags:        list[str] = []
+
+
+class DatasetSpec(BaseModel):
+    format:            Literal["parquet", "sql"]
+    location:          str | None = None
+    catalog_uri:       str | None = None
+    catalog_type:      str | None = None
+    namespace:         str | None = None
+    table_name:        str | None = None
+    connection_string: str | None = None
+    partition_column:  str | None = None
+
+
+class WebhookSpec(BaseModel):
+    url:     str
+    headers: dict[str, str] = {}
+
+
+class EmailSpec(BaseModel):
+    smtp_host:         str
+    smtp_port:         int = 587
+    smtp_user:         str
+    smtp_password_env: str
+    recipients:        list[str] = []
+
+
+class NotificationsSpec(BaseModel):
+    webhook: WebhookSpec | None = None
+    email:   EmailSpec | None   = None
+
+
+class DataContract(BaseModel):
+    apiVersion: Literal["datacontract/v1"]
+    kind:       Literal["DataContract"]
+    metadata:   MetadataSpec
+    dataset:    DatasetSpec
+    on_breach:  Literal["warn", "fail"] = "warn"
+    consumers:  list[ConsumerSpec]           = []
+    schema_:    SchemaSpec | None         = Field(None, alias="schema")
+    freshness:  FreshnessSpec | None      = None
+    volume:     VolumeSpec | None         = None
+    quality:    list[QualityRule]            = []
+    notifications: NotificationsSpec | None = None
+
+    model_config = {"populate_by_name": True}

akad/models/result.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+
+class ClauseStatus(StrEnum):
+    PASS    = "PASS"
+    FAIL    = "FAIL"
+    SKIPPED = "SKIPPED"
+    ERROR   = "ERROR"
+
+
+class OverallStatus(StrEnum):
+    COMPLIANT = "COMPLIANT"
+    BREACH    = "BREACH"
+    ERROR     = "ERROR"
+
+
+@dataclass
+class ClauseResult:
+    clause_type:   str
+    clause_target: str | None
+    status:        ClauseStatus
+    expected:      Any
+    observed:      Any
+    message:       str
+
+    def to_dict(self) -> dict:
+        """JSON-safe dict matching the registry's ClauseResultSchema."""
+        return {
+            "clause_type":   self.clause_type,
+            "clause_target": self.clause_target,
+            "status":        self.status.value,
+            "expected":      str(self.expected),
+            "observed":      str(self.observed),
+            "message":       self.message,
+        }
+
+
+@dataclass
+class ValidationResult:
+    contract_name:    str
+    contract_version: str
+    dataset_location: str
+    validated_at:     datetime
+    overall_status:   OverallStatus
+    clause_results:   list[ClauseResult] = field(default_factory=list)
+    row_count:        int | None = None
+    error_message:    str | None = None
+
+    @property
+    def is_breach(self) -> bool:
+        return self.overall_status == OverallStatus.BREACH
+
+    @property
+    def failed_clauses(self) -> list[ClauseResult]:
+        return [c for c in self.clause_results if c.status == ClauseStatus.FAIL]
+
+    def to_dict(self) -> dict:
+        """JSON-safe dict matching the registry's ValidationResultRequest payload."""
+        return {
+            "contract_name":    self.contract_name,
+            "contract_version": self.contract_version,
+            "dataset_location": self.dataset_location,
+            "validated_at":     self.validated_at.isoformat(),
+            "overall_status":   self.overall_status.value,
+            "row_count":        self.row_count,
+            "clause_results":   [c.to_dict() for c in self.clause_results],
+            "error_message":    self.error_message,
+        }

akad/notifier.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from akad.models.contract import DataContract
+from akad.models.result import ValidationResult
+from akad.notifiers.base import Notifier
+from akad.notifiers.email_notifier import EmailNotifier
+from akad.notifiers.webhook_notifier import WebhookNotifier
+
+_DEFAULT_NOTIFIERS: list[Notifier] = [WebhookNotifier(), EmailNotifier()]
+
+
+def dispatch_notifications(
+    contract: DataContract,
+    result: ValidationResult,
+    notifiers: list[Notifier] | None = None,
+) -> None:
+    """Send breach notifications via all configured notifiers.
+
+    Pass *notifiers* to override the default list — useful in tests to inject mocks.
+    """
+    active = notifiers if notifiers is not None else _DEFAULT_NOTIFIERS
+    for n in active:
+        n.notify(contract, result)

akad/notifiers/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from akad.models.contract import DataContract
+from akad.models.result import ValidationResult
+
+
+class Notifier(ABC):
+    @abstractmethod
+    def notify(self, contract: DataContract, result: ValidationResult) -> None:
+        """Send a breach notification. Must never raise."""
+        ...

akad/notifiers/email_notifier.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import logging
+import os
+import smtplib
+from email.mime.text import MIMEText
+
+from akad.models.contract import DataContract
+from akad.models.result import ValidationResult
+from akad.notifiers.base import Notifier
+
+log = logging.getLogger(__name__)
+
+
+def _collect_recipients(contract: DataContract) -> list[str]:
+    recipients: list[str] = []
+    recipients.append(contract.metadata.owner.email)
+    for consumer in contract.consumers:
+        recipients.append(consumer.email)
+    if contract.notifications and contract.notifications.email:
+        recipients.extend(contract.notifications.email.recipients)
+    return list(dict.fromkeys(recipients))  # deduplicate, preserve order
+
+
+def _build_email_body(contract: DataContract, result: ValidationResult) -> str:
+    lines = [
+        "Akad Breach Alert",
+        "",
+        f"Contract : {result.contract_name} v{result.contract_version}",
+        f"Dataset  : {result.dataset_location}",
+        f"Time     : {result.validated_at.isoformat()}",
+        f"Rows     : {result.row_count}",
+        "",
+        f"Failed Clauses ({len(result.failed_clauses)}):",
+    ]
+    for c in result.failed_clauses:
+        target = f" [{c.clause_target}]" if c.clause_target else ""
+        lines.append(f"  • {c.clause_type}{target}: {c.message}")
+    return "\n".join(lines)
+
+
+class EmailNotifier(Notifier):
+    def notify(self, contract: DataContract, result: ValidationResult) -> None:
+        if not (contract.notifications and contract.notifications.email):
+            return
+        cfg = contract.notifications.email
+        recipients = _collect_recipients(contract)
+        if not recipients:
+            return
+        body = _build_email_body(contract, result)
+        try:
+            msg = MIMEText(body)
+            msg["Subject"] = f"[Akad BREACH] {contract.metadata.name} v{contract.metadata.version}"
+            msg["From"]    = cfg.smtp_user
+            msg["To"]      = ", ".join(recipients)
+            password = os.environ.get(cfg.smtp_password_env, "")
+            with smtplib.SMTP(cfg.smtp_host, cfg.smtp_port) as srv:
+                srv.starttls()
+                srv.login(cfg.smtp_user, password)
+                srv.sendmail(cfg.smtp_user, recipients, msg.as_string())
+        except Exception as exc:
+            log.warning("Email notification failed: %s", exc)

akad/notifiers/webhook_notifier.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from akad.models.contract import DataContract
+from akad.models.result import ValidationResult
+from akad.notifiers.base import Notifier
+
+log = logging.getLogger(__name__)
+
+
+def _build_payload(contract: DataContract, result: ValidationResult) -> dict:
+    return {
+        "event":            "DATA_CONTRACT_BREACH",
+        "contract_name":    result.contract_name,
+        "contract_version": result.contract_version,
+        "dataset_location": result.dataset_location,
+        "validated_at":     result.validated_at.isoformat(),
+        "row_count":        result.row_count,
+        "failed_clauses": [
+            {
+                "clause_type":   c.clause_type,
+                "clause_target": c.clause_target,
+                "expected":      str(c.expected),
+                "observed":      str(c.observed),
+                "message":       c.message,
+            }
+            for c in result.failed_clauses
+        ],
+        "on_breach": contract.on_breach,
+    }
+
+
+class WebhookNotifier(Notifier):
+    def notify(self, contract: DataContract, result: ValidationResult) -> None:
+        if not (contract.notifications and contract.notifications.webhook):
+            return
+        cfg = contract.notifications.webhook
+        payload = _build_payload(contract, result)
+        try:
+            resp = httpx.post(
+                cfg.url,
+                json=payload,
+                headers=cfg.headers,
+                timeout=10,
+            )
+            resp.raise_for_status()
+        except Exception as exc:
+            log.warning("Webhook notification failed: %s", exc)

akad/readers/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+from akad.models.contract import DatasetSpec
+
+
+class DataReadError(Exception):
+    """Raised when a DataReader cannot load the requested dataset."""
+
+
+class DataReader(ABC):
+    @abstractmethod
+    def read(self, spec: DatasetSpec) -> pd.DataFrame:
+        """Read the dataset and return a DataFrame. Raise DataReadError on failure."""
+        ...
+
+    @abstractmethod
+    def get_last_modified(self, spec: DatasetSpec) -> float:
+        """Return Unix epoch of last modification. Raise NotImplementedError if unsupported."""
+        ...

akad/readers/parquet_reader.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+import pyarrow.parquet as pq
+
+from akad.models.contract import DatasetSpec
+from akad.readers.base import DataReader, DataReadError
+
+
+class ParquetReader(DataReader):
+    def read(self, spec: DatasetSpec) -> pd.DataFrame:
+        try:
+            table = pq.read_table(spec.location)
+            return table.to_pandas()
+        except Exception as exc:
+            raise DataReadError(f"Cannot read Parquet at '{spec.location}': {exc}") from exc
+
+    def get_last_modified(self, spec: DatasetSpec) -> float:
+        if spec.location is None:
+            raise DataReadError("Parquet dataset spec is missing 'location'")
+        path = Path(spec.location)
+        if path.exists():
+            return path.stat().st_mtime
+        raise NotImplementedError("S3/remote last-modified requires s3fs configuration")