@oasisomniverse/web6-api 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# @oasisomniverse/web6-api
+
+Isomorphic (Node 18+ and browser) JavaScript/TypeScript-friendly client for the
+**WEB6 OASIS AI Layer API** - full coverage of the OASIS2 WEB6 WebAPI: unified
+AI completion/chat across every provider (OpenAI, Anthropic, Google Gemini,
+xAI Grok, Qwen, DeepSeek, OpenServ, ...), image generation, the Holonic BRAID
+fractal memory hierarchy and shared reasoning-graph library, multi-agent
+orchestrator adapters (MCP/A2A/LangChain/AutoGen/CrewAI/Semantic Kernel), and
+the Reasoning Network (FAHRN) for agent registration, scoring and dispatch.
+
+Zero dependencies. Wraps the global `fetch`. Works the same in Node and the
+browser.
+
+## Installation
+
+```bash
+npm install @oasisomniverse/web6-api
+```
+
+## Quick start
+
+```js
+const { Web6Client } = require('@oasisomniverse/web6-api');
+// or: import { Web6Client } from '@oasisomniverse/web6-api';
+
+const web6 = new Web6Client({ baseUrl: 'https://api.web6.oasisomniverse.one' });
+
+const { isError, message, result } = await web6.completion.complete({
+  avatarId,
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+## Calling any endpoint
+
+Every controller on the OASIS2 WEB6 WebAPI is reachable as a lowerCamel
+property on the client (`web6.completion`, `web6.images`,
+`web6.holonicMemory`, `web6.holonicBraid`, `web6.orchestrator`,
+`web6.reasoningNetwork`). Every generated method takes a single args object:
+
+- Any key matching a `{token}` in the route template is consumed and
+  substituted into the URL (case-insensitive match).
+- Any remaining keys become the query string (GET/DELETE) or JSON body
+  (POST/PUT) - **matching the real `[FromQuery]`/`[FromBody]` binding of the
+  underlying C# action**, not just the HTTP verb. `endpoints.json` records
+  exactly which arg names are query-bound per operation (see
+  [`docs/`](./docs/README.md) for the per-method breakdown), so a `POST`
+  action that binds some params from the query string (like
+  `HolonicMemoryController.GetOrCreateHolon`) still sends those on the URL.
+
+```js
+// GET v1/holonic-braid/graph/{taskType} -> taskType is consumed as a route token
+const graph = await web6.holonicBraid.getGraph({ taskType: 'research' });
+
+// PUT v1/holonic-memory/holons/{holonId}/membrane-rule -> holonId consumed, rest becomes the body
+await web6.holonicMemory.setMembraneRule({ holonId, allow: ['propagate-up'] });
+
+// POST v1/holonic-memory/holons -> level/name/parentHolonId are all [FromQuery]
+// even though this is a POST, so they're sent on the URL, not as a JSON body
+const holon = await web6.holonicMemory.getOrCreateHolon({ level: 'Local', name: 'London', parentHolonId: earthId });
+```
+
+Every response has the shape:
+
+```ts
+interface OASISResponse<T = any> {
+  isError: boolean;
+  message: string | null;
+  result: T;
+  raw: any;
+  statusCode: number;
+}
+```
+
+## Auth
+
+WEB6 is an internal AI layer that sits behind the same OASIS avatar identity
+as WEB4/WEB5 - it has no avatar/login endpoints of its own. Reuse a JWT
+you've already obtained elsewhere (e.g. from `web4-oasis-api`'s
+`client.auth.login()`):
+
+```js
+web6.setToken(jwtToken);
+```
+
+## Module examples
+
+### Completion (`web6.completion`)
+
+```js
+const reply = await web6.completion.complete({
+  avatarId,
+  provider: 'OpenAI',
+  messages: [{ role: 'user', content: 'Summarise this holon graph.' }]
+});
+
+const models = await web6.completion.openServModels();
+```
+
+### Images (`web6.images`)
+
+```js
+const image = await web6.images.generate({ prompt: 'a holonic crystal city at dawn', provider: 'StabilityAI' });
+```
+
+### Holonic Memory (`web6.holonicMemory`)
+
+```js
+const earth = await web6.holonicMemory.getEarthHolon();
+const holon = await web6.holonicMemory.getOrCreateHolon({ level: 'Local', name: 'London', parentHolonId: earth.result.id });
+await web6.holonicMemory.recordMemory({ holonId: holon.result.id, content: 'New observation...' });
+await web6.holonicMemory.propagate({ childHolonId: holon.result.id });
+```
+
+### Holonic BRAID (`web6.holonicBraid`)
+
+```js
+const graph = await web6.holonicBraid.getGraph({ taskType: 'research' });
+await web6.holonicBraid.saveGraph({ taskType: 'research', nodes: graph.result.nodes });
+```
+
+### Orchestrator (`web6.orchestrator`)
+
+```js
+await web6.orchestrator.registerAdapter({ protocol: 'MCP', endpoint: 'https://my-agent.example.com' });
+const adapters = await web6.orchestrator.getAdapters();
+await web6.orchestrator.invoke({ adapterId, payload: { task: 'lookup-weather' } });
+```
+
+### Reasoning Network (`web6.reasoningNetwork`)
+
+```js
+await web6.reasoningNetwork.registerAgent({ name: 'researcher-1', capabilities: ['search', 'summarise'] });
+await web6.reasoningNetwork.seedOpenServAgents();
+const result = await web6.reasoningNetwork.dispatch({ taskType: 'research', payload: { query: 'OASIS HyperDrive' } });
+```
+
+## Module reference
+
+6 modules, 18 operations in total. Full per-method tables live in
+[`docs/`](./docs/README.md).
+
+| Client property | Route prefix | Operations |
+| --- | --- | --- |
+| `web6.completion` | `v1` | 2 |
+| `web6.holonicBraid` | `v1/holonic-braid` | 2 |
+| `web6.holonicMemory` | `v1/holonic-memory` | 5 |
+| `web6.images` | `v1/images` | 1 |
+| `web6.orchestrator` | `v1/orchestrators` | 3 |
+| `web6.reasoningNetwork` | `v1/reasoning-network` | 4 |
+
+See [`docs/README.md`](./docs/README.md) for the full generated reference,
+or [`docs/modules/`](./docs/modules) for per-module method tables with
+parameter and route details.
+
+## Regenerating
+
+The generated modules, type declarations and docs are produced from
+`endpoints.json` (extracted from the WEB6 WebAPI controller source):
+
+```bash
+npm run generate   # src/modules/*.js + src/modules/index.js
+npm run types      # src/modules/*.d.ts + index.d.ts + src/core/types.d.ts
+npm run docs       # docs/README.md + docs/modules/*.md
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/docs/README.md

@@ -0,0 +1,24 @@
+# WEB6 AI Layer API — JavaScript SDK Reference
+
+Generated from `endpoints.json` (extracted from the WebAPI controllers) by
+`scripts/generate-full-docs.js`. Regenerate the full pipeline after the API
+changes:
+
+```
+node scripts/extract-endpoints.js
+node scripts/generate-modules.js
+node scripts/generate-full-docs.js
+```
+
+- [Module Reference](#module-reference) (6 modules, 17 operations)
+
+## Module Reference
+
+| Client property | Route prefix | Operations |
+| --- | --- | --- |
+| [`web6.completion`](modules/Completion.md) | `v1` | 2 |
+| [`web6.holonicBraid`](modules/HolonicBraid.md) | `v1/holonic-braid` | 2 |
+| [`web6.holonicMemory`](modules/HolonicMemory.md) | `v1/holonic-memory` | 5 |
+| [`web6.images`](modules/Images.md) | `v1/images` | 1 |
+| [`web6.orchestrator`](modules/Orchestrator.md) | `v1/orchestrators` | 3 |
+| [`web6.reasoningNetwork`](modules/ReasoningNetwork.md) | `v1/reasoning-network` | 4 |

package/docs/modules/Completion.md

@@ -0,0 +1,124 @@
+# Completion — `web6.completion`
+
+Source controller: [`CompletionController.cs`](https://github.com/NextGenSoftwareUK/OASIS2/blob/main/WEB6/NextGenSoftware.OASIS.Web6.WebAPI/Controllers/CompletionController.cs)
+Route prefix: `v1`
+2 operation(s).
+
+Every method takes a single args object: any key matching a `{token}` in the route is substituted into the URL; everything else becomes the query string (GET/DELETE) or JSON body (POST/PUT). Every call resolves to the standard OASIS envelope:
+
+```ts
+{
+  isError: boolean;
+  isWarning: boolean;
+  message: string;
+  errorCode?: string;
+  result: T; // see each endpoint's Response section below
+}
+```
+
+## Operations
+
+### `complete`
+
+Routes a completion request to whichever AI provider/model best fits, normalising the response. POST https://api.web6.oasisomniverse.one/v1/complete
+
+**POST** `v1/complete`
+
+**Request**
+
+Body type: `CompletionRequest`
+
+| Field | Type |
+| --- | --- |
+| `Provider` | `string` |
+| `Model` | `string` |
+| `Messages` | `List<ChatMessage>` |
+| `Routing` | `RoutingOptions` |
+| `AvatarId` | `Guid` |
+| `Temperature` | `double?` |
+| `MaxTokens` | `int?` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `CompletionResponse`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `string` |
+| `Provider` | `string` |
+| `Model` | `string` |
+| `Content` | `string` |
+| `PromptTokens` | `int` |
+| `CompletionTokens` | `int` |
+| `LatencyMs` | `long` |
+| `FailedOver` | `bool` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web6.completion.complete({
+    provider: "example string",
+    model: "example string",
+    messages: [{ "Id": "example string", "SessionId": "example string", "SenderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Content": "example string", "MessageType": {  }, "Timestamp": "2026-01-01T00:00:00Z", "IsDelivered": true, "IsRead": true }],
+    routing: { "Priority": "example string", "Fallback": true },
+    avatarId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    temperature: 1.0,
+    maxTokens: 1
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "Id": "example string", "Provider": "example string", "Model": "example string", "Content": "example string", "PromptTokens": 1, "CompletionTokens": 1, "LatencyMs": 1, "FailedOver": true }
+}
+```
+
+---
+
+### `openServModels`
+
+Lists the models reachable through the OpenServ provider (provider: "openserv"), i.e. the full SERV catalog spanning OpenAI, Anthropic, Google, xAI, Qwen and DeepSeek behind one SERV_API_KEY. GET https://api.web6.oasisomniverse.one/v1/openserv/models
+
+**GET** `v1/openserv/models`
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `OpenServModel` (array)
+
+| Field | Type |
+| --- | --- |
+| `Id` | `string` |
+| `Label` | `string` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web6.completion.openServModels({});
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": [{ "Id": "example string", "Label": "example string" }]
+}
+```
+

package/docs/modules/HolonicBraid.md

@@ -0,0 +1,137 @@
+# HolonicBraid — `web6.holonicBraid`
+
+Source controller: [`HolonicBraidController.cs`](https://github.com/NextGenSoftwareUK/OASIS2/blob/main/WEB6/NextGenSoftware.OASIS.Web6.WebAPI/Controllers/HolonicBraidController.cs)
+Route prefix: `v1/holonic-braid`
+2 operation(s).
+
+Every method takes a single args object: any key matching a `{token}` in the route is substituted into the URL; everything else becomes the query string (GET/DELETE) or JSON body (POST/PUT). Every call resolves to the standard OASIS envelope:
+
+```ts
+{
+  isError: boolean;
+  isWarning: boolean;
+  message: string;
+  errorCode?: string;
+  result: T; // see each endpoint's Response section below
+}
+```
+
+## Operations
+
+### `getGraph`
+
+Looks up the shared reasoning graph already generated for a task type, if any.
+
+**GET** `v1/holonic-braid/graph/{taskType}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `taskType` | `string` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `HolonicBraidGraphDto`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `TaskType` | `string` |
+| `MermaidDiagram` | `string` |
+| `GeneratedByModel` | `string` |
+| `TimesReused` | `int` |
+| `CreatedUtc` | `DateTime` |
+| `ParentHolonId` | `Guid` |
+| `AvgSolverAccuracy` | `double` |
+| `Version` | `int` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web6.holonicBraid.getGraph({
+    taskType: '<taskType>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "TaskType": "example string", "MermaidDiagram": "example string", "GeneratedByModel": "example string", "TimesReused": 1, "CreatedUtc": "2026-01-01T00:00:00Z", "ParentHolonId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AvgSolverAccuracy": 1.0, "Version": 1 }
+}
+```
+
+---
+
+### `saveGraph`
+
+Seeds the shared library with a reasoning graph for a task type (the "generator" step of the two-stage BRAID protocol).
+
+**POST** `v1/holonic-braid/graph/{taskType}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `taskType` | `string` |
+
+**Request**
+
+Body type: `SaveGraphRequest`
+
+| Field | Type |
+| --- | --- |
+| `MermaidDiagram` | `string` |
+| `GeneratedByModel` | `string` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `HolonicBraidGraphDto`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `TaskType` | `string` |
+| `MermaidDiagram` | `string` |
+| `GeneratedByModel` | `string` |
+| `TimesReused` | `int` |
+| `CreatedUtc` | `DateTime` |
+| `ParentHolonId` | `Guid` |
+| `AvgSolverAccuracy` | `double` |
+| `Version` | `int` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web6.holonicBraid.saveGraph({
+    taskType: '<taskType>',
+    mermaidDiagram: "example string",
+    generatedByModel: "example string"
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "TaskType": "example string", "MermaidDiagram": "example string", "GeneratedByModel": "example string", "TimesReused": 1, "CreatedUtc": "2026-01-01T00:00:00Z", "ParentHolonId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AvgSolverAccuracy": 1.0, "Version": 1 }
+}
+```
+