@kortexya/reasoninglayer 1.27.0 → 2.0.0

package/README.md

@@ -186,16 +186,31 @@ browser code that has already gone through the platform's login flow.
 
 ## Response Metadata
 
+A resource method resolves to the parsed body alone. To see a **successful**
+response's status, headers or rate-limit budget, register an interceptor — it
+wraps every request the client makes.
+
 ```typescript
-// Default: returns data directly
-const sort = await client.sorts.createSort({ name: 'person' });
+const client = new ReasoningLayerClient({
+  baseUrl: 'https://platform.ovh.reasoninglayer.ai',
+  tenantId: 'your-tenant-uuid',
+  auth: { mode: 'cookie' },
+  interceptors: [
+    async (request, next) => {
+      const response = await next(request);
+      console.log(response.status);                              // 201
+      console.log(response.headers.get('x-ratelimit-remaining')); // '99'
+      return response;
+    },
+  ],
+});
 
-// With metadata: returns { data, status, headers, rateLimit }
-const result = await client.sorts.withMetadata().createSort({ name: 'person' });
-console.log(result.status);    // 201
-console.log(result.rateLimit); // { limit, remaining, retryAfter }
+const sort = await client.sorts.createSort({ name: 'person' });
 ```
 
+On a **failure**, the thrown `ApiError` carries `status` and `headers`
+directly — see Error Handling below.
+
 ## Error Handling
 
 ```typescript
@@ -227,23 +242,28 @@ try {
 The SDK provides builder functions for constructing API request values with full type safety:
 
 ```typescript
-import { Value, FeatureInput, TermInput, guard, allen, SortBuilder, psi, LP } from '@kortexya/reasoninglayer';
+import { Value, FuzzyShape, guard, constrained, allen, SortBuilder, psi, LP } from '@kortexya/reasoninglayer';
 
-// Tagged values (term CRUD)
-Value.string('hello')           // { type: 'String', value: 'hello' }
-Value.integer(42)               // { type: 'Integer', value: 42 }
-Value.fuzzyNumber('triangular', { a: 20, b: 22, c: 24 })
+// Tagged values (term CRUD). A plain scalar needs no builder — the resource
+// methods tag it for you. `Value.*` is for the shapes a scalar cannot express.
+const features = { name: 'hello', age: 42 };       // tagged on the way to the wire
+Value.reference('550e8400-e29b-41d4-a716-446655440000')
+                                // { type: 'Reference', value: '550e8400-…' }
+Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24))
+                                // { type: 'FuzzyNumber', value: { kind: 'Triangular', … } }
 
-// Untagged values (inference)
-FeatureInput.string('hello')    // 'hello'
-FeatureInput.variable('X')      // { name: 'X' }
-FeatureInput.constrainedVar('S', { op: 'gt', value: 80000 })
+// Untagged values (inference). `psi()` writes them: a scalar stays a scalar,
+// and a '?Name' string becomes a logic variable.
+psi('employee', { name: '?Name', department: 'Engineering' })
+                                // { sortName: 'employee', features: { name: { name: '?Name' }, … } }
 
-// Guard constraints
-guard('gt', 100)                // { guard: { op: 'gt', value: 100 } }
+// Guard constraints — a guard is itself a Ψ-term
+guard('gt', 100)                // { sortName: 'guard_constraint', features: { op: 'gt', right: 100 } }
+constrained('?Salary', guard('gt', 80000))
 
 // Allen temporal relations
-allen('before')                 // { allen: 'before' }
+allen('before', '?Employment', intervalTermId)
+                                // { type: 'Allen', intervalA: '?Employment', … }
 
 // LP optimization
 LP.maximize({ x: 3, y: 5 })    // objective function