@exellix/graph-ai-service

FR-AIS compliant AI-service for Exellix graphs. Owns catalog exposure over Catalox graphs and sync invoke via @exellix/jobs → graph-engine.

Complies with the x12i Generic internal AI-service contract (FR-AIS-1…5): docs/ai-services-fr.md. Uses @x12i/core-service + /ai-services/v1/*.

| Field | Value | |-------|--------| | Package | @exellix/graph-ai-service | | CLI | exellix-graph-ai-service serve | | aiServiceType | graph | | Zone | graph-engine (ports 6200–6219, default 6200) | | Catalox catalogs | graphs |

For domain async runs / legacy execute paths, see @exellix/graph-engine-http.

Install and run

npm install @exellix/graph-ai-service
npx exellix-graph-ai-service serve
# → http://127.0.0.1:6200 (or GRAPH_ENGINE_PORT)
# → /health · /_live · /ai-services/v1/*

Copy env.example to .env (or reuse graph-packages/graph-engine/.env).

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /health | Core health (ok reflects Catalox readiness) | | GET | /_live | Live request UI (@x12i/api-live-view) | | GET | /ai-services/v1/descriptor | AI-service descriptor | | GET | /ai-services/v1/items | List graphs (q, tag, limit) | | GET | /ai-services/v1/items/:id | Graph detail | | POST | /ai-services/v1/invoke | Sync execute (itemId → graphId) |

Invoke body

{
  "itemId": "my-graph-id",
  "input": { "foo": 1 },
  "execution": {
    "inputByPath": {},
    "jobId": "optional",
    "debugMode": false,
    "context": {},
    "sourceEntity": "optional",
    "recordId": "optional"
  },
  "correlationId": "optional-fallback"
}

Prefer header x-correlation-id (echoed on the response).

FR-AIS checklist

| # | Check | Status | |---|-------|--------| | 1 | Descriptor: stable aiServiceType, packageId, zoneId, cataloxCatalogIds | yes | | 2 | @x12i/core-service: zone port, /health, /_live, correlation, banner | yes | | 3 | Published package: install → serve → listening process | yes | | 4 | GET /ai-services/v1/descriptor | items | items/:id | yes | | 5 | POST /ai-services/v1/invoke with structured success/error | yes |

Required env

• Catalox + Mongo (same as graph-engine / jobs-api)
• Optional: GRAPH_ENGINE_PORT / GRAPH_AI_SERVICE_PORT
• Optional auth: GRAPH_AI_SERVICE_TOKEN (or GRAPH_ENGINE_HTTP_TOKEN / JOBS_UI_TOKEN)