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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: gaard-api
-Version: 0.2.5
+Version: 0.2.6
 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.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: 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.6}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gaard-api"
-version = "0.2.5"
+version = "0.2.6"
 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.6",
+    "gaard-connectors==0.2.6",
+    "gaard-llm==0.2.6",
+    "gaard-plugin-api>=0.2.6,<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.6}/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.6}/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)
@@ -308,16 +317,49 @@ 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.post("/dashboards")
 def create_dashboard(
     request: DashboardCreateRequest,
@@ -378,6 +420,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.6}/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.6",
     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.6/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.6
 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.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: 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.6}/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.6
+gaard-connectors==0.2.6
+gaard-llm==0.2.6
+gaard-plugin-api<0.3.0,>=0.2.6
 fastapi>=0.111.0
 uvicorn[standard]>=0.30.0
 pydantic>=2.7.0

{gaard_api-0.2.5 → gaard_api-0.2.6}/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,
@@ -483,6 +507,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,
@@ -1432,6 +1480,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: