@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
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
|
|
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,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
|
}
|