@bpmsoftwaresolutions/ai-engine-client 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @bpmsoftwaresolutions/ai-engine-client
+
+Thin npm client for AI Engine's supported operator and retrieval APIs.
+
+## Why this package exists
+
+This package is the no-clone distribution shape for coworkers and other consumers.
+
+It does not embed the full AI Engine runtime. It talks to a running AI Engine service over its stable HTTP surfaces.
+
+## Install
+
+```bash
+npm install @bpmsoftwaresolutions/ai-engine-client
+```
+
+## Usage
+
+```js
+import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';
+
+const client = new AIEngineClient({
+  baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io'
+});
+
+const health = await client.ping();
+const workflowStatus = await client.currentWorkflowStatus();
+const procedure = await client.resolveOperatingProcedure({ intentText: 'startup' });
+```
+
+The Azure-hosted base URL above is the current working no-clone path.
+
+## Supported methods
+
+- `ping()`
+- `currentWorkflowStatus()`
+- `currentArchitectureIntegrityStatus()`
+- `currentSecurityGovernanceStatus()`
+- `getCommandCard()`
+- `resolveOperatingProcedure()`
+- `getSymbolDefinition()`
+- `getRelatedCode()`
+
+## Runtime contract
+
+The package expects a running AI Engine web service. The preferred production-style path is the Azure-hosted deployment at:
+
+```text
+https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io
+```
+
+You can also point it at the Flask app from this repo or another deployment exposing the same routes.
+
+Current required HTTP surfaces:
+
+- `/healthz`
+- `/api/operator/current-workflow-status`
+- `/api/operator/current-architecture-integrity-status`
+- `/api/operator/current-security-governance-status`
+- `/api/operator/retrieval/wrapper/command-card`
+- `/api/operator/retrieval/wrapper/operating-procedure`
+- `/api/operator/retrieval/wrapper/symbol-definition`
+- `/api/operator/retrieval/wrapper/related-code`
+
+## Distribution note
+
+This is the preferred distribution shape when the consumer should not clone the full repo. The full repo is still required only when the consumer is running or developing the backend itself.
+
+Known limitation: `getRelatedCode()` is available on the hosted surface, but it currently returns `blocked_insufficient_data` until the relationship index is populated.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@bpmsoftwaresolutions/ai-engine-client",
+  "version": "0.1.0",
+  "description": "Thin npm client for the AI Engine operator and retrieval APIs",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-engine",
+    "sdk",
+    "client",
+    "retrieval",
+    "workflow"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,162 @@
+const DEFAULT_TIMEOUT_MS = 30000;
+
+function trimTrailingSlash(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+function appendQuery(url, query) {
+  const target = new URL(url);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    target.searchParams.set(key, String(value));
+  }
+  return target;
+}
+
+async function readJson(response) {
+  const contentType = response.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+  const text = await response.text();
+  return { message: text };
+}
+
+export class AIEngineClient {
+  constructor({ baseUrl, apiKey, actorId, fetchImpl, timeoutMs } = {}) {
+    if (!baseUrl) {
+      throw new Error('baseUrl is required.');
+    }
+    this.baseUrl = trimTrailingSlash(baseUrl);
+    this.apiKey = apiKey || null;
+    this.actorId = actorId || 'sdk:npm-ai-engine-client';
+    this.fetchImpl = fetchImpl || globalThis.fetch;
+    this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
+    if (typeof this.fetchImpl !== 'function') {
+      throw new Error('A fetch implementation is required. Use Node 18+ or supply fetchImpl.');
+    }
+  }
+
+  static fromEnv(options = {}) {
+    return new AIEngineClient({
+      baseUrl: options.baseUrl || process.env.AI_ENGINE_BASE_URL || process.env.AI_ENGINE_API_BASE_URL,
+      apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
+      actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client'
+    });
+  }
+
+  async ping() {
+    const [health, workflow] = await Promise.all([
+      this._request('/healthz'),
+      this.currentWorkflowStatus()
+    ]);
+    return {
+      status: health.status || 'ok',
+      workflow_name: workflow?.summary?.workflow_name || null,
+      run_status: workflow?.summary?.run_status || null,
+      base_url: this.baseUrl
+    };
+  }
+
+  async currentWorkflowStatus() {
+    return this._request('/api/operator/current-workflow-status');
+  }
+
+  async currentArchitectureIntegrityStatus() {
+    return this._request('/api/operator/current-architecture-integrity-status');
+  }
+
+  async currentSecurityGovernanceStatus({ environment, topN } = {}) {
+    return this._request('/api/operator/current-security-governance-status', {
+      query: {
+        environment,
+        top_n: topN
+      }
+    });
+  }
+
+  async getCommandCard({ commandKey, alias, intentText, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/command-card', {
+      query: {
+        command_key: commandKey,
+        alias,
+        intent_text: intentText,
+        requested_by: requestedBy
+      }
+    });
+  }
+
+  async resolveOperatingProcedure({ procedureKey, intentText, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/operating-procedure', {
+      query: {
+        procedure_key: procedureKey,
+        intent_text: intentText,
+        requested_by: requestedBy
+      }
+    });
+  }
+
+  async getSymbolDefinition({ symbolKey, qualifiedName, symbolName, projectScope, includeCode = true, maxLines = 120, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/symbol-definition', {
+      query: {
+        symbol_key: symbolKey,
+        qualified_name: qualifiedName,
+        symbol_name: symbolName,
+        project_scope: projectScope,
+        include_code: includeCode,
+        max_lines: maxLines,
+        requested_by: requestedBy
+      }
+    });
+  }
+
+  async getRelatedCode({ symbolKey, qualifiedName, relationshipType, depth = 1, includeCode = false, maxLines = 80, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/related-code', {
+      query: {
+        symbol_key: symbolKey,
+        qualified_name: qualifiedName,
+        relationship_type: relationshipType,
+        depth,
+        include_code: includeCode,
+        max_lines: maxLines,
+        requested_by: requestedBy
+      }
+    });
+  }
+
+  async _request(path, { method = 'GET', query, headers, body } = {}) {
+    const url = appendQuery(`${this.baseUrl}${path}`, query);
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: {
+          accept: 'application/json',
+          'content-type': body ? 'application/json' : undefined,
+          'x-actor-id': this.actorId,
+          authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
+          ...headers
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal
+      });
+      const payload = await readJson(response);
+      if (!response.ok) {
+        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+      }
+      return payload;
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
+export function createAIEngineClient(options) {
+  return new AIEngineClient(options);
+}