@ai.ntellect/core 1.0.0 → 1.1.1

package/persistence/neo4j/execution-tracer.ts

@@ -0,0 +1,194 @@
+import { ZodSchema } from "zod";
+import { GraphFlow } from "../../execution";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export class Neo4jExecutionTracer {
+  private driver: Neo4jDriverLike;
+  private database?: string;
+  private unsubscribeFns: Array<() => void> = [];
+  private executionId: string;
+
+  private constructor(
+    driver: Neo4jDriverLike,
+    executionId: string,
+    database?: string
+  ) {
+    this.driver = driver;
+    this.executionId = executionId;
+    this.database = database;
+  }
+
+  static attach<T extends ZodSchema>(
+    graph: GraphFlow<T>,
+    driver: Neo4jDriverLike,
+    executionId?: string,
+    database?: string
+  ): Neo4jExecutionTracer {
+    const id = executionId || crypto.randomUUID();
+    const tracer = new Neo4jExecutionTracer(driver, id, database);
+
+    const onStarted = (data: any) => {
+      tracer.onNodeStarted(data).catch(() => {});
+    };
+    graph.on("nodeStarted", onStarted);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeStarted", onStarted);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeStarted", onStarted);
+      }
+    });
+
+    const onCompleted = (data: any) => {
+      tracer.onNodeCompleted(data).catch(() => {});
+    };
+    graph.on("nodeCompleted", onCompleted);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeCompleted", onCompleted);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeCompleted", onCompleted);
+      }
+    });
+
+    const onError = (data: any) => {
+      tracer.onNodeError(data).catch(() => {});
+    };
+    graph.on("nodeError", onError);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeError", onError);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeError", onError);
+      }
+    });
+
+    return tracer;
+  }
+
+  getExecutionId(): string {
+    return this.executionId;
+  }
+
+  detach(): void {
+    for (const fn of this.unsubscribeFns) {
+      fn();
+    }
+    this.unsubscribeFns = [];
+  }
+
+  async initExecution(
+    graphName: string,
+    startedAt: Date = new Date()
+  ): Promise<void> {
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MERGE (e:Execution {id: $id})
+         SET e.graphName = $graphName,
+             e.startedAt = $startedAt,
+             e.status = "running"`,
+        { id: this.executionId, graphName, startedAt: startedAt.toISOString() }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  async completeExecution(
+    status: "completed" | "failed" = "completed",
+    completedAt: Date = new Date()
+  ): Promise<void> {
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (e:Execution {id: $id})
+         SET e.status = $status,
+             e.completedAt = $completedAt`,
+        { id: this.executionId, status, completedAt: completedAt.toISOString() }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeStarted(data: {
+    name?: string;
+    payload?: { name?: string };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (e:Execution {id: $executionId})
+         MERGE (n:NodeRun {id: $nodeRunId})
+         SET n.name = $name,
+             n.startedAt = $startedAt,
+             n.status = "running"
+         MERGE (e)-[:HAS_RUN]->(n)`,
+        {
+          executionId: this.executionId,
+          nodeRunId,
+          name,
+          startedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeCompleted(data: {
+    name?: string;
+    payload?: { name?: string; context?: any };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (n:NodeRun {id: $nodeRunId})
+         SET n.status = "completed",
+             n.completedAt = $completedAt`,
+        {
+          nodeRunId,
+          completedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeError(data: {
+    name?: string;
+    payload?: { name?: string; error?: any };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+    const errorMessage =
+      data.payload?.error?.message ||
+      data.payload?.error?.toString() ||
+      "Unknown error";
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (n:NodeRun {id: $nodeRunId})
+         SET n.status = "error",
+             n.error = $error,
+             n.completedAt = $completedAt`,
+        {
+          nodeRunId,
+          error: errorMessage,
+          completedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+}

package/persistence/neo4j/memory-adapter.ts

@@ -0,0 +1,281 @@
+import { IGraphMemoryAdapter, MemoryRelation } from "../../interfaces";
+import {
+  BaseMemoryType,
+  CreateMemoryInput,
+} from "../../types";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export class Neo4jMemoryAdapter implements IGraphMemoryAdapter {
+  constructor(
+    private driver: Neo4jDriverLike,
+    private database?: string
+  ) {}
+
+  private session(): Neo4jSessionLike {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async init(roomId?: string): Promise<void> {
+    if (!roomId) return;
+    const s = this.session();
+    try {
+      await s.run(
+        `MERGE (:Room {id: $roomId})`,
+        { roomId }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined> {
+    const memory: BaseMemoryType = {
+      id: input.id || crypto.randomUUID(),
+      content: input.content,
+      metadata: input.metadata,
+      embedding: input.embedding,
+      roomId: input.roomId,
+      createdAt: new Date(),
+    };
+
+    const s = this.session();
+    try {
+      await s.run(
+        `MERGE (r:Room {id: $roomId})
+         CREATE (m:Memory {
+           id: $id,
+           content: $content,
+           createdAt: $createdAt,
+           metadata: $metadata
+         })
+         MERGE (m)-[:IN_ROOM]->(r)
+         RETURN m`,
+        {
+          roomId: memory.roomId,
+          id: memory.id,
+          content: memory.content,
+          createdAt: memory.createdAt.toISOString(),
+          metadata: memory.metadata ? JSON.stringify(memory.metadata) : null,
+        }
+      );
+
+      if (memory.embedding) {
+        try {
+          await s.run(
+            `MATCH (m:Memory {id: $id})
+             SET m.embedding = $embedding`,
+            { id: memory.id, embedding: memory.embedding }
+          );
+        } catch {
+          // vector index may not exist; embedding stored as best-effort
+        }
+      }
+
+      return memory;
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (m:Memory {id: $id})-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m`,
+        { id, roomId }
+      );
+
+      if (result.records.length === 0) return null;
+      return this.recordToMemory(result.records[0].get("m"));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `CALL db.index.fulltext.queryNodes("memory_content", $query)
+         YIELD node AS m, score
+         WHERE (m)-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m, score
+         ORDER BY score DESC
+         LIMIT toInteger($limit)`,
+        {
+          query,
+          roomId: options.roomId,
+          limit: options.limit || 10,
+        }
+      );
+
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } catch {
+      const result = await s.run(
+        `MATCH (m:Memory)-[:IN_ROOM]->(:Room {id: $roomId})
+         WHERE m.content CONTAINS $query
+         RETURN m
+         LIMIT toInteger($limit)`,
+        {
+          roomId: options.roomId,
+          query,
+          limit: options.limit || 10,
+        }
+      );
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (m:Memory)-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m
+         ORDER BY m.createdAt DESC`,
+        { roomId }
+      );
+
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clearMemoryById(id: string, roomId: string): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (m:Memory {id: $id})-[:IN_ROOM]->(:Room {id: $roomId})
+         DETACH DELETE m`,
+        { id, roomId }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clearAllMemories(): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(`MATCH (m:Memory) DETACH DELETE m`);
+    } finally {
+      await s.close();
+    }
+  }
+
+  async addRelation(relation: MemoryRelation): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (from:Memory {id: $fromId})
+         MATCH (to:Memory {id: $toId})
+         MERGE (from)-[r:RELATES_TO {type: $type}]->(to)
+         SET r.weight = $weight,
+             r.createdAt = $createdAt`,
+        {
+          fromId: relation.fromId,
+          toId: relation.toId,
+          type: relation.type,
+          weight: relation.properties?.weight ?? 1,
+          createdAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async removeRelation(
+    fromId: string,
+    toId: string,
+    type: string,
+    _roomId: string
+  ): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (from:Memory {id: $fromId})-[r:RELATES_TO {type: $type}]->(to:Memory {id: $toId})
+         DELETE r`,
+        { fromId, toId, type }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getRelated(
+    id: string,
+    options: {
+      roomId: string;
+      relationTypes?: string[];
+      direction?: "in" | "out" | "both";
+      depth?: number;
+      limit?: number;
+    }
+  ): Promise<Array<{ memory: BaseMemoryType; relationPath: string[] }>> {
+    const depth = options.depth ?? 1;
+    const direction = options.direction ?? "both";
+    const limit = options.limit ?? 10;
+
+    let directionPattern: string;
+    if (direction === "out") directionPattern = "(m:Memory)-[r:RELATES_TO]->(related)";
+    else if (direction === "in") directionPattern = "(m:Memory)<-[r:RELATES_TO]-(related)";
+    else directionPattern = "(m:Memory)-[r:RELATES_TO]-(related)";
+
+    let typeFilter = "";
+    if (options.relationTypes && options.relationTypes.length > 0) {
+      const types = options.relationTypes.map(t => `r.type = "${t}"`).join(" OR ");
+      typeFilter = `AND (${types})`;
+    }
+
+    const s = this.session();
+    try {
+      const query = depth === 1
+        ? `MATCH ${directionPattern}
+           WHERE m.id = $id ${typeFilter}
+           RETURN DISTINCT related AS related, [] AS path
+           LIMIT toInteger($limit)`
+        : `MATCH (m:Memory {id: $id})
+           CALL {
+             MATCH (m)-[r:RELATES_TO*1..${depth}]-(related:Memory)
+             WHERE m.id <> related.id ${typeFilter ? `AND ${typeFilter.replace(/r\./g, "r0.")}` : ""}
+             RETURN DISTINCT related, [r IN r | r.type] AS path
+           }
+           RETURN related, path
+           LIMIT toInteger($limit)`;
+
+      const result = await s.run(query, { id, limit });
+
+      return result.records.map((r: any) => ({
+        memory: this.recordToMemory(r.get("related")),
+        relationPath: r.get("path") || [],
+      }));
+    } finally {
+      await s.close();
+    }
+  }
+
+  private recordToMemory(record: any): BaseMemoryType {
+    const props = record.properties ? (typeof record.properties === "function" ? record.properties() : record.properties) : record;
+    return {
+      id: props.id,
+      content: props.content,
+      metadata: props.metadata ? (typeof props.metadata === "string" ? JSON.parse(props.metadata) : props.metadata) : undefined,
+      embedding: props.embedding,
+      roomId: props.roomId,
+      createdAt: new Date(props.createdAt),
+    };
+  }
+}

package/persistence/neo4j/petri-checkpoint-adapter.ts

@@ -0,0 +1,153 @@
+import { PetriNet } from "../../routing";
+import { Session } from "../../routing/orchestrator";
+import { IPetriCheckpointAdapter } from "../../routing/checkpoint-adapter";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export class Neo4jPetriCheckpointAdapter implements IPetriCheckpointAdapter {
+  constructor(
+    private driver: Neo4jDriverLike,
+    private database?: string
+  ) {}
+
+  private session(): Neo4jSessionLike {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async save(net: PetriNet, session?: Session): Promise<string> {
+    const checkpointId = `petri-cp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    const marking = (net as any).state.marking as Map<string, any[]>;
+    const serializedMarking: any[] = [];
+    for (const [pid, tokens] of marking) {
+      serializedMarking.push({
+        placeId: pid,
+        tokens: tokens.map((t: any) => ({ id: t.id, data: t.data, createdAt: t.createdAt })),
+      });
+    }
+
+    const s = this.session();
+    try {
+      await s.run(
+        `MERGE (s:PetriSession {id: $sessionId})
+         SET s.createdAt = $createdAt
+         WITH s
+         CREATE (c:Checkpoint {id: $checkpointId, timestamp: $timestamp, marking: $marking})
+         MERGE (s)-[:HAS_CHECKPOINT]->(c)`,
+        {
+          sessionId: session?.id || "anonymous",
+          createdAt: session?.createdAt ? new Date(session.createdAt).toISOString() : new Date().toISOString(),
+          checkpointId,
+          timestamp: Date.now(),
+          marking: JSON.stringify(serializedMarking),
+        }
+      );
+
+      if (session?.id) {
+        const history = (net as any).state.history || [];
+        for (const entry of history) {
+          await s.run(
+            `MATCH (s:PetriSession {id: $sessionId})
+             CREATE (f:TransitionFiring {id: $firingId, transitionId: $transitionId, seq: $seq, firedAt: $firedAt})
+             MERGE (s)-[:FIRED]->(f)`,
+            {
+              sessionId: session.id,
+              firingId: `firing-${session.id}-${entry.timestamp || Date.now()}-${Math.random().toString(36).substr(2, 6)}`,
+              transitionId: entry.transitionId || "unknown",
+              seq: entry.seq || 0,
+              firedAt: entry.timestamp ? new Date(entry.timestamp).toISOString() : new Date().toISOString(),
+            }
+          );
+        }
+      }
+
+      return checkpointId;
+    } finally {
+      await s.close();
+    }
+  }
+
+  async load(checkpointId: string): Promise<{ net: PetriNet; session?: Session } | null> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (c:Checkpoint {id: $checkpointId})
+         OPTIONAL MATCH (c)<-[:HAS_CHECKPOINT]-(sess:PetriSession)
+         RETURN c, sess`,
+        { checkpointId }
+      );
+
+      if (result.records.length === 0) return null;
+
+      const record = result.records[0];
+      const cp = record.get("c");
+      const sessRecord = record.get("sess");
+
+      if (!cp) return null;
+
+      const cpProps = cp.properties ? (typeof cp.properties === "function" ? cp.properties() : cp.properties) : cp;
+      const marking = JSON.parse(cpProps.marking || "[]");
+
+      const net = new PetriNet(cpProps.id || checkpointId);
+      const stateMarking = (net as any).state.marking as Map<string, any[]>;
+
+      for (const item of marking) {
+        stateMarking.set(
+          item.placeId,
+          item.tokens.map((t: any) => ({ ...t }))
+        );
+      }
+
+      (net as any).state.history = [];
+
+      let session: Session | undefined;
+      if (sessRecord) {
+        const sessProps = sessRecord.properties ? (typeof sessRecord.properties === "function" ? sessRecord.properties() : sessRecord.properties) : sessRecord;
+        session = {
+          id: sessProps.id || "restored",
+          petriNet: net,
+          context: {},
+          history: [],
+          createdAt: new Date(sessProps.createdAt || Date.now()),
+          traceId: `trace-restored-${Date.now()}`,
+        } as any;
+      }
+
+      return { net, session };
+    } finally {
+      await s.close();
+    }
+  }
+
+  async list(): Promise<Array<{ id: string; timestamp: number; sessionId?: string }>> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (c:Checkpoint)
+         OPTIONAL MATCH (c)<-[:HAS_CHECKPOINT]-(sess:PetriSession)
+         RETURN c.id AS id, c.timestamp AS timestamp, sess.id AS sessionId
+         ORDER BY c.timestamp DESC`
+      );
+
+      return result.records.map((r: any) => ({
+        id: r.get("id"),
+        timestamp: Number(r.get("timestamp")) || 0,
+        sessionId: r.get("sessionId") || undefined,
+      }));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async delete(checkpointId: string): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (c:Checkpoint {id: $checkpointId})
+         DETACH DELETE c`,
+        { checkpointId }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+}