trustline 0.1.0__py3-none-any.whl

trustline/__init__.py

@@ -0,0 +1,18 @@
+"""Trustline — open-source trust layer for data products.
+
+Public API (v0.2+):
+    validate: Validate contract YAML against JSON Schema
+    audit: Run five-phase trust scorecard
+
+Current exports:
+    __version__: Package version string
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("trustline")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

trustline/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for Trustline commands."""

trustline/cli/audit.py

@@ -0,0 +1,267 @@
+"""trustline audit — five-phase trust scorecard."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+
+from trustline.compiler.audit_profile import compile_audit_profile_checks
+from trustline.compiler.cohort import compile_cohort_checks
+from trustline.compiler.funnel import compile_funnel_checks
+from trustline.config import (
+    Profile,
+    load_profile,
+    resolve_duckdb_path,
+    resolve_profiles_path,
+)
+from trustline.contracts.audit_profile import AuditProfile, load_audit_profile
+from trustline.contracts.loader import load_contracts_dir
+from trustline.contracts.models import CohortManifest, FunnelContract
+from trustline.exceptions import AuditError, ExecutorError, TrustlineError, ValidationError
+from trustline.executors.base import CompiledCheck, Executor
+from trustline.executors.duckdb import DuckDBExecutor
+from trustline.reporters.brief import render_brief
+from trustline.reporters.json_report import render_scorecard_json
+from trustline.reporters.markdown import render_scorecard
+from trustline.reporters.rich_console import render_scorecard_console
+from trustline.scorecard._common import dialect_for_profile
+from trustline.scorecard.orchestrator import run_full_audit
+from trustline.scorecard.types import ScorecardResult
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="Run five-phase trust scorecard audit.")
+OutputFormat = Literal["text", "json", "both"]
+
+
+def _default_audit_profile_path(contracts_dir: Path) -> Path:
+    return contracts_dir.parent / "audit_profile.yaml"
+
+
+def _load_audit_profile(path: Path) -> AuditProfile | None:
+    if not path.is_file():
+        return None
+    return load_audit_profile(path)
+
+
+def _compile_checks(
+    contracts: list[FunnelContract | CohortManifest],
+    audit_profile: AuditProfile | None,
+    profile: Profile,
+) -> list[CompiledCheck]:
+    dialect = dialect_for_profile(profile.target)
+    checks: list[CompiledCheck] = []
+    if audit_profile is not None:
+        checks.extend(compile_audit_profile_checks(audit_profile, profile, dialect))
+    for contract in contracts:
+        if isinstance(contract, FunnelContract):
+            checks.extend(compile_funnel_checks(contract, profile, dialect))
+        elif isinstance(contract, CohortManifest):
+            checks.extend(compile_cohort_checks(contract, profile, dialect))
+    return checks
+
+
+def _build_executor(profile: Profile, profiles_path: Path) -> Executor:
+    if profile.target == "duckdb":
+        database = resolve_duckdb_path(profile, profiles_path)
+        if not database.is_file():
+            msg = f"DuckDB database not found: {database}"
+            raise TrustlineError(msg)
+        return DuckDBExecutor(database)
+    if profile.target == "snowflake":
+        from trustline.executors.snowflake import SnowflakeExecutor
+
+        return SnowflakeExecutor.from_env(profile)
+    msg = f"unsupported warehouse target: {profile.target!r}"
+    raise TrustlineError(msg)
+
+
+def _print_text_summary(
+    result: ScorecardResult,
+    *,
+    title: str,
+    no_color: bool = False,
+) -> None:
+    render_scorecard_console(result, title=title, no_color=no_color)
+
+
+def _write_reports(result: ScorecardResult, output_dir: Path, *, title: str) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "scorecard.md").write_text(
+        render_scorecard(result, title=title),
+        encoding="utf-8",
+    )
+    (output_dir / "scorecard.json").write_text(
+        json.dumps(render_scorecard_json(result), indent=2) + "\n",
+        encoding="utf-8",
+    )
+    (output_dir / "brief.md").write_text(render_brief(result), encoding="utf-8")
+
+
+def _exit_code_for_verdict(verdict: str) -> int:
+    return 1 if verdict == "fail" else 0
+
+
+def _maybe_notify_slack(
+    notify: str | None,
+    slack_webhook: str | None,
+    result: ScorecardResult,
+    *,
+    title: str,
+) -> None:
+    """Send Slack notification when configured and the audit failed."""
+    if notify is None:
+        return
+    if notify != "slack":
+        msg = f"unsupported notification channel: {notify!r}"
+        raise TrustlineError(msg)
+    if result.verdict != "fail":
+        return
+
+    from trustline.integrations.slack import notify_audit_failure, resolve_webhook_url
+
+    webhook_url = resolve_webhook_url(slack_webhook)
+    notify_audit_failure(webhook_url, result, title=title)
+
+
+@app.callback(invoke_without_command=True)
+def audit(  # noqa: PLR0913
+    contracts: str = typer.Option(
+        "./contracts",
+        "--contracts",
+        "-c",
+        help="Directory containing contract YAML files.",
+    ),
+    target: str = typer.Option(
+        "duckdb",
+        "--target",
+        "-t",
+        help="Warehouse target: duckdb or snowflake.",
+    ),
+    profile_name: str = typer.Option(
+        "default",
+        "--profile",
+        "-p",
+        help="Profile name in profiles.yml.",
+    ),
+    audit_profile_path: str | None = typer.Option(
+        None,
+        "--audit-profile",
+        help="Path to audit_profile.yaml (default: sibling of contracts directory).",
+    ),
+    profiles_path: str | None = typer.Option(
+        None,
+        "--profiles",
+        help="Path to profiles.yml (default: ./profiles.yml or ACME example).",
+    ),
+    output_dir: str = typer.Option(
+        ".",
+        "--output-dir",
+        help="Directory for scorecard.md and scorecard.json.",
+    ),
+    output_format: Annotated[
+        OutputFormat,
+        typer.Option("--output", "-o", help="Output format: text, json, or both."),
+    ] = "text",
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Compile checks only; do not execute SQL.",
+    ),
+    notify: str | None = typer.Option(
+        None,
+        "--notify",
+        help="Notification channel on failure (slack).",
+    ),
+    slack_webhook: str | None = typer.Option(
+        None,
+        "--slack-webhook",
+        envvar="SLACK_WEBHOOK_URL",
+        help="Slack incoming webhook URL.",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable ANSI colors in terminal output.",
+    ),
+) -> None:
+    """Run the five-phase trust scorecard against contract YAML."""
+    try:
+        contracts_dir = Path(contracts)
+        if not contracts_dir.is_dir():
+            typer.echo(f"ERROR: contracts directory not found: {contracts_dir}", err=True)
+            raise typer.Exit(code=2)
+
+        resolved_profiles = resolve_profiles_path(
+            Path(profiles_path) if profiles_path is not None else None
+        )
+        if not resolved_profiles.is_file():
+            typer.echo(f"ERROR: profiles file not found: {resolved_profiles}", err=True)
+            raise typer.Exit(code=2)
+
+        profile = load_profile(profile_name, resolved_profiles)
+        if profile.target != target:
+            typer.echo(
+                f"ERROR: profile {profile_name!r} target {profile.target!r} "
+                f"does not match --target {target!r}",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        documents = load_contracts_dir(contracts_dir)
+        if not documents:
+            typer.echo("ERROR: no contract files found.", err=True)
+            raise typer.Exit(code=2)
+
+        audit_path = (
+            Path(audit_profile_path)
+            if audit_profile_path is not None
+            else _default_audit_profile_path(contracts_dir)
+        )
+        audit_profile = _load_audit_profile(audit_path)
+
+        if dry_run:
+            compiled = _compile_checks(documents, audit_profile, profile)
+            typer.echo(f"Compiled {len(compiled)} checks (dry run).")
+            raise typer.Exit(code=0)
+
+        executor = _build_executor(profile, resolved_profiles)
+        try:
+            result = run_full_audit(documents, audit_profile, executor, profile)
+        finally:
+            if hasattr(executor, "close"):
+                executor.close()
+
+        title = contracts_dir.parent.name.replace("_", " ").title()
+        reports_dir = Path(output_dir)
+        _write_reports(result, reports_dir, title=title)
+
+        if output_format in {"text", "both"}:
+            _print_text_summary(result, title=title, no_color=no_color)
+            typer.echo(f"\nReports written to {reports_dir.resolve()}/")
+        if output_format in {"json", "both"}:
+            typer.echo(json.dumps(render_scorecard_json(result), indent=2))
+
+        _maybe_notify_slack(notify, slack_webhook, result, title=title)
+
+        raise typer.Exit(code=_exit_code_for_verdict(result.verdict))
+    except typer.Exit:
+        raise
+    except FileNotFoundError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    except (ValidationError, TrustlineError, AuditError) as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    except ExecutorError as exc:
+        logger.exception("audit executor failure")
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=3) from exc
+    except Exception as exc:
+        logger.exception("unexpected audit failure")
+        typer.echo(f"ERROR: internal error: {exc}", err=True)
+        raise typer.Exit(code=3) from exc

trustline/cli/main.py

@@ -0,0 +1,37 @@
+"""Trustline CLI entrypoint."""
+
+from importlib.metadata import version
+
+import typer
+
+from trustline.cli import audit, validate
+
+app = typer.Typer(
+    name="trustline",
+    help="Open-source trust layer for data products.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(version("trustline"))
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version_flag: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Trustline — machine-checkable contracts across ETL, ML, and delivery seams."""
+
+
+app.add_typer(validate.app, name="validate")
+app.add_typer(audit.app, name="audit")

trustline/cli/validate.py

@@ -0,0 +1,115 @@
+"""trustline validate — contract YAML validation."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+
+from trustline.contracts.validator import (
+    ValidationSummary,
+    validate_contract_file,
+    validate_contracts_dir,
+)
+from trustline.exceptions import TrustlineError, ValidationError
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="Validate contract YAML against JSON Schema.")
+
+
+def _print_summary(summary: ValidationSummary) -> None:
+    """Print per-file validation results."""
+    typer.echo(f"Validating {summary.total} contracts...\n")
+    for result in summary.results:
+        status = "PASS" if result.passed else "FAIL"
+        kind = result.kind or "Unknown"
+        typer.echo(f"  {result.path.name:<40} {kind:<20} {status}")
+        if not result.passed:
+            for error in result.errors:
+                typer.echo(error, err=True)
+
+
+def _summary_from_file(path: Path) -> ValidationSummary:
+    """Build a validation summary for a single file."""
+    result = validate_contract_file(path)
+    passed = 1 if result.passed else 0
+    return ValidationSummary(
+        total=1,
+        passed=passed,
+        failed=1 - passed,
+        results=(result,),
+    )
+
+
+def _exit_code_for_summary(summary: ValidationSummary) -> int:
+    """Map validation summary to CLI exit code."""
+    if summary.failed:
+        return 1
+    return 0
+
+
+@app.callback(invoke_without_command=True)
+def validate(
+    contracts: str = typer.Option(
+        "./contracts",
+        "--contracts",
+        "-c",
+        help="Directory containing contract YAML files.",
+    ),
+    file: str | None = typer.Option(
+        None,
+        "--file",
+        "-f",
+        help="Validate a single contract file instead of a directory.",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Treat warnings as errors (reserved for future use).",
+    ),
+) -> None:
+    """Validate contract YAML files against JSON Schema."""
+    del strict  # reserved for v0.1; schema errors already fail validation
+
+    try:
+        if file is not None:
+            path = Path(file)
+            if not path.is_file():
+                typer.echo(f"ERROR: contract file not found: {path}", err=True)
+                raise typer.Exit(code=2)
+            summary = _summary_from_file(path)
+        else:
+            directory = Path(contracts)
+            if not directory.is_dir():
+                typer.echo(f"ERROR: contracts directory not found: {directory}", err=True)
+                raise typer.Exit(code=2)
+            summary = validate_contracts_dir(directory)
+
+        _print_summary(summary)
+        if summary.total == 0:
+            typer.echo("\nNo contract files found.")
+            raise typer.Exit(code=2)
+
+        if summary.failed:
+            typer.echo("\nValidation failed.")
+            raise typer.Exit(code=_exit_code_for_summary(summary))
+
+        typer.echo("\nAll contracts valid.")
+    except typer.Exit:
+        raise
+    except FileNotFoundError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    except ValidationError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    except TrustlineError as exc:
+        logger.exception("validate command failed")
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=3) from exc
+    except Exception as exc:
+        logger.exception("unexpected validate failure")
+        typer.echo(f"ERROR: internal error: {exc}", err=True)
+        raise typer.Exit(code=3) from exc

trustline/compiler/__init__.py

@@ -0,0 +1 @@
+"""Contract-to-SQL check compilation."""

trustline/compiler/audit_profile.py

@@ -0,0 +1,79 @@
+"""Compile audit profile documents into SQL checks."""
+
+from __future__ import annotations
+
+from trustline.compiler.templates import render_template, resolve_refs
+from trustline.config import Profile
+from trustline.contracts.audit_profile import AuditProfile
+from trustline.executors.base import CheckExpectation, CompiledCheck
+
+
+def compile_audit_profile_checks(
+    profile_doc: AuditProfile,
+    profile: Profile,
+    dialect: str,
+) -> list[CompiledCheck]:
+    """Compile Phase 1 and Phase 3 checks from an audit profile."""
+    checks: list[CompiledCheck] = []
+
+    sync_table = resolve_refs(profile_doc.crm_coverage.sync_table, profile)
+    mirror_table = resolve_refs(profile_doc.crm_coverage.mirror_table, profile)
+    checks.append(
+        CompiledCheck(
+            check_id="audit.crm_coverage",
+            phase=1,
+            sql=render_template(
+                "crm_coverage_gap.sql.j2",
+                {"sync_table": sync_table, "mirror_table": mirror_table},
+                dialect,
+            ),
+            expect=CheckExpectation(
+                kind="min_sync_pct",
+                value=profile_doc.crm_coverage.expect_sync_pct,
+            ),
+            evidence_key="crm_coverage",
+        )
+    )
+
+    swap_table = resolve_refs(profile_doc.source_swap.table, profile)
+    migration = profile_doc.source_swap.migration
+    checks.append(
+        CompiledCheck(
+            check_id="audit.source_swap_volume",
+            phase=3,
+            sql=render_template(
+                "source_swap_volume.sql.j2",
+                {
+                    "table_ref": swap_table,
+                    "from_source": migration.from_source,
+                    "to_source": migration.to_source,
+                    "cutover_date": migration.cutover_date.isoformat(),
+                },
+                dialect,
+            ),
+            expect=CheckExpectation(
+                kind="max_drift_pct",
+                value=profile_doc.source_swap.volume_threshold_pct,
+                tolerance=2.0,
+            ),
+            evidence_key="source_swap",
+        )
+    )
+
+    if profile_doc.score_distribution is not None:
+        table_ref = resolve_refs(profile_doc.score_distribution.table, profile)
+        checks.append(
+            CompiledCheck(
+                check_id="audit.score_distribution",
+                phase=3,
+                sql=render_template(
+                    "score_distribution.sql.j2",
+                    {"table_ref": table_ref},
+                    dialect,
+                ),
+                expect=CheckExpectation(kind="min_count", value=1.0),
+                evidence_key="score_distribution",
+            )
+        )
+
+    return checks

trustline/compiler/cohort.py

@@ -0,0 +1,59 @@
+"""Compile CohortManifest documents into SQL checks."""
+
+from __future__ import annotations
+
+from trustline.compiler.templates import render_template, resolve_refs
+from trustline.config import Profile
+from trustline.contracts.models import CohortManifest
+from trustline.executors.base import CheckExpectation, CompiledCheck
+
+
+def compile_cohort_checks(
+    contract: CohortManifest,
+    profile: Profile,
+    dialect: str,
+) -> list[CompiledCheck]:
+    """Compile cohort source parity and positive rate checks."""
+    training_table = resolve_refs(contract.spec.sources.training, profile)
+    scoring_table = resolve_refs(contract.spec.sources.scoring, profile)
+    contract_name = contract.metadata.name
+
+    source_parity_sql = render_template(
+        "cohort_source_parity.sql.j2",
+        {
+            "training_table": training_table,
+            "scoring_table": scoring_table,
+        },
+        dialect,
+    )
+
+    label_sql = contract.spec.label.sql or "1"
+    positive_rate_sql = render_template(
+        "cohort_positive_rate.sql.j2",
+        {
+            "label_sql": label_sql,
+            "training_table": training_table,
+        },
+        dialect,
+    )
+
+    return [
+        CompiledCheck(
+            check_id=f"cohort.source_parity.{contract_name}",
+            phase=4,
+            sql=source_parity_sql,
+            expect=CheckExpectation(kind="source_parity", value=1.0),
+            evidence_key="sources",
+        ),
+        CompiledCheck(
+            check_id=f"cohort.positive_rate.{contract_name}",
+            phase=4,
+            sql=positive_rate_sql,
+            expect=CheckExpectation(
+                kind="positive_rate",
+                value=contract.spec.expected_positive_rate,
+                tolerance=contract.spec.positive_rate_tolerance,
+            ),
+            evidence_key="positive_rate",
+        ),
+    ]

trustline/compiler/funnel.py

@@ -0,0 +1,100 @@
+"""Compile FunnelContract documents into SQL checks."""
+
+from __future__ import annotations
+
+from trustline.compiler.templates import render_template, resolve_refs
+from trustline.config import Profile
+from trustline.contracts.models import FunnelContract, FunnelStage
+from trustline.exceptions import AuditError
+from trustline.executors.base import CheckExpectation, CompiledCheck
+
+
+def _stage_subquery(
+    stage: FunnelStage,
+    stage_queries: dict[str, str],
+    profile: Profile,
+    dialect: str,
+) -> str:
+    """Build the SQL subquery that materializes a funnel stage."""
+    if stage.sql is not None:
+        return resolve_refs(stage.sql, profile)
+
+    if stage.from_stage is None or stage.join is None:
+        msg = f"stage {stage.name!r} is missing sql or join configuration"
+        raise AuditError(msg)
+
+    return render_template(
+        "funnel_stage_join.sql.j2",
+        {
+            "prior_stage_sql": stage_queries[stage.from_stage],
+            "join_table": resolve_refs(stage.join.table, profile),
+            "join_type": stage.join.type.upper(),
+            "join_on": stage.join.on,
+        },
+        dialect,
+    )
+
+
+def _build_stage_queries(
+    contract: FunnelContract, profile: Profile, dialect: str
+) -> dict[str, str]:
+    """Compile all stage subqueries in funnel order."""
+    queries: dict[str, str] = {}
+    for stage in contract.spec.stages:
+        queries[stage.name] = _stage_subquery(stage, queries, profile, dialect)
+    return queries
+
+
+def compile_funnel_checks(
+    contract: FunnelContract,
+    profile: Profile,
+    dialect: str,
+) -> list[CompiledCheck]:
+    """Compile funnel stage count and retention checks."""
+    checks: list[CompiledCheck] = []
+    stage_queries = _build_stage_queries(contract, profile, dialect)
+
+    for index, stage in enumerate(contract.spec.stages):
+        stage_sql = stage_queries[stage.name]
+        contract_name = contract.metadata.name
+
+        if stage.expect_min_count is not None:
+            sql = render_template(
+                "funnel_stage_count.sql.j2",
+                {"stage_sql": stage_sql, "stage_name": stage.name},
+                dialect,
+            )
+            checks.append(
+                CompiledCheck(
+                    check_id=f"funnel.count.{contract_name}.{stage.name}",
+                    phase=2,
+                    sql=sql,
+                    expect=CheckExpectation(kind="min_count", value=float(stage.expect_min_count)),
+                    evidence_key=stage.name,
+                )
+            )
+
+        if stage.expect_retention_pct is not None and index > 0:
+            prior_stage = contract.spec.stages[index - 1]
+            sql = render_template(
+                "funnel_retention.sql.j2",
+                {
+                    "stage_sql": stage_sql,
+                    "prior_stage_sql": stage_queries[prior_stage.name],
+                },
+                dialect,
+            )
+            checks.append(
+                CompiledCheck(
+                    check_id=f"funnel.retention.{contract_name}.{stage.name}",
+                    phase=2,
+                    sql=sql,
+                    expect=CheckExpectation(
+                        kind="min_retention_pct",
+                        value=float(stage.expect_retention_pct),
+                    ),
+                    evidence_key=stage.name,
+                )
+            )
+
+    return checks