@cortexa/core 1.0.1 → 1.1.1

package/README.md

@@ -23,6 +23,7 @@
 - [Architecture](#architecture)
 - [Supported Databases](#supported-databases)
 - [CLI Reference](#cli-reference)
+- [REST API](#rest-api)
 - [Configuration](#configuration)
 - [Requirements](#requirements)
 - [Contributing](#contributing)
@@ -307,6 +308,85 @@ npm install @powersync/mysql-zongji
 | `cortexa actions` | View and manage action recommendations |
 | `cortexa explain <type> <id>` | AI explanation of anomaly, insight, or event |
 | `cortexa ask "<question>"` | Ask a natural language question |
+| `cortexa serve` | Start REST API server (`--port`, `--host`) |
+
+## REST API
+
+Start the HTTP server to access Cortexa from any language (Python, Go, Ruby, etc.):
+
+```bash
+npx cortexa serve
+# Cortexa API running at http://127.0.0.1:3210
+```
+
+Options: `--port <port>` (default: 3210), `--host <host>` (default: 127.0.0.1), `--no-cors`.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/status` | Connection status |
+| GET | `/api/entities` | List classified entities |
+| GET | `/api/relationships` | List entity relationships |
+| GET | `/api/events` | List change events (`?entity=`, `?last=`) |
+| GET | `/api/baselines` | Learned rate baselines |
+| GET | `/api/anomalies` | Detected anomalies (`?severity=`, `?entity=`) |
+| GET | `/api/insights` | State analysis insights (`?entity=`, `?severity=`) |
+| GET | `/api/transitions` | Transition statistics (`?entity=`) |
+| GET | `/api/correlations` | Cross-entity correlations |
+| GET | `/api/distributions` | Value distributions (`?entity=`) |
+| GET | `/api/graph` | Knowledge graph summary |
+| GET | `/api/graph/export` | Full graph as JSON |
+| GET | `/api/graph/entity/:name` | Entity intelligence |
+| GET | `/api/actions` | Recommendations (`?status=`, `?action=`) |
+| POST | `/api/discover` | Trigger schema discovery |
+| POST | `/api/explain` | AI explanation (`{ type, id }`) |
+| POST | `/api/ask` | Natural language question (`{ question }`) |
+| POST | `/api/watch` | Start watching (`{ interval, once }`) |
+| POST | `/api/unwatch` | Stop watching |
+| POST | `/api/actions/:id/approve` | Approve recommendation |
+| POST | `/api/actions/:id/reject` | Reject recommendation |
+
+All responses return `{ ok: boolean, data?: ..., error?: string }`.
+
+### Examples
+
+```bash
+# Get anomalies
+curl http://localhost:3210/api/anomalies?severity=high
+
+# Ask a question
+curl -X POST http://localhost:3210/api/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "Why did order activity spike today?"}'
+
+# Explain an anomaly
+curl -X POST http://localhost:3210/api/explain \
+  -H "Content-Type: application/json" \
+  -d '{"type": "anomaly", "id": 1}'
+```
+
+```python
+# Python example
+import requests
+
+r = requests.get("http://localhost:3210/api/anomalies", params={"severity": "high"})
+print(r.json()["data"])
+
+r = requests.post("http://localhost:3210/api/ask", json={"question": "Are orders healthy?"})
+print(r.json()["data"]["answer"])
+```
+
+### Programmatic usage
+
+```ts
+import { CortexaServer } from '@cortexa/core';
+
+const server = new CortexaServer(config, { port: 3210, cors: true });
+await server.start();
+// ... later
+await server.stop();
+```
 
 ## Configuration
 

package/dist/cli/index.js

@@ -4742,6 +4742,283 @@ Return valid JSON in this exact format:
   }
 };
 
+// src/server/server.ts
+import { createServer } from "http";
+
+// src/server/router.ts
+var Router = class {
+  routes = [];
+  get(path4, handler) {
+    this.addRoute("GET", path4, handler);
+  }
+  post(path4, handler) {
+    this.addRoute("POST", path4, handler);
+  }
+  addRoute(method, path4, handler) {
+    const paramNames = [];
+    const patternStr = path4.replace(/:(\w+)/g, (_match, name) => {
+      paramNames.push(name);
+      return "([^/]+)";
+    });
+    this.routes.push({
+      method,
+      pattern: new RegExp(`^${patternStr}$`),
+      paramNames,
+      handler
+    });
+  }
+  async handle(req, res, cors) {
+    if (cors) {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    }
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const path4 = url.pathname;
+    const method = req.method ?? "GET";
+    const query = {};
+    url.searchParams.forEach((value, key) => {
+      query[key] = value;
+    });
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      const match = route.pattern.exec(path4);
+      if (!match) continue;
+      const pathParams = {};
+      for (let i = 0; i < route.paramNames.length; i++) {
+        pathParams[route.paramNames[i]] = match[i + 1];
+      }
+      let body = void 0;
+      if (method === "POST") {
+        body = await readBody(req);
+      }
+      const params = { path: path4, method, query, body, pathParams };
+      try {
+        const result = await route.handler(params);
+        sendJson(res, result.ok ? 200 : 400, result);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Internal server error";
+        sendJson(res, 500, { ok: false, error: message });
+      }
+      return;
+    }
+    sendJson(res, 404, { ok: false, error: `Not found: ${method} ${path4}` });
+  }
+};
+function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString();
+      if (!raw) {
+        resolve(void 0);
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+// src/server/handlers.ts
+function registerHandlers(router, cortexa) {
+  router.get("/api/status", async () => {
+    return { ok: true, data: cortexa.status };
+  });
+  router.get("/api/entities", async () => {
+    const { entities } = cortexa.exportGraph();
+    return { ok: true, data: entities };
+  });
+  router.get("/api/relationships", async () => {
+    const { relationships } = cortexa.exportGraph();
+    return { ok: true, data: relationships };
+  });
+  router.post("/api/discover", async (params) => {
+    const body = params.body ?? {};
+    const result = await cortexa.discover({
+      includeSampleData: body.includeSampleData !== false,
+      excludeTables: body.excludeTables,
+      excludeColumns: body.excludeColumns
+    });
+    return {
+      ok: true,
+      data: {
+        tables: result.raw.tables.length,
+        entities: result.entities.length,
+        relationships: result.relationships.length
+      }
+    };
+  });
+  router.get("/api/events", async (params) => {
+    const filter = {};
+    if (params.query.entity) filter.entity = params.query.entity;
+    if (params.query.last) filter.last = parseInt(params.query.last, 10);
+    if (params.query.operation) filter.operation = params.query.operation;
+    return { ok: true, data: cortexa.getEvents(filter) };
+  });
+  router.get("/api/baselines", async () => {
+    return { ok: true, data: cortexa.getBaselines() };
+  });
+  router.get("/api/anomalies", async (params) => {
+    const filter = {};
+    if (params.query.entity) filter.entity = params.query.entity;
+    if (params.query.last) filter.last = parseInt(params.query.last, 10);
+    if (params.query.severity) filter.severity = params.query.severity;
+    return { ok: true, data: cortexa.getAnomalies(filter) };
+  });
+  router.get("/api/insights", async (params) => {
+    const filter = {};
+    if (params.query.entity) filter.entity = params.query.entity;
+    if (params.query.last) filter.last = parseInt(params.query.last, 10);
+    if (params.query.severity) filter.severity = params.query.severity;
+    return { ok: true, data: cortexa.getInsights(filter) };
+  });
+  router.get("/api/transitions", async (params) => {
+    return { ok: true, data: cortexa.getTransitions(params.query.entity) };
+  });
+  router.get("/api/correlations", async () => {
+    return { ok: true, data: cortexa.getCorrelations() };
+  });
+  router.get("/api/distributions", async (params) => {
+    return { ok: true, data: cortexa.getDistributions(params.query.entity) };
+  });
+  router.get("/api/graph", async () => {
+    return { ok: true, data: cortexa.graph().getSummary() };
+  });
+  router.get("/api/graph/export", async () => {
+    return { ok: true, data: cortexa.graph().export() };
+  });
+  router.get("/api/graph/entity/:name", async (params) => {
+    const intel = cortexa.graph().entity(params.pathParams.name).intelligence();
+    if (!intel) {
+      return { ok: false, error: `Entity "${params.pathParams.name}" not found in knowledge graph` };
+    }
+    return { ok: true, data: intel };
+  });
+  router.get("/api/actions", async (params) => {
+    const filter = {};
+    if (params.query.status) filter.status = params.query.status;
+    if (params.query.action) filter.action = params.query.action;
+    return { ok: true, data: cortexa.getRecommendations(filter) };
+  });
+  router.post("/api/actions/:id/approve", async (params) => {
+    const id = parseInt(params.pathParams.id, 10);
+    if (isNaN(id)) return { ok: false, error: "Invalid id" };
+    cortexa.approveRecommendation(id);
+    return { ok: true, data: { id, status: "approved" } };
+  });
+  router.post("/api/actions/:id/reject", async (params) => {
+    const id = parseInt(params.pathParams.id, 10);
+    if (isNaN(id)) return { ok: false, error: "Invalid id" };
+    cortexa.rejectRecommendation(id);
+    return { ok: true, data: { id, status: "rejected" } };
+  });
+  router.post("/api/explain", async (params) => {
+    const body = params.body;
+    if (!body?.type || !body?.id) {
+      return { ok: false, error: 'Required: { type: "anomaly"|"insight"|"event"|"entity", id: number }' };
+    }
+    const target = {
+      type: body.type,
+      id: body.id
+    };
+    const result = await cortexa.explain(target);
+    return { ok: true, data: result };
+  });
+  router.post("/api/ask", async (params) => {
+    const body = params.body;
+    if (!body?.question || typeof body.question !== "string") {
+      return { ok: false, error: "Required: { question: string }" };
+    }
+    const result = await cortexa.ask(body.question, {
+      entityHint: body.entity
+    });
+    return { ok: true, data: result };
+  });
+  router.post("/api/watch", async (params) => {
+    const body = params.body ?? {};
+    await cortexa.watch({
+      interval: body.interval,
+      once: body.once
+    });
+    return { ok: true, data: { watching: true } };
+  });
+  router.post("/api/unwatch", async () => {
+    cortexa.unwatch();
+    return { ok: true, data: { watching: false } };
+  });
+}
+
+// src/server/server.ts
+var CortexaServer = class {
+  cortexa;
+  serverConfig;
+  logger;
+  httpServer = null;
+  constructor(cortexaConfig, serverConfig) {
+    this.cortexa = new Cortexa(cortexaConfig);
+    this.serverConfig = {
+      port: serverConfig?.port ?? 3210,
+      host: serverConfig?.host ?? "127.0.0.1",
+      cors: serverConfig?.cors ?? true
+    };
+    this.logger = createLogger();
+  }
+  async start() {
+    await this.cortexa.connect();
+    const router = new Router();
+    registerHandlers(router, this.cortexa);
+    const cors = this.serverConfig.cors ?? true;
+    this.httpServer = createServer((req, res) => {
+      router.handle(req, res, cors).catch((err) => {
+        this.logger.error({ err }, "Unhandled request error");
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "Internal server error" }));
+      });
+    });
+    const { port, host } = this.serverConfig;
+    await new Promise((resolve) => {
+      this.httpServer.listen(port, host, () => {
+        this.logger.info({ port, host }, "Cortexa REST API server started");
+        resolve();
+      });
+    });
+  }
+  async stop() {
+    if (this.httpServer) {
+      await new Promise((resolve, reject) => {
+        this.httpServer.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+      this.httpServer = null;
+    }
+    await this.cortexa.disconnect();
+    this.logger.info("Cortexa REST API server stopped");
+  }
+  get address() {
+    return {
+      port: this.serverConfig.port ?? 3210,
+      host: this.serverConfig.host ?? "127.0.0.1"
+    };
+  }
+};
+
 // src/index.ts
 var KnowledgeGraph = class {
   store;
@@ -5811,6 +6088,58 @@ Related Entities: ${result.relatedEntities.join(", ")}`);
   }
 }
 
+// src/cli/serve.ts
+async function runServe(options) {
+  try {
+    const config = await loadConfig();
+    const port = options.port ? parseInt(options.port, 10) : 3210;
+    const host = options.host ?? "127.0.0.1";
+    const server = new CortexaServer(
+      { ...config, projectRoot: process.cwd() },
+      { port, host, cors: !options.noCors }
+    );
+    console.log("Starting Cortexa REST API server...");
+    await server.start();
+    console.log("");
+    console.log(`  Cortexa API running at http://${host}:${port}`);
+    console.log("");
+    console.log("  Endpoints:");
+    console.log("    GET  /api/status          Connection status");
+    console.log("    GET  /api/entities         List entities");
+    console.log("    GET  /api/relationships    List relationships");
+    console.log("    GET  /api/events           List events");
+    console.log("    GET  /api/baselines        List baselines");
+    console.log("    GET  /api/anomalies        List anomalies");
+    console.log("    GET  /api/insights         List insights");
+    console.log("    GET  /api/transitions      Transition stats");
+    console.log("    GET  /api/correlations     Correlation status");
+    console.log("    GET  /api/distributions    Distribution summaries");
+    console.log("    GET  /api/graph            Knowledge graph summary");
+    console.log("    GET  /api/graph/export     Export full graph");
+    console.log("    GET  /api/graph/entity/:n  Entity intelligence");
+    console.log("    GET  /api/actions          Recommendations");
+    console.log("    POST /api/discover         Trigger discovery");
+    console.log("    POST /api/explain          Explain anomaly/insight");
+    console.log("    POST /api/ask              Ask a question");
+    console.log("    POST /api/watch            Start watching");
+    console.log("    POST /api/unwatch          Stop watching");
+    console.log("    POST /api/actions/:id/approve");
+    console.log("    POST /api/actions/:id/reject");
+    console.log("");
+    console.log("  Press Ctrl+C to stop");
+    const shutdown = async () => {
+      console.log("\nShutting down...");
+      await server.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 // src/cli/banner.ts
 var RESET = "\x1B[0m";
 var BOLD = "\x1B[1m";
@@ -5917,5 +6246,8 @@ program.command("explain <type> <id>").description("Explain why an anomaly, insi
 program.command("ask <question>").description("Ask a natural language question about your database").option("--json", "Output raw JSON instead of formatted text").option("--entity <name>", "Focus context on a specific entity").action(async (question, options) => {
   await runAsk(question, options);
 });
+program.command("serve").description("Start REST API server for cross-language access").option("--port <port>", "Port to listen on (default: 3210)").option("--host <host>", "Host to bind to (default: 127.0.0.1)").option("--no-cors", "Disable CORS headers").action(async (options) => {
+  await runServe(options);
+});
 program.parse();
 //# sourceMappingURL=index.js.map