┌──────────────────────────────┐
   user question  ──────────▶│  GraphRAGRetriever            │
                              │   1. get live schema (labels, │
                              │      relationship types,      │
                              │      property keys)           │
                              │   2. LLM ➜ Cypher              │
                              │   3. ensure LIMIT              │
                              │   4. run Cypher                │
                              └──────────┬───────────────────┘
                                         │
                                         ▼
                              ┌──────────────────────────────┐
                              │       CypherStore             │
                              │   neo4j-driver or compatible  │
                              └──────────────────────────────┘

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

interface CypherRecord {
  values: Record<string, unknown>;   // column name -> value
}

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

import { Neo4jCypherStore } from "@agentium/core";

const store = new Neo4jCypherStore({
  uri: process.env.NEO4J_URI ?? "bolt://localhost:7687",
  username: process.env.NEO4J_USER ?? "neo4j",
  password: process.env.NEO4J_PASSWORD ?? "neo4j",
  database: "neo4j",                   // optional, default is "neo4j"
});
await store.connect();

import { MemgraphCypherStore } from "@agentium/core";

const store = new MemgraphCypherStore({
  uri: process.env.MEMGRAPH_URI ?? "bolt://localhost:7687",
  username: process.env.MEMGRAPH_USER,
  password: process.env.MEMGRAPH_PASSWORD,
});

const rows = await store.runCypher(
  "MATCH (p:Person {name: $name})-[:KNOWS]->(other) RETURN other.name AS knows",
  { name: "Alice" },
);
for (const r of rows) console.log(r.values.knows);

const schema = await store.getSchema();
console.log(schema.nodeLabels);          // ["Person", "Project"]
console.log(schema.relationshipTypes);   // ["KNOWS", "WORKS_ON"]
console.log(schema.propertyKeys);        // ["name", "email", "title"]

import { GraphRAGRetriever, Neo4jCypherStore, openai } from "@agentium/core";

const store = new Neo4jCypherStore({ /* ... */ });
await store.connect();

const retriever = new GraphRAGRetriever({
  store,
  model: openai("gpt-4o"),
  maxRecords: 25,             // default 25 - auto-appends LIMIT 25 if missing
  systemPrompt: undefined,    // optional override - see below
});

const result = await retriever.retrieve("Who works on the Atlas project?");
console.log(result.cypher);   // "MATCH (p:Person)-[:WORKS_ON]->(:Project {name: 'Atlas'}) RETURN p.name LIMIT 25"
console.log(result.text);     // "name=Alice\nname=Bob"

interface GraphRAGResult {
  cypher: string;          // the Cypher the model generated (post-LIMIT-injection)
  records: CypherRecord[]; // raw rows from the DB
  text: string;            // plain-text rendering of records (great as RAG context)
}

You convert a natural-language question into a Cypher query that runs against a Neo4j-compatible graph.
Rules:
1. Use ONLY the labels and relationship types listed in the schema.
2. Return only Cypher - no prose, no markdown fences.
3. Always end with a LIMIT clause (default 25 rows).
4. Prefer MATCH ... RETURN over WRITE operations.

import {
  GraphRAGRetriever,
  HybridRetriever,
  InMemoryVectorStore,
  Neo4jCypherStore,
  OpenAIEmbedding,
  openai,
  CohereReranker,
} from "@agentium/core";

const vector = new InMemoryVectorStore(new OpenAIEmbedding());
await vector.upsert("notes", { id: "1", content: "Alice manages Bob and Carol." });
await vector.upsert("notes", { id: "2", content: "Project Atlas is shipping in Q4." });

const graphStore = new Neo4jCypherStore({ /* ... */ });
await graphStore.connect();
const graph = new GraphRAGRetriever({ store: graphStore, model: openai("gpt-4o") });

const hybrid = new HybridRetriever({
  vector: { store: vector, collection: "notes", topK: 10 },
  graph: { retriever: graph },
  rerank: new CohereReranker(),
  topK: 5,
});

const results = await hybrid.retrieve("Who works on Atlas?");
for (const r of results) {
  console.log(`[${r.source}] ${r.score.toFixed(3)}  ${r.content}`);
}

interface HybridResult {
  source: "vector" | "graph"; // which retriever surfaced this
  id: string;                  // unique id, prefixed with v: or g:
  content: string;
  score: number;               // RRF or rerank score
}

interface HybridRetrieverConfig {
  vector?: { store: VectorStore; collection: string; topK?: number };
  graph?: { retriever: GraphRAGRetriever };
  rerank?: Reranker;
  topK?: number;     // default 10
}