@coasys/ad4m 0.10.1-rc9-dev → 0.10.1-release-candidate-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.
Files changed (61) hide show
  1. package/lib/index.cjs +3179 -811
  2. package/lib/index.js +3171 -807
  3. package/lib/src/Literal.js +4 -1
  4. package/lib/src/ai/AIClient.d.ts +1 -1
  5. package/lib/src/ai/AIClient.js +6 -6
  6. package/lib/src/ai/AIResolver.d.ts +1 -1
  7. package/lib/src/ai/AIResolver.js +7 -4
  8. package/lib/src/index.d.ts +4 -3
  9. package/lib/src/index.js +4 -3
  10. package/lib/src/model/Ad4mModel.d.ts +609 -0
  11. package/lib/src/model/Ad4mModel.js +1048 -0
  12. package/lib/src/{subject → model}/Subject.d.ts +2 -2
  13. package/lib/src/{subject → model}/Subject.js +18 -18
  14. package/lib/src/model/decorators.d.ts +502 -0
  15. package/lib/src/model/decorators.js +683 -0
  16. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +2 -2
  17. package/lib/src/neighbourhood/NeighbourhoodClient.js +16 -10
  18. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -2
  19. package/lib/src/neighbourhood/NeighbourhoodProxy.js +4 -4
  20. package/lib/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  21. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +31 -0
  22. package/lib/src/neighbourhood/NeighbourhoodResolver.d.ts +2 -2
  23. package/lib/src/neighbourhood/NeighbourhoodResolver.js +6 -4
  24. package/lib/src/perspectives/PerspectiveClient.d.ts +18 -11
  25. package/lib/src/perspectives/PerspectiveClient.js +116 -49
  26. package/lib/src/perspectives/PerspectiveProxy.d.ts +471 -54
  27. package/lib/src/perspectives/PerspectiveProxy.js +579 -64
  28. package/lib/src/perspectives/PerspectiveResolver.d.ts +23 -9
  29. package/lib/src/perspectives/PerspectiveResolver.js +140 -46
  30. package/lib/src/runtime/RuntimeClient.d.ts +5 -1
  31. package/lib/src/runtime/RuntimeClient.js +48 -0
  32. package/lib/src/runtime/RuntimeResolver.d.ts +24 -0
  33. package/lib/src/runtime/RuntimeResolver.js +117 -0
  34. package/lib/src/schema.gql +25 -11
  35. package/lib/src/typeDefs.js +25 -11
  36. package/package.json +2 -1
  37. package/src/Literal.ts +4 -1
  38. package/src/ai/AIClient.ts +6 -6
  39. package/src/ai/AIResolver.ts +6 -3
  40. package/src/index.ts +4 -3
  41. package/src/model/Ad4mModel.ts +1206 -0
  42. package/src/{subject → model}/Subject.ts +16 -16
  43. package/src/{subject/SDNADecorators.ts → model/decorators.ts} +384 -50
  44. package/src/neighbourhood/NeighbourhoodClient.ts +16 -10
  45. package/src/neighbourhood/NeighbourhoodProxy.test.ts +45 -0
  46. package/src/neighbourhood/NeighbourhoodProxy.ts +4 -4
  47. package/src/neighbourhood/NeighbourhoodResolver.ts +2 -2
  48. package/src/perspectives/PerspectiveClient.ts +122 -51
  49. package/src/perspectives/PerspectiveProxy.ts +642 -77
  50. package/src/perspectives/PerspectiveResolver.ts +126 -23
  51. package/src/runtime/RuntimeClient.ts +52 -1
  52. package/src/runtime/RuntimeResolver.ts +77 -0
  53. package/lib/src/subject/SDNADecorators.d.ts +0 -188
  54. package/lib/src/subject/SDNADecorators.js +0 -360
  55. package/lib/src/subject/SubjectEntity.d.ts +0 -110
  56. package/lib/src/subject/SubjectEntity.js +0 -288
  57. package/src/subject/SubjectEntity.ts +0 -336
  58. package/yarn-error.log +0 -90
  59. /package/lib/src/{subject → model}/util.d.ts +0 -0
  60. /package/lib/src/{subject → model}/util.js +0 -0
  61. /package/src/{subject → model}/util.ts +0 -0
@@ -7,86 +7,451 @@ import { ExpressionRendered } from "../expression/Expression";
7
7
  import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
8
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
9
  import { AIClient } from "../ai/AIClient";
10
+ import { AllInstancesResult } from "../model/Ad4mModel";
11
+ type QueryCallback = (result: AllInstancesResult) => void;
12
+ /** Proxy object for a subscribed Prolog query that provides real-time updates
13
+ *
14
+ * This class handles:
15
+ * - Keeping the subscription alive by sending periodic keepalive signals
16
+ * - Managing callbacks for result updates
17
+ * - Subscribing to query updates via GraphQL subscriptions
18
+ * - Maintaining the latest query result
19
+ * - Ensuring subscription is fully initialized before allowing access
20
+ *
21
+ * The subscription will remain active as long as keepalive signals are sent.
22
+ * Make sure to call dispose() when you're done with the subscription to clean up
23
+ * resources and stop keepalive signals.
24
+ *
25
+ * The subscription goes through an initialization process where it waits for the first
26
+ * result to come through the subscription channel. You can await the `initialized`
27
+ * promise to ensure the subscription is ready. The initialization will timeout after
28
+ * 30 seconds if no result is received.
29
+ *
30
+ * Example usage:
31
+ * ```typescript
32
+ * const subscription = await perspective.subscribeInfer("my_query(X)");
33
+ * // At this point the subscription is already initialized since subscribeInfer waits
34
+ *
35
+ * // Set up callback for future updates
36
+ * const removeCallback = subscription.onResult(result => {
37
+ * console.log("New result:", result);
38
+ * });
39
+ *
40
+ * // Later: clean up
41
+ * subscription.dispose();
42
+ * ```
43
+ */
44
+ export declare class QuerySubscriptionProxy {
45
+ #private;
46
+ /** Creates a new query subscription
47
+ * @param uuid - The UUID of the perspective
48
+ * @param subscriptionId - The ID returned by the subscription mutation
49
+ * @param initialResult - The initial query result
50
+ * @param client - The PerspectiveClient instance to use for communication
51
+ */
52
+ constructor(uuid: string, subscriptionId: string, initialResult: AllInstancesResult, client: PerspectiveClient);
53
+ /** Promise that resolves when the subscription has received its first result
54
+ * through the subscription channel. This ensures the subscription is fully
55
+ * set up before allowing access to results or updates.
56
+ *
57
+ * The promise will reject if no result is received within 30 seconds.
58
+ *
59
+ * Note: You typically don't need to await this directly since the subscription
60
+ * creation methods (like subscribeInfer) already wait for initialization.
61
+ */
62
+ get initialized(): Promise<boolean>;
63
+ /** Get the latest query result
64
+ *
65
+ * This returns the most recent result from the query, which could be either:
66
+ * - The initial result from when the subscription was created
67
+ * - The latest update received through the subscription
68
+ *
69
+ * @returns The latest query result as a string (usually a JSON array of bindings)
70
+ */
71
+ get result(): AllInstancesResult;
72
+ /** Add a callback that will be called whenever new results arrive
73
+ *
74
+ * The callback will be called immediately with the current result,
75
+ * and then again each time the query results change.
76
+ *
77
+ * @param callback - Function that takes a result string and processes it
78
+ * @returns A function that can be called to remove this callback
79
+ *
80
+ * Example:
81
+ * ```typescript
82
+ * const removeCallback = subscription.onResult(result => {
83
+ * const bindings = JSON.parse(result);
84
+ * console.log("New bindings:", bindings);
85
+ * });
86
+ *
87
+ * // Later: stop receiving updates
88
+ * removeCallback();
89
+ * ```
90
+ */
91
+ onResult(callback: QueryCallback): () => void;
92
+ /** Clean up the subscription and stop keepalive signals
93
+ *
94
+ * This method:
95
+ * 1. Stops the keepalive timer
96
+ * 2. Unsubscribes from GraphQL subscription updates
97
+ * 3. Clears all registered callbacks
98
+ * 4. Cleans up any pending initialization timeout
99
+ *
100
+ * After calling this method, the subscription is no longer active and
101
+ * will not receive any more updates. The instance should be discarded.
102
+ */
103
+ dispose(): void;
104
+ }
10
105
  type PerspectiveListenerTypes = "link-added" | "link-removed" | "link-updated";
11
106
  export type LinkStatus = "shared" | "local";
12
107
  interface Parameter {
13
108
  name: string;
14
109
  value: string;
15
110
  }
16
- /** Perspective UI proxy object
111
+ /**
112
+ * PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs
113
+ * that store and organize links between expressions.
114
+ *
115
+ * A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view
116
+ * of their digital world. Through PerspectiveProxy, you can:
117
+ * - Add, remove, and query links
118
+ * - Work with Social DNA (subject classes and flows)
119
+ * - Subscribe to real-time updates
120
+ * - Share perspectives as Neighbourhoods
121
+ * - Execute Prolog queries for complex graph patterns
122
+ *
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * // Create and work with links
127
+ * const perspective = await ad4m.perspective.add("My Space");
128
+ * await perspective.add({
129
+ * source: "did:key:alice",
130
+ * predicate: "knows",
131
+ * target: "did:key:bob"
132
+ * });
133
+ *
134
+ * // Query links
135
+ * const friends = await perspective.get({
136
+ * source: "did:key:alice",
137
+ * predicate: "knows"
138
+ * });
139
+ *
140
+ * // Use Social DNA
141
+ * await perspective.addSdna(todoClass, "subject_class");
142
+ * const todo = await perspective.createSubject("Todo", "expression://123");
17
143
  *
18
- * Convenience object for UIs to interact with a perspective.
19
- * It is created by some of the methods in the PerspectiveClient class and includes
20
- * a reference to the PerspectiveClient object that created it.
144
+ * // Subscribe to changes
145
+ * perspective.addListener("link-added", (link) => {
146
+ * console.log("New link added:", link);
147
+ * });
148
+ * ```
21
149
  */
22
150
  export declare class PerspectiveProxy {
23
151
  #private;
24
- /** Unique ID of the perspective */
152
+ /** Unique identifier of this perspective */
25
153
  uuid: string;
26
- /** Given name of the perspective */
154
+ /** Human-readable name of this perspective */
27
155
  name: string;
28
- /** If the perspective is shared as a Neighbourhood, this is the Neighbourhood URL */
156
+ /** If this perspective is shared as a Neighbourhood, this is its URL */
29
157
  sharedUrl: string | null;
30
- /** If the perspective is shared as a Neighbourhood, this is the Neighbourhood Expression */
158
+ /** If this perspective is shared, this contains the Neighbourhood metadata */
31
159
  neighbourhood: NeighbourhoodExpression | null;
32
- /** Returns the state of the perspective **/
160
+ /** Current sync state if this perspective is shared */
33
161
  state: PerspectiveState | null;
162
+ /**
163
+ * Creates a new PerspectiveProxy instance.
164
+ * Note: Don't create this directly, use ad4m.perspective.add() instead.
165
+ */
34
166
  constructor(handle: PerspectiveHandle, ad4m: PerspectiveClient);
35
- executeAction(actions: any, expression: any, parameters: Parameter[]): Promise<boolean>;
36
- /** Returns all the links of this perspective that matches the LinkQuery */
167
+ /**
168
+ * Executes a set of actions on an expression with optional parameters.
169
+ * Used internally by Social DNA flows and subject class operations.
170
+ *
171
+ * Actions are specified as an array of commands that modify links in the perspective.
172
+ * Each action is an object with the following format:
173
+ * ```typescript
174
+ * {
175
+ * action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
176
+ * source: string, // Usually "this" to reference the current expression
177
+ * predicate: string, // The predicate URI
178
+ * target: string // The target value or "value" for parameters
179
+ * }
180
+ * ```
181
+ *
182
+ * Available commands:
183
+ * - `addLink`: Creates a new link
184
+ * - `removeLink`: Removes an existing link
185
+ * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
186
+ * - `collectionSetter`: Special command for setting collection properties
187
+ *
188
+ * When used with parameters, the special value "value" in the target field will be
189
+ * replaced with the actual parameter value.
190
+ *
191
+ * @example
192
+ * ```typescript
193
+ * // Add a state link and remove an old one
194
+ * await perspective.executeAction([
195
+ * {
196
+ * action: "addLink",
197
+ * source: "this",
198
+ * predicate: "todo://state",
199
+ * target: "todo://doing"
200
+ * },
201
+ * {
202
+ * action: "removeLink",
203
+ * source: "this",
204
+ * predicate: "todo://state",
205
+ * target: "todo://ready"
206
+ * }
207
+ * ], "expression://123");
208
+ *
209
+ * // Set a property using a parameter
210
+ * await perspective.executeAction([
211
+ * {
212
+ * action: "setSingleTarget",
213
+ * source: "this",
214
+ * predicate: "todo://title",
215
+ * target: "value"
216
+ * }
217
+ * ], "expression://123", [
218
+ * { name: "title", value: "New Title" }
219
+ * ]);
220
+ * ```
221
+ *
222
+ * @param actions - Array of action objects to execute
223
+ * @param expression - Target expression address (replaces "this" in actions)
224
+ * @param parameters - Optional parameters that replace "value" in actions
225
+ * @param batchId - Optional batch ID to group this operation with others
226
+ */
227
+ executeAction(actions: any, expression: any, parameters: Parameter[], batchId?: string): Promise<boolean>;
228
+ /**
229
+ * Retrieves links from the perspective that match the given query.
230
+ *
231
+ * @param query - Query parameters to filter links
232
+ * @returns Array of matching LinkExpressions
233
+ *
234
+ * @example
235
+ * ```typescript
236
+ * // Get all links where Alice knows someone
237
+ * const links = await perspective.get({
238
+ * source: "did:key:alice",
239
+ * predicate: "knows"
240
+ * });
241
+ *
242
+ * // Get all comments on a post
243
+ * const comments = await perspective.get({
244
+ * source: "post://123",
245
+ * predicate: "comment"
246
+ * });
247
+ * ```
248
+ */
37
249
  get(query: LinkQuery): Promise<LinkExpression[]>;
38
- /** Runs a Prolog query on the perspective's Prolog engine */
250
+ /**
251
+ * Executes a Prolog query against the perspective's knowledge base.
252
+ * This is a powerful way to find complex patterns in the graph.
253
+ *
254
+ * @param query - Prolog query string
255
+ * @returns Query results or false if no results
256
+ *
257
+ * @example
258
+ * ```typescript
259
+ * // Find friends of friends
260
+ * const results = await perspective.infer(`
261
+ * triple(A, "knows", B),
262
+ * triple(B, "knows", C),
263
+ * A \= C
264
+ * `);
265
+ *
266
+ * // Find all active todos
267
+ * const todos = await perspective.infer(`
268
+ * instance(Todo, "Todo"),
269
+ * property_getter("Todo", Todo, "state", "active")
270
+ * `);
271
+ * ```
272
+ */
39
273
  infer(query: string): Promise<any>;
40
- /** Adds a link to this perspective */
41
- add(link: Link, status?: LinkStatus): Promise<LinkExpression>;
42
- /** Adds multiple links to this perspective **/
43
- addLinks(links: Link[], status?: LinkStatus): Promise<LinkExpression[]>;
44
- /** Removes multiple links from this perspective **/
45
- removeLinks(links: LinkExpressionInput[]): Promise<LinkExpression[]>;
46
- /** Adds and removes multiple links from this perspective **/
274
+ /**
275
+ * Adds a new link to the perspective.
276
+ *
277
+ * @param link - The link to add
278
+ * @param status - Whether the link should be shared in a Neighbourhood
279
+ * @param batchId - Optional batch ID to group this operation with others
280
+ * @returns The created LinkExpression
281
+ *
282
+ * @example
283
+ * ```typescript
284
+ * // Add a simple relationship
285
+ * await perspective.add({
286
+ * source: "did:key:alice",
287
+ * predicate: "follows",
288
+ * target: "did:key:bob"
289
+ * });
290
+ *
291
+ * // Add a local-only link
292
+ * await perspective.add({
293
+ * source: "note://123",
294
+ * predicate: "tag",
295
+ * target: "private"
296
+ * }, "local");
297
+ * ```
298
+ */
299
+ add(link: Link, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
300
+ /**
301
+ * Adds multiple links to the perspective in a single operation.
302
+ * More efficient than adding links one by one.
303
+ *
304
+ * @param links - Array of links to add
305
+ * @param status - Whether the links should be shared
306
+ * @param batchId - Optional batch ID to group this operation with others
307
+ * @returns Array of created LinkExpressions
308
+ */
309
+ addLinks(links: Link[], status?: LinkStatus, batchId?: string): Promise<LinkExpression[]>;
310
+ /**
311
+ * Removes multiple links from the perspective.
312
+ *
313
+ * @param links - Array of links to remove
314
+ * @param batchId - Optional batch ID to group this operation with others
315
+ * @returns Array of removed LinkExpressions
316
+ */
317
+ removeLinks(links: LinkExpressionInput[], batchId?: string): Promise<LinkExpression[]>;
318
+ /**
319
+ * Applies a set of link mutations (adds and removes) in a single operation.
320
+ * Useful for atomic updates to the perspective.
321
+ *
322
+ * @param mutations - Object containing links to add and remove
323
+ * @param status - Whether new links should be shared
324
+ * @returns Object containing results of the mutations
325
+ */
47
326
  linkMutations(mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
48
- /** Adds a linkExpression to this perspective */
49
- addLinkExpression(link: LinkExpression, status?: LinkStatus): Promise<LinkExpression>;
50
- update(oldLink: LinkExpressionInput, newLink: Link): Promise<LinkExpression>;
51
- remove(link: LinkExpressionInput): Promise<{
52
- perspectiveRemoveLink: boolean;
53
- }>;
327
+ /**
328
+ * Adds a pre-signed LinkExpression to the perspective.
329
+ *
330
+ * @param link - The signed LinkExpression to add
331
+ * @param status - Whether the link should be shared
332
+ * @param batchId - Optional batch ID to group this operation with others
333
+ * @returns The added LinkExpression
334
+ */
335
+ addLinkExpression(link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
336
+ /**
337
+ * Updates an existing link with new data.
338
+ *
339
+ * @param oldLink - The existing link to update
340
+ * @param newLink - The new link data
341
+ * @param batchId - Optional batch ID to group this operation with others
342
+ */
343
+ update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
344
+ /**
345
+ * Removes a link from the perspective.
346
+ *
347
+ * @param link - The link to remove
348
+ * @param batchId - Optional batch ID to group this operation with others
349
+ */
350
+ remove(link: LinkExpressionInput, batchId?: string): Promise<boolean>;
351
+ /** Creates a new batch for grouping operations */
352
+ createBatch(): Promise<string>;
353
+ /** Commits a batch of operations */
354
+ commitBatch(batchId: string): Promise<LinkExpressionMutations>;
355
+ /**
356
+ * Retrieves and renders an Expression referenced in this perspective.
357
+ *
358
+ * @param expressionURI - URI of the Expression to retrieve
359
+ * @returns The rendered Expression
360
+ */
54
361
  getExpression(expressionURI: string): Promise<ExpressionRendered>;
362
+ /**
363
+ * Creates a new Expression in the specified Language.
364
+ *
365
+ * @param content - Content for the new Expression
366
+ * @param languageAddress - Address of the Language to use
367
+ * @returns URI of the created Expression
368
+ */
55
369
  createExpression(content: any, languageAddress: string): Promise<string>;
56
- /** Adds a link listener
57
- * @param type Can be 'link-added' or 'link-removed'
58
- * @param cb Callback function that is called when a link is added to the perspective
370
+ /**
371
+ * Subscribes to link changes in the perspective.
372
+ *
373
+ * @param type - Type of change to listen for
374
+ * @param cb - Callback function
375
+ *
376
+ * @example
377
+ * ```typescript
378
+ * // Listen for new links
379
+ * perspective.addListener("link-added", (link) => {
380
+ * console.log("New link:", link);
381
+ * });
382
+ *
383
+ * // Listen for removed links
384
+ * perspective.addListener("link-removed", (link) => {
385
+ * console.log("Link removed:", link);
386
+ * });
387
+ * ```
59
388
  */
60
389
  addListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
61
- /** Adds a sync state listener
62
- * @param cb Callback function that is called when the sync state of the perspective changes
63
- * @returns A function that can be called to remove the listener
390
+ /**
391
+ * Subscribes to sync state changes if this perspective is shared.
392
+ *
393
+ * @param cb - Callback function
394
+ *
395
+ * @example
396
+ * ```typescript
397
+ * perspective.addSyncStateChangeListener((state) => {
398
+ * console.log("Sync state:", state);
399
+ * });
400
+ * ```
64
401
  */
65
402
  addSyncStateChangeListener(cb: SyncStateChangeCallback): Promise<void>;
66
- /** Removes a previously added link listener
67
- * @param type Can be 'link-added' or 'link-removed'
68
- * @param cb Callback function that is called when a link is added to the perspective
403
+ /**
404
+ * Unsubscribes from link changes.
405
+ *
406
+ * @param type - Type of change to stop listening for
407
+ * @param cb - The callback function to remove
69
408
  */
70
409
  removeListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
71
- /** Create and return a snapshot of this perspective
72
- * A snapshot is a rendered Perspectie object that contains all the links of the perspective.
410
+ /**
411
+ * Creates a snapshot of the current perspective state.
412
+ * Useful for backup or sharing.
413
+ *
414
+ * @returns Perspective object containing all links
73
415
  */
74
416
  snapshot(): Promise<Perspective>;
75
- /** Take and load all the links from the given snapshot */
417
+ /**
418
+ * Loads a perspective snapshot, replacing current content.
419
+ *
420
+ * @param snapshot - Perspective snapshot to load
421
+ */
76
422
  loadSnapshot(snapshot: Perspective): Promise<void>;
77
- /** Convenience function to get the target of the first link that matches the given query
78
- * This makes sense when the query is expected to return only one link
79
- * and the target of that link is what you are looking for.
423
+ /**
424
+ * Gets a single target value matching a query.
425
+ * Useful when you expect only one result.
426
+ *
427
+ * @param query - Query to find the target
428
+ * @returns Target value or void if not found
80
429
  *
81
- * Works best together with @member setSingelTarget()
430
+ * @example
431
+ * ```typescript
432
+ * // Get a user's name
433
+ * const name = await perspective.getSingleTarget({
434
+ * source: "did:key:alice",
435
+ * predicate: "name"
436
+ * });
437
+ * ```
82
438
  */
83
439
  getSingleTarget(query: LinkQuery): Promise<string | void>;
84
- /** Convenience function to ensure there is only one link with given source and predicate
85
- * This function will remove all links with the same source and predicate as the given link,
86
- * and then add the given link.
87
- * This ensures there is only one target for the given source and predicate.
440
+ /**
441
+ * Sets a single target value, removing any existing targets.
442
+ *
443
+ * @param link - Link defining the new target
444
+ * @param status - Whether the link should be shared
88
445
  *
89
- * Works best together with @member getSingleTarget()
446
+ * @example
447
+ * ```typescript
448
+ * // Set a user's status
449
+ * await perspective.setSingleTarget({
450
+ * source: "did:key:alice",
451
+ * predicate: "status",
452
+ * target: "online"
453
+ * });
454
+ * ```
90
455
  */
91
456
  setSingleTarget(link: Link, status?: LinkStatus): Promise<void>;
92
457
  /** Returns all the Social DNA flows defined in this perspective */
@@ -111,17 +476,20 @@ export declare class PerspectiveProxy {
111
476
  addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom"): Promise<boolean>;
112
477
  /** Returns all the Subject classes defined in this perspectives SDNA */
113
478
  subjectClasses(): Promise<string[]>;
114
- stringOrTemplateObjectToSubjectClass<T>(subjectClass: T): Promise<string>;
115
- /** Creates a new subject instance by running its (SDNA defined) constructor,
116
- * which means adding links around the given expression address so that it
117
- * conforms to the given subject class.
479
+ stringOrTemplateObjectToSubjectClassName<T>(subjectClass: T): Promise<string>;
480
+ /**
481
+ * Creates a new subject instance of the given subject class
118
482
  *
119
483
  * @param subjectClass Either a string with the name of the subject class, or an object
120
- * with the properties of the subject class. In the latter case, the first subject class
121
- * that matches the given properties will be used.
484
+ * with the properties of the subject class.
122
485
  * @param exprAddr The address of the expression to be turned into a subject instance
486
+ * @param initialValues Optional initial values for properties. If provided, these will be
487
+ * merged with constructor actions for better performance.
488
+ * @param batchId Optional batch ID for grouping operations. If provided, returns the expression address
489
+ * instead of the subject proxy since the subject won't exist until the batch is committed.
490
+ * @returns A proxy object for the created subject, or just the expression address if in batch mode
123
491
  */
124
- createSubject<T>(subjectClass: T, exprAddr: string): Promise<T>;
492
+ createSubject<T, B extends string | undefined = undefined>(subjectClass: T, exprAddr: string, initialValues?: Record<string, any>, batchId?: B): Promise<B extends undefined ? T : string>;
125
493
  getSubjectData<T>(subjectClass: T, exprAddr: string): Promise<T>;
126
494
  /** Removes a subject instance by running its (SDNA defined) destructor,
127
495
  * which means removing links around the given expression address
@@ -130,8 +498,10 @@ export declare class PerspectiveProxy {
130
498
  * with the properties of the subject class. In the latter case, the first subject class
131
499
  * that matches the given properties will be used.
132
500
  * @param exprAddr The address of the expression to be turned into a subject instance
501
+ * @param batchId Optional batch ID for grouping operations. If provided, the removal will be part of the batch
502
+ * and won't be executed until the batch is committed.
133
503
  */
134
- removeSubject<T>(subjectClass: T, exprAddr: string): Promise<void>;
504
+ removeSubject<T>(subjectClass: T, exprAddr: string, batchId?: string): Promise<void>;
135
505
  /** Checks if the given expression is a subject instance of the given subject class
136
506
  * @param expression The expression to be checked
137
507
  * @param subjectClass Either a string with the name of the subject class, or an object
@@ -182,6 +552,53 @@ export declare class PerspectiveProxy {
182
552
  */
183
553
  ensureSDNASubjectClass(jsClass: any): Promise<void>;
184
554
  getNeighbourhoodProxy(): NeighbourhoodProxy;
555
+ /**
556
+ * Returns a proxy object for working with AI capabilities.
557
+ *
558
+ * @returns AIClient instance
559
+ *
560
+ * @example
561
+ * ```typescript
562
+ * // Use AI to analyze perspective content
563
+ * const summary = await perspective.ai.summarize();
564
+ *
565
+ * // Generate new content
566
+ * const suggestion = await perspective.ai.suggest("next action");
567
+ * ```
568
+ */
185
569
  get ai(): AIClient;
570
+ /**
571
+ * Creates a subscription for a Prolog query that updates in real-time.
572
+ *
573
+ * This method:
574
+ * 1. Creates the subscription on the Rust side
575
+ * 2. Sets up the subscription callback
576
+ * 3. Waits for the initial result to come through the subscription channel
577
+ * 4. Returns a fully initialized QuerySubscriptionProxy
578
+ *
579
+ * The returned subscription is guaranteed to be ready to receive updates,
580
+ * as this method waits for the initialization process to complete.
581
+ *
582
+ * @param query - Prolog query string
583
+ * @returns Initialized QuerySubscriptionProxy instance
584
+ *
585
+ * @example
586
+ * ```typescript
587
+ * // Subscribe to active todos
588
+ * const subscription = await perspective.subscribeInfer(`
589
+ * instance(Todo, "Todo"),
590
+ * property_getter("Todo", Todo, "state", "active")
591
+ * `);
592
+ *
593
+ * // Subscription is already initialized here
594
+ * console.log("Initial result:", subscription.result);
595
+ *
596
+ * // Set up callback for future updates
597
+ * subscription.onResult((todos) => {
598
+ * console.log("Active todos:", todos);
599
+ * });
600
+ * ```
601
+ */
602
+ subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
186
603
  }
187
604
  export {};