gaard-api 0.2.16__tar.gz → 0.2.18__tar.gz

{gaard_api-0.2.16/src/gaard_api.egg-info → gaard_api-0.2.18}/PKG-INFO

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

{gaard_api-0.2.16 → gaard_api-0.2.18}/pyproject.toml

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

{gaard_api-0.2.16 → gaard_api-0.2.18}/src/gaard_api/admin/services.py

@@ -1839,10 +1839,19 @@ def upsert_analysis_business_logic_suggestion(
         session.flush()
         return existing
 
+    should_enable = auto_enable or existing.enabled
     existing.source_audit_id = source_audit_id
-    existing.status = BUSINESS_LOGIC_STATUS_ACTIVE if auto_enable else BUSINESS_LOGIC_STATUS_PENDING
-    existing.safety = BUSINESS_LOGIC_SAFETY_SAFE if auto_enable else BUSINESS_LOGIC_SAFETY_REVIEW
-    existing.enabled = auto_enable
+    existing.status = (
+        BUSINESS_LOGIC_STATUS_ACTIVE
+        if should_enable
+        else BUSINESS_LOGIC_STATUS_PENDING
+    )
+    existing.safety = (
+        BUSINESS_LOGIC_SAFETY_SAFE
+        if should_enable
+        else BUSINESS_LOGIC_SAFETY_REVIEW
+    )
+    existing.enabled = should_enable
     existing.error_category = normalized_type
     existing.title = normalized_title
     existing.rule_text = normalized_rule

{gaard_api-0.2.16 → gaard_api-0.2.18}/src/gaard_api/analysis_findings.py

@@ -186,6 +186,46 @@ def create_analysis_finding(
     return finding
 
 
+def get_analysis_finding_for_business_logic_suggestion(
+    session: Session,
+    *,
+    investigation_id: str,
+    owner_user_id: str,
+    business_logic_suggestion_id: int,
+) -> AnalysisFinding | None:
+    return session.scalar(
+        select(AnalysisFinding)
+        .where(
+            AnalysisFinding.investigation_id == investigation_id,
+            AnalysisFinding.owner_user_id == owner_user_id,
+            AnalysisFinding.business_logic_suggestion_id == business_logic_suggestion_id,
+        )
+        .order_by(AnalysisFinding.id.asc())
+    )
+
+
+def refresh_analysis_finding_observation(
+    finding: AnalysisFinding,
+    *,
+    statement: str,
+    finding_type: str,
+    confidence: float,
+    critique: str,
+    scope: dict[str, Any],
+    evidence_refs: list[str],
+) -> AnalysisFinding:
+    finding.statement = remove_thinking_blocks(statement).strip()[:4_000]
+    finding.finding_type = (finding_type.strip() or "finding")[:100]
+    finding.confidence = max(0.0, min(1.0, float(confidence)))
+    finding.critique = remove_thinking_blocks(critique).strip()[:4_000]
+    finding.scope_json = json_dumps(scope)
+    finding.evidence_refs_json = json_dumps(
+        unique_texts(text_list(finding.evidence_refs_json) + evidence_refs)
+    )
+    finding.contract_version = FINDING_CONTRACT_VERSION
+    return finding
+
+
 def get_owned_analysis_finding(
     session: Session,
     *,

{gaard_api-0.2.16 → gaard_api-0.2.18}/src/gaard_api/api/v1/analysis.py

@@ -45,10 +45,12 @@ from gaard_api.analysis_findings import (
     create_analysis_finding,
     create_radar_finding_decision,
     format_working_knowledge,
+    get_analysis_finding_for_business_logic_suggestion,
     get_owned_analysis_finding,
     list_active_analysis_findings,
     list_owned_analysis_findings,
     record_finding_usage,
+    refresh_analysis_finding_observation,
     serialize_analysis_finding,
     serialize_finding_decision,
     serialize_working_knowledge_item,
@@ -81,6 +83,27 @@ EVIDENCE_REFERENCE_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]{0,63}:[^\s]{1,190}$
 ACTIVE_WORKING_KNOWLEDGE_STATUSES = {"running", "waiting_for_user"}
 
 
+def normalize_planner_text_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+
+    items = value if isinstance(value, list) else [value]
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for item in items:
+        if item is None or isinstance(item, bool):
+            continue
+        if not isinstance(item, (str, int, float)):
+            continue
+        text = str(item).strip()
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        normalized.append(text)
+
+    return normalized
+
+
 class AnalysisAction(StrEnum):
     ANSWER_FROM_CONTEXT = "answer_from_context"
     ASK_USER = "ask_user"
@@ -101,6 +124,11 @@ class AnalysisBusinessLogicFinding(BaseModel):
     terms: list[str] = Field(default_factory=list)
     confidence: float = Field(default=0.0, ge=0.0, le=1.0)
 
+    @field_validator("evidence_refs", "terms", mode="before")
+    @classmethod
+    def normalize_text_lists(cls, value: Any) -> list[str]:
+        return normalize_planner_text_list(value)
+
 
 class AnalysisFindingEvidenceUpdate(BaseModel):
     finding_id: str = Field(min_length=1, max_length=64)
@@ -109,6 +137,11 @@ class AnalysisFindingEvidenceUpdate(BaseModel):
     summary: str = Field(min_length=1, max_length=4_000)
     evidence_refs: list[str] = Field(default_factory=list, max_length=100)
 
+    @field_validator("evidence_refs", mode="before")
+    @classmethod
+    def normalize_evidence_refs(cls, value: Any) -> list[str]:
+        return normalize_planner_text_list(value)
+
 
 class AnalysisFindingUsage(BaseModel):
     finding_id: str = Field(min_length=1, max_length=64)
@@ -118,6 +151,11 @@ class AnalysisFindingUsage(BaseModel):
     statement: str = Field(min_length=1, max_length=4_000)
     evidence_refs: list[str] = Field(default_factory=list, max_length=100)
 
+    @field_validator("evidence_refs", mode="before")
+    @classmethod
+    def normalize_evidence_refs(cls, value: Any) -> list[str]:
+        return normalize_planner_text_list(value)
+
 
 class AnalysisPlannerDecision(BaseModel):
     action: AnalysisAction
@@ -1004,7 +1042,7 @@ Business logic learning:
 - If the latest database observation reveals durable knowledge such as dictionary values, terminology meaning, table meaning, column meaning, or stable domain rules, include business_logic.create_suggestion=true.
 - Distinct values, enumerations, statuses, categories, and table/column meaning discovered through ask_database should be saved as business logic findings unless they are clearly one-off metrics for the current answer.
 - Do not create business logic for one-off answer values that are only useful for the current final answer.
-- statement must be a short, self-contained semantic claim. critique must state its main limitation or counterargument. Cite supporting query references in evidence_refs. Never include private chain-of-thought.
+- statement must be a short, self-contained semantic claim. critique must state its main limitation or counterargument. Cite supporting query references as JSON strings in evidence_refs; use the form "query:<audit_id>" for query audit references. Never include private chain-of-thought.
 
 Investigation-scoped working knowledge:
 - session_context.working_knowledge contains externally reviewed semantic evidence for this investigation only.
@@ -1185,22 +1223,42 @@ def save_business_logic_finding(
             auto_enable=runtime_config.analysis_auto_enable_business_logic,
             actor=f"analysis:{session_id}",
         )
-        finding_record = create_analysis_finding(
+        critique = first_non_empty(
+            finding.critique,
+            "Confirmed only by evidence from this investigation and datasource.",
+        )
+        scope = finding_scope(finding, connector.connector_key, context)
+        evidence_refs = finding_evidence_refs(finding, context)
+        finding_record = get_analysis_finding_for_business_logic_suggestion(
             session,
             investigation_id=session_id,
             owner_user_id=record.user_id,
-            connector_id=connector.id,
             business_logic_suggestion_id=suggestion.id,
-            statement=statement,
-            finding_type=finding.knowledge_type,
-            confidence=finding.confidence,
-            critique=first_non_empty(
-                finding.critique,
-                "Confirmed only by evidence from this investigation and datasource.",
-            ),
-            scope=finding_scope(finding, connector.connector_key, context),
-            evidence_refs=finding_evidence_refs(finding, context),
         )
+        if finding_record is None:
+            finding_record = create_analysis_finding(
+                session,
+                investigation_id=session_id,
+                owner_user_id=record.user_id,
+                connector_id=connector.id,
+                business_logic_suggestion_id=suggestion.id,
+                statement=statement,
+                finding_type=finding.knowledge_type,
+                confidence=finding.confidence,
+                critique=critique,
+                scope=scope,
+                evidence_refs=evidence_refs,
+            )
+        else:
+            refresh_analysis_finding_observation(
+                finding_record,
+                statement=statement,
+                finding_type=finding.knowledge_type,
+                confidence=finding.confidence,
+                critique=critique,
+                scope=scope,
+                evidence_refs=evidence_refs,
+            )
         session.commit()
         finding_payload = serialize_analysis_finding(finding_record)
         return {

{gaard_api-0.2.16 → gaard_api-0.2.18}/src/gaard_api/main.py

@@ -40,7 +40,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
 
 app = FastAPI(
     title="GAARD API",
-    version="0.2.16",
+    version="0.2.18",
     description="Self-hosted AI SQL Gateway for governed natural-language access to relational data.",
     lifespan=lifespan,
 )

{gaard_api-0.2.16 → gaard_api-0.2.18/src/gaard_api.egg-info}/PKG-INFO

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

{gaard_api-0.2.16 → gaard_api-0.2.18}/src/gaard_api.egg-info/requires.txt

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

{gaard_api-0.2.16 → gaard_api-0.2.18}/tests/test_analysis_api.py

@@ -134,6 +134,42 @@ def create_active_default_datasource() -> DatasourceConnector:
         return connector
 
 
+def test_analysis_planner_normalizes_model_generated_text_lists() -> None:
+    decision = analysis_module.parse_analysis_decision(
+        json.dumps(
+            {
+                "action": "answer_from_context",
+                "business_logic": {
+                    "evidence_refs": [156, " 157 ", 156, None, False, {"audit_id": 158}],
+                    "terms": [" cardiology ", 23, "cardiology", None],
+                },
+                "finding_updates": [
+                    {
+                        "finding_id": "finding-1",
+                        "effect": "strengthened",
+                        "confidence": 0.9,
+                        "summary": "Confirmed by another query.",
+                        "evidence_refs": 158,
+                    }
+                ],
+                "finding_usages": [
+                    {
+                        "finding_id": "finding-1",
+                        "usage": "used_for_query",
+                        "statement": "Used to constrain the query.",
+                        "evidence_refs": "query:159",
+                    }
+                ],
+            }
+        )
+    )
+
+    assert decision.business_logic.evidence_refs == ["156", "157"]
+    assert decision.business_logic.terms == ["cardiology", "23"]
+    assert decision.finding_updates[0].evidence_refs == ["158"]
+    assert decision.finding_usages[0].evidence_refs == ["query:159"]
+
+
 def test_analysis_stream_runs_final_query_and_persists_session(
     analysis_client: TestClient,
 ) -> None:
@@ -340,6 +376,146 @@ def test_analysis_database_step_can_record_business_logic_suggestion(
         assert suggestions[0].error_category == "analysis.dictionary_value"
 
 
+def test_repeated_analysis_finding_preserves_review_decisions(
+    analysis_client: TestClient,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    headers = auth_headers(analysis_client)
+    connector = create_active_default_datasource()
+
+    def repeated_finding() -> analysis_module.AnalysisBusinessLogicFinding:
+        return analysis_module.AnalysisBusinessLogicFinding(
+            create_suggestion=True,
+            knowledge_type="semantic_mapping",
+            title="Cardiology dictionary mapping",
+            rule_text="The dictionary value for cardiology is cardiology.",
+            statement="The dictionary value for cardiology is cardiology.",
+            confidence=0.94,
+            critique="The mapping is confirmed only in the current datasource.",
+            scope={"entity": "specialization", "field": "specialization_name"},
+            evidence_refs=["query:dictionary-check"],
+        )
+
+    class RepeatedFindingPlanner:
+        def __init__(self) -> None:
+            self.calls = 0
+            self.working_knowledge_seen: list[list[dict[str, Any]]] = []
+
+        def decide(
+            self, request: Any, datasource_context: Any, context: dict[str, Any]
+        ) -> analysis_module.AnalysisPlannerDecision:
+            self.calls += 1
+            self.working_knowledge_seen.append(list(context.get("working_knowledge") or []))
+            return analysis_module.AnalysisPlannerDecision(
+                action=analysis_module.AnalysisAction.ASK_USER,
+                visible_question=f"Review mapping attempt {self.calls}.",
+                visible_reasoning="The same semantic mapping was observed again.",
+                user_question="Continue after review.",
+                business_logic=repeated_finding(),
+            )
+
+    planner = RepeatedFindingPlanner()
+    monkeypatch.setattr(analysis_module, "create_analysis_planner", lambda: planner)
+
+    response = analysis_client.post(
+        "/api/v1/analysis/stream",
+        headers=headers,
+        json={"question": "Find the cardiology dictionary value.", "user_id": "spoofed"},
+    )
+    assert response.status_code == 200
+    events = parse_ndjson(response.text)
+    session_id = events[0]["session_id"]
+    first_suggestion = next(
+        item["business_logic_suggestion"]
+        for item in events
+        if item["event"] == "business_logic_suggestion"
+    )
+    finding_id = first_suggestion["finding_id"]
+
+    radar_decision_payload = {
+        "finding_id": finding_id,
+        "decision": "accept_for_investigation",
+        "confidence": 0.93,
+        "verdict": "The observed values explain the terminology lookup.",
+        "scope": {
+            "investigation_id": session_id,
+            "radar_run_id": "radar-repeat-1",
+        },
+        "evidence_refs": ["query:dictionary-check"],
+    }
+    accepted_response = analysis_client.post(
+        f"/api/v1/analysis/{session_id}/finding-decisions",
+        headers=headers,
+        json=radar_decision_payload,
+    )
+    assert accepted_response.status_code == 200
+    assert accepted_response.json()["accepted"] is True
+
+    repeat_response = analysis_client.post(
+        f"/api/v1/analysis/{session_id}/messages/stream",
+        headers=headers,
+        json={"message": "Continue."},
+    )
+    assert repeat_response.status_code == 200
+    repeat_events = parse_ndjson(repeat_response.text)
+    repeated_suggestion = next(
+        item["business_logic_suggestion"]
+        for item in repeat_events
+        if item["event"] == "business_logic_suggestion"
+    )
+    assert repeated_suggestion["finding_id"] == finding_id
+    assert repeated_suggestion["finding"]["status"] == "accepted_for_investigation"
+    assert planner.working_knowledge_seen[-1][0]["finding_id"] == finding_id
+
+    persistent_response = analysis_client.put(
+        f"/api/v1/analysis/{session_id}/findings/{finding_id}/decision",
+        headers=headers,
+        json={
+            "finding_id": finding_id,
+            "decision": "accept_as_persistent_business_logic",
+            "confidence": 0.93,
+            "verdict": "An administrator approved this as durable logic.",
+            "scope": {"investigation_id": session_id},
+            "evidence_refs": ["query:dictionary-check"],
+        },
+    )
+    assert persistent_response.status_code == 200
+
+    repeat_after_persistent_response = analysis_client.post(
+        f"/api/v1/analysis/{session_id}/messages/stream",
+        headers=headers,
+        json={"message": "Continue again."},
+    )
+    assert repeat_after_persistent_response.status_code == 200
+    repeat_after_persistent_events = parse_ndjson(repeat_after_persistent_response.text)
+    repeated_persistent_suggestion = next(
+        item["business_logic_suggestion"]
+        for item in repeat_after_persistent_events
+        if item["event"] == "business_logic_suggestion"
+    )
+    assert repeated_persistent_suggestion["finding_id"] == finding_id
+    assert repeated_persistent_suggestion["finding"]["status"] == (
+        "accepted_as_persistent_business_logic"
+    )
+
+    with create_session() as session:
+        findings = list(
+            session.scalars(
+                select(AnalysisFinding).where(
+                    AnalysisFinding.investigation_id == session_id
+                )
+            )
+        )
+        assert len(findings) == 1
+        assert findings[0].finding_id == finding_id
+        assert findings[0].decision == "accept_as_persistent_business_logic"
+        assert findings[0].status == "accepted_as_persistent_business_logic"
+        suggestions = list_business_logic_suggestions(session, connector.id)
+        assert len(suggestions) == 1
+        assert suggestions[0].enabled is True
+        assert suggestions[0].status == "active"
+
+
 def test_investigation_finding_review_lifecycle_and_scoped_working_knowledge(
     analysis_client: TestClient,
     monkeypatch: pytest.MonkeyPatch,