analyticsreceipts 0.0.2__py3-none-any.whl

analyticsreceipts/data/ossie-schema.json

@@ -0,0 +1,374 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/apache/ossie/core-spec/ossie-schema.json",
+  "title": "Apache Ossie Core Metadata Specification",
+  "description": "JSON Schema for validating a single Apache Ossie semantic model document",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "0.2.0.dev0",
+      "description": "Apache Ossie specification version"
+    },
+    "name": {
+      "$ref": "#/$defs/SemanticModel/properties/name"
+    },
+    "description": {
+      "$ref": "#/$defs/SemanticModel/properties/description"
+    },
+    "ai_context": {
+      "$ref": "#/$defs/SemanticModel/properties/ai_context"
+    },
+    "datasets": {
+      "$ref": "#/$defs/SemanticModel/properties/datasets"
+    },
+    "relationships": {
+      "$ref": "#/$defs/SemanticModel/properties/relationships"
+    },
+    "metrics": {
+      "$ref": "#/$defs/SemanticModel/properties/metrics"
+    },
+    "custom_extensions": {
+      "$ref": "#/$defs/SemanticModel/properties/custom_extensions"
+    }
+  },
+  "required": ["version", "name", "datasets"],
+  "additionalProperties": false,
+  "$defs": {
+    "Dialect": {
+      "type": "string",
+      "enum": ["ANSI_SQL", "SNOWFLAKE", "MDX", "TABLEAU", "DATABRICKS", "MAQL", "BIGQUERY", "SIGMA", "THOUGHTSPOT", "DAX", "OSSIE_SQL_2026"],
+      "description": "Supported SQL and expression language dialects"
+    },
+    "Vendor": {
+      "type": "string",
+      "examples": ["COMMON", "SNOWFLAKE", "SALESFORCE", "DBT", "DATABRICKS", "GOODDATA", "WISDOM", "POWER_BI"],
+      "description": "Vendor name for custom extensions. Any string value is accepted."
+    },
+    "AIContext": {
+      "description": "Additional context for AI tools",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "instructions": {
+              "type": "string",
+              "description": "Instructions for AI on how to use this entity"
+            },
+            "synonyms": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Alternative names and terms"
+            },
+            "examples": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Sample questions or use cases"
+            }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+    "CustomExtension": {
+      "type": "object",
+      "description": "Vendor-specific attributes for extensibility",
+      "properties": {
+        "vendor_name": {
+          "$ref": "#/$defs/Vendor"
+        },
+        "data": {
+          "type": "string",
+          "description": "JSON string containing vendor-specific data"
+        }
+      },
+      "required": ["vendor_name", "data"],
+      "additionalProperties": false
+    },
+    "DialectExpression": {
+      "type": "object",
+      "description": "Expression in a specific dialect",
+      "properties": {
+        "dialect": {
+          "$ref": "#/$defs/Dialect"
+        },
+        "expression": {
+          "type": "string",
+          "description": "SQL or dialect-specific expression"
+        }
+      },
+      "required": ["dialect", "expression"],
+      "additionalProperties": false
+    },
+    "Expression": {
+      "type": "object",
+      "description": "Expression definition with multi-dialect support",
+      "properties": {
+        "dialects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DialectExpression"
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["dialects"],
+      "additionalProperties": false
+    },
+    "DataType": {
+      "type": "string",
+      "enum": [
+        "String",
+        "Integer",
+        "Decimal",
+        "Float",
+        "Boolean",
+        "Date",
+        "Time",
+        "DateTime",
+        "DateTimeTz",
+        "Opaque"
+      ],
+      "description": "Logical data type for fields and metrics, independent of role (e.g. dimension vs fact) and physical representation. `Decimal` is exact base-10 with unspecified precision and scale; `Float` is approximate. `DateTime` has no timezone or offset, while `DateTimeTz` identifies an instant using offset or timezone context but does not guarantee preservation of a named timezone. Omit `datatype` when unknown; use `Opaque` plus `custom_extensions` for a known type outside the portable vocabulary."
+    },
+    "Dimension": {
+      "type": "object",
+      "description": "Dimension metadata",
+      "properties": {
+        "is_time": {
+          "type": "boolean",
+          "description": "Temporal-role marker. When true, consumers that distinguish time dimensions (e.g. for time-series analysis or temporal filtering) should treat this field as a time dimension. This is a *role* flag, independent of the field's data type: a field with `is_time: true` may carry any `datatype` (e.g. `Integer` for a year grain, `String` for a month name, as well as temporal data types). When `is_time` is unset, it defaults to `true` if `datatype` is one of `Date`, `Time`, `DateTime`, or `DateTimeTz`, and `false` otherwise. Set `is_time: false` explicitly to opt a temporal-typed column (such as an audit timestamp) out of time-dimension treatment."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Field": {
+      "type": "object",
+      "description": "Row-level attribute for grouping, filtering, and metric expressions",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier for the field within the dataset"
+        },
+        "expression": {
+          "$ref": "#/$defs/Expression"
+        },
+        "dimension": {
+          "$ref": "#/$defs/Dimension"
+        },
+        "label": {
+          "type": "string",
+          "description": "Label for categorization"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "datatype": {
+          "$ref": "#/$defs/DataType"
+        },
+        "ai_context": {
+          "$ref": "#/$defs/AIContext"
+        },
+        "custom_extensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CustomExtension"
+          }
+        }
+      },
+      "required": ["name", "expression"],
+      "additionalProperties": false
+    },
+    "Dataset": {
+      "type": "object",
+      "description": "Logical dataset representing a business entity (fact or dimension table)",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier for the dataset"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Reference to underlying physical table/view (database.schema.table) or query"
+        },
+        "primary_key": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Primary key columns (single or composite)"
+        },
+        "unique_keys": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "description": "Array of unique key definitions (each can be single or composite)"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "ai_context": {
+          "$ref": "#/$defs/AIContext"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Field"
+          }
+        },
+        "custom_extensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CustomExtension"
+          }
+        }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": false
+    },
+    "Relationship": {
+      "type": "object",
+      "description": "Foreign key relationship between datasets",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier for the relationship"
+        },
+        "from": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Dataset on the many side of the relationship"
+        },
+        "to": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Dataset on the one side of the relationship"
+        },
+        "from_columns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Foreign key columns in the 'from' dataset"
+        },
+        "to_columns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Primary/unique key columns in the 'to' dataset"
+        },
+        "ai_context": {
+          "$ref": "#/$defs/AIContext"
+        },
+        "custom_extensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CustomExtension"
+          }
+        }
+      },
+      "required": ["name", "from", "to", "from_columns", "to_columns"],
+      "additionalProperties": false
+    },
+    "Metric": {
+      "type": "object",
+      "description": "Quantitative measure defined on business data",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier for the metric"
+        },
+        "expression": {
+          "$ref": "#/$defs/Expression"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what the metric measures"
+        },
+        "datatype": {
+          "$ref": "#/$defs/DataType"
+        },
+        "ai_context": {
+          "$ref": "#/$defs/AIContext"
+        },
+        "custom_extensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CustomExtension"
+          }
+        }
+      },
+      "required": ["name", "expression"],
+      "additionalProperties": false
+    },
+    "SemanticModel": {
+      "type": "object",
+      "description": "Top-level container representing a complete semantic model",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier for the semantic model"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "ai_context": {
+          "$ref": "#/$defs/AIContext"
+        },
+        "datasets": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Dataset"
+          },
+          "minItems": 1,
+          "description": "Collection of logical datasets"
+        },
+        "relationships": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Relationship"
+          },
+          "description": "Defines how datasets are connected"
+        },
+        "metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Metric"
+          },
+          "description": "Quantifiable measures spanning datasets"
+        },
+        "custom_extensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CustomExtension"
+          }
+        }
+      },
+      "required": ["name", "datasets"],
+      "additionalProperties": false
+    }
+  }
+}

analyticsreceipts/execution.py

@@ -0,0 +1,185 @@
+"""Read-only execution with caps, and the receipt emitted on the execution path.
+
+The connection is opened read-only with external access disabled and the configuration locked, so
+a statement cannot read or write files outside the database (no read_csv, no COPY TO) or loosen
+those settings. Every result is capped by rows and by time. The same instance is capped in memory, threads
+and temp-file disk use (set before the lock), and at most MAX_CONCURRENT_RUNS statements run at once.
+"""
+
+import datetime as dt
+import decimal
+import hashlib
+import json
+import threading
+import time
+import uuid
+
+import duckdb
+
+RECEIPT_VERSION = "2"  # 2: `compiler` required and tied to `kind`; no non_additive_guard check
+ROW_CAP = 1000
+TIMEOUT_S = 20.0
+MEMORY_LIMIT = "1GB"           # per DuckDB instance, shared by every cursor on it
+THREADS = 2
+MAX_TEMP_DIRECTORY_SIZE = "0B"  # no spilling to disk: a query over the memory limit fails instead
+MAX_CONCURRENT_RUNS = 4         # per process; further calls wait (up to their timeout) for a slot
+_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
+_LIMITS = {"memory_limit": f"'{MEMORY_LIMIT}'", "threads": str(THREADS),
+           "max_temp_directory_size": f"'{MAX_TEMP_DIRECTORY_SIZE}'"}
+
+
+def connect(db_path):
+    con = duckdb.connect(db_path, read_only=True, config={"enable_external_access": False})
+    # a second connection to the same file in one process shares the (already locked) instance
+    if not con.execute("SELECT current_setting('lock_configuration')").fetchone()[0]:
+        for name, value in _LIMITS.items():
+            con.execute(f"SET {name} = {value}")
+        con.execute("SET lock_configuration = true")
+    if _settings(con) != _expected_settings():
+        raise RuntimeError("this database instance was locked with other resource limits; refusing to serve")
+    if con.execute("SELECT current_setting('enable_external_access')").fetchone()[0]:
+        raise RuntimeError("external access is enabled on this database instance; refusing to serve")
+    return con
+
+
+def _settings(con):
+    return {n: con.execute("SELECT current_setting(?)", [n]).fetchone()[0] for n in _LIMITS}
+
+
+_EXPECTED = []
+
+
+def _expected_settings():
+    # how DuckDB reports the limits (e.g. '1GB' reads back as '953.6 MiB'), from a scratch in-memory instance
+    if not _EXPECTED:
+        scratch = duckdb.connect()
+        for name, value in _LIMITS.items():
+            scratch.execute(f"SET {name} = {value}")
+        _EXPECTED.append(_settings(scratch))
+        scratch.close()
+    return _EXPECTED[0]
+
+
+def _cell(v):
+    if isinstance(v, decimal.Decimal):
+        return float(v)
+    if isinstance(v, (dt.date, dt.datetime)):
+        return v.isoformat()
+    return v
+
+
+def file_sha256(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+class Executor:
+    def __init__(self, db_path):
+        self.db_path = db_path
+        self.con = connect(db_path)
+        # a warehouse built by analyticsreceipts.load carries snapshot_meta; any other warehouse is
+        # fingerprinted by its file hash alone, and its data range comes from the semantic model
+        has_meta = self.con.execute("SELECT count(*) FROM information_schema.tables "
+                                    "WHERE table_name = 'snapshot_meta'").fetchone()[0]
+        if has_meta:
+            meta = self.con.execute("SELECT xlsx_sha256, max_invoice_ts FROM snapshot_meta").fetchone()
+            self.snapshot = {"source_xlsx_sha256": meta[0], "max_invoice_ts": meta[1].isoformat(),
+                             "db_file_sha256": file_sha256(db_path)}
+        else:
+            self.snapshot = {"db_file_sha256": file_sha256(db_path)}
+        self.data_range = None  # (start_date, end_date, end_label), set by the server from the model
+
+    def set_data_range(self, start, end):
+        label = self.snapshot.get("max_invoice_ts") or end
+        self.data_range = (start, end, label)
+
+    def run(self, sql, params=(), cap=ROW_CAP, timeout_s=TIMEOUT_S):
+        """Returns (columns, rows, truncated, error). Never raises for a bad statement.
+
+        Each call runs on its own cursor (a separate connection to the same read-only database), and
+        the timeout interrupts only that cursor. Concurrent calls (the MCP SDK runs sync tools on worker
+        threads) therefore can neither read each other's results nor cancel each other's queries. At most
+        MAX_CONCURRENT_RUNS calls run at once; a call that gets no slot within timeout_s returns an error.
+        """
+        if not _RUN_SLOTS.acquire(timeout=timeout_s):
+            return [], [], False, f"Busy: {MAX_CONCURRENT_RUNS} queries already running; no slot within {timeout_s} s"
+        try:
+            return self._run(sql, params, cap, timeout_s)
+        finally:
+            _RUN_SLOTS.release()
+
+    def _run(self, sql, params, cap, timeout_s):
+        cur = self.con.cursor()
+        timer = threading.Timer(timeout_s, cur.interrupt)
+        timer.start()
+        try:
+            cur.execute(sql, list(params))
+            cols = [d[0] for d in (cur.description or [])]
+            rows = cur.fetchmany(cap + 1)
+        except Exception as e:  # the statement failed; the caller records it
+            return [], [], False, f"{type(e).__name__}: {str(e).splitlines()[0][:300]}"
+        finally:
+            timer.cancel()
+            cur.close()
+        truncated = len(rows) > cap
+        rows = [[_cell(v) for v in r] for r in rows[:cap]]
+        return cols, rows, truncated, None
+
+
+def result_sha256(columns, rows):
+    return hashlib.sha256(json.dumps({"columns": columns, "rows": rows}, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def make_receipt(*, executor, kind, request, metric_id, metric_def_version, semantic_model_sha256, sql, params,
+                 sql_sha256, columns, rows, truncated, error, checks, caveats, server_version, started, compiler=None):
+    return {
+        "receipt_version": RECEIPT_VERSION,
+        "kind": kind,  # "governed_metric" (MCP query_metric), "control_metric" (planted compiler) or "raw_sql"
+        "compiler": compiler,  # "governed", "planted:<bug>" for a control run, None for raw SQL
+        "request": request,
+        "metric_id": metric_id,
+        "metric_def_version": metric_def_version,
+        "semantic_model_sha256": semantic_model_sha256,
+        "compiled_sql": sql,
+        "params": list(params),
+        "compiled_sql_sha256": sql_sha256 or hashlib.sha256((sql + "\n" + json.dumps(list(params))).encode()).hexdigest(),
+        "engine": {"name": "duckdb", "version": duckdb.__version__},
+        "snapshot": executor.snapshot,
+        "result": {"columns": columns, "rows": rows},
+        "result_sha256": None if error else result_sha256(columns, rows),
+        "row_count": len(rows),
+        "truncated": truncated,
+        "error": error,
+        "checks": checks,
+        "uncertainty": {"caveats_applied": caveats},
+        "run": {"request_id": uuid.uuid4().hex, "server_version": server_version, "started_at": started,
+                "elapsed_s": round(time.time() - _epoch(started), 3)},
+    }
+
+
+def _epoch(iso):
+    return dt.datetime.fromisoformat(iso).timestamp()
+
+
+def now_iso():
+    return dt.datetime.now().isoformat(timespec="milliseconds")
+
+
+def period_checks(data_range, time_range, comparison_range=None):
+    """Checks that make an incomplete or out-of-data period visible in the receipt.
+    data_range = (first data date, last data date, label for the last data point)."""
+    min_date, max_date, end_label = data_range
+    out = []
+    for name, r in (("time_range", time_range), ("comparison_range", comparison_range)):
+        if not r:
+            continue
+        complete = r["end"] <= max_date
+        out.append({"name": f"{name}_complete", "success": complete,
+                    "expected": f"end <= last data date {max_date}", "actual": r["end"],
+                    "note": None if complete else f"data ends {end_label}; the period is incomplete"})
+        out.append({"name": f"{name}_starts_in_data", "success": r["start"] >= min_date,
+                    "expected": f"start >= {min_date}", "actual": r["start"]})
+    return out