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

inputlayer/__init__.py

@@ -0,0 +1,151 @@
+"""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
+
+# Aggregations
+from inputlayer.aggregations import (
+    avg,
+    count,
+    count_distinct,
+    max_,
+    min_,
+    sum_,
+    top_k,
+    top_k_threshold,
+    within_radius,
+)
+
+# Functions (re-export all)
+from inputlayer import functions
+
+# Index
+from inputlayer.index import HnswIndex
+
+# Exceptions
+from inputlayer.exceptions import (
+    AuthenticationError,
+    CannotDropError,
+    ConnectionError,
+    IndexNotFoundError,
+    InputLayerError,
+    InternalError,
+    KnowledgeGraphExistsError,
+    KnowledgeGraphNotFoundError,
+    PermissionError,
+    QueryTimeoutError,
+    RelationNotFoundError,
+    RuleNotFoundError,
+    SchemaConflictError,
+    ValidationError,
+)
+
+# Result
+from inputlayer.result import ResultSet
+
+# Client
+from inputlayer.client import InputLayer
+from inputlayer.client_sync import InputLayerSync
+
+# Knowledge Graph
+from inputlayer.knowledge_graph import (
+    ClearResult,
+    ColumnInfo,
+    DeleteResult,
+    ExplainResult,
+    IndexInfo,
+    IndexStats,
+    InsertResult,
+    KnowledgeGraph,
+    RelationDescription,
+    RelationInfo,
+    RuleInfo,
+    ServerStatus,
+)
+
+# Auth
+from inputlayer.auth import AclEntry, ApiKeyInfo, UserInfo
+
+# Session
+from inputlayer.session import Session
+
+# Notifications
+from inputlayer.notifications import NotificationEvent
+
+# Migrations
+from inputlayer.migrations import Migration
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Types
+    "Vector",
+    "VectorInt8",
+    "Timestamp",
+    # Relation
+    "Relation",
+    "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",
+    "IndexNotFoundError",
+    "InternalError",
+    # Result
+    "ResultSet",
+    # Client
+    "InputLayer",
+    "InputLayerSync",
+    # KG
+    "KnowledgeGraph",
+    "RelationInfo",
+    "RelationDescription",
+    "ColumnInfo",
+    "RuleInfo",
+    "IndexInfo",
+    "IndexStats",
+    "InsertResult",
+    "DeleteResult",
+    "ClearResult",
+    "ExplainResult",
+    "ServerStatus",
+    # Auth
+    "UserInfo",
+    "ApiKeyInfo",
+    "AclEntry",
+    # Session
+    "Session",
+    # Notifications
+    "NotificationEvent",
+    # Migrations
+    "Migration",
+]

inputlayer/_ast.py

@@ -0,0 +1,133 @@
+"""Internal AST nodes for expression trees compiled to Datalog."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── Base ──────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Expr:
+    """Base class for all expression AST nodes."""
+
+
+@dataclass(frozen=True)
+class BoolExpr:
+    """Base class for boolean expression AST nodes (conditions)."""
+
+
+# ── Leaf nodes ────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Column(Expr):
+    """Reference to a relation column."""
+    relation: str
+    name: str
+    ref_alias: str | None = None  # For self-join disambiguation
+
+    @property
+    def qualified(self) -> str:
+        prefix = self.ref_alias or self.relation
+        return f"{prefix}.{self.name}"
+
+
+@dataclass(frozen=True)
+class Literal(Expr):
+    """A constant value."""
+    value: Any  # int, float, str, bool, list (vector), None
+
+
+# ── Arithmetic ────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Arithmetic(Expr):
+    """Binary arithmetic: +, -, *, /, %."""
+    op: str  # "+", "-", "*", "/", "%"
+    left: Expr
+    right: Expr
+
+
+# ── Function call ─────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class FuncCall(Expr):
+    """Built-in function call: distance(V1, V2), upper(S), etc."""
+    name: str
+    args: tuple[Expr, ...] = ()
+
+
+# ── Aggregation ───────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AggExpr(Expr):
+    """Aggregation expression: count<X>, sum<X>, top_k<k, ...>, etc."""
+    func: str  # "count", "sum", "min", "max", "avg", "count_distinct",
+    # "top_k", "top_k_threshold", "within_radius"
+    column: Expr | None = None  # The aggregated column (None for count(*))
+    params: tuple[Any, ...] = ()  # Extra params (k, threshold, etc.)
+    passthrough: tuple[Expr, ...] = ()  # Passthrough columns
+    order_column: Expr | None = None  # For top_k: the ordering column
+    desc: bool = True  # For top_k: descending order
+
+
+# ── Ordering ──────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class OrderedColumn(Expr):
+    """A column with sort direction."""
+    column: Expr
+    descending: bool = False
+
+
+# ── Boolean expressions ──────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Comparison(BoolExpr):
+    """Binary comparison: ==, !=, <, <=, >, >=."""
+    op: str  # "=", "!=", "<", "<=", ">", ">="
+    left: Expr
+    right: Expr
+
+
+@dataclass(frozen=True)
+class And(BoolExpr):
+    """Logical AND of two conditions (Datalog comma)."""
+    left: BoolExpr
+    right: BoolExpr
+
+
+@dataclass(frozen=True)
+class Or(BoolExpr):
+    """Logical OR - requires splitting into multiple queries."""
+    left: BoolExpr
+    right: BoolExpr
+
+
+@dataclass(frozen=True)
+class Not(BoolExpr):
+    """Negation: !relation(X, Y) in Datalog."""
+    operand: BoolExpr
+
+
+@dataclass(frozen=True)
+class InExpr(BoolExpr):
+    """Membership test: Column appears in another relation."""
+    column: Expr
+    target_column: Expr
+
+
+@dataclass(frozen=True)
+class NegatedIn(BoolExpr):
+    """Negated membership test."""
+    column: Expr
+    target_column: Expr
+
+
+@dataclass(frozen=True)
+class MatchExpr(BoolExpr):
+    """Multi-column negation/existence check against a relation."""
+    relation: str
+    bindings: dict[str, Expr]  # target_col -> source expr
+    negated: bool = False

inputlayer/_naming.py

@@ -0,0 +1,44 @@
+"""Naming convention utilities: CamelCase ↔ snake_case, column → Datalog variable."""
+
+from __future__ import annotations
+
+import re
+
+
+def camel_to_snake(name: str) -> str:
+    """Convert CamelCase class name to snake_case relation name.
+
+    Examples:
+        Employee -> employee
+        UserProfile -> user_profile
+        HTTPRequest -> http_request
+        ABCDef -> abc_def
+    """
+    # Insert underscore between sequences of uppercase and a following lower/digit
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    # Insert underscore between lowercase/digit and uppercase
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
+    return s.lower()
+
+
+def snake_to_camel(name: str) -> str:
+    """Convert snake_case to CamelCase.
+
+    Examples:
+        employee -> Employee
+        user_profile -> UserProfile
+        http_request -> HttpRequest
+    """
+    return "".join(part.capitalize() for part in name.split("_"))
+
+
+def column_to_variable(column_name: str) -> str:
+    """Convert a snake_case column name to a Datalog variable (Capitalized).
+
+    Examples:
+        id -> Id
+        name -> Name
+        department_name -> DepartmentName
+        x -> X
+    """
+    return snake_to_camel(column_name)

inputlayer/_protocol.py

@@ -0,0 +1,225 @@
+"""WebSocket wire protocol: message serialization and deserialization.
+
+Matches the AsyncAPI spec at ``docs/spec/asyncapi.yaml``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── Client → Server messages ──────────────────────────────────────────
+
+@dataclass(frozen=True)
+class LoginMessage:
+    username: str
+    password: str
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "type": "login",
+            "username": self.username,
+            "password": self.password,
+        })
+
+
+@dataclass(frozen=True)
+class AuthenticateMessage:
+    api_key: str
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "type": "authenticate",
+            "api_key": self.api_key,
+        })
+
+
+@dataclass(frozen=True)
+class ExecuteMessage:
+    program: str
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "type": "execute",
+            "program": self.program,
+        })
+
+
+@dataclass(frozen=True)
+class PingMessage:
+    def to_json(self) -> str:
+        return json.dumps({"type": "ping"})
+
+
+# ── Server → Client messages ─────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AuthenticatedResponse:
+    session_id: str
+    knowledge_graph: str
+    version: str
+    role: str
+
+
+@dataclass(frozen=True)
+class AuthErrorResponse:
+    message: str
+
+
+@dataclass(frozen=True)
+class ResultResponse:
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    total_count: int
+    truncated: bool
+    execution_time_ms: int
+    row_provenance: list[str] | None = None
+    metadata: dict[str, Any] | None = None
+    switched_kg: str | None = None
+
+
+@dataclass(frozen=True)
+class ErrorResponse:
+    message: str
+    validation_errors: list[dict[str, Any]] | None = None
+
+
+@dataclass(frozen=True)
+class ResultStartResponse:
+    columns: list[str]
+    total_count: int
+    truncated: bool
+    execution_time_ms: int
+    metadata: dict[str, Any] | None = None
+    switched_kg: str | None = None
+
+
+@dataclass(frozen=True)
+class ResultChunkResponse:
+    rows: list[list[Any]]
+    chunk_index: int
+    row_provenance: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class ResultEndResponse:
+    row_count: int
+    chunk_count: int
+
+
+@dataclass(frozen=True)
+class PongResponse:
+    pass
+
+
+@dataclass(frozen=True)
+class NotificationResponse:
+    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
+    # persistent_update fields
+    relation: str | None = None
+    operation: str | None = None
+    count: int | None = None
+    # rule_change fields
+    rule_name: str | None = None
+    # schema_change fields
+    entity: str | None = None
+
+
+# ── Type alias ────────────────────────────────────────────────────────
+
+ServerMessage = (
+    AuthenticatedResponse
+    | AuthErrorResponse
+    | ResultResponse
+    | ErrorResponse
+    | ResultStartResponse
+    | ResultChunkResponse
+    | ResultEndResponse
+    | PongResponse
+    | NotificationResponse
+)
+
+
+# ── Serialization / Deserialization ───────────────────────────────────
+
+def serialize_message(msg: LoginMessage | AuthenticateMessage | ExecuteMessage | PingMessage) -> str:
+    """Serialize a client message to JSON."""
+    return msg.to_json()
+
+
+def deserialize_message(data: str | bytes) -> ServerMessage:
+    """Deserialize a server JSON message into a typed response object."""
+    if isinstance(data, bytes):
+        data = data.decode("utf-8")
+    obj = json.loads(data)
+    msg_type = obj.get("type")
+
+    if msg_type == "authenticated":
+        return AuthenticatedResponse(
+            session_id=obj["session_id"],
+            knowledge_graph=obj["knowledge_graph"],
+            version=obj["version"],
+            role=obj["role"],
+        )
+    if msg_type == "auth_error":
+        return AuthErrorResponse(message=obj["message"])
+    if msg_type == "result":
+        return ResultResponse(
+            columns=obj["columns"],
+            rows=obj["rows"],
+            row_count=obj["row_count"],
+            total_count=obj["total_count"],
+            truncated=obj["truncated"],
+            execution_time_ms=obj["execution_time_ms"],
+            row_provenance=obj.get("row_provenance"),
+            metadata=obj.get("metadata"),
+            switched_kg=obj.get("switched_kg"),
+        )
+    if msg_type == "error":
+        return ErrorResponse(
+            message=obj["message"],
+            validation_errors=obj.get("validation_errors"),
+        )
+    if msg_type == "result_start":
+        return ResultStartResponse(
+            columns=obj["columns"],
+            total_count=obj["total_count"],
+            truncated=obj["truncated"],
+            execution_time_ms=obj["execution_time_ms"],
+            metadata=obj.get("metadata"),
+            switched_kg=obj.get("switched_kg"),
+        )
+    if msg_type == "result_chunk":
+        return ResultChunkResponse(
+            rows=obj["rows"],
+            chunk_index=obj["chunk_index"],
+            row_provenance=obj.get("row_provenance"),
+        )
+    if msg_type == "result_end":
+        return ResultEndResponse(
+            row_count=obj["row_count"],
+            chunk_count=obj["chunk_count"],
+        )
+    if msg_type == "pong":
+        return PongResponse()
+    if msg_type in ("persistent_update", "rule_change", "kg_change", "schema_change"):
+        return NotificationResponse(
+            type=msg_type,
+            seq=obj["seq"],
+            timestamp_ms=obj["timestamp_ms"],
+            session_id=obj.get("session_id"),
+            knowledge_graph=obj.get("knowledge_graph"),
+            relation=obj.get("relation"),
+            operation=obj.get("operation"),
+            count=obj.get("count"),
+            rule_name=obj.get("rule_name"),
+            entity=obj.get("entity"),
+        )
+    raise ValueError(f"Unknown message type: {msg_type!r}")