@x12i/nexum

Nexum

Nexum turns org knowledge into a knowledge graph.

Accepts content, records, JSON Schema, OpenAPI / endpoints, and object properties. Isolation is always per organization (graphified-<orgId> Mongo DB). Optional agentId is host/Memorix context only.

npm install @x12i/nexum@^2.0.1
# bins: nexum-worker, nexum-semantic-bridge

Which API for which job

Job	Use	Store
Memorix pipeline analyze → write-record	Capability worker nexum-worker / createNexumWorker	Memorix subjects
Embed org/item graph in a host app	Explore SDK createNexumClient → Python REST	Mongo graphified-{orgId}
SPA explorer	ui/ → Python REST	Mongo
Optional prose enrichment	nexum-semantic-bridge + .funcx/ (assistant-functions)	Feeds Mongo ingest only

Pipeline success does not fill SPA Mongo; SPA ingest does not fill Memorix subjects. See docs/adr/0001-nexum-dual-surface.md.

Two surfaces

You want	Use
Embed an org or item graph in a host app	Explore SDK — createNexumClient
Pipeline analyze drafts for Memorix write-record	Capability worker — createNexumWorker / buildAnalyzeDraft

This package does not ship the React explorer under ui/. Analyze never writes Memorix subjects or Mongo domain data; REST POST …/ingestions (deprecated alias /graphify) is the persist path for the explore API.

Explore SDK — host views

import {
  createNexumClient,
  graphViewFrom,
  isGraphifierApiError,
} from "@x12i/nexum";

const client = createNexumClient({
  baseUrl: "http://127.0.0.1:8080",
  orgId: "authix",
  agentId: "opx", // host context only — not a DB filter
  graphId: "default",
});

try {
  // Org canvas (nodes include properties — schemas/endpoints keep their payload)
  const viz = await client.getVisualization({
    maximumNodes: 500,
    nodeTypes: ["schema", "endpoint", "property", "openapi"],
  });

  // Item ego-network
  const around = await client.getItemNeighborhood("default", "user-schema", {
    depth: 1,
  });

  const view = graphViewFrom(around); // { nodes, edges } for Cytoscape / Sigma / custom
  console.log(client.scope, view.nodes.length);

  // Preferred ingest
  await client.ingestions.submit({
    mode: "upsert",
    items: [/* … */],
  });
} catch (err) {
  if (isGraphifierApiError(err)) {
    console.error(err.code, err.status, err.message);
  } else {
    throw err;
  }
}

View scopes

View intent	SDK usage
Org graph	getVisualization / searchNodes / getNeighbors
Item + connected	getItemNeighborhood(graphId, itemId, { depth })
Schema / endpoint slice	getVisualization({ nodeTypes: ["schema","endpoint","property"] }) or listNodes(graphId, { type: "endpoint" })

forScope({ orgId, agentId, graphId }) clones the client. REST paths are always /v1/orgs/{orgId}/…. See examples/explore-host-view.ts.

Graphify schemas, endpoints, and objects

Content and record-shaped items still work. Structured JSON that looks like a schema or API is graphified without registering JSONPath object-types:

• JSON Schema — $schema or a properties map of objects → schema + property nodes, has_property / refs
• OpenAPI — openapi / swagger or paths → openapi + endpoint nodes, exposes / uses_schema
• Endpoint object — method + path (or url)
• Nested objects — child nodes + has_property (depth 2). Scalar record fields (e.g. name, ownerTeamId) stay on the entity; they are not exploded into property nodes

Offline draft (no REST)

import { buildAnalyzeDraft, SERVICE_ID } from "@x12i/nexum";

const draft = buildAnalyzeDraft(
  {
    schemas: [
      {
        id: "user",
        title: "User",
        $schema: "https://json-schema.org/draft/2020-12/schema",
        properties: { email: { type: "string" } },
      },
    ],
  },
  { serviceId: SERVICE_ID },
);
// draft.proposedGraph.nodes / .edges — same envelope as analyze since 2.0.0

Bags: items, records, snapshot, schemas, endpoints, objects.

Persist via REST

await client.graphify({
  items: [
    {
      id: "pets-api",
      inputType: "structured",
      objectType: "openapi",
      data: {
        openapi: "3.0.0",
        paths: { "/pets": { get: { operationId: "listPets" } } },
      },
    },
  ],
});

Optional putObjectType / listObjectTypes still apply JSONPath mappings when you want them; they are not required for schema/endpoint ingest. Full sample: examples/graphify-schema-endpoint.ts.

Requires the Nexum REST API (memorix_graphifier Python package, typically :8080).

Env (operator-side)

Variable	Purpose
NEXUM_API_URL / GRAPHIFIER_API_URL	REST base for the client
NEXUM_DEFAULT_ORG_ID / GRAPHIFIER_DEFAULT_ORG_ID	Default orgId or full graphified-<orgId>
NEXUM_DEFAULT_GRAPH_ID / GRAPHIFIER_DEFAULT_GRAPH_ID	Default graph id (default)
NEXUM_SEMANTIC_MODE	off | enrich | required (Mongo ingest)
NEXUM_SEMANTIC_PROFILE	ai-profiles profile/choice (default extraction/default)
OPENROUTER_API_KEY	FuncX / assistant-functions (semantic enrich)

Capability worker (Memorix pipelines)

Analyze → persist envelope: proposedGraph + sourceRefs + diagnostics (since 2.0.0). Platform sequence is analyze → write-record. Details: docs/memorix-binding.md.

npm install
npm test
npm start   # or: nexum-worker

Worker listen URL is printed as JSON (endpoint → ServiceRef). Defaults: host 127.0.0.1, port 7500 (ports zone nexum; ports-manager map key memorix-graphier).

• serviceId: nexum
• operation: analyze
• Pack: metadata/services.json
• Sample pipeline: examples/pipeline.v2.json

import {
  nexumCapability,
  createNexumWorker,
  SERVICE_ID,
} from "@x12i/nexum";

Depends on @x12i/memorix-sdk only. Do not install Memorix engine packages in this app.

Manual invoke

curl -sS -X POST "http://127.0.0.1:${NEXUM_WORKER_PORT:-7500}/" \
  -H 'content-type: application/json' \
  -d '{
    "version":"memorix-capability/1",
    "serviceId":"nexum",
    "operation":"analyze",
    "scope":{"orgId":"sandbox1","agentIds":["opx"]},
    "execution":{
      "runId":"r1","stepId":"s1","attempt":1,"correlationId":"c1"
    },
    "inputs":{
      "items":[
        {"id":"credorix","inputType":"structured","objectType":"product",
         "data":{"name":"Credorix","ownerTeamId":"identity-team"}}
      ]
    }
  }'

Smoke and CI fixtures: sandbox* orgs and agentIds: ["opx"] only.

Python REST (SPA / SDK)

memorix_graphifier/ is a FastAPI + Mongo explore/ingest API. It is not the Memorix called-service surface. The explore SDK uses it as the data plane.

export NEXUM_USE_MEMORY_STORE=true
# or GRAPHIFIER_USE_MEMORY_STORE=true
pip install -e ".[dev]"

See ARCHITECTURE.md. Internals: docs/graphify-internals.md.

Knowledge Graph UI

Optional full SPA (not this npm package):

# API: set GRAPHIFIER_CORS_ORIGINS=http://127.0.0.1:7501
cd ui && cp .env.example .env && npm install && npm run dev
# open http://127.0.0.1:7501/organizations/<orgId>/knowledge-graph

Details: ui/README.md.

License

Apache License 2.0. Upstream Graphify attribution is retained in NOTICE and LICENSE-MIT for applicable portions.