@coasys/ad4m 0.13.0-test-interpretation → 0.13.0-test-interpretation-2
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 +451 -149
- package/lib/index.js +449 -150
- package/lib/src/Literal.js +8 -0
- package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
- package/lib/src/model/Ad4mModel.d.ts +28 -11
- package/lib/src/model/Ad4mModel.js +57 -35
- package/lib/src/model/ModelQueryBuilder.js +2 -2
- package/lib/src/model/decorators.d.ts +52 -8
- package/lib/src/model/decorators.js +18 -8
- package/lib/src/model/json-schema.js +7 -21
- package/lib/src/model/query-common.d.ts +2 -2
- package/lib/src/model/query-sparql.d.ts +62 -0
- package/lib/src/model/query-sparql.js +78 -15
- package/lib/src/model/query-utils.d.ts +7 -2
- package/lib/src/model/query-utils.js +21 -11
- package/lib/src/model/shacl-gen.js +44 -15
- package/lib/src/model/types.d.ts +23 -8
- package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
- package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
- package/lib/src/perspectives/InterpretationModels.js +64 -26
- package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
- package/lib/src/perspectives/PerspectiveClient.js +35 -3
- package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
- package/lib/src/perspectives/PerspectiveProxy.js +24 -14
- package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
- package/lib/src/perspectives/SparqlBindings.js +57 -6
- package/lib/src/shacl/SHACLShape.d.ts +11 -3
- package/lib/src/shacl/SHACLShape.js +15 -1
- package/lib/src/shacl/index.d.ts +1 -1
- package/lib/src/shacl/index.js +1 -1
- package/package.json +2 -2
- package/src/Literal.ts +7 -0
- package/src/generated/api/RunInterpretationRequest.ts +19 -3
- package/src/model/Ad4mModel.test.ts +84 -22
- package/src/model/Ad4mModel.ts +61 -41
- package/src/model/ModelQueryBuilder.ts +2 -2
- package/src/model/decorators.ts +62 -9
- package/src/model/json-schema.ts +10 -25
- package/src/model/query-common.ts +2 -2
- package/src/model/query-sparql.test.ts +114 -13
- package/src/model/query-sparql.ts +83 -14
- package/src/model/query-utils.ts +22 -12
- package/src/model/shacl-gen.ts +42 -13
- package/src/model/shacl-roundtrip.test.ts +4 -2
- package/src/model/types.ts +23 -8
- package/src/perspectives/AutoProcessor.ts +133 -1
- package/src/perspectives/InterpretationModels.ts +103 -21
- package/src/perspectives/PerspectiveClient.ts +50 -4
- package/src/perspectives/PerspectiveProxy.ts +37 -21
- package/src/perspectives/SparqlBindings.test.ts +134 -0
- package/src/perspectives/SparqlBindings.ts +57 -6
- package/src/shacl/SHACLShape.test.ts +56 -4
- package/src/shacl/SHACLShape.ts +30 -6
- package/src/shacl/index.ts +1 -1
|
@@ -3,7 +3,55 @@
|
|
|
3
3
|
// `AutoProcessorConfig` / `auto_processor::events::AutoProcessorEvent`
|
|
4
4
|
// (serde `camelCase`).
|
|
5
5
|
|
|
6
|
-
/**
|
|
6
|
+
/**
|
|
7
|
+
* Raw form of `Scope` (parent node + linking predicate) — the only variant
|
|
8
|
+
* the WebSocket auto-processor config accepts. `Scope`'s model form
|
|
9
|
+
* (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
|
|
10
|
+
* constructor, which JSON.stringify silently drops, so the executor would
|
|
11
|
+
* receive `{ id }` and the scope would be unresolvable. Client callers who
|
|
12
|
+
* hold a model class should resolve its predicate via
|
|
13
|
+
* `ModelQueryBuilder.buildParentScope()` first and pass the result here.
|
|
14
|
+
*/
|
|
15
|
+
export type RawScope = { id: string; predicate: string };
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* One step in an auto-processor pass (serde camelCase of the Rust enum).
|
|
19
|
+
*
|
|
20
|
+
* ## Lifecycle (winning peer, emitDebugEvents: true)
|
|
21
|
+
*
|
|
22
|
+
* A pass on the winning executor emits, in order:
|
|
23
|
+
*
|
|
24
|
+
* 1. `batchReady` — debounced batch reached threshold, pass starting
|
|
25
|
+
* 2. `claimed` — this executor won the `try_claim`
|
|
26
|
+
* 3. `gatheringTranscript` — pulling the batch's transcript turns
|
|
27
|
+
* 4. `runningInterpretation` — about to invoke the LLM
|
|
28
|
+
* 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
|
|
29
|
+
* (only when `emitDebugEvents: true`)
|
|
30
|
+
* 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
|
|
31
|
+
* (only when `emitDebugEvents: true`) — the UI
|
|
32
|
+
* can render "waiting on LLM" between steps 5-6
|
|
33
|
+
* 7. `processed` — pass complete; carries `bases[]` (new/updated
|
|
34
|
+
* instance URIs)
|
|
35
|
+
*
|
|
36
|
+
* ## Lifecycle (losing peer, or short-circuit)
|
|
37
|
+
*
|
|
38
|
+
* - `batchReady` → `backedOff` — another peer claimed the batch first
|
|
39
|
+
* - `batchReady` → `awaitingAuthor` — no author of the batch is online
|
|
40
|
+
* - `batchReady` → `notCandidate` — this peer stood down for an earlier author
|
|
41
|
+
* - `claimed` → `shapesMissing` — a configured class shape hasn't synced
|
|
42
|
+
* - `claimed` → `emptyTranscript` — the batch drained empty
|
|
43
|
+
*
|
|
44
|
+
* ## Payload fields per step
|
|
45
|
+
*
|
|
46
|
+
* All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`.
|
|
47
|
+
* Additional payload:
|
|
48
|
+
*
|
|
49
|
+
* - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
|
|
50
|
+
* - `shapesMissing` → `detail` = comma-joined missing class URIs
|
|
51
|
+
* - `llmRequestSent` → `llmInput` = raw prompt
|
|
52
|
+
* - `llmResponseReceived` → `llmOutput` = raw LLM response
|
|
53
|
+
* - `processed` → `bases[]` = new/updated instance URIs
|
|
54
|
+
*/
|
|
7
55
|
export type AutoProcessorStep =
|
|
8
56
|
| "batchReady"
|
|
9
57
|
| "claimed"
|
|
@@ -12,6 +60,8 @@ export type AutoProcessorStep =
|
|
|
12
60
|
| "notCandidate"
|
|
13
61
|
| "gatheringTranscript"
|
|
14
62
|
| "runningInterpretation"
|
|
63
|
+
| "llmRequestSent"
|
|
64
|
+
| "llmResponseReceived"
|
|
15
65
|
| "processed"
|
|
16
66
|
| "shapesMissing"
|
|
17
67
|
| "emptyTranscript";
|
|
@@ -30,6 +80,46 @@ export interface AutoProcessorEvent {
|
|
|
30
80
|
bases: string[];
|
|
31
81
|
/** Free-form context for the step (a holder/elected DID, an error, …). */
|
|
32
82
|
detail?: string;
|
|
83
|
+
/** Raw LLM prompt this pass fed the model. Present ONLY on
|
|
84
|
+
* `llmRequestSent` events, and only when the processor was configured
|
|
85
|
+
* with `emitDebugEvents: true`. Never carried on `processed`. */
|
|
86
|
+
llmInput?: string;
|
|
87
|
+
/** Raw LLM response this pass received. Present ONLY on
|
|
88
|
+
* `llmResponseReceived` events, and only when the processor was
|
|
89
|
+
* configured with `emitDebugEvents: true`. Never carried on `processed`. */
|
|
90
|
+
llmOutput?: string;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Coarse-grained phase of a neighbourhood-state event.
|
|
95
|
+
*
|
|
96
|
+
* `claimed` — this executor just started a pass.
|
|
97
|
+
* `finished` — the pass completed successfully.
|
|
98
|
+
* `abandoned` — the pass short-circuited (missing shape / empty batch /
|
|
99
|
+
* error); the claim will TTL-expire.
|
|
100
|
+
*/
|
|
101
|
+
export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* `auto-processor-neighbourhood-state` — perspective-scoped observability
|
|
105
|
+
* event. Fires when THIS executor claims, finishes, or abandons a batch.
|
|
106
|
+
* Anyone with perspective read access sees it, so a UI can render "someone
|
|
107
|
+
* is auto-processing this" without receiving the batch payload or LLM I/O.
|
|
108
|
+
*
|
|
109
|
+
* Cross-executor visibility (peer's claim reaching us via Holochain sync) is
|
|
110
|
+
* NOT covered here; consumers who need that subscribe to `link-added` and
|
|
111
|
+
* filter for the `has_claim` predicate on the shared perspective.
|
|
112
|
+
*/
|
|
113
|
+
export interface AutoProcessorNeighbourhoodStateEvent {
|
|
114
|
+
type: "auto-processor-neighbourhood-state";
|
|
115
|
+
perspectiveUuid: string;
|
|
116
|
+
processorId: string;
|
|
117
|
+
/** DID that claimed the batch — the pass owner's DID. */
|
|
118
|
+
claimantDid: string;
|
|
119
|
+
/** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
|
|
120
|
+
* for the same key to render a single row in a UI. */
|
|
121
|
+
batchKey: string;
|
|
122
|
+
phase: NeighbourhoodPhase;
|
|
33
123
|
}
|
|
34
124
|
|
|
35
125
|
/** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
|
|
@@ -86,6 +176,48 @@ export interface AddAutoProcessorConfig {
|
|
|
86
176
|
* runs.
|
|
87
177
|
*/
|
|
88
178
|
sourceWindowMs?: number;
|
|
179
|
+
/**
|
|
180
|
+
* Optional parent-scope filter for the dedup lookup: when set, only
|
|
181
|
+
* existing instances of the interpretation classes that live under this
|
|
182
|
+
* scope are candidates for upsert. Omit for the whole-perspective dedup
|
|
183
|
+
* set (pre-scope behaviour). Raw form only — see `RawScope`.
|
|
184
|
+
*/
|
|
185
|
+
existingScope?: RawScope;
|
|
186
|
+
/**
|
|
187
|
+
* Optional parent-scope target for newly minted instances: when set,
|
|
188
|
+
* every base URI the pass CREATES is additionally linked as a child of
|
|
189
|
+
* `mintScope.id` via the scope's predicate — turning the SoA-tree
|
|
190
|
+
* "children live under this node" pattern from a URI-prefix convention
|
|
191
|
+
* into an actual graph edge. Upserts of pre-existing instances are NOT
|
|
192
|
+
* linked (would multi-parent unrelated graph state). Raw form only —
|
|
193
|
+
* see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
|
|
194
|
+
*/
|
|
195
|
+
mintScope?: RawScope;
|
|
196
|
+
/**
|
|
197
|
+
* Persist the raw LLM prompt + response on the pass's `InterpretationRun`
|
|
198
|
+
* (`debugPrompt` / `debugResponse`) so a UI can look them up post-hoc.
|
|
199
|
+
* Independent of `emitDebugEvents` — Nico's PR #903 split so a caller
|
|
200
|
+
* can persist without emitting mid-pass events (retrospective inspection
|
|
201
|
+
* only) or emit without persisting (live observability, no graph-sync
|
|
202
|
+
* payload). Default `false` — LLM I/O is 10s of KB per pass and every
|
|
203
|
+
* enabled peer syncs it.
|
|
204
|
+
*/
|
|
205
|
+
persistDebug?: boolean;
|
|
206
|
+
/**
|
|
207
|
+
* Emit `LlmRequestSent` and `LlmResponseReceived` `auto-processor-event`s
|
|
208
|
+
* mid-pass, so a subscribed UI can render "waiting on LLM" between
|
|
209
|
+
* prompt-send and response-receive. See `persistDebug` for the split
|
|
210
|
+
* rationale. Default `false`.
|
|
211
|
+
*/
|
|
212
|
+
emitDebugEvents?: boolean;
|
|
213
|
+
/**
|
|
214
|
+
* Legacy backwards-compat alias — pre-split callers set `debugMode` as a
|
|
215
|
+
* single coupled flag. When present and both `persistDebug` +
|
|
216
|
+
* `emitDebugEvents` are absent, its value is expanded to both. The two
|
|
217
|
+
* specific fields take precedence when present. Prefer the split fields;
|
|
218
|
+
* this alias is retained so pre-split clients still work.
|
|
219
|
+
*/
|
|
220
|
+
debugMode?: boolean;
|
|
89
221
|
}
|
|
90
222
|
|
|
91
223
|
/**
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
18
|
import { Ad4mModel } from "../model/Ad4mModel";
|
|
19
|
-
import {
|
|
19
|
+
import { HasMany, Optional, Property } from "../model/decorators";
|
|
20
20
|
import { Model } from "../model/decorators";
|
|
21
21
|
|
|
22
22
|
// ── AutoProcessorConfig ─────────────────────────────────────────────────────
|
|
@@ -24,12 +24,19 @@ import { Model } from "../model/decorators";
|
|
|
24
24
|
// One node per registered processor; the node URI is
|
|
25
25
|
// `ad4m://autoprocessor/<processorId>`.
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
// Model name = "AutoProcessor" (NOT "AutoProcessorConfig") to match the Rust
|
|
28
|
+
// hardwired subject class in `perspectives/auto_processor/config.rs` — that
|
|
29
|
+
// alignment is what the SDNA parity test in
|
|
30
|
+
// `tests/js/tests/model/interpretation-models.test.ts` guards. The TS class
|
|
31
|
+
// symbol keeps the `Config` suffix for readability (`AutoProcessorConfig` reads
|
|
32
|
+
// better than a bare `AutoProcessor` for an "instances of the config record"
|
|
33
|
+
// query), but the on-graph subject class it registers is `AutoProcessor`.
|
|
34
|
+
@Model({ name: "AutoProcessor" })
|
|
28
35
|
export class AutoProcessorConfig extends Ad4mModel {
|
|
29
|
-
@Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" })
|
|
30
|
-
type: string = "ad4m://AutoProcessor";
|
|
31
|
-
|
|
32
36
|
/** Unique processor id — the dedup key for auto-processor instances. */
|
|
37
|
+
// First-declared property: `buildSHACL` derives the shape namespace from
|
|
38
|
+
// its `through` prefix, so `ad4m://processor_id` → `ad4m://` → target_class
|
|
39
|
+
// `ad4m://AutoProcessor` (matches Rust `AUTO_PROCESSOR_TARGET_CLASS`).
|
|
33
40
|
@Property({ through: "ad4m://processor_id", required: true, identity: true })
|
|
34
41
|
processorId: string = "";
|
|
35
42
|
|
|
@@ -38,11 +45,15 @@ export class AutoProcessorConfig extends Ad4mModel {
|
|
|
38
45
|
sourceScopeQuery: string = "";
|
|
39
46
|
|
|
40
47
|
/** URI prefix for minted instances; omit for the per-processor default. */
|
|
41
|
-
|
|
48
|
+
// No resolveLanguage — Rust SDNA declares none for this property, so under
|
|
49
|
+
// PR #874 both sides get the fast deterministic typed-literal path.
|
|
50
|
+
// (resolveLanguage: "literal" would ask the executor for a signed envelope
|
|
51
|
+
// that the Rust writer never produces for config metadata.)
|
|
52
|
+
@Optional({ through: "ad4m://base_prefix" })
|
|
42
53
|
basePrefix?: string;
|
|
43
54
|
|
|
44
55
|
/** Class URIs (SHACL targetClass) to materialise each pass. */
|
|
45
|
-
@HasMany({ through: "ad4m://interpretation_class" })
|
|
56
|
+
@HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" })
|
|
46
57
|
interpretationClasses: string[] = [];
|
|
47
58
|
|
|
48
59
|
/** Quiet-window (ms) after the last new item before a pass runs. */
|
|
@@ -50,7 +61,7 @@ export class AutoProcessorConfig extends Ad4mModel {
|
|
|
50
61
|
debounceMs: string = "200";
|
|
51
62
|
|
|
52
63
|
/** Minimum batch size before a pass runs (default 1). */
|
|
53
|
-
@Optional({ through: "ad4m://batch_min"
|
|
64
|
+
@Optional({ through: "ad4m://batch_min" })
|
|
54
65
|
batchMin?: string;
|
|
55
66
|
|
|
56
67
|
/** Maximum items per pass. */
|
|
@@ -58,7 +69,7 @@ export class AutoProcessorConfig extends Ad4mModel {
|
|
|
58
69
|
batchMax: string = "32";
|
|
59
70
|
|
|
60
71
|
/** Safety flush (ms) for a sub-`batchMin` batch; absent = wait indefinitely. */
|
|
61
|
-
@Optional({ through: "ad4m://max_wait_ms"
|
|
72
|
+
@Optional({ through: "ad4m://max_wait_ms" })
|
|
62
73
|
maxWaitMs?: string;
|
|
63
74
|
|
|
64
75
|
/** How long a won claim is authoritative before peers may re-claim (ms). */
|
|
@@ -66,12 +77,70 @@ export class AutoProcessorConfig extends Ad4mModel {
|
|
|
66
77
|
claimTtlMs: string = "60000";
|
|
67
78
|
|
|
68
79
|
/** How far back (ms) each pass looks; absent = unbounded. */
|
|
69
|
-
@Optional({ through: "ad4m://source_window_ms"
|
|
80
|
+
@Optional({ through: "ad4m://source_window_ms" })
|
|
70
81
|
sourceWindowMs?: string;
|
|
71
82
|
|
|
72
83
|
/** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
|
|
73
|
-
@Optional({ through: "ad4m://dedup_strategy"
|
|
84
|
+
@Optional({ through: "ad4m://dedup_strategy" })
|
|
74
85
|
dedupStrategy?: string;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Serialised `Scope` JSON (absent = whole-perspective dedup set).
|
|
89
|
+
* Constrains the existing-instance lookup to the subtree rooted at
|
|
90
|
+
* `Scope.id` linked via `Scope.predicate` — the SoA-tree "existing items
|
|
91
|
+
* live under THIS project node" pattern. Stored as an opaque JSON blob
|
|
92
|
+
* because SHACL properties carry no rich-object type-check; the Rust
|
|
93
|
+
* watcher parses it back into `Scope`.
|
|
94
|
+
*/
|
|
95
|
+
@Optional({ through: "ad4m://existing_scope" })
|
|
96
|
+
existingScope?: string;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Serialised `Scope` JSON (absent = mint sites are unlinked). When set,
|
|
100
|
+
* every freshly created base URI gets an additional `Scope.id
|
|
101
|
+
* --Scope.predicate--> new-uri` link written into the perspective, so
|
|
102
|
+
* mints become first-class children of the target scope. Must be the
|
|
103
|
+
* `Raw` form of `Scope`; `Model` scopes carry no linking predicate.
|
|
104
|
+
*/
|
|
105
|
+
@Optional({ through: "ad4m://mint_scope" })
|
|
106
|
+
mintScope?: string;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Legacy coupled debug knob (`"true"` / `"false"` string). Reserved as a
|
|
110
|
+
* backwards-compat scalar: pre-split writes used it as the single flag
|
|
111
|
+
* for both LLM I/O persistence AND mid-pass event emission. The Rust
|
|
112
|
+
* loader still reads it as a fallback when the specific `persistDebug`
|
|
113
|
+
* / `emitDebugEvents` fields are absent. New writes SHOULD prefer the
|
|
114
|
+
* split fields (below); this alias is retained so a pre-split peer's
|
|
115
|
+
* config still loads with the coupled behaviour it originally requested.
|
|
116
|
+
*/
|
|
117
|
+
@Optional({ through: "ad4m://debug_mode", resolveLanguage: "literal" })
|
|
118
|
+
debugMode?: string;
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Persist the raw LLM prompt + response on the pass's `InterpretationRun`
|
|
122
|
+
* (`debugPrompt` / `debugResponse`). Independent of `emitDebugEvents`
|
|
123
|
+
* — Nico's PR #903 split. Absent = fall back to legacy `debugMode` (see
|
|
124
|
+
* above); when both are absent, defaults to `"false"`.
|
|
125
|
+
*/
|
|
126
|
+
@Optional({ through: "ad4m://persist_debug", resolveLanguage: "literal" })
|
|
127
|
+
persistDebug?: string;
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Emit `LlmRequestSent` and `LlmResponseReceived` auto-processor events
|
|
131
|
+
* mid-pass, so a subscribed UI can render "waiting on LLM" between
|
|
132
|
+
* prompt-send and response-receive. Independent of `persistDebug`.
|
|
133
|
+
* Absent = fall back to legacy `debugMode`; when both are absent,
|
|
134
|
+
* defaults to `"false"`.
|
|
135
|
+
*/
|
|
136
|
+
@Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" })
|
|
137
|
+
emitDebugEvents?: string;
|
|
138
|
+
|
|
139
|
+
// No `@Flag` type discriminator (Nico 2026-08-19: "type flags are an
|
|
140
|
+
// anti-pattern for subject classes; match over all the properties
|
|
141
|
+
// instead"). Conformance is by the presence of `processorId` +
|
|
142
|
+
// `sourceScopeQuery` + `interpretationClasses` + `debounceMs` +
|
|
143
|
+
// `batchMax` + `claimTtlMs` — the Rust SDNA takes the same shape.
|
|
75
144
|
}
|
|
76
145
|
|
|
77
146
|
// ── InterpretationRun ───────────────────────────────────────────────────────
|
|
@@ -80,36 +149,49 @@ export class AutoProcessorConfig extends Ad4mModel {
|
|
|
80
149
|
|
|
81
150
|
@Model({ name: "InterpretationRun" })
|
|
82
151
|
export class InterpretationRun extends Ad4mModel {
|
|
83
|
-
|
|
84
|
-
|
|
152
|
+
// No `@Flag` type discriminator — Rust SDNA drops `ad4m://type` too.
|
|
153
|
+
// Conformance is by `runId` (identity) — same pattern
|
|
154
|
+
// `InterpretationOverlay` already uses (`kind` is its discriminator).
|
|
85
155
|
|
|
86
156
|
/** UUID for this run — the dedup key across run nodes. */
|
|
87
157
|
@Property({ through: "ad4m://interp/run_id", required: true, identity: true })
|
|
88
158
|
runId: string = "";
|
|
89
159
|
|
|
90
160
|
/** LLM model id used for this run. */
|
|
91
|
-
@Optional({ through: "ad4m://interp/model"
|
|
161
|
+
@Optional({ through: "ad4m://interp/model" })
|
|
92
162
|
model?: string;
|
|
93
163
|
|
|
94
164
|
/** SHA-256 hex of the system prompt + few-shots at the time of the run. */
|
|
95
|
-
@Optional({ through: "ad4m://interp/prompt_version"
|
|
165
|
+
@Optional({ through: "ad4m://interp/prompt_version" })
|
|
96
166
|
promptVersion?: string;
|
|
97
167
|
|
|
98
168
|
/** RFC3339 timestamp when the run completed. */
|
|
99
|
-
@Optional({ through: "ad4m://interp/ran_at"
|
|
169
|
+
@Optional({ through: "ad4m://interp/ran_at" })
|
|
100
170
|
ranAt?: string;
|
|
101
171
|
|
|
102
172
|
/** URI of the AutoProcessorConfig node that triggered this run. */
|
|
103
|
-
@Optional({ through: "ad4m://interp/processor"
|
|
173
|
+
@Optional({ through: "ad4m://interp/processor" })
|
|
104
174
|
processor?: string;
|
|
105
175
|
|
|
106
176
|
/**
|
|
107
177
|
* Source item IDs consumed by this pass.
|
|
108
178
|
* Stored as multiple links with the same predicate; the processed-turn
|
|
109
|
-
* cursor uses these to avoid re-interpreting a turn.
|
|
179
|
+
* cursor uses these to avoid re-interpreting a turn. Values are plain
|
|
180
|
+
* strings (turn hex), so the property opts into `sh:datatype`-gated
|
|
181
|
+
* literal decoding on hydration.
|
|
110
182
|
*/
|
|
111
|
-
@HasMany({ through: "ad4m://interp/sources" })
|
|
183
|
+
@HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" })
|
|
112
184
|
sources: string[] = [];
|
|
185
|
+
|
|
186
|
+
/** Raw LLM prompt this pass fed the model. Present only when the pass's
|
|
187
|
+
* AutoProcessor had `persistDebug: true` (or the legacy `debugMode: true`
|
|
188
|
+
* fallback). Absent by default. */
|
|
189
|
+
@Optional({ through: "ad4m://interp/debug_prompt", resolveLanguage: "literal" })
|
|
190
|
+
debugPrompt?: string;
|
|
191
|
+
|
|
192
|
+
/** Raw LLM response this pass received. Same rules as `debugPrompt`. */
|
|
193
|
+
@Optional({ through: "ad4m://interp/debug_response", resolveLanguage: "literal" })
|
|
194
|
+
debugResponse?: string;
|
|
113
195
|
}
|
|
114
196
|
|
|
115
197
|
// ── InterpretationOverlay ───────────────────────────────────────────────────
|
|
@@ -136,10 +218,10 @@ export class InterpretationOverlay extends Ad4mModel {
|
|
|
136
218
|
* changes to an existing one (`"update"`). This is the discriminator link
|
|
137
219
|
* that makes a node identifiable as an overlay.
|
|
138
220
|
*/
|
|
139
|
-
@Property({ through: "ad4m://interp/kind", required: true
|
|
221
|
+
@Property({ through: "ad4m://interp/kind", required: true })
|
|
140
222
|
kind: string = "";
|
|
141
223
|
|
|
142
224
|
/** URI of the InterpretationRun that last wrote this overlay, if present. */
|
|
143
|
-
@Optional({ through: "ad4m://interp/run"
|
|
225
|
+
@Optional({ through: "ad4m://interp/run" })
|
|
144
226
|
run?: string;
|
|
145
227
|
}
|
|
@@ -11,7 +11,7 @@ import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
|
|
|
11
11
|
import { AIClient } from "../ai/AIClient";
|
|
12
12
|
import { AllInstancesResult } from "../model/types";
|
|
13
13
|
import type { TranscriptTurn } from "../generated/api";
|
|
14
|
-
import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
|
|
14
|
+
import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope } from "./AutoProcessor";
|
|
15
15
|
|
|
16
16
|
export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null
|
|
17
17
|
export type UuidCallback = (uuid: string) => null
|
|
@@ -261,11 +261,25 @@ export class PerspectiveClient {
|
|
|
261
261
|
* retries on parse failure), so it can legitimately take minutes on slower
|
|
262
262
|
* or CPU-only models. We raise the default 30s RPC timeout here to 20 min
|
|
263
263
|
* (matches the CI `--timeout 1200000` for the interpretation tests).
|
|
264
|
+
*
|
|
265
|
+
* `existingScope` and `mintScope` match the AutoProcessor semantics:
|
|
266
|
+
* `existingScope` constrains the dedup lookup to instances under a
|
|
267
|
+
* subtree; `mintScope` links every FRESHLY-created base as a child of
|
|
268
|
+
* `mintScope.id` via its predicate (upserts of pre-existing instances
|
|
269
|
+
* are NOT re-parented — same rule as the watcher).
|
|
264
270
|
*/
|
|
265
|
-
async runInterpretation(
|
|
271
|
+
async runInterpretation(
|
|
272
|
+
uuid: string,
|
|
273
|
+
transcript: TranscriptTurn[],
|
|
274
|
+
basePrefix: string,
|
|
275
|
+
classes?: string[],
|
|
276
|
+
existingScope?: RawScope,
|
|
277
|
+
mintScope?: RawScope,
|
|
278
|
+
): Promise<string[]> {
|
|
266
279
|
const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000
|
|
267
280
|
return this.#apiClient.call<string[]>(
|
|
268
|
-
'perspective.runInterpretation',
|
|
281
|
+
'perspective.runInterpretation',
|
|
282
|
+
{ uuid, transcript, basePrefix, classes, existingScope, mintScope },
|
|
269
283
|
RUN_INTERPRETATION_TIMEOUT_MS,
|
|
270
284
|
)
|
|
271
285
|
}
|
|
@@ -311,6 +325,11 @@ export class PerspectiveClient {
|
|
|
311
325
|
* Subscribe to auto-processor step signals. `cb` fires for every
|
|
312
326
|
* `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
|
|
313
327
|
* Processed), letting a UI show progress and await the next batch.
|
|
328
|
+
*
|
|
329
|
+
* Registered on the per-uuid `#linkUnsubscribers` map so
|
|
330
|
+
* `PerspectiveProxy.dispose()` → `removeAllListeners(uuid)` cleans the
|
|
331
|
+
* subscription up; using the global `#unsubscribers` array would leak
|
|
332
|
+
* callbacks across repeated view lifecycles (CodeRabbit #881 review).
|
|
314
333
|
*/
|
|
315
334
|
async addAutoProcessorEventListener(uuid: String, cb: (event: AutoProcessorEvent) => void): Promise<void> {
|
|
316
335
|
const unsub = this.#apiClient.subscribe(
|
|
@@ -320,7 +339,34 @@ export class PerspectiveClient {
|
|
|
320
339
|
}
|
|
321
340
|
}
|
|
322
341
|
)
|
|
323
|
-
this.#
|
|
342
|
+
let existing = this.#linkUnsubscribers.get(uuid as string) || []
|
|
343
|
+
existing.push(unsub)
|
|
344
|
+
this.#linkUnsubscribers.set(uuid as string, existing)
|
|
345
|
+
await this.#apiClient.waitForSubscription()
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* Subscribe to neighbourhood-state events on a perspective. `cb` fires
|
|
350
|
+
* when THIS executor claims / finishes / abandons a batch for any
|
|
351
|
+
* processor on `uuid` — perspective-scoped observability so a UI can
|
|
352
|
+
* render "someone is auto-processing this" without receiving the batch
|
|
353
|
+
* payload or LLM I/O. Registered on the per-uuid `#linkUnsubscribers`
|
|
354
|
+
* map so `PerspectiveProxy.dispose()` sweeps it up.
|
|
355
|
+
*/
|
|
356
|
+
async addAutoProcessorNeighbourhoodStateListener(
|
|
357
|
+
uuid: String,
|
|
358
|
+
cb: (event: AutoProcessorNeighbourhoodStateEvent) => void,
|
|
359
|
+
): Promise<void> {
|
|
360
|
+
const unsub = this.#apiClient.subscribe(
|
|
361
|
+
(data) => {
|
|
362
|
+
if (data.type === 'auto-processor-neighbourhood-state' && data.perspectiveUuid === uuid) {
|
|
363
|
+
cb(data as unknown as AutoProcessorNeighbourhoodStateEvent)
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
)
|
|
367
|
+
let existing = this.#linkUnsubscribers.get(uuid as string) || []
|
|
368
|
+
existing.push(unsub)
|
|
369
|
+
this.#linkUnsubscribers.set(uuid as string, existing)
|
|
324
370
|
await this.#apiClient.waitForSubscription()
|
|
325
371
|
}
|
|
326
372
|
|
|
@@ -16,7 +16,7 @@ import type { TranscriptTurn } from "../generated/api";
|
|
|
16
16
|
|
|
17
17
|
import { SHACLShape } from "../shacl/SHACLShape";
|
|
18
18
|
import { SHACLFlow, LinkPattern } from "../shacl/SHACLFlow";
|
|
19
|
-
import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
|
|
19
|
+
import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo } from "./AutoProcessor";
|
|
20
20
|
|
|
21
21
|
type QueryCallback = (result: AllInstancesResult) => void;
|
|
22
22
|
|
|
@@ -606,6 +606,19 @@ export class PerspectiveProxy {
|
|
|
606
606
|
return await this.#client.addAutoProcessorEventListener(this.#handle.uuid, cb)
|
|
607
607
|
}
|
|
608
608
|
|
|
609
|
+
/**
|
|
610
|
+
* Subscribe to this perspective's auto-processor neighbourhood-state
|
|
611
|
+
* events — fires when this executor claims / finishes / abandons a
|
|
612
|
+
* batch. Perspective-scoped, so a UI can render "someone is
|
|
613
|
+
* auto-processing this" without receiving the batch payload. See
|
|
614
|
+
* `AutoProcessorNeighbourhoodStateEvent`.
|
|
615
|
+
*/
|
|
616
|
+
async addAutoProcessorNeighbourhoodStateListener(
|
|
617
|
+
cb: (event: AutoProcessorNeighbourhoodStateEvent) => void,
|
|
618
|
+
): Promise<void> {
|
|
619
|
+
return await this.#client.addAutoProcessorNeighbourhoodStateListener(this.#handle.uuid, cb)
|
|
620
|
+
}
|
|
621
|
+
|
|
609
622
|
/**
|
|
610
623
|
* Executes a Prolog query against the perspective's knowledge base.
|
|
611
624
|
* This is a powerful way to find complex patterns in the graph.
|
|
@@ -1522,36 +1535,39 @@ export class PerspectiveProxy {
|
|
|
1522
1535
|
*/
|
|
1523
1536
|
async getFlow(name: string): Promise<SHACLFlow | null> {
|
|
1524
1537
|
const flowNameLiteral = Literal.from(name).toUrl();
|
|
1525
|
-
|
|
1538
|
+
|
|
1526
1539
|
// Find flow URI from name mapping
|
|
1527
1540
|
const flowUriLinks = await this.get(new LinkQuery({
|
|
1528
1541
|
source: flowNameLiteral,
|
|
1529
1542
|
predicate: "ad4m://flow_uri"
|
|
1530
1543
|
}));
|
|
1531
|
-
|
|
1544
|
+
|
|
1532
1545
|
if (flowUriLinks.length === 0) {
|
|
1533
1546
|
return null;
|
|
1534
1547
|
}
|
|
1535
|
-
|
|
1548
|
+
|
|
1536
1549
|
const flowUri = flowUriLinks[0].data.target;
|
|
1537
|
-
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
|
|
1541
|
-
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1550
|
+
|
|
1551
|
+
// Fetch flow-level links (hasState, hasTransition, flowable, startAction)
|
|
1552
|
+
const flowLevelLinks = await this.get(new LinkQuery({ source: flowUri }));
|
|
1553
|
+
|
|
1554
|
+
// Collect state and transition URIs, then fetch their child links
|
|
1555
|
+
const childUris = flowLevelLinks
|
|
1556
|
+
.filter(l => l.data.predicate === "ad4m://hasState"
|
|
1557
|
+
|| l.data.predicate === "ad4m://hasTransition")
|
|
1558
|
+
.map(l => l.data.target);
|
|
1559
|
+
const childResults = await Promise.all(
|
|
1560
|
+
childUris.map(uri => this.get(new LinkQuery({ source: uri })))
|
|
1561
|
+
);
|
|
1562
|
+
|
|
1563
|
+
// Flatten into the {source, predicate, target} shape fromLinks expects
|
|
1564
|
+
const allExprs = [...flowLevelLinks, ...childResults.flat()];
|
|
1565
|
+
const flowLinks = allExprs.map(l => ({
|
|
1566
|
+
source: l.data.source,
|
|
1567
|
+
predicate: l.data.predicate,
|
|
1568
|
+
target: l.data.target
|
|
1553
1569
|
}));
|
|
1554
|
-
|
|
1570
|
+
|
|
1555
1571
|
return SHACLFlow.fromLinks(flowLinks, flowUri);
|
|
1556
1572
|
}
|
|
1557
1573
|
|