gaard-core 0.1.0__py3-none-any.whl

gaard_core/prompt_compiler/investigation_readiness_prompt.py

@@ -0,0 +1,84 @@
+from gaard_core.investigation.models import InvestigationContext, InvestigationRoute
+from gaard_core.json_utils import json_dumps
+from gaard_core.prompt_compiler.models import CompiledPrompt
+
+
+class InvestigationReadinessPromptCompiler:
+    def compile(self, context: InvestigationContext) -> CompiledPrompt:
+        payload = {
+            "question": context.question,
+            "datasource_id": context.datasource_id,
+            "user_id": context.user_id,
+            "schema": context.formatted_schema,
+            "business_logic": context.business_logic,
+        }
+
+        return CompiledPrompt(
+            system_prompt=self._build_system_prompt(),
+            user_prompt=self._build_user_prompt(payload),
+            metadata={
+                "allowed_routes": [item.value for item in InvestigationRoute],
+            },
+        )
+
+    def _build_system_prompt(self) -> str:
+        return """You are GAARD Investigation Readiness.
+
+Your task is to decide whether GAARD already knows enough to create a correct SQL query for the user's question.
+
+Assume nothing. Verify continuously.
+
+Use only:
+- the user's question,
+- the active datasource schema,
+- the approved or previously saved business logic supplied in the payload.
+
+You do not generate SQL.
+You do not answer the user.
+You decide only whether normal SQL generation may start safely.
+
+Return ready_for_sql=true only when all information needed for correct SQL is explicit in the question, schema, and business logic:
+- requested business entity or metric,
+- relevant tables, views and columns,
+- required filters and dictionary/status values,
+- required joins or relationships,
+- requested output shape such as count, list, detail, or aggregation.
+
+Return ready_for_sql=false when any material element is missing, ambiguous, inferred only from the model, or would require checking data values before SQL can be trusted. In that case route must be analysis.
+
+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:
+  {"ready_for_sql":false,"route":"analysis","confidence":0.0,"reason":"short reason","missing_information":[],"required_analysis":[],"required_analysis_tasks":[],"assumptions":[]}
+
+Required analysis task shape:
+{"missing_information":"what is missing","required_analysis":"specific read-only data question for SQL analysis","category":"dictionary_value","expected_output":"what kind of result would resolve this"}
+
+Allowed categories:
+- dictionary_value
+- relationship_logic
+- filter_logic
+- aggregation_logic
+- entity_mapping
+- unknown
+"""
+
+    def _build_user_prompt(self, payload: dict[str, str]) -> str:
+        return f"""Assess whether normal SQL generation can start.
+
+Input JSON:
+{json_dumps(payload, ensure_ascii=False, indent=2)}
+
+Return one JSON object with:
+- ready_for_sql: boolean
+- route: sql or analysis
+- confidence: number from 0 to 1
+- reason: short explanation
+- missing_information: list of missing or ambiguous items
+- required_analysis: list of checks that Analysis mode should perform when ready_for_sql=false
+- required_analysis_tasks: list of structured SQL-analysis tasks with missing_information, required_analysis, category, expected_output
+- assumptions: list of any assumptions that would affect SQL correctness
+"""

gaard_core/prompt_compiler/models.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from gaard_core.schema.models import DatabaseSchema
+
+
+class SqlGenerationPromptRequest(BaseModel):
+    question: str = Field(min_length=1)
+    database_schema: DatabaseSchema | None = None
+    formatted_schema: str | None = None
+    dialect: str = "sqlite"
+    max_rows: int = 100
+
+
+class CompiledPrompt(BaseModel):
+    system_prompt: str
+    user_prompt: str
+    metadata: dict[str, Any] = Field(default_factory=dict)

gaard_core/prompt_compiler/result_classification_prompt.py

@@ -0,0 +1,62 @@
+from gaard_core.json_utils import json_dumps
+from gaard_core.prompt_compiler.models import CompiledPrompt
+from gaard_core.query_pipeline.models import OutputClassification, QueryRequest
+
+
+class ResultClassificationPromptCompiler:
+    def compile(
+        self,
+        request: QueryRequest,
+        answer: str,
+    ) -> CompiledPrompt:
+        payload = {
+            "question": request.question,
+            "answer": answer,
+        }
+
+        return CompiledPrompt(
+            system_prompt=self._build_system_prompt(),
+            user_prompt=self._build_user_prompt(payload),
+            metadata={
+                "allowed_classifications": [
+                    item.value for item in OutputClassification
+                ],
+            },
+        )
+
+    def _build_system_prompt(self) -> str:
+        return """You are GAARD Output Classification.
+
+Your task is to classify the user-facing interpreted answer into exactly one output data class.
+
+Allowed classes:
+- personal_data: the answer is about personal data, people, identities, audit events concerning personal data, or aggregates describing personal data access.
+- sensitive_data: the answer is about sensitive or special-category data such as health, credentials, secrets, financial risk, legal status, biometric data, or similarly high-risk information.
+- technical_data: the answer is about system configuration, schemas, logs, query mechanics, infrastructure, or operational technical metadata.
+- neutral_data: the answer is about non-personal, non-sensitive business or aggregate information.
+- unknown: the answer cannot be classified reliably.
+
+Priority rules:
+1. Choose sensitive_data over personal_data if both apply.
+2. Choose personal_data over technical_data if the answer concerns audit or technical records about personal data.
+3. Choose unknown instead of guessing when the answer lacks enough context.
+
+Rules:
+- Classify only the interpreted answer and the user's question.
+- Do not classify raw database rows.
+- Return only one allowed class value.
+- Do not include explanations.
+- Do not include markdown.
+- Do not include reasoning.
+- Do not include <think> blocks.
+"""
+
+    def _build_user_prompt(self, payload: dict[str, str]) -> str:
+        return f"""Classify this interpreted result.
+
+Input JSON:
+{json_dumps(payload, ensure_ascii=False, indent=2)}
+
+Return exactly one of:
+{", ".join(item.value for item in OutputClassification)}
+"""

gaard_core/prompt_compiler/result_interpretation_prompt.py

@@ -0,0 +1,73 @@
+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 QueryRequest, QueryResult
+
+
+class ResultInterpretationPromptCompiler:
+    def compile(
+        self,
+        request: QueryRequest,
+        sql: str,
+        result: QueryResult,
+    ) -> CompiledPrompt:
+        system_prompt = self._build_system_prompt()
+        user_prompt = self._build_user_prompt(
+            question=request.question,
+            sql=sql,
+            rows=result.rows,
+            columns=result.columns,
+        )
+
+        return CompiledPrompt(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            metadata={
+                "rows_count": len(result.rows),
+                "columns_count": len(result.columns),
+            },
+        )
+
+    def _build_system_prompt(self) -> str:
+        return """You are GAARD Data Result Interpreter.
+
+Your task is to explain SQL query results to the user.
+
+Rules:
+- Answer in the same language as the user's question.
+- Pay attention to correct user's language grammar and plural forms.
+- Use only the data provided in the result.
+- Do not invent facts.
+- Be concise.
+- Prefer one short paragraph.
+- If the result is empty, say that the query returned no rows.
+- If the result contains aggregated values, explain the value directly.
+- Do not mention that you are an AI model.
+- Do not include markdown tables unless explicitly needed.
+- Do not include reasoning.
+- Do not include <think> blocks.
+- Return only the final answer.
+"""
+
+    def _build_user_prompt(
+        self,
+        question: str,
+        sql: str,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+    ) -> str:
+        payload = {
+            "question": question,
+            "sql": sql,
+            "columns": columns,
+            "rows": rows,
+        }
+
+        return f"""Interpret the following SQL result for the user.
+
+Input JSON:
+{json_dumps(payload, ensure_ascii=False, indent=2)}
+
+Return only the final user-facing answer.
+"""

gaard_core/prompt_compiler/schema_formatter.py

@@ -0,0 +1,43 @@
+from gaard_core.schema.models import DatabaseSchema, TableInfo
+
+
+class SchemaPromptFormatter:
+    def format(self, schema: DatabaseSchema) -> str:
+        if not schema.tables:
+            return "No tables or views available."
+
+        sections: list[str] = []
+
+        for table in sorted(schema.tables, key=lambda item: item.name):
+            sections.append(self._format_table(table))
+
+        return "\n\n".join(sections)
+
+    def _format_table(self, table: TableInfo) -> str:
+        object_label = "View" if table.object_type == "view" else "Table"
+        lines: list[str] = [f"{object_label}: {table.name}", "Columns:"]
+
+        if not table.columns:
+            lines.append("- No columns available.")
+        else:
+            for column in table.columns:
+                modifiers: list[str] = []
+
+                if column.primary_key:
+                    modifiers.append("primary key")
+
+                if not column.nullable:
+                    modifiers.append("not null")
+
+                modifier_text = f" ({', '.join(modifiers)})" if modifiers else ""
+                lines.append(f"- {column.name}: {column.type}{modifier_text}")
+
+        if table.foreign_keys:
+            lines.append("Foreign keys:")
+
+            for foreign_key in table.foreign_keys:
+                constrained = ", ".join(foreign_key.constrained_columns)
+                referred = ", ".join(foreign_key.referred_columns)
+                lines.append(f"- {constrained} -> {foreign_key.referred_table}.{referred}")
+
+        return "\n".join(lines)

gaard_core/prompt_compiler/sql_generation_prompt.py

@@ -0,0 +1,105 @@
+from gaard_core.errors import ConfigurationError
+from gaard_core.prompt_compiler.models import CompiledPrompt, SqlGenerationPromptRequest
+from gaard_core.prompt_compiler.schema_formatter import SchemaPromptFormatter
+
+
+class SqlGenerationPromptCompiler:
+    def __init__(self, schema_formatter: SchemaPromptFormatter | None = None) -> None:
+        self.schema_formatter = schema_formatter or SchemaPromptFormatter()
+
+    def compile(self, request: SqlGenerationPromptRequest) -> CompiledPrompt:
+        formatted_schema = self._resolve_formatted_schema(request)
+
+        system_prompt = self._build_system_prompt(
+            dialect=request.dialect,
+            max_rows=request.max_rows,
+        )
+
+        user_prompt = self._build_user_prompt(
+            schema=formatted_schema,
+            question=request.question,
+        )
+
+        return CompiledPrompt(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            metadata={
+                "dialect": request.dialect,
+                "max_rows": request.max_rows,
+                "schema_source": "formatted_schema"
+                if request.formatted_schema is not None
+                else "database_schema",
+                "tables_count": len(request.database_schema.tables)
+                if request.database_schema is not None
+                else None,
+            },
+        )
+
+    def _resolve_formatted_schema(self, request: SqlGenerationPromptRequest) -> str:
+        if request.formatted_schema is not None:
+            return request.formatted_schema
+
+        if request.database_schema is None:
+            raise ConfigurationError(
+                "Either database_schema or formatted_schema must be provided."
+            )
+
+        return self.schema_formatter.format(request.database_schema)
+
+    def _build_system_prompt(self, dialect: str, max_rows: int) -> str:
+        return f"""You are an expert data analyst and SQL specialist.
+
+Your task is to generate exactly one valid SQL SELECT query based on:
+- the user's question,
+- the provided database schema,
+- the provided data rules and descriptions.
+
+You must generate SQL for the {dialect} dialect.
+
+Core rules:
+1. Generate only one SQL statement.
+2. Generate only a SELECT statement.
+3. Do not generate multiple statements.
+4. Do not generate INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, MERGE, REPLACE, GRANT or REVOKE.
+5. Use only tables, views and columns listed in the provided schema.
+6. Do not invent tables, views or columns.
+7. Return only raw SQL.
+8. Do not use markdown.
+9. Do not use code fences.
+10. Do not add comments.
+11. Do not add explanations.
+12. Do not include reasoning.
+13. Do not include <think> blocks.
+
+Query construction rules:
+1. If the user asks for a count, use COUNT with a clear alias.
+2. If the user asks for a breakdown, distribution, comparison by category, or values "by" some dimension, use one SELECT statement with GROUP BY or conditional aggregation.
+3. If the user asks for both a total and a breakdown, prefer one SELECT statement that returns grouped rows or conditional aggregate columns.
+4. Do not solve one user question by generating multiple separate SELECT statements.
+5. Prefer explicit column names over SELECT *.
+6. Add LIMIT {max_rows} when the query may return many rows.
+7. Do not add LIMIT to pure aggregate queries that return a single row, unless it is already useful for the dialect or safety.
+8. Use clear aliases for computed expressions.
+9. When the query uses more than one table, every table must have a short, stable alias.
+10. When the query uses more than one table, every column reference must be qualified with the correct table alias in SELECT, JOIN, WHERE, GROUP BY, HAVING and ORDER BY.
+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.
+
+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.
+"""
+
+    def _build_user_prompt(self, schema: str, question: str) -> str:
+        return f"""Database schema:
+{schema}
+
+User question:
+{question}
+
+Generate exactly one SQL SELECT statement for this question.
+If the answer requires multiple values, categories or groups, return them using one query.
+Return SQL only.
+"""

gaard_core/query_intent/__init__.py

@@ -0,0 +1 @@
+

gaard_core/query_intent/llm_classifier.py

@@ -0,0 +1,112 @@
+import json
+from typing import Any, Protocol
+
+from gaard_core.llm_output import remove_thinking_blocks
+from gaard_core.prompt_compiler.intent_classification_prompt import (
+    IntentClassificationPromptCompiler,
+)
+from gaard_core.prompt_compiler.models import CompiledPrompt
+from gaard_core.query_pipeline.models import (
+    QueryIntentClassification,
+    QueryIntentDecision,
+    QueryRequest,
+)
+from gaard_llm.openai_compatible.client import OpenAICompatibleClient
+from gaard_llm.providers.models import ChatCompletionRequest, ChatMessage
+
+
+class IntentPromptCompiler(Protocol):
+    def compile(self, request: QueryRequest) -> CompiledPrompt:
+        pass
+
+
+class LlmQueryIntentClassifier:
+    def __init__(
+        self,
+        client: OpenAICompatibleClient,
+        model: str,
+        extra_body: dict[str, Any] | None = None,
+        prompt_compiler: IntentPromptCompiler | None = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.extra_body = extra_body or {}
+        self.prompt_compiler = prompt_compiler or IntentClassificationPromptCompiler()
+
+    def classify(self, request: QueryRequest) -> QueryIntentClassification:
+        compiled_prompt = self.prompt_compiler.compile(request=request)
+
+        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_query_intent_classification(response.content)
+
+
+def parse_query_intent_classification(value: str) -> QueryIntentClassification:
+    cleaned = remove_thinking_blocks(value).strip()
+
+    try:
+        payload = json.loads(cleaned)
+    except json.JSONDecodeError:
+        payload = {"decision": cleaned}
+
+    if not isinstance(payload, dict):
+        return QueryIntentClassification()
+
+    return QueryIntentClassification(
+        decision=parse_query_intent_decision(payload.get("decision")),
+        confidence=parse_confidence(payload.get("confidence")),
+        reason=str(payload.get("reason") or ""),
+        model_response=payload,
+    )
+
+
+def parse_query_intent_decision(value: object) -> QueryIntentDecision:
+    if not isinstance(value, str):
+        return QueryIntentDecision.AMBIGUOUS
+
+    normalized = value.strip().lower().replace(" ", "_").replace("-", "_")
+
+    aliases = {
+        "read_only": QueryIntentDecision.READ_ONLY_DATA_QUESTION,
+        "readonly": QueryIntentDecision.READ_ONLY_DATA_QUESTION,
+        "select": QueryIntentDecision.READ_ONLY_DATA_QUESTION,
+        "write": QueryIntentDecision.WRITE_OR_MUTATION_REQUEST,
+        "mutation": QueryIntentDecision.WRITE_OR_MUTATION_REQUEST,
+        "unsafe": QueryIntentDecision.WRITE_OR_MUTATION_REQUEST,
+        "non_data": QueryIntentDecision.NON_DATA_REQUEST,
+        "not_data": QueryIntentDecision.NON_DATA_REQUEST,
+    }
+
+    if normalized in aliases:
+        return aliases[normalized]
+
+    for item in QueryIntentDecision:
+        if normalized == item.value:
+            return item
+
+    return QueryIntentDecision.AMBIGUOUS
+
+
+def parse_confidence(value: object) -> float:
+    try:
+        confidence = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+    return max(0.0, min(1.0, confidence))

gaard_core/query_intent/mock_classifier.py

@@ -0,0 +1,14 @@
+from gaard_core.query_pipeline.models import (
+    QueryIntentClassification,
+    QueryIntentDecision,
+    QueryRequest,
+)
+
+
+class MockQueryIntentClassifier:
+    def classify(self, request: QueryRequest) -> QueryIntentClassification:
+        return QueryIntentClassification(
+            decision=QueryIntentDecision.READ_ONLY_DATA_QUESTION,
+            confidence=1.0,
+            reason="Mock intent classifier allows the request.",
+        )

gaard_core/query_pipeline/llm_sql_generator.py

@@ -0,0 +1,85 @@
+from typing import Any, Protocol
+
+from gaard_core.prompt_compiler.models import CompiledPrompt, SqlGenerationPromptRequest
+from gaard_core.prompt_compiler.sql_generation_prompt import SqlGenerationPromptCompiler
+from gaard_core.llm_output import remove_thinking_blocks
+from gaard_core.query_pipeline.models import GeneratedSql, QueryRequest
+from gaard_llm.openai_compatible.client import OpenAICompatibleClient
+from gaard_llm.providers.models import ChatCompletionRequest, ChatMessage
+
+
+class SqlPromptCompiler(Protocol):
+    def compile(self, request: SqlGenerationPromptRequest) -> CompiledPrompt:
+        pass
+
+
+class LlmSqlGenerator:
+    def __init__(
+        self,
+        client: OpenAICompatibleClient,
+        model: str,
+        formatted_schema: str,
+        dialect: str = "sqlite",
+        max_rows: int = 100,
+        extra_body: dict[str, Any] | None = None,
+        prompt_compiler: SqlPromptCompiler | None = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.formatted_schema = formatted_schema
+        self.dialect = dialect
+        self.max_rows = max_rows
+        self.extra_body = extra_body or {}
+        self.prompt_compiler = prompt_compiler or SqlGenerationPromptCompiler()
+
+    def generate(self, request: QueryRequest) -> GeneratedSql:
+        compiled_prompt = self.prompt_compiler.compile(
+            SqlGenerationPromptRequest(
+                question=request.question,
+                formatted_schema=self.formatted_schema,
+                dialect=self.dialect,
+                max_rows=self.max_rows,
+            )
+        )
+
+        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,
+                    ),
+                ],
+            )
+        )
+
+        sql = self._clean_sql(response.content)
+
+        return GeneratedSql(
+            sql=sql,
+            confidence=0.0,
+            assumptions=[
+                "SQL generated by OpenAI-compatible LLM provider.",
+            ],
+        )
+
+    def _clean_sql(self, value: str) -> str:
+        cleaned = remove_thinking_blocks(value)
+
+        if cleaned.startswith("```sql"):
+            cleaned = cleaned.removeprefix("```sql").strip()
+
+        if cleaned.startswith("```"):
+            cleaned = cleaned.removeprefix("```").strip()
+
+        if cleaned.endswith("```"):
+            cleaned = cleaned.removesuffix("```").strip()
+
+        return cleaned

gaard_core/query_pipeline/mock_sql_generator.py

@@ -0,0 +1,33 @@
+from gaard_core.query_pipeline.models import GeneratedSql, QueryRequest
+
+
+class MockSqlGenerator:
+    def generate(self, request: QueryRequest) -> GeneratedSql:
+        question = request.question.lower()
+
+        if "aktywn" in question or "active" in question:
+            return GeneratedSql(
+                sql="SELECT COUNT(*) AS active_patients_count FROM patients WHERE status = 'active'",
+                confidence=0.95,
+                assumptions=["Using demo patients table and status = active."],
+            )
+
+        if "pacjent" in question or "patient" in question:
+            return GeneratedSql(
+                sql="SELECT COUNT(*) AS patients_count FROM patients",
+                confidence=0.95,
+                assumptions=["Using demo patients table."],
+            )
+
+        if "wizyt" in question or "appointment" in question:
+            return GeneratedSql(
+                sql="SELECT COUNT(*) AS appointments_count FROM appointments",
+                confidence=0.9,
+                assumptions=["Using demo appointments table."],
+            )
+
+        return GeneratedSql(
+            sql="SELECT 1 AS value",
+            confidence=0.5,
+            assumptions=["Fallback mock query."],
+        )