canonic 0.5.0__py3-none-any.whl

canonic/airgap.py

@@ -0,0 +1,139 @@
+"""Air-gapped egress guard (SPEC-E10 §4).
+
+The enforced privacy differentiator: under ``runtime.air_gapped: true`` no warehouse
+content or context may leave the machine/network. :class:`EgressPolicy` is the single
+source of truth for *what counts as local*, shared by load-time config validation
+(``canonic/config.py``) and call-time runtime enforcement (``canonic/runtime/generation.py``)
+so the allowlist logic is never duplicated.
+
+Default policy is **localhost-only** (loopback + the name ``localhost``): the tightest
+guarantee. A separate on-prem inference host must be opted in explicitly via
+``runtime.allow_cidrs``. Dependency-light (stdlib only) so the config layer can import it
+without pulling in litellm.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from canonic.exc import AirGappedViolation
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["LOCAL_REF_SCHEMES", "EgressPolicy", "guard_telemetry"]
+
+#: Secret-reference schemes that resolve on-machine. A ``*_ref`` using any other scheme
+#: (e.g. a future ``vault:``/``https:`` remote secret service) is rejected under air-gapped.
+LOCAL_REF_SCHEMES: frozenset[str] = frozenset({"env", "keyring", "file"})
+
+#: Always-allowed loopback ranges, independent of any configured allowlist.
+_LOOPBACK_NETWORKS: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = (
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+)
+
+
+def guard_telemetry(*, air_gapped: bool, telemetry_enabled: bool) -> None:
+    """Raise AirGappedViolation if telemetry would be on while air-gapped (SPEC-E16 §9, S5).
+
+    The single chokepoint for the air-gapped telemetry guarantee. Load-time config validation
+    and any future opt-in telemetry-enable path both call this so the guard cannot be bypassed.
+    """
+    if air_gapped and telemetry_enabled:
+        raise AirGappedViolation(
+            "air-gapped: telemetry.enabled must be false when runtime.air_gapped is true"
+        )
+
+
+class EgressPolicy:
+    """Allowlist guard for air-gapped egress (SPEC-E10 §4).
+
+    Loopback addresses and the literal hostname ``localhost`` are always allowed.
+    ``allow_cidrs`` adds explicit private/LAN ranges for an on-prem inference host. An
+    instance is only created when ``runtime.air_gapped`` is set — its mere existence
+    means enforcement is active.
+    """
+
+    def __init__(self, *, allow_cidrs: Sequence[str] = ()) -> None:
+        extra: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
+        for cidr in allow_cidrs:
+            try:
+                extra.append(ipaddress.ip_network(cidr, strict=False))
+            except ValueError as exc:
+                raise AirGappedViolation(
+                    f"runtime.allow_cidrs entry {cidr!r} is not a valid CIDR: {exc}"
+                ) from exc
+        self._networks: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = (
+            *_LOOPBACK_NETWORKS,
+            *extra,
+        )
+
+    def check_url(self, url: str, *, what: str) -> None:
+        """Raise :class:`AirGappedViolation` if ``url``'s host is not allowlisted.
+
+        Args:
+            url: The endpoint URL whose host is checked (e.g. ``llm.base_url``).
+            what: Names the configuration source for a clear message.
+        """
+        host = urlsplit(url).hostname
+        if host is None:
+            raise AirGappedViolation(f"air-gapped: {what} {url!r} has no resolvable host to check")
+        if not self.is_allowed_host(host):
+            raise AirGappedViolation(
+                f"air-gapped: {what} host {host!r} is not local or allowlisted — "
+                f"add it to runtime.allow_cidrs or use a local endpoint"
+            )
+
+    def check_ref_local(self, ref: str, *, what: str) -> None:
+        """Raise :class:`AirGappedViolation` if ``ref`` uses a non-local secret scheme.
+
+        Forward-proofs against a future remote secret service: only ``env:``/``keyring:``/
+        ``file:`` resolve on-machine (:data:`LOCAL_REF_SCHEMES`).
+        """
+        scheme = ref.partition(":")[0]
+        if scheme not in LOCAL_REF_SCHEMES:
+            raise AirGappedViolation(
+                f"air-gapped: {what} {ref!r} uses non-local secret scheme {scheme!r}; "
+                f"only {', '.join(sorted(LOCAL_REF_SCHEMES))} are allowed"
+            )
+
+    def is_allowed_host(self, host: str) -> bool:
+        """Whether ``host`` resolves only to allowlisted addresses.
+
+        An IP literal is checked directly. ``localhost`` is special-cased to avoid relying
+        on resolver configuration. Any other hostname is resolved via ``getaddrinfo`` and
+        **every** resolved address must be allowlisted — fail-closed when resolution yields
+        nothing or any address falls outside the allowlist.
+        """
+        if host == "localhost":
+            return True
+
+        literal = self._as_ip(host)
+        if literal is not None:
+            return self._is_allowed_address(literal)
+
+        try:
+            infos = socket.getaddrinfo(host, None)
+        except socket.gaierror:
+            return False
+        addresses = {str(info[4][0]) for info in infos}
+        if not addresses:
+            return False
+        return all(
+            (addr := self._as_ip(raw)) is not None and self._is_allowed_address(addr)
+            for raw in addresses
+        )
+
+    def _is_allowed_address(self, address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+        return any(address in network for network in self._networks)
+
+    @staticmethod
+    def _as_ip(value: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+        try:
+            return ipaddress.ip_address(value)
+        except ValueError:
+            return None

canonic/cli/_errors.py

@@ -0,0 +1,112 @@
+"""Shared CLI plumbing: the global context object and structured error handling.
+
+Adapters do transport translation only (SPEC §2.1): here we turn a raised
+``CanonicError`` into the headless exit code from the canonical registry (§6.1) and
+print a structured ``{code, message}`` payload — JSON under ``--json``, Rich text
+otherwise — instead of leaking a traceback.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from canonic.exc import CanonicError
+from canonic.mcp.errors import error_payload
+
+_err_console = Console(stderr=True)
+
+
+@dataclass
+class CliContext:
+    """Per-invocation state shared from the root callback to every subcommand."""
+
+    json_output: bool = False
+
+
+def get_cli_context(ctx: typer.Context) -> CliContext:
+    """Return the ``CliContext`` for this invocation, creating a default if absent."""
+    if not isinstance(ctx.obj, CliContext):
+        ctx.obj = CliContext()
+    return ctx.obj
+
+
+def emit_error(err: CanonicError, *, json_output: bool) -> None:
+    """Print a structured error to stderr in the requested format.
+
+    Reuses :func:`canonic.mcp.errors.error_payload` for the wire shape so the CLI's
+    ``--json`` output — including ``candidates`` — stays byte-for-byte consistent
+    with the MCP adapter (adapter parity, SPEC §2.1), rather than reimplementing a
+    second, looser candidate serialization.
+    """
+    payload = error_payload(err)
+    if not payload["message"]:
+        payload["message"] = err.__class__.__name__
+    # ASSERTION_FAILED carries which check diverged (SPEC-Fuller-E15 §3.3).
+    assertion_id = getattr(err, "assertion_id", None)
+    if assertion_id is not None:
+        payload["assertion_id"] = assertion_id
+    if json_output:
+        sys.stderr.write(json.dumps(payload) + "\n")
+        return
+
+    _err_console.print(f"[red]error[/red] [bold]{payload['code']}[/bold]: {payload['message']}")
+    candidates = err.candidates
+    if not candidates:
+        return
+    for i, c in enumerate(candidates, 1):
+        if hasattr(c, "route"):
+            _err_console.print(f"  path {i}: {c.route}", markup=False)
+            _err_console.print(f"    via: {c.via}", markup=False)
+        elif isinstance(c, (list, tuple)):
+            owner = getattr(err, "owner", "")
+            prefix = f"{owner} → " if owner else ""
+            _err_console.print(f"  path {i}: {prefix}{' → '.join(c)}", markup=False)
+        elif hasattr(c, "metric"):
+            _err_console.print(f"  candidate {i}: {c.metric}", markup=False)
+        else:
+            _err_console.print(f"  candidate {i}: {c}", markup=False)
+    if hasattr(candidates[0], "via"):
+        _err_console.print(
+            '  hint: re-issue with "via": <chosen path\'s via list> to select a path',
+            markup=False,
+        )
+    elif isinstance(candidates[0], (list, tuple)):
+        _err_console.print(
+            '  hint: add "via": ["<first-hop>"] to your query to select a path',
+            markup=False,
+        )
+    elif isinstance(candidates[0], str):
+        _err_console.print(
+            f"  hint: qualify with one of the candidates above, e.g. --dimensions {candidates[0]}",
+            markup=False,
+        )
+
+
+def handle_errors[F: Callable[..., Any]](func: F) -> F:
+    """Wrap a command so a raised ``CanonicError`` becomes a structured exit.
+
+    The wrapped command must declare a ``ctx: typer.Context`` parameter so the
+    handler can read ``--json`` mode from the shared ``CliContext``.
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        ctx = kwargs.get("ctx")
+        if ctx is None:
+            ctx = next((a for a in args if isinstance(a, typer.Context)), None)
+        json_output = get_cli_context(ctx).json_output if ctx is not None else False
+        try:
+            return func(*args, **kwargs)
+        except CanonicError as err:
+            emit_error(err, json_output=json_output)
+            raise typer.Exit(err.exit_code) from err
+
+    return wrapper  # type: ignore[return-value]

canonic/cli/app.py

@@ -0,0 +1,106 @@
+"""Root Typer application for the ``canonic`` CLI (E7 serving surface).
+
+This adapter does transport translation only (SPEC §2.1): it parses options,
+selects output format (``--json``), and dispatches to capability commands. All
+real logic lives behind the core in later epics.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Annotated
+
+import typer
+
+from canonic.cli._errors import get_cli_context
+from canonic.cli.commands import (
+    apply,
+    assertions,
+    completion,
+    connection,
+    evaluate,
+    ingest,
+    knowledge,
+    mcp,
+    outcome,
+    overview,
+    query,
+    report,
+    review,
+    setup,
+    sl,
+    sql,
+    status,
+)
+
+app = typer.Typer(
+    name="canonic",
+    help="The Open Context Layer for Data Agents.",
+    add_completion=False,
+    no_args_is_help=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    try:
+        typer.echo(version("canonic"))
+    except PackageNotFoundError:  # pragma: no cover — only when running uninstalled
+        typer.echo("unknown")
+    raise typer.Exit(0)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", "-j", help="Emit raw structured JSON instead of formatted text."),
+    ] = False,
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show the canonic version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Canonic CLI entry point: sets global flags and dispatches subcommands."""
+    get_cli_context(ctx).json_output = json_output
+
+    from canonic.log import _effective_log_params, configure_logging
+
+    level, file, format = _effective_log_params("WARNING", None)
+    configure_logging(level=level, file=file, format=format)
+
+    if ctx.invoked_subcommand is None:
+        if json_output:
+            typer.echo("interactive mode is not available with --json; run `canonic --help`.")
+            raise typer.Exit(2)
+        from canonic.cli.commands.setup import run_interactive
+
+        run_interactive()
+        raise typer.Exit(0)
+
+
+# Command groups (multi-command).
+app.add_typer(connection.app, name="connection")
+app.add_typer(sl.app, name="sl")
+app.add_typer(mcp.app, name="mcp")
+app.add_typer(knowledge.app, name="knowledge")
+app.add_typer(evaluate.app, name="eval")
+app.add_typer(outcome.app, name="outcome")
+
+# Top-level single commands.
+app.command("overview")(overview.overview)
+app.command("setup")(setup.setup)
+app.command("ingest")(ingest.ingest)
+app.command("review")(review.review)
+app.command("apply")(apply.apply)
+app.command("query")(query.query)
+app.command("assert")(assertions.assert_)
+app.command("sql")(sql.sql)
+app.command("status")(status.status)
+app.command("report")(report.report)
+app.command("completion")(completion.completion)

canonic/cli/commands/__init__.py

@@ -0,0 +1,105 @@
+"""CLI subcommand groups. Each module exposes a ``typer.Typer()`` named ``app``."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+import typer
+from rich.console import Console
+
+from canonic.cli._errors import get_cli_context
+from canonic.compiler import SemanticQuery
+from canonic.compiler.query import parse_filter_flag
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from canonic.core.service import CanonicService
+
+_console = Console()
+
+
+def not_implemented(ctx: typer.Context, feature: str) -> None:
+    """Print a uniform ``not implemented yet`` notice and exit 0 (no traceback).
+
+    Stub for capability commands whose logic lands in later epics (E2/E5/E6/E8/E9).
+    """
+    json_output = get_cli_context(ctx).json_output
+    if json_output:
+        typer.echo(json.dumps({"status": "not_implemented", "feature": feature}))
+    else:
+        _console.print(f"[yellow]{feature}[/yellow]: not implemented yet")
+    raise typer.Exit(0)
+
+
+def load_service(ctx: typer.Context) -> CanonicService:
+    """Locate the enclosing canonic project and build its :class:`CanonicService`.
+
+    Capability commands (``query``, ``sql``) share this so project discovery and
+    service wiring live in one place. Exits 1 with a clear message — not a
+    traceback — when run outside a project.
+    """
+    from canonic.config import find_project_root
+    from canonic.core.service import CanonicService
+
+    root = find_project_root()
+    if root is None:
+        msg = "no canonic project found; run from inside a project directory"
+        if get_cli_context(ctx).json_output:
+            typer.echo(json.dumps({"error": msg}))
+        else:
+            _console.print(f"[red]error:[/red] {msg}")
+        raise typer.Exit(1)
+
+    try:
+        from canonic.config import load_config
+        from canonic.log import _effective_log_params, configure_logging
+
+        cfg = load_config(root / "canonic.yaml")
+        level, file, format = _effective_log_params(
+            cfg.logging.level, cfg.logging.file, cfg.logging.format
+        )
+        configure_logging(level=level, file=file, format=format)
+    except Exception:
+        pass  # CanonicService.from_project below will fail with a clearer error if config is broken
+
+    return CanonicService.from_project(root)
+
+
+def _expand_csv(values: list[str] | None) -> list[str]:
+    """Flatten repeated and/or comma-separated ``--flag`` occurrences into one list."""
+    return [v.strip() for item in values or [] for v in item.split(",") if v.strip()]
+
+
+def build_semantic_query(
+    file: Path | None,
+    metrics: list[str] | None,
+    dimensions: list[str] | None,
+    filters: list[str] | None,
+) -> SemanticQuery:
+    """Build a :class:`SemanticQuery` from ``-f``/``--file`` or the inline flag set.
+
+    Exactly one of the two input modes must be used — ``query``/``sl compile`` share
+    this so both commands resolve flags to the identical object the JSON-file path
+    would deserialize (SPEC-E7-E8 §3, S14).
+    """
+    flags_given = bool(metrics or dimensions or filters)
+    if file is not None and flags_given:
+        raise typer.BadParameter(
+            "-f/--file and --metrics/--dimensions/--filter are mutually exclusive"
+        )
+    if file is None and not flags_given:
+        raise typer.BadParameter("either -f/--file or --metrics is required")
+
+    if file is not None:
+        return SemanticQuery.model_validate_json(file.read_text())
+
+    try:
+        parsed_filters = [parse_filter_flag(f) for f in filters or []]
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    return SemanticQuery(
+        metrics=_expand_csv(metrics), dimensions=_expand_csv(dimensions), filters=parsed_filters
+    )

canonic/cli/commands/apply.py

@@ -0,0 +1,88 @@
+"""``canonic apply`` — batch-apply pending proposals after manual diff editing (GH-150, E7 §3).
+
+Reads ``status.yaml`` from the given run directory and applies every proposal still marked
+``pending``.  Proposals whose diff file the user deleted, or that are already in a terminal
+state (accepted / rejected / frozen), are silently skipped.  No git interaction (E4 §6).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from canonic.cli._errors import handle_errors
+from canonic.cli.commands import _console
+from canonic.config import find_project_root
+from canonic.ingestion.pending import (
+    PendingProposalEntry,
+    PendingRun,
+    ProposalStatus,
+    apply_entry,
+    update_status,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@handle_errors
+def apply(
+    run_dir: Annotated[
+        Path,
+        typer.Argument(help="Path to the pending-diff run directory to apply."),
+    ],
+) -> None:
+    """Batch-apply all pending proposals from a run directory.
+
+    Skips proposals already in a terminal state or whose diff file has been deleted.
+    No git interaction — applied files appear as unstaged changes.
+    """
+    root = find_project_root()
+    if root is None:
+        _console.print(
+            "[red]error:[/red] no canonic project found — run from inside a project directory"
+        )
+        raise typer.Exit(1)
+
+    run_dir = run_dir.resolve()
+    if not run_dir.is_dir():
+        _console.print(f"[red]error:[/red] run directory not found: {run_dir}")
+        raise typer.Exit(1)
+
+    run = PendingRun.load(run_dir)
+    logger.info("apply: run_dir=%s proposals=%d", run_dir.name, len(run.proposals))
+
+    applied = 0
+    skipped = 0
+    updated: list[PendingProposalEntry] = list(run.proposals)
+
+    for proposal in run.proposals:
+        if proposal.status is not ProposalStatus.PENDING:
+            logger.debug(
+                "apply: skipping proposal=%s target=%s (status=%s)",
+                proposal.id,
+                proposal.target,
+                proposal.status.value,
+            )
+            skipped += 1
+            continue
+        if not Path(proposal.diff_file).exists():
+            logger.debug(
+                "apply: skipping proposal=%s target=%s (diff file missing)",
+                proposal.id,
+                proposal.target,
+            )
+            skipped += 1
+            continue
+
+        apply_entry(root, run, proposal)
+        logger.debug("apply: applied proposal=%s target=%s", proposal.id, proposal.target)
+        i = next(j for j, p in enumerate(updated) if p.id == proposal.id)
+        updated[i] = proposal.model_copy(update={"status": ProposalStatus.ACCEPTED})
+        applied += 1
+
+    update_status(run_dir, updated)
+    logger.info("apply complete: applied=%d skipped=%d", applied, skipped)
+    _console.print(f"[green]applied {applied}[/green], skipped {skipped}")

canonic/cli/commands/assertions.py

@@ -0,0 +1,101 @@
+"""``canonic assert`` — the accuracy harness CI gate (SPEC-Fuller-E15 §3.4, GH-110).
+
+Runs the labeled assertion set through the compiler, compares each result to its expectation
+within tolerance, and reports ``accuracy = passed / total``. This is the E16 integration that
+turns ">90% accuracy" from aspirational to measured. Used as a CI gate: an accuracy regression
+below ``--min-accuracy`` exits 10 (``ASSERTION_FAILED``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+
+from canonic.cli._errors import get_cli_context, handle_errors
+from canonic.cli.commands import load_service
+from canonic.exc import AssertionFailed
+
+if TYPE_CHECKING:
+    from canonic.contracts.assertions import AccuracyReport
+
+_console = Console()
+
+
+@handle_errors
+def assert_(
+    ctx: typer.Context,
+    min_accuracy: Annotated[
+        float,
+        typer.Option(
+            "--min-accuracy",
+            help="Accuracy floor for the CI gate; below it exits 10 (ASSERTION_FAILED).",
+            min=0.0,
+            max=1.0,
+        ),
+    ] = 1.0,
+    baseline: Annotated[
+        bool,
+        typer.Option(
+            "--baseline",
+            help="Also run the schema-only baseline and report the lift (SPEC-E16 Part 2 §2).",
+        ),
+    ] = False,
+) -> None:
+    """Run the accuracy harness over all loaded assertions and gate on the result.
+
+    Every executable assertion in ``contracts/assertions/`` is compiled, executed read-only,
+    and compared to its expected value within ``tolerance``. The harness reports
+    ``accuracy = correct / total``; when it drops below ``--min-accuracy`` (default ``1.0`` —
+    every assertion must hold), the command exits 10 with the diverging checks, so a regression
+    fails CI. With ``--baseline``, the same assertions also run against a schema-only resolver
+    (no curated bindings/aliases/guardrails) so the accuracy lift from canon's context layer is
+    measured, not asserted; the gate still applies to the canon accuracy only.
+    """
+    service = load_service(ctx)
+    report = asyncio.run(service.run_accuracy_harness())
+    baseline_report: AccuracyReport | None = None
+    if baseline:
+        baseline_report = asyncio.run(service.run_accuracy_baseline())
+
+    if get_cli_context(ctx).json_output:
+        payload = report.to_dict()
+        if baseline_report is not None:
+            payload["baseline"] = baseline_report.to_dict()
+            payload["lift"] = report.accuracy - baseline_report.accuracy
+        typer.echo(json.dumps(payload))
+    else:
+        _render(report)
+        if baseline_report is not None:
+            _render_baseline(report, baseline_report)
+
+    if report.accuracy < min_accuracy:
+        first = report.failures[0] if report.failures else None
+        raise AssertionFailed(
+            f"accuracy {report.accuracy:.1%} below target {min_accuracy:.1%} "
+            f"({report.passed}/{report.total} assertions passed)",
+            assertion_id=first.assertion_id if first is not None else None,
+        )
+
+
+def _render(report: AccuracyReport) -> None:
+    """Print a human-readable accuracy summary and any diverging assertions."""
+    _console.print(
+        f"accuracy [bold]{report.accuracy:.1%}[/bold] "
+        f"({report.passed}/{report.total} assertions passed)"
+    )
+    for failure in report.failures:
+        _console.print(f"  [red]✗[/red] {failure.detail}")
+
+
+def _render_baseline(report: AccuracyReport, baseline_report: AccuracyReport) -> None:
+    """Print the schema-only baseline accuracy and the lift over it."""
+    lift = report.accuracy - baseline_report.accuracy
+    _console.print(
+        f"baseline (schema-only) [bold]{baseline_report.accuracy:.1%}[/bold] "
+        f"({baseline_report.passed}/{baseline_report.total} assertions passed)"
+    )
+    _console.print(f"lift: [bold]{lift:+.1%}[/bold]")

canonic/cli/commands/completion.py

@@ -0,0 +1,10 @@
+"""``canonic completion`` — shell completion (stub)."""
+
+import typer
+
+from canonic.cli.commands import not_implemented
+
+
+def completion(ctx: typer.Context) -> None:
+    """Generate shell completion script."""
+    not_implemented(ctx, "completion")