Graph retrieval

/**
 * Low-level Cypher execution API used by `GraphRAGRetriever`.
 *
 * Distinct from the existing `GraphStore` interface in `./types.ts`, which is
 * a higher-level semantic entity graph (nodes/edges by entity type, used by
 * `GraphMemory`). `CypherStore` exposes raw Cypher for LLM-to-Cypher use cases.
 */
export interface CypherRecord {
    values: Record<string, unknown>;
}

export interface CypherSchema {
    nodeLabels: string[];
    relationshipTypes: string[];
    propertyKeys?: string[];
}

export interface CypherStore {
    readonly providerId: string;
    connect(): Promise<void>;
    runCypher(cypher: string, params?: Record<string, unknown>): Promise<CypherRecord[]>;
    getSchema(): Promise<CypherSchema>;
    close(): Promise<void>;
}

export interface GraphEdge {
    id: string;
    sourceId: string;
    targetId: string;
    type: string;
    properties: Record<string, unknown>;
    weight?: number;
    validFrom: Date;
    invalidatedAt?: Date;
    createdAt: Date;
}

export interface GraphNode {
    id: string;
    type: string;
    name: string;
    properties: Record<string, unknown>;
    validFrom: Date;
    invalidatedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
}

export interface GraphNodeQuery {
    type?: string;
    name?: string;
    properties?: Record<string, unknown>;
}

export interface GraphRAGResult {
    cypher: string;
    records: CypherRecord[];
    /** Plain-text rendering of the records, useful as RAG context. */
    text: string;
}

export declare class GraphRAGRetriever {
    constructor(config: GraphRAGRetrieverConfig);
    /** Translate a natural-language query to Cypher, run it, and return rows. */
    retrieve(query: string): Promise<GraphRAGResult>;
}

export interface GraphRAGRetrieverConfig {
    store: CypherStore;
    model: ModelProvider;
    /** Optional system prompt prepended to the LLM-to-Cypher call. */
    systemPrompt?: string;
    /** Max records returned from a single query (after `LIMIT` is appended if missing). */
    maxRecords?: number;
}

export interface GraphSearchOptions {
    nodeTypes?: string[];
    limit?: number;
}

export interface GraphStore {
    initialize(): Promise<void>;
    addNode(node: Omit<GraphNode, "createdAt" | "updatedAt">): Promise<GraphNode>;
    getNode(id: string): Promise<GraphNode | null>;
    updateNode(id: string, patch: Partial<Pick<GraphNode, "name" | "properties" | "invalidatedAt">>): Promise<void>;
    deleteNode(id: string): Promise<void>;
    findNodes(query: GraphNodeQuery): Promise<GraphNode[]>;
    addEdge(edge: Omit<GraphEdge, "id" | "createdAt">): Promise<GraphEdge>;
    getEdges(nodeId: string, direction?: "in" | "out" | "both"): Promise<GraphEdge[]>;
    deleteEdge(id: string): Promise<void>;
    traverse(startNodeId: string, options?: GraphTraversalOptions): Promise<{
        nodes: GraphNode[];
        edges: GraphEdge[];
    }>;
    search(query: string, options?: GraphSearchOptions): Promise<GraphNode[]>;
    close(): Promise<void>;
}

export interface GraphTraversalOptions {
    maxDepth?: number;
    edgeTypes?: string[];
    nodeTypes?: string[];
    includeInvalid?: boolean;
}

export interface HybridResult {
    /** Source label (which sub-retriever produced the row). */
    source: "vector" | "graph";
    /** Stable identifier. */
    id: string;
    /** Text rendering. */
    content: string;
    /** RRF / rerank score. */
    score: number;
}

/**
 * Compose vector retrieval + graph retrieval into a single pipeline:
 *
 *   1. Run both sub-retrievers in parallel.
 *   2. Fuse with reciprocal rank fusion (default k=60).
 *   3. Optionally rerank the top fused set.
 */
export declare class HybridRetriever {
    constructor(config: HybridRetrieverConfig);
    retrieve(query: string): Promise<HybridResult[]>;
}

export interface HybridRetrieverConfig {
    /** Vector backend (for semantic search). */
    vector?: {
        store: VectorStore;
        collection: string;
        topK?: number;
    };
    /** Graph backend (for structured reasoning). */
    graph?: {
        retriever: GraphRAGRetriever;
    };
    /** Optional reranker for the fused result set. */
    rerank?: Reranker;
    /** Max results returned from the fused pipeline. */
    topK?: number;
}

export declare class InMemoryGraphStore implements GraphStore {
    initialize(): Promise<void>;
    addNode(node: Omit<GraphNode, "createdAt" | "updatedAt">): Promise<GraphNode>;
    getNode(id: string): Promise<GraphNode | null>;
    updateNode(id: string, patch: Partial<Pick<GraphNode, "name" | "properties" | "invalidatedAt">>): Promise<void>;
    deleteNode(id: string): Promise<void>;
    findNodes(query: GraphNodeQuery): Promise<GraphNode[]>;
    addEdge(edge: Omit<GraphEdge, "id" | "createdAt">): Promise<GraphEdge>;
    getEdges(nodeId: string, direction?: "in" | "out" | "both"): Promise<GraphEdge[]>;
    deleteEdge(id: string): Promise<void>;
    traverse(startNodeId: string, options?: GraphTraversalOptions): Promise<{
        nodes: GraphNode[];
        edges: GraphEdge[];
    }>;
    search(query: string, options?: GraphSearchOptions): Promise<GraphNode[]>;
    close(): Promise<void>;
}

/**
 * Memgraph reuses the Bolt protocol so we just inherit Neo4jCypherStore.
 */
export declare class MemgraphCypherStore extends Neo4jCypherStore {
    readonly providerId = "memgraph";
    constructor(config?: Neo4jCypherStoreConfig);
}

/**
 * Neo4j-backed Cypher store. Lazily loads `neo4j-driver` (already an optional
 * peer dep on @agentium/core).
 */
export declare class Neo4jCypherStore implements CypherStore {
    readonly providerId: string;
    constructor(config?: Neo4jCypherStoreConfig);
    connect(): Promise<void>;
    runCypher(cypher: string, params?: Record<string, unknown>): Promise<CypherRecord[]>;
    getSchema(): Promise<CypherSchema>;
    close(): Promise<void>;
}

export interface Neo4jCypherStoreConfig {
    uri?: string;
    username?: string;
    password?: string;
    database?: string;
}

/**
 * Neo4j-backed graph store. Requires `neo4j-driver` as a peer dependency.
 *
 * Install: npm install neo4j-driver
 */
export declare class Neo4jGraphStore implements GraphStore {
    constructor(config: Neo4jGraphStoreConfig);
    initialize(): Promise<void>;
    addNode(node: Omit<GraphNode, "createdAt" | "updatedAt">): Promise<GraphNode>;
    getNode(id: string): Promise<GraphNode | null>;
    updateNode(id: string, patch: Partial<Pick<GraphNode, "name" | "properties" | "invalidatedAt">>): Promise<void>;
    deleteNode(id: string): Promise<void>;
    findNodes(query: GraphNodeQuery): Promise<GraphNode[]>;
    addEdge(edge: Omit<GraphEdge, "id" | "createdAt">): Promise<GraphEdge>;
    getEdges(nodeId: string, direction?: "in" | "out" | "both"): Promise<GraphEdge[]>;
    deleteEdge(id: string): Promise<void>;
    traverse(startNodeId: string, options?: GraphTraversalOptions): Promise<{
        nodes: GraphNode[];
        edges: GraphEdge[];
    }>;
    search(query: string, options?: GraphSearchOptions): Promise<GraphNode[]>;
    close(): Promise<void>;
}

export interface Neo4jGraphStoreConfig {
    uri: string;
    username: string;
    password: string;
    database?: string;
}