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

inputlayer/notifications.py

@@ -0,0 +1,83 @@
+"""Notification dispatcher for push events from the server."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Callable
+
+
+@dataclass(frozen=True)
+class NotificationEvent:
+    """A single notification event from the server."""
+
+    type: str  # persistent_update, rule_change, kg_change, schema_change
+    seq: int
+    timestamp_ms: int
+    session_id: str | None = None
+    knowledge_graph: str | None = None
+    relation: str | None = None
+    operation: str | None = None
+    count: int | None = None
+    rule_name: str | None = None
+    entity: str | None = None
+
+
+Callback = Callable[[NotificationEvent], Any]
+
+
+class NotificationDispatcher:
+    """Routes notification events to registered callbacks."""
+
+    def __init__(self) -> None:
+        self._callbacks: list[tuple[str | None, str | None, str | None, Callback]] = []
+        self._queue: asyncio.Queue[NotificationEvent] = asyncio.Queue()
+        self._last_seq: int = 0
+
+    @property
+    def last_seq(self) -> int:
+        return self._last_seq
+
+    def on(
+        self,
+        event_type: str | None = None,
+        *,
+        relation: str | None = None,
+        knowledge_graph: str | None = None,
+        callback: Callback | None = None,
+    ) -> Callable | None:
+        """Register a callback for notifications. Can be used as a decorator."""
+        def decorator(fn: Callback) -> Callback:
+            self._callbacks.append((event_type, relation, knowledge_graph, fn))
+            return fn
+
+        if callback is not None:
+            self._callbacks.append((event_type, relation, knowledge_graph, callback))
+            return None
+        return decorator
+
+    def dispatch(self, event: NotificationEvent) -> None:
+        """Dispatch a notification to matching callbacks and the async queue."""
+        self._last_seq = max(self._last_seq, event.seq)
+        # Push to async iterator queue
+        self._queue.put_nowait(event)
+        # Call matching callbacks
+        for evt_type, rel, kg, cb in self._callbacks:
+            if evt_type is not None and event.type != evt_type:
+                continue
+            if rel is not None and event.relation != rel:
+                continue
+            if kg is not None and event.knowledge_graph != kg:
+                continue
+            try:
+                result = cb(event)
+                if asyncio.iscoroutine(result):
+                    asyncio.ensure_future(result)
+            except Exception:
+                pass  # Callbacks should not break the dispatcher
+
+    async def __aiter__(self) -> AsyncIterator[NotificationEvent]:
+        """Async iterator yielding notification events."""
+        while True:
+            event = await self._queue.get()
+            yield event

inputlayer/relation.py

@@ -0,0 +1,102 @@
+"""Relation base class - user-facing schema definition via Pydantic models."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, get_type_hints
+
+from pydantic import BaseModel, ConfigDict
+from pydantic._internal._model_construction import ModelMetaclass
+
+from inputlayer._naming import camel_to_snake
+from inputlayer._proxy import ColumnProxy, RelationRef
+
+
+class _RelationMeta(ModelMetaclass):
+    """Metaclass that adds ColumnProxy attribute access to Relation subclasses.
+
+    When you write ``Employee.name`` on the class (not an instance), this
+    metaclass intercepts the lookup and returns a ColumnProxy for query building.
+    Pydantic's own ``ModelMetaclass.__getattr__`` blocks this, so we override it.
+    """
+
+    def __getattr__(cls, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        # model_fields is a dict after Pydantic model construction.
+        # During construction it may be a descriptor, so guard carefully.
+        try:
+            fields = super().__getattribute__("model_fields")
+        except AttributeError:
+            fields = None
+        if isinstance(fields, dict) and name in fields:
+            rel_name = _resolve_name(cls)
+            return ColumnProxy(rel_name, name)
+        raise AttributeError(f"type object '{cls.__name__}' has no attribute '{name}'")
+
+
+def _resolve_name(cls: type) -> str:
+    """Get the Datalog relation name for a Relation subclass."""
+    rn = getattr(cls, "__relation_name__", None)
+    if rn is not None:
+        return rn
+    return camel_to_snake(cls.__name__)
+
+
+class Relation(BaseModel, metaclass=_RelationMeta):
+    """Base class for all InputLayer relations.
+
+    Subclass this with typed fields to define a relation schema::
+
+        class Employee(Relation):
+            id: int
+            name: str
+            department: str
+            salary: float
+            active: bool
+
+    Column proxy access:
+        ``Employee.name`` returns a ``ColumnProxy`` for query building.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    __relation_name__: ClassVar[str | None] = None
+
+    # ── Class-level introspection ─────────────────────────────────────
+
+    @classmethod
+    def _resolve_name(cls, relation_cls: type[Relation] | None = None) -> str:
+        """Get the Datalog relation name for a Relation subclass."""
+        target = relation_cls or cls
+        return _resolve_name(target)
+
+    @classmethod
+    def _get_columns(cls, relation_cls: type[Relation] | None = None) -> list[str]:
+        """Get ordered column names (excludes Pydantic internals)."""
+        target = relation_cls or cls
+        return list(target.model_fields.keys())
+
+    @classmethod
+    def _get_column_types(cls, relation_cls: type[Relation] | None = None) -> dict[str, type]:
+        """Get column name → Python type mapping."""
+        target = relation_cls or cls
+        hints = get_type_hints(target)
+        return {k: hints[k] for k in target.model_fields}
+
+    # ── Self-join support ─────────────────────────────────────────────
+
+    @classmethod
+    def refs(cls, n: int) -> tuple[RelationRef, ...]:
+        """Create n independent references for self-joins.
+
+        Usage::
+
+            r1, r2 = Follow.refs(2)
+            kg.query(r1.follower, r2.followee,
+                     join=[r1, r2],
+                     on=lambda a, b: a.followee == b.follower)
+        """
+        return tuple(
+            RelationRef(cls, f"{_resolve_name(cls)}_{i}")
+            for i in range(1, n + 1)
+        )

inputlayer/result.py

@@ -0,0 +1,89 @@
+"""ResultSet - typed, iterable query results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import SimpleNamespace
+from typing import Any, Iterator
+
+
+@dataclass
+class ResultSet:
+    """Container for query results.
+
+    Supports iteration, indexing, and conversion to dicts/tuples/DataFrames.
+    """
+
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int = 0
+    total_count: int = 0
+    truncated: bool = False
+    execution_time_ms: int = 0
+    row_provenance: list[str] | None = None
+    has_ephemeral: bool = False
+    ephemeral_sources: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    # Optional Relation class for typed iteration
+    _relation_cls: type | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.row_count == 0:
+            self.row_count = len(self.rows)
+        if self.total_count == 0:
+            self.total_count = self.row_count
+
+    def __len__(self) -> int:
+        return self.row_count
+
+    def __bool__(self) -> bool:
+        return self.row_count > 0
+
+    def __iter__(self) -> Iterator[Any]:
+        for row in self.rows:
+            yield self._row_to_obj(row)
+
+    def __getitem__(self, idx: int) -> Any:
+        return self._row_to_obj(self.rows[idx])
+
+    def first(self) -> Any | None:
+        """Return the first row as an object, or None if empty."""
+        if not self.rows:
+            return None
+        return self._row_to_obj(self.rows[0])
+
+    def scalar(self) -> Any:
+        """Return the single value from a 1×1 result."""
+        if not self.rows or not self.rows[0]:
+            raise ValueError("No results to extract scalar from")
+        return self.rows[0][0]
+
+    def to_dicts(self) -> list[dict[str, Any]]:
+        """Convert all rows to list of dicts."""
+        return [dict(zip(self.columns, row)) for row in self.rows]
+
+    def to_tuples(self) -> list[tuple[Any, ...]]:
+        """Convert all rows to list of tuples."""
+        return [tuple(row) for row in self.rows]
+
+    def to_df(self) -> Any:
+        """Convert to a pandas DataFrame. Requires pandas."""
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError(
+                "pandas is required for to_df(). "
+                "Install with: pip install inputlayer[pandas]"
+            )
+        return pd.DataFrame(self.rows, columns=self.columns)
+
+    def _row_to_obj(self, row: list[Any]) -> Any:
+        """Convert a row to a typed object or SimpleNamespace."""
+        if self._relation_cls is not None:
+            try:
+                kwargs = dict(zip(self.columns, row))
+                return self._relation_cls(**kwargs)
+            except Exception:
+                pass
+        return SimpleNamespace(**dict(zip(self.columns, row)))

inputlayer/session.py

@@ -0,0 +1,75 @@
+"""Session - ephemeral facts and rules (no + prefix)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from inputlayer.compiler import compile_bulk_insert, compile_insert, compile_rule
+from inputlayer.relation import Relation
+
+if TYPE_CHECKING:
+    from inputlayer.connection import Connection
+    from inputlayer.derived import Derived
+    from inputlayer.result import ResultSet
+
+
+class Session:
+    """Manage session-scoped (ephemeral) data.
+
+    Session inserts and rules omit the ``+`` prefix, making them ephemeral
+    (cleared on disconnect or KG switch).
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self._conn = connection
+
+    async def insert(self, facts: Relation | list[Relation]) -> None:
+        """Insert ephemeral session facts (no + prefix)."""
+        if isinstance(facts, list):
+            if not facts:
+                return
+            datalog = compile_bulk_insert(type(facts[0]), facts, persistent=False)
+        else:
+            datalog = compile_insert(facts, persistent=False)
+        await self._conn.execute(datalog)
+
+    async def define_rules(self, *targets: type[Derived]) -> None:
+        """Define session-scoped rules (no + prefix)."""
+        from inputlayer.derived import Derived
+
+        for target in targets:
+            head_name = Relation._resolve_name(target)
+            head_columns = Relation._get_columns(target)
+            for clause in target.rules:
+                datalog = compile_rule(
+                    head_name,
+                    head_columns,
+                    clause.select_map,
+                    clause.relations,
+                    clause.condition,
+                    persistent=False,
+                )
+                await self._conn.execute(datalog)
+
+    async def list_rules(self) -> list[str]:
+        """List session rules."""
+        result = await self._conn.execute(".session list")
+        return [row[0] for row in result.rows] if result.rows else []
+
+    async def drop_rule(
+        self,
+        name: str | None = None,
+        *,
+        index: int | None = None,
+    ) -> None:
+        """Drop a session rule by name, or a specific clause by index."""
+        if name and index is not None:
+            await self._conn.execute(f".session remove {name} {index}")
+        elif name:
+            await self._conn.execute(f".session drop {name}")
+        else:
+            raise ValueError("Must provide rule name")
+
+    async def clear(self) -> None:
+        """Clear all session facts and rules."""
+        await self._conn.execute(".session clear")

inputlayer/types.py

@@ -0,0 +1,192 @@
+"""InputLayer type system - Python types that map to Datalog storage types."""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, ClassVar
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+
+class _VectorMeta(type):
+    """Metaclass for Vector that supports Vector[N] syntax."""
+
+    _dim: int | None = None
+    _cache: ClassVar[dict[int, type]] = {}
+
+    def __getitem__(cls, dim: int) -> type:
+        if not isinstance(dim, int) or dim <= 0:
+            raise TypeError(f"Vector dimension must be a positive integer, got {dim!r}")
+        if dim not in cls._cache:
+            ns = type.__new__(_VectorMeta, f"Vector[{dim}]", (cls,), {"_dim": dim})
+            cls._cache[dim] = ns
+        return cls._cache[dim]
+
+    def __instancecheck__(cls, instance: object) -> bool:
+        if not isinstance(instance, list):
+            return False
+        if cls._dim is not None and len(instance) != cls._dim:
+            return False
+        return all(isinstance(v, (int, float)) for v in instance)
+
+    def __repr__(cls) -> str:
+        if cls._dim is not None:
+            return f"Vector[{cls._dim}]"
+        return "Vector"
+
+
+class Vector(list, metaclass=_VectorMeta):
+    """Float32 vector type. Use Vector[N] for a fixed-dimensionality vector."""
+
+    _dim: ClassVar[int | None] = None
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        dim = getattr(source_type, "_dim", None)
+
+        def validate(v: Any) -> list:
+            if isinstance(v, (list, tuple)):
+                v = list(v)
+            if not isinstance(v, list):
+                raise ValueError(f"Expected list for Vector, got {type(v).__name__}")
+            if dim is not None and len(v) != dim:
+                raise ValueError(f"Expected vector of dimension {dim}, got {len(v)}")
+            return [float(x) for x in v]
+
+        return core_schema.no_info_plain_validator_function(
+            validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda v: v, info_arg=False
+            ),
+        )
+
+
+class _VectorInt8Meta(type):
+    """Metaclass for VectorInt8 that supports VectorInt8[N] syntax."""
+
+    _dim: int | None = None
+    _cache: ClassVar[dict[int, type]] = {}
+
+    def __getitem__(cls, dim: int) -> type:
+        if not isinstance(dim, int) or dim <= 0:
+            raise TypeError(
+                f"VectorInt8 dimension must be a positive integer, got {dim!r}"
+            )
+        if dim not in cls._cache:
+            ns = type.__new__(
+                _VectorInt8Meta, f"VectorInt8[{dim}]", (cls,), {"_dim": dim}
+            )
+            cls._cache[dim] = ns
+        return cls._cache[dim]
+
+    def __instancecheck__(cls, instance: object) -> bool:
+        if not isinstance(instance, list):
+            return False
+        if cls._dim is not None and len(instance) != cls._dim:
+            return False
+        return all(isinstance(v, int) and -128 <= v <= 127 for v in instance)
+
+    def __repr__(cls) -> str:
+        if cls._dim is not None:
+            return f"VectorInt8[{cls._dim}]"
+        return "VectorInt8"
+
+
+class VectorInt8(list, metaclass=_VectorInt8Meta):
+    """Int8 quantized vector type. Use VectorInt8[N] for fixed dimensionality."""
+
+    _dim: ClassVar[int | None] = None
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        dim = getattr(source_type, "_dim", None)
+
+        def validate(v: Any) -> list:
+            if isinstance(v, (list, tuple)):
+                v = list(v)
+            if not isinstance(v, list):
+                raise ValueError(f"Expected list for VectorInt8, got {type(v).__name__}")
+            if dim is not None and len(v) != dim:
+                raise ValueError(f"Expected vector of dimension {dim}, got {len(v)}")
+            for x in v:
+                if not isinstance(x, int) or not (-128 <= x <= 127):
+                    raise ValueError(f"VectorInt8 values must be int in [-128, 127], got {x}")
+            return [int(x) for x in v]
+
+        return core_schema.no_info_plain_validator_function(
+            validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda v: v, info_arg=False
+            ),
+        )
+
+
+class Timestamp(int):
+    """Timestamp as Unix milliseconds since epoch."""
+
+    @classmethod
+    def now(cls) -> Timestamp:
+        """Current time as a Timestamp."""
+        return cls(int(time.time() * 1000))
+
+    @classmethod
+    def from_datetime(cls, dt: datetime) -> Timestamp:
+        """Convert a datetime to a Timestamp (Unix ms)."""
+        return cls(int(dt.timestamp() * 1000))
+
+    def to_datetime(self) -> datetime:
+        """Convert to a timezone-aware UTC datetime."""
+        return datetime.fromtimestamp(int(self) / 1000.0, tz=timezone.utc)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        return core_schema.no_info_plain_validator_function(
+            lambda v: Timestamp(int(v)),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda v: int(v), info_arg=False
+            ),
+        )
+
+
+# Map Python types to InputLayer Datalog type names
+# Order matters: more specific types first (bool before int, Timestamp before int)
+TYPE_MAP: dict[type, str] = {
+    bool: "bool",
+    Timestamp: "timestamp",
+    int: "int",
+    float: "float",
+    str: "string",
+    Vector: "vector",
+    VectorInt8: "vector_int8",
+}
+
+
+def python_type_to_datalog(tp: type) -> str:
+    """Convert a Python type annotation to its InputLayer Datalog type string.
+
+    Handles Vector[N], VectorInt8[N], and plain types.
+    """
+    # Check for dimensioned vectors
+    if isinstance(tp, _VectorMeta) and tp._dim is not None:
+        return f"vector[{tp._dim}]"
+    if isinstance(tp, _VectorInt8Meta) and tp._dim is not None:
+        return f"vector_int8[{tp._dim}]"
+    # Check base types
+    for base_type, name in TYPE_MAP.items():
+        if tp is base_type:
+            return name
+        # Handle subclasses (e.g., Vector without dim)
+        try:
+            if issubclass(tp, base_type) and tp is not base_type:
+                return name
+        except TypeError:
+            pass
+    raise TypeError(f"Unsupported type for InputLayer schema: {tp!r}")