arango-query-core 0.1.0__py3-none-any.whl

arango_query_core/__init__.py

@@ -0,0 +1,46 @@
+from .aql import AqlFragment, AqlQuery
+from .errors import CoreError
+from .exec import AqlExecutor, explain_aql, safe_execute
+from .extensions import ExtensionPolicy, ExtensionRegistry
+from .mapping import (
+    COLLECTION_NAME_RE,
+    IndexInfo,
+    MappingBundle,
+    MappingResolver,
+    MappingSource,
+    PropertyInfo,
+    RelationshipStats,
+    is_valid_collection_name,
+    mapping_from_wire_dict,
+    mapping_hash,
+)
+from .owl_turtle import mapping_to_turtle, turtle_to_mapping
+
+try:
+    from .owl_rdflib import parse_owl_with_rdflib
+except ImportError:
+    parse_owl_with_rdflib = None  # type: ignore[assignment]
+
+__all__ = [
+    "COLLECTION_NAME_RE",
+    "AqlExecutor",
+    "AqlFragment",
+    "AqlQuery",
+    "CoreError",
+    "ExtensionPolicy",
+    "ExtensionRegistry",
+    "explain_aql",
+    "safe_execute",
+    "IndexInfo",
+    "MappingBundle",
+    "MappingResolver",
+    "MappingSource",
+    "PropertyInfo",
+    "RelationshipStats",
+    "is_valid_collection_name",
+    "mapping_from_wire_dict",
+    "mapping_hash",
+    "mapping_to_turtle",
+    "parse_owl_with_rdflib",
+    "turtle_to_mapping",
+]

arango_query_core/aql.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import CoreError
+
+
+@dataclass
+class AqlFragment:
+    text: str
+    bind_vars: dict[str, Any] = field(default_factory=dict)
+
+    def __add__(self, other: AqlFragment) -> AqlFragment:
+        if not isinstance(other, AqlFragment):
+            return NotImplemented
+        text = self.text.rstrip()
+        other_text = other.text.lstrip()
+        joined = (text + "\n" + other_text).strip() if text and other_text else (text + other_text).strip()
+
+        merged: dict[str, Any] = dict(self.bind_vars)
+        for k, v in other.bind_vars.items():
+            if k in merged and merged[k] != v:
+                raise CoreError(f"Bind var collision for {k!r}", code="BIND_VAR_COLLISION")
+            merged[k] = v
+        return AqlFragment(text=joined, bind_vars=merged)
+
+
+@dataclass(frozen=True)
+class AqlQuery:
+    text: str
+    bind_vars: dict[str, Any]
+    debug: dict[str, Any] | None = None
+    warnings: tuple[str, ...] = ()

arango_query_core/errors.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+
+class CoreError(Exception):
+    def __init__(self, message: str, *, code: str = "CORE_ERROR"):
+        super().__init__(message)
+        self.code = code

arango_query_core/exec.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .aql import AqlQuery
+
+
+def _aql_references_bindvar(aql: str, name: str) -> bool:
+    """Whether *aql* references the value bind parameter ``@name``.
+
+    ArangoDB rejects a query (``[ERR 1552] bind parameter '<name>' was
+    not declared in the query``) when ``bind_vars`` carries a key the
+    query text never uses. The Layer-6 session-spread must therefore
+    add ``tenantId`` / ``tenantKey`` **only** when the AQL actually
+    references them — otherwise a perfectly safe global / satellite-only
+    read (e.g. ``FOR c IN Country RETURN c``) explodes at EXPLAIN time
+    just because the session injected an unused tenant bind.
+
+    Matches a single-``@`` *value* reference (``@tenantId``) and
+    deliberately ignores the doubled *collection* form (``@@tenantId``)
+    — tenant scope binds are always value binds. The name boundary
+    stops ``@tenantId`` from matching a longer identifier such as
+    ``@tenantIdentifier``.
+
+    This is a textual heuristic, mirroring Layer 4's textual splice
+    approach. A false positive (``@tenantId`` appearing only inside an
+    AQL comment or string literal) would re-introduce ERR 1552, but the
+    transpiler and Layer 3/4 only ever emit the token in real predicate
+    positions, so the heuristic is safe for produced AQL.
+    """
+    return re.search(r"(?<![@\w])@" + re.escape(name) + r"(?![\w])", aql) is not None
+
+
+@dataclass
+class AqlExecutor:
+    db: Any  # python-arango Database
+
+    def execute(self, query: AqlQuery, *, batch_size: int | None = None, **kwargs: Any) -> Any:
+        aql = self.db.aql
+        return aql.execute(query.text, bind_vars=query.bind_vars, batch_size=batch_size, **kwargs)
+
+
+def safe_execute(
+    *,
+    db: Any,
+    aql: str,
+    client_bind_vars: dict[str, Any] | None,
+    session: Any,
+    validator: Callable[..., None],
+    manifest: Any,
+    sharding_profile: dict[str, Any] | None,
+    collection_to_entity: dict[str, str] | None = None,
+    execute_kwargs: dict[str, Any] | None = None,
+    admin_bypass: bool = False,
+    bypass_reason: str = "",
+) -> tuple[Any, dict[str, Any]]:
+    """Layer 6 — execute AQL only after Layer 5 has certified the plan.
+
+    Implements the contract from ``docs/multitenant_prd.md`` §9 / Wave 7
+    part 4. The bind-var spread order is load-bearing:
+
+    .. code-block:: python
+
+        bind_vars = {
+            **client_bind_vars,
+            "tenantId": session.tenant_id,
+            "tenantKey": session.tenant_key,
+        }
+
+    The session value silently overrides any caller-supplied
+    ``tenantId`` / ``tenantKey``. Layer 5 (``validator``) then
+    verifies the bind-var matches the session — closing T7 (bind-var
+    override) by construction.
+
+    The session binds are spread **only when the AQL references the
+    corresponding ``@tenantId`` / ``@tenantKey`` parameter**. ArangoDB
+    refuses a query that declares a bind value it never uses
+    (``[ERR 1552] bind parameter '<name>' was not declared in the
+    query``), so unconditionally injecting the session tenant would
+    blow up every safe global / satellite-only read at EXPLAIN time.
+    A query that *does* reference the tenant bind always has the
+    session value win; a client-supplied ``tenantId`` on a query that
+    never uses ``@tenantId`` is inert and is dropped (it cannot affect
+    results and would only trip ERR 1552).
+
+    Returns ``(cursor, bind_vars)`` so the caller can echo the final
+    bind vars back to the UI for transparency (§9.2). The validator is
+    injected rather than imported here so ``arango_query_core`` stays
+    free of an ``arango_cypher`` reverse dependency.
+
+    Raises whatever the validator raises — typically
+    ``arango_cypher.tenant_plan_validator.TenantScopeViolation`` — on
+    refusal. The execute never runs in that case.
+    """
+    if session is None:
+        raise PermissionError("safe_execute: no authenticated session; cannot bind tenant context")
+    bind_vars = dict(client_bind_vars or {})
+    if _aql_references_bindvar(aql, "tenantId"):
+        bind_vars["tenantId"] = getattr(session, "tenant_id", None)
+    else:
+        bind_vars.pop("tenantId", None)
+    if _aql_references_bindvar(aql, "tenantKey"):
+        bind_vars["tenantKey"] = getattr(session, "tenant_key", None)
+    else:
+        bind_vars.pop("tenantKey", None)
+
+    validator(
+        db=db,
+        aql=aql,
+        bind_vars=bind_vars,
+        manifest=manifest,
+        sharding_profile=sharding_profile,
+        collection_to_entity=collection_to_entity,
+        session=session,
+        admin_bypass=admin_bypass,
+        bypass_reason=bypass_reason,
+    )
+
+    cursor = db.aql.execute(aql, bind_vars=bind_vars, **(execute_kwargs or {}))
+    return cursor, bind_vars
+
+
+def explain_aql(
+    db: Any,
+    aql: str,
+    bind_vars: dict[str, Any] | None = None,
+) -> tuple[bool, str]:
+    """Plan the query via ``POST /_api/explain`` without executing it.
+
+    Returns ``(ok, error_message)``. On success, *error_message* is the
+    empty string. On failure, it's a short, LLM-friendly description of
+    the planner error — short enough to paste back into a retry prompt,
+    and stripped of stack traces, HTTP payloads, and sensitive detail.
+
+    This is the hook WP-25.3 uses to catch semantic errors
+    (non-existent collections/properties, invalid traversal directions)
+    that ANTLR's grammar-only check happily waves through.  We never
+    execute the query — the ``explain`` endpoint only plans it, so there
+    is no cost to row materialization.
+
+    Safe to call against any read-only or read-write database: the AQL
+    is only planned, never run.  Caller is responsible for ensuring
+    *db* is a valid python-arango database handle.
+    """
+    bv = dict(bind_vars or {})
+    try:
+        result = db.aql.explain(aql, bind_vars=bv)
+    except Exception as exc:
+        return False, _summarize_explain_error(exc)
+
+    if isinstance(result, dict) and result.get("error"):
+        msg = str(result.get("errorMessage") or result.get("error") or "EXPLAIN failed")
+        return False, msg[:500]
+    return True, ""
+
+
+def _summarize_explain_error(exc: BaseException) -> str:
+    """Collapse a python-arango / server error into a single short line.
+
+    python-arango raises ``AQLQueryExplainError`` or ``ArangoServerError``
+    whose ``str()`` can include multi-line HTTP payloads and stack frames.
+    We strip to the most informative line for LLM feedback.
+    """
+    msg = str(exc) or exc.__class__.__name__
+    msg = msg.splitlines()[0] if "\n" in msg else msg
+    msg = msg.strip()
+    if len(msg) > 500:
+        msg = msg[:497] + "..."
+    return msg

arango_query_core/extensions.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import CoreError
+
+
+@dataclass(frozen=True)
+class ExtensionPolicy:
+    enabled: bool = False
+    allowlist: set[str] | None = None
+    denylist: set[str] | None = None
+
+    def check_allowed(self, name: str) -> None:
+        if not self.enabled:
+            raise CoreError(f"Extensions are disabled (attempted: {name})", code="EXTENSIONS_DISABLED")
+        if self.denylist and name in self.denylist:
+            raise CoreError(f"Extension denied: {name}", code="EXTENSION_DENIED")
+        if self.allowlist is not None and name not in self.allowlist:
+            raise CoreError(f"Extension not in allowlist: {name}", code="EXTENSION_NOT_ALLOWED")
+
+
+FunctionCompiler = Callable[[Any, Any], Any]
+ProcedureCompiler = Callable[[Any, Any], Any]
+
+
+class ExtensionRegistry:
+    def __init__(self, *, policy: ExtensionPolicy | None = None):
+        self.policy = policy or ExtensionPolicy()
+        self._functions: dict[str, FunctionCompiler] = {}
+        self._procedures: dict[str, ProcedureCompiler] = {}
+
+    def register_function(self, name: str, compiler: FunctionCompiler) -> None:
+        self._functions[name] = compiler
+
+    def register_procedure(self, name: str, compiler: ProcedureCompiler) -> None:
+        self._procedures[name] = compiler
+
+    def compile_function(self, name: str, call_ast: Any, ctx: Any) -> Any:
+        self.policy.check_allowed(name)
+        fn = self._functions.get(name)
+        if not fn:
+            raise CoreError(f"Unknown extension function: {name}", code="UNKNOWN_EXTENSION")
+        return fn(call_ast, ctx)
+
+    def compile_procedure(self, name: str, call_ast: Any, ctx: Any) -> Any:
+        self.policy.check_allowed(name)
+        proc = self._procedures.get(name)
+        if not proc:
+            raise CoreError(f"Unknown extension procedure: {name}", code="UNKNOWN_EXTENSION")
+        return proc(call_ast, ctx)