gaard-api 0.1.0__py3-none-any.whl

gaard_api/admin/defaults.py

@@ -0,0 +1,271 @@
+DEFAULT_SQL_GENERATION_SYSTEM_PROMPT = """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. 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.
+"""
+
+DEFAULT_SQL_GENERATION_USER_PROMPT = """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.
+"""
+
+DEFAULT_INTENT_CLASSIFICATION_SYSTEM_PROMPT = """You are GAARD Query Intent Classification.
+
+Your task is to decide whether the user's request can be fulfilled only by a read-only SQL SELECT query.
+
+Allowed decisions:
+- read_only_data_question: the user asks a question about data that can be answered with a read-only SELECT or WITH query.
+- write_or_mutation_request: the user asks to insert, update, delete, reset, clear, modify, create, alter, drop, or otherwise change data, schema, configuration, files, permissions, or system state.
+- non_data_request: the request is not a question about database data.
+- ambiguous: the intent is unclear or it is not safe to decide that it is read-only.
+
+Decision rules:
+1. Allow only requests whose intent is to read, count, list, aggregate, compare, summarize, inspect, or analyze existing data.
+2. Reject requests that ask for a change, even if a SELECT query could be used to find the affected rows.
+3. Reject destructive, administrative, or state-changing requests.
+4. Choose ambiguous instead of guessing when the intent is unclear.
+
+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":"read_only_data_question","confidence":0.0,"reason":"short reason"}
+"""
+
+DEFAULT_INTENT_CLASSIFICATION_USER_PROMPT = """Classify this user request before SQL generation.
+
+Input JSON:
+{payload}
+
+Return one JSON object with:
+- decision: one of read_only_data_question, write_or_mutation_request, non_data_request, ambiguous
+- confidence: number from 0 to 1
+- reason: short explanation
+"""
+
+DEFAULT_INVESTIGATION_READINESS_SYSTEM_PROMPT = """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
+"""
+
+DEFAULT_INVESTIGATION_READINESS_USER_PROMPT = """Assess whether normal SQL generation can start.
+
+Input JSON:
+{payload}
+
+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
+"""
+
+DEFAULT_RESULT_INTERPRETATION_SYSTEM_PROMPT = """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.
+"""
+
+DEFAULT_RESULT_INTERPRETATION_USER_PROMPT = """Interpret the following SQL result for the user.
+
+Input JSON:
+{payload}
+
+Return only the final user-facing answer.
+"""
+
+DEFAULT_RESULT_CLASSIFICATION_SYSTEM_PROMPT = """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.
+"""
+
+DEFAULT_RESULT_CLASSIFICATION_USER_PROMPT = """Classify this interpreted result.
+
+Input JSON:
+{payload}
+
+Return exactly one of:
+personal_data, sensitive_data, technical_data, neutral_data, unknown
+"""
+
+DEFAULT_GOVERNANCE_POLICY_CONFIG = {
+    "final_answer": {
+        "record_level_pii_allowed": False,
+        "prefer_aggregates_for_sensitive_domains": True,
+    },
+    "sql": {
+        "read_only": True,
+        "select_star_allowed": False,
+        "tenant_filter_required": False,
+        "tenant_column": None,
+    },
+    "privacy": {
+        "forbidden_columns": {},
+        "record_level_forbidden": False,
+    },
+    "pii_column_names": {
+        "identity": ["first_name", "last_name", "full_name"],
+        "contact": ["email", "phone"],
+        "birth_date": ["birth_date", "date_of_birth"],
+        "national_identifier": ["ssn", "pesel"],
+    },
+}
+
+DEFAULT_PROMPTS = [
+    {
+        "prompt_key": "intent_classification",
+        "name": "Intent classification",
+        "description": "Decides whether a user request is safe to process as read-only SQL.",
+        "system_prompt": DEFAULT_INTENT_CLASSIFICATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_INTENT_CLASSIFICATION_USER_PROMPT,
+    },
+    {
+        "prompt_key": "sql_generation",
+        "name": "SQL generation",
+        "description": "Generates one safe SQL SELECT statement from a user question and schema.",
+        "system_prompt": DEFAULT_SQL_GENERATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_SQL_GENERATION_USER_PROMPT,
+    },
+    {
+        "prompt_key": "investigation_readiness",
+        "name": "Investigation: readiness",
+        "description": "Decides whether Investigation can safely delegate to normal SQL generation.",
+        "system_prompt": DEFAULT_INVESTIGATION_READINESS_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_INVESTIGATION_READINESS_USER_PROMPT,
+    },
+    {
+        "prompt_key": "result_interpretation",
+        "name": "Result interpretation",
+        "description": "Explains SQL query results to the user.",
+        "system_prompt": DEFAULT_RESULT_INTERPRETATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_RESULT_INTERPRETATION_USER_PROMPT,
+    },
+    {
+        "prompt_key": "result_classification",
+        "name": "Result classification",
+        "description": "Classifies interpreted query answers into audit output data classes.",
+        "system_prompt": DEFAULT_RESULT_CLASSIFICATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_RESULT_CLASSIFICATION_USER_PROMPT,
+    },
+]

gaard_api/admin/models.py

@@ -0,0 +1,253 @@
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    Enum as SAEnum,
+    Float,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from gaard_core.query_pipeline.models import OutputClassification
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class AdminUser(Base):
+    __tablename__ = "admin_users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    username: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    password_hash: Mapped[str] = mapped_column(Text)
+    must_change_password: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+
+
+class AdminSession(Base):
+    __tablename__ = "admin_sessions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    token_hash: Mapped[str] = mapped_column(String(128), unique=True, index=True)
+    user_id: Mapped[int] = mapped_column(Integer, index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+
+
+class AdminAuditLog(Base):
+    __tablename__ = "admin_audit_logs"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    actor: Mapped[str] = mapped_column(String(255), index=True)
+    action: Mapped[str] = mapped_column(String(255), index=True)
+    resource_type: Mapped[str] = mapped_column(String(255), index=True)
+    resource_id: Mapped[str] = mapped_column(String(255), default="")
+    details_json: Mapped[str] = mapped_column(Text, default="{}")
+
+
+class DataQueryAuditType(StrEnum):
+    INFO = "info"
+    SQL_ERROR = "sql_error"
+    ACCESS_ERROR = "access_error"
+
+
+class DataQueryAuditLog(Base):
+    __tablename__ = "data_query_audit_logs"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    type: Mapped[DataQueryAuditType] = mapped_column(
+        SAEnum(
+            DataQueryAuditType,
+            values_callable=lambda items: [item.value for item in items],
+            native_enum=False,
+            validate_strings=True,
+            create_constraint=True,
+            length=50,
+            name="data_query_audit_type",
+        ),
+        default=DataQueryAuditType.INFO,
+        index=True,
+    )
+    user_id: Mapped[str] = mapped_column(String(255), index=True)
+    datasource_id: Mapped[str] = mapped_column(String(255), index=True)
+    question: Mapped[str] = mapped_column(Text)
+    answer: Mapped[str] = mapped_column(Text)
+    sql: Mapped[str] = mapped_column(Text)
+    output_classification: Mapped[OutputClassification] = mapped_column(
+        SAEnum(
+            OutputClassification,
+            values_callable=lambda items: [item.value for item in items],
+            native_enum=False,
+            validate_strings=True,
+            create_constraint=True,
+            length=50,
+            name="output_classification",
+        ),
+        default=OutputClassification.UNKNOWN,
+        index=True,
+    )
+    metadata_json: Mapped[str] = mapped_column(Text, default="{}")
+
+
+class PromptTemplate(Base):
+    __tablename__ = "prompt_templates"
+    __table_args__ = (UniqueConstraint("prompt_key", name="uq_prompt_templates_key"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    prompt_key: Mapped[str] = mapped_column(String(255), index=True)
+    name: Mapped[str] = mapped_column(String(255))
+    description: Mapped[str] = mapped_column(Text, default="")
+    system_prompt: Mapped[str] = mapped_column(Text)
+    user_prompt_template: Mapped[str] = mapped_column(Text)
+    version: Mapped[int] = mapped_column(Integer, default=1)
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+
+
+class AdminSetting(Base):
+    __tablename__ = "admin_settings"
+
+    key: Mapped[str] = mapped_column(String(255), primary_key=True)
+    value: Mapped[str] = mapped_column(Text)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+
+
+class DatasourceConnector(Base):
+    __tablename__ = "datasource_connectors"
+    __table_args__ = (UniqueConstraint("connector_key", name="uq_datasource_connectors_key"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    connector_key: Mapped[str] = mapped_column(String(255), index=True)
+    name: Mapped[str] = mapped_column(String(255))
+    database_type: Mapped[str] = mapped_column(String(50))
+    database_url: Mapped[str] = mapped_column(Text)
+    sql_dialect: Mapped[str] = mapped_column(String(50))
+    active: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+
+
+class DatasourceSchemaCache(Base):
+    __tablename__ = "datasource_schema_caches"
+
+    connector_id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    schema_json: Mapped[str] = mapped_column(Text)
+    table_settings_json: Mapped[str] = mapped_column(Text, default="{}")
+    formatted_schema: Mapped[str] = mapped_column(Text, default="")
+    introspected_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+
+
+class OverviewWidget(Base):
+    __tablename__ = "overview_widgets"
+    __table_args__ = (UniqueConstraint("widget_key", name="uq_overview_widgets_key"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    widget_key: Mapped[str] = mapped_column(String(255), index=True)
+    label: Mapped[str] = mapped_column(String(255))
+    widget_type: Mapped[str] = mapped_column(String(50))
+    datasource_key: Mapped[str] = mapped_column(String(255), default="metadata-db")
+    question: Mapped[str] = mapped_column(Text)
+    sql: Mapped[str] = mapped_column(Text, default="")
+    result_mode: Mapped[str] = mapped_column(String(50), default="data")
+    position: Mapped[int] = mapped_column(Integer, default=100)
+    grid_width: Mapped[int] = mapped_column(Integer, default=1)
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+
+
+class BusinessLogicSuggestion(Base):
+    __tablename__ = "business_logic_suggestions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    connector_id: Mapped[int] = mapped_column(Integer, index=True)
+    source_audit_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    status: Mapped[str] = mapped_column(String(50), index=True, default="pending")
+    safety: Mapped[str] = mapped_column(String(50), index=True, default="review")
+    enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    error_category: Mapped[str] = mapped_column(String(100), index=True)
+    title: Mapped[str] = mapped_column(String(255))
+    rule_text: Mapped[str] = mapped_column(Text)
+    terms_json: Mapped[str] = mapped_column(Text, default="[]")
+    join_hints_json: Mapped[str] = mapped_column(Text, default="[]")
+    failed_identifier: Mapped[str] = mapped_column(String(255), default="")
+    repaired_identifier: Mapped[str] = mapped_column(String(255), default="")
+    confidence: Mapped[float] = mapped_column(Float, default=0.0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")
+
+
+class BusinessKnowledgeClaim(Base):
+    __tablename__ = "business_knowledge_claims"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    connector_id: Mapped[int] = mapped_column(Integer, index=True)
+    knowledge_type: Mapped[str] = mapped_column(String(100), index=True)
+    status: Mapped[str] = mapped_column(String(50), index=True, default="candidate")
+    claim_text: Mapped[str] = mapped_column(Text)
+    subject_json: Mapped[str] = mapped_column(Text, default="{}")
+    evidence_json: Mapped[str] = mapped_column(Text, default="[]")
+    confidence: Mapped[float] = mapped_column(Float, default=0.0)
+    source: Mapped[str] = mapped_column(String(100), index=True, default="query_pipeline")
+    request_id: Mapped[str] = mapped_column(String(255), index=True, default="")
+    audit_reference: Mapped[str] = mapped_column(String(255), default="")
+    requires_approval: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    last_verified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+    updated_by: Mapped[str] = mapped_column(String(255), default="system")