@m6d/cortex-server 1.1.0 → 1.1.2

package/src/graph/resolver.ts

@@ -16,14 +16,14 @@ import type { ConceptDef } from "./types.ts";
 // ---------------------------------------------------------------------------
 
 export type RerankerConfig = {
-  url: string;
-  apiKey: string;
+    url: string;
+    apiKey: string;
 };
 
 export type ResolverConfig = {
-  neo4j: Neo4jClient;
-  embeddingModel: EmbeddingModel;
-  reranker?: RerankerConfig;
+    neo4j: Neo4jClient;
+    embeddingModel: EmbeddingModel;
+    reranker?: RerankerConfig;
 };
 
 // ---------------------------------------------------------------------------
@@ -31,39 +31,39 @@ export type ResolverConfig = {
 // ---------------------------------------------------------------------------
 
 type EndpointDependency = {
-  depPath: string;
-  depMethod: string;
-  paramName: string;
-  fromField: string;
+    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[];
+    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[];
+    concept: string;
+    serviceName: string;
+    builtInId: string;
+    description: string;
+    rules: string[];
 };
 
 export type ResolvedContext = {
-  readEndpoints: ResolvedEndpoint[];
-  writeEndpoints: ResolvedEndpoint[];
-  services: ResolvedService[];
+    readEndpoints: ResolvedEndpoint[];
+    writeEndpoints: ResolvedEndpoint[];
+    services: ResolvedService[];
 };
 
 // ---------------------------------------------------------------------------
@@ -71,24 +71,24 @@ export type ResolvedContext = {
 // ---------------------------------------------------------------------------
 
 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)[];
+    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)[];
+    concept: string;
+    serviceName: string;
+    builtInId: string;
+    description: string | null;
+    rules: (string | null)[];
 };
 
 // ---------------------------------------------------------------------------
@@ -96,50 +96,45 @@ type ServiceRow = {
 // ---------------------------------------------------------------------------
 
 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)
+    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 },
-    );
+            { embedding },
+        );
 
-    let concepts = JSON.parse(conceptsRaw) as (Pick<
-      ConceptDef,
-      "name" | "description"
-    > & { score: number })[];
+        let concepts = JSON.parse(conceptsRaw) as (Pick<ConceptDef, "name" | "description"> & {
+            score: number;
+        })[];
 
-    if (!Array.isArray(concepts) || concepts.length === 0) {
-      return empty;
-    }
+        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);
-    }
+        if (config.reranker) {
+            concepts = await computeRelevanceScores(prompt, concepts, config.reranker);
+        } else {
+            concepts = concepts.slice(0, 3);
+        }
 
-    const conceptNames = concepts.map((c) => c.name);
+        const conceptNames = concepts.map((c) => c.name);
 
-    const endpointsRaw = await config.neo4j.query(
-      `UNWIND $names AS conceptName
+        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
@@ -166,34 +161,32 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     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
+            { 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
@@ -207,27 +200,27 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     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)
+            { 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 {
@@ -249,46 +242,43 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                         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)),
-          };
-        }),
-      );
-    }
+                {},
+            );
+
+            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]);
 
-    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;
-  }
+        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;
+    }
 }
 
 // ---------------------------------------------------------------------------
@@ -296,62 +286,62 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
 // ---------------------------------------------------------------------------
 
 function asArray<T>(value: unknown) {
-  return Array.isArray(value) ? (value as T[]) : ([] as T[]);
+    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);
-  }
+    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;
+    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);
-  }
+    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;
+    return deduped;
 }
 
 async function computeRelevanceScores(
-  prompt: string,
-  concepts: (Pick<ConceptDef, "name" | "description"> & { score: number })[],
-  reranker: RerankerConfig,
+    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);
+    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);
 }