gaard-api 0.2.5__tar.gz → 0.2.7__tar.gz

{gaard_api-0.2.5/src/gaard_api.egg-info → gaard_api-0.2.7}/PKG-INFO

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

{gaard_api-0.2.5 → gaard_api-0.2.7}/pyproject.toml

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

{gaard_api-0.2.5 → gaard_api-0.2.7}/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.
@@ -187,6 +256,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",

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/admin/prompt_runtime.py

@@ -1,8 +1,14 @@
+from typing import Any
+
 from gaard_core.errors import ConfigurationError
 from gaard_core.json_utils import json_dumps
 from gaard_core.prompt_compiler.models import CompiledPrompt, SqlGenerationPromptRequest
 from gaard_core.prompt_compiler.schema_formatter import SchemaPromptFormatter
-from gaard_core.query_pipeline.models import QueryRequest, QueryResult
+from gaard_core.query_pipeline.models import (
+    ConversationContextDecision,
+    QueryRequest,
+    QueryResult,
+)
 
 from gaard_api.admin.models import PromptTemplate
 from gaard_api.admin.services import get_active_prompt_template_safe
@@ -85,6 +91,62 @@ class MetadataIntentClassificationPromptCompiler:
         )
 
 
+class MetadataConversationContextPromptCompiler:
+    def __init__(self, prompt_template: PromptTemplate) -> None:
+        self.prompt_template = prompt_template
+
+    def compile(
+        self,
+        request: QueryRequest,
+        conversation_context: dict[str, Any],
+    ) -> CompiledPrompt:
+        recent_turns = self._recent_turns(conversation_context)
+        payload = {
+            "turn_t_minus_2": recent_turns[0] if len(recent_turns) == 2 else {},
+            "turn_t_minus_1": recent_turns[-1] if recent_turns else {},
+            "turn_t": {
+                "question": request.question,
+                "datasource_id": request.datasource_id,
+                "datasource_ids": request.datasource_ids,
+            },
+        }
+        payload_json = json_dumps(payload, ensure_ascii=False, indent=2)
+
+        return CompiledPrompt(
+            system_prompt=self.prompt_template.system_prompt,
+            user_prompt=self.prompt_template.user_prompt_template.format(
+                payload=payload_json,
+                question=request.question,
+                datasource_id=request.datasource_id,
+                datasource_ids=json_dumps(request.datasource_ids, ensure_ascii=False),
+            ),
+            metadata={
+                "allowed_decisions": [item.value for item in ConversationContextDecision],
+                "decision_task": "logical_continuation_yes_no",
+                "prompt_key": self.prompt_template.prompt_key,
+                "prompt_version": self.prompt_template.version,
+            },
+        )
+
+    def _recent_turns(self, conversation_context: dict[str, Any]) -> list[dict[str, Any]]:
+        turns = [
+            turn for turn in conversation_context.get("turns", []) if isinstance(turn, dict)
+        ][-2:]
+        labels = ["t-2", "t-1"] if len(turns) == 2 else ["t-1"]
+        return [
+            {
+                "label": label,
+                "question": str(turn.get("question") or ""),
+                "standalone_question": str(turn.get("standalone_question") or ""),
+                "answer": str(turn.get("answer") or ""),
+                "sql": str(turn.get("sql") or ""),
+                "context_decision": str(turn.get("context_decision") or ""),
+                "context_reason": str(turn.get("context_reason") or ""),
+            }
+            for label, turn in zip(labels, turns, strict=False)
+        ]
+
+
 class MetadataResultInterpretationPromptCompiler:
     def __init__(self, prompt_template: PromptTemplate) -> None:
         self.prompt_template = prompt_template
@@ -170,6 +232,17 @@ def get_intent_classification_prompt_compiler() -> (
     return MetadataIntentClassificationPromptCompiler(prompt_template=prompt_template)
 
 
+def get_conversation_context_prompt_compiler() -> (
+    MetadataConversationContextPromptCompiler | None
+):
+    prompt_template = get_active_prompt_template_safe("conversation_context_classification")
+
+    if prompt_template is None:
+        return None
+
+    return MetadataConversationContextPromptCompiler(prompt_template=prompt_template)
+
+
 def get_result_interpretation_prompt_compiler() -> (
     MetadataResultInterpretationPromptCompiler | None
 ):

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/api/v1/admin.py

@@ -13,6 +13,7 @@ from gaard_core.errors import (
     QueryExecutionError,
     SqlValidationError,
 )
+from gaard_core.llm_output import remove_thinking_blocks
 from gaard_core.query_pipeline.models import (
     OutputClassification,
     QueryRequest,
@@ -21,6 +22,8 @@ from gaard_core.query_pipeline.models import (
 )
 from gaard_core.sql_validator.select_only import SelectOnlySqlValidator
 from gaard_connectors import ConnectorRegistryError
+from gaard_llm.openai_compatible.client import OpenAICompatibleClient
+from gaard_llm.providers.models import ChatCompletionRequest, ChatMessage
 from gaard_plugin_api import ExtensionRecord
 from pydantic import BaseModel, Field
 from sqlalchemy import select
@@ -251,6 +254,11 @@ class OverviewWidgetFromQueryRequest(BaseModel):
     )
 
 
+class OverviewWidgetTitleSuggestionRequest(BaseModel):
+    question: str = Field(min_length=1)
+    sql: str | None = None
+
+
 class DatasourceConnectorRequest(BaseModel):
     connector_key: str = Field(min_length=1, pattern=r"^[a-zA-Z0-9_-]+$")
     name: str = Field(min_length=1)
@@ -503,6 +511,79 @@ def build_client_widget_key(session: Session, label: str, question: str) -> str:
     return widget_key
 
 
+def normalize_metric_title(value: str, fallback: str) -> str:
+    cleaned = remove_thinking_blocks(value).strip()
+
+    if cleaned.startswith("```"):
+        cleaned = cleaned.removeprefix("```").strip()
+        if cleaned.startswith("text"):
+            cleaned = cleaned.removeprefix("text").strip()
+        if cleaned.endswith("```"):
+            cleaned = cleaned.removesuffix("```").strip()
+
+    cleaned = cleaned.strip().strip('"').strip("'")
+    cleaned = re.sub(r"\s+", " ", cleaned)
+    cleaned = cleaned.rstrip(".:;-")
+    if not cleaned:
+        cleaned = fallback.strip()
+
+    return cleaned[:80].strip() or "Saved Metric"
+
+
+def fallback_metric_title(question: str) -> str:
+    normalized = re.sub(r"\s+", " ", question.strip())
+    normalized = normalized.rstrip("?!.:;-")
+    if not normalized:
+        return "Saved Metric"
+
+    return normalized[0].upper() + normalized[1:80]
+
+
+def suggest_metric_title_with_llm(session: Session, request: OverviewWidgetTitleSuggestionRequest) -> str:
+    llm_config = get_llm_runtime_config(session)
+    if llm_config.provider != "openai-compatible":
+        raise ConfigurationError(f"Unsupported GAARD_LLM_PROVIDER: {llm_config.provider}")
+    if not llm_config.api_key or llm_config.api_key == "change-me":
+        raise ConfigurationError("GAARD_LLM_API_KEY must be configured to suggest metric titles.")
+
+    client = OpenAICompatibleClient(
+        base_url=llm_config.base_url,
+        api_key=llm_config.api_key,
+        timeout_seconds=llm_config.timeout_seconds,
+    )
+    fallback = fallback_metric_title(request.question)
+    response = client.create_chat_completion(
+        ChatCompletionRequest(
+            model=llm_config.model,
+            temperature=0.0,
+            extra_body=llm_config.extra_body,
+            messages=[
+                ChatMessage(
+                    role="system",
+                    content=(
+                        "You write short human-friendly metric names for dashboard widgets. "
+                        "Return only the metric name, without quotes, markdown, explanations, "
+                        "or trailing punctuation. Use the same language as the user question. "
+                        "Prefer 3 to 8 words and keep it under 80 characters."
+                    ),
+                ),
+                ChatMessage(
+                    role="user",
+                    content=(
+                        "User question:\n"
+                        f"{request.question.strip()}\n\n"
+                        "Generated SQL, if useful:\n"
+                        f"{(request.sql or '').strip()}\n\n"
+                        "Return the metric name only."
+                    ),
+                ),
+            ],
+        )
+    )
+
+    return normalize_metric_title(response.content, fallback)
+
+
 def build_client_excel_datasource_key(session: Session, filename: str) -> str:
     stem = Path(filename).stem or "excel"
     normalized = re.sub(r"[^a-z0-9_-]+", "_", stem.lower()).strip("_-") or "excel"
@@ -1416,6 +1497,23 @@ def create_overview_widget_from_query(
     }
 
 
+@router.post("/overview/widgets/title-suggestion")
+def suggest_overview_widget_title(
+    request: OverviewWidgetTitleSuggestionRequest,
+    _principal: AuthenticatedSession = Depends(get_current_api_user),
+    session: Session = Depends(get_session),
+) -> dict[str, Any]:
+    try:
+        title = suggest_metric_title_with_llm(session, request)
+    except (ConfigurationError, LlmProviderError, ValueError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        ) from exc
+
+    return {"title": title}
+
+
 @router.put("/overview/widgets/{widget_key}")
 def update_overview_widget(
     widget_key: str,

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/api/v1/dashboards.py

@@ -48,6 +48,11 @@ class DashboardCreateRequest(BaseModel):
     description: str = Field(default="", max_length=2_000)
 
 
+class DashboardUpdateRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=255)
+    description: str = Field(default="", max_length=2_000)
+
+
 class ActiveDashboardRequest(BaseModel):
     dashboard_id: str = Field(min_length=1, max_length=64)
 
@@ -58,6 +63,10 @@ class DashboardWidgetCreateRequest(BaseModel):
     visualization_type: str = Field(pattern=r"^(number|bar|stacked_bar|line|multi_line|pie|area|table)$")
 
 
+class SavedMetricUpdateRequest(BaseModel):
+    label: str = Field(min_length=1, max_length=255)
+
+
 class DashboardWidgetLayoutItem(BaseModel):
     widget_id: str = Field(min_length=1, max_length=64)
     x: int = Field(ge=0, le=11)
@@ -223,6 +232,19 @@ def get_saved_metric_for_owner(
     )
 
 
+def get_saved_metric_link_for_owner(
+    session: Session,
+    widget_key: str,
+    owner_user_id: str,
+) -> UserSavedMetric | None:
+    return session.scalar(
+        select(UserSavedMetric).where(
+            UserSavedMetric.widget_key == widget_key,
+            UserSavedMetric.owner_user_id == owner_user_id,
+        )
+    )
+
+
 def list_saved_metrics_for_owner(
     session: Session,
     owner_user_id: str,
@@ -308,16 +330,93 @@ def list_dashboards(
 
 @router.get("/dashboards/metrics")
 def list_saved_dashboard_metrics(
+    include_result: bool = True,
     principal: AuthenticatedSession = Depends(get_current_api_user),
     session: Session = Depends(get_session),
 ) -> dict[str, Any]:
     metrics = list_saved_metrics_for_owner(session, dashboard_owner_user_id(principal))
     return {
-        "items": [serialize_saved_metric(session, metric) for metric in metrics],
+        "items": [
+            serialize_saved_metric(session, metric, include_result=include_result)
+            for metric in metrics
+        ],
         "viewer": dashboard_owner_username(principal),
     }
 
 
+@router.patch("/dashboards/metrics/{widget_key}")
+def update_saved_dashboard_metric(
+    widget_key: str,
+    request: SavedMetricUpdateRequest,
+    principal: AuthenticatedSession = Depends(get_current_api_user),
+    session: Session = Depends(get_session),
+) -> dict[str, Any]:
+    owner_user_id = dashboard_owner_user_id(principal)
+    metric = get_saved_metric_for_owner(session, widget_key, owner_user_id)
+    if metric is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Saved metric not found.",
+        )
+
+    label = request.label.strip()
+    if not label:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Metric name is required.",
+        )
+
+    metric.label = label
+    metric.updated_by = dashboard_owner_username(principal)
+    session.commit()
+
+    return {"item": serialize_saved_metric(session, metric, include_result=False)}
+
+
+@router.delete("/dashboards/metrics/{widget_key}")
+def delete_saved_dashboard_metric(
+    widget_key: str,
+    principal: AuthenticatedSession = Depends(get_current_api_user),
+    session: Session = Depends(get_session),
+) -> dict[str, Any]:
+    owner_user_id = dashboard_owner_user_id(principal)
+    metric = get_saved_metric_for_owner(session, widget_key, owner_user_id)
+    metric_link = get_saved_metric_link_for_owner(session, widget_key, owner_user_id)
+    if metric is None or metric_link is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Saved metric not found.",
+        )
+
+    dashboard_widgets = list(
+        session.scalars(
+            select(DashboardWidget).where(
+                DashboardWidget.metric_widget_key == widget_key,
+                DashboardWidget.owner_user_id == owner_user_id,
+            )
+        )
+    )
+    for widget in dashboard_widgets:
+        session.delete(widget)
+
+    session.delete(metric_link)
+    session.flush()
+
+    remaining_links = session.scalar(
+        select(UserSavedMetric.id).where(UserSavedMetric.widget_key == widget_key)
+    )
+    if remaining_links is None:
+        session.delete(metric)
+
+    session.commit()
+
+    return {
+        "status": "deleted",
+        "widget_key": widget_key,
+        "removed_dashboard_widgets": len(dashboard_widgets),
+    }
+
+
 @router.post("/dashboards")
 def create_dashboard(
     request: DashboardCreateRequest,
@@ -378,6 +477,40 @@ def set_active_dashboard(
     }
 
 
+@router.put("/dashboards/{dashboard_id}")
+def update_dashboard(
+    dashboard_id: str,
+    request: DashboardUpdateRequest,
+    principal: AuthenticatedSession = Depends(get_current_api_user),
+    session: Session = Depends(get_session),
+) -> dict[str, Any]:
+    dashboard = get_dashboard_for_owner(
+        session,
+        dashboard_id,
+        dashboard_owner_user_id(principal),
+    )
+
+    if dashboard is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Dashboard not found.",
+        )
+
+    name = request.name.strip()
+    if not name:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Dashboard name is required.",
+        )
+
+    dashboard.name = name
+    dashboard.description = request.description.strip()
+    dashboard.owner_username = dashboard_owner_username(principal)
+    session.commit()
+
+    return {"item": serialize_dashboard(dashboard)}
+
+
 @router.get("/dashboards/{dashboard_id}/widgets")
 def list_widgets_for_dashboard(
     dashboard_id: str,

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/api/v1/query.py

@@ -38,6 +38,7 @@ from gaard_core.sql_validator.select_only import SelectOnlySqlValidator
 from gaard_llm.openai_compatible.client import OpenAICompatibleClient
 
 from gaard_api.admin.prompt_runtime import (
+    get_conversation_context_prompt_compiler,
     get_intent_classification_prompt_compiler,
     get_result_classification_prompt_compiler,
     get_result_interpretation_prompt_compiler,
@@ -230,6 +231,7 @@ def create_conversation_context_classifier(
             client=create_llm_client(llm_config),
             model=llm_config.model,
             extra_body=llm_config.extra_body,
+            prompt_compiler=get_conversation_context_prompt_compiler(),
         )
 
     raise ConfigurationError(
@@ -799,20 +801,21 @@ def resolve_request_conversation(
             ),
         )
 
-    deterministic = deterministic_follow_up_classification(request, context)
-    if deterministic is not None:
-        return (
-            conversation,
-            deterministic,
-            request.model_copy(
-                update={
-                    "question": deterministic.standalone_question,
-                    "conversation_id": conversation.conversation_id,
-                }
-            ),
-        )
-
     context_mode = resolve_intent_classification_mode()
+    if context_mode != "llm":
+        deterministic = deterministic_follow_up_classification(request, context)
+        if deterministic is not None:
+            return (
+                conversation,
+                deterministic,
+                request.model_copy(
+                    update={
+                        "question": deterministic.standalone_question,
+                        "conversation_id": conversation.conversation_id,
+                    }
+                ),
+            )
+
     llm_config = get_llm_runtime_config_safe() if context_mode == "llm" else None
     classification = create_conversation_context_classifier(llm_config).classify(
         request,
@@ -831,6 +834,8 @@ def resolve_request_conversation(
             request.question,
             standalone_question,
             context,
+            classification,
+            allow_deterministic_fallback=context_mode != "llm",
         )
         if guard_rewrite is None:
             classification = classification.model_copy(
@@ -897,6 +902,7 @@ def deterministic_follow_up_classification(
                 "and change only the requested output fields."
             ),
             model_response=projected_result,
+            source="deterministic",
         )
 
     if is_open_only_command(question):
@@ -911,6 +917,7 @@ def deterministic_follow_up_classification(
             standalone_question=filter_rewrite["standalone_question"],
             reason="Deterministic rewrite: preserve previous topic and add open-status filter.",
             model_response=filter_rewrite,
+            source="deterministic",
         )
 
     previous_period = rewrite_previous_period_follow_up(previous, previous_question, question)
@@ -921,6 +928,7 @@ def deterministic_follow_up_classification(
             standalone_question=previous_period["standalone_question"],
             reason="Deterministic rewrite: replace current time period with previous period.",
             model_response=previous_period,
+            source="deterministic",
         )
 
     return None
@@ -930,6 +938,9 @@ def guard_follow_up_rewrite(
     original_question: str,
     standalone_question: str,
     context: dict[str, Any],
+    classification: ConversationContextClassification,
+    *,
+    allow_deterministic_fallback: bool,
 ) -> str | None:
     original = normalize_question_text(original_question)
     standalone = normalize_question_text(standalone_question)
@@ -944,6 +955,10 @@ def guard_follow_up_rewrite(
     )
 
     if rewrite_is_too_close_to_original(original, standalone):
+        if classification.model_response.get("current_question_is_standalone") is True:
+            return original_question.strip()
+        if not allow_deterministic_fallback:
+            return None
         deterministic = deterministic_follow_up_classification(
             QueryRequest(question=original_question),
             context,
@@ -955,6 +970,8 @@ def guard_follow_up_rewrite(
     if is_open_only_command(original) and not carries_previous_context(
         standalone, previous_question
     ):
+        if not allow_deterministic_fallback:
+            return None
         deterministic = deterministic_follow_up_classification(
             QueryRequest(question=original_question),
             context,

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/conversations.py

@@ -210,6 +210,9 @@ def build_conversation_metadata(
         "standalone_question": classification.standalone_question,
         "confidence": classification.confidence,
         "context_reason": classification.reason,
+        "context_source": classification.source,
+        "context_model_response": classification.model_response,
+        "context_prompt": classification.prompt,
     }
 
 
@@ -221,6 +224,7 @@ def new_topic_classification(
         confidence=confidence,
         standalone_question=question,
         reason="Started a new conversation context.",
+        source="system",
     )
 
 
@@ -327,6 +331,10 @@ def conversation_turn_metadata(
     compact = compact_response_metadata(metadata)
     compact["context_reason"] = context_classification.reason
     compact["context_model_response"] = context_classification.model_response
+    if context_classification.prompt:
+        compact["context_prompt"] = context_classification.prompt
+    if context_classification.source:
+        compact["context_source"] = context_classification.source
     compact["working_context"] = build_working_context(
         original_question=original_question,
         standalone_question=standalone_question,

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api/main.py

@@ -29,7 +29,7 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(
     title="GAARD API",
-    version="0.2.5",
+    version="0.2.7",
     description="Self-hosted AI SQL Gateway for governed natural-language access to relational data.",
     lifespan=lifespan,
 )

{gaard_api-0.2.5 → gaard_api-0.2.7/src/gaard_api.egg-info}/PKG-INFO

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

{gaard_api-0.2.5 → gaard_api-0.2.7}/src/gaard_api.egg-info/requires.txt

@@ -1,7 +1,7 @@
-gaard-core==0.2.4
-gaard-connectors==0.2.4
-gaard-llm==0.2.4
-gaard-plugin-api<0.3.0,>=0.2.4
+gaard-core==0.2.7
+gaard-connectors==0.2.7
+gaard-llm==0.2.7
+gaard-plugin-api<0.3.0,>=0.2.7
 fastapi>=0.111.0
 uvicorn[standard]>=0.30.0
 pydantic>=2.7.0

{gaard_api-0.2.5 → gaard_api-0.2.7}/tests/test_admin_api.py

@@ -400,6 +400,30 @@ def test_dashboards_are_scoped_to_authenticated_user(admin_client: TestClient) -
     assert metrics_response.json()["items"][0]["widget_key"] == "admin_saved_metric"
     assert metrics_response.json()["items"][0]["result"]["status"] == "ok"
 
+    lightweight_metrics_response = admin_client.get(
+        "/api/v1/dashboards/metrics?include_result=false",
+        headers=admin_headers,
+    )
+    assert lightweight_metrics_response.status_code == 200
+    assert lightweight_metrics_response.json()["items"][0]["widget_key"] == "admin_saved_metric"
+    assert "result" not in lightweight_metrics_response.json()["items"][0]
+
+    rename_metric_response = admin_client.patch(
+        "/api/v1/dashboards/metrics/admin_saved_metric",
+        headers=admin_headers,
+        json={"label": "Updated prompt count"},
+    )
+    assert rename_metric_response.status_code == 200
+    assert rename_metric_response.json()["item"]["label"] == "Updated prompt count"
+    assert "result" not in rename_metric_response.json()["item"]
+
+    cross_rename_metric_response = admin_client.patch(
+        "/api/v1/dashboards/metrics/admin_saved_metric",
+        headers=analyst_headers,
+        json={"label": "Cross user rename"},
+    )
+    assert cross_rename_metric_response.status_code == 404
+
     dashboard_widget_response = admin_client.post(
         f"/api/v1/dashboards/{admin_dashboard['id']}/widgets",
         headers=admin_headers,
@@ -462,6 +486,68 @@ def test_dashboards_are_scoped_to_authenticated_user(admin_client: TestClient) -
         "h": 3,
     }
 
+    cross_delete_metric_response = admin_client.delete(
+        "/api/v1/dashboards/metrics/admin_saved_metric",
+        headers=analyst_headers,
+    )
+    assert cross_delete_metric_response.status_code == 404
+
+    delete_metric_response = admin_client.delete(
+        "/api/v1/dashboards/metrics/admin_saved_metric",
+        headers=admin_headers,
+    )
+    assert delete_metric_response.status_code == 200
+    assert delete_metric_response.json() == {
+        "status": "deleted",
+        "widget_key": "admin_saved_metric",
+        "removed_dashboard_widgets": 1,
+    }
+
+    deleted_metric_list = admin_client.get(
+        "/api/v1/dashboards/metrics",
+        headers=admin_headers,
+    )
+    assert deleted_metric_list.status_code == 200
+    assert all(
+        item["widget_key"] != "admin_saved_metric"
+        for item in deleted_metric_list.json()["items"]
+    )
+
+    widgets_after_metric_delete = admin_client.get(
+        f"/api/v1/dashboards/{admin_dashboard['id']}/widgets",
+        headers=admin_headers,
+    )
+    assert widgets_after_metric_delete.status_code == 200
+    assert widgets_after_metric_delete.json()["items"] == []
+
+    with create_session() as session:
+        assert (
+            session.scalar(
+                select(UserSavedMetric).where(
+                    UserSavedMetric.owner_user_id == "1",
+                    UserSavedMetric.widget_key == "admin_saved_metric",
+                )
+            )
+            is None
+        )
+        assert (
+            session.scalar(
+                select(DashboardWidget).where(
+                    DashboardWidget.owner_user_id == "1",
+                    DashboardWidget.metric_widget_key == "admin_saved_metric",
+                )
+            )
+            is None
+        )
+        assert (
+            session.scalar(
+                select(OverviewWidget).where(
+                    OverviewWidget.widget_key == "admin_saved_metric",
+                )
+            )
+            is None
+        )
+
     admin_list = admin_client.get("/api/v1/dashboards", headers=admin_headers)
     analyst_list = admin_client.get("/api/v1/dashboards", headers=analyst_headers)
 
@@ -483,6 +569,30 @@ def test_dashboards_are_scoped_to_authenticated_user(admin_client: TestClient) -
     )
     assert cross_delete.status_code == 404
 
+    update_dashboard_response = admin_client.put(
+        f"/api/v1/dashboards/{admin_dashboard['id']}",
+        headers=admin_headers,
+        json={
+            "name": "Operations renamed",
+            "description": "Updated daily operational dashboard.",
+        },
+    )
+    assert update_dashboard_response.status_code == 200
+    assert update_dashboard_response.json()["item"]["name"] == "Operations renamed"
+    assert update_dashboard_response.json()["item"]["description"] == (
+        "Updated daily operational dashboard."
+    )
+
+    cross_update_dashboard_response = admin_client.put(
+        f"/api/v1/dashboards/{analyst_dashboard['id']}",
+        headers=admin_headers,
+        json={
+            "name": "Cross user rename",
+            "description": "Should not be allowed.",
+        },
+    )
+    assert cross_update_dashboard_response.status_code == 404
+
     admin_dashboards = admin_client.get(
         "/api/v1/admin/dashboards",
         headers=admin_headers,
@@ -706,7 +816,9 @@ def test_admin_first_login_requires_password_change(admin_client: TestClient) ->
     )
 
     assert prompts_response.status_code == 200
-    assert len(prompts_response.json()["items"]) >= 2
+    prompt_keys = {item["prompt_key"] for item in prompts_response.json()["items"]}
+    assert len(prompt_keys) >= 2
+    assert "conversation_context_classification" in prompt_keys
 
 
 def test_prompt_update_creates_admin_audit_event(admin_client: TestClient) -> None:
@@ -1432,6 +1544,57 @@ def test_overview_widget_can_be_saved_from_query_and_deleted(
     )
 
 
+def test_overview_widget_title_suggestion_uses_llm(
+    admin_client: TestClient,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    headers = auth_headers(admin_client)
+
+    with create_session() as session:
+        set_setting(session, "gaard_llm_api_key", "test-key", "test")
+        set_setting(session, "gaard_llm_model", "title-model", "test")
+        session.commit()
+
+    class FakeOpenAICompatibleClient:
+        init_kwargs: dict | None = None
+        requests = []
+
+        def __init__(self, **kwargs) -> None:
+            self.__class__.init_kwargs = kwargs
+
+        def create_chat_completion(self, request):
+            self.__class__.requests.append(request)
+            return ChatCompletionResponse(
+                content="```text\nDoctors by Specialty.\n```",
+                model=request.model,
+            )
+
+    monkeypatch.setattr(
+        "gaard_api.api.v1.admin.OpenAICompatibleClient",
+        FakeOpenAICompatibleClient,
+    )
+
+    response = admin_client.post(
+        "/api/v1/admin/overview/widgets/title-suggestion",
+        headers=headers,
+        json={
+            "question": "How many doctors are there by specialty?",
+            "sql": "SELECT specialization, COUNT(*) FROM doctors GROUP BY specialization",
+        },
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"title": "Doctors by Specialty"}
+    assert FakeOpenAICompatibleClient.init_kwargs is not None
+    assert FakeOpenAICompatibleClient.init_kwargs["api_key"] == "test-key"
+    request = FakeOpenAICompatibleClient.requests[0]
+    assert request.model == "title-model"
+    assert request.temperature == 0.0
+    assert request.messages[0].role == "system"
+    assert "same language as the user question" in request.messages[0].content
+    assert "How many doctors" in request.messages[1].content
+
+
 def test_overview_widget_from_query_strips_datasource_qualifier(
     admin_client: TestClient,
 ) -> None:

{gaard_api-0.2.5 → gaard_api-0.2.7}/tests/test_conversation_api.py

@@ -441,6 +441,83 @@ def test_query_follow_up_guard_rejects_unrewritten_classifier_output(
     assert payload["metadata"]["conversation"]["context_decision"] == "ambiguous"
 
 
+def test_query_accepts_llm_follow_up_when_current_question_is_standalone(
+    conversation_client: TestClient,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    headers = auth_headers(conversation_client)
+    first = conversation_client.post(
+        "/api/v1/query",
+        headers=headers,
+        json={
+            "question": "ilu pacjentów było przyjętych tydzień temu",
+            "user_id": "alice",
+        },
+    )
+    assert first.status_code == 200
+    conversation_id = first.json()["metadata"]["conversation"]["id"]
+
+    second = conversation_client.post(
+        "/api/v1/query",
+        headers=headers,
+        json={
+            "question": "a dwa tygodnie temu?",
+            "user_id": "alice",
+            "conversation_id": conversation_id,
+        },
+    )
+    assert second.status_code == 200
+
+    class StandaloneContinuationClassifier:
+        def classify(self, request, context):
+            return ConversationContextClassification(
+                decision=ConversationContextDecision.FOLLOW_UP,
+                confidence=0.92,
+                standalone_question=request.question,
+                reason="LLM classified this as a logical continuation with a standalone question.",
+                model_response={
+                    "is_continuation": True,
+                    "current_question_is_standalone": True,
+                },
+                prompt={
+                    "system_prompt": "Decide whether turn t is a logical continuation.",
+                    "user_prompt": "turn_t_minus_1 + turn_t",
+                    "metadata": {"decision_task": "logical_continuation_yes_no"},
+                },
+                source="llm",
+            )
+
+    monkeypatch.setattr(
+        query_module,
+        "create_conversation_context_classifier",
+        lambda _llm_config=None: StandaloneContinuationClassifier(),
+    )
+
+    third = conversation_client.post(
+        "/api/v1/query",
+        headers=headers,
+        json={
+            "question": "ilu pacjentów przyjęto w tym tygodniu",
+            "user_id": "alice",
+            "conversation_id": conversation_id,
+        },
+    )
+
+    assert third.status_code == 200
+    payload = third.json()
+    conversation = payload["metadata"]["conversation"]
+    assert payload["sql"]
+    assert payload["metadata"].get("blocked") is not True
+    assert "Potrzebuję doprecyzowania" not in payload["answer"]
+    assert conversation["context_decision"] == "follow_up"
+    assert conversation["standalone_question"] == "ilu pacjentów przyjęto w tym tygodniu"
+    assert conversation["context_source"] == "llm"
+    assert conversation["context_model_response"]["is_continuation"] is True
+    assert conversation["context_prompt"]["metadata"]["decision_task"] == (
+        "logical_continuation_yes_no"
+    )
+
+
 def test_query_turn_metadata_keeps_context_reason_and_working_context(
     conversation_client: TestClient,
 ) -> None:

{gaard_api-0.2.5 → gaard_api-0.2.7}/tests/test_prompt_runtime.py

@@ -4,6 +4,7 @@ from gaard_core.query_pipeline.models import QueryRequest, QueryResult
 
 from gaard_api.admin.models import PromptTemplate
 from gaard_api.admin.prompt_runtime import (
+    MetadataConversationContextPromptCompiler,
     MetadataIntentClassificationPromptCompiler,
     MetadataResultClassificationPromptCompiler,
     MetadataResultInterpretationPromptCompiler,
@@ -59,6 +60,44 @@ def test_metadata_intent_classification_prompt_compiler_serializes_question() ->
     assert compiled.metadata["prompt_key"] == "intent_classification"
 
 
+def test_metadata_conversation_context_prompt_compiler_serializes_recent_turns() -> None:
+    compiler = MetadataConversationContextPromptCompiler(
+        prompt_template=PromptTemplate(
+            prompt_key="conversation_context_classification",
+            name="Conversation context classification",
+            system_prompt="system",
+            user_prompt_template="{payload}\n{question}",
+            version=3,
+            active=True,
+        )
+    )
+
+    compiled = compiler.compile(
+        request=QueryRequest(question="ilu pacjentów przyjęto w tym tygodniu"),
+        conversation_context={
+            "turns": [
+                {
+                    "question": "ilu pacjentów było przyjętych tydzień temu",
+                    "answer": "12",
+                },
+                {
+                    "question": "a dwa tygodnie temu?",
+                    "standalone_question": "ilu pacjentów było przyjętych dwa tygodnie temu",
+                    "answer": "9",
+                },
+            ]
+        },
+    )
+
+    assert '"turn_t_minus_2"' in compiled.user_prompt
+    assert '"turn_t_minus_1"' in compiled.user_prompt
+    assert '"turn_t"' in compiled.user_prompt
+    assert "ilu pacjentów przyjęto w tym tygodniu" in compiled.user_prompt
+    assert compiled.metadata["prompt_key"] == "conversation_context_classification"
+    assert compiled.metadata["prompt_version"] == 3
+    assert compiled.metadata["decision_task"] == "logical_continuation_yes_no"
+
+
 def test_metadata_result_classification_prompt_compiler_serializes_answer() -> None:
     compiler = MetadataResultClassificationPromptCompiler(
         prompt_template=PromptTemplate(