@m6d/cortex-server 1.1.0 → 1.1.2

package/src/graph/seed.ts

@@ -19,154 +19,141 @@ import { validateDomain } from "./validate.ts";
 // ---------------------------------------------------------------------------
 
 export type EmbeddingConfig = {
-  model: EmbeddingModel;
-  dimension: number;
+    model: EmbeddingModel;
+    dimension: number;
 };
 
 export type SeedGraphConfig = {
-  neo4j: Neo4jConfig;
-  embedding: EmbeddingConfig;
+    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++;
+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`);
+    console.log(`  ✓ ${success} succeeded, ${failed} failed`);
 }
 
-async function generateEmbeddings(
-  client: Neo4jClient,
-  embeddingConfig: EmbeddingConfig,
-) {
-  console.log("Seeding concept embeddings...");
+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
+    // 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})
+    );
+    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,
-          },
+                    {
+                        name: result.concept.name,
+                        embedding: result.embedding,
+                    },
+                ),
         ),
-    ),
-  );
+    );
 
-  console.log("Embedding seeding complete!");
+    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)`,
+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}`),
     );
-  }
 
-  const client = createNeo4jClient(config.neo4j, config.embedding.model);
-  const targets = Object.entries(domains);
+    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)...`);
+    console.log(`Seeding ${targets.length} domain(s)...`);
 
-  // Generate Cypher for all target domains
-  const allCypher: [string, GeneratedCypher][] = targets.map(([name, data]) => [
-    name,
-    generateCypher(data),
-  ]);
+    // 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 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);
+    // 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!");
+    console.log("\nGraph seeding complete!");
 
-  // Phase 3: Generate embeddings for concepts
-  await generateEmbeddings(client, config.embedding);
+    // Phase 3: Generate embeddings for concepts
+    await generateEmbeddings(client, config.embedding);
 }

package/src/graph/types.ts

@@ -12,33 +12,33 @@
 // ---------------------------------------------------------------------------
 
 export type EndpointScalarType =
-  | "uuid"
-  | "number"
-  | "date"
-  | "datetime"
-  | "string"
-  | "boolean"
-  | "any"
-  | "object";
+    | "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;
+    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;
+    readonly params: readonly EndpointProperty[];
+    readonly body: readonly EndpointProperty[];
+    readonly response: readonly EndpointProperty[];
+    readonly successStatus: number;
+    readonly errorStatuses: readonly number[];
+    readonly responseKind?: ResponseKind;
 };
 
 // ---------------------------------------------------------------------------
@@ -46,12 +46,12 @@ export type AutoGenerated = {
 // ---------------------------------------------------------------------------
 
 export type ConceptDef = {
-  readonly __brand: "concept";
-  name: string;
-  description: string;
-  aliases?: string[];
-  parentConcept?: ConceptDef;
-  governedBy?: RuleDef[];
+    readonly __brand: "concept";
+    name: string;
+    description: string;
+    aliases?: string[];
+    parentConcept?: ConceptDef;
+    governedBy?: RuleDef[];
 };
 
 // ---------------------------------------------------------------------------
@@ -59,31 +59,31 @@ export type ConceptDef = {
 // ---------------------------------------------------------------------------
 
 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[];
+    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[];
 };
 
 // ---------------------------------------------------------------------------
@@ -91,27 +91,27 @@ export type EndpointDef = {
 // ---------------------------------------------------------------------------
 
 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[];
+    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[];
 };
 
 // ---------------------------------------------------------------------------
@@ -119,12 +119,12 @@ export type EndpointInput = {
 // ---------------------------------------------------------------------------
 
 export type ServiceDef = {
-  readonly __brand: "service";
-  name: string;
-  description: string;
-  builtInId: string;
-  belongsTo: ConceptDef;
-  governedBy?: RuleDef[];
+    readonly __brand: "service";
+    name: string;
+    description: string;
+    builtInId: string;
+    belongsTo: ConceptDef;
+    governedBy?: RuleDef[];
 };
 
 // ---------------------------------------------------------------------------
@@ -132,9 +132,9 @@ export type ServiceDef = {
 // ---------------------------------------------------------------------------
 
 export type RuleDef = {
-  readonly __brand: "rule";
-  name: string;
-  description: string;
+    readonly __brand: "rule";
+    name: string;
+    description: string;
 };
 
 // ---------------------------------------------------------------------------
@@ -142,11 +142,11 @@ export type RuleDef = {
 // ---------------------------------------------------------------------------
 
 export type DomainDef = {
-  readonly __brand: "domain";
-  name: string;
-  description: string;
-  concepts?: ConceptDef[];
-  endpoints?: EndpointDef[];
-  services?: ServiceDef[];
-  rules?: RuleDef[];
+    readonly __brand: "domain";
+    name: string;
+    description: string;
+    concepts?: ConceptDef[];
+    endpoints?: EndpointDef[];
+    services?: ServiceDef[];
+    rules?: RuleDef[];
 };

package/src/graph/validate.ts

@@ -1,80 +1,78 @@
 import type { DomainDef } from "./types.ts";
 
 export function validateDomain(data: DomainDef) {
-  const errors: string[] = [];
+    const errors: string[] = [];
 
-  const seenConceptNames = new Set<string>();
-  for (const c of data.concepts ?? []) {
-    if (seenConceptNames.has(c.name)) {
-      errors.push(`Duplicate concept name: "${c.name}"`);
+    const seenConceptNames = new Set<string>();
+    for (const c of data.concepts ?? []) {
+        if (seenConceptNames.has(c.name)) {
+            errors.push(`Duplicate concept name: "${c.name}"`);
+        }
+        seenConceptNames.add(c.name);
     }
-    seenConceptNames.add(c.name);
-  }
 
-  const seenEndpointNames = new Set<string>();
-  for (const e of data.endpoints ?? []) {
-    if (seenEndpointNames.has(e.name)) {
-      errors.push(`Duplicate endpoint name: "${e.name}"`);
+    const seenEndpointNames = new Set<string>();
+    for (const e of data.endpoints ?? []) {
+        if (seenEndpointNames.has(e.name)) {
+            errors.push(`Duplicate endpoint name: "${e.name}"`);
+        }
+        seenEndpointNames.add(e.name);
     }
-    seenEndpointNames.add(e.name);
-  }
 
-  const seenServiceNames = new Set<string>();
-  for (const s of data.services ?? []) {
-    if (seenServiceNames.has(s.name)) {
-      errors.push(`Duplicate service name: "${s.name}"`);
+    const seenServiceNames = new Set<string>();
+    for (const s of data.services ?? []) {
+        if (seenServiceNames.has(s.name)) {
+            errors.push(`Duplicate service name: "${s.name}"`);
+        }
+        seenServiceNames.add(s.name);
     }
-    seenServiceNames.add(s.name);
-  }
 
-  const seenRuleNames = new Set<string>();
-  for (const r of data.rules ?? []) {
-    if (seenRuleNames.has(r.name)) {
-      errors.push(`Duplicate rule name: "${r.name}"`);
+    const seenRuleNames = new Set<string>();
+    for (const r of data.rules ?? []) {
+        if (seenRuleNames.has(r.name)) {
+            errors.push(`Duplicate rule name: "${r.name}"`);
+        }
+        seenRuleNames.add(r.name);
     }
-    seenRuleNames.add(r.name);
-  }
 
-  // Cross-domain references are allowed (concepts/endpoints/services may
-  // be defined in another domain), so we do not enforce local membership.
+    // Cross-domain references are allowed (concepts/endpoints/services may
+    // be defined in another domain), so we do not enforce local membership.
 
-  const referencedConcepts = new Set<string>();
-  const referencedRules = new Set<string>();
+    const referencedConcepts = new Set<string>();
+    const referencedRules = new Set<string>();
 
-  for (const ep of data.endpoints ?? []) {
-    ep.queries?.forEach((c) => referencedConcepts.add(c.name));
-    ep.mutates?.forEach((c) => referencedConcepts.add(c.name));
-    ep.returns?.forEach((r) => referencedConcepts.add(r.concept.name));
-    ep.governedBy?.forEach((r) => referencedRules.add(r.name));
-  }
+    for (const ep of data.endpoints ?? []) {
+        ep.queries?.forEach((c) => referencedConcepts.add(c.name));
+        ep.mutates?.forEach((c) => referencedConcepts.add(c.name));
+        ep.returns?.forEach((r) => referencedConcepts.add(r.concept.name));
+        ep.governedBy?.forEach((r) => referencedRules.add(r.name));
+    }
 
-  for (const svc of data.services ?? []) {
-    referencedConcepts.add(svc.belongsTo.name);
-    svc.governedBy?.forEach((r) => referencedRules.add(r.name));
-  }
+    for (const svc of data.services ?? []) {
+        referencedConcepts.add(svc.belongsTo.name);
+        svc.governedBy?.forEach((r) => referencedRules.add(r.name));
+    }
 
-  for (const c of data.concepts ?? []) {
-    c.governedBy?.forEach((r) => referencedRules.add(r.name));
-    if (c.parentConcept) {
-      referencedConcepts.add(c.parentConcept.name);
+    for (const c of data.concepts ?? []) {
+        c.governedBy?.forEach((r) => referencedRules.add(r.name));
+        if (c.parentConcept) {
+            referencedConcepts.add(c.parentConcept.name);
+        }
     }
-  }
 
-  for (const c of data.concepts ?? []) {
-    if (!referencedConcepts.has(c.name)) {
-      errors.push(
-        `Concept "${c.name}" is never referenced by any endpoint, or service`,
-      );
+    for (const c of data.concepts ?? []) {
+        if (!referencedConcepts.has(c.name)) {
+            errors.push(`Concept "${c.name}" is never referenced by any endpoint, or service`);
+        }
     }
-  }
 
-  for (const r of data.rules ?? []) {
-    if (!referencedRules.has(r.name)) {
-      errors.push(
-        `Rule "${r.name}" is never referenced by any endpoint, service, or concept`,
-      );
+    for (const r of data.rules ?? []) {
+        if (!referencedRules.has(r.name)) {
+            errors.push(
+                `Rule "${r.name}" is never referenced by any endpoint, service, or concept`,
+            );
+        }
     }
-  }
 
-  return errors;
+    return errors;
 }

package/src/index.ts

@@ -1,10 +1,10 @@
 // Config types
 export type {
-  CortexConfig,
-  CortexAgentDefinition,
-  KnowledgeConfig,
-  DatabaseConfig,
-  StorageConfig,
+    CortexConfig,
+    CortexAgentDefinition,
+    KnowledgeConfig,
+    DatabaseConfig,
+    StorageConfig,
 } from "./config";
 
 // Types consumers may need