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

inputlayer/_proxy.py

@@ -0,0 +1,244 @@
+"""Column proxy objects for building expression ASTs via operator overloading."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from inputlayer._ast import (
+    AggExpr,
+    And,
+    Arithmetic,
+    BoolExpr,
+    Column as AstColumn,
+    Comparison,
+    Expr,
+    InExpr,
+    Literal,
+    MatchExpr,
+    NegatedIn,
+    Not,
+    Or,
+    OrderedColumn,
+)
+
+if TYPE_CHECKING:
+    from inputlayer.relation import Relation
+
+
+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:
+        self._relation = relation
+        self._name = name
+        self._ref_alias = ref_alias
+
+    @property
+    def relation(self) -> str:
+        return self._relation
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def ref_alias(self) -> str | None:
+        return self._ref_alias
+
+    def _to_ast(self) -> AstColumn:
+        return AstColumn(self._relation, self._name, self._ref_alias)
+
+    # ── Comparison operators → BoolExpr ───────────────────────────────
+
+    def __eq__(self, other: Any) -> Comparison:  # type: ignore[override]
+        return Comparison("=", self._to_ast(), _wrap(other))
+
+    def __ne__(self, other: Any) -> Comparison:  # type: ignore[override]
+        return Comparison("!=", self._to_ast(), _wrap(other))
+
+    def __lt__(self, other: Any) -> Comparison:
+        return Comparison("<", self._to_ast(), _wrap(other))
+
+    def __le__(self, other: Any) -> Comparison:
+        return Comparison("<=", self._to_ast(), _wrap(other))
+
+    def __gt__(self, other: Any) -> Comparison:
+        return Comparison(">", self._to_ast(), _wrap(other))
+
+    def __ge__(self, other: Any) -> Comparison:
+        return Comparison(">=", self._to_ast(), _wrap(other))
+
+    # ── Arithmetic operators → Expr ───────────────────────────────────
+
+    def __add__(self, other: Any) -> Arithmetic:
+        return Arithmetic("+", self._to_ast(), _wrap(other))
+
+    def __radd__(self, other: Any) -> Arithmetic:
+        return Arithmetic("+", _wrap(other), self._to_ast())
+
+    def __sub__(self, other: Any) -> Arithmetic:
+        return Arithmetic("-", self._to_ast(), _wrap(other))
+
+    def __rsub__(self, other: Any) -> Arithmetic:
+        return Arithmetic("-", _wrap(other), self._to_ast())
+
+    def __mul__(self, other: Any) -> Arithmetic:
+        return Arithmetic("*", self._to_ast(), _wrap(other))
+
+    def __rmul__(self, other: Any) -> Arithmetic:
+        return Arithmetic("*", _wrap(other), self._to_ast())
+
+    def __truediv__(self, other: Any) -> Arithmetic:
+        return Arithmetic("/", self._to_ast(), _wrap(other))
+
+    def __rtruediv__(self, other: Any) -> Arithmetic:
+        return Arithmetic("/", _wrap(other), self._to_ast())
+
+    def __mod__(self, other: Any) -> Arithmetic:
+        return Arithmetic("%", self._to_ast(), _wrap(other))
+
+    def __rmod__(self, other: Any) -> Arithmetic:
+        return Arithmetic("%", _wrap(other), self._to_ast())
+
+    # ── Negation (bitwise NOT used as logical NOT) ────────────────────
+
+    def __invert__(self) -> ColumnProxy:
+        """Returns a negated proxy (for ~Relation.col.in_(...) patterns)."""
+        return _NegatedColumnProxy(self)
+
+    # ── Membership ────────────────────────────────────────────────────
+
+    def in_(self, other: ColumnProxy) -> InExpr:
+        """Test if this column's value appears in another relation's column."""
+        return InExpr(self._to_ast(), other._to_ast())
+
+    # ── Ordering ──────────────────────────────────────────────────────
+
+    def asc(self) -> OrderedColumn:
+        return OrderedColumn(self._to_ast(), descending=False)
+
+    def desc(self) -> OrderedColumn:
+        return OrderedColumn(self._to_ast(), descending=True)
+
+    # ── Multi-column match ────────────────────────────────────────────
+
+    def matches(
+        self, relation: type[Relation], on: dict[str, str]
+    ) -> MatchExpr:
+        """Check if columns match entries in another relation."""
+        from inputlayer.relation import Relation as RelBase
+
+        rel_name = RelBase._resolve_name(relation)
+        bindings = {}
+        for target_col, source_col_name in on.items():
+            # source_col_name refers to a column on self's relation
+            bindings[target_col] = AstColumn(self._relation, source_col_name, self._ref_alias)
+        return MatchExpr(rel_name, bindings, negated=False)
+
+    def __repr__(self) -> str:
+        if self._ref_alias:
+            return f"ColumnProxy({self._ref_alias}.{self._name})"
+        return f"ColumnProxy({self._relation}.{self._name})"
+
+
+class _NegatedColumnProxy(ColumnProxy):
+    """Wrapper returned by ~col to flip .in_() to NegatedIn."""
+
+    def __init__(self, inner: ColumnProxy) -> None:
+        super().__init__(inner._relation, inner._name, ref_alias=inner._ref_alias)
+        self._inner = inner
+
+    def in_(self, other: ColumnProxy) -> NegatedIn:  # type: ignore[override]
+        return NegatedIn(self._inner._to_ast(), other._to_ast())
+
+    def matches(  # type: ignore[override]
+        self, relation: type[Relation], on: dict[str, str]
+    ) -> MatchExpr:
+        from inputlayer.relation import Relation as RelBase
+
+        rel_name = RelBase._resolve_name(relation)
+        bindings = {}
+        for target_col, source_col_name in on.items():
+            bindings[target_col] = AstColumn(self._relation, source_col_name, self._ref_alias)
+        return MatchExpr(rel_name, bindings, negated=True)
+
+
+class RelationProxy:
+    """Proxy object passed to where/on lambdas. Attribute access returns ColumnProxy."""
+
+    def __init__(self, relation_name: str, *, ref_alias: str | None = None) -> None:
+        self._relation_name = relation_name
+        self._ref_alias = ref_alias
+
+    def __getattr__(self, name: str) -> ColumnProxy:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return ColumnProxy(self._relation_name, name, ref_alias=self._ref_alias)
+
+    def __repr__(self) -> str:
+        if self._ref_alias:
+            return f"RelationProxy({self._ref_alias})"
+        return f"RelationProxy({self._relation_name})"
+
+
+class RelationRef:
+    """Independent reference to a relation for self-joins. Created by Relation.refs(n)."""
+
+    def __init__(self, relation_cls: type[Relation], alias: str) -> None:
+        self._relation_cls = relation_cls
+        self._alias = alias
+        from inputlayer.relation import Relation as RelBase
+
+        self._relation_name = RelBase._resolve_name(relation_cls)
+
+    @property
+    def alias(self) -> str:
+        return self._alias
+
+    @property
+    def relation_name(self) -> str:
+        return self._relation_name
+
+    @property
+    def relation_cls(self) -> type[Relation]:
+        return self._relation_cls
+
+    def __getattr__(self, name: str) -> ColumnProxy:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return ColumnProxy(self._relation_name, name, ref_alias=self._alias)
+
+    def __repr__(self) -> str:
+        return f"RelationRef({self._relation_name} as {self._alias})"
+
+
+# ── BoolExpr combinator operators ─────────────────────────────────────
+# Monkey-patch & | ~ on BoolExpr subclasses so cond1 & cond2 works.
+
+def _bool_and(self: BoolExpr, other: BoolExpr) -> And:
+    return And(self, other)
+
+
+def _bool_or(self: BoolExpr, other: BoolExpr) -> Or:
+    return Or(self, other)
+
+
+def _bool_not(self: BoolExpr) -> Not:
+    return Not(self)
+
+
+for _cls in (Comparison, And, Or, Not, InExpr, NegatedIn, MatchExpr):
+    _cls.__and__ = _bool_and  # type: ignore[attr-defined]
+    _cls.__or__ = _bool_or  # type: ignore[attr-defined]
+    _cls.__invert__ = _bool_not  # type: ignore[attr-defined]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+def _wrap(value: Any) -> Expr:
+    """Wrap a raw Python value or proxy into an AST Expr."""
+    if isinstance(value, ColumnProxy):
+        return value._to_ast()
+    if isinstance(value, Expr):
+        return value
+    return Literal(value)

inputlayer/aggregations.py

@@ -0,0 +1,126 @@
+"""Aggregation functions that compile to Datalog aggregates."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from inputlayer._ast import AggExpr, Expr
+from inputlayer._proxy import ColumnProxy
+
+if TYPE_CHECKING:
+    from inputlayer.relation import Relation
+
+
+def _to_expr(col: ColumnProxy | Expr) -> Expr:
+    if isinstance(col, ColumnProxy):
+        return col._to_ast()
+    return col
+
+
+def count(column: ColumnProxy | type[Relation] | None = None) -> AggExpr:
+    """Count rows. If a column is given, counts non-null values.
+
+    Datalog: count<Var>
+    """
+    if column is None or (isinstance(column, type)):
+        # count(*) - needs at least one column from the body
+        return AggExpr(func="count", column=None)
+    return AggExpr(func="count", column=_to_expr(column))
+
+
+def count_distinct(column: ColumnProxy) -> AggExpr:
+    """Count distinct values.
+
+    Datalog: count_distinct<Var>
+    """
+    return AggExpr(func="count_distinct", column=_to_expr(column))
+
+
+def sum_(column: ColumnProxy) -> AggExpr:
+    """Sum numeric values.
+
+    Datalog: sum<Var>
+    """
+    return AggExpr(func="sum", column=_to_expr(column))
+
+
+def min_(column: ColumnProxy) -> AggExpr:
+    """Minimum value.
+
+    Datalog: min<Var>
+    """
+    return AggExpr(func="min", column=_to_expr(column))
+
+
+def max_(column: ColumnProxy) -> AggExpr:
+    """Maximum value.
+
+    Datalog: max<Var>
+    """
+    return AggExpr(func="max", column=_to_expr(column))
+
+
+def avg(column: ColumnProxy) -> AggExpr:
+    """Average value.
+
+    Datalog: avg<Var>
+    """
+    return AggExpr(func="avg", column=_to_expr(column))
+
+
+def top_k(
+    k: int,
+    *passthrough: ColumnProxy,
+    order_by: ColumnProxy,
+    desc: bool = True,
+) -> AggExpr:
+    """Top-K aggregation with ordering.
+
+    Datalog: top_k<k, Passthrough..., OrderCol:desc>
+    """
+    return AggExpr(
+        func="top_k",
+        params=(k,),
+        passthrough=tuple(_to_expr(p) for p in passthrough),
+        order_column=_to_expr(order_by),
+        desc=desc,
+    )
+
+
+def top_k_threshold(
+    k: int,
+    threshold: float,
+    *passthrough: ColumnProxy,
+    order_by: ColumnProxy,
+    desc: bool = True,
+) -> AggExpr:
+    """Top-K with threshold aggregation.
+
+    Datalog: top_k_threshold<k, threshold, Passthrough..., OrderCol:desc>
+    """
+    return AggExpr(
+        func="top_k_threshold",
+        params=(k, threshold),
+        passthrough=tuple(_to_expr(p) for p in passthrough),
+        order_column=_to_expr(order_by),
+        desc=desc,
+    )
+
+
+def within_radius(
+    max_distance: float,
+    *passthrough: ColumnProxy,
+    distance: ColumnProxy | Expr,
+    asc: bool = True,
+) -> AggExpr:
+    """Within-radius aggregation.
+
+    Datalog: within_radius<r, Passthrough..., DistCol:asc>
+    """
+    return AggExpr(
+        func="within_radius",
+        params=(max_distance,),
+        passthrough=tuple(_to_expr(p) for p in passthrough),
+        order_column=_to_expr(distance),
+        desc=not asc,
+    )

inputlayer/auth.py

@@ -0,0 +1,70 @@
+"""Authentication helpers - data classes and meta-command compilation for user/key/ACL management."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class UserInfo:
+    username: str
+    role: str
+
+
+@dataclass(frozen=True)
+class ApiKeyInfo:
+    label: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class AclEntry:
+    username: str
+    role: str
+
+
+# ── Meta command compilation ──────────────────────────────────────────
+
+
+def compile_create_user(username: str, password: str, role: str = "viewer") -> str:
+    return f".user create {username} {password} {role}"
+
+
+def compile_drop_user(username: str) -> str:
+    return f".user drop {username}"
+
+
+def compile_set_password(username: str, new_password: str) -> str:
+    return f".user password {username} {new_password}"
+
+
+def compile_set_role(username: str, role: str) -> str:
+    return f".user role {username} {role}"
+
+
+def compile_list_users() -> str:
+    return ".user list"
+
+
+def compile_create_api_key(label: str) -> str:
+    return f".apikey create {label}"
+
+
+def compile_list_api_keys() -> str:
+    return ".apikey list"
+
+
+def compile_revoke_api_key(label: str) -> str:
+    return f".apikey revoke {label}"
+
+
+def compile_grant_access(kg: str, username: str, role: str) -> str:
+    return f".kg acl grant {kg} {username} {role}"
+
+
+def compile_revoke_access(kg: str, username: str) -> str:
+    return f".kg acl revoke {kg} {username}"
+
+
+def compile_list_acl(kg: str) -> str:
+    return f".kg acl list {kg}"

inputlayer/client.py

@@ -0,0 +1,178 @@
+"""InputLayer - top-level async client."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Callable
+
+from inputlayer.auth import (
+    AclEntry,
+    ApiKeyInfo,
+    UserInfo,
+    compile_create_api_key,
+    compile_create_user,
+    compile_drop_user,
+    compile_list_api_keys,
+    compile_list_users,
+    compile_revoke_api_key,
+    compile_set_password,
+    compile_set_role,
+)
+from inputlayer.connection import Connection
+from inputlayer.knowledge_graph import KnowledgeGraph
+from inputlayer.notifications import NotificationDispatcher, NotificationEvent
+
+
+class InputLayer:
+    """Async client for InputLayer knowledge graph engine.
+
+    Usage::
+
+        async with InputLayer("ws://localhost:8080/ws", username="admin", password="admin") as il:
+            kg = il.knowledge_graph("default")
+            await kg.define(Employee)
+            await kg.insert(Employee(id=1, name="Alice", department="eng", salary=120000.0, active=True))
+            result = await kg.query(Employee)
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        api_key: str | None = None,
+        auto_reconnect: bool = True,
+        reconnect_delay: float = 1.0,
+        max_reconnect_attempts: int = 10,
+        initial_kg: str | None = None,
+        last_seq: int | None = None,
+    ) -> None:
+        self._conn = Connection(
+            url,
+            username=username,
+            password=password,
+            api_key=api_key,
+            auto_reconnect=auto_reconnect,
+            reconnect_delay=reconnect_delay,
+            max_reconnect_attempts=max_reconnect_attempts,
+            initial_kg=initial_kg,
+            last_seq=last_seq,
+        )
+        self._kgs: dict[str, KnowledgeGraph] = {}
+
+    # ── Connection lifecycle ──────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Connect and authenticate."""
+        await self._conn.connect()
+
+    async def close(self) -> None:
+        """Close the connection."""
+        await self._conn.close()
+
+    async def __aenter__(self) -> InputLayer:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # ── Properties ────────────────────────────────────────────────────
+
+    @property
+    def connected(self) -> bool:
+        return self._conn.connected
+
+    @property
+    def session_id(self) -> str | None:
+        return self._conn.session_id
+
+    @property
+    def server_version(self) -> str | None:
+        return self._conn.server_version
+
+    @property
+    def role(self) -> str | None:
+        return self._conn.role
+
+    @property
+    def last_seq(self) -> int:
+        return self._conn.last_seq
+
+    # ── KG management ─────────────────────────────────────────────────
+
+    def knowledge_graph(self, name: str, *, create: bool = True) -> KnowledgeGraph:
+        """Get a KnowledgeGraph handle. Switches the session's active KG."""
+        if name not in self._kgs:
+            self._kgs[name] = KnowledgeGraph(name, self._conn)
+        return self._kgs[name]
+
+    async def list_knowledge_graphs(self) -> list[str]:
+        """List all knowledge graphs."""
+        result = await self._conn.execute(".kg list")
+        return [row[0] for row in result.rows] if result.rows else []
+
+    async def drop_knowledge_graph(self, name: str) -> None:
+        """Drop a knowledge graph."""
+        await self._conn.execute(f".kg drop {name}")
+        self._kgs.pop(name, None)
+
+    # ── User management ───────────────────────────────────────────────
+
+    async def create_user(self, username: str, password: str, role: str = "viewer") -> None:
+        await self._conn.execute(compile_create_user(username, password, role))
+
+    async def drop_user(self, username: str) -> None:
+        await self._conn.execute(compile_drop_user(username))
+
+    async def set_password(self, username: str, new_password: str) -> None:
+        await self._conn.execute(compile_set_password(username, new_password))
+
+    async def set_role(self, username: str, role: str) -> None:
+        await self._conn.execute(compile_set_role(username, role))
+
+    async def list_users(self) -> list[UserInfo]:
+        result = await self._conn.execute(compile_list_users())
+        return [
+            UserInfo(username=row[0], role=row[1])
+            for row in result.rows
+            if len(row) >= 2
+        ]
+
+    # ── API key management ────────────────────────────────────────────
+
+    async def create_api_key(self, label: str) -> str:
+        """Create an API key. Returns the key string."""
+        result = await self._conn.execute(compile_create_api_key(label))
+        if result.rows and result.rows[0]:
+            return str(result.rows[0][0])
+        return ""
+
+    async def list_api_keys(self) -> list[ApiKeyInfo]:
+        result = await self._conn.execute(compile_list_api_keys())
+        return [
+            ApiKeyInfo(label=row[0], created_at=str(row[1]) if len(row) > 1 else "")
+            for row in result.rows
+        ]
+
+    async def revoke_api_key(self, label: str) -> None:
+        await self._conn.execute(compile_revoke_api_key(label))
+
+    # ── Notifications ─────────────────────────────────────────────────
+
+    def on(
+        self,
+        event_type: str,
+        *,
+        relation: str | None = None,
+        knowledge_graph: str | None = None,
+    ) -> Callable:
+        """Register a notification callback. Use as a decorator."""
+        return self._conn.dispatcher.on(
+            event_type, relation=relation, knowledge_graph=knowledge_graph
+        )
+
+    async def notifications(self) -> AsyncIterator[NotificationEvent]:
+        """Async iterator yielding notification events."""
+        async for event in self._conn.dispatcher:
+            yield event