@eucoder/rag 0.2.0 → 0.3.0

package/src/neo4j-knowledge-graph.ts

@@ -0,0 +1,357 @@
+import neo4j, { Driver, ManagedTransaction } from "neo4j-driver";
+import type { Entity, Relation, AsyncKnowledgeGraph } from "./types.js";
+
+export interface Neo4jConfig {
+  uri: string;
+  username: string;
+  password: string;
+  database?: string;
+}
+
+/**
+ * Knowledge Graph persistente con Neo4j
+ * 
+ * Implementa un grafo di conoscenza persistente usando Neo4j come database.
+ * Supporta operazioni CRUD per entità e relazioni, query per trovare entità connesse,
+ * e gestione delle transazioni.
+ */
+export class Neo4jKnowledgeGraph implements AsyncKnowledgeGraph {
+  private driver: Driver;
+  private database: string;
+
+  constructor(config: Neo4jConfig) {
+    this.driver = neo4j.driver(
+      config.uri,
+      neo4j.auth.basic(config.username, config.password)
+    );
+    this.database = config.database || "neo4j";
+  }
+
+  /**
+   * Chiude la connessione al database
+   */
+  async close(): Promise<void> {
+    await this.driver.close();
+  }
+
+  /**
+   * Verifica la connessione al database
+   */
+  async verifyConnectivity(): Promise<boolean> {
+    try {
+      await this.driver.verifyConnectivity();
+      return true;
+    } catch (error) {
+      console.error("Neo4j connectivity check failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Inizializza gli indici e i vincoli del database
+   */
+  async initializeSchema(): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      // Crea indice univoco per Entity.id
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(`
+          CREATE INDEX entity_id_index IF NOT EXISTS
+          FOR (e:Entity) ON (e.id)
+        `);
+      });
+
+      // Crea indice per Entity.type
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(`
+          CREATE INDEX entity_type_index IF NOT EXISTS
+          FOR (e:Entity) ON (e.type)
+        `);
+      });
+
+      // Crea indice per Relation.type
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(`
+          CREATE INDEX relation_type_index IF NOT EXISTS
+          FOR ()-[r:RELATES_TO]-() ON (r.type)
+        `);
+      });
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Aggiunge un'entità al grafo
+   */
+  async addEntity(entity: Entity): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(
+          `
+          MERGE (e:Entity {id: $id})
+          SET e.name = $name,
+              e.type = $type,
+              e.properties = $properties,
+              e.updatedAt = datetime()
+          `,
+          {
+            id: entity.id,
+            name: entity.name,
+            type: entity.type,
+            properties: JSON.stringify(entity.properties || {}),
+          }
+        );
+      });
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Aggiunge una relazione al grafo
+   */
+  async addRelation(relation: Relation): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(
+          `
+          MATCH (source:Entity {id: $sourceId})
+          MATCH (target:Entity {id: $targetId})
+          MERGE (source)-[r:RELATES_TO {id: $id}]->(target)
+          SET r.type = $type,
+              r.properties = $properties,
+              r.updatedAt = datetime()
+          `,
+          {
+            id: relation.id,
+            sourceId: relation.source,
+            targetId: relation.target,
+            type: relation.type,
+            properties: JSON.stringify(relation.properties || {}),
+          }
+        );
+      });
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Recupera un'entità per ID
+   */
+  async getEntity(id: string): Promise<Entity | undefined> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const result = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(
+          `
+          MATCH (e:Entity {id: $id})
+          RETURN e.id AS id, e.name AS name, e.type AS type, e.properties AS properties
+          `,
+          { id }
+        );
+      });
+
+      if (result.records.length === 0) {
+        return undefined;
+      }
+
+      const record = result.records[0];
+      return {
+        id: record.get("id"),
+        name: record.get("name"),
+        type: record.get("type"),
+        properties: JSON.parse(record.get("properties") || "{}"),
+      };
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Recupera tutte le relazioni di un'entità
+   */
+  async getRelations(entityId: string): Promise<Relation[]> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const result = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(
+          `
+          MATCH (e:Entity {id: $entityId})-[r:RELATES_TO]-(other:Entity)
+          RETURN r.id AS id, 
+                 r.type AS type, 
+                 r.properties AS properties,
+                 startNode(r).id AS source,
+                 endNode(r).id AS target
+          `,
+          { entityId }
+        );
+      });
+
+      return result.records.map((record) => ({
+        id: record.get("id"),
+        type: record.get("type"),
+        properties: JSON.parse(record.get("properties") || "{}"),
+        source: record.get("source"),
+        target: record.get("target"),
+      }));
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Recupera tutte le entità connesse a un'entità fino a una certa profondità
+   */
+  async getConnectedEntities(entityId: string, depth: number = 1): Promise<Entity[]> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const result = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(
+          `
+          MATCH path = (start:Entity {id: $entityId})-[:RELATES_TO*1..${depth}]-(connected:Entity)
+          WHERE connected.id <> $entityId
+          RETURN DISTINCT connected.id AS id, 
+                          connected.name AS name, 
+                          connected.type AS type, 
+                          connected.properties AS properties
+          `,
+          { entityId }
+        );
+      });
+
+      return result.records.map((record) => ({
+        id: record.get("id"),
+        name: record.get("name"),
+        type: record.get("type"),
+        properties: JSON.parse(record.get("properties") || "{}"),
+      }));
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Cerca entità per nome o tipo
+   */
+  async searchEntities(query: { name?: string; type?: string }): Promise<Entity[]> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const conditions: string[] = [];
+      const params: Record<string, any> = {};
+
+      if (query.name) {
+        conditions.push("e.name CONTAINS $name");
+        params.name = query.name;
+      }
+
+      if (query.type) {
+        conditions.push("e.type = $type");
+        params.type = query.type;
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+
+      const result = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(
+          `
+          MATCH (e:Entity)
+          ${whereClause}
+          RETURN e.id AS id, e.name AS name, e.type AS type, e.properties AS properties
+          LIMIT 100
+          `,
+          params
+        );
+      });
+
+      return result.records.map((record) => ({
+        id: record.get("id"),
+        name: record.get("name"),
+        type: record.get("type"),
+        properties: JSON.parse(record.get("properties") || "{}"),
+      }));
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Elimina un'entità e tutte le sue relazioni
+   */
+  async deleteEntity(entityId: string): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(
+          `
+          MATCH (e:Entity {id: $entityId})
+          DETACH DELETE e
+          `,
+          { entityId }
+        );
+      });
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Elimina una relazione per ID
+   */
+  async deleteRelation(relationId: string): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(
+          `
+          MATCH ()-[r:RELATES_TO {id: $relationId}]-()
+          DELETE r
+          `,
+          { relationId }
+        );
+      });
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Recupera statistiche del grafo
+   */
+  async getStats(): Promise<{ entityCount: number; relationCount: number }> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const entityResult = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(`MATCH (e:Entity) RETURN count(e) AS count`);
+      });
+
+      const relationResult = await session.executeRead(async (tx: ManagedTransaction) => {
+        return await tx.run(`MATCH ()-[r:RELATES_TO]-() RETURN count(r) AS count`);
+      });
+
+      return {
+        entityCount: entityResult.records[0].get("count").toNumber(),
+        relationCount: relationResult.records[0].get("count").toNumber(),
+      };
+    } finally {
+      await session.close();
+    }
+  }
+
+  /**
+   * Pulisce completamente il grafo (elimina tutte le entità e relazioni)
+   */
+  async clear(): Promise<void> {
+    const session = this.driver.session({ database: this.database });
+    try {
+      await session.executeWrite(async (tx: ManagedTransaction) => {
+        await tx.run(`MATCH (n) DETACH DELETE n`);
+      });
+    } finally {
+      await session.close();
+    }
+  }
+}

package/src/types.ts

@@ -88,6 +88,20 @@ export interface KnowledgeGraph {
   getConnectedEntities(entityId: string, depth?: number): Entity[];
 }
 
+export interface AsyncKnowledgeGraph {
+  addEntity(entity: Entity): Promise<void>;
+  addRelation(relation: Relation): Promise<void>;
+  getEntity(id: string): Promise<Entity | undefined>;
+  getRelations(entityId: string): Promise<Relation[]>;
+  getConnectedEntities(entityId: string, depth?: number): Promise<Entity[]>;
+  searchEntities(query: { name?: string; type?: string }): Promise<Entity[]>;
+  deleteEntity(entityId: string): Promise<void>;
+  deleteRelation(relationId: string): Promise<void>;
+  getStats(): Promise<{ entityCount: number; relationCount: number }>;
+  clear(): Promise<void>;
+  close(): Promise<void>;
+}
+
 export interface EntityExtractor {
   extract(text: string): Promise<Entity[]>;
 }