sageql 0.2.1__py3-none-any.whl

sageql/__init__.py

@@ -0,0 +1,108 @@
+"""Public API for SageQL."""
+
+from sageql.core import Candidate, GeneratedQuery, SQLProvider, generate_sql
+from sageql.conversation import (
+    ChatConfig,
+    ChatError,
+    ChatProvider,
+    DatabaseConfig,
+    LLMConfig,
+    Message,
+    ReportConversation,
+)
+from sageql.context import ContextProvider, ContextResolution, ContextResolutionSession, ResolvedContext
+from sageql.catalog_input import catalog_from_dict, load_catalog_file
+from sageql.discovery import (
+    CatalogSource, DiscoveryCandidates, DiscoveryError, DiscoveryProvider,
+    DiscoverySelection, QuerySpace, discover_query_space,
+)
+from sageql.odbc_catalog import ODBCCatalogSource
+from sageql.planning import (
+    PlanCandidates, PlanProposal, PlanQuality, PlanningError, PlanningProvider,
+    ProposedFilter, ProposedJoin, ProposedMeasure, QueryPlan, create_query_plan,
+    review_query_plan,
+)
+from sageql.schema import Column, Definition, Relation, SchemaCatalog, Table
+from sageql.sql_generation import SQLGenerationError, SQLQuery, generate_sql_from_plan
+from sageql.report_validation import (
+    PreparedQuery, QueryValidationError, RequiredFilter, ValidationResult,
+    prepare_report_query, validate_report_query,
+)
+from sageql.execution import QueryExecutionError, QueryResult, execute_sqlite_report
+from sageql.errors import GenerationError, InvalidSQL
+from sageql.validation import validate_sql
+from sageql.tsql import (
+    TSQLQuery, TSQLResult, TSQLReportError, render_tsql_report,
+    validate_tsql_report, execute_tsql_report,
+)
+from sageql.understanding import RequestAssessment, RequestUnderstandingSession, UnderstandingProvider
+from sageql.sdk import SageQL
+
+__all__ = [
+    "Candidate",
+    "SageQL",
+    "ChatConfig",
+    "ChatError",
+    "ChatProvider",
+    "ContextProvider",
+    "ContextResolution",
+    "ContextResolutionSession",
+    "CatalogSource",
+    "catalog_from_dict",
+    "Column",
+    "DatabaseConfig",
+    "Definition",
+    "DiscoveryCandidates",
+    "DiscoveryError",
+    "DiscoveryProvider",
+    "DiscoverySelection",
+    "GeneratedQuery",
+    "GenerationError",
+    "InvalidSQL",
+    "LLMConfig",
+    "load_catalog_file",
+    "Message",
+    "ODBCCatalogSource",
+    "PlanCandidates",
+    "PlanProposal",
+    "PlanQuality",
+    "PlanningError",
+    "PlanningProvider",
+    "ProposedFilter",
+    "ProposedJoin",
+    "ProposedMeasure",
+    "QueryPlan",
+    "QueryExecutionError",
+    "QueryResult",
+    "QueryValidationError",
+    "QuerySpace",
+    "Relation",
+    "ReportConversation",
+    "ResolvedContext",
+    "RequestAssessment",
+    "RequestUnderstandingSession",
+    "RequiredFilter",
+    "SQLProvider",
+    "SQLGenerationError",
+    "SQLQuery",
+    "PreparedQuery",
+    "ValidationResult",
+    "SchemaCatalog",
+    "Table",
+    "UnderstandingProvider",
+    "generate_sql",
+    "generate_sql_from_plan",
+    "prepare_report_query",
+    "validate_report_query",
+    "execute_sqlite_report",
+    "discover_query_space",
+    "create_query_plan",
+    "review_query_plan",
+    "validate_sql",
+    "TSQLQuery",
+    "TSQLResult",
+    "TSQLReportError",
+    "render_tsql_report",
+    "validate_tsql_report",
+    "execute_tsql_report",
+]

sageql/catalog_input.py

@@ -0,0 +1,138 @@
+"""Parse schema metadata supplied by the package user."""
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from sageql.schema import Column, Definition, Relation, SchemaCatalog, Table
+
+
+_MAX_FILE_BYTES = 1_000_000
+
+
+def _object(value: Any, required: set[str], optional: set[str], label: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict) or not required <= value.keys() or value.keys() - required - optional:
+        raise ValueError(f"{label} has missing or unexpected fields")
+    return value
+
+
+def _array(value: Any, label: str, *, maximum: int, nonempty: bool = False) -> list[Any]:
+    if not isinstance(value, list) or len(value) > maximum or (nonempty and not value):
+        raise ValueError(f"{label} must be a JSON array with 1 to {maximum} items" if nonempty
+                         else f"{label} must be a JSON array with at most {maximum} items")
+    return value
+
+
+def _text(value: Any, label: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str) or len(value) > 2000 or (not allow_empty and not value.strip()):
+        raise ValueError(f"{label} must be text")
+    if any(ord(character) < 32 for character in value if character not in "\n\t"):
+        raise ValueError(f"{label} contains invalid control characters")
+    return value.strip()
+
+
+def _identifier(value: Any, label: str, *, allow_empty: bool = False) -> str:
+    result = _text(value, label, allow_empty=allow_empty)
+    if len(result) > 256 or "\n" in result or "\t" in result:
+        raise ValueError(f"{label} must be a single-line identifier")
+    return result
+
+
+def catalog_from_dict(data: Mapping[str, Any]) -> SchemaCatalog:
+    """Validate a JSON-shaped catalog with tables, columns, relations, and definitions."""
+    root = _object(data, {"tables"}, {"relations", "definitions"}, "catalog")
+    tables: list[Table] = []
+    columns: list[Column] = []
+    definitions: list[Definition] = []
+    for index, raw_table in enumerate(_array(root["tables"], "tables", maximum=200, nonempty=True)):
+        label = f"tables[{index}]"
+        item = _object(raw_table, {"name", "columns"}, {"schema", "kind", "description"}, label)
+        table = Table(
+            name=_identifier(item["name"], label + ".name"),
+            schema=_identifier(item.get("schema", ""), label + ".schema", allow_empty=True),
+            kind=_identifier(item.get("kind", "TABLE"), label + ".kind").upper(),
+        )
+        tables.append(table)
+        if "description" in item:
+            definitions.append(Definition(
+                table.key, _text(item["description"], label + ".description"),
+                "user table description",
+            ))
+        for col_index, raw_column in enumerate(
+            _array(item["columns"], label + ".columns", maximum=500, nonempty=True)
+        ):
+            col_label = f"{label}.columns[{col_index}]"
+            col = _object(raw_column, {"name"}, {"data_type", "nullable", "description"}, col_label)
+            nullable = col.get("nullable", True)
+            if type(nullable) is not bool:
+                raise ValueError(f"{col_label}.nullable must be a boolean")
+            column = Column(
+                table=table.key,
+                name=_identifier(col["name"], col_label + ".name"),
+                data_type=_identifier(col.get("data_type", "unknown"), col_label + ".data_type"),
+                nullable=nullable,
+            )
+            columns.append(column)
+            if "description" in col:
+                definitions.append(Definition(
+                    column.key, _text(col["description"], col_label + ".description"),
+                    "user column description",
+                ))
+    if len(columns) > 5000:
+        raise ValueError("catalog has too many columns")
+
+    table_names = {table.key.casefold(): table.key for table in tables}
+    column_names = {(column.table.casefold(), column.name.casefold()): column.name
+                    for column in columns}
+    relations: list[Relation] = []
+    for index, raw_relation in enumerate(_array(root.get("relations", []), "relations", maximum=500)):
+        label = f"relations[{index}]"
+        item = _object(raw_relation,
+                       {"name", "child_table", "child_columns", "parent_table", "parent_columns"},
+                       set(), label)
+        child_raw = _identifier(item["child_table"], label + ".child_table")
+        parent_raw = _identifier(item["parent_table"], label + ".parent_table")
+        child = table_names.get(child_raw.casefold(), child_raw)
+        parent = table_names.get(parent_raw.casefold(), parent_raw)
+        def relation_columns(field: str, table: str) -> tuple[str, ...]:
+            values = _array(item[field], label + "." + field, maximum=32, nonempty=True)
+            return tuple(
+                column_names.get((table.casefold(), name.casefold()), name)
+                for name in (_identifier(value, label + "." + field) for value in values)
+            )
+        relations.append(Relation(
+            name=_identifier(item["name"], label + ".name"),
+            child_table=child,
+            child_columns=relation_columns("child_columns", child),
+            parent_table=parent,
+            parent_columns=relation_columns("parent_columns", parent),
+        ))
+
+    for index, raw_definition in enumerate(_array(root.get("definitions", []), "definitions", maximum=500)):
+        label = f"definitions[{index}]"
+        item = _object(raw_definition, {"term", "meaning"}, set(), label)
+        definitions.append(Definition(
+            _identifier(item["term"], label + ".term"),
+            _text(item["meaning"], label + ".meaning"),
+            "user glossary",
+        ))
+    try:
+        return SchemaCatalog(tuple(tables), tuple(columns), tuple(relations), tuple(definitions))
+    except ValueError as exc:
+        raise ValueError(f"invalid catalog structure: {exc}") from exc
+
+
+def load_catalog_file(path: str | Path) -> SchemaCatalog:
+    """Load a UTF-8 JSON catalog without echoing file contents in errors."""
+    try:
+        with Path(path).open("rb") as handle:
+            content = handle.read(_MAX_FILE_BYTES + 1)
+    except OSError as exc:
+        raise ValueError("could not read schema catalog file") from exc
+    if len(content) > _MAX_FILE_BYTES:
+        raise ValueError("schema catalog file is too large")
+    try:
+        data = json.loads(content.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError("schema catalog must be valid UTF-8 JSON") from exc
+    return catalog_from_dict(data)

sageql/chat_cli.py

@@ -0,0 +1,229 @@
+"""Interactive report-planning chat CLI."""
+
+import argparse
+import getpass
+import json
+import os
+import sys
+
+from sageql.chat_provider import OpenAIChatProvider
+from sageql.catalog_input import load_catalog_file
+from sageql.conversation import ChatConfig, ChatError, DatabaseConfig, LLMConfig
+from sageql.context import ContextResolutionSession, ResolvedContext
+from sageql.discovery import DiscoveryError, QuerySpace, discover_query_space
+from sageql.planning import PlanQuality, PlanningError, QueryPlan, create_query_plan, review_query_plan
+from sageql.report_validation import QueryValidationError, validate_report_query
+from sageql.sql_generation import SQLGenerationError, SQLQuery, generate_sql_from_plan
+from sageql.execution import QueryExecutionError, execute_sqlite_report
+from sageql.understanding import RequestUnderstandingSession
+
+
+def _required_input(label: str) -> str:
+    while True:
+        value = input(label).strip()
+        if value:
+            return value
+        print("Please enter a value.", file=sys.stderr)
+
+
+def _configured_or_input(name: str, label: str) -> str:
+    return os.environ.get(name, "").strip() or _required_input(label)
+
+
+def _next_message() -> str:
+    return _required_input("You> ")
+
+
+def _print_context(context: ResolvedContext) -> None:
+    print("Resolved context:")
+    print(f"  Time period: {context.time_period or 'Not specified'}")
+    print(f"  Entities: {', '.join(context.entities) or 'Not specified'}")
+    print(f"  Metrics: {', '.join(context.metrics) or 'Not specified'}")
+    print(f"  Filters: {', '.join(context.filters) or 'Not specified'}")
+    print(f"  Comparison period: {context.comparison_period or 'Not specified'}")
+
+
+def _print_query_space(space: QuerySpace) -> None:
+    print("Query space discovery:")
+    print("  Tables/views:")
+    for table in space.tables:
+        print(f"    {table.key} ({table.kind.lower()})")
+    print("  Columns:")
+    for column in space.columns:
+        print(f"    {column.key} ({column.data_type})")
+    print("  Relations:")
+    for relation in space.relations:
+        child = ", ".join(f"{relation.child_table}.{item}" for item in relation.child_columns)
+        parent = ", ".join(f"{relation.parent_table}.{item}" for item in relation.parent_columns)
+        print(f"    {child} -> {parent} [{relation.name}]")
+    print("  Definitions:")
+    for definition in space.definitions:
+        print(f"    {definition.term}: {definition.meaning} ({definition.source})")
+    if not space.relations:
+        print("    No relevant supplied relations selected.")
+    if not space.definitions:
+        print("    No relevant definitions selected or available.")
+
+
+def _print_plan(plan: QueryPlan, quality: PlanQuality) -> None:
+    print("\nQuery plan (logical operations, no SQL):")
+    print(json.dumps(plan.operations(), indent=2, ensure_ascii=False))
+    print("Plan quality:")
+    for check in quality.checks_passed:
+        print(f"  PASS: {check}")
+    for item in quality.review_items:
+        print(f"  REVIEW: {item}")
+    print("  Execution: Not performed.")
+
+
+def _print_sql(query: SQLQuery) -> None:
+    print("\nGenerated SQLite SQL (review before execution):")
+    print(query.sql)
+    print("Parameters:", dict(query.parameters))
+    print("Required date bindings:", ", ".join(query.required_parameters) or "None")
+
+
+def _schema_paths(values: list[str]) -> dict[str, str]:
+    paths = {}
+    for value in values:
+        name, separator, path = value.partition("=")
+        if not separator or not name or not path or name in paths:
+            raise ValueError("--sqlite-schema must be a unique NAME=PATH entry")
+        paths[name] = path
+    return paths
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sageql chat", description="Discuss a report request with an AI assistant"
+    )
+    parser.add_argument("--no-discovery", action="store_true", help="stop after context resolution")
+    parser.add_argument("--no-planning", action="store_true", help="stop after query-space discovery")
+    parser.add_argument("--no-sql", action="store_true", help="stop after logical query planning")
+    parser.add_argument("--catalog", help="path to a user-supplied schema catalog JSON file")
+    parser.add_argument("--period-start", help="inclusive ISO date for the report period")
+    parser.add_argument("--period-end", help="exclusive ISO date for the report period")
+    parser.add_argument("--comparison-start", help="inclusive ISO date for the comparison period")
+    parser.add_argument("--comparison-end", help="exclusive ISO date for the comparison period")
+    parser.add_argument("--execute-sqlite", metavar="PATH", help="execute on this SQLite file read-only")
+    parser.add_argument("--sqlite-schema", action="append", default=[], metavar="NAME=PATH",
+                        help="attach a named SQLite schema file read-only; repeat as needed")
+    parser.add_argument("--max-rows", type=int, default=50, help="maximum rows returned when executing")
+    args = parser.parse_args(argv)
+    if args.execute_sqlite and (args.no_discovery or args.no_planning or args.no_sql):
+        parser.error("--execute-sqlite requires discovery, planning, and SQL generation")
+    if bool(args.period_start) != bool(args.period_end):
+        parser.error("provide both --period-start and --period-end")
+    if bool(args.comparison_start) != bool(args.comparison_end):
+        parser.error("provide both --comparison-start and --comparison-end")
+
+    try:
+        first_question = _required_input("What report would you like to create? ")
+        print("\nDatabase configuration")
+        database = DatabaseConfig(
+            server_host=_configured_or_input("DB_SERVER_HOST", "Server / Host: "),
+            database=_configured_or_input("DB_NAME", "Database: "),
+            authentication=_configured_or_input("DB_AUTHENTICATION", "Authentication method: "),
+            odbc_driver=_configured_or_input("DB_ODBC_DRIVER", "ODBC Driver: "),
+        )
+
+        print("\nLLM configuration")
+        api_key = (
+            os.environ.get("LLM_API_KEY")
+            or os.environ.get("OPENAI_API_KEY")
+            or getpass.getpass("API Key: ")
+        )
+        base_url = os.environ.get("LLM_BASE_URL", "").strip()
+        model = os.environ.get("LLM_MODEL", "").strip()
+        if not base_url:
+            base_url = input("Base URL [https://api.openai.com/v1]: ").strip()
+        if not model:
+            model = input("Model [gpt-5-nano]: ").strip()
+        llm = LLMConfig(
+            api_key=api_key,
+            base_url=base_url or "https://api.openai.com/v1",
+            model=model or "gpt-5-nano",
+        )
+
+        config = ChatConfig(database=database, llm=llm)
+        provider = OpenAIChatProvider(llm)
+        conversation = RequestUnderstandingSession(config, provider)
+        print("\nRequest understanding started. Type /exit to finish.\n")
+        pending = first_question
+        while True:
+            try:
+                assessment = conversation.submit(pending)
+                if assessment.enough_information:
+                    print(f"Request understanding:\n{assessment.request_understanding.strip()}")
+                    break
+                print(f"AI> {assessment.clarification_question.strip()}\n")
+            except ChatError as exc:
+                print(f"sageql: {exc}", file=sys.stderr)
+
+            pending = _next_message()
+            if pending.lower() in {"/exit", "/quit"}:
+                return 0
+
+        context_session = ContextResolutionSession(
+            config, provider, conversation.history, assessment.request_understanding
+        )
+        resolution = context_session.start()
+        while not resolution.ready:
+            print(f"AI> {resolution.clarification_question.strip()}\n")
+            answer = _next_message()
+            if answer.lower() in {"/exit", "/quit"}:
+                return 0
+            resolution = context_session.submit(answer)
+        _print_context(resolution.context)
+        if not args.no_discovery:
+            catalog_path = args.catalog or os.getenv("SCHEMA_CATALOG_PATH", "")
+            if not catalog_path:
+                catalog_path = _required_input("Schema catalog JSON path: ")
+            catalog = load_catalog_file(catalog_path)
+            print("\nDiscovering query space from supplied schema...")
+            space = discover_query_space(catalog, provider, assessment.request_understanding,
+                                         resolution.context)
+            _print_query_space(space)
+            if not args.no_planning:
+                plan = create_query_plan(
+                    assessment.request_understanding, resolution.context, space, provider
+                )
+                _print_plan(plan, review_query_plan(plan, resolution.context, space))
+                if not args.no_sql:
+                    period_bounds = ((args.period_start, args.period_end)
+                                     if args.period_start else None)
+                    comparison_bounds = ((args.comparison_start, args.comparison_end)
+                                         if args.comparison_start else None)
+                    query = generate_sql_from_plan(
+                        plan, period_bounds=period_bounds, comparison_bounds=comparison_bounds
+                    )
+                    _print_sql(query)
+                    validation = validate_report_query(query, plan, resolution.context, space)
+                    print("Validation:")
+                    for check in validation.checks_passed:
+                        print(f"  PASS: {check}")
+                    for issue in validation.issues:
+                        print(f"  BLOCK: {issue}")
+                    if args.execute_sqlite:
+                        if not validation.valid:
+                            raise QueryValidationError("query must pass validation before execution")
+                        result = execute_sqlite_report(
+                            args.execute_sqlite, query, plan, resolution.context, space,
+                            attached_schemas=_schema_paths(args.sqlite_schema),
+                            max_rows=args.max_rows,
+                        )
+                        print("Read-only SQLite result:")
+                        print("  Columns:", result.columns)
+                        for row in result.rows:
+                            print("  Row:", row)
+                        print("  Truncated:", result.truncated)
+                    else:
+                        print("Execution: Not performed.")
+        return 0
+    except (EOFError, KeyboardInterrupt):
+        print("\nChat ended.")
+        return 0
+    except (ValueError, ChatError, DiscoveryError, PlanningError, SQLGenerationError,
+            QueryValidationError, QueryExecutionError) as exc:
+        print(f"sageql: {exc}", file=sys.stderr)
+        return 1