@m6d/cortex-server 1.7.0 → 2.0.0

package/src/graph/resolver.ts

@@ -1,357 +0,0 @@
-/**
- * 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[];
-    metadata: string;
-};
-
-export type ResolvedService = {
-    concept: string;
-    serviceName: string;
-    builtInId: string;
-    description: string;
-    rules: string[];
-    metadata: 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;
-    metadata: string | null;
-    dependencies: (EndpointDependency | { depPath: null })[];
-    rules: (string | null)[];
-};
-
-type ServiceRow = {
-    concept: string;
-    serviceName: string;
-    builtInId: string;
-    description: string | null;
-    metadata: 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,
-                    e.metadata AS metadata,
-                    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 ?? "[]",
-                    metadata: row.metadata ?? "{}",
-                    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,
-                    svc.metadata AS metadata,
-                    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 ?? "",
-                    metadata: row.metadata ?? "{}",
-                    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,
-                        e.metadata AS metadata,
-                        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 ?? "[]",
-                        metadata: row.metadata ?? "{}",
-                        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

@@ -1,162 +0,0 @@
-/**
- * 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 { expandDomains } from "./expand-domains.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>) {
-    const expandedDomains = expandDomains(domains);
-
-    // Validate all domains
-    const validationErrors = Object.entries(expandedDomains).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(expandedDomains);
-
-    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/validate.ts

@@ -1,78 +0,0 @@
-import type { DomainDef } from "./types.ts";
-
-export function validateDomain(data: DomainDef) {
-    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}"`);
-        }
-        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}"`);
-        }
-        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}"`);
-        }
-        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}"`);
-        }
-        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.
-
-    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 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 ?? []) {
-        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`,
-            );
-        }
-    }
-
-    return errors;
-}

package/src/routes/chat.ts

@@ -1,86 +0,0 @@
-import { Hono } from "hono";
-import { zValidator } from "@hono/zod-validator";
-import z from "zod";
-import { HTTPException } from "hono/http-exception";
-import type { CortexAppEnv } from "../types.ts";
-import { requireAuth } from "../auth/middleware.ts";
-import { stream } from "../ai/index.ts";
-import { subscribe, abortStream } from "../ai/active-streams.ts";
-import { notify } from "../ws/index.ts";
-import { toThreadSummary } from "../types.ts";
-
-export function createChatRoutes() {
-    const app = new Hono<CortexAppEnv>();
-
-    app.post(
-        "/chat",
-        requireAuth,
-        zValidator(
-            "json",
-            z.object({
-                id: z.string(),
-                messages: z.array(z.unknown()),
-            }),
-        ),
-        async function (c) {
-            const config = c.get("agentConfig");
-            const agentId = c.get("agentId");
-            const { id: userId, token } = c.get("user");
-            const { messages, id: threadId } = c.req.valid("json");
-            const requestContext = config.resolveRequestContext
-                ? await config.resolveRequestContext(c.req.raw)
-                : {};
-
-            const thread = await config.db.threads.getById(userId, threadId);
-
-            if (!thread || thread.agentId !== agentId) {
-                throw new HTTPException(404, { message: "Not found" });
-            }
-
-            return stream(messages, thread, userId, token, requestContext, config);
-        },
-    );
-
-    app.get("/chat/:chatId/stream", requireAuth, async function (c) {
-        const config = c.get("agentConfig");
-        const agentId = c.get("agentId");
-        const chatId = c.req.param("chatId");
-        const thread = await config.db.threads.getById(c.get("user").id, chatId);
-        if (!thread || thread.agentId !== agentId) {
-            throw new HTTPException(404, { message: "Not found" });
-        }
-
-        const subscriberStream = subscribe(chatId);
-        if (!subscriberStream) {
-            return c.body(null, 204);
-        }
-
-        return new Response(subscriberStream.pipeThrough(new TextEncoderStream()), {
-            headers: {
-                "Content-Type": "text/event-stream",
-                "Cache-Control": "no-cache",
-                Connection: "keep-alive",
-            },
-        });
-    });
-
-    app.post("/chat/:chatId/abort", requireAuth, async function (c) {
-        const config = c.get("agentConfig");
-        const agentId = c.get("agentId");
-        const userId = c.get("user").id;
-        const chatId = c.req.param("chatId");
-        const thread = await config.db.threads.getById(userId, chatId);
-        if (!thread || thread.agentId !== agentId) {
-            throw new HTTPException(404, { message: "Not found" });
-        }
-
-        abortStream(chatId);
-        notify(userId, agentId, {
-            type: "thread:run-finished",
-            payload: { thread: toThreadSummary(thread, false) },
-        });
-        return c.body(null, 204);
-    });
-
-    return app;
-}