@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
package/lib/src/index.js 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";
@@ -357,7 +357,7 @@ export class ModelQueryBuilder {
357
357
  return JSON.stringify(results, (_, v) => typeof v === 'function' ? undefined : v);
358
358
  };
359
359
  lastResultFingerprint = buildFingerprint(initialResults);
360
- // Listen for subscription updates via the same GraphQL subscription channel.
360
+ // Listen for subscription updates via the same WS-RPC subscription channel.
361
361
  // When Rust re-runs the model query and finds changed results, it pushes them.
362
362
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
363
363
  try {
@@ -179,6 +179,24 @@ export interface PropertyOptions {
179
179
  value: string;
180
180
  label?: string;
181
181
  }>;
182
+ /**
183
+ * Natural-language hint that steers the generic LLM extractor when
184
+ * turning a transcript into typed subject-class instances. Emitted as
185
+ * an `ad4m://interpretation_hint` link on the property shape and surfaced
186
+ * on `ShapeProperty.interpretation_hint` by the Rust model query so the
187
+ * extractor prompt can quote it verbatim.
188
+ */
189
+ interpretationHint?: string;
190
+ /**
191
+ * Marks this property as the class's **identity** (dedup key) for the
192
+ * generic LLM interpreter: on re-runs, two proposed instances of the same
193
+ * class with an equal (normalized/semantic) value on the identity property
194
+ * are treated as the same instance rather than duplicated. Emitted as an
195
+ * `ad4m://identity` link on the property shape and read back by the Rust
196
+ * model query (`ShapeProperty.identity`). At most one property per class
197
+ * should set this.
198
+ */
199
+ identity?: boolean;
182
200
  }
183
201
  /**
184
202
  * Convenience decorator for defining optional (not required) properties.
@@ -270,6 +288,13 @@ export interface ModelConfig {
270
288
  * The name of the entity.
271
289
  */
272
290
  name: string;
291
+ /**
292
+ * Natural-language hint that steers the generic LLM extractor when
293
+ * turning a transcript into instances of this class. Emitted as an
294
+ * `ad4m://interpretation_hint` link on the SHACL shape node and surfaced
295
+ * on `ModelShape.interpretation_hint` by the Rust model query.
296
+ */
297
+ interpretationHint?: string;
273
298
  }
274
299
  /**
275
300
  * Decorator for defining model classes in AD4M.
@@ -370,7 +370,7 @@ export function Model(opts) {
370
370
  return buildSDNA(opts.name, target.prototype, getPropertiesMetadata(target), getRelationsMetadata(target));
371
371
  };
372
372
  target.generateSHACL = function () {
373
- return getMemoizedSHACL(target, (seed) => buildSHACL(opts.name, target, getPropertiesMetadata(target), getRelationsMetadata(target), buildConformanceFilter, seed));
373
+ return getMemoizedSHACL(target, (seed) => buildSHACL(opts.name, target, getPropertiesMetadata(target), getRelationsMetadata(target), buildConformanceFilter, seed, opts.interpretationHint));
374
374
  };
375
375
  Object.defineProperty(target, 'type', { configurable: true });
376
376
  };
@@ -39,7 +39,14 @@ export declare function buildSHACL(subjectName: string, target: any, properties:
39
39
  seedCache?: (partial: {
40
40
  shape: SHACLShape;
41
41
  name: string;
42
- }) => void): {
42
+ }) => void,
43
+ /**
44
+ * Natural-language hint declared on the `@Model` decorator that
45
+ * steers the generic LLM extractor when producing instances of
46
+ * this class. Attached to the SHACL shape node and re-emitted as
47
+ * an `ad4m://interpretation_hint` link by `SHACLShape.toLinks()`.
48
+ */
49
+ interpretationHint?: string): {
43
50
  shape: SHACLShape;
44
51
  name: string;
45
52
  };
@@ -30,7 +30,14 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
30
30
  * `getMemoizedSHACL`; safe to omit when calling `buildSHACL`
31
31
  * directly (e.g. from a one-off SDNA build tool).
32
32
  */
33
- seedCache) {
33
+ seedCache,
34
+ /**
35
+ * Natural-language hint declared on the `@Model` decorator that
36
+ * steers the generic LLM extractor when producing instances of
37
+ * this class. Attached to the SHACL shape node and re-emitted as
38
+ * an `ad4m://interpretation_hint` link by `SHACLShape.toLinks()`.
39
+ */
40
+ interpretationHint) {
34
41
  const obj = target.prototype;
35
42
  // ── Determine namespace from first property or relation ─────────────
36
43
  let namespace = "ad4m://";
@@ -58,6 +65,9 @@ seedCache) {
58
65
  const shapeUri = `${namespace}${subjectName}Shape`;
59
66
  const targetClass = `${namespace}${subjectName}`;
60
67
  const shape = new SHACLShape(shapeUri, targetClass);
68
+ if (interpretationHint) {
69
+ shape.interpretationHint = interpretationHint;
70
+ }
61
71
  // ── Seed the memoisation cache while we keep building ──────────────
62
72
  // Any subsequent `target.generateSHACL()` call from inside this
63
73
  // function (typically when walking a self-referential or
@@ -144,6 +154,16 @@ seedCache) {
144
154
  if (propMeta.transform) {
145
155
  propShape.transform = propMeta.transform;
146
156
  }
157
+ // Natural-language interpretation hint (read by the generic LLM
158
+ // extractor via ShapeProperty.interpretation_hint).
159
+ if (propMeta.interpretationHint) {
160
+ propShape.interpretationHint = propMeta.interpretationHint;
161
+ }
162
+ // Declared-identity dedup key for the generic LLM interpreter
163
+ // (emitted as `ad4m://identity` by SHACLShape.toLinks()).
164
+ if (propMeta.identity) {
165
+ propShape.identity = true;
166
+ }
147
167
  // ── Setter actions ──────────────────────────────────────────────
148
168
  if (propMeta.prologSetter) {
149
169
  console.warn(`[SHACL Generation] Custom Prolog setter for property '${propName}' in class '${subjectName}' is not yet supported. ` +
@@ -0,0 +1,89 @@
1
+ /** One step in an auto-processor pass (serde camelCase of the Rust enum). */
2
+ export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "processed" | "shapesMissing" | "emptyTranscript";
3
+ /** A single step-signal from one auto-processor pass on one perspective. */
4
+ export interface AutoProcessorEvent {
5
+ type: "auto-processor-event";
6
+ perspectiveUuid: string;
7
+ processorId: string;
8
+ /** DID of the agent that ran the pass (which peer claimed/processed/backed off). */
9
+ agentDid?: string;
10
+ step: AutoProcessorStep;
11
+ /** The batch's source item ids (present from `batchReady` onward). */
12
+ itemIds: string[];
13
+ /** Instance base URIs written by the pass (present on `processed`). */
14
+ bases: string[];
15
+ /** Free-form context for the step (a holder/elected DID, an error, …). */
16
+ detail?: string;
17
+ }
18
+ /** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
19
+ export interface AddAutoProcessorConfig {
20
+ /** Human-meaningful processor id (unique per perspective). */
21
+ processorId: string;
22
+ /**
23
+ * SPARQL `SELECT ?speaker ?text ?timestamp` over the source items to
24
+ * interpret. All three bindings are required: `?timestamp` is what makes a
25
+ * turn identifiable, so the processed-turn cursor can tell a re-gathered
26
+ * turn from the same wording said again later. Read the body link's reifier
27
+ * for author and timestamp rather than an app-level `ns://author`:
28
+ *
29
+ * ```sparql
30
+ * SELECT ?speaker ?text ?timestamp WHERE {
31
+ * ?m <ns://body> ?text .
32
+ * ?r <http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> <<( ?m <ns://body> ?text )>> .
33
+ * ?r <ad4m://ontology/author> ?speaker .
34
+ * ?r <ad4m://ontology/timestamp> ?timestamp .
35
+ * }
36
+ * ORDER BY ?timestamp
37
+ * ```
38
+ *
39
+ * Swap `ns://body` for your own body predicate. A query binding only
40
+ * speaker+text fails the gather.
41
+ */
42
+ sourceScopeQuery: string;
43
+ /**
44
+ * URI namespace new interpreted instances are minted under (the "spawn
45
+ * scope"), e.g. `soa://project/42/`. Omit for a per-processor default
46
+ * (`ad4m://autoprocessor/<processorId>/instance/`). Point this and
47
+ * `sourceScopeQuery` at the same subtree to confine a processor to it.
48
+ */
49
+ basePrefix?: string;
50
+ /** Class URIs (SHACL `target_class`) to materialize each pass. */
51
+ interpretationClasses: string[];
52
+ /** Quiet-window (ms) after the last new item before a pass runs. */
53
+ debounceMs: number;
54
+ /** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */
55
+ batchMin?: number;
56
+ /** Cap on items per pass. */
57
+ batchMax: number;
58
+ /** Safety flush (ms) for a sub-`batchMin` batch; omit to wait indefinitely. */
59
+ maxWaitMs?: number;
60
+ /** How long a won claim is authoritative before peers may re-claim (ms). */
61
+ claimTtlMs: number;
62
+ /** Optional serialized `DedupStrategy` JSON (else NormalizedString). */
63
+ dedupStrategyJson?: string;
64
+ /**
65
+ * How far back (ms) each pass looks: turns older than `now - window` are
66
+ * dropped, and the processed-turn cursor only counts runs that finished
67
+ * inside the same window. Omit for no window — every gathered turn is a
68
+ * candidate and the cursor is the unbounded union of this processor's past
69
+ * runs.
70
+ */
71
+ sourceWindowMs?: number;
72
+ }
73
+ /**
74
+ * Raw REST-API response shape for a pending interpretation overlay.
75
+ * This is the plain-data DTO returned by `PerspectiveProxy.interpretationOverlays()`.
76
+ * For perspective-graph querying, use the `@Model` class `InterpretationOverlay`
77
+ * from `@coasys/ad4m` (which supports `findAll`, `findOne`, etc.).
78
+ */
79
+ export interface InterpretationOverlayInfo {
80
+ /** The base instance the overlay sits on. */
81
+ base: string;
82
+ /** Whether the LLM authored the whole instance (`"create"`) or proposed
83
+ * changes to an existing one (`"update"`). */
84
+ kind: "create" | "update";
85
+ /** The `InterpretationRun` that last wrote it, if present. */
86
+ run: string | null;
87
+ /** `[realPredicate, stagedValue]` pairs — the model's proposed values. */
88
+ inferred: [string, any][];
89
+ }
@@ -0,0 +1,5 @@
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
+ export {};
@@ -0,0 +1,71 @@
1
+ /**
2
+ * TypeScript @Model classes mirroring the Rust-side SDNA for the generic
3
+ * interpretation subsystem. Apps can import these to query the perspective
4
+ * graph for interpretation history and pending overlay proposals without
5
+ * knowing the raw link predicates.
6
+ *
7
+ * Registration:
8
+ * await InterpretationOverlay.register(perspective);
9
+ * await InterpretationRun.register(perspective);
10
+ * await AutoProcessorConfig.register(perspective);
11
+ *
12
+ * Querying:
13
+ * const pending = await InterpretationOverlay.findAll(perspective);
14
+ * const runs = await InterpretationRun.findAll(perspective);
15
+ * const configs = await AutoProcessorConfig.findAll(perspective);
16
+ */
17
+ import { Ad4mModel } from "../model/Ad4mModel";
18
+ export declare class AutoProcessorConfig extends Ad4mModel {
19
+ type: string;
20
+ /** Unique processor id — the dedup key for auto-processor instances. */
21
+ processorId: string;
22
+ /** SPARQL SELECT that gathers source items each pass. */
23
+ sourceScopeQuery: string;
24
+ /** URI prefix for minted instances; omit for the per-processor default. */
25
+ basePrefix?: string;
26
+ /** Class URIs (SHACL targetClass) to materialise each pass. */
27
+ interpretationClasses: string[];
28
+ /** Quiet-window (ms) after the last new item before a pass runs. */
29
+ debounceMs: string;
30
+ /** Minimum batch size before a pass runs (default 1). */
31
+ batchMin?: string;
32
+ /** Maximum items per pass. */
33
+ batchMax: string;
34
+ /** Safety flush (ms) for a sub-`batchMin` batch; absent = wait indefinitely. */
35
+ maxWaitMs?: string;
36
+ /** How long a won claim is authoritative before peers may re-claim (ms). */
37
+ claimTtlMs: string;
38
+ /** How far back (ms) each pass looks; absent = unbounded. */
39
+ sourceWindowMs?: string;
40
+ /** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
41
+ dedupStrategy?: string;
42
+ }
43
+ export declare class InterpretationRun extends Ad4mModel {
44
+ type: string;
45
+ /** UUID for this run — the dedup key across run nodes. */
46
+ runId: string;
47
+ /** LLM model id used for this run. */
48
+ model?: string;
49
+ /** SHA-256 hex of the system prompt + few-shots at the time of the run. */
50
+ promptVersion?: string;
51
+ /** RFC3339 timestamp when the run completed. */
52
+ ranAt?: string;
53
+ /** URI of the AutoProcessorConfig node that triggered this run. */
54
+ processor?: string;
55
+ /**
56
+ * Source item IDs consumed by this pass.
57
+ * Stored as multiple links with the same predicate; the processed-turn
58
+ * cursor uses these to avoid re-interpreting a turn.
59
+ */
60
+ sources: string[];
61
+ }
62
+ export declare class InterpretationOverlay extends Ad4mModel {
63
+ /**
64
+ * Whether the LLM authored the whole instance (`"create"`) or proposed
65
+ * changes to an existing one (`"update"`). This is the discriminator link
66
+ * that makes a node identifiable as an overlay.
67
+ */
68
+ kind: string;
69
+ /** URI of the InterpretationRun that last wrote this overlay, if present. */
70
+ run?: string;
71
+ }
@@ -0,0 +1,190 @@
1
+ /**
2
+ * TypeScript @Model classes mirroring the Rust-side SDNA for the generic
3
+ * interpretation subsystem. Apps can import these to query the perspective
4
+ * graph for interpretation history and pending overlay proposals without
5
+ * knowing the raw link predicates.
6
+ *
7
+ * Registration:
8
+ * await InterpretationOverlay.register(perspective);
9
+ * await InterpretationRun.register(perspective);
10
+ * await AutoProcessorConfig.register(perspective);
11
+ *
12
+ * Querying:
13
+ * const pending = await InterpretationOverlay.findAll(perspective);
14
+ * const runs = await InterpretationRun.findAll(perspective);
15
+ * const configs = await AutoProcessorConfig.findAll(perspective);
16
+ */
17
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
18
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
19
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
20
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
21
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
22
+ };
23
+ var __metadata = (this && this.__metadata) || function (k, v) {
24
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
25
+ };
26
+ import { Ad4mModel } from "../model/Ad4mModel";
27
+ import { Flag, HasMany, Optional, Property } from "../model/decorators";
28
+ import { Model } from "../model/decorators";
29
+ // ── AutoProcessorConfig ─────────────────────────────────────────────────────
30
+ // Mirrors the Rust `auto_processor::config::AutoProcessorConfig` SDNA.
31
+ // One node per registered processor; the node URI is
32
+ // `ad4m://autoprocessor/<processorId>`.
33
+ let AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
34
+ constructor() {
35
+ super(...arguments);
36
+ this.type = "ad4m://AutoProcessor";
37
+ /** Unique processor id — the dedup key for auto-processor instances. */
38
+ this.processorId = "";
39
+ /** SPARQL SELECT that gathers source items each pass. */
40
+ this.sourceScopeQuery = "";
41
+ /** Class URIs (SHACL targetClass) to materialise each pass. */
42
+ this.interpretationClasses = [];
43
+ /** Quiet-window (ms) after the last new item before a pass runs. */
44
+ this.debounceMs = "200";
45
+ /** Maximum items per pass. */
46
+ this.batchMax = "32";
47
+ /** How long a won claim is authoritative before peers may re-claim (ms). */
48
+ this.claimTtlMs = "60000";
49
+ }
50
+ };
51
+ __decorate([
52
+ Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" }),
53
+ __metadata("design:type", String)
54
+ ], AutoProcessorConfig.prototype, "type", void 0);
55
+ __decorate([
56
+ Property({ through: "ad4m://processor_id", required: true, identity: true }),
57
+ __metadata("design:type", String)
58
+ ], AutoProcessorConfig.prototype, "processorId", void 0);
59
+ __decorate([
60
+ Property({ through: "ad4m://source_scope_query", required: true }),
61
+ __metadata("design:type", String)
62
+ ], AutoProcessorConfig.prototype, "sourceScopeQuery", void 0);
63
+ __decorate([
64
+ Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" }),
65
+ __metadata("design:type", String)
66
+ ], AutoProcessorConfig.prototype, "basePrefix", void 0);
67
+ __decorate([
68
+ HasMany({ through: "ad4m://interpretation_class" }),
69
+ __metadata("design:type", Array)
70
+ ], AutoProcessorConfig.prototype, "interpretationClasses", void 0);
71
+ __decorate([
72
+ Property({ through: "ad4m://debounce_ms", required: true }),
73
+ __metadata("design:type", String)
74
+ ], AutoProcessorConfig.prototype, "debounceMs", void 0);
75
+ __decorate([
76
+ Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" }),
77
+ __metadata("design:type", String)
78
+ ], AutoProcessorConfig.prototype, "batchMin", void 0);
79
+ __decorate([
80
+ Property({ through: "ad4m://batch_max", required: true }),
81
+ __metadata("design:type", String)
82
+ ], AutoProcessorConfig.prototype, "batchMax", void 0);
83
+ __decorate([
84
+ Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" }),
85
+ __metadata("design:type", String)
86
+ ], AutoProcessorConfig.prototype, "maxWaitMs", void 0);
87
+ __decorate([
88
+ Property({ through: "ad4m://claim_ttl_ms", required: true }),
89
+ __metadata("design:type", String)
90
+ ], AutoProcessorConfig.prototype, "claimTtlMs", void 0);
91
+ __decorate([
92
+ Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" }),
93
+ __metadata("design:type", String)
94
+ ], AutoProcessorConfig.prototype, "sourceWindowMs", void 0);
95
+ __decorate([
96
+ Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" }),
97
+ __metadata("design:type", String)
98
+ ], AutoProcessorConfig.prototype, "dedupStrategy", void 0);
99
+ AutoProcessorConfig = __decorate([
100
+ Model({ name: "AutoProcessorConfig" })
101
+ ], AutoProcessorConfig);
102
+ export { AutoProcessorConfig };
103
+ // ── InterpretationRun ───────────────────────────────────────────────────────
104
+ // Mirrors the Rust `interpretation::overlay::InterpretationRun` SDNA.
105
+ // One node per completed pass; the node URI is `ad4m://interp/run/<runId>`.
106
+ let InterpretationRun = class InterpretationRun extends Ad4mModel {
107
+ constructor() {
108
+ super(...arguments);
109
+ this.type = "ad4m://interpretation-run";
110
+ /** UUID for this run — the dedup key across run nodes. */
111
+ this.runId = "";
112
+ /**
113
+ * Source item IDs consumed by this pass.
114
+ * Stored as multiple links with the same predicate; the processed-turn
115
+ * cursor uses these to avoid re-interpreting a turn.
116
+ */
117
+ this.sources = [];
118
+ }
119
+ };
120
+ __decorate([
121
+ Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" }),
122
+ __metadata("design:type", String)
123
+ ], InterpretationRun.prototype, "type", void 0);
124
+ __decorate([
125
+ Property({ through: "ad4m://interp/run_id", required: true, identity: true }),
126
+ __metadata("design:type", String)
127
+ ], InterpretationRun.prototype, "runId", void 0);
128
+ __decorate([
129
+ Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" }),
130
+ __metadata("design:type", String)
131
+ ], InterpretationRun.prototype, "model", void 0);
132
+ __decorate([
133
+ Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" }),
134
+ __metadata("design:type", String)
135
+ ], InterpretationRun.prototype, "promptVersion", void 0);
136
+ __decorate([
137
+ Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" }),
138
+ __metadata("design:type", String)
139
+ ], InterpretationRun.prototype, "ranAt", void 0);
140
+ __decorate([
141
+ Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" }),
142
+ __metadata("design:type", String)
143
+ ], InterpretationRun.prototype, "processor", void 0);
144
+ __decorate([
145
+ HasMany({ through: "ad4m://interp/sources" }),
146
+ __metadata("design:type", Array)
147
+ ], InterpretationRun.prototype, "sources", void 0);
148
+ InterpretationRun = __decorate([
149
+ Model({ name: "InterpretationRun" })
150
+ ], InterpretationRun);
151
+ export { InterpretationRun };
152
+ // ── InterpretationOverlay ───────────────────────────────────────────────────
153
+ // Mirrors the Rust `interpretation::overlay::InterpretationOverlay` SDNA.
154
+ // An overlay sits on the *same* base URI as the proposed instance — it is a
155
+ // pending LLM suggestion awaiting human accept/reject.
156
+ //
157
+ // The dynamic "inferred" values are stored as links with predicates of the
158
+ // form `ad4m://interp/inferred/<realPredicate>` and are NOT captured here as
159
+ // fixed @Property fields because the predicates vary per class. Read them
160
+ // directly via perspective.get({ source: overlay.baseExpression }).
161
+ //
162
+ // Accept → perspective.acceptInterpretationOverlay(base) [deletes the overlay]
163
+ // Reject → perspective.rejectInterpretationOverlay(base) [drops the suggestion]
164
+ //
165
+ // Note: `findAll` finds ALL nodes that currently carry a `kind` link, i.e.
166
+ // all pending proposals. Accepted/rejected overlays are removed from the
167
+ // graph and will not appear.
168
+ let InterpretationOverlay = class InterpretationOverlay extends Ad4mModel {
169
+ constructor() {
170
+ super(...arguments);
171
+ /**
172
+ * Whether the LLM authored the whole instance (`"create"`) or proposed
173
+ * changes to an existing one (`"update"`). This is the discriminator link
174
+ * that makes a node identifiable as an overlay.
175
+ */
176
+ this.kind = "";
177
+ }
178
+ };
179
+ __decorate([
180
+ Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" }),
181
+ __metadata("design:type", String)
182
+ ], InterpretationOverlay.prototype, "kind", void 0);
183
+ __decorate([
184
+ Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" }),
185
+ __metadata("design:type", String)
186
+ ], InterpretationOverlay.prototype, "run", void 0);
187
+ InterpretationOverlay = __decorate([
188
+ Model({ name: "InterpretationOverlay" })
189
+ ], InterpretationOverlay);
190
+ export { InterpretationOverlay };
@@ -10,6 +10,8 @@ import { PerspectiveHandle, PerspectiveState } from "./PerspectiveHandle";
10
10
  import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
11
11
  import { AIClient } from "../ai/AIClient";
12
12
  import { AllInstancesResult } from "../model/types";
13
+ import type { TranscriptTurn } from "../generated/api";
14
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
13
15
  export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null;
14
16
  export type UuidCallback = (uuid: string) => null;
15
17
  export type LinkCallback = (link: LinkExpression) => null;
@@ -52,6 +54,41 @@ export declare class PerspectiveClient {
52
54
  addLinks(uuid: string, links: Link[], status?: LinkStatus, batchId?: string): Promise<LinkExpression[]>;
53
55
  removeLinks(uuid: string, links: LinkExpressionInput[], batchId?: string): Promise<LinkExpression[]>;
54
56
  linkMutations(uuid: string, mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
57
+ /**
58
+ * Run generic LLM interpretation over a transcript into this perspective's own
59
+ * SHACL subject classes. The target shapes are resolved server-side from the
60
+ * perspective's registered subject classes, so you pass only the transcript.
61
+ * Returns the freshly minted instances (their base URIs + the links written).
62
+ *
63
+ * The server-side call prompts an LLM (up to `INTERPRETATION_MAX_ATTEMPTS`
64
+ * retries on parse failure), so it can legitimately take minutes on slower
65
+ * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
66
+ * (matches the CI `--timeout 1200000` for the interpretation tests).
67
+ */
68
+ runInterpretation(uuid: string, transcript: TranscriptTurn[], basePrefix: string, classes?: string[]): Promise<string[]>;
69
+ /**
70
+ * Register a neighbourhood auto-processor on this perspective. The executor's
71
+ * watch loop then runs interpretation automatically over new source items
72
+ * (like Flux per channel), coordinating which peer processes each batch via
73
+ * the shared-graph ProcessingClaim, and emits step signals on the events
74
+ * WebSocket (subscribe via {@link addAutoProcessorEventListener}).
75
+ * Returns the processor id.
76
+ */
77
+ addAutoProcessor(uuid: string, config: AddAutoProcessorConfig): Promise<string>;
78
+ /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
79
+ interpretationOverlays(uuid: string): Promise<InterpretationOverlayInfo[]>;
80
+ /** Accept an overlay's suggestion(s): the LLM value becomes the real value and
81
+ * the overlay is deleted. Omit `property` to accept the whole base. */
82
+ acceptInterpretation(uuid: string, base: string, property?: string): Promise<boolean>;
83
+ /** Reject an overlay's suggestion(s). Omit `property` to reject the whole base
84
+ * (a rejected `create` deletes the suggested instance). */
85
+ rejectInterpretation(uuid: string, base: string, property?: string): Promise<boolean>;
86
+ /**
87
+ * Subscribe to auto-processor step signals. `cb` fires for every
88
+ * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
89
+ * Processed), letting a UI show progress and await the next batch.
90
+ */
91
+ addAutoProcessorEventListener(uuid: String, cb: (event: AutoProcessorEvent) => void): Promise<void>;
55
92
  addLinkExpression(uuid: string, link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
56
93
  updateLink(uuid: string, oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
57
94
  removeLink(uuid: string, link: LinkExpressionInput, batchId?: string): Promise<boolean>;
@@ -192,6 +192,60 @@ export class PerspectiveClient {
192
192
  async linkMutations(uuid, mutations, status) {
193
193
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.linkMutations', { uuid, mutations, status });
194
194
  }
195
+ /**
196
+ * Run generic LLM interpretation over a transcript into this perspective's own
197
+ * SHACL subject classes. The target shapes are resolved server-side from the
198
+ * perspective's registered subject classes, so you pass only the transcript.
199
+ * Returns the freshly minted instances (their base URIs + the links written).
200
+ *
201
+ * The server-side call prompts an LLM (up to `INTERPRETATION_MAX_ATTEMPTS`
202
+ * retries on parse failure), so it can legitimately take minutes on slower
203
+ * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
204
+ * (matches the CI `--timeout 1200000` for the interpretation tests).
205
+ */
206
+ async runInterpretation(uuid, transcript, basePrefix, classes) {
207
+ const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
208
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes }, RUN_INTERPRETATION_TIMEOUT_MS);
209
+ }
210
+ /**
211
+ * Register a neighbourhood auto-processor on this perspective. The executor's
212
+ * watch loop then runs interpretation automatically over new source items
213
+ * (like Flux per channel), coordinating which peer processes each batch via
214
+ * the shared-graph ProcessingClaim, and emits step signals on the events
215
+ * WebSocket (subscribe via {@link addAutoProcessorEventListener}).
216
+ * Returns the processor id.
217
+ */
218
+ async addAutoProcessor(uuid, config) {
219
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addAutoProcessor', { uuid, ...config });
220
+ }
221
+ /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
222
+ async interpretationOverlays(uuid) {
223
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.interpretationOverlays', { uuid });
224
+ }
225
+ /** Accept an overlay's suggestion(s): the LLM value becomes the real value and
226
+ * the overlay is deleted. Omit `property` to accept the whole base. */
227
+ async acceptInterpretation(uuid, base, property) {
228
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptInterpretation', { uuid, base, property });
229
+ }
230
+ /** Reject an overlay's suggestion(s). Omit `property` to reject the whole base
231
+ * (a rejected `create` deletes the suggested instance). */
232
+ async rejectInterpretation(uuid, base, property) {
233
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectInterpretation', { uuid, base, property });
234
+ }
235
+ /**
236
+ * Subscribe to auto-processor step signals. `cb` fires for every
237
+ * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
238
+ * Processed), letting a UI show progress and await the next batch.
239
+ */
240
+ async addAutoProcessorEventListener(uuid, cb) {
241
+ const unsub = __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
242
+ if (data.type === 'auto-processor-event' && data.perspectiveUuid === uuid) {
243
+ cb(data);
244
+ }
245
+ });
246
+ __classPrivateFieldGet(this, _PerspectiveClient_unsubscribers, "f").push(unsub);
247
+ await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
248
+ }
195
249
  async addLinkExpression(uuid, link, status = 'shared', batchId) {
196
250
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLinkExpression', { uuid, link, status, batchId });
197
251
  }