gaard-api 0.2.6__tar.gz → 0.2.8__tar.gz

{gaard_api-0.2.6/src/gaard_api.egg-info → gaard_api-0.2.8}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: gaard-api
-Version: 0.2.6
+Version: 0.2.8
 Summary: GAARD backend web services providing admin interface
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: gaard-core==0.2.6
-Requires-Dist: gaard-connectors==0.2.6
-Requires-Dist: gaard-llm==0.2.6
-Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.6
+Requires-Dist: gaard-core==0.2.8
+Requires-Dist: gaard-connectors==0.2.8
+Requires-Dist: gaard-llm==0.2.8
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.8
 Requires-Dist: fastapi>=0.111.0
 Requires-Dist: uvicorn[standard]>=0.30.0
 Requires-Dist: pydantic>=2.7.0

{gaard_api-0.2.6 → gaard_api-0.2.8}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gaard-api"
-version = "0.2.6"
+version = "0.2.8"
 description = "GAARD backend web services providing admin interface"
 readme = "README.md"
 requires-python = ">=3.11"
 
 dependencies = [
-    "gaard-core==0.2.6",
-    "gaard-connectors==0.2.6",
-    "gaard-llm==0.2.6",
-    "gaard-plugin-api>=0.2.6,<0.3.0",
+    "gaard-core==0.2.8",
+    "gaard-connectors==0.2.8",
+    "gaard-llm==0.2.8",
+    "gaard-plugin-api>=0.2.8,<0.3.0",
     "fastapi>=0.111.0",
     "uvicorn[standard]>=0.30.0",
     "pydantic>=2.7.0",

{gaard_api-0.2.6 → gaard_api-0.2.8}/src/gaard_api/admin/database.py

@@ -17,7 +17,10 @@ from gaard_api.admin.models import (
     DataQueryAuditType,
     DatasourceConnector,
     OverviewWidget,
+    OverviewWidgetTag,
     PromptTemplate,
+    UserSavedMetric,
+    WidgetTag,
 )
 from gaard_api.admin.security import hash_password
 from gaard_api.core.settings import settings
@@ -75,6 +78,7 @@ def init_metadata_store() -> None:
         engine = get_engine()
         Base.metadata.create_all(engine)
         ensure_admin_session_schema(engine)
+        ensure_admin_user_schema(engine)
         ensure_data_query_audit_schema(engine)
         ensure_overview_widget_schema(engine)
 
@@ -88,6 +92,7 @@ def init_metadata_store() -> None:
             seed_prompts(session)
             seed_datasource_connectors(session)
             seed_overview_widgets(session)
+            backfill_overview_widget_tags(session)
             backfill_data_query_audit_types(session)
             session.commit()
 
@@ -107,6 +112,142 @@ def seed_admin_user(session: Session) -> None:
     )
 
 
+def ensure_admin_user_schema(engine: Engine) -> None:
+    columns = {column["name"] for column in inspect(engine).get_columns("admin_users")}
+    additions = {
+        "display_name": "ALTER TABLE admin_users ADD COLUMN display_name VARCHAR(255) NOT NULL DEFAULT ''",
+        "auth_provider": "ALTER TABLE admin_users ADD COLUMN auth_provider VARCHAR(255) NOT NULL DEFAULT 'local'",
+        "is_provisioned": "ALTER TABLE admin_users ADD COLUMN is_provisioned BOOLEAN NOT NULL DEFAULT 0",
+    }
+    with engine.begin() as connection:
+        for name, sql in additions.items():
+            if name not in columns:
+                connection.execute(text(sql))
+        if engine.dialect.name == "sqlite" and (
+            admin_user_has_global_username_constraint(engine)
+            or not admin_user_has_provider_username_constraint(engine)
+        ):
+            rebuild_sqlite_admin_users(connection)
+        else:
+            drop_global_admin_username_constraint(connection, engine)
+            normalize_external_admin_usernames(connection, engine.dialect.name)
+            ensure_admin_user_provider_username_constraint(connection, engine)
+
+
+def admin_user_has_global_username_constraint(engine: Engine) -> bool:
+    return ["username"] in admin_user_unique_column_sets(engine)
+
+
+def admin_user_has_provider_username_constraint(engine: Engine) -> bool:
+    return ["auth_provider", "username"] in admin_user_unique_column_sets(engine)
+
+
+def admin_user_unique_column_sets(engine: Engine) -> list[list[str]]:
+    if engine.dialect.name == "sqlite":
+        with engine.connect() as connection:
+            return [
+                [row[2] for row in connection.execute(text(f"PRAGMA index_info({index_name!r})"))]
+                for _sequence, index_name, is_unique, *_rest in connection.execute(
+                    text("PRAGMA index_list('admin_users')")
+                )
+                if is_unique
+            ]
+
+    inspector = inspect(engine)
+    return [
+        cast(list[str], constraint_column_names)
+        for constraint in inspector.get_unique_constraints("admin_users")
+        if isinstance((constraint_column_names := constraint.get("column_names")), list)
+        and all(isinstance(column_name, str) for column_name in constraint_column_names)
+    ] + [
+        cast(list[str], index_column_names)
+        for index in inspector.get_indexes("admin_users")
+        if index.get("unique")
+        and isinstance((index_column_names := index.get("column_names")), list)
+        and all(isinstance(column_name, str) for column_name in index_column_names)
+    ]
+
+
+def rebuild_sqlite_admin_users(connection) -> None:
+    connection.execute(text("""
+        CREATE TABLE admin_users__migrated (
+            id INTEGER NOT NULL PRIMARY KEY,
+            username VARCHAR(255) NOT NULL,
+            display_name VARCHAR(255) NOT NULL DEFAULT '',
+            auth_provider VARCHAR(255) NOT NULL DEFAULT 'local',
+            password_hash TEXT NOT NULL,
+            must_change_password BOOLEAN NOT NULL,
+            is_provisioned BOOLEAN NOT NULL DEFAULT 0,
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            CONSTRAINT uq_admin_users_auth_provider_username UNIQUE (auth_provider, username)
+        )
+    """))
+    connection.execute(text("""
+        INSERT INTO admin_users__migrated
+            (id, username, display_name, auth_provider, password_hash, must_change_password, is_provisioned, created_at, updated_at)
+        SELECT
+            id,
+            CASE WHEN password_hash = 'external$disabled' AND instr(username, ':') > 0
+                    AND (auth_provider = 'local' OR substr(username, 1, instr(username, ':') - 1) = auth_provider)
+                THEN substr(username, instr(username, ':') + 1) ELSE username END,
+            display_name,
+            CASE WHEN auth_provider = 'local' AND password_hash = 'external$disabled' AND instr(username, ':') > 0
+                THEN substr(username, 1, instr(username, ':') - 1) ELSE auth_provider END,
+            password_hash, must_change_password, 0, created_at, updated_at
+        FROM admin_users
+    """))
+    connection.execute(text("DROP TABLE admin_users"))
+    connection.execute(text("ALTER TABLE admin_users__migrated RENAME TO admin_users"))
+    connection.execute(text("CREATE INDEX ix_admin_users_username ON admin_users (username)"))
+    connection.execute(text("CREATE INDEX ix_admin_users_auth_provider ON admin_users (auth_provider)"))
+
+
+def drop_global_admin_username_constraint(connection, engine: Engine) -> None:
+    if engine.dialect.name != "postgresql":
+        return
+    inspector = inspect(engine)
+    quote = connection.dialect.identifier_preparer.quote
+    for constraint in inspector.get_unique_constraints("admin_users"):
+        if constraint.get("column_names") == ["username"]:
+            connection.execute(text(f"ALTER TABLE admin_users DROP CONSTRAINT {quote(constraint['name'])}"))
+
+
+def normalize_external_admin_usernames(connection, dialect_name: str) -> None:
+    if dialect_name == "sqlite":
+        username = "substr(username, instr(username, ':') + 1)"
+        provider = "substr(username, 1, instr(username, ':') - 1)"
+        has_prefix = "instr(username, ':') > 0"
+        prefix_matches_provider = "substr(username, 1, instr(username, ':') - 1) = auth_provider"
+    elif dialect_name == "postgresql":
+        username = "substring(username from position(':' in username) + 1)"
+        provider = "substring(username from 1 for position(':' in username) - 1)"
+        has_prefix = "position(':' in username) > 0"
+        prefix_matches_provider = "substring(username from 1 for position(':' in username) - 1) = auth_provider"
+    else:
+        return
+    connection.execute(text(
+        "UPDATE admin_users "
+        f"SET username = {username}, auth_provider = CASE WHEN auth_provider = 'local' THEN {provider} ELSE auth_provider END "
+        "WHERE password_hash = 'external$disabled' "
+        f"AND {has_prefix} AND (auth_provider = 'local' OR {prefix_matches_provider})"
+    ))
+
+
+def ensure_admin_user_provider_username_constraint(connection, engine: Engine) -> None:
+    if engine.dialect.name != "postgresql":
+        return
+    constraints = inspect(engine).get_unique_constraints("admin_users")
+    if not any(
+        constraint.get("column_names") == ["auth_provider", "username"]
+        for constraint in constraints
+    ):
+        connection.execute(text(
+            "ALTER TABLE admin_users ADD CONSTRAINT uq_admin_users_auth_provider_username "
+            "UNIQUE (auth_provider, username)"
+        ))
+
+
 def seed_settings(session: Session) -> None:
     defaults = {
         "gaard_intent_classification_mode": settings.gaard_intent_classification_mode,
@@ -278,6 +419,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 10,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "audit_retention",
@@ -296,6 +438,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 20,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "schema_cache_ttl",
@@ -314,6 +457,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 30,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "license_edition",
@@ -328,6 +472,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 40,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "runtime_daily_queries",
@@ -343,6 +488,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 250,
             "grid_width": 12,
+            "grid_height": 4,
             "active": False,
         },
         {
@@ -362,6 +508,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 130,
             "grid_width": 12,
+            "grid_height": 4,
         },
     ]
 
@@ -516,6 +663,18 @@ def ensure_overview_widget_schema(engine: Engine) -> None:
                 text("ALTER TABLE overview_widgets ADD COLUMN grid_width INTEGER DEFAULT 1")
             )
 
+    if "grid_height" not in columns:
+        with engine.begin() as connection:
+            connection.execute(
+                text("ALTER TABLE overview_widgets ADD COLUMN grid_height INTEGER DEFAULT 2")
+            )
+            connection.execute(
+                text(
+                    "UPDATE overview_widgets SET grid_height = 4 "
+                    "WHERE widget_type <> 'scalar'"
+                )
+            )
+
     if "result_mode" not in columns:
         with engine.begin() as connection:
             connection.execute(
@@ -525,6 +684,33 @@ def ensure_overview_widget_schema(engine: Engine) -> None:
                 )
             )
 
+def backfill_overview_widget_tags(session: Session) -> None:
+    """Give legacy widgets public and saved-metric owner tags."""
+    if session.scalar(select(WidgetTag).where(WidgetTag.name == "public")) is None:
+        session.add(WidgetTag(name="public"))
+        session.flush()
+    widget_ids_with_tags = set(session.scalars(select(OverviewWidgetTag.widget_id)))
+    for widget_id in session.scalars(select(OverviewWidget.id)):
+        if widget_id not in widget_ids_with_tags:
+            session.add(OverviewWidgetTag(widget_id=widget_id, tag_name="public"))
+
+    existing_assignments = set(
+        session.execute(select(OverviewWidgetTag.widget_id, OverviewWidgetTag.tag_name))
+    )
+    for widget_id, owner_username in session.execute(
+        select(OverviewWidget.id, UserSavedMetric.owner_username).join(
+            UserSavedMetric,
+            UserSavedMetric.widget_key == OverviewWidget.widget_key,
+        )
+    ):
+        if not owner_username:
+            continue
+        if session.get(WidgetTag, owner_username) is None:
+            session.add(WidgetTag(name=owner_username))
+            session.flush()
+        if (widget_id, owner_username) not in existing_assignments:
+            session.add(OverviewWidgetTag(widget_id=widget_id, tag_name=owner_username))
+
 
 def reset_metadata_store_for_tests() -> None:
     global _engine, _engine_url, _session_factory

{gaard_api-0.2.6 → gaard_api-0.2.8}/src/gaard_api/admin/defaults.py

@@ -86,6 +86,75 @@ Return one JSON object with:
 - reason: short explanation
 """
 
+DEFAULT_CONVERSATION_CONTEXT_CLASSIFICATION_SYSTEM_PROMPT = """You are GAARD Conversation Context Classification.
+
+Your task is to decide whether the current user data question (turn t) is a
+logical continuation of the recent conversation turns (t-2 and t-1).
+
+Use the previous question-answer pairs as conversation evidence. Do not classify
+by rigid prefix or keyword rules. Decide semantically whether turn t depends on,
+compares with, narrows, broadens, or otherwise continues the immediately
+preceding analytical thread.
+
+Allowed decisions:
+- new_topic: answer "no" to logical continuation. The question starts a new analytical thread.
+- follow_up: answer "yes" to logical continuation. The question continues the
+  recent thread and can be executed safely.
+- ambiguous: the question appears to continue the thread, but required entities,
+  filters, date ranges, or datasource scope cannot be inferred safely.
+
+Decision rules:
+1. First answer the yes/no question: is turn t a logical continuation of t-1/t-2?
+2. A question can be a logical continuation even when it is already
+   self-contained. In that case use follow_up, set
+   current_question_is_standalone to true, and set standalone_question to the
+   current question.
+3. If the answer is no, use new_topic and set standalone_question to the current question.
+4. If the answer is yes and the current question is elliptical, rewrite it as a
+   standalone data question using t-1/t-2.
+5. Use ambiguous only when the answer is yes but the continuation cannot be
+   rewritten or executed safely without asking the user.
+6. Treat detail/projection requests about the previous result as follow_up when
+   the previous turn defines the result set. If the previous question counted,
+   grouped, or filtered records and the user now asks for descriptions, names,
+   statuses, fields, details, or values for those same records, rewrite by
+   preserving the previous filters/date range/datasource and changing only the
+   returned fields.
+7. Do not mark a projection/detail follow-up ambiguous merely because the
+   previous answer did not expose row ids. The previous standalone question and
+   SQL are enough context for the next SQL generation step.
+8. Never include rows or sensitive data in the standalone question.
+
+Output rules:
+- Return only a JSON object.
+- Do not include markdown.
+- Do not include reasoning outside the JSON.
+- Do not include <think> blocks.
+- Use exactly this JSON shape:
+  {
+    "is_continuation": false,
+    "decision": "new_topic",
+    "current_question_is_standalone": true,
+    "confidence": 0.0,
+    "standalone_question": "rewritten or current question",
+    "reason": "short reason"
+  }
+"""
+
+DEFAULT_CONVERSATION_CONTEXT_CLASSIFICATION_USER_PROMPT = """Decide whether turn t is a logical continuation of turns t-2 and t-1.
+
+Input JSON:
+{payload}
+
+Return one JSON object with:
+- is_continuation: boolean yes/no answer to the logical-continuation question
+- decision: one of new_topic, follow_up, ambiguous
+- current_question_is_standalone: boolean
+- confidence: number from 0 to 1
+- standalone_question: required for follow_up and new_topic; empty only for ambiguous
+- reason: short explanation
+"""
+
 DEFAULT_RESULT_INTERPRETATION_SYSTEM_PROMPT = """You are GAARD Data Result Interpreter.
 
 Your task is to explain SQL query results to the user.
@@ -149,6 +218,40 @@ Return exactly one of:
 personal_data, sensitive_data, technical_data, neutral_data, unknown
 """
 
+DEFAULT_ANSWER_EXPLANATION_SYSTEM_PROMPT = """You are GAARD Answer Explanation.
+
+Your task is to explain why a specific SQL query was generated for the user's data question.
+
+Use the provided:
+- original user question,
+- generated SQL,
+- interpreted answer and raw result rows,
+- inference metadata,
+- prompt metadata,
+- approved business logic and schema/rule context.
+
+Rules:
+1. Answer in the same language as the user's question.
+2. Explain the logical mapping from the question to the SQL.
+3. Mention the selected tables, columns, joins, filters, time ranges, grouping,
+   aggregation, ordering and limits when they are relevant.
+4. If business logic affected the SQL, describe that rule in plain language.
+5. Distinguish explicit evidence from assumptions.
+6. Do not invent tables, columns, rules, filters or results that are not present in the input.
+7. Do not reveal hidden chain-of-thought.
+8. Do not include <think> blocks.
+9. Do not use markdown tables.
+10. Return only the final explanation.
+"""
+
+DEFAULT_ANSWER_EXPLANATION_USER_PROMPT = """Explain why this SQL was generated for the user's question.
+
+Input JSON:
+{payload}
+
+Return only the final explanation.
+"""
+
 DEFAULT_GOVERNANCE_POLICY_CONFIG = {
     "final_answer": {
         "record_level_pii_allowed": False,
@@ -187,6 +290,16 @@ DEFAULT_PROMPTS = [
         "system_prompt": DEFAULT_SQL_GENERATION_SYSTEM_PROMPT,
         "user_prompt_template": DEFAULT_SQL_GENERATION_USER_PROMPT,
     },
+    {
+        "prompt_key": "conversation_context_classification",
+        "name": "Conversation context classification",
+        "description": (
+            "Decides whether the current question is a logical continuation "
+            "of recent conversation turns."
+        ),
+        "system_prompt": DEFAULT_CONVERSATION_CONTEXT_CLASSIFICATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_CONVERSATION_CONTEXT_CLASSIFICATION_USER_PROMPT,
+    },
     {
         "prompt_key": "result_interpretation",
         "name": "Result interpretation",
@@ -201,4 +314,11 @@ DEFAULT_PROMPTS = [
         "system_prompt": DEFAULT_RESULT_CLASSIFICATION_SYSTEM_PROMPT,
         "user_prompt_template": DEFAULT_RESULT_CLASSIFICATION_USER_PROMPT,
     },
+    {
+        "prompt_key": "answer_explanation",
+        "name": "Answer explanation",
+        "description": "Explains why a generated SQL query answered a user question.",
+        "system_prompt": DEFAULT_ANSWER_EXPLANATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_ANSWER_EXPLANATION_USER_PROMPT,
+    },
 ]

{gaard_api-0.2.6 → gaard_api-0.2.8}/src/gaard_api/admin/models.py

@@ -6,6 +6,7 @@ from sqlalchemy import (
     DateTime,
     Enum as SAEnum,
     Float,
+    ForeignKey,
     Integer,
     String,
     Text,
@@ -26,11 +27,19 @@ class Base(DeclarativeBase):
 
 class AdminUser(Base):
     __tablename__ = "admin_users"
+    __table_args__ = (
+        UniqueConstraint("auth_provider", "username", name="uq_admin_users_auth_provider_username"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
-    username: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(255), index=True)
+    display_name: Mapped[str] = mapped_column(String(255), default="")
+    auth_provider: Mapped[str] = mapped_column(String(255), index=True, default="local")
     password_hash: Mapped[str] = mapped_column(Text)
     must_change_password: Mapped[bool] = mapped_column(Boolean, default=True)
+    # Provider refreshes create provisional records so they can be assigned before login.
+    # The provider may safely remove only records which remain provisional.
+    is_provisioned: Mapped[bool] = mapped_column(Boolean, default=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
     updated_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
@@ -180,6 +189,22 @@ class DashboardUserState(Base):
     )
 
 
+class UserDatasourceSelection(Base):
+    """Client datasource selections, scoped to one authenticated user."""
+
+    __tablename__ = "user_datasource_selections"
+
+    owner_user_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    owner_username: Mapped[str] = mapped_column(String(255), index=True, default="")
+    datasource_ids_json: Mapped[str] = mapped_column(Text, default="[]")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+
+
 class UserSavedMetric(Base):
     __tablename__ = "user_saved_metrics"
     __table_args__ = (
@@ -303,6 +328,7 @@ class OverviewWidget(Base):
     result_mode: Mapped[str] = mapped_column(String(50), default="data")
     position: Mapped[int] = mapped_column(Integer, default=100)
     grid_width: Mapped[int] = mapped_column(Integer, default=1)
+    grid_height: Mapped[int] = mapped_column(Integer, default=2)
     active: Mapped[bool] = mapped_column(Boolean, default=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
     updated_at: Mapped[datetime] = mapped_column(
@@ -313,6 +339,26 @@ class OverviewWidget(Base):
     updated_by: Mapped[str] = mapped_column(String(255), default="system")
 
 
+class WidgetTag(Base):
+    """Permanent catalogue of every tag that has been used on a widget."""
+
+    __tablename__ = "widget_tags"
+
+    name: Mapped[str] = mapped_column(String(255), primary_key=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+
+
+class OverviewWidgetTag(Base):
+    __tablename__ = "overview_widget_tags"
+
+    widget_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("overview_widgets.id", ondelete="CASCADE"), primary_key=True
+    )
+    tag_name: Mapped[str] = mapped_column(
+        String(255), ForeignKey("widget_tags.name"), primary_key=True
+    )
+
+
 class BusinessLogicSuggestion(Base):
     __tablename__ = "business_logic_suggestions"