inputlayer-js-dev 0.1.0-dev.ec507e7

package/dist/index.d.ts

@@ -0,0 +1,929 @@
+import { I as IQLType, C as ColumnProxy, R as RelationRef, E as Expr, B as BoolExpr, a as Column, b as Fact, c as RelationProxy, A as AggExpr } from './proxy-CPWAPhZZ.js';
+export { d as AND, e as And, f as Arithmetic, g as ColumnDef, h as Comparison, i as FieldValue, F as FuncCall, j as InExpr, L as Literal, M as MatchExpr, N as NOT, k as NegatedIn, l as Not, O as OR, m as Or, n as OrderedColumn, o as RelationSchema, T as Timestamp, V as Vector, p as VectorInt8, w as wrap } from './proxy-CPWAPhZZ.js';
+
+/**
+ * Relation definitions - schema-first approach for TypeScript.
+ *
+ * Unlike Python's class-based approach with Pydantic metaclasses, TypeScript
+ * uses plain objects with a schema descriptor. Relations are defined as:
+ *
+ *   const Employee = relation("Employee", {
+ *     id: "int",
+ *     name: "string",
+ *     department: "string",
+ *     salary: "float",
+ *     active: "bool",
+ *   });
+ *
+ * This returns a RelationDef with column accessors, insert helpers, etc.
+ */
+
+/** Column type shorthand map for the schema definition DSL. */
+type ColumnTypes = Record<string, IQLType>;
+/** A relation definition created by `relation()`. */
+declare class RelationDef {
+    /** The IQL relation name (snake_case). */
+    readonly relationName: string;
+    /** Original class-style name. */
+    readonly className: string;
+    /** Ordered column names. */
+    readonly columns: string[];
+    /** Column name -> IQL type. */
+    readonly columnTypes: Record<string, IQLType>;
+    constructor(className: string, columnTypes: ColumnTypes, name?: string);
+    /** Get a ColumnProxy for a column (for query building). */
+    col(name: string): ColumnProxy;
+    /**
+     * Create multiple independent references for self-joins.
+     *
+     * Usage:
+     *   const [r1, r2] = Follow.refs(2);
+     *   kg.query({ select: [r1.col("follower"), r2.col("followee")], join: [r1, r2], ... });
+     */
+    refs(n: number): RelationRef[];
+}
+/**
+ * Define a relation schema.
+ *
+ * @param className - CamelCase name (converted to snake_case for IQL)
+ * @param columnTypes - Column name -> type mapping
+ * @param opts - Optional overrides
+ * @returns A RelationDef for use with KnowledgeGraph operations
+ *
+ * @example
+ * const Employee = relation("Employee", {
+ *   id: "int",
+ *   name: "string",
+ *   department: "string",
+ *   salary: "float",
+ *   active: "bool",
+ * });
+ */
+declare function relation(className: string, columnTypes: ColumnTypes, opts?: {
+    name?: string;
+}): RelationDef;
+/** Compile a value to its IQL literal representation. */
+declare function compileValue(value: unknown): string;
+/** Resolve a RelationDef or string to its IQL relation name. */
+declare function resolveRelationName(r: RelationDef | string): string;
+/** Get ordered column names from a RelationDef. */
+declare function getColumns(r: RelationDef): string[];
+/** Get column types from a RelationDef. */
+declare function getColumnTypes(r: RelationDef): Record<string, IQLType>;
+
+/**
+ * Compiler: TypeScript objects and AST nodes -> IQL text.
+ *
+ * Every function is pure (no I/O), taking TypeScript objects and returning
+ * IQL strings.
+ */
+
+/**
+ * Variable environment for tracking column->variable mappings with union-find.
+ * Ensures that join conditions produce shared IQL variables.
+ */
+declare class VarEnv {
+    private map;
+    private counter;
+    private parent;
+    private find;
+    private union;
+    getVar(col: Column): string;
+    unify(colA: Column, colB: Column): string;
+    lookup(col: Column): string | undefined;
+    /** Direct-set a variable for conditional delete setup. */
+    set(key: string, varName: string): void;
+}
+declare function compileExpr(expr: Expr, env: VarEnv): string;
+declare function compileBoolExpr(expr: BoolExpr, env: VarEnv): string[];
+/** Compile a relation definition to a schema statement: +employee(id: int, name: string, ...) */
+declare function compileSchema(rel: RelationDef): string;
+/** Compile a single fact insert: +employee(1, "Alice", ...) */
+declare function compileInsert(rel: RelationDef, fact: Fact, persistent?: boolean): string;
+/** Compile a bulk insert: +employee[(1, "Alice", ...), (2, "Bob", ...)] */
+declare function compileBulkInsert(rel: RelationDef, facts: Fact[], persistent?: boolean): string;
+/** Compile a single fact deletion: -employee(1, "Alice", ...) */
+declare function compileDelete(rel: RelationDef, fact: Fact): string;
+/** Compile a conditional delete: -employee(X0, X1, ...) <- employee(X0, X1, ...), X2 = "sales" */
+declare function compileConditionalDelete(rel: RelationDef, condition: BoolExpr): string;
+interface QueryOptions {
+    /** Columns/relations to select. */
+    select: Array<RelationDef | Expr>;
+    /** Relations to join. */
+    join?: Array<RelationDef | RelationRef>;
+    /** Join condition (BoolExpr). */
+    on?: BoolExpr;
+    /** Where filter (BoolExpr). */
+    where?: BoolExpr;
+    /** Order by expression. */
+    orderBy?: Expr;
+    /** Limit number of rows. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+    /** Computed columns: alias -> Expr. */
+    computed?: Record<string, Expr>;
+}
+/**
+ * Compile a query to IQL.
+ * Returns a single string, or an array of strings if OR conditions require splitting.
+ */
+declare function compileQuery(opts: QueryOptions): string | string[];
+interface RuleClause {
+    /** Body relations: [name, RelationDef, alias?] */
+    relations: Array<{
+        name: string;
+        def: RelationDef;
+        alias?: string;
+    }>;
+    /** Head column -> body Expr mapping. */
+    selectMap: Record<string, Expr>;
+    /** Optional filter condition. */
+    condition?: BoolExpr;
+}
+/** Compile a rule definition to IQL. */
+declare function compileRule(headName: string, headColumns: string[], clause: RuleClause, persistent?: boolean): string;
+
+/**
+ * Derived relations and the From/Where/Select rule builder.
+ *
+ * Provides a fluent API for defining rules that mirrors the Python SDK.
+ *
+ * @example
+ * ```typescript
+ * const reachableRules = [
+ *   from(Edge).select({ src: Edge.col("x"), dst: Edge.col("y") }),
+ *   from(Reachable, Edge)
+ *     .where((r, e) => r.col("dst").eq(e.col("x")))
+ *     .select({ src: Reachable.col("src"), dst: Edge.col("y") }),
+ * ];
+ *
+ * await kg.defineRules("reachable", ["src", "dst"], reachableRules);
+ * ```
+ */
+
+declare class FromWhere {
+    private readonly relations;
+    private readonly condition;
+    constructor(relations: Array<{
+        name: string;
+        def: RelationDef;
+        alias?: string;
+    }>, condition: BoolExpr);
+    /**
+     * Map derived columns to body expressions.
+     * Keys must match the derived relation's column names.
+     */
+    select(columns: Record<string, ColumnProxy | Expr>): RuleClause;
+}
+declare class FromBuilder {
+    private readonly relations;
+    constructor(rels: Array<RelationDef | RelationRef>);
+    /**
+     * Add a filter/join condition.
+     * Accepts a BoolExpr or a callback receiving RelationProxy objects.
+     */
+    where(condition: BoolExpr | ((...proxies: RelationProxy[]) => BoolExpr)): FromWhere;
+    /**
+     * Map derived columns to body expressions (no filter).
+     * Keys must match the derived relation's column names.
+     */
+    select(columns: Record<string, ColumnProxy | Expr>): RuleClause;
+}
+/**
+ * Start building a rule clause.
+ *
+ * @param relations - The body relations for this rule clause
+ * @returns A FromBuilder with .where() and .select() methods
+ *
+ * @example
+ * from(Edge).select({ src: Edge.col("x"), dst: Edge.col("y") })
+ */
+declare function from(...relations: Array<RelationDef | RelationRef>): FromBuilder;
+
+/**
+ * Aggregation functions that compile to IQL aggregates.
+ */
+
+/**
+ * Count rows. If a column is given, counts non-null values.
+ * IQL: count<Var>
+ */
+declare function count(column?: ColumnProxy | Expr): AggExpr;
+/**
+ * Count distinct values.
+ * IQL: count_distinct<Var>
+ */
+declare function countDistinct(column: ColumnProxy | Expr): AggExpr;
+/**
+ * Sum numeric values.
+ * IQL: sum<Var>
+ */
+declare function sum(column: ColumnProxy | Expr): AggExpr;
+/**
+ * Minimum value.
+ * IQL: min<Var>
+ */
+declare function min(column: ColumnProxy | Expr): AggExpr;
+/**
+ * Maximum value.
+ * IQL: max<Var>
+ */
+declare function max(column: ColumnProxy | Expr): AggExpr;
+/**
+ * Average value.
+ * IQL: avg<Var>
+ */
+declare function avg(column: ColumnProxy | Expr): AggExpr;
+/**
+ * Top-K aggregation with ordering.
+ * IQL: top_k<k, Passthrough..., OrderCol:desc>
+ */
+declare function topK(opts: {
+    k: number;
+    passthrough?: Array<ColumnProxy | Expr>;
+    orderBy: ColumnProxy | Expr;
+    desc?: boolean;
+}): AggExpr;
+/**
+ * Top-K with threshold aggregation.
+ * IQL: top_k_threshold<k, threshold, Passthrough..., OrderCol:desc>
+ */
+declare function topKThreshold(opts: {
+    k: number;
+    threshold: number;
+    passthrough?: Array<ColumnProxy | Expr>;
+    orderBy: ColumnProxy | Expr;
+    desc?: boolean;
+}): AggExpr;
+/**
+ * Within-radius aggregation.
+ * IQL: within_radius<r, Passthrough..., DistCol:asc>
+ */
+declare function withinRadius(opts: {
+    maxDistance: number;
+    passthrough?: Array<ColumnProxy | Expr>;
+    distance: ColumnProxy | Expr;
+    asc?: boolean;
+}): AggExpr;
+
+/**
+ * HNSW index definition and compilation.
+ */
+
+interface HnswIndexOptions {
+    name: string;
+    relation: RelationDef;
+    column: string;
+    metric?: 'cosine' | 'euclidean' | 'manhattan' | 'dot_product';
+    m?: number;
+    efConstruction?: number;
+    efSearch?: number;
+}
+/**
+ * HNSW vector index configuration.
+ */
+declare class HnswIndex {
+    readonly name: string;
+    readonly relation: RelationDef;
+    readonly column: string;
+    readonly metric: string;
+    readonly m: number;
+    readonly efConstruction: number;
+    readonly efSearch: number;
+    constructor(opts: HnswIndexOptions);
+    /** Compile this index definition to an IQL meta command. */
+    toIQL(): string;
+}
+
+/**
+ * Exception hierarchy for the InputLayer SDK.
+ */
+declare class InputLayerError extends Error {
+    constructor(message: string);
+}
+declare class ConnectionError extends InputLayerError {
+    constructor(message: string);
+}
+declare class AuthenticationError extends InputLayerError {
+    constructor(message: string);
+}
+declare class SchemaConflictError extends InputLayerError {
+    existingSchema?: Record<string, unknown>;
+    proposedSchema?: Record<string, unknown>;
+    conflicts: string[];
+    constructor(message: string, opts?: {
+        existingSchema?: Record<string, unknown>;
+        proposedSchema?: Record<string, unknown>;
+        conflicts?: string[];
+    });
+}
+declare class ValidationError extends InputLayerError {
+    details: Array<Record<string, unknown>>;
+    constructor(message: string, opts?: {
+        details?: Array<Record<string, unknown>>;
+    });
+}
+declare class QueryTimeoutError extends InputLayerError {
+    constructor(message: string);
+}
+declare class PermissionError extends InputLayerError {
+    constructor(message: string);
+}
+declare class KnowledgeGraphNotFoundError extends InputLayerError {
+    constructor(message: string);
+}
+declare class KnowledgeGraphExistsError extends InputLayerError {
+    constructor(message: string);
+}
+declare class CannotDropError extends InputLayerError {
+    constructor(message: string);
+}
+declare class RelationNotFoundError extends InputLayerError {
+    constructor(message: string);
+}
+declare class RuleNotFoundError extends InputLayerError {
+    constructor(message: string);
+}
+declare class IndexNotFoundError extends InputLayerError {
+    constructor(message: string);
+}
+declare class InternalError extends InputLayerError {
+    constructor(message: string);
+}
+
+/**
+ * ResultSet - typed, iterable query results.
+ */
+type AnyRow = any[];
+interface ResultSetOptions {
+    columns: string[];
+    rows: AnyRow[];
+    rowCount?: number;
+    totalCount?: number;
+    truncated?: boolean;
+    executionTimeMs?: number;
+    rowProvenance?: string[];
+    hasEphemeral?: boolean;
+    ephemeralSources?: string[];
+    warnings?: string[];
+}
+/**
+ * Container for query results.
+ * Supports iteration, indexing, and conversion to various formats.
+ */
+declare class ResultSet implements Iterable<Record<string, unknown>> {
+    readonly columns: string[];
+    readonly rows: AnyRow[];
+    readonly rowCount: number;
+    readonly totalCount: number;
+    readonly truncated: boolean;
+    readonly executionTimeMs: number;
+    readonly rowProvenance?: string[];
+    hasEphemeral: boolean;
+    ephemeralSources: string[];
+    warnings: string[];
+    constructor(opts: ResultSetOptions);
+    /** Number of result rows. */
+    get length(): number;
+    /** True if there are any results. */
+    get isEmpty(): boolean;
+    /** Get a single row as a keyed object. */
+    get(index: number): Record<string, unknown>;
+    /** Get the first row or undefined if empty. */
+    first(): Record<string, unknown> | undefined;
+    /** Return the single value from a 1x1 result. */
+    scalar(): unknown;
+    /** Convert all rows to a list of keyed objects. */
+    toDicts(): Array<Record<string, unknown>>;
+    /** Convert all rows to a list of tuples (arrays). */
+    toTuples(): AnyRow[];
+    /** Iterate over rows as keyed objects. */
+    [Symbol.iterator](): Iterator<Record<string, unknown>>;
+    private rowToObj;
+}
+
+/**
+ * WebSocket wire protocol: message serialization and deserialization.
+ * Matches the AsyncAPI spec at docs/spec/asyncapi.yaml.
+ */
+interface LoginMessage {
+    type: 'login';
+    username: string;
+    password: string;
+}
+interface AuthenticateMessage {
+    type: 'authenticate';
+    api_key: string;
+}
+interface ExecuteMessage {
+    type: 'execute';
+    program: string;
+}
+interface PingMessage {
+    type: 'ping';
+}
+type ClientMessage = LoginMessage | AuthenticateMessage | ExecuteMessage | PingMessage;
+interface AuthenticatedResponse {
+    type: 'authenticated';
+    session_id: string;
+    knowledge_graph: string;
+    version: string;
+    role: string;
+}
+interface AuthErrorResponse {
+    type: 'auth_error';
+    message: string;
+}
+interface ResultResponse {
+    type: 'result';
+    columns: string[];
+    rows: any[][];
+    row_count: number;
+    total_count: number;
+    truncated: boolean;
+    execution_time_ms: number;
+    row_provenance?: string[];
+    metadata?: Record<string, any>;
+    switched_kg?: string;
+}
+interface ErrorResponse {
+    type: 'error';
+    message: string;
+    validation_errors?: Array<Record<string, any>>;
+}
+interface ResultStartResponse {
+    type: 'result_start';
+    columns: string[];
+    total_count: number;
+    truncated: boolean;
+    execution_time_ms: number;
+    metadata?: Record<string, any>;
+    switched_kg?: string;
+}
+interface ResultChunkResponse {
+    type: 'result_chunk';
+    rows: any[][];
+    chunk_index: number;
+    row_provenance?: string[];
+}
+interface ResultEndResponse {
+    type: 'result_end';
+    row_count: number;
+    chunk_count: number;
+}
+interface PongResponse {
+    type: 'pong';
+}
+interface NotificationResponse {
+    type: 'persistent_update' | 'rule_change' | 'kg_change' | 'schema_change';
+    seq: number;
+    timestamp_ms: number;
+    session_id?: string;
+    knowledge_graph?: string;
+    relation?: string;
+    operation?: string;
+    count?: number;
+    rule_name?: string;
+    entity?: string;
+}
+type ServerMessage = AuthenticatedResponse | AuthErrorResponse | ResultResponse | ErrorResponse | ResultStartResponse | ResultChunkResponse | ResultEndResponse | PongResponse | NotificationResponse;
+declare function serializeMessage(msg: ClientMessage): string;
+declare function deserializeMessage(data: string): ServerMessage;
+
+/**
+ * Notification dispatcher for push events from the server.
+ */
+/** A single notification event from the server. */
+interface NotificationEvent {
+    type: string;
+    seq: number;
+    timestampMs: number;
+    sessionId?: string;
+    knowledgeGraph?: string;
+    relation?: string;
+    operation?: string;
+    count?: number;
+    ruleName?: string;
+    entity?: string;
+}
+type NotificationCallback = (event: NotificationEvent) => void | Promise<void>;
+/**
+ * Routes notification events to registered callbacks.
+ */
+declare class NotificationDispatcher {
+    private callbacks;
+    private _lastSeq;
+    private waiters;
+    get lastSeq(): number;
+    /**
+     * Register a callback for notifications.
+     *
+     * @param eventType - Filter by event type (e.g. "persistent_update")
+     * @param opts - Additional filters
+     * @param callback - Function to call when a matching event arrives
+     */
+    on(eventType: string | undefined, opts: {
+        relation?: string;
+        knowledgeGraph?: string;
+    }, callback: NotificationCallback): void;
+    /** Remove a previously registered callback. */
+    off(callback: NotificationCallback): void;
+    /** Dispatch a notification to matching callbacks. */
+    dispatch(event: NotificationEvent): void;
+    /** Wait for the next notification event. */
+    next(): Promise<NotificationEvent>;
+    /**
+     * Create an async iterable of notification events.
+     *
+     * Usage:
+     *   for await (const event of dispatcher.events()) { ... }
+     */
+    events(): AsyncIterableIterator<NotificationEvent>;
+}
+
+/**
+ * WebSocket connection management with authentication and streaming support.
+ */
+
+interface ConnectionOptions {
+    url: string;
+    username?: string;
+    password?: string;
+    apiKey?: string;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectAttempts?: number;
+    initialKg?: string;
+    lastSeq?: number;
+}
+/**
+ * Manages the WebSocket connection to an InputLayer server.
+ */
+declare class Connection {
+    private readonly url;
+    private readonly username?;
+    private readonly password?;
+    private readonly apiKey?;
+    private readonly autoReconnect;
+    private readonly reconnectDelay;
+    private readonly maxReconnectAttempts;
+    private readonly initialKg?;
+    private ws;
+    private _sessionId?;
+    private _serverVersion?;
+    private _role?;
+    private _currentKg?;
+    private _connected;
+    private _lastSeq?;
+    private readonly _dispatcher;
+    private pendingResolve?;
+    constructor(opts: ConnectionOptions);
+    get connected(): boolean;
+    get sessionId(): string | undefined;
+    get serverVersion(): string | undefined;
+    get role(): string | undefined;
+    get currentKg(): string | undefined;
+    /** Force-set the current KG (used by KnowledgeGraph after .kg use). */
+    setCurrentKg(name: string): void;
+    get dispatcher(): NotificationDispatcher;
+    get lastSeq(): number;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private authenticate;
+    /**
+     * Send a program/command and wait for the result.
+     * Transparently assembles streamed results (result_start -> chunks -> result_end).
+     */
+    execute(program: string): Promise<ResultResponse>;
+    private readResult;
+    private assembleStream;
+    private isNotification;
+    private dispatchNotification;
+    private reconnect;
+    ping(): Promise<void>;
+    private createWebSocket;
+    /** Receive exactly one message (used during auth before handler is set up). */
+    private receiveOne;
+    /** Receive the next message via the pendingResolve mechanism. */
+    private receiveMessage;
+}
+
+/**
+ * Authentication helpers - data types and meta-command compilation for user/key/ACL management.
+ */
+interface UserInfo {
+    username: string;
+    role: string;
+}
+interface ApiKeyInfo {
+    label: string;
+    createdAt: string;
+}
+interface AclEntry {
+    username: string;
+    role: string;
+}
+
+/**
+ * Session - ephemeral facts and rules (no + prefix).
+ */
+
+/**
+ * Manage session-scoped (ephemeral) data.
+ *
+ * Session inserts and rules omit the + prefix, making them ephemeral
+ * (cleared on disconnect or KG switch).
+ */
+declare class Session {
+    private readonly conn;
+    constructor(connection: Connection);
+    /** Insert ephemeral session facts (no + prefix). */
+    insert(rel: RelationDef, facts: Fact | Fact[]): Promise<void>;
+    /** Define session-scoped rules (no + prefix). */
+    defineRules(headName: string, headColumns: string[], clauses: RuleClause[]): Promise<void>;
+    /** List session rules. */
+    listRules(): Promise<string[]>;
+    /** Drop a session rule by name, or a specific clause by index. */
+    dropRule(name: string, index?: number): Promise<void>;
+    /** Clear all session facts and rules. */
+    clear(): Promise<void>;
+}
+
+/**
+ * KnowledgeGraph - the primary workspace for data, queries, and rules.
+ */
+
+interface RelationInfo {
+    name: string;
+    rowCount: number;
+}
+interface ColumnInfo {
+    name: string;
+    type: string;
+}
+interface RelationDescription {
+    name: string;
+    columns: ColumnInfo[];
+    rowCount: number;
+    sample: Array<Record<string, unknown>>;
+}
+interface RuleInfo {
+    name: string;
+    clauseCount: number;
+}
+interface IndexInfo {
+    name: string;
+    relation: string;
+    column: string;
+    metric: string;
+    rowCount: number;
+}
+interface IndexStats {
+    name: string;
+    rowCount: number;
+    layers: number;
+    memoryBytes: number;
+}
+interface InsertResult {
+    count: number;
+}
+interface DeleteResult {
+    count: number;
+}
+interface ClearResult {
+    relationsCleared: number;
+    factsCleared: number;
+    details: Array<[string, number]>;
+}
+interface ExplainResult {
+    iql: string;
+    plan: string;
+}
+interface ServerStatus {
+    version: string;
+    knowledgeGraph: string;
+}
+/**
+ * Primary workspace for interacting with a knowledge graph.
+ */
+declare class KnowledgeGraph {
+    private readonly _name;
+    private readonly conn;
+    private readonly _session;
+    private kgActive;
+    constructor(name: string, connection: Connection);
+    get name(): string;
+    get session(): Session;
+    /** Ensure the connection is using this knowledge graph. */
+    private ensureKg;
+    /** Deploy schema definitions. Idempotent. */
+    define(...relations: RelationDef[]): Promise<void>;
+    /** List all relations in this KG. */
+    relations(): Promise<RelationInfo[]>;
+    /** Describe a relation's schema. */
+    describe(relation: RelationDef | string): Promise<RelationDescription>;
+    /** Drop a relation and all its data. */
+    dropRelation(relation: RelationDef | string): Promise<void>;
+    /** Insert facts into the knowledge graph. */
+    insert(rel: RelationDef, facts: Fact | Fact[]): Promise<InsertResult>;
+    /**
+     * Delete facts from the knowledge graph.
+     *
+     * @param rel - The relation definition
+     * @param factsOrCondition - Either specific facts to delete, or a BoolExpr condition
+     */
+    delete(rel: RelationDef, factsOrCondition: Fact | Fact[] | BoolExpr): Promise<DeleteResult>;
+    /**
+     * Query the knowledge graph.
+     *
+     * @example
+     * // Simple query
+     * const result = await kg.query({ select: [Employee] });
+     *
+     * // Filter
+     * const result = await kg.query({
+     *   select: [Employee.col("name"), Employee.col("salary")],
+     *   join: [Employee],
+     *   where: Employee.col("department").eq("eng"),
+     * });
+     *
+     * // Join
+     * const result = await kg.query({
+     *   select: [Employee.col("name"), Department.col("budget")],
+     *   join: [Employee, Department],
+     *   on: Employee.col("department").eq(Department.col("name")),
+     * });
+     */
+    query(opts: QueryOptions): Promise<ResultSet>;
+    /**
+     * Stream query results in batches.
+     *
+     * Returns an async generator yielding arrays of rows.
+     */
+    queryStream(opts: QueryOptions & {
+        batchSize?: number;
+    }): AsyncIterableIterator<Array<Record<string, unknown>>>;
+    /**
+     * Perform a vector similarity search.
+     */
+    vectorSearch(opts: {
+        relation: RelationDef;
+        queryVec: number[];
+        column?: string;
+        k?: number;
+        radius?: number;
+        metric?: 'cosine' | 'euclidean' | 'manhattan' | 'dot_product';
+    }): Promise<ResultSet>;
+    /** Deploy persistent rule definitions. */
+    defineRules(headName: string, headColumns: string[], clauses: RuleClause[]): Promise<void>;
+    /** List all rules in this KG. */
+    listRules(): Promise<RuleInfo[]>;
+    /** Get the IQL definition of a rule. */
+    ruleDefinition(name: string): Promise<string[]>;
+    /** Drop all clauses of a rule. */
+    dropRule(name: string): Promise<void>;
+    /** Remove a specific clause from a rule (1-based index). */
+    dropRuleClause(name: string, index: number): Promise<void>;
+    /** Replace a specific rule clause (remove + re-add). */
+    editRuleClause(name: string, index: number, headColumns: string[], clause: RuleClause): Promise<void>;
+    /** Clear a rule's materialized data. */
+    clearRule(name: string): Promise<void>;
+    /** Drop all rules whose names start with prefix. */
+    dropRulesByPrefix(prefix: string): Promise<void>;
+    /** Create an HNSW vector index. */
+    createIndex(index: HnswIndex): Promise<void>;
+    /** List all indexes. */
+    listIndexes(): Promise<IndexInfo[]>;
+    /** Get statistics for an index. */
+    indexStats(name: string): Promise<IndexStats>;
+    /** Drop an index. */
+    dropIndex(name: string): Promise<void>;
+    /** Rebuild an index. */
+    rebuildIndex(name: string): Promise<void>;
+    /** Grant per-KG access. */
+    grantAccess(username: string, role: string): Promise<void>;
+    /** Revoke per-KG access. */
+    revokeAccess(username: string): Promise<void>;
+    /** List ACL entries. */
+    listAcl(): Promise<AclEntry[]>;
+    /** Show the query plan without executing. */
+    explain(opts: QueryOptions): Promise<ExplainResult>;
+    /** Trigger storage compaction. */
+    compact(): Promise<void>;
+    /** Get server status. */
+    status(): Promise<ServerStatus>;
+    /** Load data from a file on the server. */
+    load(path: string, mode?: string): Promise<void>;
+    /** Clear all relations matching a prefix. */
+    clearPrefix(prefix: string): Promise<ClearResult>;
+    /** Execute raw IQL. */
+    execute(iql: string): Promise<ResultSet>;
+}
+
+/**
+ * InputLayer - top-level async client.
+ */
+
+interface InputLayerOptions {
+    /** WebSocket URL (e.g. "ws://localhost:8080/ws") */
+    url: string;
+    /** Username for login auth */
+    username?: string;
+    /** Password for login auth */
+    password?: string;
+    /** API key for token auth */
+    apiKey?: string;
+    /** Enable auto-reconnect on connection loss (default: true) */
+    autoReconnect?: boolean;
+    /** Delay between reconnect attempts in seconds (default: 1.0) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts before giving up (default: 10) */
+    maxReconnectAttempts?: number;
+    /** Initial knowledge graph to use (default: "default") */
+    initialKg?: string;
+    /** Last notification sequence for replay on reconnect */
+    lastSeq?: number;
+}
+/**
+ * Async client for InputLayer knowledge graph engine.
+ *
+ * @example
+ * ```typescript
+ * import { InputLayer, relation } from 'inputlayer';
+ *
+ * const Employee = relation("Employee", {
+ *   id: "int",
+ *   name: "string",
+ *   department: "string",
+ *   salary: "float",
+ *   active: "bool",
+ * });
+ *
+ * const il = new InputLayer({ url: "ws://localhost:8080/ws", username: "admin", password: "admin" });
+ * await il.connect();
+ *
+ * const kg = il.knowledgeGraph("default");
+ * await kg.define(Employee);
+ * await kg.insert(Employee, { id: 1, name: "Alice", department: "eng", salary: 120000, active: true });
+ * const result = await kg.query({ select: [Employee] });
+ *
+ * await il.close();
+ * ```
+ */
+declare class InputLayer {
+    private readonly conn;
+    private readonly kgs;
+    constructor(opts: InputLayerOptions);
+    /** Connect and authenticate. */
+    connect(): Promise<void>;
+    /** Close the connection. */
+    close(): Promise<void>;
+    get connected(): boolean;
+    get sessionId(): string | undefined;
+    get serverVersion(): string | undefined;
+    get role(): string | undefined;
+    get lastSeq(): number;
+    /** Get a KnowledgeGraph handle. Switches the session's active KG. */
+    knowledgeGraph(name: string): KnowledgeGraph;
+    /** List all knowledge graphs. */
+    listKnowledgeGraphs(): Promise<string[]>;
+    /** Drop a knowledge graph. */
+    dropKnowledgeGraph(name: string): Promise<void>;
+    createUser(username: string, password: string, role?: string): Promise<void>;
+    dropUser(username: string): Promise<void>;
+    setPassword(username: string, newPassword: string): Promise<void>;
+    setRole(username: string, role: string): Promise<void>;
+    listUsers(): Promise<UserInfo[]>;
+    /** Create an API key. Returns the key string. */
+    createApiKey(label: string): Promise<string>;
+    listApiKeys(): Promise<ApiKeyInfo[]>;
+    revokeApiKey(label: string): Promise<void>;
+    /**
+     * Register a notification callback.
+     *
+     * @param eventType - Filter by event type (e.g. "persistent_update")
+     * @param callback - Function to call when event arrives
+     * @param opts - Additional filters
+     */
+    on(eventType: string, callback: NotificationCallback, opts?: {
+        relation?: string;
+        knowledgeGraph?: string;
+    }): void;
+    /** Remove a notification callback. */
+    off(callback: NotificationCallback): void;
+    /** Async iterator yielding notification events. */
+    notifications(): AsyncIterableIterator<NotificationEvent>;
+}
+
+/**
+ * Naming convention utilities: CamelCase <-> snake_case, column -> IQL variable.
+ */
+/** Convert CamelCase class name to snake_case relation name. */
+declare function camelToSnake(name: string): string;
+/** Convert snake_case to CamelCase. */
+declare function snakeToCamel(name: string): string;
+/** Convert a snake_case column name to a IQL variable (Capitalized). */
+declare function columnToVariable(columnName: string): string;
+
+export { type AclEntry, AggExpr, type ApiKeyInfo, type AuthErrorResponse, type AuthenticateMessage, type AuthenticatedResponse, AuthenticationError, BoolExpr, CannotDropError, type ClearResult, type ClientMessage, Column, type ColumnInfo, ColumnProxy, type ColumnTypes, Connection, ConnectionError, type ConnectionOptions, type DeleteResult, type ErrorResponse, type ExecuteMessage, type ExplainResult, Expr, Fact, HnswIndex, type HnswIndexOptions, IQLType, type IndexInfo, IndexNotFoundError, type IndexStats, InputLayer, InputLayerError, type InputLayerOptions, type InsertResult, InternalError, KnowledgeGraph, KnowledgeGraphExistsError, KnowledgeGraphNotFoundError, type LoginMessage, type NotificationCallback, NotificationDispatcher, type NotificationEvent, type NotificationResponse, PermissionError, type PingMessage, type PongResponse, type QueryOptions, QueryTimeoutError, RelationDef, type RelationDescription, type RelationInfo, RelationNotFoundError, RelationProxy, RelationRef, type ResultChunkResponse, type ResultEndResponse, type ResultResponse, ResultSet, type ResultSetOptions, type ResultStartResponse, type RuleClause, type RuleInfo, RuleNotFoundError, SchemaConflictError, type ServerMessage, type ServerStatus, Session, type UserInfo, ValidationError, avg, camelToSnake, columnToVariable, compileBoolExpr, compileBulkInsert, compileConditionalDelete, compileDelete, compileExpr, compileInsert, compileQuery, compileRule, compileSchema, compileValue, count, countDistinct, deserializeMessage, from, getColumnTypes, getColumns, max, min, relation, resolveRelationName, serializeMessage, snakeToCamel, sum, topK, topKThreshold, withinRadius };