@kortexya/reasoninglayer 1.26.0 → 1.28.0

package/README.md

@@ -7,8 +7,10 @@ TypeScript SDK for the [Reasoning Layer](https://kortexya.com) API — a knowled
 - **Zero runtime dependencies** — only `fetch` and `AbortController` (ES2022)
 - **Dual ESM/CJS** — works in Node 18+, modern browsers, Deno, and Bun
 - **Full type safety** — strict TypeScript with discriminated unions, no `any` types
-- **29 resource clients** covering sorts, terms, inference, query, fuzzy logic, cognitive agents, causal reasoning, optimization, and more
-- **8 builder namespaces** — `Value`, `FeatureInput`, `TermInput`, `guard`, `SortBuilder`, `psi`, `allen`, `LP`
+- **100 resource clients** covering sorts, terms, inference, query, fuzzy logic, cognitive agents, causal reasoning, optimization, snapshots, the audit chain, and more
+- **Builder namespaces** — `Value`, `FuzzyShape`, `Geometry`, `Constraint`, `psi`, `guard`, `constrained`, `SortBuilder`, `allen`, `LP`, `flow`
+- **Per-call request options** — a timeout, retry budget, abort signal or header override on any method, without a second client
+- **Async pagination** — `for await` over the paged endpoints, both dialects
 - **Automatic retry** — exponential backoff with jitter on 429 and 503 responses
 - **WebSocket** — real-time cognitive agent event subscriptions with auto-reconnect
 - **Error hierarchy** — typed errors for constraint violations, rate limits, timeouts, and network failures
@@ -26,7 +28,12 @@ yarn add @kortexya/reasoninglayer
 ## Quick Start
 
 ```typescript
-import { ReasoningLayerClient, Value, TermInput, FeatureInput } from '@kortexya/reasoninglayer';
+import {
+  ReasoningLayerClient,
+  Value,
+  Constraint,
+  psi,
+} from '@kortexya/reasoninglayer';
 
 const client = new ReasoningLayerClient({
   baseUrl: 'https://platform.ovh.reasoninglayer.ai',
@@ -34,47 +41,54 @@ const client = new ReasoningLayerClient({
   auth: { mode: 'bearer', token: process.env.RL_API_TOKEN! },
 });
 
-// Create a sort hierarchy
-const personSort = await client.sorts.createSort({ name: 'person' });
-const employeeSort = await client.sorts.createSort({
+// A sort hierarchy. Features are declared, not inferred.
+const person = await client.sorts.createSort({
+  name: 'person',
+  features: [{ name: 'name', required: true, expectedTypeHint: 'String' }],
+});
+const employee = await client.sorts.createSort({
   name: 'employee',
-  parents: [personSort.id],
-  features: { salary: { value_type: 'Real' } },
+  parents: [person.id],
+  features: [
+    { name: 'salary', required: false, expectedTypeHint: 'Real' },
+    { name: 'hired_at', required: false, expectedTypeHint: 'DateTime' },
+  ],
 });
 
-// Create a psi-term
+// A Ψ-term. Plain JS values convert themselves; `Value.*` is for the rest.
 const term = await client.terms.createTerm({
-  sort_id: employeeSort.id,
+  sortId: employee.id,
+  ownerId: 'your-tenant-uuid',
   features: {
-    name: Value.string('Alice'),
-    salary: Value.real(95000),
+    name: 'Alice',
+    salary: 95000,
+    hired_at: Value.dateTime('2024-03-01T00:00:00Z'),
   },
 });
 
-// Add inference rules (homoiconic format)
+// A rule. `?X` is a logic variable; repeating it is what makes a join.
+await client.sorts.createSort({
+  name: 'well_paid',
+  features: [{ name: 'name', required: false }],
+});
 await client.inference.addRule({
-  head: TermInput.byName('well_paid', {
-    person: FeatureInput.variable('X'),
-  }),
-  body: [
-    {
-      term: TermInput.byName('employee', {
-        name: FeatureInput.variable('X'),
-        salary: FeatureInput.constrainedVar('S', { op: 'gt', value: 80000 }),
-      }),
-    },
+  term: psi('well_paid', { name: '?X' }),
+  antecedents: [
+    psi('employee', { name: '?X', salary: '?S' }),
+    Constraint.where('?S', '>', 80000),
   ],
 });
 
-// Query with backward chaining
-const result = await client.inference.backwardChain({
-  goal: TermInput.byName('well_paid', {
-    person: FeatureInput.variable('Who'),
-  }),
-  max_solutions: 10,
+// Prove it, and walk every employee without writing the offset arithmetic.
+const proved = await client.inference.backwardChain({
+  goal: psi('well_paid', { name: '?X' }),
 });
+for await (const employee of client.terms.iterateTerms({ sortName: 'employee' })) {
+  console.log(employee.id);
+}
 
-console.log(result.solutions); // Solutions with bindings
+// One slow call gets a budget of its own; the client keeps its default.
+await client.inference.forwardChain({ maxIterations: 100 }, { timeoutMs: 600_000 });
 ```
 
 ## Resource Clients
@@ -109,6 +123,13 @@ console.log(result.solutions); // Solutions with bindings
 | `discovery` | Discovery | causal effect discovery, prediction |
 | `extract` | Extraction | entity extraction from text |
 | `optimize` | Optimization | LP solve, KB-driven optimization |
+| `snapshots` | Tenant snapshots | capture, export, import, restore |
+| `audit` | Conversation audit chain | append, list, count, verify integrity |
+| `analysis` | Analysis | FCA sort discovery, attribute exploration, rule-base certification |
+| `compliance` | Compliance | audit receipts, EU AI Act conformity |
+
+A row per area, not per client — the SDK ships 100 resource clients in all.
+
 
 ## Configuration