qcp-cli 0.1.5__py3-none-any.whl

qcp/__init__.py

@@ -0,0 +1,8 @@
+"""QCP package metadata."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("qcp-cli")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

qcp/agent.py

@@ -0,0 +1,165 @@
+"""LangChain database-agent orchestration for QCP commands."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol, TypeVar
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import after_model
+from langchain.messages import HumanMessage
+from langgraph.runtime import Runtime
+from pydantic import BaseModel, ValidationError
+
+from qcp.db import DatabaseClient
+from qcp.errors import LLMError, QcpError
+from qcp.llm import ChatModelFactory
+from qcp.memory import SchemaMemoryStore
+from qcp.models import (
+    AgentInsightsResponse,
+    AgentQueryResponse,
+    InsightsNarrative,
+    QueryNarrative,
+    QueryResult,
+)
+from qcp.tools import DatabaseToolkit, QcpAgentState
+
+SYSTEM_PROMPT = """You are QCP, a PostgreSQL data analyst for non-developers.
+Use tools sequentially and ground every claim in tool output.
+Always call schema_memory with operation=recall first. If it misses, call lookup_schema,
+then schema_memory with operation=store. Never invent tables, columns, SQL results, or insights.
+Only execute one SELECT or WITH query. Never request or attempt writes, DDL, or multiple statements.
+If execute_read_query reports stale schema, refresh, store, and retry exactly once.
+Keep final answers concise and understandable to a non-developer.
+"""
+
+QUERY_EXECUTION_RETRY_PROMPT = (
+    "Your previous response did not execute a query. QCP requires SQL and exact rows for every query command. "
+    "Use the schema already loaded, call execute_read_query now, and only then return the concise answer."
+)
+
+NarrativeModel = TypeVar("NarrativeModel", bound=BaseModel)
+
+
+class AgentInvoker(Protocol):
+    """Minimal invocation interface implemented by compiled LangChain graphs."""
+
+    def invoke(self, value: dict[str, Any]) -> Mapping[str, Any]:
+        """Invoke the compiled graph with an agent-state update."""
+
+
+def _query_execution_retry_update(state: QcpAgentState) -> dict[str, Any] | None:
+    """Return a one-time corrective state update when the model skips execution."""
+    if state.get("query_result") is not None or state.get("query_execution_retry_count", 0) >= 1:
+        return None
+    messages = state.get("messages", [])
+    if not messages or getattr(messages[-1], "tool_calls", None):
+        return None
+    return {
+        "messages": [HumanMessage(content=QUERY_EXECUTION_RETRY_PROMPT)],
+        "query_execution_retry_count": 1,
+        "jump_to": "model",
+    }
+
+
+@after_model(state_schema=QcpAgentState, can_jump_to=["model"])
+def require_query_execution(state: QcpAgentState, runtime: Runtime) -> dict[str, Any] | None:
+    """Give Gemini one corrective turn when it answers without executing SQL."""
+    del runtime
+    return _query_execution_retry_update(state)
+
+
+class DatabaseAgent:
+    """Coordinate LangChain agents while preserving exact tool artifacts."""
+
+    def __init__(
+        self,
+        database: DatabaseClient,
+        memory: SchemaMemoryStore,
+        model_factory: ChatModelFactory,
+    ) -> None:
+        """Initialize the agent with abstract infrastructure dependencies."""
+        self._database = database
+        self._memory = memory
+        self._model_factory = model_factory
+
+    def query(self, question: str, *, dry_run: bool = False) -> AgentQueryResponse:
+        """Answer a natural-language question using one read-only SQL query."""
+        agent = create_agent(
+            model=self._model_factory.create(),
+            tools=DatabaseToolkit(self._database, self._memory, dry_run=dry_run).build(),
+            system_prompt=SYSTEM_PROMPT,
+            state_schema=QcpAgentState,
+            response_format=QueryNarrative,
+            middleware=[require_query_execution],
+        )
+        prompt = (
+            f"Question: {question}\n"
+            "Find the schema, produce one PostgreSQL query, call execute_read_query, "
+            "then return a concise answer."
+        )
+        if dry_run:
+            prompt += " This is a dry run: validate and record the SQL with the tool, but do not claim any data result."
+        result = self._invoke(agent, prompt)
+        raw_query_result = result.get("query_result")
+        if raw_query_result is None:
+            raise LLMError("the agent finished without producing a SQL query result")
+        narrative = self._validate_narrative(QueryNarrative, result.get("structured_response"))
+        return AgentQueryResponse(
+            query_result=QueryResult.model_validate(raw_query_result),
+            answer=narrative.answer,
+        )
+
+    def insights(self, from_question: str | None = None) -> AgentInsightsResponse:
+        """Generate schema-grounded or query-grounded analytical suggestions."""
+        agent = create_agent(
+            model=self._model_factory.create(),
+            tools=DatabaseToolkit(self._database, self._memory).build(),
+            system_prompt=SYSTEM_PROMPT,
+            state_schema=QcpAgentState,
+            response_format=InsightsNarrative,
+        )
+        if from_question:
+            prompt = (
+                f"Generate insights for this focus: {from_question}\n"
+                "Load the schema, create and execute one relevant read query, call analyze_insights, "
+                "then return 3-6 grounded insights."
+            )
+        else:
+            prompt = (
+                "Load the schema, call analyze_insights without executing a query, "
+                "then return 3-6 concrete analyses the user could run next."
+            )
+        result = self._invoke(agent, prompt)
+        narrative = self._validate_narrative(InsightsNarrative, result.get("structured_response"))
+        raw_query_result = result.get("query_result")
+        query_result = QueryResult.model_validate(raw_query_result) if raw_query_result is not None else None
+        return AgentInsightsResponse(insights=narrative.insights, query_result=query_result)
+
+    @staticmethod
+    def _invoke(agent: AgentInvoker, prompt: str) -> dict[str, Any]:
+        """Invoke LangChain and normalize provider failures into QCP errors."""
+        try:
+            result = agent.invoke(
+                {
+                    "messages": [{"role": "user", "content": prompt}],
+                    "schema_snapshot": None,
+                    "query_result": None,
+                    "insight_context": None,
+                    "schema_retry_count": 0,
+                    "query_execution_retry_count": 0,
+                }
+            )
+        except QcpError:
+            raise
+        except Exception as error:
+            raise LLMError(str(error)) from error
+        return dict(result)
+
+    @staticmethod
+    def _validate_narrative(model: type[NarrativeModel], value: object) -> NarrativeModel:
+        """Convert invalid structured model output into a user-facing AI error."""
+        try:
+            return model.model_validate(value)
+        except ValidationError as error:
+            raise LLMError("the agent returned an invalid structured response") from error

qcp/cli.py

@@ -0,0 +1,191 @@
+"""qcp - Query Companion: a CLI to query Postgres in natural language."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from qcp import __version__, db, llm
+from qcp import config as cfg
+from qcp.agent import DatabaseAgent
+from qcp.db import PostgresDatabaseClient
+from qcp.errors import QcpError
+from qcp.llm import GeminiChatModelFactory
+from qcp.memory import JsonSchemaMemoryStore
+from qcp.output import format_table
+
+
+def _print_err(msg: str) -> None:
+    """Print a red error message to stderr."""
+    click.secho(msg, fg="red", err=True)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="qcp")
+def main() -> None:
+    """QCP - your CLI companion for querying Postgres in plain English."""
+
+
+@main.command()
+@click.option("--database-url", "-d", default=None, help="Postgres connection string. Prompted if omitted.")
+@click.option("--force", is_flag=True, help="Overwrite existing configuration without asking.")
+def init(database_url: str | None, force: bool) -> None:
+    """Connect QCP to a Postgres database."""
+    existing = cfg.get_db_url()
+    if (
+        existing
+        and not force
+        and not click.confirm(f"A database is already configured ({_mask(existing)}). Replace it?")
+    ):
+        click.echo("Keeping existing configuration.")
+        return
+
+    if not database_url:
+        click.echo("Enter your Postgres connection string, e.g.")
+        click.echo("  postgresql://user:password@host:5432/dbname")
+        database_url = click.prompt("Database URL", hide_input=True)
+
+    click.echo("Testing connection...")
+    db.test_connection(database_url)
+    cfg.set_key("database_url", database_url)
+    click.secho("Connected and saved.", fg="green")
+
+    if not cfg.get_gemini_api_key():
+        click.echo("\nTip: run `qcp auth` next to add your Gemini API key.")
+
+
+@main.command()
+@click.option("--key", "-k", default=None, help="Gemini API key. Prompted if omitted.")
+@click.option("--remove", is_flag=True, help="Remove the stored API key.")
+@click.option("--skip-validate", is_flag=True, help="Skip validating the key against Gemini.")
+@click.option("--model", default=None, help="Override the Gemini model (e.g. gemini-2.5-flash).")
+def auth(key: str | None, remove: bool, skip_validate: bool, model: str | None) -> None:
+    """Add (or remove) your Gemini API key."""
+    if remove:
+        cfg.unset_key("gemini_api_key")
+        click.secho("Removed stored Gemini API key.", fg="green")
+        return
+
+    if model:
+        cfg.set_key("gemini_model", model)
+        click.echo(f"Using model: {model}")
+
+    if not key:
+        click.echo("Get a free Gemini API key at https://aistudio.google.com/apikey")
+        key = click.prompt("Gemini API key", hide_input=True)
+
+    if not skip_validate:
+        click.echo("Validating key...")
+        ok, detail = llm.validate_api_key(key)
+        if not ok:
+            raise QcpError(
+                "That Gemini API key didn't validate "
+                f"(model: {llm.get_model()}).\n"
+                f"Reason: {detail}\n"
+                "Double-check the key, or re-run with --skip-validate to store it anyway."
+            )
+
+    cfg.set_key("gemini_api_key", key)
+    cfg.set_key("provider", "gemini")
+    click.secho("Gemini API key saved.", fg="green")
+
+
+@main.command()
+@click.argument("question", nargs=-1, required=True)
+@click.option("--show-sql/--no-show-sql", default=True, help="Print the generated SQL before running it.")
+@click.option("--dry-run", is_flag=True, help="Only generate and print SQL, don't execute it.")
+def query(question: tuple[str, ...], show_sql: bool, dry_run: bool) -> None:
+    """Ask a question about your data in plain English.
+
+    Example: qcp query "what were the top 5 products by revenue last month?"
+    """
+    question_text = " ".join(question)
+    db_url = db.require_db_url()
+
+    click.echo("Reading schema...")
+    click.echo("Running database agent...")
+    result = _create_agent(db_url).query(question_text, dry_run=dry_run)
+    sql = result.query_result.sql
+
+    if show_sql or dry_run:
+        click.secho("\n" + sql + "\n", fg="cyan")
+
+    if dry_run:
+        return
+
+    click.echo(format_table(result.query_result.columns, result.query_result.rows))
+    if result.query_result.truncated:
+        click.echo("\n(Result limited to 200 rows.)")
+    click.echo("\n" + result.answer)
+
+
+@main.command()
+@click.option(
+    "--from-question", default=None, help="Base insights on the results of this question instead of just the schema."
+)
+def insights(from_question: str | None) -> None:
+    """Get AI-generated analytics and insights about your database."""
+    db_url = db.require_db_url()
+    database_agent = _create_agent(db_url)
+    if from_question:
+        click.echo("Running a read query for your question...")
+
+    click.echo("Generating insights...")
+    result = database_agent.insights(from_question)
+    if result.query_result is not None:
+        click.secho("\n" + result.query_result.sql + "\n", fg="cyan")
+        click.echo(format_table(result.query_result.columns, result.query_result.rows) + "\n")
+    click.echo("\n" + "\n".join(f"- {insight}" for insight in result.insights))
+
+
+@main.command()
+def status() -> None:
+    """Show current QCP configuration."""
+    db_url = cfg.get_db_url()
+    api_key = cfg.get_gemini_api_key()
+    provider = cfg.get_provider()
+
+    click.echo(f"Config file:  {cfg.config_path()}")
+    click.echo(f"Database:     {_mask(db_url) if db_url else 'not configured (run `qcp init`)'}")
+    click.echo(f"AI provider:  {provider}")
+    click.echo(f"Model:        {llm.get_model()}")
+    click.echo(f"API key:      {'configured' if api_key else 'not configured (run `qcp auth`)'}")
+
+
+def _mask(url: str) -> str:
+    """Hide credentials in a connection string for display purposes."""
+    if "@" not in url:
+        return url
+    scheme_and_creds, host_part = url.rsplit("@", 1)
+    scheme = scheme_and_creds.split("://")[0]
+    return f"{scheme}://***@{host_part}"
+
+
+def _create_agent(database_url: str) -> DatabaseAgent:
+    """Construct the dependency-injected agent used by CLI commands."""
+    database = PostgresDatabaseClient(database_url)
+    model_factory = GeminiChatModelFactory(llm.require_api_key())
+    return DatabaseAgent(database, JsonSchemaMemoryStore(), model_factory)
+
+
+def run() -> None:
+    """Entry point used by the packaged console script."""
+    try:
+        main(standalone_mode=False)
+    except click.exceptions.Abort:
+        click.echo("\nAborted.")
+        sys.exit(1)
+    except click.ClickException as e:
+        e.show()
+        sys.exit(e.exit_code)
+    except QcpError as e:
+        _print_err(f"Error: {e}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        click.echo("\nAborted.")
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    run()

qcp/config.py

@@ -0,0 +1,85 @@
+"""Validated configuration storage for QCP."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from qcp.models import QcpConfig
+
+CONFIG_DIR = Path(os.environ.get("QCP_HOME", Path.home() / ".qcp"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_PROVIDER = "gemini"
+
+
+def _ensure_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with suppress(OSError):
+        os.chmod(CONFIG_DIR, stat.S_IRWXU)
+
+
+def load() -> dict[str, Any]:
+    """Load validated configuration, treating corrupt files as empty."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        raw_data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        return QcpConfig.model_validate(raw_data).model_dump(mode="json", exclude_none=True)
+    except json.JSONDecodeError, OSError, ValidationError:
+        return {}
+
+
+def save(data: dict[str, Any]) -> None:
+    """Validate and persist configuration with owner-only permissions."""
+    validated = QcpConfig.model_validate(data)
+    serialized = validated.model_dump(mode="json", exclude_none=True)
+    _ensure_dir()
+    CONFIG_FILE.write_text(json.dumps(serialized, indent=2), encoding="utf-8")
+    with suppress(OSError):
+        os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def get(key: str, default: Any = None) -> Any:
+    """Return a configuration value by its persisted key."""
+    return load().get(key, default)
+
+
+def set_key(key: str, value: Any) -> None:
+    """Set and validate one configuration value."""
+    data = load()
+    data[key] = value
+    save(data)
+
+
+def unset_key(key: str) -> None:
+    """Remove one configuration value when present."""
+    data = load()
+    if key in data:
+        del data[key]
+        save(data)
+
+
+def get_db_url() -> str | None:
+    """Resolve the database URL, preferring ``QCP_DATABASE_URL``."""
+    return os.environ.get("QCP_DATABASE_URL") or get("database_url")
+
+
+def get_gemini_api_key() -> str | None:
+    """Resolve the Gemini key, preferring ``GEMINI_API_KEY``."""
+    return os.environ.get("GEMINI_API_KEY") or get("gemini_api_key")
+
+
+def get_provider() -> str:
+    """Return the configured language-model provider."""
+    return str(get("provider", DEFAULT_PROVIDER))
+
+
+def config_path() -> str:
+    """Return the configuration path for status output."""
+    return str(CONFIG_FILE)

qcp/db.py

@@ -0,0 +1,176 @@
+"""PostgreSQL access with schema introspection and read-only enforcement."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+import psycopg
+from psycopg import Connection
+from psycopg.errors import InvalidSchemaName, UndefinedColumn, UndefinedTable
+
+from qcp import config as cfg
+from qcp.errors import (
+    DatabaseConnectionError,
+    NoDatabaseConfiguredError,
+    SchemaChangedError,
+    UnsafeQueryError,
+)
+from qcp.models import QueryResult, SchemaColumn, SchemaSnapshot, SchemaTable
+
+MAX_QUERY_ROWS = 200
+_READ_QUERY_PATTERN = re.compile(r"^\s*(select|with)\b", re.IGNORECASE)
+
+
+class DatabaseClient(ABC):
+    """Contract used by the database agent's PostgreSQL tools."""
+
+    @property
+    @abstractmethod
+    def database_id(self) -> str:
+        """Return a non-secret stable identifier for schema isolation."""
+
+    @abstractmethod
+    def test_connection(self) -> None:
+        """Raise an application error when the database cannot be reached."""
+
+    @abstractmethod
+    def lookup_schema(self) -> SchemaSnapshot:
+        """Read the public PostgreSQL schema."""
+
+    @abstractmethod
+    def execute_read_query(self, sql: str, limit: int = MAX_QUERY_ROWS) -> QueryResult:
+        """Execute one read-only query and return at most ``limit`` rows."""
+
+
+class PostgresDatabaseClient(DatabaseClient):
+    """Psycopg 3 implementation of the QCP database contract."""
+
+    def __init__(self, database_url: str) -> None:
+        """Initialize the client with a PostgreSQL connection string."""
+        self._database_url = database_url
+
+    @property
+    def database_id(self) -> str:
+        """Return a credential-safe identifier for the configured database."""
+        return hashlib.sha256(self._database_url.encode("utf-8")).hexdigest()[:16]
+
+    def _connect(self) -> Connection[Any]:
+        try:
+            return psycopg.connect(self._database_url, connect_timeout=10)
+        except Exception as error:
+            raise DatabaseConnectionError(str(error)) from error
+
+    def test_connection(self) -> None:
+        """Verify that PostgreSQL accepts the configured connection string."""
+        connection = self._connect()
+        connection.close()
+
+    def lookup_schema(self) -> SchemaSnapshot:
+        """Return tables and columns from the PostgreSQL public schema."""
+        sql = """
+            SELECT table_schema, table_name, column_name, data_type, is_nullable
+            FROM information_schema.columns
+            WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+              AND table_schema NOT LIKE 'pg_toast%'
+            ORDER BY table_schema, table_name, ordinal_position
+        """
+        connection = self._connect()
+        try:
+            with connection.cursor() as cursor:
+                cursor.execute(sql)
+                rows = cursor.fetchall()
+        except Exception as error:
+            raise DatabaseConnectionError(str(error)) from error
+        finally:
+            connection.close()
+
+        columns_by_table: dict[tuple[str, str], list[SchemaColumn]] = {}
+        for schema_name, table_name, column_name, data_type, is_nullable in rows:
+            table_key = (str(schema_name), str(table_name))
+            columns_by_table.setdefault(table_key, []).append(
+                SchemaColumn(name=str(column_name), data_type=str(data_type), nullable=is_nullable == "YES")
+            )
+        tables = [
+            SchemaTable(schema_name=schema_name, name=table_name, columns=columns)
+            for (schema_name, table_name), columns in columns_by_table.items()
+        ]
+        return SchemaSnapshot(database_id=self.database_id, captured_at=datetime.now(UTC), tables=tables)
+
+    def execute_read_query(self, sql: str, limit: int = MAX_QUERY_ROWS) -> QueryResult:
+        """Execute a single SELECT/CTE inside a read-only transaction."""
+        normalized_sql = normalize_read_query(sql)
+        connection = self._connect()
+        try:
+            connection.read_only = True
+            with connection.cursor() as cursor:
+                cursor.execute(normalized_sql.encode("utf-8"))
+                if cursor.description is None:
+                    raise UnsafeQueryError(normalized_sql)
+                columns = [_column_name(item) for item in cursor.description]
+                fetched_rows: Sequence[Sequence[Any]] = cursor.fetchmany(limit + 1)
+        except (UndefinedTable, UndefinedColumn, InvalidSchemaName) as error:
+            raise SchemaChangedError(str(error)) from error
+        except UnsafeQueryError, SchemaChangedError:
+            raise
+        except Exception as error:
+            raise DatabaseConnectionError(str(error)) from error
+        finally:
+            connection.close()
+
+        truncated = len(fetched_rows) > limit
+        rows = [list(row) for row in fetched_rows[:limit]]
+        return QueryResult(sql=normalized_sql, columns=columns, rows=rows, truncated=truncated)
+
+
+def _column_name(description: Any) -> str:
+    """Read a column name from Psycopg or a DB-API-compatible test double."""
+    return str(description.name if hasattr(description, "name") else description[0])
+
+
+def normalize_read_query(sql: str) -> str:
+    """Validate and normalize a single PostgreSQL SELECT or WITH statement."""
+    normalized = sql.strip()
+    if normalized.endswith(";"):
+        normalized = normalized[:-1].rstrip()
+    candidate = normalized.lstrip("(").lstrip()
+    if not normalized or ";" in normalized or not _READ_QUERY_PATTERN.match(candidate):
+        raise UnsafeQueryError(sql)
+    return normalized
+
+
+def is_read_only(sql: str) -> bool:
+    """Return whether SQL passes QCP's single read-statement validation."""
+    try:
+        normalize_read_query(sql)
+    except UnsafeQueryError:
+        return False
+    return True
+
+
+def require_db_url() -> str:
+    """Return the configured database URL or raise a user-facing error."""
+    database_url = cfg.get_db_url()
+    if not database_url:
+        raise NoDatabaseConfiguredError()
+    return database_url
+
+
+def test_connection(database_url: str) -> None:
+    """Compatibility wrapper around :class:`PostgresDatabaseClient`."""
+    PostgresDatabaseClient(database_url).test_connection()
+
+
+def get_schema_summary(database_url: str, max_tables: int = 50) -> str:
+    """Compatibility wrapper returning a compact schema string."""
+    return PostgresDatabaseClient(database_url).lookup_schema().summary(max_tables=max_tables)
+
+
+def run_query(database_url: str, sql: str, limit: int = MAX_QUERY_ROWS) -> tuple[list[str], list[tuple[Any, ...]]]:
+    """Compatibility wrapper returning DB-API-style columns and rows."""
+    result = PostgresDatabaseClient(database_url).execute_read_query(sql, limit=limit)
+    return result.columns, [tuple(row) for row in result.rows]

qcp/errors.py

@@ -0,0 +1,61 @@
+"""Application exceptions converted to clean messages at the CLI boundary."""
+
+
+class QcpError(Exception):
+    """Base error for all QCP CLI failures."""
+
+
+class NoDatabaseConfiguredError(QcpError):
+    """Raised when a command needs a database but none is configured."""
+
+    def __init__(self) -> None:
+        """Initialize the actionable configuration error."""
+        super().__init__(
+            "No database is configured.\n"
+            "Run `qcp init` to connect a Postgres database, "
+            "or set the QCP_DATABASE_URL environment variable."
+        )
+
+
+class NoApiKeyConfiguredError(QcpError):
+    """Raised when a command needs Gemini but no key is configured."""
+
+    def __init__(self, provider: str = "gemini") -> None:
+        """Initialize the actionable API-key error."""
+        super().__init__(
+            f"No API key configured for provider '{provider}'.\n"
+            f"Run `qcp auth` to add your {provider.title()} API key, "
+            f"or set the GEMINI_API_KEY environment variable."
+        )
+
+
+class DatabaseConnectionError(QcpError):
+    """Raised for PostgreSQL connection or execution failures."""
+
+    def __init__(self, detail: str) -> None:
+        """Initialize the database error with driver details."""
+        super().__init__(f"Could not connect to the database: {detail}")
+
+
+class LLMError(QcpError):
+    """Raised when Gemini or the LangChain agent fails."""
+
+    def __init__(self, detail: str) -> None:
+        """Initialize the AI provider error."""
+        super().__init__(f"AI provider error: {detail}")
+
+
+class UnsafeQueryError(QcpError):
+    """Raised when SQL is not one read-only statement."""
+
+    def __init__(self, statement: str) -> None:
+        """Initialize the query safety error."""
+        super().__init__(
+            "Refusing to run a non-read-only statement generated from your "
+            f"question:\n  {statement}\n"
+            "qcp only executes one SELECT or WITH query."
+        )
+
+
+class SchemaChangedError(QcpError):
+    """Raised when cached schema metadata no longer matches PostgreSQL."""