@coasys/ad4m 0.13.0-test-9 → 0.13.0-test-interpretation
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.
- package/lib/index.cjs +368 -8
- package/lib/index.js +369 -9
- package/lib/src/ai/AIClient.js +3 -1
- package/lib/src/apiClient.d.ts +4 -1
- package/lib/src/apiClient.js +7 -3
- package/lib/src/generated/api/RunInterpretationRequest.d.ts +19 -0
- package/lib/src/generated/api/RunInterpretationRequest.js +1 -0
- package/lib/src/generated/api/TranscriptTurn.d.ts +7 -0
- package/lib/src/generated/api/TranscriptTurn.js +2 -0
- package/lib/src/generated/api/index.d.ts +2 -0
- package/lib/src/index.d.ts +2 -0
- package/lib/src/index.js +2 -0
- package/lib/src/model/ModelQueryBuilder.js +1 -1
- package/lib/src/model/decorators.d.ts +25 -0
- package/lib/src/model/decorators.js +1 -1
- package/lib/src/model/shacl-gen.d.ts +8 -1
- package/lib/src/model/shacl-gen.js +21 -1
- package/lib/src/perspectives/AutoProcessor.d.ts +89 -0
- package/lib/src/perspectives/AutoProcessor.js +5 -0
- package/lib/src/perspectives/InterpretationModels.d.ts +71 -0
- package/lib/src/perspectives/InterpretationModels.js +190 -0
- package/lib/src/perspectives/PerspectiveClient.d.ts +37 -0
- package/lib/src/perspectives/PerspectiveClient.js +54 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +43 -1
- package/lib/src/perspectives/PerspectiveProxy.js +53 -1
- package/lib/src/shacl/SHACLShape.d.ts +14 -0
- package/lib/src/shacl/SHACLShape.js +43 -0
- package/package.json +6 -2
- package/src/ai/AIClient.ts +3 -1
- package/src/apiClient.ts +7 -3
- package/src/generated/api/RunInterpretationRequest.ts +18 -0
- package/src/generated/api/TranscriptTurn.ts +6 -0
- package/src/generated/api/index.ts +2 -0
- package/src/index.ts +2 -0
- package/src/model/ModelQueryBuilder.ts +1 -1
- package/src/model/decorators.ts +29 -0
- package/src/model/shacl-gen.ts +22 -0
- package/src/model/shacl-roundtrip.test.ts +76 -0
- package/src/perspectives/AutoProcessor.ts +107 -0
- package/src/perspectives/InterpretationModels.ts +145 -0
- package/src/perspectives/PerspectiveClient.ts +75 -0
- package/src/perspectives/PerspectiveProxy.ts +61 -1
- package/src/shacl/SHACLShape.ts +80 -4
|
@@ -8,8 +8,10 @@ import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
|
|
|
8
8
|
import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
|
|
9
9
|
import { AIClient } from "../ai/AIClient";
|
|
10
10
|
import { AllInstancesResult } from "../model/types";
|
|
11
|
+
import type { TranscriptTurn } from "../generated/api";
|
|
11
12
|
import { SHACLShape } from "../shacl/SHACLShape";
|
|
12
13
|
import { SHACLFlow } from "../shacl/SHACLFlow";
|
|
14
|
+
import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
|
|
13
15
|
type QueryCallback = (result: AllInstancesResult) => void;
|
|
14
16
|
/** Proxy object for a subscribed Prolog query that provides real-time updates
|
|
15
17
|
*
|
|
@@ -278,6 +280,46 @@ export declare class PerspectiveProxy {
|
|
|
278
280
|
* ```
|
|
279
281
|
*/
|
|
280
282
|
get(query: LinkQuery): Promise<LinkExpression[]>;
|
|
283
|
+
/**
|
|
284
|
+
* Runs generic LLM interpretation over a conversation transcript, turning it
|
|
285
|
+
* into typed instances of this perspective's own SHACL subject classes
|
|
286
|
+
* (steered by each class's `@InterpretationHint`). The target shapes are
|
|
287
|
+
* resolved automatically from the perspective's registered classes, so you
|
|
288
|
+
* pass only the transcript. New instances are written as links into this
|
|
289
|
+
* perspective; the returned placements list each instance's base URI and
|
|
290
|
+
* the links written for it.
|
|
291
|
+
*
|
|
292
|
+
* @param transcript ordered `{ speaker, text }` turns
|
|
293
|
+
* @param basePrefix URI namespace for new instance identities, e.g. `soa://ext/`
|
|
294
|
+
* @param classes local names of the subject classes to extract into; omit for all
|
|
295
|
+
*/
|
|
296
|
+
runInterpretation(transcript: TranscriptTurn[], basePrefix: string, classes?: string[]): Promise<string[]>;
|
|
297
|
+
/**
|
|
298
|
+
* Register a neighbourhood auto-processor on this perspective. The executor
|
|
299
|
+
* then runs interpretation automatically over new source items (like Flux
|
|
300
|
+
* per channel), coordinating which peer processes each batch. Returns the
|
|
301
|
+
* processor id. Subscribe to progress via {@link addAutoProcessorEventListener}.
|
|
302
|
+
*/
|
|
303
|
+
addAutoProcessor(config: AddAutoProcessorConfig): Promise<string>;
|
|
304
|
+
/**
|
|
305
|
+
* Pending interpretation overlays on this perspective — LLM suggestions the
|
|
306
|
+
* §4 divergence gate staged rather than applied, awaiting human accept/reject.
|
|
307
|
+
*/
|
|
308
|
+
interpretationOverlays(): Promise<InterpretationOverlayInfo[]>;
|
|
309
|
+
/**
|
|
310
|
+
* Accept an interpretation overlay's suggestion(s): the LLM's staged value
|
|
311
|
+
* becomes the real, human-owned value and the overlay is deleted. Pass
|
|
312
|
+
* `property` to accept a single predicate; omit it for the whole base.
|
|
313
|
+
*/
|
|
314
|
+
acceptInterpretation(base: string, property?: string): Promise<boolean>;
|
|
315
|
+
/**
|
|
316
|
+
* Reject an interpretation overlay's suggestion(s). Omit `property` to reject
|
|
317
|
+
* the whole base — a rejected `create` deletes the suggested instance, a
|
|
318
|
+
* rejected `update` drops the overlay and keeps the real value.
|
|
319
|
+
*/
|
|
320
|
+
rejectInterpretation(base: string, property?: string): Promise<boolean>;
|
|
321
|
+
/** Subscribe to this perspective's auto-processor step signals. */
|
|
322
|
+
addAutoProcessorEventListener(cb: (event: AutoProcessorEvent) => void): Promise<void>;
|
|
281
323
|
/**
|
|
282
324
|
* Executes a Prolog query against the perspective's knowledge base.
|
|
283
325
|
* This is a powerful way to find complex patterns in the graph.
|
|
@@ -352,7 +394,7 @@ export declare class PerspectiveProxy {
|
|
|
352
394
|
* internally in Rust, registers a subscription, runs the initial query, and
|
|
353
395
|
* pushes updated results when relevant links change.
|
|
354
396
|
*
|
|
355
|
-
* The subscription reuses the same
|
|
397
|
+
* The subscription reuses the same WS-RPC subscription channel as subscribeQuery().
|
|
356
398
|
* Use keepAliveQuery() / disposeQuerySubscription() with the returned subscriptionId.
|
|
357
399
|
*
|
|
358
400
|
* @param className - The model class name
|
|
@@ -487,6 +487,58 @@ export class PerspectiveProxy {
|
|
|
487
487
|
async get(query) {
|
|
488
488
|
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").queryLinks(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
|
|
489
489
|
}
|
|
490
|
+
/**
|
|
491
|
+
* Runs generic LLM interpretation over a conversation transcript, turning it
|
|
492
|
+
* into typed instances of this perspective's own SHACL subject classes
|
|
493
|
+
* (steered by each class's `@InterpretationHint`). The target shapes are
|
|
494
|
+
* resolved automatically from the perspective's registered classes, so you
|
|
495
|
+
* pass only the transcript. New instances are written as links into this
|
|
496
|
+
* perspective; the returned placements list each instance's base URI and
|
|
497
|
+
* the links written for it.
|
|
498
|
+
*
|
|
499
|
+
* @param transcript ordered `{ speaker, text }` turns
|
|
500
|
+
* @param basePrefix URI namespace for new instance identities, e.g. `soa://ext/`
|
|
501
|
+
* @param classes local names of the subject classes to extract into; omit for all
|
|
502
|
+
*/
|
|
503
|
+
async runInterpretation(transcript, basePrefix, classes) {
|
|
504
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").runInterpretation(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, transcript, basePrefix, classes);
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Register a neighbourhood auto-processor on this perspective. The executor
|
|
508
|
+
* then runs interpretation automatically over new source items (like Flux
|
|
509
|
+
* per channel), coordinating which peer processes each batch. Returns the
|
|
510
|
+
* processor id. Subscribe to progress via {@link addAutoProcessorEventListener}.
|
|
511
|
+
*/
|
|
512
|
+
async addAutoProcessor(config) {
|
|
513
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addAutoProcessor(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, config);
|
|
514
|
+
}
|
|
515
|
+
/**
|
|
516
|
+
* Pending interpretation overlays on this perspective — LLM suggestions the
|
|
517
|
+
* §4 divergence gate staged rather than applied, awaiting human accept/reject.
|
|
518
|
+
*/
|
|
519
|
+
async interpretationOverlays() {
|
|
520
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").interpretationOverlays(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
|
|
521
|
+
}
|
|
522
|
+
/**
|
|
523
|
+
* Accept an interpretation overlay's suggestion(s): the LLM's staged value
|
|
524
|
+
* becomes the real, human-owned value and the overlay is deleted. Pass
|
|
525
|
+
* `property` to accept a single predicate; omit it for the whole base.
|
|
526
|
+
*/
|
|
527
|
+
async acceptInterpretation(base, property) {
|
|
528
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").acceptInterpretation(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, base, property);
|
|
529
|
+
}
|
|
530
|
+
/**
|
|
531
|
+
* Reject an interpretation overlay's suggestion(s). Omit `property` to reject
|
|
532
|
+
* the whole base — a rejected `create` deletes the suggested instance, a
|
|
533
|
+
* rejected `update` drops the overlay and keeps the real value.
|
|
534
|
+
*/
|
|
535
|
+
async rejectInterpretation(base, property) {
|
|
536
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").rejectInterpretation(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, base, property);
|
|
537
|
+
}
|
|
538
|
+
/** Subscribe to this perspective's auto-processor step signals. */
|
|
539
|
+
async addAutoProcessorEventListener(cb) {
|
|
540
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, cb);
|
|
541
|
+
}
|
|
490
542
|
/**
|
|
491
543
|
* Executes a Prolog query against the perspective's knowledge base.
|
|
492
544
|
* This is a powerful way to find complex patterns in the graph.
|
|
@@ -571,7 +623,7 @@ export class PerspectiveProxy {
|
|
|
571
623
|
* internally in Rust, registers a subscription, runs the initial query, and
|
|
572
624
|
* pushes updated results when relevant links change.
|
|
573
625
|
*
|
|
574
|
-
* The subscription reuses the same
|
|
626
|
+
* The subscription reuses the same WS-RPC subscription channel as subscribeQuery().
|
|
575
627
|
* Use keepAliveQuery() / disposeQuerySubscription() with the returned subscriptionId.
|
|
576
628
|
*
|
|
577
629
|
* @param className - The model class name
|
|
@@ -99,6 +99,15 @@ export interface SHACLPropertyShape {
|
|
|
99
99
|
* Applied to resolved property values in the Rust model query engine.
|
|
100
100
|
* Only used for properties with resolveLanguage set. */
|
|
101
101
|
transform?: NodeExpression;
|
|
102
|
+
/** AD4M-specific: Natural-language hint that steers the generic LLM
|
|
103
|
+
* extractor when producing typed instances from a transcript. Emitted
|
|
104
|
+
* as an `ad4m://interpretation_hint` link on the property shape node and
|
|
105
|
+
* surfaced on `ShapeProperty.interpretation_hint` by the Rust model query. */
|
|
106
|
+
interpretationHint?: string;
|
|
107
|
+
/** AD4M-specific: marks this property as the class's identity (dedup key)
|
|
108
|
+
* for the generic LLM interpreter. Emitted as an `ad4m://identity` link
|
|
109
|
+
* (`literal:string:true`) and read back on `ShapeProperty.identity`. */
|
|
110
|
+
identity?: boolean;
|
|
102
111
|
}
|
|
103
112
|
/**
|
|
104
113
|
* SHACL Node Shape
|
|
@@ -117,6 +126,11 @@ export declare class SHACLShape {
|
|
|
117
126
|
destructor_actions?: AD4MAction[];
|
|
118
127
|
/** Parent shape URIs for model inheritance (sh:node references) */
|
|
119
128
|
parentShapes: string[];
|
|
129
|
+
/** AD4M-specific: Natural-language hint that steers the generic LLM
|
|
130
|
+
* extractor when producing instances of this class. Emitted as an
|
|
131
|
+
* `ad4m://interpretation_hint` link on the shape node itself and surfaced
|
|
132
|
+
* on `ModelShape.interpretation_hint` by the Rust model query. */
|
|
133
|
+
interpretationHint?: string;
|
|
120
134
|
/**
|
|
121
135
|
* Create a new SHACL Shape
|
|
122
136
|
* @param targetClassOrShapeUri - If one argument: the target class (shape URI auto-derived as {class}Shape)
|
|
@@ -229,6 +229,15 @@ export class SHACLShape {
|
|
|
229
229
|
target: `literal:string:${JSON.stringify(this.destructor_actions)}`
|
|
230
230
|
});
|
|
231
231
|
}
|
|
232
|
+
// Class-level interpretation hint — read by the Rust model query as
|
|
233
|
+
// `ModelShape.interpretation_hint` and fed to the generic LLM extractor.
|
|
234
|
+
if (this.interpretationHint) {
|
|
235
|
+
links.push({
|
|
236
|
+
source: this.nodeShapeUri,
|
|
237
|
+
predicate: "ad4m://interpretation_hint",
|
|
238
|
+
target: `literal:string:${this.interpretationHint}`
|
|
239
|
+
});
|
|
240
|
+
}
|
|
232
241
|
// Property shapes (each gets a named URI: {namespace}/{ClassName}.{propertyName})
|
|
233
242
|
for (let i = 0; i < this.properties.length; i++) {
|
|
234
243
|
const prop = this.properties[i];
|
|
@@ -428,6 +437,20 @@ export class SHACLShape {
|
|
|
428
437
|
target: `literal:string:${JSON.stringify(prop.transform)}`
|
|
429
438
|
});
|
|
430
439
|
}
|
|
440
|
+
if (prop.interpretationHint) {
|
|
441
|
+
links.push({
|
|
442
|
+
source: propShapeId,
|
|
443
|
+
predicate: "ad4m://interpretation_hint",
|
|
444
|
+
target: `literal:string:${prop.interpretationHint}`
|
|
445
|
+
});
|
|
446
|
+
}
|
|
447
|
+
if (prop.identity) {
|
|
448
|
+
links.push({
|
|
449
|
+
source: propShapeId,
|
|
450
|
+
predicate: "ad4m://identity",
|
|
451
|
+
target: `literal:string:true`
|
|
452
|
+
});
|
|
453
|
+
}
|
|
431
454
|
}
|
|
432
455
|
return links;
|
|
433
456
|
}
|
|
@@ -460,6 +483,11 @@ export class SHACLShape {
|
|
|
460
483
|
// Ignore parse errors
|
|
461
484
|
}
|
|
462
485
|
}
|
|
486
|
+
// Class-level interpretation hint (mirror of the emit in toLinks())
|
|
487
|
+
const classHintLink = links.find(l => l.source === shapeUri && l.predicate === "ad4m://interpretation_hint");
|
|
488
|
+
if (classHintLink) {
|
|
489
|
+
shape.interpretationHint = classHintLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
|
|
490
|
+
}
|
|
463
491
|
// Find all property shapes
|
|
464
492
|
const propShapeLinks = links.filter(l => l.source === shapeUri && l.predicate === "sh://property");
|
|
465
493
|
for (const propLink of propShapeLinks) {
|
|
@@ -647,6 +675,15 @@ export class SHACLShape {
|
|
|
647
675
|
val = val.substring(8);
|
|
648
676
|
prop.filter = val === 'true';
|
|
649
677
|
}
|
|
678
|
+
const interpretationHintLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://interpretation_hint");
|
|
679
|
+
if (interpretationHintLink) {
|
|
680
|
+
prop.interpretationHint = interpretationHintLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
|
|
681
|
+
}
|
|
682
|
+
const identityLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://identity");
|
|
683
|
+
if (identityLink) {
|
|
684
|
+
prop.identity =
|
|
685
|
+
identityLink.target.replace(/^literal:\/\/string:|^literal:string:/, '') === 'true';
|
|
686
|
+
}
|
|
650
687
|
const transformLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://transform");
|
|
651
688
|
if (transformLink) {
|
|
652
689
|
const jsonStr = transformLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
|
|
@@ -678,6 +715,7 @@ export class SHACLShape {
|
|
|
678
715
|
node_shape_uri: this.nodeShapeUri,
|
|
679
716
|
target_class: this.targetClass,
|
|
680
717
|
parent_shapes: this.parentShapes.length > 0 ? this.parentShapes : undefined,
|
|
718
|
+
interpretation_hint: this.interpretationHint,
|
|
681
719
|
properties: this.properties.map(p => ({
|
|
682
720
|
path: p.path,
|
|
683
721
|
name: p.name,
|
|
@@ -705,6 +743,7 @@ export class SHACLShape {
|
|
|
705
743
|
where_predicates: p.wherePredicates,
|
|
706
744
|
filter: p.filter,
|
|
707
745
|
transform: p.transform,
|
|
746
|
+
interpretation_hint: p.interpretationHint,
|
|
708
747
|
})),
|
|
709
748
|
constructor_actions: this.constructor_actions,
|
|
710
749
|
destructor_actions: this.destructor_actions,
|
|
@@ -750,6 +789,7 @@ export class SHACLShape {
|
|
|
750
789
|
wherePredicates: p.where_predicates,
|
|
751
790
|
filter: p.filter,
|
|
752
791
|
transform: p.transform,
|
|
792
|
+
interpretationHint: p.interpretation_hint,
|
|
753
793
|
});
|
|
754
794
|
}
|
|
755
795
|
if (json.constructor_actions) {
|
|
@@ -763,6 +803,9 @@ export class SHACLShape {
|
|
|
763
803
|
shape.addParentShape(ps);
|
|
764
804
|
}
|
|
765
805
|
}
|
|
806
|
+
if (json.interpretation_hint) {
|
|
807
|
+
shape.interpretationHint = json.interpretation_hint;
|
|
808
|
+
}
|
|
766
809
|
return shape;
|
|
767
810
|
}
|
|
768
811
|
}
|
package/package.json
CHANGED
|
@@ -55,7 +55,11 @@
|
|
|
55
55
|
},
|
|
56
56
|
"patchedDependencies": {},
|
|
57
57
|
"pnpm": {
|
|
58
|
-
"patchedDependencies": {}
|
|
58
|
+
"patchedDependencies": {},
|
|
59
|
+
"overrides": {
|
|
60
|
+
"@types/node": "18.11.10",
|
|
61
|
+
"pako": "2.1.0"
|
|
62
|
+
}
|
|
59
63
|
},
|
|
60
|
-
"version": "0.13.0-test-
|
|
64
|
+
"version": "0.13.0-test-interpretation"
|
|
61
65
|
}
|
package/src/ai/AIClient.ts
CHANGED
|
@@ -83,7 +83,9 @@ export class AIClient {
|
|
|
83
83
|
const aiEmbed = await this.#apiClient.call<string>('ai.embed', { modelId, text });
|
|
84
84
|
|
|
85
85
|
const compressed = base64js.toByteArray(aiEmbed);
|
|
86
|
-
|
|
86
|
+
// Decode to a string via TextDecoder rather than pako's `{ to: 'string' }`
|
|
87
|
+
// option: newer @types/pako dropped that overload, which broke the build.
|
|
88
|
+
const decompressed = JSON.parse(new TextDecoder().decode(pako.inflate(compressed)));
|
|
87
89
|
|
|
88
90
|
return decompressed;
|
|
89
91
|
}
|
package/src/apiClient.ts
CHANGED
|
@@ -207,9 +207,12 @@ export class ApiClient {
|
|
|
207
207
|
* Send an RPC call over the WebSocket connection.
|
|
208
208
|
* @param type - The operation type (e.g. 'agent.get', 'perspective.all')
|
|
209
209
|
* @param params - Optional parameters to include in the message
|
|
210
|
+
* @param timeoutMs - Optional per-call timeout override in ms. Defaults to
|
|
211
|
+
* [[DEFAULT_TIMEOUT_MS]]. Use for long-running calls (LLM prompts,
|
|
212
|
+
* holochain ops) that legitimately exceed the default.
|
|
210
213
|
* @returns Promise that resolves with the result from the server
|
|
211
214
|
*/
|
|
212
|
-
async call<T>(type: string, params?: Record<string, unknown
|
|
215
|
+
async call<T>(type: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T> {
|
|
213
216
|
await this._ready()
|
|
214
217
|
|
|
215
218
|
const id = nextId()
|
|
@@ -217,12 +220,13 @@ export class ApiClient {
|
|
|
217
220
|
// protocol fields "id" and "type" (e.g. params might contain
|
|
218
221
|
// { id: modelId } or { type: "db" }).
|
|
219
222
|
const message: Record<string, unknown> = { id, type, params: params || {} }
|
|
223
|
+
const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS
|
|
220
224
|
|
|
221
225
|
return new Promise<T>((resolve, reject) => {
|
|
222
226
|
const timer = setTimeout(() => {
|
|
223
227
|
this._pendingCalls.delete(id)
|
|
224
|
-
reject(new RpcError(408, `RPC call '${type}' timed out after ${
|
|
225
|
-
},
|
|
228
|
+
reject(new RpcError(408, `RPC call '${type}' timed out after ${effectiveTimeout}ms`))
|
|
229
|
+
}, effectiveTimeout)
|
|
226
230
|
|
|
227
231
|
this._pendingCalls.set(id, {
|
|
228
232
|
resolve: resolve as (value: unknown) => void,
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
|
|
2
|
+
import type { TranscriptTurn } from "./TranscriptTurn";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Run generic LLM interpretation over a transcript into the perspective's own
|
|
6
|
+
* SHACL subject classes. Shapes are resolved server-side from the
|
|
7
|
+
* perspective's registered classes, so callers pass only the transcript.
|
|
8
|
+
*/
|
|
9
|
+
export type RunInterpretationRequest = { uuid: string, transcript: Array<TranscriptTurn>,
|
|
10
|
+
/**
|
|
11
|
+
* URI namespace new instance identities are minted under, e.g. `soa://ext/`.
|
|
12
|
+
*/
|
|
13
|
+
basePrefix: string,
|
|
14
|
+
/**
|
|
15
|
+
* Local names of the subject classes to extract into (e.g. `["Task","Belief"]`).
|
|
16
|
+
* `None`/empty selects all subject classes registered in the perspective.
|
|
17
|
+
*/
|
|
18
|
+
classes: Array<string> | null, };
|
|
@@ -36,11 +36,13 @@ export type { PublishNeighbourhoodRequest } from "./PublishNeighbourhoodRequest"
|
|
|
36
36
|
export type { QueryRequest } from "./QueryRequest";
|
|
37
37
|
export type { RemoveLinkRequest } from "./RemoveLinkRequest";
|
|
38
38
|
export type { RemoveLinksBulkRequest } from "./RemoveLinksBulkRequest";
|
|
39
|
+
export type { RunInterpretationRequest } from "./RunInterpretationRequest";
|
|
39
40
|
export type { SetDefaultModelRequest } from "./SetDefaultModelRequest";
|
|
40
41
|
export type { SetFreeHostingEnabledRequest } from "./SetFreeHostingEnabledRequest";
|
|
41
42
|
export type { SetMultiUserRequest } from "./SetMultiUserRequest";
|
|
42
43
|
export type { SetStatusRequest } from "./SetStatusRequest";
|
|
43
44
|
export type { SignMessageRequest } from "./SignMessageRequest";
|
|
45
|
+
export type { TranscriptTurn } from "./TranscriptTurn";
|
|
44
46
|
export type { TrustedAgentsRequest } from "./TrustedAgentsRequest";
|
|
45
47
|
export type { UnlockAgentRequest } from "./UnlockAgentRequest";
|
|
46
48
|
export type { UpdateLinkRequest } from "./UpdateLinkRequest";
|
package/src/index.ts
CHANGED
|
@@ -16,6 +16,8 @@ export * from "./Literal";
|
|
|
16
16
|
export * from "./perspectives/Perspective";
|
|
17
17
|
export * from "./perspectives/PerspectiveHandle";
|
|
18
18
|
export * from "./perspectives/PerspectiveProxy";
|
|
19
|
+
export * from "./perspectives/AutoProcessor";
|
|
20
|
+
export * from "./perspectives/InterpretationModels";
|
|
19
21
|
export * from "./perspectives/SparqlBindings";
|
|
20
22
|
export * from "./perspectives/WakerSubscriptionManager";
|
|
21
23
|
export * from "./perspectives/PerspectiveDiff";
|
|
@@ -400,7 +400,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
400
400
|
};
|
|
401
401
|
lastResultFingerprint = buildFingerprint(initialResults);
|
|
402
402
|
|
|
403
|
-
// Listen for subscription updates via the same
|
|
403
|
+
// Listen for subscription updates via the same WS-RPC subscription channel.
|
|
404
404
|
// When Rust re-runs the model query and finds changed results, it pushes them.
|
|
405
405
|
const unsubscribe = this.perspective.client.subscribeToQueryUpdates(
|
|
406
406
|
subscriptionId,
|
package/src/model/decorators.ts
CHANGED
|
@@ -335,6 +335,26 @@ export interface PropertyOptions {
|
|
|
335
335
|
* ```
|
|
336
336
|
*/
|
|
337
337
|
options?: Array<{ value: string; label?: string }>;
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* Natural-language hint that steers the generic LLM extractor when
|
|
341
|
+
* turning a transcript into typed subject-class instances. Emitted as
|
|
342
|
+
* an `ad4m://interpretation_hint` link on the property shape and surfaced
|
|
343
|
+
* on `ShapeProperty.interpretation_hint` by the Rust model query so the
|
|
344
|
+
* extractor prompt can quote it verbatim.
|
|
345
|
+
*/
|
|
346
|
+
interpretationHint?: string;
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* Marks this property as the class's **identity** (dedup key) for the
|
|
350
|
+
* generic LLM interpreter: on re-runs, two proposed instances of the same
|
|
351
|
+
* class with an equal (normalized/semantic) value on the identity property
|
|
352
|
+
* are treated as the same instance rather than duplicated. Emitted as an
|
|
353
|
+
* `ad4m://identity` link on the property shape and read back by the Rust
|
|
354
|
+
* model query (`ShapeProperty.identity`). At most one property per class
|
|
355
|
+
* should set this.
|
|
356
|
+
*/
|
|
357
|
+
identity?: boolean;
|
|
338
358
|
}
|
|
339
359
|
|
|
340
360
|
|
|
@@ -506,6 +526,14 @@ export interface ModelConfig {
|
|
|
506
526
|
* The name of the entity.
|
|
507
527
|
*/
|
|
508
528
|
name: string;
|
|
529
|
+
|
|
530
|
+
/**
|
|
531
|
+
* Natural-language hint that steers the generic LLM extractor when
|
|
532
|
+
* turning a transcript into instances of this class. Emitted as an
|
|
533
|
+
* `ad4m://interpretation_hint` link on the SHACL shape node and surfaced
|
|
534
|
+
* on `ModelShape.interpretation_hint` by the Rust model query.
|
|
535
|
+
*/
|
|
536
|
+
interpretationHint?: string;
|
|
509
537
|
}
|
|
510
538
|
|
|
511
539
|
/**
|
|
@@ -584,6 +612,7 @@ export function Model(opts: ModelConfig) {
|
|
|
584
612
|
getRelationsMetadata(target),
|
|
585
613
|
buildConformanceFilter,
|
|
586
614
|
seed,
|
|
615
|
+
opts.interpretationHint,
|
|
587
616
|
));
|
|
588
617
|
}
|
|
589
618
|
|
package/src/model/shacl-gen.ts
CHANGED
|
@@ -45,6 +45,13 @@ export function buildSHACL(
|
|
|
45
45
|
* directly (e.g. from a one-off SDNA build tool).
|
|
46
46
|
*/
|
|
47
47
|
seedCache?: (partial: { shape: SHACLShape; name: string }) => void,
|
|
48
|
+
/**
|
|
49
|
+
* Natural-language hint declared on the `@Model` decorator that
|
|
50
|
+
* steers the generic LLM extractor when producing instances of
|
|
51
|
+
* this class. Attached to the SHACL shape node and re-emitted as
|
|
52
|
+
* an `ad4m://interpretation_hint` link by `SHACLShape.toLinks()`.
|
|
53
|
+
*/
|
|
54
|
+
interpretationHint?: string,
|
|
48
55
|
): { shape: SHACLShape; name: string } {
|
|
49
56
|
const obj = target.prototype;
|
|
50
57
|
|
|
@@ -76,6 +83,9 @@ export function buildSHACL(
|
|
|
76
83
|
const shapeUri = `${namespace}${subjectName}Shape`;
|
|
77
84
|
const targetClass = `${namespace}${subjectName}`;
|
|
78
85
|
const shape = new SHACLShape(shapeUri, targetClass);
|
|
86
|
+
if (interpretationHint) {
|
|
87
|
+
shape.interpretationHint = interpretationHint;
|
|
88
|
+
}
|
|
79
89
|
|
|
80
90
|
// ── Seed the memoisation cache while we keep building ──────────────
|
|
81
91
|
// Any subsequent `target.generateSHACL()` call from inside this
|
|
@@ -176,6 +186,18 @@ export function buildSHACL(
|
|
|
176
186
|
propShape.transform = propMeta.transform;
|
|
177
187
|
}
|
|
178
188
|
|
|
189
|
+
// Natural-language interpretation hint (read by the generic LLM
|
|
190
|
+
// extractor via ShapeProperty.interpretation_hint).
|
|
191
|
+
if (propMeta.interpretationHint) {
|
|
192
|
+
propShape.interpretationHint = propMeta.interpretationHint;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
// Declared-identity dedup key for the generic LLM interpreter
|
|
196
|
+
// (emitted as `ad4m://identity` by SHACLShape.toLinks()).
|
|
197
|
+
if (propMeta.identity) {
|
|
198
|
+
propShape.identity = true;
|
|
199
|
+
}
|
|
200
|
+
|
|
179
201
|
// ── Setter actions ──────────────────────────────────────────────
|
|
180
202
|
if (propMeta.prologSetter) {
|
|
181
203
|
console.warn(
|
|
@@ -194,4 +194,80 @@ describe("Decorators → SHACL writer round-trip", () => {
|
|
|
194
194
|
findLinkTarget(links, "ns://Profile.name", "ad4m://resolveLanguage"),
|
|
195
195
|
).toBe("literal:string:literal");
|
|
196
196
|
});
|
|
197
|
+
|
|
198
|
+
it("emits ad4m://interpretation_hint on the class shape and per property", () => {
|
|
199
|
+
@Model({
|
|
200
|
+
name: "Belief",
|
|
201
|
+
interpretationHint:
|
|
202
|
+
"A claim a participant holds to be true about the world or the group. Not a task or a question.",
|
|
203
|
+
})
|
|
204
|
+
class Belief extends Ad4mModel {
|
|
205
|
+
@Property({
|
|
206
|
+
through: "ns://title",
|
|
207
|
+
required: true,
|
|
208
|
+
resolveLanguage: "literal",
|
|
209
|
+
interpretationHint: "One-sentence statement in the claimant's framing.",
|
|
210
|
+
})
|
|
211
|
+
title: string = "";
|
|
212
|
+
|
|
213
|
+
@Property({ through: "ns://body", resolveLanguage: "literal" })
|
|
214
|
+
body: string = "";
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
const { shape } = Belief.generateSHACL();
|
|
218
|
+
const links = flatten(shape);
|
|
219
|
+
|
|
220
|
+
expect(findLinkTarget(links, shape.nodeShapeUri, "ad4m://interpretation_hint"))
|
|
221
|
+
.toBe(
|
|
222
|
+
"literal:string:A claim a participant holds to be true about the " +
|
|
223
|
+
"world or the group. Not a task or a question.",
|
|
224
|
+
);
|
|
225
|
+
expect(
|
|
226
|
+
findLinkTarget(links, "ns://Belief.title", "ad4m://interpretation_hint"),
|
|
227
|
+
).toBe(
|
|
228
|
+
"literal:string:One-sentence statement in the claimant's framing.",
|
|
229
|
+
);
|
|
230
|
+
expect(
|
|
231
|
+
findLinkTarget(links, "ns://Belief.body", "ad4m://interpretation_hint"),
|
|
232
|
+
).toBeUndefined();
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
it("round-trips interpretationHint through toJSON/fromJSON", () => {
|
|
236
|
+
@Model({
|
|
237
|
+
name: "Task",
|
|
238
|
+
interpretationHint:
|
|
239
|
+
"Something a participant commits to doing - actionable outcome.",
|
|
240
|
+
})
|
|
241
|
+
class Task extends Ad4mModel {
|
|
242
|
+
@Property({
|
|
243
|
+
through: "ns://title",
|
|
244
|
+
required: true,
|
|
245
|
+
resolveLanguage: "literal",
|
|
246
|
+
interpretationHint: "Imperative summary of the work.",
|
|
247
|
+
})
|
|
248
|
+
title: string = "";
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const { shape } = Task.generateSHACL();
|
|
252
|
+
const json: any = shape.toJSON();
|
|
253
|
+
|
|
254
|
+
expect(json.interpretation_hint).toBe(
|
|
255
|
+
"Something a participant commits to doing - actionable outcome.",
|
|
256
|
+
);
|
|
257
|
+
const titleProp = json.properties.find((p: any) => p.name === "title");
|
|
258
|
+
expect(titleProp.interpretation_hint).toBe(
|
|
259
|
+
"Imperative summary of the work.",
|
|
260
|
+
);
|
|
261
|
+
|
|
262
|
+
const rebuilt = (shape.constructor as any).fromJSON(json);
|
|
263
|
+
expect(rebuilt.interpretationHint).toBe(
|
|
264
|
+
"Something a participant commits to doing - actionable outcome.",
|
|
265
|
+
);
|
|
266
|
+
const rebuiltTitle = rebuilt.properties.find(
|
|
267
|
+
(p: any) => p.name === "title",
|
|
268
|
+
);
|
|
269
|
+
expect(rebuiltTitle.interpretationHint).toBe(
|
|
270
|
+
"Imperative summary of the work.",
|
|
271
|
+
);
|
|
272
|
+
});
|
|
197
273
|
});
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// Neighbourhood auto-processor: client-side types for `perspective.addAutoProcessor`
|
|
2
|
+
// and the `auto-processor-event` step signals. These mirror the Rust
|
|
3
|
+
// `AutoProcessorConfig` / `auto_processor::events::AutoProcessorEvent`
|
|
4
|
+
// (serde `camelCase`).
|
|
5
|
+
|
|
6
|
+
/** One step in an auto-processor pass (serde camelCase of the Rust enum). */
|
|
7
|
+
export type AutoProcessorStep =
|
|
8
|
+
| "batchReady"
|
|
9
|
+
| "claimed"
|
|
10
|
+
| "backedOff"
|
|
11
|
+
| "awaitingAuthor"
|
|
12
|
+
| "notCandidate"
|
|
13
|
+
| "gatheringTranscript"
|
|
14
|
+
| "runningInterpretation"
|
|
15
|
+
| "processed"
|
|
16
|
+
| "shapesMissing"
|
|
17
|
+
| "emptyTranscript";
|
|
18
|
+
|
|
19
|
+
/** A single step-signal from one auto-processor pass on one perspective. */
|
|
20
|
+
export interface AutoProcessorEvent {
|
|
21
|
+
type: "auto-processor-event";
|
|
22
|
+
perspectiveUuid: string;
|
|
23
|
+
processorId: string;
|
|
24
|
+
/** DID of the agent that ran the pass (which peer claimed/processed/backed off). */
|
|
25
|
+
agentDid?: string;
|
|
26
|
+
step: AutoProcessorStep;
|
|
27
|
+
/** The batch's source item ids (present from `batchReady` onward). */
|
|
28
|
+
itemIds: string[];
|
|
29
|
+
/** Instance base URIs written by the pass (present on `processed`). */
|
|
30
|
+
bases: string[];
|
|
31
|
+
/** Free-form context for the step (a holder/elected DID, an error, …). */
|
|
32
|
+
detail?: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
|
|
36
|
+
export interface AddAutoProcessorConfig {
|
|
37
|
+
/** Human-meaningful processor id (unique per perspective). */
|
|
38
|
+
processorId: string;
|
|
39
|
+
/**
|
|
40
|
+
* SPARQL `SELECT ?speaker ?text ?timestamp` over the source items to
|
|
41
|
+
* interpret. All three bindings are required: `?timestamp` is what makes a
|
|
42
|
+
* turn identifiable, so the processed-turn cursor can tell a re-gathered
|
|
43
|
+
* turn from the same wording said again later. Read the body link's reifier
|
|
44
|
+
* for author and timestamp rather than an app-level `ns://author`:
|
|
45
|
+
*
|
|
46
|
+
* ```sparql
|
|
47
|
+
* SELECT ?speaker ?text ?timestamp WHERE {
|
|
48
|
+
* ?m <ns://body> ?text .
|
|
49
|
+
* ?r <http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> <<( ?m <ns://body> ?text )>> .
|
|
50
|
+
* ?r <ad4m://ontology/author> ?speaker .
|
|
51
|
+
* ?r <ad4m://ontology/timestamp> ?timestamp .
|
|
52
|
+
* }
|
|
53
|
+
* ORDER BY ?timestamp
|
|
54
|
+
* ```
|
|
55
|
+
*
|
|
56
|
+
* Swap `ns://body` for your own body predicate. A query binding only
|
|
57
|
+
* speaker+text fails the gather.
|
|
58
|
+
*/
|
|
59
|
+
sourceScopeQuery: string;
|
|
60
|
+
/**
|
|
61
|
+
* URI namespace new interpreted instances are minted under (the "spawn
|
|
62
|
+
* scope"), e.g. `soa://project/42/`. Omit for a per-processor default
|
|
63
|
+
* (`ad4m://autoprocessor/<processorId>/instance/`). Point this and
|
|
64
|
+
* `sourceScopeQuery` at the same subtree to confine a processor to it.
|
|
65
|
+
*/
|
|
66
|
+
basePrefix?: string;
|
|
67
|
+
/** Class URIs (SHACL `target_class`) to materialize each pass. */
|
|
68
|
+
interpretationClasses: string[];
|
|
69
|
+
/** Quiet-window (ms) after the last new item before a pass runs. */
|
|
70
|
+
debounceMs: number;
|
|
71
|
+
/** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */
|
|
72
|
+
batchMin?: number;
|
|
73
|
+
/** Cap on items per pass. */
|
|
74
|
+
batchMax: number;
|
|
75
|
+
/** Safety flush (ms) for a sub-`batchMin` batch; omit to wait indefinitely. */
|
|
76
|
+
maxWaitMs?: number;
|
|
77
|
+
/** How long a won claim is authoritative before peers may re-claim (ms). */
|
|
78
|
+
claimTtlMs: number;
|
|
79
|
+
/** Optional serialized `DedupStrategy` JSON (else NormalizedString). */
|
|
80
|
+
dedupStrategyJson?: string;
|
|
81
|
+
/**
|
|
82
|
+
* How far back (ms) each pass looks: turns older than `now - window` are
|
|
83
|
+
* dropped, and the processed-turn cursor only counts runs that finished
|
|
84
|
+
* inside the same window. Omit for no window — every gathered turn is a
|
|
85
|
+
* candidate and the cursor is the unbounded union of this processor's past
|
|
86
|
+
* runs.
|
|
87
|
+
*/
|
|
88
|
+
sourceWindowMs?: number;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Raw REST-API response shape for a pending interpretation overlay.
|
|
93
|
+
* This is the plain-data DTO returned by `PerspectiveProxy.interpretationOverlays()`.
|
|
94
|
+
* For perspective-graph querying, use the `@Model` class `InterpretationOverlay`
|
|
95
|
+
* from `@coasys/ad4m` (which supports `findAll`, `findOne`, etc.).
|
|
96
|
+
*/
|
|
97
|
+
export interface InterpretationOverlayInfo {
|
|
98
|
+
/** The base instance the overlay sits on. */
|
|
99
|
+
base: string;
|
|
100
|
+
/** Whether the LLM authored the whole instance (`"create"`) or proposed
|
|
101
|
+
* changes to an existing one (`"update"`). */
|
|
102
|
+
kind: "create" | "update";
|
|
103
|
+
/** The `InterpretationRun` that last wrote it, if present. */
|
|
104
|
+
run: string | null;
|
|
105
|
+
/** `[realPredicate, stagedValue]` pairs — the model's proposed values. */
|
|
106
|
+
inferred: [string, any][];
|
|
107
|
+
}
|