inputlayer-client-dev 0.1.0__py3-none-any.whl → 0.1.0.dev913__py3-none-any.whl

inputlayer/__init__.py

@@ -1,11 +1,7 @@
 """inputlayer - Python Object-Logic Mapper for InputLayer knowledge graph engine."""
 
-# Core types
-from inputlayer.types import Timestamp, Vector, VectorInt8
-
-# Relation system
-from inputlayer.relation import Relation
-from inputlayer.derived import Derived, From, RuleClause
+# Functions (re-export all)
+from inputlayer import functions
 
 # Aggregations
 from inputlayer.aggregations import (
@@ -20,11 +16,13 @@ from inputlayer.aggregations import (
     within_radius,
 )
 
-# Functions (re-export all)
-from inputlayer import functions
+# Auth
+from inputlayer.auth import AclEntry, ApiKeyInfo, UserInfo
 
-# Index
-from inputlayer.index import HnswIndex
+# Client
+from inputlayer.client import InputLayer
+from inputlayer.client_sync import InputLayerSync
+from inputlayer.derived import Derived, From, RuleClause
 
 # Exceptions
 from inputlayer.exceptions import (
@@ -32,11 +30,14 @@ from inputlayer.exceptions import (
     CannotDropError,
     ConnectionError,
     IndexNotFoundError,
+    InputLayerConnectionError,
     InputLayerError,
+    InputLayerPermissionError,
     InternalError,
     KnowledgeGraphExistsError,
     KnowledgeGraphNotFoundError,
     PermissionError,
+    QueryError,
     QueryTimeoutError,
     RelationNotFoundError,
     RuleNotFoundError,
@@ -44,108 +45,119 @@ from inputlayer.exceptions import (
     ValidationError,
 )
 
-# Result
-from inputlayer.result import ResultSet
-
-# Client
-from inputlayer.client import InputLayer
-from inputlayer.client_sync import InputLayerSync
+# Index
+from inputlayer.index import HnswIndex
 
 # Knowledge Graph
 from inputlayer.knowledge_graph import (
     ClearResult,
     ColumnInfo,
+    DebugResult,
     DeleteResult,
-    ExplainResult,
     IndexInfo,
     IndexStats,
     InsertResult,
     KnowledgeGraph,
+    ProofNode,
+    ProofTree,
     RelationDescription,
     RelationInfo,
     RuleInfo,
     ServerStatus,
+    WhyNotResult,
+    WhyResult,
 )
 
-# Auth
-from inputlayer.auth import AclEntry, ApiKeyInfo, UserInfo
-
-# Session
-from inputlayer.session import Session
+# Migrations
+from inputlayer.migrations import Migration
 
 # Notifications
 from inputlayer.notifications import NotificationEvent
 
-# Migrations
-from inputlayer.migrations import Migration
+# Relation system
+from inputlayer.relation import Relation
+
+# Result
+from inputlayer.result import ResultSet
+
+# Session
+from inputlayer.session import Session
+from inputlayer.types import Timestamp, Vector, VectorInt8
 
 __version__ = "0.1.0"
 
 __all__ = [
-    # Types
-    "Vector",
-    "VectorInt8",
-    "Timestamp",
-    # Relation
-    "Relation",
+    "AclEntry",
+    "ApiKeyInfo",
+    "AuthenticationError",
+    "CannotDropError",
+    "ClearResult",
+    "ColumnInfo",
+    "ConnectionError",
+    "DebugResult",
+    "DeleteResult",
     "Derived",
     "From",
-    "RuleClause",
-    # Aggregations
-    "count",
-    "count_distinct",
-    "sum_",
-    "min_",
-    "max_",
-    "avg",
-    "top_k",
-    "top_k_threshold",
-    "within_radius",
-    # Functions
-    "functions",
     # Index
     "HnswIndex",
-    # Exceptions
-    "InputLayerError",
-    "ConnectionError",
-    "AuthenticationError",
-    "SchemaConflictError",
-    "ValidationError",
-    "QueryTimeoutError",
-    "PermissionError",
-    "KnowledgeGraphNotFoundError",
-    "KnowledgeGraphExistsError",
-    "CannotDropError",
-    "RelationNotFoundError",
-    "RuleNotFoundError",
+    "IndexInfo",
     "IndexNotFoundError",
-    "InternalError",
-    # Result
-    "ResultSet",
+    "IndexStats",
     # Client
     "InputLayer",
+    # Exceptions
+    "InputLayerConnectionError",
+    "InputLayerError",
+    "InputLayerPermissionError",
     "InputLayerSync",
+    "InsertResult",
+    "InternalError",
     # KG
     "KnowledgeGraph",
-    "RelationInfo",
+    "KnowledgeGraphExistsError",
+    "KnowledgeGraphNotFoundError",
+    # Migrations
+    "Migration",
+    # Notifications
+    "NotificationEvent",
+    "PermissionError",
+    "ProofNode",
+    "ProofTree",
+    "QueryError",
+    "QueryTimeoutError",
+    # Relation
+    "Relation",
     "RelationDescription",
-    "ColumnInfo",
+    "RelationInfo",
+    "RelationNotFoundError",
+    # Result
+    "ResultSet",
+    "RuleClause",
     "RuleInfo",
-    "IndexInfo",
-    "IndexStats",
-    "InsertResult",
-    "DeleteResult",
-    "ClearResult",
-    "ExplainResult",
+    "RuleNotFoundError",
+    "SchemaConflictError",
     "ServerStatus",
-    # Auth
-    "UserInfo",
-    "ApiKeyInfo",
-    "AclEntry",
     # Session
     "Session",
-    # Notifications
-    "NotificationEvent",
-    # Migrations
-    "Migration",
+    "Timestamp",
+    # Auth
+    "UserInfo",
+    "ValidationError",
+    # Types
+    "Vector",
+    "VectorInt8",
+    "WhyNotResult",
+    "WhyResult",
+    "avg",
+    # Aggregations
+    "count",
+    "count_distinct",
+    # Functions
+    "functions",
+    "max_",
+    "min_",
+    "sum_",
+    "top_k",
+    "top_k_threshold",
+    "within_radius",
 ]

inputlayer/_ast.py

@@ -1,11 +1,10 @@
-"""Internal AST nodes for expression trees compiled to Datalog."""
+"""Internal AST nodes for expression trees compiled to IQL."""
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any
 
-
 # ── Base ──────────────────────────────────────────────────────────────
 
 @dataclass(frozen=True)
@@ -93,7 +92,7 @@ class Comparison(BoolExpr):
 
 @dataclass(frozen=True)
 class And(BoolExpr):
-    """Logical AND of two conditions (Datalog comma)."""
+    """Logical AND of two conditions (IQL comma)."""
     left: BoolExpr
     right: BoolExpr
 
@@ -107,7 +106,7 @@ class Or(BoolExpr):
 
 @dataclass(frozen=True)
 class Not(BoolExpr):
-    """Negation: !relation(X, Y) in Datalog."""
+    """Negation: !relation(X, Y) in IQL."""
     operand: BoolExpr
 
 

inputlayer/_naming.py

@@ -1,4 +1,4 @@
-"""Naming convention utilities: CamelCase ↔ snake_case, column → Datalog variable."""
+"""Naming convention utilities: CamelCase ↔ snake_case, column → IQL variable."""
 
 from __future__ import annotations
 
@@ -33,7 +33,7 @@ def snake_to_camel(name: str) -> str:
 
 
 def column_to_variable(column_name: str) -> str:
-    """Convert a snake_case column name to a Datalog variable (Capitalized).
+    """Convert a snake_case column name to an IQL variable (Capitalized).
 
     Examples:
         id -> Id

inputlayer/_protocol.py

@@ -6,10 +6,9 @@ Matches the AsyncAPI spec at ``docs/spec/asyncapi.yaml``.
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any
 
-
 # ── Client → Server messages ──────────────────────────────────────────
 
 @dataclass(frozen=True)
@@ -79,6 +78,8 @@ class ResultResponse:
     row_provenance: list[str] | None = None
     metadata: dict[str, Any] | None = None
     switched_kg: str | None = None
+    proof_trees: list[dict[str, Any]] | None = None
+    timing_breakdown: dict[str, Any] | None = None
 
 
 @dataclass(frozen=True)
@@ -95,6 +96,8 @@ class ResultStartResponse:
     execution_time_ms: int
     metadata: dict[str, Any] | None = None
     switched_kg: str | None = None
+    proof_trees: list[dict[str, Any]] | None = None
+    timing_breakdown: dict[str, Any] | None = None
 
 
 @dataclass(frozen=True)
@@ -149,7 +152,9 @@ ServerMessage = (
 
 # ── Serialization / Deserialization ───────────────────────────────────
 
-def serialize_message(msg: LoginMessage | AuthenticateMessage | ExecuteMessage | PingMessage) -> str:
+def serialize_message(
+    msg: LoginMessage | AuthenticateMessage | ExecuteMessage | PingMessage,
+) -> str:
     """Serialize a client message to JSON."""
     return msg.to_json()
 
@@ -181,6 +186,8 @@ def deserialize_message(data: str | bytes) -> ServerMessage:
             row_provenance=obj.get("row_provenance"),
             metadata=obj.get("metadata"),
             switched_kg=obj.get("switched_kg"),
+            proof_trees=obj.get("proof_trees"),
+            timing_breakdown=obj.get("timing_breakdown"),
         )
     if msg_type == "error":
         return ErrorResponse(
@@ -195,6 +202,8 @@ def deserialize_message(data: str | bytes) -> ServerMessage:
             execution_time_ms=obj["execution_time_ms"],
             metadata=obj.get("metadata"),
             switched_kg=obj.get("switched_kg"),
+            proof_trees=obj.get("proof_trees"),
+            timing_breakdown=obj.get("timing_breakdown"),
         )
     if msg_type == "result_chunk":
         return ResultChunkResponse(

inputlayer/_proxy.py

@@ -5,11 +5,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from inputlayer._ast import (
-    AggExpr,
     And,
     Arithmetic,
     BoolExpr,
-    Column as AstColumn,
     Comparison,
     Expr,
     InExpr,
@@ -20,6 +18,9 @@ from inputlayer._ast import (
     Or,
     OrderedColumn,
 )
+from inputlayer._ast import (
+    Column as AstColumn,
+)
 
 if TYPE_CHECKING:
     from inputlayer.relation import Relation
@@ -28,10 +29,28 @@ if TYPE_CHECKING:
 class ColumnProxy:
     """Proxy returned by Relation.column_name - builds AST nodes via operators."""
 
-    def __init__(self, relation: str, name: str, *, ref_alias: str | None = None) -> None:
+    def __init__(
+        self,
+        relation: str,
+        name: str,
+        *,
+        ref_alias: str | None = None,
+        relation_cls: type | None = None,
+    ) -> None:
         self._relation = relation
         self._name = name
         self._ref_alias = ref_alias
+        self._relation_cls = relation_cls
+
+    @property
+    def relation_cls(self) -> type | None:
+        """The originating ``Relation`` subclass, if known.
+
+        Set when the proxy was created via attribute access on a
+        ``Relation`` class (``Sale.region``). Stays ``None`` for
+        proxies built from raw column references.
+        """
+        return self._relation_cls
 
     @property
     def relation(self) -> str:

inputlayer/_sync.py

@@ -0,0 +1,104 @@
+"""Sync-from-async bridge using a dedicated background event loop thread.
+
+Safe to call from any context: plain scripts, Jupyter notebooks,
+inside running event loops (FastAPI, LangGraph), etc.
+
+This is the same pattern used by httpx.Client and playwright.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+import threading
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for waiting on coroutine results.
+# None means wait indefinitely (matching httpx behavior).
+DEFAULT_TIMEOUT: float | None = None
+
+
+class _LoopThread:
+    """Background thread owning its own event loop."""
+
+    def __init__(self, timeout: float | None = DEFAULT_TIMEOUT) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self._timeout = timeout
+
+    def _ensure_running(self) -> asyncio.AbstractEventLoop:
+        # Fast path: already running (no lock needed for a quick read -
+        # the lock below handles the actual creation race).
+        loop = self._loop
+        if loop is not None and loop.is_running():
+            return loop
+        with self._lock:
+            # Re-check under lock to avoid creating a duplicate.
+            if self._loop is not None and self._loop.is_running():
+                return self._loop
+            new_loop = asyncio.new_event_loop()
+            thread = threading.Thread(
+                target=new_loop.run_forever,
+                daemon=True,
+                name="inputlayer-sync",
+            )
+            thread.start()
+            self._loop = new_loop
+            self._thread = thread
+            return new_loop
+
+    def run(self, coro: Coroutine[Any, Any, T]) -> T:
+        """Submit a coroutine to the background loop and block until done."""
+        if threading.current_thread() is self._thread:
+            raise RuntimeError(
+                "Cannot call run_sync from the background event loop thread "
+                "- use 'await' instead. This would deadlock."
+            )
+        loop = self._ensure_running()
+        future = asyncio.run_coroutine_threadsafe(coro, loop)
+        return future.result(timeout=self._timeout)
+
+    def shutdown(self) -> None:
+        """Stop the background loop and join the thread."""
+        with self._lock:
+            loop = self._loop
+            thread = self._thread
+            self._loop = None
+            self._thread = None
+
+        if loop is not None and loop.is_running():
+            try:
+                loop.call_soon_threadsafe(loop.stop)
+            except RuntimeError:
+                # Loop already closed or stopping - not an error.
+                logger.debug("Loop already stopped during shutdown")
+        if thread is not None:
+            thread.join(timeout=5)
+            if thread.is_alive():
+                logger.warning(
+                    "inputlayer-sync thread did not stop within 5 s; "
+                    "it will be cleaned up at process exit (daemon thread)."
+                )
+        if loop is not None and not loop.is_closed():
+            loop.close()
+
+
+_default_thread = _LoopThread()
+atexit.register(_default_thread.shutdown)
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine from synchronous code. Always safe.
+
+    Uses a module-level background thread with its own event loop,
+    so it works even when the caller already has a running loop
+    (Jupyter, FastAPI, LangGraph, etc.).
+    """
+    return _default_thread.run(coro)

inputlayer/aggregations.py

@@ -1,4 +1,4 @@
-"""Aggregation functions that compile to Datalog aggregates."""
+"""Aggregation functions that compile to IQL aggregates."""
 
 from __future__ import annotations
 
@@ -20,7 +20,7 @@ def _to_expr(col: ColumnProxy | Expr) -> Expr:
 def count(column: ColumnProxy | type[Relation] | None = None) -> AggExpr:
     """Count rows. If a column is given, counts non-null values.
 
-    Datalog: count<Var>
+    IQL: count<Var>
     """
     if column is None or (isinstance(column, type)):
         # count(*) - needs at least one column from the body
@@ -31,7 +31,7 @@ def count(column: ColumnProxy | type[Relation] | None = None) -> AggExpr:
 def count_distinct(column: ColumnProxy) -> AggExpr:
     """Count distinct values.
 
-    Datalog: count_distinct<Var>
+    IQL: count_distinct<Var>
     """
     return AggExpr(func="count_distinct", column=_to_expr(column))
 
@@ -39,7 +39,7 @@ def count_distinct(column: ColumnProxy) -> AggExpr:
 def sum_(column: ColumnProxy) -> AggExpr:
     """Sum numeric values.
 
-    Datalog: sum<Var>
+    IQL: sum<Var>
     """
     return AggExpr(func="sum", column=_to_expr(column))
 
@@ -47,7 +47,7 @@ def sum_(column: ColumnProxy) -> AggExpr:
 def min_(column: ColumnProxy) -> AggExpr:
     """Minimum value.
 
-    Datalog: min<Var>
+    IQL: min<Var>
     """
     return AggExpr(func="min", column=_to_expr(column))
 
@@ -55,7 +55,7 @@ def min_(column: ColumnProxy) -> AggExpr:
 def max_(column: ColumnProxy) -> AggExpr:
     """Maximum value.
 
-    Datalog: max<Var>
+    IQL: max<Var>
     """
     return AggExpr(func="max", column=_to_expr(column))
 
@@ -63,7 +63,7 @@ def max_(column: ColumnProxy) -> AggExpr:
 def avg(column: ColumnProxy) -> AggExpr:
     """Average value.
 
-    Datalog: avg<Var>
+    IQL: avg<Var>
     """
     return AggExpr(func="avg", column=_to_expr(column))
 
@@ -76,7 +76,7 @@ def top_k(
 ) -> AggExpr:
     """Top-K aggregation with ordering.
 
-    Datalog: top_k<k, Passthrough..., OrderCol:desc>
+    IQL: top_k<k, Passthrough..., OrderCol:desc>
     """
     return AggExpr(
         func="top_k",
@@ -96,7 +96,7 @@ def top_k_threshold(
 ) -> AggExpr:
     """Top-K with threshold aggregation.
 
-    Datalog: top_k_threshold<k, threshold, Passthrough..., OrderCol:desc>
+    IQL: top_k_threshold<k, threshold, Passthrough..., OrderCol:desc>
     """
     return AggExpr(
         func="top_k_threshold",
@@ -115,7 +115,7 @@ def within_radius(
 ) -> AggExpr:
     """Within-radius aggregation.
 
-    Datalog: within_radius<r, Passthrough..., DistCol:asc>
+    IQL: within_radius<r, Passthrough..., DistCol:asc>
     """
     return AggExpr(
         func="within_radius",

inputlayer/auth.py

@@ -1,9 +1,40 @@
-"""Authentication helpers - data classes and meta-command compilation for user/key/ACL management."""
+"""Authentication helpers.
+
+Data classes and meta-command compilation for user/key/ACL management.
+"""
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 
+_SAFE_IDENTIFIER = re.compile(r"^[A-Za-z0-9_.-]+$")
+# Passwords allow more characters but no whitespace or control chars
+_SAFE_PASSWORD = re.compile(r"^\S+$")
+
+
+def _validate_identifier(value: str, name: str) -> str:
+    """Validate that a value is safe for use in meta-commands."""
+    if not value:
+        raise ValueError(f"{name} must not be empty")
+    if not _SAFE_IDENTIFIER.match(value):
+        raise ValueError(
+            f"{name} contains invalid characters: {value!r}. "
+            f"Only letters, digits, underscores, dots, and hyphens are allowed."
+        )
+    return value
+
+
+def _validate_password(value: str, name: str) -> str:
+    """Validate a password for use in space-delimited meta-commands."""
+    if not value:
+        raise ValueError(f"{name} must not be empty")
+    if not _SAFE_PASSWORD.match(value):
+        raise ValueError(
+            f"{name} must not contain whitespace: {value!r}"
+        )
+    return value
+
 
 @dataclass(frozen=True)
 class UserInfo:
@@ -27,18 +58,26 @@ class AclEntry:
 
 
 def compile_create_user(username: str, password: str, role: str = "viewer") -> str:
+    _validate_identifier(username, "username")
+    _validate_password(password, "password")
+    _validate_identifier(role, "role")
     return f".user create {username} {password} {role}"
 
 
 def compile_drop_user(username: str) -> str:
+    _validate_identifier(username, "username")
     return f".user drop {username}"
 
 
 def compile_set_password(username: str, new_password: str) -> str:
+    _validate_identifier(username, "username")
+    _validate_password(new_password, "new_password")
     return f".user password {username} {new_password}"
 
 
 def compile_set_role(username: str, role: str) -> str:
+    _validate_identifier(username, "username")
+    _validate_identifier(role, "role")
     return f".user role {username} {role}"
 
 
@@ -47,6 +86,7 @@ def compile_list_users() -> str:
 
 
 def compile_create_api_key(label: str) -> str:
+    _validate_identifier(label, "label")
     return f".apikey create {label}"
 
 
@@ -55,16 +95,23 @@ def compile_list_api_keys() -> str:
 
 
 def compile_revoke_api_key(label: str) -> str:
+    _validate_identifier(label, "label")
     return f".apikey revoke {label}"
 
 
 def compile_grant_access(kg: str, username: str, role: str) -> str:
+    _validate_identifier(kg, "kg")
+    _validate_identifier(username, "username")
+    _validate_identifier(role, "role")
     return f".kg acl grant {kg} {username} {role}"
 
 
 def compile_revoke_access(kg: str, username: str) -> str:
+    _validate_identifier(kg, "kg")
+    _validate_identifier(username, "username")
     return f".kg acl revoke {kg} {username}"
 
 
 def compile_list_acl(kg: str) -> str:
+    _validate_identifier(kg, "kg")
     return f".kg acl list {kg}"