@m6d/cortex-server 1.0.0

package/src/graph/resolver.ts

@@ -0,0 +1,357 @@
+/**
+ * Pre-resolves relevant API endpoints from the Neo4j knowledge graph
+ * using vector similarity search on concept descriptions.
+ *
+ * All configuration is passed explicitly — no hardcoded model references
+ * or environment variables.
+ */
+
+import type { EmbeddingModel } from "ai";
+import { embed } from "ai";
+import type { Neo4jClient } from "./neo4j.ts";
+import type { ConceptDef } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export type RerankerConfig = {
+  url: string;
+  apiKey: string;
+};
+
+export type ResolverConfig = {
+  neo4j: Neo4jClient;
+  embeddingModel: EmbeddingModel;
+  reranker?: RerankerConfig;
+};
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+type EndpointDependency = {
+  depPath: string;
+  depMethod: string;
+  paramName: string;
+  fromField: string;
+};
+
+type EndpointRelation = "read" | "write";
+
+export type ResolvedEndpoint = {
+  concept: string;
+  relation: EndpointRelation;
+  name: string;
+  path: string;
+  method: string;
+  params: string;
+  body: string;
+  response: string;
+  dependencies: EndpointDependency[];
+  rules: string[];
+};
+
+export type ResolvedService = {
+  concept: string;
+  serviceName: string;
+  builtInId: string;
+  description: string;
+  rules: string[];
+};
+
+export type ResolvedContext = {
+  readEndpoints: ResolvedEndpoint[];
+  writeEndpoints: ResolvedEndpoint[];
+  services: ResolvedService[];
+};
+
+// ---------------------------------------------------------------------------
+// Internal row types
+// ---------------------------------------------------------------------------
+
+type EndpointRow = {
+  concept: string;
+  relationType: "QUERIED_VIA" | "MUTATED_VIA";
+  name: string;
+  path: string;
+  method: string;
+  params: string | null;
+  body: string | null;
+  response: string | null;
+  dependencies: (EndpointDependency | { depPath: null })[];
+  rules: (string | null)[];
+};
+
+type ServiceRow = {
+  concept: string;
+  serviceName: string;
+  builtInId: string;
+  description: string | null;
+  rules: (string | null)[];
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
+  const empty: ResolvedContext = {
+    readEndpoints: [],
+    writeEndpoints: [],
+    services: [],
+  };
+
+  try {
+    const { embedding } = await embed({
+      model: config.embeddingModel,
+      value: prompt,
+    });
+
+    const conceptsRaw = await config.neo4j.query(
+      `CALL db.index.vector.queryNodes('concept_embeddings', 10, $embedding)
+             YIELD node, score
+             WHERE score > 0.3
+             RETURN node.name AS name, node.description AS description, score
+             ORDER BY score DESC`,
+      { embedding },
+    );
+
+    let concepts = JSON.parse(conceptsRaw) as (Pick<
+      ConceptDef,
+      "name" | "description"
+    > & { score: number })[];
+
+    if (!Array.isArray(concepts) || concepts.length === 0) {
+      return empty;
+    }
+
+    if (config.reranker) {
+      concepts = await computeRelevanceScores(
+        prompt,
+        concepts,
+        config.reranker,
+      );
+    } else {
+      concepts = concepts.slice(0, 3);
+    }
+
+    const conceptNames = concepts.map((c) => c.name);
+
+    const endpointsRaw = await config.neo4j.query(
+      `UNWIND $names AS conceptName
+             MATCH (c:Concept {name: conceptName})-[:SPECIALIZES*0..3]->(ancestor:Concept)
+             WITH conceptName, collect(DISTINCT ancestor) AS family
+             UNWIND family AS related
+             MATCH (related)-[rel:QUERIED_VIA|MUTATED_VIA]->(e:Endpoint)
+             WITH conceptName, related, rel, e
+             OPTIONAL MATCH (e)-[d:DEPENDS_ON]->(dep:Endpoint)
+             WITH conceptName, related, rel, e,
+                  collect(DISTINCT {
+                      depPath: dep.path,
+                      depMethod: dep.method,
+                      paramName: d.paramName,
+                      fromField: d.fromField
+                  }) AS dependencies
+             OPTIONAL MATCH (rEndpoint:Rule)-[:GOVERNS]->(e)
+             OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(related)
+             RETURN conceptName AS concept,
+                    type(rel) AS relationType,
+                    e.name AS name,
+                    e.path AS path,
+                    e.method AS method,
+                    e.params AS params,
+                    e.body AS body,
+                    e.response AS response,
+                    dependencies,
+                    collect(DISTINCT rEndpoint.description) +
+                    collect(DISTINCT rConcept.description) AS rules`,
+      { names: conceptNames },
+    );
+
+    const endpointRows = asArray<EndpointRow>(JSON.parse(endpointsRaw));
+    const allEndpoints = dedupeEndpoints(
+      endpointRows.map(function (row) {
+        return {
+          concept: row.concept,
+          relation:
+            row.relationType === "MUTATED_VIA"
+              ? ("write" as const)
+              : ("read" as const),
+          name: row.name,
+          path: row.path,
+          method: row.method,
+          params: row.params ?? "[]",
+          body: row.body ?? "[]",
+          response: row.response ?? "[]",
+          dependencies: row.dependencies.filter(
+            (dep): dep is EndpointDependency => dep.depPath != null,
+          ),
+          rules: row.rules.filter((rule): rule is string => Boolean(rule)),
+        };
+      }),
+    );
+
+    const servicesRaw = await config.neo4j.query(
+      `UNWIND $names AS conceptName
+             MATCH (c:Concept {name: conceptName})-[:SPECIALIZES*0..3]->(ancestor:Concept)
+             WITH conceptName, collect(DISTINCT ancestor) AS family
+             UNWIND family AS related
+             MATCH (related)-[:REQUESTED_VIA]->(svc:Service)
+             WITH conceptName, related, svc
+             OPTIONAL MATCH (rService:Rule)-[:GOVERNS]->(svc)
+             OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(related)
+             RETURN conceptName AS concept,
+                    svc.name AS serviceName,
+                    svc.builtInId AS builtInId,
+                    svc.description AS description,
+                    collect(DISTINCT rService.description) +
+                    collect(DISTINCT rConcept.description) AS rules`,
+      { names: conceptNames },
+    );
+
+    const services = dedupeServices(
+      asArray<ServiceRow>(JSON.parse(servicesRaw)).map(function (row) {
+        return {
+          concept: row.concept,
+          serviceName: row.serviceName,
+          builtInId: row.builtInId,
+          description: row.description ?? "",
+          rules: row.rules.filter((rule): rule is string => Boolean(rule)),
+        };
+      }),
+    );
+
+    // Service-to-Servicing bridge: if any services were resolved, pull in
+    // the generic Servicing endpoints
+    let servicingEndpoints: ResolvedEndpoint[] = [];
+    if (services.length > 0) {
+      const servicingRaw = await config.neo4j.query(
+        `MATCH (c:Concept {name: 'ServiceRequest'})-[rel:QUERIED_VIA|MUTATED_VIA]->(e:Endpoint)
+                 OPTIONAL MATCH (e)-[d:DEPENDS_ON]->(dep:Endpoint)
+                 WITH c, rel, e,
+                      collect(DISTINCT {
+                          depPath: dep.path,
+                          depMethod: dep.method,
+                          paramName: d.paramName,
+                          fromField: d.fromField
+                      }) AS dependencies
+                 OPTIONAL MATCH (rEndpoint:Rule)-[:GOVERNS]->(e)
+                 OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(c)
+                 RETURN 'ServiceRequest' AS concept,
+                        type(rel) AS relationType,
+                        e.name AS name,
+                        e.path AS path,
+                        e.method AS method,
+                        e.params AS params,
+                        e.body AS body,
+                        e.response AS response,
+                        dependencies,
+                        collect(DISTINCT rEndpoint.description) +
+                        collect(DISTINCT rConcept.description) AS rules`,
+        {},
+      );
+
+      servicingEndpoints = dedupeEndpoints(
+        asArray<EndpointRow>(JSON.parse(servicingRaw)).map(function (row) {
+          return {
+            concept: row.concept,
+            relation:
+              row.relationType === "MUTATED_VIA"
+                ? ("write" as const)
+                : ("read" as const),
+            name: row.name,
+            path: row.path,
+            method: row.method,
+            params: row.params ?? "[]",
+            body: row.body ?? "[]",
+            response: row.response ?? "[]",
+            dependencies: row.dependencies.filter(
+              (dep): dep is EndpointDependency => dep.depPath != null,
+            ),
+            rules: row.rules.filter((rule): rule is string => Boolean(rule)),
+          };
+        }),
+      );
+    }
+
+    const combinedEndpoints = dedupeEndpoints([
+      ...allEndpoints,
+      ...servicingEndpoints,
+    ]);
+
+    return {
+      readEndpoints: combinedEndpoints.filter((ep) => ep.relation === "read"),
+      writeEndpoints: combinedEndpoints.filter((ep) => ep.relation === "write"),
+      services,
+    } satisfies ResolvedContext;
+  } catch (error) {
+    console.error("Graph resolution failed:", error);
+    return empty;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function asArray<T>(value: unknown) {
+  return Array.isArray(value) ? (value as T[]) : ([] as T[]);
+}
+
+function dedupeEndpoints(endpoints: ResolvedEndpoint[]) {
+  const seen = new Set<string>();
+  const deduped: ResolvedEndpoint[] = [];
+
+  for (const ep of endpoints) {
+    const key = `${ep.relation}|${ep.concept}|${ep.method}|${ep.path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(ep);
+  }
+
+  return deduped;
+}
+
+function dedupeServices(services: ResolvedService[]) {
+  const seen = new Set<string>();
+  const deduped: ResolvedService[] = [];
+
+  for (const svc of services) {
+    const key = `${svc.concept}|${svc.builtInId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(svc);
+  }
+
+  return deduped;
+}
+
+async function computeRelevanceScores(
+  prompt: string,
+  concepts: (Pick<ConceptDef, "name" | "description"> & { score: number })[],
+  reranker: RerankerConfig,
+) {
+  const response = await fetch(reranker.url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${reranker.apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      queries: [prompt],
+      documents: concepts.map((x) => x.description),
+    }),
+  });
+
+  const data = (await response.json()) as { scores: number[] };
+  const scores = data.scores;
+
+  const scoredConcepts = concepts.map((c, idx) => ({
+    ...c,
+    score: scores[idx]!,
+  }));
+
+  scoredConcepts.sort((a, b) => b.score - a.score);
+  return scoredConcepts.slice(0, 3);
+}

package/src/graph/seed.ts

@@ -0,0 +1,172 @@
+/**
+ * Seed orchestrator for the knowledge graph.
+ *
+ * Validates domains, generates Cypher, executes against Neo4j,
+ * and generates concept embeddings. All configuration is passed
+ * explicitly — no environment variables or Convex dependencies.
+ */
+
+import type { EmbeddingModel } from "ai";
+import { embed } from "ai";
+import type { Neo4jClient, Neo4jConfig } from "./neo4j.ts";
+import { createNeo4jClient } from "./neo4j.ts";
+import { generateCypher, type GeneratedCypher } from "./generate-cypher.ts";
+import type { DomainDef } from "./types.ts";
+import { validateDomain } from "./validate.ts";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export type EmbeddingConfig = {
+  model: EmbeddingModel;
+  dimension: number;
+};
+
+export type SeedGraphConfig = {
+  neo4j: Neo4jConfig;
+  embedding: EmbeddingConfig;
+};
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function runStatements(
+  client: Neo4jClient,
+  label: string,
+  statements: string[],
+) {
+  console.log(`\n--- ${label} (${statements.length} statements) ---`);
+
+  let success = 0;
+  let failed = 0;
+
+  for (const stmt of statements) {
+    try {
+      const result = await client.query(stmt);
+      const parsed = JSON.parse(result);
+      if (parsed.error) {
+        console.error(`  ✗ Failed: ${parsed.message}`);
+        console.error(`    Statement: ${stmt.substring(0, 120)}...`);
+        failed++;
+      } else {
+        success++;
+      }
+    } catch (e) {
+      console.error(`  ✗ Exception: ${e}`);
+      console.error(`    Statement: ${stmt.substring(0, 120)}...`);
+      failed++;
+    }
+  }
+
+  console.log(`  ✓ ${success} succeeded, ${failed} failed`);
+}
+
+async function generateEmbeddings(
+  client: Neo4jClient,
+  embeddingConfig: EmbeddingConfig,
+) {
+  console.log("Seeding concept embeddings...");
+
+  // 1. Create the vector index (idempotent)
+  await client.query(
+    `CREATE VECTOR INDEX concept_embeddings IF NOT EXISTS
+             FOR (c:Concept) ON (c.embedding)
+             OPTIONS {indexConfig: {
+                 \`vector.dimensions\`: ${embeddingConfig.dimension},
+                 \`vector.similarity_function\`: 'cosine'
+             }}`,
+  );
+  console.log("Vector index created (or already exists)");
+
+  // 2. Fetch all concepts
+  const conceptsRaw = await client.query(
+    "MATCH (c:Concept) RETURN c.name AS name, c.description AS description",
+  );
+  const concepts: { name: string; description: string }[] =
+    JSON.parse(conceptsRaw);
+
+  if (!Array.isArray(concepts) || concepts.length === 0) {
+    console.log("No concepts found in Neo4j");
+    return;
+  }
+
+  console.log(`Found ${concepts.length} concepts, generating embeddings...`);
+
+  // 3. Generate and store embeddings for each concept
+  const embeddingResults = await Promise.all(
+    concepts.map(async (concept) => ({
+      concept,
+      embedding: (
+        await embed({
+          model: embeddingConfig.model,
+          value: concept.description,
+        })
+      ).embedding,
+    })),
+  );
+
+  // 4. Store the embeddings in the graph
+  await Promise.all(
+    embeddingResults.map(
+      async (result) =>
+        await client.query(
+          `MATCH (c:Concept {name: $name})
+                     SET c.embedding = $embedding`,
+          {
+            name: result.concept.name,
+            embedding: result.embedding,
+          },
+        ),
+    ),
+  );
+
+  console.log("Embedding seeding complete!");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function seedGraph(
+  config: SeedGraphConfig,
+  domains: Record<string, DomainDef>,
+) {
+  // Validate all domains
+  const validationErrors = Object.entries(domains).flatMap(([name, domain]) =>
+    validateDomain(domain).map((err) => `[${name}] ${err}`),
+  );
+
+  if (validationErrors.length) {
+    validationErrors.forEach((err) => console.error(err));
+    throw new Error(
+      `Validation failed with ${validationErrors.length} error(s)`,
+    );
+  }
+
+  const client = createNeo4jClient(config.neo4j, config.embedding.model);
+  const targets = Object.entries(domains);
+
+  console.log(`Seeding ${targets.length} domain(s)...`);
+
+  // Generate Cypher for all target domains
+  const allCypher: [string, GeneratedCypher][] = targets.map(([name, data]) => [
+    name,
+    generateCypher(data),
+  ]);
+
+  // Phase 1: Create all nodes across every domain first.
+  // This ensures cross-domain references resolve correctly.
+  const allNodes = allCypher.flatMap(([, c]) => c.nodes);
+  await runStatements(client, "Phase 1: Nodes", allNodes);
+
+  // Phase 2: Create all edges now that every node exists.
+  const allEdges = allCypher.flatMap(([, c]) => c.edges);
+  await runStatements(client, "Phase 2: Edges", allEdges);
+
+  console.log("\nGraph seeding complete!");
+
+  // Phase 3: Generate embeddings for concepts
+  await generateEmbeddings(client, config.embedding);
+}

package/src/graph/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Declarative types for knowledge graph seed data.
+ *
+ * This is the v2 schema:
+ * - Endpoints use params/body/response EndpointProperty arrays.
+ * - Source/default mappings are intentionally removed.
+ * - Services are concept associations (no hardcoded endpoint steps).
+ */
+
+// ---------------------------------------------------------------------------
+// Endpoint property model (v2)
+// ---------------------------------------------------------------------------
+
+export type EndpointScalarType =
+  | "uuid"
+  | "number"
+  | "date"
+  | "datetime"
+  | "string"
+  | "boolean"
+  | "any"
+  | "object";
+
+export type EndpointProperty = {
+  readonly name: string;
+  readonly required: boolean;
+  readonly type: EndpointScalarType | string;
+  readonly isArray?: boolean;
+  readonly properties?: readonly EndpointProperty[];
+  readonly description?: string;
+};
+
+export type ResponseKind = "object" | "array" | "paginated" | "file" | "none";
+
+export type AutoGenerated = {
+  readonly params: readonly EndpointProperty[];
+  readonly body: readonly EndpointProperty[];
+  readonly response: readonly EndpointProperty[];
+  readonly successStatus: number;
+  readonly errorStatuses: readonly number[];
+  readonly responseKind?: ResponseKind;
+};
+
+// ---------------------------------------------------------------------------
+// Concept descriptor
+// ---------------------------------------------------------------------------
+
+export type ConceptDef = {
+  readonly __brand: "concept";
+  name: string;
+  description: string;
+  aliases?: string[];
+  parentConcept?: ConceptDef;
+  governedBy?: RuleDef[];
+};
+
+// ---------------------------------------------------------------------------
+// Endpoint descriptor (v2)
+// ---------------------------------------------------------------------------
+
+export type EndpointDef = {
+  readonly __brand: "endpoint";
+  name: string;
+  description: string;
+  path: string;
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  propertiesDescriptions: Record<string, string>;
+
+  params: EndpointProperty[];
+  body: EndpointProperty[];
+  response: EndpointProperty[];
+  successStatus: number;
+  errorStatuses: number[];
+  responseKind: ResponseKind;
+
+  queries?: ConceptDef[];
+  mutates?: ConceptDef[];
+
+  returns?: { concept: ConceptDef; field?: string }[];
+  dependsOn?: {
+    endpoint: EndpointDef;
+    paramName: string;
+    fromField: string;
+  }[];
+
+  governedBy?: RuleDef[];
+};
+
+// ---------------------------------------------------------------------------
+// EndpointInput
+// ---------------------------------------------------------------------------
+
+export type EndpointInput = {
+  name: string;
+  path: string;
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  description?: string;
+  autoGenerated?: AutoGenerated;
+
+  propertiesDescriptions?: Record<string, string>;
+
+  queries?: ConceptDef[];
+  mutates?: ConceptDef[];
+  paramDescriptions?: Partial<Record<string, string>>;
+  responseDescriptions?: Partial<Record<string, string>>;
+
+  returns?: { concept: ConceptDef; field?: string }[];
+  dependsOn?: {
+    endpoint: EndpointDef;
+    paramName: string;
+    fromField: string;
+  }[];
+
+  governedBy?: RuleDef[];
+};
+
+// ---------------------------------------------------------------------------
+// Service descriptor (v2)
+// ---------------------------------------------------------------------------
+
+export type ServiceDef = {
+  readonly __brand: "service";
+  name: string;
+  description: string;
+  builtInId: string;
+  belongsTo: ConceptDef;
+  governedBy?: RuleDef[];
+};
+
+// ---------------------------------------------------------------------------
+// Rule descriptor
+// ---------------------------------------------------------------------------
+
+export type RuleDef = {
+  readonly __brand: "rule";
+  name: string;
+  description: string;
+};
+
+// ---------------------------------------------------------------------------
+// Domain descriptor
+// ---------------------------------------------------------------------------
+
+export type DomainDef = {
+  readonly __brand: "domain";
+  name: string;
+  description: string;
+  concepts?: ConceptDef[];
+  endpoints?: EndpointDef[];
+  services?: ServiceDef[];
+  rules?: RuleDef[];
+};