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

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gaard-core
-Version: 0.2.2
+Version: 0.2.4
 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.2
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.4
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: sqlglot>=25.0.0
 Provides-Extra: dev

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

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

gaard_core-0.2.4/src/gaard_core/conversation_context/__init__.py

@@ -0,0 +1,11 @@
+from gaard_core.conversation_context.llm_classifier import (
+    LlmConversationContextClassifier,
+    parse_conversation_context_classification,
+)
+from gaard_core.conversation_context.mock_classifier import MockConversationContextClassifier
+
+__all__ = [
+    "LlmConversationContextClassifier",
+    "MockConversationContextClassifier",
+    "parse_conversation_context_classification",
+]

gaard_core-0.2.4/src/gaard_core/conversation_context/llm_classifier.py

@@ -0,0 +1,124 @@
+import json
+from typing import Any, Protocol, cast
+
+from gaard_core.llm_output import remove_thinking_blocks
+from gaard_core.prompt_compiler.conversation_context_prompt import (
+    ConversationContextPromptCompiler,
+)
+from gaard_core.prompt_compiler.models import CompiledPrompt
+from gaard_core.query_pipeline.models import (
+    ConversationContextClassification,
+    ConversationContextDecision,
+    QueryRequest,
+)
+from gaard_llm.openai_compatible.client import OpenAICompatibleClient
+from gaard_llm.providers.models import ChatCompletionRequest, ChatMessage
+
+
+class ConversationContextPromptCompilerProtocol(Protocol):
+    def compile(
+        self,
+        request: QueryRequest,
+        conversation_context: dict[str, Any],
+    ) -> CompiledPrompt:
+        pass
+
+
+class LlmConversationContextClassifier:
+    def __init__(
+        self,
+        client: OpenAICompatibleClient,
+        model: str,
+        extra_body: dict[str, Any] | None = None,
+        prompt_compiler: ConversationContextPromptCompilerProtocol | None = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.extra_body = extra_body or {}
+        self.prompt_compiler = prompt_compiler or ConversationContextPromptCompiler()
+
+    def classify(
+        self,
+        request: QueryRequest,
+        conversation_context: dict[str, Any],
+    ) -> ConversationContextClassification:
+        compiled_prompt = self.prompt_compiler.compile(
+            request=request,
+            conversation_context=conversation_context,
+        )
+        response = self.client.create_chat_completion(
+            ChatCompletionRequest(
+                model=self.model,
+                temperature=0.0,
+                extra_body=self.extra_body,
+                messages=[
+                    ChatMessage(role="system", content=compiled_prompt.system_prompt),
+                    ChatMessage(role="user", content=compiled_prompt.user_prompt),
+                ],
+            )
+        )
+
+        return parse_conversation_context_classification(response.content)
+
+
+def parse_conversation_context_classification(
+    value: str,
+) -> ConversationContextClassification:
+    cleaned = remove_thinking_blocks(value).strip()
+    if cleaned.startswith("```json"):
+        cleaned = cleaned.removeprefix("```json").strip()
+    if cleaned.startswith("```"):
+        cleaned = cleaned.removeprefix("```").strip()
+    if cleaned.endswith("```"):
+        cleaned = cleaned.removesuffix("```").strip()
+
+    try:
+        payload = json.loads(cleaned)
+    except json.JSONDecodeError:
+        payload = {"decision": cleaned}
+
+    if not isinstance(payload, dict):
+        return ConversationContextClassification()
+
+    return ConversationContextClassification(
+        decision=parse_conversation_context_decision(payload.get("decision")),
+        confidence=parse_confidence(payload.get("confidence")),
+        standalone_question=str(payload.get("standalone_question") or "").strip(),
+        reason=str(payload.get("reason") or ""),
+        model_response=payload,
+    )
+
+
+def parse_conversation_context_decision(value: object) -> ConversationContextDecision:
+    if not isinstance(value, str):
+        return ConversationContextDecision.AMBIGUOUS
+
+    normalized = value.strip().lower().replace(" ", "_").replace("-", "_")
+    aliases = {
+        "new": ConversationContextDecision.NEW_TOPIC,
+        "new_question": ConversationContextDecision.NEW_TOPIC,
+        "newtopic": ConversationContextDecision.NEW_TOPIC,
+        "continue": ConversationContextDecision.FOLLOW_UP,
+        "continuation": ConversationContextDecision.FOLLOW_UP,
+        "followup": ConversationContextDecision.FOLLOW_UP,
+        "follow_up_question": ConversationContextDecision.FOLLOW_UP,
+        "unclear": ConversationContextDecision.AMBIGUOUS,
+        "needs_clarification": ConversationContextDecision.AMBIGUOUS,
+    }
+    if normalized in aliases:
+        return aliases[normalized]
+
+    for item in ConversationContextDecision:
+        if normalized == item.value:
+            return item
+
+    return ConversationContextDecision.AMBIGUOUS
+
+
+def parse_confidence(value: object) -> float:
+    try:
+        confidence = float(cast(Any, value))
+    except (TypeError, ValueError):
+        return 0.0
+
+    return max(0.0, min(1.0, confidence))

gaard_core-0.2.4/src/gaard_core/conversation_context/mock_classifier.py

@@ -0,0 +1,142 @@
+import re
+from typing import Any
+
+from gaard_core.query_pipeline.models import (
+    ConversationContextClassification,
+    ConversationContextDecision,
+    QueryRequest,
+)
+
+
+FOLLOW_UP_PREFIXES = (
+    "a ",
+    "and ",
+    "oraz ",
+    "to samo",
+    "tak samo",
+    "dla ",
+    "w ",
+    "za ",
+    "porównaj",
+    "porownaj",
+    "compare",
+    "same",
+)
+
+AMBIGUOUS_TERMS = (
+    "to",
+    "tego",
+    "tamto",
+    "tamte",
+    "them",
+    "it",
+    "that",
+)
+
+RESULT_REFERENCE_TERMS = (
+    "ich",
+    "nich",
+    "tych",
+    "te",
+    "tej",
+    "tego",
+    "their",
+    "them",
+    "these",
+    "those",
+)
+
+PROJECTION_COMMAND_PREFIXES = (
+    "podaj ",
+    "pokaż ",
+    "pokaz ",
+    "wypisz ",
+    "wyświetl ",
+    "wyswietl ",
+    "show ",
+    "list ",
+    "give ",
+    "return ",
+)
+
+
+class MockConversationContextClassifier:
+    def classify(
+        self,
+        request: QueryRequest,
+        conversation_context: dict[str, Any],
+    ) -> ConversationContextClassification:
+        turns = conversation_context.get("turns") or []
+        if not turns:
+            return ConversationContextClassification(
+                decision=ConversationContextDecision.NEW_TOPIC,
+                confidence=1.0,
+                standalone_question=request.question,
+                reason="No previous turns are available.",
+            )
+
+        question = request.question.strip()
+        normalized = question.lower()
+        if looks_like_follow_up(normalized) or looks_like_projection_follow_up(normalized):
+            previous = latest_question(turns)
+            standalone = combine_follow_up(previous, question)
+            return ConversationContextClassification(
+                decision=ConversationContextDecision.FOLLOW_UP,
+                confidence=0.8,
+                standalone_question=standalone,
+                reason="The question appears to continue the previous data question.",
+            )
+
+        if normalized in AMBIGUOUS_TERMS or re.fullmatch(
+            r"(a )?(co|what|why|dlaczego)\??", normalized
+        ):
+            return ConversationContextClassification(
+                decision=ConversationContextDecision.AMBIGUOUS,
+                confidence=0.45,
+                standalone_question="",
+                reason="The question is too short to safely resolve from context.",
+            )
+
+        return ConversationContextClassification(
+            decision=ConversationContextDecision.NEW_TOPIC,
+            confidence=0.9,
+            standalone_question=question,
+            reason="The question is self-contained.",
+        )
+
+
+def looks_like_follow_up(normalized_question: str) -> bool:
+    return any(normalized_question.startswith(prefix) for prefix in FOLLOW_UP_PREFIXES)
+
+
+def looks_like_projection_follow_up(normalized_question: str) -> bool:
+    if not any(normalized_question.startswith(prefix) for prefix in PROJECTION_COMMAND_PREFIXES):
+        return False
+
+    tokens = set(re.findall(r"[\wąćęłńóśźż]+", normalized_question))
+    return bool(tokens & set(RESULT_REFERENCE_TERMS))
+
+
+def latest_question(turns: list[Any]) -> str:
+    for turn in reversed(turns):
+        if not isinstance(turn, dict):
+            continue
+        question = str(
+            turn.get("standalone_question")
+            or turn.get("question")
+            or turn.get("original_question")
+            or ""
+        ).strip()
+        if question:
+            return question
+
+    return ""
+
+
+def combine_follow_up(previous_question: str, question: str) -> str:
+    previous = previous_question.strip().rstrip(".?")
+    current = question.strip().rstrip(".?")
+    if not previous:
+        return question.strip()
+
+    return f"{previous}; kontynuacja: {current}?"

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

@@ -0,0 +1,68 @@
+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
+"""

{gaard_core-0.2.2 → gaard_core-0.2.4}/src/gaard_core/prompt_compiler/sql_generation_prompt.py

@@ -40,9 +40,7 @@ class SqlGenerationPromptCompiler:
             return request.formatted_schema
 
         if request.database_schema is None:
-            raise ConfigurationError(
-                "Either database_schema or formatted_schema must be provided."
-            )
+            raise ConfigurationError("Either database_schema or formatted_schema must be provided.")
 
         return self.schema_formatter.format(request.database_schema)
 
@@ -85,11 +83,14 @@ Query construction rules:
 11. When the query uses table aliases, use those aliases consistently and do not mix aliased and unaliased table references.
 12. Do not use unqualified column names in joins or multi-table queries.
 13. If the question is ambiguous, choose the most likely interpretation based on the schema, column names, descriptions and data rules.
+14. Do not use bind parameters, placeholders, variables, or prepared-statement markers such as :name, ?, $1, @name, or %(name)s.
+15. When dates or dynamic ranges are needed, express them directly with {dialect} SQL functions or literal values so the SQL is executable without any external parameter binding.
 
 Output contract:
 - Return exactly one SQL SELECT statement.
 - The first non-whitespace token must be SELECT or WITH.
 - The final output must be executable SQL only.
+- The final SQL must be self-contained and executable as-is.
 """
 
     def _build_user_prompt(self, schema: str, question: str) -> str:

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

@@ -26,12 +26,34 @@ class QueryIntentClassification(BaseModel):
     model_response: dict[str, Any] = Field(default_factory=dict)
 
 
+class ContextMode(StrEnum):
+    AUTO = "auto"
+    NEW = "new"
+    OFF = "off"
+
+
+class ConversationContextDecision(StrEnum):
+    NEW_TOPIC = "new_topic"
+    FOLLOW_UP = "follow_up"
+    AMBIGUOUS = "ambiguous"
+
+
+class ConversationContextClassification(BaseModel):
+    decision: ConversationContextDecision = ConversationContextDecision.NEW_TOPIC
+    confidence: float = 0.0
+    standalone_question: str = ""
+    reason: str = ""
+    model_response: dict[str, Any] = Field(default_factory=dict)
+
+
 class QueryRequest(BaseModel):
     question: str = Field(min_length=1)
     datasource_id: str = "default"
     datasource_ids: list[str] = Field(default_factory=list)
     user_id: str = "local-admin"
     interpret: bool = True
+    conversation_id: str | None = None
+    context_mode: ContextMode = ContextMode.AUTO
 
 
 class GeneratedSql(BaseModel):

{gaard_core-0.2.2 → gaard_core-0.2.4}/src/gaard_core/sql_validator/select_only.py

@@ -35,3 +35,12 @@ class SelectOnlySqlValidator:
         for node in statement.walk():
             if isinstance(node, forbidden_expressions):
                 raise SqlValidationError(f"DDL and DML statements are not allowed. {sql}")
+            if isinstance(node, (exp.Placeholder, exp.Parameter)):
+                raise SqlValidationError(
+                    f"SQL bind parameters are not allowed. SQL: {sql}",
+                    sql=sql,
+                    metadata={
+                        "primary_error_category": "sql.validation.bind_parameter",
+                        "error_categories": ["sql.validation.bind_parameter"],
+                    },
+                )

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gaard-core
-Version: 0.2.2
+Version: 0.2.4
 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.2
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.4
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: sqlglot>=25.0.0
 Provides-Extra: dev

{gaard_core-0.2.2 → gaard_core-0.2.4}/src/gaard_core.egg-info/SOURCES.txt

@@ -10,9 +10,13 @@ src/gaard_core.egg-info/SOURCES.txt
 src/gaard_core.egg-info/dependency_links.txt
 src/gaard_core.egg-info/requires.txt
 src/gaard_core.egg-info/top_level.txt
+src/gaard_core/conversation_context/__init__.py
+src/gaard_core/conversation_context/llm_classifier.py
+src/gaard_core/conversation_context/mock_classifier.py
 src/gaard_core/execution/__init__.py
 src/gaard_core/execution/mock_executor.py
 src/gaard_core/prompt_compiler/__init__.py
+src/gaard_core/prompt_compiler/conversation_context_prompt.py
 src/gaard_core/prompt_compiler/intent_classification_prompt.py
 src/gaard_core/prompt_compiler/models.py
 src/gaard_core/prompt_compiler/result_classification_prompt.py
@@ -39,6 +43,7 @@ src/gaard_core/schema/context.py
 src/gaard_core/schema/models.py
 src/gaard_core/sql_validator/__init__.py
 src/gaard_core/sql_validator/select_only.py
+tests/test_conversation_context_classifier.py
 tests/test_json_utils.py
 tests/test_llm_output.py
 tests/test_llm_query_intent_classifier.py

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

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

gaard_core-0.2.4/tests/test_conversation_context_classifier.py

@@ -0,0 +1,70 @@
+from gaard_core.conversation_context.llm_classifier import (
+    parse_conversation_context_classification,
+)
+from gaard_core.conversation_context.mock_classifier import MockConversationContextClassifier
+from gaard_core.query_pipeline.models import ConversationContextDecision, QueryRequest
+
+
+def test_parse_conversation_context_classification_handles_aliases_and_invalid_values() -> None:
+    assert (
+        parse_conversation_context_classification(
+            '<think>hidden</think>{"decision":"followup","confidence":0.8,'
+            '"standalone_question":"How many patients in May?"}'
+        ).decision
+        == ConversationContextDecision.FOLLOW_UP
+    )
+    assert (
+        parse_conversation_context_classification('{"decision":"surprising"}').decision
+        == ConversationContextDecision.AMBIGUOUS
+    )
+
+
+def test_mock_conversation_context_classifier_rewrites_simple_follow_up() -> None:
+    classifier = MockConversationContextClassifier()
+
+    classification = classifier.classify(
+        QueryRequest(question="a w maju?"),
+        {
+            "turns": [
+                {
+                    "question": "Jaka była sprzedaż w czerwcu według regionów?",
+                    "standalone_question": "Jaka była sprzedaż w czerwcu według regionów?",
+                }
+            ]
+        },
+    )
+
+    assert classification.decision == ConversationContextDecision.FOLLOW_UP
+    assert "czerwcu" in classification.standalone_question
+    assert "maju" in classification.standalone_question
+
+
+def test_mock_conversation_context_classifier_rewrites_projection_follow_up() -> None:
+    classifier = MockConversationContextClassifier()
+
+    classification = classifier.classify(
+        QueryRequest(question="show their names"),
+        {
+            "turns": [
+                {
+                    "question": "How many active patients are there?",
+                    "standalone_question": "How many active patients are there?",
+                }
+            ]
+        },
+    )
+
+    assert classification.decision == ConversationContextDecision.FOLLOW_UP
+    assert "active patients" in classification.standalone_question
+    assert "show their names" in classification.standalone_question
+
+
+def test_mock_conversation_context_classifier_marks_short_reference_ambiguous() -> None:
+    classifier = MockConversationContextClassifier()
+
+    classification = classifier.classify(
+        QueryRequest(question="to"),
+        {"turns": [{"question": "How many active patients are there?"}]},
+    )
+
+    assert classification.decision == ConversationContextDecision.AMBIGUOUS

{gaard_core-0.2.2 → gaard_core-0.2.4}/tests/test_sql_generation_prompt_compiler.py

@@ -31,6 +31,8 @@ def test_sql_generation_prompt_compiler_builds_prompt_with_rules_schema_and_ques
     assert "every table must have a short, stable alias" in compiled.system_prompt
     assert "every column reference must be qualified" in compiled.system_prompt
     assert "Do not use unqualified column names in joins" in compiled.system_prompt
+    assert "Do not use bind parameters" in compiled.system_prompt
+    assert "executable without any external parameter binding" in compiled.system_prompt
 
     assert "Table: patients" in compiled.user_prompt
     assert "- status: TEXT (not null)" in compiled.user_prompt

{gaard_core-0.2.2 → gaard_core-0.2.4}/tests/test_sql_validator.py

@@ -40,3 +40,12 @@ def test_validator_rejects_multiple_statements() -> None:
 
     with pytest.raises(SqlValidationError):
         validator.validate("SELECT * FROM patients; SELECT * FROM users")
+
+
+def test_validator_rejects_bind_parameters() -> None:
+    validator = SelectOnlySqlValidator(dialect="mysql")
+
+    with pytest.raises(SqlValidationError) as exc_info:
+        validator.validate("SELECT * FROM `lead` WHERE source_id = :source_id")
+
+    assert exc_info.value.metadata["primary_error_category"] == ("sql.validation.bind_parameter")