@m6d/cortex-server 1.0.0

package/src/factory.ts

@@ -0,0 +1,159 @@
+import { Hono } from "hono";
+import { websocket } from "hono/bun";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { CortexConfig, ResolvedCortexAgentConfig } from "./config.ts";
+import type { AppEnv, CortexAppEnv } from "./types.ts";
+import type { DomainDef } from "./graph/types.ts";
+import { createUserLoaderMiddleware } from "./auth/middleware.ts";
+import { createThreadRoutes } from "./routes/threads.ts";
+import { createChatRoutes } from "./routes/chat.ts";
+import { createFileRoutes } from "./routes/files.ts";
+import { createWsRoute } from "./routes/ws.ts";
+import { runMigrations } from "./db/migrate.ts";
+import { createMssqlAdapter } from "./adapters/mssql.ts";
+import { createMinioAdapter } from "./adapters/minio.ts";
+import { seedGraph as seedGraphFn } from "./graph/seed.ts";
+import { extractEndpoints as extractEndpointsFn } from "./cli/extract-endpoints.ts";
+
+export type CortexInstance = {
+  serve(): Promise<{
+    app: Hono<AppEnv>;
+    fetch: Hono<AppEnv>["fetch"];
+    websocket: typeof websocket;
+  }>;
+  seedGraph(): Promise<void>;
+  extractEndpoints(options: {
+    domainsDir: string;
+    write?: boolean;
+  }): Promise<void>;
+};
+
+export function createCortex(config: CortexConfig): CortexInstance {
+  function collectAllDomains() {
+    const all: Record<string, DomainDef> = {};
+    if (config.knowledge?.domains) Object.assign(all, config.knowledge.domains);
+    for (const agent of Object.values(config.agents)) {
+      if (agent.knowledge && agent.knowledge.domains) {
+        Object.assign(all, agent.knowledge.domains);
+      }
+    }
+    return all;
+  }
+
+  function collectAllSwaggerUrls() {
+    const urls = new Set<string>();
+    if (config.knowledge?.swagger?.url) urls.add(config.knowledge.swagger.url);
+    for (const agent of Object.values(config.agents)) {
+      if (agent.knowledge && agent.knowledge.swagger?.url) {
+        urls.add(agent.knowledge.swagger.url);
+      }
+    }
+    return [...urls];
+  }
+
+  return {
+    async serve() {
+      const storage = createMinioAdapter(config.storage);
+      const db = createMssqlAdapter(config.database.connectionString, storage);
+
+      await runMigrations(config.database.connectionString);
+
+      const app = new Hono<AppEnv>();
+
+      const userLoader = createUserLoaderMiddleware(config.auth);
+      app.use("*", userLoader);
+
+      // WebSocket route (global, not agent-scoped)
+      app.route("/", createWsRoute());
+
+      // Agent-scoped routes
+      const agentApp = new Hono<CortexAppEnv>();
+
+      agentApp.use("*", async function (c, next) {
+        const agentId = c.req.param("agentId") as string;
+        const agentDef = config.agents[agentId];
+        if (!agentDef) return c.json({ error: "Agent not found" }, 404);
+
+        const resolvedConfig: ResolvedCortexAgentConfig = {
+          db,
+          storage,
+          model: agentDef.model ?? config.model,
+          embedding: agentDef.embedding ?? config.embedding,
+          neo4j: agentDef.neo4j ?? config.neo4j,
+          reranker: agentDef.reranker ?? config.reranker,
+          knowledge:
+            agentDef.knowledge === null
+              ? undefined
+              : (agentDef.knowledge ?? config.knowledge),
+          systemPrompt: agentDef.systemPrompt,
+          tools: agentDef.tools,
+          backendFetch: agentDef.backendFetch,
+          loadSessionData: agentDef.loadSessionData,
+          onToolCall: agentDef.onToolCall,
+          onStreamFinish: agentDef.onStreamFinish,
+        };
+
+        c.set("agentConfig", resolvedConfig);
+        c.set("agentId", agentId);
+        await next();
+      });
+
+      agentApp.route("/", createThreadRoutes());
+      agentApp.route("/", createChatRoutes());
+      agentApp.route("/", createFileRoutes());
+
+      app.route("/agents/:agentId", agentApp);
+
+      return {
+        app,
+        fetch: app.fetch,
+        websocket,
+      };
+    },
+
+    async seedGraph() {
+      const domains = collectAllDomains();
+      if (!Object.keys(domains).length) {
+        throw new Error("No domains found in knowledge config");
+      }
+      if (!config.neo4j) {
+        throw new Error("neo4j config is required for seedGraph");
+      }
+      if (!config.embedding) {
+        throw new Error("embedding config is required for seedGraph");
+      }
+
+      const provider = createOpenAICompatible({
+        name: "embedding-provider",
+        baseURL: config.embedding.baseURL,
+        apiKey: config.embedding.apiKey,
+      });
+
+      await seedGraphFn(
+        {
+          neo4j: config.neo4j,
+          embedding: {
+            model: provider.textEmbeddingModel(config.embedding.modelName),
+            dimension: config.embedding.dimension,
+          },
+        },
+        domains,
+      );
+    },
+
+    async extractEndpoints(options) {
+      const swaggerUrls = collectAllSwaggerUrls();
+      if (!swaggerUrls.length) {
+        throw new Error("No swagger URLs found in knowledge config");
+      }
+
+      for (const swaggerUrl of swaggerUrls) {
+        await extractEndpointsFn({
+          swaggerUrl,
+          domainsDir: options.domainsDir,
+          write: options.write ?? true,
+        });
+      }
+    },
+  };
+}

package/src/graph/generate-cypher.ts

@@ -0,0 +1,179 @@
+/**
+ * Transforms declarative DomainDef into idempotent MERGE-based Cypher.
+ *
+ * Returns two phases:
+ *   - `nodes`  -- MERGE statements that create/update Domain, Concept, Endpoint,
+ *                 Service, and Rule nodes.
+ *   - `edges`  -- MATCH+MERGE statements that wire up relationships between nodes.
+ *
+ * The caller MUST run all `nodes` from every module before running any `edges`,
+ * because edges may reference nodes defined in a different module (e.g. a Rule
+ * in the leaves module that GOVERNS a Concept created by the servicing module).
+ */
+
+import type { DomainDef } from "./types.ts";
+
+export type GeneratedCypher = {
+  nodes: string[];
+  edges: string[];
+};
+
+function esc(s: string) {
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n");
+}
+
+function jsonStr(value: unknown) {
+  return esc(JSON.stringify(value));
+}
+
+export function generateCypher(data: DomainDef) {
+  const nodes: string[] = [];
+  const edges: string[] = [];
+
+  // -- Domain node --
+  nodes.push(
+    `MERGE (d:Domain {name: '${esc(data.name)}'})
+        SET d.description = '${esc(data.description)}'`,
+  );
+
+  // -- Concept nodes --
+  for (const c of data.concepts ?? []) {
+    const aliasClause =
+      c.aliases && c.aliases.length > 0
+        ? `, c.aliases = [${c.aliases.map((a) => `'${esc(a)}'`).join(", ")}]`
+        : "";
+
+    nodes.push(
+      `MERGE (c:Concept {name: '${esc(c.name)}'})
+            SET c.description = '${esc(c.description)}'${aliasClause}`,
+    );
+
+    edges.push(
+      `MATCH (c:Concept {name: '${esc(c.name)}'})
+            MATCH (d:Domain {name: '${esc(data.name)}'})
+            MERGE (c)-[:BELONGS_TO]->(d)`,
+    );
+
+    if (c.parentConcept) {
+      edges.push(
+        `MATCH (child:Concept {name: '${esc(c.name)}'})
+                MATCH (parent:Concept {name: '${esc(c.parentConcept.name)}'})
+                MERGE (child)-[:SPECIALIZES]->(parent)`,
+      );
+    }
+
+    c.governedBy?.forEach((rule) => {
+      edges.push(
+        `MATCH (r:Rule {name: '${esc(rule.name)}'})
+                MATCH (t:Concept {name: '${esc(c.name)}'})
+                MERGE (r)-[:GOVERNS]->(t)`,
+      );
+    });
+  }
+
+  // -- Endpoint nodes --
+  for (const ep of data.endpoints ?? []) {
+    nodes.push(
+      `MERGE (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+            SET e.name = '${esc(ep.name)}',
+                e.description = '${esc(ep.description)}',
+                e.params = '${jsonStr(ep.params)}',
+                e.body = '${jsonStr(ep.body)}',
+                e.response = '${jsonStr(ep.response)}',
+                e.propertiesDescriptions = '${jsonStr(ep.propertiesDescriptions)}',
+                e.successStatus = ${ep.successStatus},
+                e.errorStatuses = [${ep.errorStatuses.join(", ")}]`,
+    );
+
+    for (const concept of ep.queries ?? []) {
+      edges.push(
+        `MATCH (c:Concept {name: '${esc(concept.name)}'})
+                MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+                MERGE (c)-[:QUERIED_VIA]->(e)`,
+      );
+    }
+
+    for (const concept of ep.mutates ?? []) {
+      edges.push(
+        `MATCH (c:Concept {name: '${esc(concept.name)}'})
+                MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+                MERGE (c)-[:MUTATED_VIA]->(e)`,
+      );
+    }
+
+    for (const ret of ep.returns ?? []) {
+      const fieldClause = ret.field ? ` SET r.field = '${esc(ret.field)}'` : "";
+
+      edges.push(
+        `MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+                MATCH (c:Concept {name: '${esc(ret.concept.name)}'})
+                MERGE (e)-[r:RETURNS]->(c)${fieldClause}`,
+      );
+    }
+
+    for (const rule of ep.governedBy ?? []) {
+      edges.push(
+        `MATCH (r:Rule {name: '${esc(rule.name)}'})
+                MATCH (t:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+                MERGE (r)-[:GOVERNS]->(t)`,
+      );
+    }
+
+    for (const dep of ep.dependsOn ?? []) {
+      edges.push(
+        `MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
+                MATCH (dep:Endpoint {path: '${esc(dep.endpoint.path)}', method: '${dep.endpoint.method}'})
+                MERGE (e)-[d:DEPENDS_ON]->(dep)
+                SET d.paramName = '${esc(dep.paramName)}', d.fromField = '${esc(dep.fromField)}'`,
+      );
+    }
+  }
+
+  // -- Service nodes --
+  for (const svc of data.services ?? []) {
+    nodes.push(
+      `MERGE (s:Service {builtInId: '${esc(svc.builtInId)}'})
+            SET s.name = '${esc(svc.name)}',
+            s.description = '${esc(svc.description)}'`,
+    );
+
+    edges.push(
+      `MATCH (c:Concept {name: '${esc(svc.belongsTo.name)}'})
+            MATCH (s:Service {builtInId: '${esc(svc.builtInId)}'})
+            MERGE (c)-[:REQUESTED_VIA]->(s)`,
+    );
+
+    svc.governedBy?.forEach((rule) => {
+      edges.push(
+        `MATCH (r:Rule {name: '${esc(rule.name)}'})
+                MATCH (t:Service {builtInId: '${esc(svc.builtInId)}'})
+                MERGE (r)-[:GOVERNS]->(t)`,
+      );
+    });
+  }
+
+  // -- Rule nodes --
+  for (const rule of data.rules ?? []) {
+    nodes.push(
+      `MERGE (r:Rule {name: '${esc(rule.name)}'})
+            SET r.description = '${esc(rule.description)}'`,
+    );
+  }
+
+  return { nodes, edges } satisfies GeneratedCypher;
+}
+
+export function toCypherScript(data: DomainDef) {
+  const { nodes, edges } = generateCypher(data);
+  return (
+    `// Auto-generated seed script for module: ${data.name}\n` +
+    `// Generated at: ${new Date().toISOString()}\n` +
+    `// Safe to re-run (uses MERGE)\n\n` +
+    `// --- Nodes ---\n` +
+    nodes.join(";\n\n") +
+    ";\n\n" +
+    `// --- Edges ---\n` +
+    edges.join(";\n\n") +
+    ";\n"
+  );
+}

package/src/graph/helpers.ts

@@ -0,0 +1,68 @@
+/**
+ * Helper functions for building knowledge graph seed data.
+ */
+
+import type {
+  ConceptDef,
+  DomainDef,
+  EndpointDef,
+  EndpointInput,
+  RuleDef,
+  ServiceDef,
+} from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Identity helpers
+// ---------------------------------------------------------------------------
+
+export function defineConcept(def: Omit<ConceptDef, "__brand">) {
+  return { __brand: "concept" as const, ...def };
+}
+
+export function defineRule(def: Omit<RuleDef, "__brand">) {
+  return { __brand: "rule" as const, ...def };
+}
+
+export function defineService(def: Omit<ServiceDef, "__brand">) {
+  return { __brand: "service" as const, ...def };
+}
+
+export function defineDomain(def: Omit<DomainDef, "__brand">) {
+  return { __brand: "domain" as const, ...def };
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint builder
+// ---------------------------------------------------------------------------
+
+export function defineEndpoint(input: EndpointInput) {
+  const propertiesDescriptions = Object.fromEntries(
+    Object.entries({
+      ...(input.propertiesDescriptions ?? {}),
+      ...(input.paramDescriptions ?? {}),
+      ...(input.responseDescriptions ?? {}),
+    }).filter(([, value]) => value != null),
+  ) as Record<string, string>;
+
+  const normalized = input.autoGenerated;
+
+  return {
+    __brand: "endpoint" as const,
+    name: input.name,
+    description: input.description ?? input.name,
+    path: input.path,
+    method: input.method,
+    propertiesDescriptions,
+    params: normalized ? [...normalized.params] : [],
+    body: normalized ? [...normalized.body] : [],
+    response: normalized ? [...normalized.response] : [],
+    successStatus: normalized?.successStatus ?? 200,
+    errorStatuses: normalized ? [...normalized.errorStatuses] : [],
+    responseKind: normalized?.responseKind ?? "object",
+    queries: input.queries,
+    mutates: input.mutates,
+    returns: input.returns,
+    dependsOn: input.dependsOn,
+    governedBy: input.governedBy,
+  } satisfies EndpointDef;
+}

package/src/graph/index.ts

@@ -0,0 +1,47 @@
+// Types
+export type {
+  EndpointScalarType,
+  EndpointProperty,
+  ResponseKind,
+  AutoGenerated,
+  ConceptDef,
+  EndpointDef,
+  EndpointInput,
+  ServiceDef,
+  RuleDef,
+  DomainDef,
+} from "./types.ts";
+
+// Helpers
+export {
+  defineConcept,
+  defineRule,
+  defineService,
+  defineDomain,
+  defineEndpoint,
+} from "./helpers.ts";
+
+// Cypher generation
+export type { GeneratedCypher } from "./generate-cypher.ts";
+export { generateCypher, toCypherScript } from "./generate-cypher.ts";
+
+// Validation
+export { validateDomain } from "./validate.ts";
+
+// Neo4j client
+export type { Neo4jConfig, Neo4jClient } from "./neo4j.ts";
+export { createNeo4jClient } from "./neo4j.ts";
+
+// Seed orchestrator
+export type { EmbeddingConfig, SeedGraphConfig } from "./seed.ts";
+export { seedGraph } from "./seed.ts";
+
+// Graph resolver
+export type {
+  RerankerConfig,
+  ResolverConfig,
+  ResolvedEndpoint,
+  ResolvedService,
+  ResolvedContext,
+} from "./resolver.ts";
+export { resolveFromGraph } from "./resolver.ts";

package/src/graph/neo4j.ts

@@ -0,0 +1,117 @@
+/**
+ * Configurable Neo4j HTTP client.
+ *
+ * Replaces the hardcoded process.env-based client from packages/sample-backend.
+ * All configuration is passed explicitly — no environment variables are read.
+ */
+
+import type { EmbeddingModel } from "ai";
+import { embed } from "ai";
+
+// ---------------------------------------------------------------------------
+// Config types
+// ---------------------------------------------------------------------------
+
+export type Neo4jConfig = {
+  url: string;
+  user: string;
+  password: string;
+};
+
+export type Neo4jClient = {
+  query(cypher: string, parameters?: Record<string, unknown>): Promise<string>;
+};
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+export function createNeo4jClient(
+  config: Neo4jConfig,
+  embeddingModel?: EmbeddingModel,
+) {
+  async function query(cypher: string, parameters?: Record<string, unknown>) {
+    // Auto-embed parameters whose keys start with '#'
+    const embeddedParams = Object.keys(parameters ?? {}).filter((x) =>
+      x.startsWith("#"),
+    );
+
+    if (embeddedParams.length) {
+      if (!embeddingModel) {
+        throw new Error(
+          "An embedding model is required when using # parameters",
+        );
+      }
+
+      const embeddingResults = await Promise.all(
+        embeddedParams.map(
+          async (x) =>
+            await embed({
+              model: embeddingModel,
+              value: parameters![x] as string,
+            }),
+        ),
+      );
+
+      embeddedParams.forEach((k, idx) => {
+        delete parameters![k];
+        parameters![k.slice(1)] = embeddingResults[idx]!.embedding;
+      });
+    }
+
+    const response = await fetch(`${config.url}/db/neo4j/tx/commit`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${btoa(`${config.user}:${config.password}`)}`,
+      },
+      body: JSON.stringify({
+        statements: [
+          {
+            statement: cypher,
+            parameters: parameters ?? {},
+          },
+        ],
+      }),
+    });
+
+    if (!response.ok) {
+      return JSON.stringify({
+        error: true,
+        status: response.status,
+        message: `Neo4j request failed with status ${response.status}`,
+      });
+    }
+
+    const result = (await response.json()) as {
+      errors?: { message: string }[];
+      results: { columns: string[]; data: { row: unknown[] }[] }[];
+    };
+
+    if (result.errors && result.errors.length > 0) {
+      return JSON.stringify({
+        error: true,
+        message: result.errors.map((e) => e.message).join("; "),
+      });
+    }
+
+    // Transform Neo4j response into a clean array of objects
+    const queryResult = result.results[0];
+    if (!queryResult) {
+      return JSON.stringify([]);
+    }
+
+    const { columns, data } = queryResult;
+    const rows = data.map((entry) => {
+      const obj: Record<string, unknown> = {};
+      columns.forEach((col, i) => {
+        obj[col] = entry.row[i];
+      });
+      return obj;
+    });
+
+    return JSON.stringify(rows);
+  }
+
+  return { query } satisfies Neo4jClient;
+}