@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.
Files changed (43) hide show
  1. package/lib/index.cjs +368 -8
  2. package/lib/index.js +369 -9
  3. package/lib/src/ai/AIClient.js +3 -1
  4. package/lib/src/apiClient.d.ts +4 -1
  5. package/lib/src/apiClient.js +7 -3
  6. package/lib/src/generated/api/RunInterpretationRequest.d.ts +19 -0
  7. package/lib/src/generated/api/RunInterpretationRequest.js +1 -0
  8. package/lib/src/generated/api/TranscriptTurn.d.ts +7 -0
  9. package/lib/src/generated/api/TranscriptTurn.js +2 -0
  10. package/lib/src/generated/api/index.d.ts +2 -0
  11. package/lib/src/index.d.ts +2 -0
  12. package/lib/src/index.js +2 -0
  13. package/lib/src/model/ModelQueryBuilder.js +1 -1
  14. package/lib/src/model/decorators.d.ts +25 -0
  15. package/lib/src/model/decorators.js +1 -1
  16. package/lib/src/model/shacl-gen.d.ts +8 -1
  17. package/lib/src/model/shacl-gen.js +21 -1
  18. package/lib/src/perspectives/AutoProcessor.d.ts +89 -0
  19. package/lib/src/perspectives/AutoProcessor.js +5 -0
  20. package/lib/src/perspectives/InterpretationModels.d.ts +71 -0
  21. package/lib/src/perspectives/InterpretationModels.js +190 -0
  22. package/lib/src/perspectives/PerspectiveClient.d.ts +37 -0
  23. package/lib/src/perspectives/PerspectiveClient.js +54 -0
  24. package/lib/src/perspectives/PerspectiveProxy.d.ts +43 -1
  25. package/lib/src/perspectives/PerspectiveProxy.js +53 -1
  26. package/lib/src/shacl/SHACLShape.d.ts +14 -0
  27. package/lib/src/shacl/SHACLShape.js +43 -0
  28. package/package.json +6 -2
  29. package/src/ai/AIClient.ts +3 -1
  30. package/src/apiClient.ts +7 -3
  31. package/src/generated/api/RunInterpretationRequest.ts +18 -0
  32. package/src/generated/api/TranscriptTurn.ts +6 -0
  33. package/src/generated/api/index.ts +2 -0
  34. package/src/index.ts +2 -0
  35. package/src/model/ModelQueryBuilder.ts +1 -1
  36. package/src/model/decorators.ts +29 -0
  37. package/src/model/shacl-gen.ts +22 -0
  38. package/src/model/shacl-roundtrip.test.ts +76 -0
  39. package/src/perspectives/AutoProcessor.ts +107 -0
  40. package/src/perspectives/InterpretationModels.ts +145 -0
  41. package/src/perspectives/PerspectiveClient.ts +75 -0
  42. package/src/perspectives/PerspectiveProxy.ts +61 -1
  43. 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 GraphQL subscription channel as subscribeQuery().
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 GraphQL subscription channel as subscribeQuery().
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-9"
64
+ "version": "0.13.0-test-interpretation"
61
65
  }
@@ -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
- const decompressed = JSON.parse(pako.inflate(compressed, { to: 'string' }));
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>): Promise<T> {
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 ${DEFAULT_TIMEOUT_MS}ms`))
225
- }, DEFAULT_TIMEOUT_MS)
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, };
@@ -0,0 +1,6 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * One conversation turn fed to the extractor.
5
+ */
6
+ export type TranscriptTurn = { speaker: string, text: string, };
@@ -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 GraphQL subscription channel.
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,
@@ -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
 
@@ -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
+ }