gaard-core 0.2.4__tar.gz → 0.2.7__tar.gz

{gaard_core-0.2.4 → gaard_core-0.2.7}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gaard-core
-Version: 0.2.4
+Version: 0.2.7
 Summary: Core GAARD query pipeline, prompt compiler, policies and SQL validation
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.4
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.7
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: sqlglot>=25.0.0
 Provides-Extra: dev

{gaard_core-0.2.4 → gaard_core-0.2.7}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gaard-core"
-version = "0.2.4"
+version = "0.2.7"
 description = "Core GAARD query pipeline, prompt compiler, policies and SQL validation"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "gaard-plugin-api>=0.2.4,<0.3.0",
+    "gaard-plugin-api>=0.2.7,<0.3.0",
     "pydantic>=2.7.0",
     "sqlglot>=25.0.0",
 ]

{gaard_core-0.2.4 → gaard_core-0.2.7}/src/gaard_core/conversation_context/llm_classifier.py

@@ -58,7 +58,32 @@ class LlmConversationContextClassifier:
             )
         )
 
-        return parse_conversation_context_classification(response.content)
+        classification = parse_conversation_context_classification(response.content)
+        if (
+            classification.decision == ConversationContextDecision.NEW_TOPIC
+            and not classification.standalone_question
+        ):
+            classification = classification.model_copy(
+                update={"standalone_question": request.question}
+            )
+        if (
+            classification.decision == ConversationContextDecision.FOLLOW_UP
+            and not classification.standalone_question
+            and classification.model_response.get("current_question_is_standalone") is True
+        ):
+            classification = classification.model_copy(
+                update={"standalone_question": request.question}
+            )
+        return classification.model_copy(
+            update={
+                "prompt": {
+                    "system_prompt": compiled_prompt.system_prompt,
+                    "user_prompt": compiled_prompt.user_prompt,
+                    "metadata": compiled_prompt.metadata,
+                },
+                "source": "llm",
+            }
+        )
 
 
 def parse_conversation_context_classification(
@@ -80,8 +105,12 @@ def parse_conversation_context_classification(
     if not isinstance(payload, dict):
         return ConversationContextClassification()
 
+    decision = parse_conversation_context_decision(
+        payload.get("decision"),
+        continuation_value=payload.get("is_continuation"),
+    )
     return ConversationContextClassification(
-        decision=parse_conversation_context_decision(payload.get("decision")),
+        decision=decision,
         confidence=parse_confidence(payload.get("confidence")),
         standalone_question=str(payload.get("standalone_question") or "").strip(),
         reason=str(payload.get("reason") or ""),
@@ -89,15 +118,30 @@ def parse_conversation_context_classification(
     )
 
 
-def parse_conversation_context_decision(value: object) -> ConversationContextDecision:
+def parse_conversation_context_decision(
+    value: object,
+    *,
+    continuation_value: object | None = None,
+) -> ConversationContextDecision:
+    if value is None:
+        continuation_decision = parse_continuation_decision(continuation_value)
+        if continuation_decision is not None:
+            return continuation_decision
+
     if not isinstance(value, str):
         return ConversationContextDecision.AMBIGUOUS
 
     normalized = value.strip().lower().replace(" ", "_").replace("-", "_")
     aliases = {
+        "no": ConversationContextDecision.NEW_TOPIC,
+        "nie": ConversationContextDecision.NEW_TOPIC,
+        "false": ConversationContextDecision.NEW_TOPIC,
         "new": ConversationContextDecision.NEW_TOPIC,
         "new_question": ConversationContextDecision.NEW_TOPIC,
         "newtopic": ConversationContextDecision.NEW_TOPIC,
+        "yes": ConversationContextDecision.FOLLOW_UP,
+        "tak": ConversationContextDecision.FOLLOW_UP,
+        "true": ConversationContextDecision.FOLLOW_UP,
         "continue": ConversationContextDecision.FOLLOW_UP,
         "continuation": ConversationContextDecision.FOLLOW_UP,
         "followup": ConversationContextDecision.FOLLOW_UP,
@@ -115,6 +159,24 @@ def parse_conversation_context_decision(value: object) -> ConversationContextDec
     return ConversationContextDecision.AMBIGUOUS
 
 
+def parse_continuation_decision(value: object) -> ConversationContextDecision | None:
+    if isinstance(value, bool):
+        return (
+            ConversationContextDecision.FOLLOW_UP
+            if value
+            else ConversationContextDecision.NEW_TOPIC
+        )
+    if not isinstance(value, str):
+        return None
+
+    normalized = value.strip().lower()
+    if normalized in {"yes", "y", "true", "tak", "t"}:
+        return ConversationContextDecision.FOLLOW_UP
+    if normalized in {"no", "n", "false", "nie"}:
+        return ConversationContextDecision.NEW_TOPIC
+    return None
+
+
 def parse_confidence(value: object) -> float:
     try:
         confidence = float(cast(Any, value))

{gaard_core-0.2.4 → gaard_core-0.2.7}/src/gaard_core/conversation_context/mock_classifier.py

@@ -73,6 +73,7 @@ class MockConversationContextClassifier:
                 confidence=1.0,
                 standalone_question=request.question,
                 reason="No previous turns are available.",
+                source="mock",
             )
 
         question = request.question.strip()
@@ -85,6 +86,7 @@ class MockConversationContextClassifier:
                 confidence=0.8,
                 standalone_question=standalone,
                 reason="The question appears to continue the previous data question.",
+                source="mock",
             )
 
         if normalized in AMBIGUOUS_TERMS or re.fullmatch(
@@ -95,6 +97,7 @@ class MockConversationContextClassifier:
                 confidence=0.45,
                 standalone_question="",
                 reason="The question is too short to safely resolve from context.",
+                source="mock",
             )
 
         return ConversationContextClassification(
@@ -102,6 +105,7 @@ class MockConversationContextClassifier:
             confidence=0.9,
             standalone_question=question,
             reason="The question is self-contained.",
+            source="mock",
         )
 
 

gaard_core-0.2.7/src/gaard_core/prompt_compiler/conversation_context_prompt.py

@@ -0,0 +1,121 @@
+from typing import Any
+
+from gaard_core.json_utils import json_dumps
+from gaard_core.prompt_compiler.models import CompiledPrompt
+from gaard_core.query_pipeline.models import ConversationContextDecision, QueryRequest
+
+
+class ConversationContextPromptCompiler:
+    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,
+            },
+        }
+
+        return CompiledPrompt(
+            system_prompt=self._build_system_prompt(),
+            user_prompt=self._build_user_prompt(payload),
+            metadata={
+                "allowed_decisions": [item.value for item in ConversationContextDecision],
+                "decision_task": "logical_continuation_yes_no",
+            },
+        )
+
+    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)
+        ]
+
+    def _build_system_prompt(self) -> str:
+        return """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"
+  }
+"""
+
+    def _build_user_prompt(self, payload: dict[str, Any]) -> str:
+        return f"""Decide whether turn t is a logical continuation of turns t-2 and t-1.
+
+Input JSON:
+{json_dumps(payload, ensure_ascii=False, indent=2)}
+
+Return one JSON object with:
+- is_continuation: boolean yes/no answer to the logical-continuation question
+- decision: one of {", ".join(item.value for item in ConversationContextDecision)}
+- 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
+"""

{gaard_core-0.2.4 → gaard_core-0.2.7}/src/gaard_core/query_pipeline/models.py

@@ -44,6 +44,8 @@ class ConversationContextClassification(BaseModel):
     standalone_question: str = ""
     reason: str = ""
     model_response: dict[str, Any] = Field(default_factory=dict)
+    prompt: dict[str, Any] = Field(default_factory=dict)
+    source: str = ""
 
 
 class QueryRequest(BaseModel):

{gaard_core-0.2.4 → gaard_core-0.2.7}/src/gaard_core.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gaard-core
-Version: 0.2.4
+Version: 0.2.7
 Summary: Core GAARD query pipeline, prompt compiler, policies and SQL validation
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.4
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.7
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: sqlglot>=25.0.0
 Provides-Extra: dev

{gaard_core-0.2.4 → gaard_core-0.2.7}/src/gaard_core.egg-info/requires.txt

@@ -1,4 +1,4 @@
-gaard-plugin-api<0.3.0,>=0.2.4
+gaard-plugin-api<0.3.0,>=0.2.7
 pydantic>=2.7.0
 sqlglot>=25.0.0
 

{gaard_core-0.2.4 → gaard_core-0.2.7}/tests/test_conversation_context_classifier.py

@@ -1,8 +1,10 @@
 from gaard_core.conversation_context.llm_classifier import (
+    LlmConversationContextClassifier,
     parse_conversation_context_classification,
 )
 from gaard_core.conversation_context.mock_classifier import MockConversationContextClassifier
 from gaard_core.query_pipeline.models import ConversationContextDecision, QueryRequest
+from gaard_llm.providers.models import ChatCompletionResponse
 
 
 def test_parse_conversation_context_classification_handles_aliases_and_invalid_values() -> None:
@@ -17,6 +19,59 @@ def test_parse_conversation_context_classification_handles_aliases_and_invalid_v
         parse_conversation_context_classification('{"decision":"surprising"}').decision
         == ConversationContextDecision.AMBIGUOUS
     )
+    assert (
+        parse_conversation_context_classification('{"is_continuation":false}').decision
+        == ConversationContextDecision.NEW_TOPIC
+    )
+    assert (
+        parse_conversation_context_classification('{"is_continuation":true}').decision
+        == ConversationContextDecision.FOLLOW_UP
+    )
+
+
+def test_llm_conversation_context_classifier_exposes_prompt_and_standalone_follow_up() -> None:
+    class FakeClient:
+        def __init__(self) -> None:
+            self.request = None
+
+        def create_chat_completion(self, request):
+            self.request = request
+            return ChatCompletionResponse(
+                content=(
+                    '{"is_continuation":true,"decision":"follow_up",'
+                    '"current_question_is_standalone":true,"confidence":0.91,'
+                    '"standalone_question":"","reason":"Same metric, new period."}'
+                )
+            )
+
+    client = FakeClient()
+    classifier = LlmConversationContextClassifier(
+        client=client,
+        model="test-model",
+    )
+
+    classification = classifier.classify(
+        QueryRequest(question="ilu pacjentów przyjęto w tym tygodniu"),
+        {
+            "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 classification.decision == ConversationContextDecision.FOLLOW_UP
+    assert classification.standalone_question == "ilu pacjentów przyjęto w tym tygodniu"
+    assert classification.source == "llm"
+    assert "turn_t_minus_1" in classification.prompt["user_prompt"]
+    assert "logical continuation" in classification.prompt["system_prompt"]
 
 
 def test_mock_conversation_context_classifier_rewrites_simple_follow_up() -> None:

gaard_core-0.2.4/src/gaard_core/prompt_compiler/conversation_context_prompt.py

@@ -1,68 +0,0 @@
-from typing import Any
-
-from gaard_core.json_utils import json_dumps
-from gaard_core.prompt_compiler.models import CompiledPrompt
-from gaard_core.query_pipeline.models import ConversationContextDecision, QueryRequest
-
-
-class ConversationContextPromptCompiler:
-    def compile(
-        self,
-        request: QueryRequest,
-        conversation_context: dict[str, Any],
-    ) -> CompiledPrompt:
-        payload = {
-            "question": request.question,
-            "datasource_id": request.datasource_id,
-            "datasource_ids": request.datasource_ids,
-            "conversation_context": conversation_context,
-        }
-
-        return CompiledPrompt(
-            system_prompt=self._build_system_prompt(),
-            user_prompt=self._build_user_prompt(payload),
-            metadata={
-                "allowed_decisions": [item.value for item in ConversationContextDecision],
-            },
-        )
-
-    def _build_system_prompt(self) -> str:
-        return """You are GAARD Conversation Context Classification.
-
-Your task is to decide whether a user's new data question starts a new topic, continues the current conversation, or is too ambiguous to safely continue.
-
-Allowed decisions:
-- new_topic: the question stands on its own or changes topic.
-- follow_up: the question clearly depends on previous turns and can be rewritten as a standalone data question.
-- ambiguous: the question appears to depend on prior context but cannot be rewritten safely.
-
-Decision rules:
-1. Use follow_up only when the current question can be resolved from the supplied compact conversation context.
-2. Use new_topic when the question is already self-contained.
-3. Use ambiguous instead of guessing when key entities, metrics, filters, date ranges, or datasource scope cannot be inferred.
-4. 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.
-5. 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.
-6. Use ambiguous when the user asks for one specific record but the context indicates multiple records and no selector is provided.
-7. 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:
-  {"decision":"new_topic","confidence":0.0,"standalone_question":"rewritten question or empty","reason":"short reason"}
-"""
-
-    def _build_user_prompt(self, payload: dict[str, Any]) -> str:
-        return f"""Classify this new user question against the compact conversation context.
-
-Input JSON:
-{json_dumps(payload, ensure_ascii=False, indent=2)}
-
-Return one JSON object with:
-- decision: one of {", ".join(item.value for item in ConversationContextDecision)}
-- confidence: number from 0 to 1
-- standalone_question: required for follow_up, otherwise empty
-- reason: short explanation
-"""