pretensor 0.1.0__py3-none-any.whl

pretensor/cli/commands/semantic.py

@@ -0,0 +1,190 @@
+"""``pretensor semantic`` command group — compile YAML metrics to SQL."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from pretensor.cli import constants as cli_constants
+from pretensor.cli.config_file import get_cli_config, resolve_path_option
+from pretensor.introspection.models.semantic import (
+    SemanticLayer as SemanticLayerModel,
+)
+from pretensor.mcp.service_registry import (
+    load_registry,
+    open_store_for_entry,
+    resolve_registry_entry,
+)
+from pretensor.semantic.compiler import MetricCompileError, MetricSqlCompiler
+
+__all__ = ["register_semantic_commands"]
+
+
+_EXIT_INVALID = 1
+_EXIT_BAD_ARGS = 2
+
+
+def register_semantic_commands(app: typer.Typer, *, console: Console) -> None:
+    """Register ``pretensor semantic compile`` onto ``app``."""
+    semantic_app = typer.Typer(
+        name="semantic",
+        help="Compile and inspect user-authored semantic layers (OSS).",
+        no_args_is_help=True,
+    )
+
+    @semantic_app.command("compile")
+    def compile_command(
+        yaml_path: Path = typer.Argument(
+            ...,
+            help="Path to a semantic layer YAML file.",
+            exists=True,
+            dir_okay=False,
+            resolve_path=True,
+        ),
+        metric: str = typer.Option(
+            ...,
+            "--metric",
+            help="Name of the metric to compile.",
+        ),
+        db: str | None = typer.Option(
+            None,
+            "--db",
+            help="connection_name or logical database; omit if only one is indexed.",
+        ),
+        state_dir: Path = typer.Option(
+            cli_constants.DEFAULT_STATE_DIR,
+            "--state-dir",
+            help="Directory containing registry.json.",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+        as_json: bool = typer.Option(
+            False,
+            "--json",
+            help="Emit machine-readable JSON instead of a rich panel.",
+        ),
+        ctx: typer.Context = typer.Option(None, hidden=True),
+    ) -> None:
+        """Compile a YAML metric to SQL and validate it against the graph."""
+        cli_config = get_cli_config(ctx)
+        state_dir = resolve_path_option(
+            ctx,
+            param_name="state_dir",
+            cli_value=state_dir,
+            config_value=cli_config.state_dir,
+        )
+
+        reg = load_registry(state_dir)
+        entry = resolve_registry_entry(reg, db)
+        if entry is None:
+            msg = (
+                f"no registry entry matches --db {db!r}"
+                if db is not None
+                else "multiple indexed databases — pass --db"
+            )
+            console.print(f"[red]{msg}[/red]")
+            raise typer.Exit(_EXIT_BAD_ARGS)
+
+        try:
+            layer = SemanticLayerModel.from_yaml(
+                yaml_path.read_text(encoding="utf-8")
+            )
+        except Exception as exc:
+            console.print(f"[red]Failed to parse {yaml_path}:[/red] {exc}")
+            raise typer.Exit(_EXIT_BAD_ARGS) from exc
+
+        if layer.connection_name != entry.connection_name and (
+            layer.connection_name != entry.database
+        ):
+            console.print(
+                f"[yellow]Warning: YAML connection_name {layer.connection_name!r} "
+                f"does not match registry entry "
+                f"({entry.connection_name!r} / {entry.database!r}).[/yellow]"
+            )
+
+        store = open_store_for_entry(entry)
+        try:
+            compiler = MetricSqlCompiler(
+                store,
+                connection_name=entry.connection_name,
+                database_key=entry.database,
+            )
+            try:
+                compiled = compiler.compile(layer, metric)
+            except MetricCompileError as exc:
+                if as_json:
+                    typer.echo(json.dumps({"error": str(exc)}))
+                else:
+                    console.print(f"[red]Compile error:[/red] {exc}")
+                raise typer.Exit(_EXIT_BAD_ARGS) from exc
+
+            if as_json:
+                payload: dict[str, object] = {
+                    "metric": compiled.metric,
+                    "entity": compiled.entity,
+                    "sql": compiled.sql,
+                    "dialect": compiled.dialect,
+                    "warnings": compiled.warnings,
+                    "valid": compiled.validation.valid,
+                    "syntax_errors": compiled.validation.syntax_errors,
+                    "missing_tables": compiled.validation.missing_tables,
+                    "missing_columns": compiled.validation.missing_columns,
+                    "invalid_joins": [
+                        {
+                            "message": j.message,
+                            "left_table": j.left_table,
+                            "right_table": j.right_table,
+                        }
+                        for j in compiled.validation.invalid_joins
+                    ],
+                    "suggestions": compiled.validation.suggestions,
+                }
+                typer.echo(json.dumps(payload, indent=2))
+            else:
+                valid_label = (
+                    "[green]valid[/green]"
+                    if compiled.validation.valid
+                    else "[red]invalid[/red]"
+                )
+                lines = [
+                    f"[bold]Entity:[/bold] {compiled.entity}",
+                    f"[bold]Dialect:[/bold] {compiled.dialect}",
+                    f"[bold]Valid:[/bold] {valid_label}",
+                    "",
+                    "[bold]SQL[/bold]",
+                    compiled.sql,
+                ]
+                if compiled.warnings:
+                    lines.append("")
+                    lines.append("[bold]Warnings[/bold]")
+                    lines.extend(f"  - {w}" for w in compiled.warnings)
+                if not compiled.validation.valid:
+                    lines.append("")
+                    lines.append("[bold]Validation errors[/bold]")
+                    for err in compiled.validation.syntax_errors:
+                        lines.append(f"  - syntax: {err}")
+                    for t in compiled.validation.missing_tables:
+                        lines.append(f"  - missing_table: {t}")
+                    for c in compiled.validation.missing_columns:
+                        lines.append(f"  - missing_column: {c}")
+                    for j in compiled.validation.invalid_joins:
+                        lines.append(f"  - invalid_join: {j.message}")
+                if compiled.validation.suggestions:
+                    lines.append("")
+                    lines.append("[bold]Suggestions[/bold]")
+                    lines.extend(f"  - {s}" for s in compiled.validation.suggestions)
+                console.print(
+                    Panel("\n".join(lines), title=f"metric: {compiled.metric}")
+                )
+
+            if not compiled.validation.valid:
+                raise typer.Exit(_EXIT_INVALID)
+        finally:
+            store.close()
+
+    app.add_typer(semantic_app)

pretensor/cli/commands/serve.py

@@ -0,0 +1,144 @@
+"""``pretensor serve`` — MCP stdio server + client config snippet."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from pretensor.cli.config_file import (
+    get_cli_config,
+    resolve_aliased_path_option,
+    resolve_optional_path_option,
+    resolve_optional_str_option,
+)
+from pretensor.config import PretensorConfig
+from pretensor.mcp.server import print_mcp_config, run_server
+from pretensor.mcp.service import mcp_config_json
+from pretensor.visibility.config import default_visibility_path
+
+console = Console()
+
+
+def register_serve_command(app: typer.Typer) -> None:
+    """Attach ``serve`` to the root Typer app."""
+
+    @app.command("serve")
+    def serve_command(
+        state_dir: Path = typer.Option(
+            Path(".pretensor"),
+            "--state-dir",
+            help="State directory (registry.json, graphs/, search index).",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+        graph_dir: Path | None = typer.Option(
+            None,
+            "--graph-dir",
+            hidden=True,
+            help="Deprecated alias for --state-dir.",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+        visibility_file: Path | None = typer.Option(
+            None,
+            "--visibility",
+            help="Path to visibility.yml (default: <graph-dir>/visibility.yml).",
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
+        ),
+        profile: str | None = typer.Option(
+            None,
+            "--profile",
+            help="Named visibility profile from visibility.yml (serve-time filter).",
+        ),
+        config_only: bool = typer.Option(
+            False,
+            "--config-only",
+            help="Print mcpServers JSON to stdout and exit (for piping).",
+        ),
+        print_config: bool = typer.Option(
+            True,
+            "--print-config/--no-print-config",
+            help="When starting the server, also print the mcpServers JSON (to stderr by default).",
+        ),
+        ctx: typer.Context = typer.Option(None, hidden=True),
+    ) -> None:
+        """Run the Pretensor MCP server on stdio (JSON-RPC over stdout).
+
+        The MCP protocol uses stdout for JSON-RPC. The Claude/Cursor ``mcpServers``
+        snippet is printed to **stderr** by default so it does not corrupt the
+        protocol stream. Use ``--config-only`` to print the snippet to stdout and exit.
+        """
+        cli_config = get_cli_config(ctx)
+        state_dir = resolve_aliased_path_option(
+            ctx,
+            primary_param="state_dir",
+            primary_value=state_dir,
+            alias_param="graph_dir",
+            alias_value=graph_dir,
+            config_value=cli_config.state_dir,
+        ).resolve()
+        visibility_file = resolve_optional_path_option(
+            ctx,
+            param_name="visibility_file",
+            cli_value=visibility_file,
+            config_value=(
+                cli_config.visibility.path
+                if cli_config.visibility.path is not None
+                else default_visibility_path(state_dir)
+            ),
+        )
+        profile = resolve_optional_str_option(
+            ctx,
+            param_name="profile",
+            cli_value=profile,
+            config_value=cli_config.visibility.profile,
+        )
+        vis_path = Path(visibility_file) if visibility_file is not None else None
+        if profile is not None and not str(profile).strip():
+            profile = None
+        if config_only:
+            try:
+                sys.stdout.write(mcp_config_json(state_dir) + "\n")
+                sys.stdout.flush()
+            except Exception as e:
+                console.print(f"[red]Failed to generate config JSON:[/red] {e}")
+                raise typer.Exit(1) from e
+            return
+        if print_config:
+            try:
+                print_mcp_config(state_dir, stream=sys.stderr)
+            except Exception:
+                pass
+            Console(file=sys.stderr).print(
+                "[dim]MCP JSON-RPC on stdout — stderr above is config only.[/dim]",
+            )
+        # Startup/runtime errors must go to stderr: stdout is the JSON-RPC
+        # protocol channel, and MCP clients surface stderr — not stdout — in
+        # their logs, so an error printed to stdout reads as a silent crash.
+        err_console = Console(file=sys.stderr)
+        try:
+            run_server(
+                state_dir,
+                visibility_path=vis_path,
+                profile=profile,
+                config=PretensorConfig(graph=cli_config.graph),
+            )
+        except ValueError as e:
+            err_console.print(f"[red]{e}[/red]")
+            raise typer.Exit(1) from e
+        except PermissionError as e:
+            err_console.print(
+                f"[red]Permission denied accessing state directory:[/red] {e}\n"
+                "Check read permissions on the --state-dir path."
+            )
+            raise typer.Exit(1) from e
+        except Exception as e:
+            err_console.print(f"[red]MCP server error:[/red] {e}")
+            raise typer.Exit(1) from e

pretensor/cli/commands/sync_grants.py

@@ -0,0 +1,149 @@
+"""``pretensor sync-grants`` — generate ``visibility.yml`` profiles from DB grants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from pretensor.cli.config_file import (
+    get_cli_config,
+    resolve_optional_str_option,
+    resolve_path_option,
+)
+from pretensor.cli.paths import default_connection_name
+from pretensor.connectors.registry import get_connector
+from pretensor.introspection.models.config import DatabaseType
+from pretensor.introspection.models.dsn import (
+    connection_config_from_url,
+    infer_database_type_from_dsn,
+)
+from pretensor.visibility.sync_grants import run_sync_grants
+
+console = Console()
+
+
+def _parse_roles_option(raw: str | None) -> frozenset[str] | None:
+    if raw is None or not str(raw).strip():
+        return None
+    parts = [p.strip() for p in str(raw).split(",")]
+    names = {p for p in parts if p}
+    return frozenset(names) if names else None
+
+
+def register_sync_grants_command(app: typer.Typer) -> None:
+    """Attach ``sync-grants`` to the root Typer app."""
+
+    @app.command("sync-grants")
+    def sync_grants_command(
+        dsn: str = typer.Option(
+            ...,
+            "--dsn",
+            help="Admin-capable database URL (postgresql:// or snowflake://).",
+        ),
+        name: str | None = typer.Option(
+            None,
+            "--name",
+            "-n",
+            help=(
+                "Logical connection name (defaults to the database name from the DSN). "
+                "Must match the value used with ``pretensor index`` so generated "
+                "``connection::schema.table`` patterns match at serve time."
+            ),
+        ),
+        output: Path = typer.Option(
+            Path(".pretensor") / "visibility.yml",
+            "--output",
+            help="Destination visibility.yml path.",
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
+        ),
+        roles: str | None = typer.Option(
+            None,
+            "--roles",
+            help="Comma-separated DB role names to sync (omit to sync all grantees).",
+        ),
+        ctx: typer.Context = typer.Option(None, hidden=True),
+    ) -> None:
+        """Write or merge ``profiles`` with ``allowed_tables`` from SELECT table grants."""
+        cli_config = get_cli_config(ctx)
+        configured_output = cli_config.visibility.path
+        if configured_output is None and cli_config.state_dir is not None:
+            configured_output = cli_config.state_dir / "visibility.yml"
+        output = resolve_path_option(
+            ctx,
+            param_name="output",
+            cli_value=output,
+            config_value=configured_output,
+        )
+        name = resolve_optional_str_option(
+            ctx,
+            param_name="name",
+            cli_value=name,
+            config_value=cli_config.connection_defaults.name,
+        )
+        raw_dsn = dsn.strip()
+        try:
+            db_type = infer_database_type_from_dsn(raw_dsn)
+        except ValueError as exc:
+            console.print(f"[red]Invalid DSN:[/red] {exc}")
+            raise typer.Exit(1) from exc
+        if db_type == DatabaseType.BIGQUERY:
+            console.print(
+                "[red]sync-grants does not support BigQuery in v1 "
+                "(IAM grants are out of scope).[/red]",
+            )
+            raise typer.Exit(1)
+
+        try:
+            connection_name = name or default_connection_name(raw_dsn)
+        except ValueError as exc:
+            console.print(f"[red]Invalid DSN:[/red] {exc}")
+            raise typer.Exit(1) from exc
+        try:
+            cfg = connection_config_from_url(raw_dsn, connection_name)
+        except ValueError as exc:
+            console.print(f"[red]Invalid DSN:[/red] {exc}")
+            raise typer.Exit(1) from exc
+        roles_filter = _parse_roles_option(roles)
+
+        try:
+            with get_connector(cfg) as connector:
+                grantee_count = run_sync_grants(
+                    connector,
+                    output_path=output.resolve(),
+                    connection_name=connection_name,
+                    roles_filter=roles_filter,
+                )
+        except ValueError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(1) from exc
+        except ImportError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(1) from exc
+        except PermissionError as exc:
+            console.print(
+                f"[red]Cannot write visibility file {output}:[/red] {exc}\n"
+                "Check write permissions on the output path."
+            )
+            raise typer.Exit(1) from exc
+        except Exception as exc:
+            console.print(
+                f"[red]Cannot connect to database:[/red] {exc}\n"
+                "Check that the DSN is correct and the database is reachable."
+            )
+            raise typer.Exit(1) from exc
+
+        if grantee_count == 0:
+            console.print(
+                "[yellow]No SELECT grants returned by the connector.[/yellow] "
+                "The DB role used for --dsn may lack catalog access, or the database "
+                "has no non-PUBLIC grants. visibility.yml was still written (merged "
+                "with any existing base rules).",
+            )
+        console.print(
+            f"[green]Wrote merged visibility rules to[/green] {output.resolve()} "
+            f"({grantee_count} grantee profile(s))",
+        )

pretensor/cli/commands/validate.py

@@ -0,0 +1,176 @@
+"""``pretensor validate`` — sqlglot + graph SQL validation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from pretensor.cli import constants as cli_constants
+from pretensor.cli.config_file import get_cli_config, resolve_aliased_path_option
+from pretensor.mcp.service_registry import (
+    load_registry,
+    open_store_for_entry,
+    resolve_registry_entry,
+)
+from pretensor.validation.query_validator import QueryValidator
+
+__all__ = ["register_validate_command"]
+
+
+_EXIT_INVALID = 1
+_EXIT_BAD_ARGS = 2
+
+
+def register_validate_command(app: typer.Typer, *, console: Console) -> None:
+    """Register ``pretensor validate`` onto ``app``."""
+
+    @app.command("validate")
+    def validate_command(
+        sql_or_path: str = typer.Argument(
+            ...,
+            help=(
+                "SQL text or path to a .sql file. If the argument names an "
+                "existing file, its contents are read."
+            ),
+        ),
+        database: str | None = typer.Option(
+            None,
+            "--database",
+            "-d",
+            help="connection_name or logical database; omit if only one is indexed.",
+        ),
+        db: str | None = typer.Option(
+            None,
+            "--db",
+            hidden=True,
+            help="Deprecated alias for --database/-d.",
+        ),
+        dialect: str = typer.Option(
+            "postgres",
+            "--dialect",
+            help="sqlglot dialect (default 'postgres').",
+        ),
+        state_dir: Path = typer.Option(
+            cli_constants.DEFAULT_STATE_DIR,
+            "--state-dir",
+            help="Directory containing registry.json.",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+        graph_dir: Path | None = typer.Option(
+            None,
+            "--graph-dir",
+            hidden=True,
+            help="Deprecated alias for --state-dir.",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+        as_json: bool = typer.Option(
+            False,
+            "--json",
+            help="Emit machine-readable JSON instead of a rich panel.",
+        ),
+        ctx: typer.Context = typer.Option(None, hidden=True),
+    ) -> None:
+        """Validate SQL against the indexed graph for one database."""
+        cli_config = get_cli_config(ctx)
+        if database is None and db is not None:
+            database = db
+        state_dir = resolve_aliased_path_option(
+            ctx,
+            primary_param="state_dir",
+            primary_value=state_dir,
+            alias_param="graph_dir",
+            alias_value=graph_dir,
+            config_value=cli_config.state_dir,
+        )
+
+        maybe_path = Path(sql_or_path)
+        if maybe_path.exists() and maybe_path.is_file():
+            sql_text = maybe_path.read_text(encoding="utf-8")
+        else:
+            sql_text = sql_or_path
+
+        if not sql_text.strip():
+            console.print("[red]Empty SQL input.[/red]")
+            raise typer.Exit(_EXIT_BAD_ARGS)
+
+        reg = load_registry(state_dir)
+        entry = resolve_registry_entry(reg, database)
+        if entry is None:
+            msg = (
+                f"no registry entry matches --database {database!r}"
+                if database is not None
+                else "multiple indexed databases — pass --database"
+            )
+            console.print(f"[red]{msg}[/red]")
+            raise typer.Exit(_EXIT_BAD_ARGS)
+
+        store = open_store_for_entry(entry)
+        try:
+            validator = QueryValidator(
+                store,
+                connection_name=entry.connection_name,
+                database_key=entry.database,
+                dialect=dialect,
+            )
+            result = validator.validate(sql_text)
+        finally:
+            store.close()
+
+        if as_json:
+            payload: dict[str, object] = {
+                "valid": result.valid,
+                "dialect": dialect,
+                "syntax_errors": result.syntax_errors,
+                "missing_tables": result.missing_tables,
+                "missing_columns": result.missing_columns,
+                "invalid_joins": [
+                    {
+                        "message": j.message,
+                        "left_table": j.left_table,
+                        "right_table": j.right_table,
+                    }
+                    for j in result.invalid_joins
+                ],
+                "suggestions": result.suggestions,
+            }
+            typer.echo(json.dumps(payload, indent=2))
+        else:
+            valid_label = (
+                "[green]valid[/green]" if result.valid else "[red]invalid[/red]"
+            )
+            lines = [
+                f"[bold]Dialect:[/bold] {dialect}",
+                f"[bold]Valid:[/bold] {valid_label}",
+            ]
+            if result.syntax_errors:
+                lines.append("")
+                lines.append("[bold]Syntax errors[/bold]")
+                lines.extend(f"  - {e}" for e in result.syntax_errors)
+            if result.missing_tables:
+                lines.append("")
+                lines.append("[bold]Missing tables[/bold]")
+                lines.extend(f"  - {t}" for t in result.missing_tables)
+            if result.missing_columns:
+                lines.append("")
+                lines.append("[bold]Missing columns[/bold]")
+                lines.extend(f"  - {c}" for c in result.missing_columns)
+            if result.invalid_joins:
+                lines.append("")
+                lines.append("[bold]Invalid joins[/bold]")
+                lines.extend(f"  - {j.message}" for j in result.invalid_joins)
+            if result.suggestions:
+                lines.append("")
+                lines.append("[bold]Suggestions[/bold]")
+                lines.extend(f"  - {s}" for s in result.suggestions)
+            console.print(Panel("\n".join(lines), title="validate_sql"))
+
+        if not result.valid:
+            raise typer.Exit(_EXIT_INVALID)