lagaam 0.2.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. lagaam/__init__.py +1 -0
  2. lagaam/__main__.py +79 -0
  3. lagaam/adapters/__init__.py +0 -0
  4. lagaam/adapters/pinot/__init__.py +7 -0
  5. lagaam/adapters/pinot/client.py +190 -0
  6. lagaam/adapters/pinot/dialect.py +106 -0
  7. lagaam/adapters/pinot/engine.py +990 -0
  8. lagaam/adapters/pinot/errors.py +54 -0
  9. lagaam/adapters/pinot/keys.py +717 -0
  10. lagaam/adapters/pinot/metadata.py +584 -0
  11. lagaam/adapters/pinot/names.py +171 -0
  12. lagaam/adapters/pinot/plan.py +187 -0
  13. lagaam/adapters/pinot/quote.py +210 -0
  14. lagaam/adapters/pinot/rels.py +71 -0
  15. lagaam/adapters/pinot/response.py +207 -0
  16. lagaam/adapters/trino/__init__.py +0 -0
  17. lagaam/adapters/trino/dialect.py +19 -0
  18. lagaam/adapters/trino/engine.py +364 -0
  19. lagaam/adapters/trino/explain.py +106 -0
  20. lagaam/adapters/trino/numbers.py +28 -0
  21. lagaam/adapters/trino/plan.py +347 -0
  22. lagaam/core/__init__.py +0 -0
  23. lagaam/core/allowlist.py +153 -0
  24. lagaam/core/audit.py +244 -0
  25. lagaam/core/budget.py +163 -0
  26. lagaam/core/caching.py +85 -0
  27. lagaam/core/cards.py +26 -0
  28. lagaam/core/cost.py +19 -0
  29. lagaam/core/errors.py +64 -0
  30. lagaam/core/identifiers.py +110 -0
  31. lagaam/core/identity.py +85 -0
  32. lagaam/core/models.py +105 -0
  33. lagaam/core/ports.py +36 -0
  34. lagaam/core/query_errors.py +93 -0
  35. lagaam/core/safety.py +385 -0
  36. lagaam/core/scans.py +1885 -0
  37. lagaam/core/verification.py +42 -0
  38. lagaam/py.typed +0 -0
  39. lagaam/server.py +189 -0
  40. lagaam-0.2.3.dist-info/METADATA +83 -0
  41. lagaam-0.2.3.dist-info/RECORD +44 -0
  42. lagaam-0.2.3.dist-info/WHEEL +4 -0
  43. lagaam-0.2.3.dist-info/entry_points.txt +3 -0
  44. lagaam-0.2.3.dist-info/licenses/LICENSE +201 -0
lagaam/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """Lagaam — governed MCP analytics server for the open lakehouse."""
lagaam/__main__.py ADDED
@@ -0,0 +1,79 @@
1
+ """Run the Lagaam MCP server over stdio, wired to one engine from env vars.
2
+
3
+ Usage: uvx lagaam (from a checkout: uv run python -m lagaam)
4
+
5
+ The server refuses to start without a table grant: an agent that can reach
6
+ every table in every catalog is the thing this exists to prevent, so that
7
+ has to be asked for rather than inherited from an empty environment.
8
+
9
+ Env:
10
+ LAGAAM_ENGINE which adapter to run: trino (default) or pinot
11
+ TRINO_HOST (localhost), TRINO_PORT (8080), TRINO_USER (lagaam)
12
+ PINOT_CONTROLLER_URL (http://localhost:9000), PINOT_BROKER_URL
13
+ (http://localhost:8000), PINOT_USER, PINOT_PASSWORD (unset = no auth)
14
+ LAGAAM_ALLOWED_TABLES comma list of catalog.schema.table — REQUIRED
15
+ LAGAAM_ALLOW_ALL_TABLES=true explicit opt-out: every table, no grant
16
+ LAGAAM_AGENT_NAME identity on the audit trail (anonymous)
17
+ LAGAAM_MAX_SCAN_BYTES pre-execution scan budget (50 GiB)
18
+ LAGAAM_MAX_ROWS pre-execution scanned-row budget (ungated)
19
+ LAGAAM_MAX_INTERMEDIATE_ROWS widest-operator row budget (default 50000000)
20
+ LAGAAM_MAX_RETURNED_ROWS rows handed back (1000, capped at 100000);
21
+ a bigger LIMIT in the query is lowered to it
22
+ LAGAAM_QUERY_TIMEOUT wall-clock seconds per query (300)
23
+ LAGAAM_METADATA_TTL metadata cache TTL in seconds (300)
24
+ LAGAAM_AUDIT_LOG audit JSONL path (unset = stderr)
25
+ """
26
+
27
+ import os
28
+ import sys
29
+
30
+ from lagaam.adapters.pinot.engine import PinotEngine
31
+ from lagaam.adapters.trino.engine import TrinoEngine
32
+ from lagaam.core.audit import AuditLog
33
+ from lagaam.core.budget import QueryBudget
34
+ from lagaam.core.caching import CachingQueryEngine
35
+ from lagaam.core.errors import ConfigurationError
36
+ from lagaam.core.identity import AgentIdentity
37
+ from lagaam.core.ports import QueryEngine
38
+ from lagaam.server import create_server
39
+
40
+
41
+ def _select_engine() -> QueryEngine:
42
+ """The adapter named by LAGAAM_ENGINE; trino when unset.
43
+
44
+ An unknown name is a configuration error rather than a silent default:
45
+ a typo must not quietly point an agent at the wrong data platform.
46
+ """
47
+ name = os.environ.get("LAGAAM_ENGINE", "trino").strip().lower()
48
+ if name == "trino":
49
+ return TrinoEngine.from_env()
50
+ if name == "pinot":
51
+ return PinotEngine.from_env()
52
+ raise ConfigurationError(
53
+ f"LAGAAM_ENGINE={name!r} is not an engine this server has. "
54
+ "Set it to 'trino' or 'pinot'."
55
+ )
56
+
57
+
58
+ def main() -> None:
59
+ try:
60
+ engine = CachingQueryEngine(
61
+ _select_engine(),
62
+ ttl_seconds=float(os.environ.get("LAGAAM_METADATA_TTL", "300")),
63
+ )
64
+ server = create_server(
65
+ engine,
66
+ budget=QueryBudget.from_env(),
67
+ identity=AgentIdentity.from_env(),
68
+ audit=AuditLog.from_env(),
69
+ )
70
+ except (ConfigurationError, ValueError) as exc:
71
+ # A misconfigured server is an operator's problem: say what to set,
72
+ # on stderr, and exit — never a traceback into an agent's stdio.
73
+ print(f"lagaam: {exc}", file=sys.stderr)
74
+ raise SystemExit(2)
75
+ server.run()
76
+
77
+
78
+ if __name__ == "__main__":
79
+ main()
File without changes
@@ -0,0 +1,7 @@
1
+ """Native Pinot adapter for the QueryEngine port."""
2
+
3
+ # Core parses with the card's dialect string, so the Pinot dialect class must
4
+ # be registered before any parse — importing the module is what registers it.
5
+ from lagaam.adapters.pinot import dialect as dialect
6
+
7
+ __all__ = ["dialect"]
@@ -0,0 +1,190 @@
1
+ """httpx wiring for Pinot: the only module in this adapter with an HTTP verb.
2
+
3
+ Two services with separate principal lists — the controller for metadata and
4
+ the broker for queries — so basic auth is threaded into both. Every failure
5
+ that is not a well-formed JSON body leaves as PinotTransportError, which the
6
+ engine turns into an EngineError; a controller 404 is not a failure but a
7
+ "no such thing", returned as the NotFound sentinel so the caller can decide.
8
+ """
9
+
10
+ import json
11
+ from typing import Any, Final
12
+ from urllib.parse import quote
13
+
14
+ import httpx
15
+
16
+
17
+ class PinotTransportError(Exception):
18
+ """Pinot could not be reached, or answered with something unreadable.
19
+
20
+ Adapter-private: never raised past engine.py, which translates it into
21
+ core's EngineError so no transport detail reaches an agent.
22
+ """
23
+
24
+
25
+ class PinotForbidden(Exception):
26
+ """Pinot refused the credentials or the table: a 401 or a 403.
27
+
28
+ Adapter-private like PinotTransportError, and deliberately body-free: the
29
+ refusal text names tables the caller may not be allowed to learn about.
30
+ A refusal is not an outage — retrying it unchanged never succeeds.
31
+ """
32
+
33
+
34
+ class PinotResponseTooLarge(Exception):
35
+ """The broker's answer outgrew the byte ceiling this client will read.
36
+
37
+ Adapter-private like PinotTransportError: engine.py turns it into the
38
+ agent-fixable RESPONSE_TOO_LARGE hint. Measured on 1.5.1, the multi-stage
39
+ engine accepts maxQueryResponseSizeBytes and ignores it, so this is the
40
+ only place the ceiling is actually enforced.
41
+ """
42
+
43
+
44
+ class _NotFound:
45
+ """Sentinel: the controller answered 404 for this path."""
46
+
47
+
48
+ # Anything that could reshape a URL path, plus whitespace a name may not carry.
49
+ _ILLEGAL_PART_CHARS: Final = frozenset("/.\\?#%")
50
+
51
+ # 401 from the auth filter, 403 from either request handler's table refusal.
52
+ _REFUSED_STATUSES: Final = frozenset({401, 403})
53
+
54
+
55
+ class PinotClient:
56
+ NotFound: Final = _NotFound
57
+
58
+ def __init__(
59
+ self,
60
+ controller_url: str,
61
+ broker_url: str,
62
+ user: str | None = None,
63
+ password: str | None = None,
64
+ timeout_seconds: float = 30.0,
65
+ *,
66
+ max_response_bytes: int = 64 * 1024 * 1024,
67
+ transport: httpx.AsyncBaseTransport | None = None,
68
+ ) -> None:
69
+ self._controller_url = controller_url.rstrip("/")
70
+ self._broker_url = broker_url.rstrip("/")
71
+ self._max_response_bytes = max_response_bytes
72
+ auth = (user, password) if user is not None and password is not None else None
73
+ self._http = httpx.AsyncClient(auth=auth, timeout=timeout_seconds, transport=transport)
74
+
75
+ @staticmethod
76
+ def path_part(part: str) -> str:
77
+ """One agent-supplied name, safe to place in a URL path.
78
+
79
+ Table names arrive from agents and land in controller paths, so this
80
+ is a security boundary: a part carrying a separator is refused rather
81
+ than encoded, because a name Pinot cannot hold is a name we never ask for.
82
+ """
83
+ if not part or part.strip() != part:
84
+ raise ValueError(f"not a usable Pinot name: {part!r}")
85
+ # Non-ASCII would raise UnicodeEncodeError inside httpx's header encoding.
86
+ if not part.isascii():
87
+ raise ValueError(f"not a usable Pinot name: {part!r}")
88
+ if any(char in _ILLEGAL_PART_CHARS for char in part):
89
+ raise ValueError(f"not a usable Pinot name: {part!r}")
90
+ if any(char.isspace() for char in part):
91
+ raise ValueError(f"not a usable Pinot name: {part!r}")
92
+ return quote(part, safe="")
93
+
94
+ async def controller_get(
95
+ self,
96
+ path: str,
97
+ params: dict[str, str | list[str]] | None = None,
98
+ database: str | None = None,
99
+ ) -> Any:
100
+ """GET one controller path. Returns parsed JSON, or NotFound on 404."""
101
+ headers = {"database": database} if database else None
102
+ try:
103
+ response = await self._http.get(
104
+ f"{self._controller_url}{path}",
105
+ params=params,
106
+ headers=headers,
107
+ )
108
+ except httpx.HTTPError as exc:
109
+ raise PinotTransportError(f"controller GET {path} failed") from exc
110
+ if response.status_code == 404:
111
+ return self.NotFound
112
+ if response.status_code in _REFUSED_STATUSES:
113
+ raise PinotForbidden(f"controller GET {path} was refused")
114
+ if response.status_code >= 400:
115
+ raise PinotTransportError(
116
+ f"controller GET {path} returned {response.status_code}"
117
+ )
118
+ return self._json(response, f"controller GET {path}")
119
+
120
+ async def broker_query(
121
+ self, sql: str, options: str, timeout_seconds: float | None = None
122
+ ) -> Any:
123
+ """POST one query to the broker. Returns parsed JSON.
124
+
125
+ Never checks the status code for a query error: every Pinot query
126
+ error is an HTTP 200 carrying exceptions[]. The body is streamed and
127
+ abandoned the moment it passes max_response_bytes, because the broker
128
+ will not stop on its own — measured, the multi-stage engine returns
129
+ the whole result however low maxQueryResponseSizeBytes is set.
130
+ """
131
+ try:
132
+ async with self._http.stream(
133
+ "POST",
134
+ f"{self._broker_url}/query/sql",
135
+ json={"sql": sql, "queryOptions": options},
136
+ timeout=timeout_seconds if timeout_seconds is not None else httpx.USE_CLIENT_DEFAULT,
137
+ ) as response:
138
+ if response.status_code in _REFUSED_STATUSES:
139
+ raise PinotForbidden("broker query was refused")
140
+ if response.status_code >= 400:
141
+ raise PinotTransportError(
142
+ f"broker query returned {response.status_code}"
143
+ )
144
+ self._check_declared_size(response)
145
+ body = await self._read_capped(response)
146
+ except (PinotResponseTooLarge, PinotForbidden):
147
+ # Must not be caught by the httpx.HTTPError handler below.
148
+ raise
149
+ except httpx.HTTPError as exc:
150
+ raise PinotTransportError("broker query failed") from exc
151
+ try:
152
+ return json.loads(body)
153
+ except ValueError as exc:
154
+ raise PinotTransportError("broker query returned a non-JSON body") from exc
155
+
156
+ def _check_declared_size(self, response: httpx.Response) -> None:
157
+ """Refuse an oversized body before a byte of it is read."""
158
+ declared = response.headers.get("content-length")
159
+ if declared is None:
160
+ return
161
+ try:
162
+ length = int(declared)
163
+ except ValueError:
164
+ return
165
+ if length > self._max_response_bytes:
166
+ raise PinotResponseTooLarge(
167
+ f"broker declared {length} bytes, over the {self._max_response_bytes} ceiling"
168
+ )
169
+
170
+ async def _read_capped(self, response: httpx.Response) -> bytes:
171
+ chunks: list[bytes] = []
172
+ total = 0
173
+ async for chunk in response.aiter_bytes():
174
+ total += len(chunk)
175
+ if total > self._max_response_bytes:
176
+ raise PinotResponseTooLarge(
177
+ f"broker response passed the {self._max_response_bytes} byte ceiling"
178
+ )
179
+ chunks.append(chunk)
180
+ return b"".join(chunks)
181
+
182
+ async def aclose(self) -> None:
183
+ await self._http.aclose()
184
+
185
+ @staticmethod
186
+ def _json(response: httpx.Response, what: str) -> Any:
187
+ try:
188
+ return response.json()
189
+ except ValueError as exc:
190
+ raise PinotTransportError(f"{what} returned a non-JSON body") from exc
@@ -0,0 +1,106 @@
1
+ """The Pinot dialect card, and a sqlglot dialect that sends Pinot what was written.
2
+
3
+ Every statement is re-rendered by sqlglot before it reaches the broker
4
+ (`validate_query`, then `two_part_sql`). The generic dialect canonicalises
5
+ spellings, and Pinot's parser does not accept the canonical ones: measured on
6
+ Pinot 1.5.1 on both engines, fourteen valid Pinot shapes broke or changed
7
+ their answer on the way out, and `ARRAY_AGG(c, 'TYPE', distinct)` was rejected
8
+ before it was ever sent. See
9
+ docs/superpowers/specs/2026-09-20-pinot-dialect-measurements.md and ADR 0010.
10
+
11
+ This is configuration of sqlglot's own parser and generator — what ADR 0003
12
+ permits — not a parser. Principle: preserve, never transpile. The card makes
13
+ the agent write Pinot SQL; sqlglot's job here is validation and two small
14
+ rewrites (LIMIT, catalog), so where a generic node cannot say a Pinot call
15
+ back, the call is kept as written.
16
+ """
17
+
18
+ from collections.abc import Callable
19
+ from typing import ClassVar
20
+
21
+ from sqlglot import exp, generator, parser
22
+ from sqlglot.dialects.dialect import Dialect, inline_array_sql, rename_func
23
+ from sqlglot.helper import seq_get
24
+
25
+ from lagaam.core.models import DialectCard
26
+
27
+ # Calls the generic parser folds into a node that cannot say them back:
28
+ # LOG10/LOG2 become LOG(base, x) and Pinot's LOG takes one argument; SUBSTR
29
+ # becomes SUBSTRING, which counts from 1, not 0; the rest are renamed to
30
+ # spellings Pinot has never had, or lose arguments on the way.
31
+ _KEPT_AS_WRITTEN = frozenset(
32
+ {"JSON_EXTRACT_SCALAR", "SUBSTR", "STRPOS", "LOG10", "LOG2", "TRUNCATE"}
33
+ )
34
+
35
+
36
+ class ArrayAgg(exp.Expression, exp.AggFunc):
37
+ """Pinot's ARRAY_AGG(column[, 'TYPE'[, distinct]]); sqlglot's own holds one argument."""
38
+
39
+ arg_types: ClassVar[dict[str, bool]] = {"this": True, "expressions": False}
40
+ is_var_len_args = True
41
+ _sql_names: ClassVar[list[str]] = ["ARRAY_AGG", "ARRAYAGG"]
42
+
43
+
44
+ def _parse_array_agg(args: list[exp.Expr]) -> ArrayAgg:
45
+ # A missing column is sqlglot's to refuse: it names the required argument.
46
+ return ArrayAgg(this=seq_get(args, 0), expressions=args[1:])
47
+
48
+
49
+ def _array_agg_sql(self: generator.Generator, expression: ArrayAgg) -> str:
50
+ return self.func("ARRAY_AGG", expression.this, *expression.expressions)
51
+
52
+
53
+ def _array_sql(self: generator.Generator, expression: exp.Array) -> str:
54
+ """ARRAY['a', 'b'] — measured: Pinot's parser rejects the bare `['a', 'b']`
55
+ that sqlglot's own inline_array_sql emits, on both engines."""
56
+ return f"ARRAY{inline_array_sql(self, expression)}"
57
+
58
+
59
+ class Pinot(Dialect):
60
+ """Registered by sqlglot under its lowercased class name: "pinot"."""
61
+
62
+ class Parser(parser.Parser):
63
+ FUNCTIONS: ClassVar[dict[str, Callable[..., exp.Expr]]] = {
64
+ **{
65
+ name: builder
66
+ for name, builder in parser.Parser.FUNCTIONS.items()
67
+ if name not in _KEPT_AS_WRITTEN
68
+ },
69
+ "ARRAY_AGG": _parse_array_agg,
70
+ "ARRAYAGG": _parse_array_agg,
71
+ }
72
+
73
+ class Generator(generator.Generator):
74
+ # Bare ClassVar, as in sqlglot: exp.DataType.Type is not valid as a type.
75
+ TYPE_MAPPING: ClassVar = {
76
+ **generator.Generator.TYPE_MAPPING,
77
+ exp.DataType.Type.TEXT: "STRING",
78
+ }
79
+ TRANSFORMS: ClassVar[dict[type[exp.Expr], Callable[..., str]]] = {
80
+ **generator.Generator.TRANSFORMS,
81
+ exp.Array: _array_sql,
82
+ exp.VariancePop: rename_func("VAR_POP"),
83
+ exp.Variance: rename_func("VAR_SAMP"),
84
+ exp.LogicalAnd: rename_func("BOOL_AND"),
85
+ exp.LogicalOr: rename_func("BOOL_OR"),
86
+ ArrayAgg: _array_agg_sql,
87
+ }
88
+
89
+
90
+ PINOT_DIALECT_CARD = DialectCard(
91
+ engine="Pinot",
92
+ sqlglot_dialect="pinot",
93
+ rules=[
94
+ "Names have three levels: pinot.default.table — pinot is the only catalog",
95
+ "Quote identifiers with double quotes; strings use single quotes",
96
+ "Table and column names are case-insensitive",
97
+ "Time columns are epoch numbers: convert with DATETIMECONVERT, DATETRUNC or ToDateTime",
98
+ "Always filter on the table's time column — that is what prunes segments",
99
+ "Prefer DISTINCTCOUNTHLL(x) over DISTINCTCOUNT(x) on large tables",
100
+ "A type ending in [] is a multi-value column: use ARRAYLENGTH/ARRAY functions, not scalar comparisons",
101
+ "CAST to Pinot types: STRING, LONG, INT, FLOAT, DOUBLE, BOOLEAN, TIMESTAMP, BIG_DECIMAL",
102
+ "Name columns explicitly; SELECT * is rejected",
103
+ "Every query needs a LIMIT; one is added if missing",
104
+ "Joins run on the multi-stage engine and are bounded by a row limit",
105
+ ],
106
+ )