@bpmsoftwaresolutions/ai-engine-client 0.1.0 → 1.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +328 -69
  2. package/package.json +1 -1
  3. package/src/index.js +949 -162
package/README.md CHANGED
@@ -1,69 +1,328 @@
1
- # @bpmsoftwaresolutions/ai-engine-client
2
-
3
- Thin npm client for AI Engine's supported operator and retrieval APIs.
4
-
5
- ## Why this package exists
6
-
7
- This package is the no-clone distribution shape for coworkers and other consumers.
8
-
9
- It does not embed the full AI Engine runtime. It talks to a running AI Engine service over its stable HTTP surfaces.
10
-
11
- ## Install
12
-
13
- ```bash
14
- npm install @bpmsoftwaresolutions/ai-engine-client
15
- ```
16
-
17
- ## Usage
18
-
19
- ```js
20
- import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';
21
-
22
- const client = new AIEngineClient({
23
- baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io'
24
- });
25
-
26
- const health = await client.ping();
27
- const workflowStatus = await client.currentWorkflowStatus();
28
- const procedure = await client.resolveOperatingProcedure({ intentText: 'startup' });
29
- ```
30
-
31
- The Azure-hosted base URL above is the current working no-clone path.
32
-
33
- ## Supported methods
34
-
35
- - `ping()`
36
- - `currentWorkflowStatus()`
37
- - `currentArchitectureIntegrityStatus()`
38
- - `currentSecurityGovernanceStatus()`
39
- - `getCommandCard()`
40
- - `resolveOperatingProcedure()`
41
- - `getSymbolDefinition()`
42
- - `getRelatedCode()`
43
-
44
- ## Runtime contract
45
-
46
- The package expects a running AI Engine web service. The preferred production-style path is the Azure-hosted deployment at:
47
-
48
- ```text
49
- https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io
50
- ```
51
-
52
- You can also point it at the Flask app from this repo or another deployment exposing the same routes.
53
-
54
- Current required HTTP surfaces:
55
-
56
- - `/healthz`
57
- - `/api/operator/current-workflow-status`
58
- - `/api/operator/current-architecture-integrity-status`
59
- - `/api/operator/current-security-governance-status`
60
- - `/api/operator/retrieval/wrapper/command-card`
61
- - `/api/operator/retrieval/wrapper/operating-procedure`
62
- - `/api/operator/retrieval/wrapper/symbol-definition`
63
- - `/api/operator/retrieval/wrapper/related-code`
64
-
65
- ## Distribution note
66
-
67
- 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.
68
-
69
- Known limitation: `getRelatedCode()` is available on the hosted surface, but it currently returns `blocked_insufficient_data` until the relationship index is populated.
1
+ # @bpmsoftwaresolutions/ai-engine-client
2
+
3
+ Full-surface npm client for the AI Engine. Covers every operator, workflow, project, retrieval, performance, and governance endpoint exposed by the deployed service.
4
+
5
+ No repo clone required. Install the package, point it at the Azure service, and call any method.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @bpmsoftwaresolutions/ai-engine-client
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ ```js
16
+ import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';
17
+
18
+ const client = new AIEngineClient({
19
+ baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io'
20
+ });
21
+
22
+ // Health
23
+ const health = await client.ping();
24
+
25
+ // Load current SQL memory projection (startup hydration)
26
+ const memory = await client.getLatestMemoryProjection();
27
+
28
+ // Create a project charter (writes to durable SQL memory)
29
+ const charter = await client.createProjectCharter({
30
+ projectName: 'Data-Driven UI',
31
+ objective: 'Build a Postgres-backed data-driven UI system with a stable renderer and live operator panel.',
32
+ businessContext: 'Enables live demo edits during sales calls without code deploys.',
33
+ successCriteria: 'Pages, blocks, and tokens are fully CRUD-managed via API. Renderer is frozen.',
34
+ priority: 'high',
35
+ inScope: ['pages', 'blocks', 'style tokens', 'versions', 'operator panel'],
36
+ outOfScope: ['drag-and-drop builder', 'custom animation engine'],
37
+ });
38
+
39
+ // Read the resulting project roadmap
40
+ const roadmap = await client.getProjectRoadmap(charter.project_id);
41
+ ```
42
+
43
+ ### fromEnv
44
+
45
+ ```js
46
+ const client = AIEngineClient.fromEnv();
47
+ // Reads: AI_ENGINE_BASE_URL, AI_ENGINE_API_KEY, AI_ENGINE_ACTOR_ID
48
+ ```
49
+
50
+ ---
51
+
52
+ ## Constructor Options
53
+
54
+ | Option | Type | Description |
55
+ |---|---|---|
56
+ | `baseUrl` | string | **Required.** Base URL of the AI Engine service. |
57
+ | `apiKey` | string | Bearer token sent as `Authorization` header. |
58
+ | `actorId` | string | Sent as `X-Actor-Id` for audit trails. Default: `sdk:npm-ai-engine-client`. |
59
+ | `fetchImpl` | function | Custom fetch (Node 18+ built-in used by default). |
60
+ | `timeoutMs` | number | Per-request timeout in ms. Default: 30000. |
61
+
62
+ ---
63
+
64
+ ## Methods
65
+
66
+ ### Health
67
+ | Method | Description |
68
+ |---|---|
69
+ | `ping()` | Health check + current workflow name/status. |
70
+
71
+ ### Operator Status
72
+ | Method | Description |
73
+ |---|---|
74
+ | `currentWorkflowStatus()` | Current workflow run state. |
75
+ | `currentArchitectureIntegrityStatus()` | Architecture integrity scan results. |
76
+ | `currentSecurityGovernanceStatus({ environment, topN })` | Security governance findings. |
77
+ | `currentCodebaseShapeStatus()` | Codebase shape analysis. |
78
+ | `getLatestMemoryProjection()` | Current SQL memory projection (startup hydration source). |
79
+ | `getDashboard()` | Operator dashboard payload. |
80
+
81
+ ### Retrieval Wrapper
82
+ | Method | Description |
83
+ |---|---|
84
+ | `getCommandCard({ commandKey, alias, intentText, requestedBy })` | Resolve a command card by key, alias, or intent. |
85
+ | `resolveOperatingProcedure({ procedureKey, intentText, requestedBy })` | Resolve an operating procedure. |
86
+ | `getSymbolDefinition({ symbolName, qualifiedName, ... })` | Symbol/code definition lookup. |
87
+ | `getRelatedCode({ symbolKey, qualifiedName, relationshipType, ... })` | Related code lookup. |
88
+
89
+ ### Retrieval Management
90
+ | Method | Description |
91
+ |---|---|
92
+ | `getRetrievalStatus()` | Retrieval status dashboard. |
93
+ | `getRetrievalProfileMetrics()` | Profile-level retrieval metrics. |
94
+ | `getRetrievalFeedbackMetrics()` | Feedback signal metrics. |
95
+ | `getRetrievalQuery(id)` | Get retrieval query detail. |
96
+ | `getRetrievalPacket(id)` | Get retrieval packet detail. |
97
+ | `generateRetrievalCandidates(body)` | Generate candidate packets. |
98
+ | `selectRetrievalPacket(body)` | Select a packet for use. |
99
+ | `recordRetrievalFeedback(body)` | Record feedback on a retrieval result. |
100
+ | `deriveRetrievalOptimizationCandidates(body)` | Derive optimization candidates. |
101
+ | `validatePromptAssembly(body)` | Validate a prompt assembly. |
102
+
103
+ ### Workflows
104
+ | Method | Description |
105
+ |---|---|
106
+ | `listWorkflows({ status, includeSteps })` | List workflows. |
107
+ | `createWorkflow({ name, slug, description, goal, ... })` | Create a workflow draft. |
108
+ | `getWorkflow(workflowId)` | Get workflow detail. |
109
+ | `replaceWorkflowSteps(workflowId, steps)` | Replace workflow steps. |
110
+ | `publishWorkflow(workflowId)` | Publish a workflow. |
111
+ | `cloneWorkflow(workflowId)` | Clone a workflow. |
112
+
113
+ ### Workflow Governance
114
+ | Method | Description |
115
+ |---|---|
116
+ | `evaluateWorkflowGovernance(workflowId)` | Run governance evaluation. |
117
+ | `listWorkflowGovernanceDecisions(workflowId)` | List governance decisions. |
118
+ | `getWorkflowGovernanceSimulation(workflowId)` | Governance simulation packet. |
119
+ | `listWorkflowGovernanceBundles(workflowId)` | Gate bundles. |
120
+ | `listWorkflowGovernanceApprovals(workflowId)` | Gate approvals. |
121
+ | `listWorkflowGovernanceEvents(workflowId)` | Gate events. |
122
+ | `getWorkflowGovernanceReview(workflowId)` | Governance review. |
123
+ | `createWorkflowGovernanceReviewDecision(workflowId, body)` | Record a review decision. |
124
+
125
+ ### Workflow Runs
126
+ | Method | Description |
127
+ |---|---|
128
+ | `createWorkflowRun(body)` | Start a workflow run. |
129
+ | `getWorkflowRun(workflowRunId)` | Get run detail. |
130
+ | `listWorkflowArtifacts(workflowRunId)` | List run artifacts. |
131
+ | `getWorkflowRunSubstrate(workflowRunId)` | Get run substrate (sessions, turns). |
132
+ | `resumeWorkflowRun(workflowRunId, body)` | Resume a paused run. |
133
+ | `listRecentInspectorRuns({ limit })` | List recent runs via inspector. |
134
+ | `inspectWorkflowRun(workflowRunId)` | Full inspector view of a run. |
135
+
136
+ ### Manual & Approval Tasks
137
+ | Method | Description |
138
+ |---|---|
139
+ | `listManualTasks()` | List tasks awaiting manual completion. |
140
+ | `listApprovalTasks()` | List tasks awaiting approval. |
141
+ | `completeManualTask(stepRunId, body)` | Complete a manual step. |
142
+ | `approveTask(stepRunId, body)` | Approve a step. |
143
+
144
+ ### Projects & Chartering
145
+ | Method | Description |
146
+ |---|---|
147
+ | `createProjectCharter({ projectName, objective, businessContext, successCriteria, priority, constraints, inScope, outOfScope, assumptions, linkedWorkflows, testingStrategy, initialContext, requestedBy })` | Charter a project (writes to durable SQL memory). |
148
+ | `listProjects({ limit, includeInactive, processStatus, charterStatus })` | List projects. |
149
+ | `getProject(projectId)` | Get project detail. |
150
+
151
+ ### Roadmaps
152
+ | Method | Description |
153
+ |---|---|
154
+ | `listProjectRoadmaps({ includeInactive })` | List all project roadmaps. |
155
+ | `getProjectRoadmap(projectId)` | Get full roadmap for a project. |
156
+ | `getProjectRoadmapSummary(projectId)` | Roadmap summary. |
157
+ | `getProjectRoadmapActiveItem(projectId)` | Current active roadmap item. |
158
+ | `listProjectOpenTasks(projectId)` | Open tasks for a project. |
159
+ | `getProjectPerformanceMetrics(projectId, { workflowId, workflowRunId, sinceUtc })` | Performance metrics. |
160
+
161
+ ### Implementation Tasks
162
+ | Method | Description |
163
+ |---|---|
164
+ | `createImplementationTask(implementationItemId, { title, implementationPacketId, ... })` | Create a task on a roadmap item. |
165
+ | `listImplementationTasks(implementationItemId)` | List tasks. |
166
+ | `listImplementationSubtasks(taskId)` | List subtasks. |
167
+ | `updateImplementationTask(taskId, updates)` | Update a task. |
168
+ | `assignImplementationTask(taskId, { assignedTo, assignedBy })` | Assign a task. |
169
+ | `completeImplementationTask(taskId, { completedBy })` | Mark complete. |
170
+
171
+ ### Governed Implementation
172
+ | Method | Description |
173
+ |---|---|
174
+ | `importImplementationPacket(body)` | Import an implementation packet. |
175
+ | `listImplementationPackets({ status, packetType })` | List packets. |
176
+ | `getImplementationPacket(packetId)` | Packet detail. |
177
+ | `updateImplementationItemStatus(itemId, body)` | Update item status. |
178
+ | `addImplementationItemEvidence(itemId, body)` | Add evidence link. |
179
+ | `addImplementationItemActivity(itemId, body)` | Add activity entry. |
180
+ | `listImplementationItemActivity(itemId)` | List item activity. |
181
+ | `updateAcceptanceCheckStatus(itemId, checkId, body)` | Update acceptance check. |
182
+ | `createImplementationPacketGateDecision(packetId, body)` | Record gate decision. |
183
+ | `bindImplementationPacketToWorkflow(workflowId, body)` | Bind packet to workflow. |
184
+ | `getWorkflowImplementationRoadmap(workflowId)` | Workflow-linked roadmap. |
185
+ | `getWorkflowResumeContext(workflowId)` | Resume context. |
186
+
187
+ ### Skills
188
+ | Method | Description |
189
+ |---|---|
190
+ | `currentSkillRegistryStatus()` | Current skill registry status. |
191
+ | `getSkillContract({ skillId, skillKey })` | Skill contract. |
192
+ | `getSkillGovernance({ skillId, skillKey, skillVersionId })` | Skill governance posture. |
193
+ | `createSkillContractDraft(body)` | Create a skill contract draft. |
194
+ | `recordSkillPatternReview(skillVersionId, body)` | Record pattern review. |
195
+ | `approveSkillContract(skillVersionId, body)` | Approve skill contract. |
196
+ | `createWorkflowSkillContract(body)` | Create workflow skill contract. |
197
+ | `listWorkflowSkillBindings(workflowId, { workflowStepId })` | List skill bindings. |
198
+ | `seedFrequentOperationSkills({ createdBy })` | Seed frequent operation skills. |
199
+
200
+ ### Skill Governance
201
+ | Method | Description |
202
+ |---|---|
203
+ | `createSkillGovernanceChange(body)` | Create a skill governance change. |
204
+ | `listSkillGovernanceChanges({ limit, processStatus, changeStatus })` | List changes. |
205
+ | `getSkillGovernanceChange(governanceChangeId)` | Change detail. |
206
+
207
+ ### Capabilities
208
+ | Method | Description |
209
+ |---|---|
210
+ | `listCapabilities()` | List capabilities. |
211
+ | `createCapability(body)` | Create a capability. |
212
+ | `testCapability(capabilityId, body)` | Test a capability. |
213
+
214
+ ### Tool Registry
215
+ | Method | Description |
216
+ |---|---|
217
+ | `currentToolRegistryStatus()` | Current tool registry status. |
218
+ | `getWorkflowToolRegistry({ workflowId, workflowSlug })` | Workflow-scoped tool registry. |
219
+ | `currentAssistantToolContext()` | Current assistant tool context. |
220
+ | `getTool(toolKey)` | Tool definition detail. |
221
+ | `getToolHistory(toolKey)` | Tool version history. |
222
+ | `getToolInvocations(toolKey)` | Tool invocation history. |
223
+ | `getToolGovernance(toolKey)` | Tool governance posture. |
224
+ | `getToolEventReplayBundle(toolEventSummaryId)` | Tool execution replay bundle. |
225
+ | `createToolReviewDecision(toolKey, body)` | Create tool review decision. |
226
+ | `createToolGateDecision(toolKey, body)` | Create tool gate decision. |
227
+
228
+ ### Context Assembly
229
+ | Method | Description |
230
+ |---|---|
231
+ | `getContextAssemblyContract(workflowRunId, { stepRunId })` | Context assembly contract. |
232
+ | `getContextAssemblyStatus(workflowRunId, { stepRunId })` | Context assembly status. |
233
+ | `getOperatorContext(workflowRunId, { stepRunId })` | Operator context for a run. |
234
+ | `getContextFragments(workflowRunId, { stepRunId })` | Context fragments. |
235
+ | `getContextReuse(workflowRunId, { stepRunId })` | Context reuse metrics. |
236
+ | `listPromptAssemblies(workflowRunId)` | Prompt assembly history. |
237
+
238
+ ### Performance
239
+ | Method | Description |
240
+ |---|---|
241
+ | `getSessionPerformanceMetrics({ clientType, workflowRunId, sessionId })` | Session metrics. |
242
+ | `captureBenchmarkSnapshot(body)` | Capture benchmark snapshot. |
243
+ | `listBenchmarks({ benchmarkScope })` | List benchmarks. |
244
+ | `getBenchmarkMetrics(benchmarkName)` | Metrics for a benchmark. |
245
+ | `getBenchmarkDelta({ baseline, current })` | Compare two benchmarks. |
246
+ | `getBenchmarkTrend({ metricKey, dimensionValue, limit })` | Metric trend. |
247
+ | `getPerformanceDashboard({ clientType, workflowRunId })` | Performance dashboard. |
248
+
249
+ ### Portfolio
250
+ | Method | Description |
251
+ |---|---|
252
+ | `getPortfolioStatus({ projectId })` | Portfolio status. |
253
+ | `getPortfolioSummary()` | Portfolio summary. |
254
+ | `getPortfolioExceptions()` | Portfolio exceptions. |
255
+ | `getPortfolioProject(projectId)` | Project detail via portfolio. |
256
+ | `getPortfolioReport()` | Full portfolio report. |
257
+ | `getPortfolioBundle()` | Portfolio bundle. |
258
+
259
+ ### Self-Learning
260
+ | Method | Description |
261
+ |---|---|
262
+ | `getSelfLearningPosture({ workflowRunId, limit })` | Self-learning posture. |
263
+ | `listLearningRecords({ workflowRunId, learningCategory, promotionReadiness, limit })` | Learning records. |
264
+ | `getLearningRecord(learningRecordId)` | Learning record detail. |
265
+ | `listPromotionCandidates({ workflowRunId, learningCategory, promotionReadiness, limit })` | Promotion candidates. |
266
+ | `getPromotionCandidate(candidateKey)` | Candidate detail. |
267
+ | `listPromotionFlows({ flowStatus, targetType, candidateKey, limit })` | Promotion flows. |
268
+
269
+ ### Self-Optimization
270
+ | Method | Description |
271
+ |---|---|
272
+ | `getSelfOptimizationDashboard()` | Self-optimization dashboard. |
273
+ | `getSelfOptimizationCandidateQueue({ objectiveCategory, impactPosture, blockedByDefault, limit })` | Candidate queue. |
274
+ | `getSelfOptimizationBacklogPosture({ snapshotKey })` | Backlog posture. |
275
+ | `getSelfOptimizationPendingHandoffs({ downstreamLane })` | Pending handoffs. |
276
+
277
+ ### Design Intelligence
278
+ | Method | Description |
279
+ |---|---|
280
+ | `getDesignIntelligenceDashboard()` | Design intelligence dashboard. |
281
+ | `listDesignDecisions()` | List design decisions. |
282
+ | `getDesignDecision(decisionId)` | Decision detail. |
283
+ | `getDesignDecisionVariants(decisionId)` | Decision variants. |
284
+ | `getDesignDecisionCritique(decisionId)` | Decision critique. |
285
+ | `getDesignDecisionLineage(decisionId)` | Decision lineage. |
286
+ | `listDesignPatterns()` | Design patterns. |
287
+ | `getDecisionLabCanvas()` | Decision lab canvas. |
288
+ | `getDesignRecommendations()` | Design recommendations. |
289
+ | `getDesignPromotions()` | Design promotions. |
290
+ | `previewDesignPromotion(body)` | Preview promotion action. |
291
+ | `getDesignIntelligenceMetrics()` | Design intelligence metrics. |
292
+
293
+ ### Script Discovery
294
+ | Method | Description |
295
+ |---|---|
296
+ | `scanScripts(body)` | Scan for discoverable scripts. |
297
+ | `listDiscoveredScriptAssets({ limit })` | Discovered script assets. |
298
+ | `listDiscoveredCapabilities({ limit })` | Discovered capabilities. |
299
+ | `listWorkflowCandidates({ limit })` | Workflow candidates. |
300
+ | `promoteWorkflowCandidate(workflowCandidateId, body)` | Promote a workflow candidate. |
301
+
302
+ ### Notes Lab
303
+ | Method | Description |
304
+ |---|---|
305
+ | `getNotesLabConfig()` | Notes lab configuration. |
306
+ | `submitNote(body)` | Submit a note for review. |
307
+ | `approveNoteReview(body)` | Approve and apply a note review. |
308
+
309
+ ### Search & Contacts
310
+ | Method | Description |
311
+ |---|---|
312
+ | `search(query)` | Search organizations and contacts. |
313
+ | `getOrganization(entityId)` | Organization detail. |
314
+ | `getContact(contactId)` | Contact detail. |
315
+
316
+ ### Benchmarks
317
+ | Method | Description |
318
+ |---|---|
319
+ | `listRecentBenchmarkRuns({ limit })` | List recent benchmark runs. |
320
+ | `getBenchmarkRun(benchmarkRunId)` | Benchmark run detail. |
321
+
322
+ ---
323
+
324
+ ## Runtime Contract
325
+
326
+ The package talks to the AI Engine web service. All routes listed above are registered unconditionally in the Flask app and served by the deployed Azure Container App.
327
+
328
+ Operator routes (`/api/operator/*`) use network-trust protection. The external v1 API (`/api/v1/*`) requires `X-Client-Id` and `X-API-Key` headers and is intentionally not wrapped by this client.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmsoftwaresolutions/ai-engine-client",
3
- "version": "0.1.0",
3
+ "version": "1.0.0-beta.0",
4
4
  "description": "Thin npm client for the AI Engine operator and retrieval APIs",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",