xmemory 3.2.1 → 3.3.0
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/README.md +29 -4
- package/dist/index.d.ts +1 -0
- package/dist/instance.d.ts +16 -1
- package/dist/instance.js +22 -16
- package/dist/types.d.ts +80 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -115,9 +115,9 @@ Get a handle to an instance and use it for reads, writes, and extractions.
|
|
|
115
115
|
const inst = xm.instance("<instance-id>");
|
|
116
116
|
```
|
|
117
117
|
|
|
118
|
-
### `inst.write(text, options?)` → `WriteResult`
|
|
118
|
+
### `inst.write(text | mutations, options?)` → `WriteResult`
|
|
119
119
|
|
|
120
|
-
Extract and store structured objects from text
|
|
120
|
+
Extract and store structured objects from text:
|
|
121
121
|
|
|
122
122
|
```typescript
|
|
123
123
|
const result = await inst.write("Bob is a designer based in Berlin.");
|
|
@@ -127,9 +127,34 @@ console.log(result.changes); // what the write created / updated / deleted
|
|
|
127
127
|
|
|
128
128
|
Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"fast"`.
|
|
129
129
|
|
|
130
|
-
|
|
130
|
+
Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
|
|
131
|
+
create/update/delete mutations applied in array order (later mutations may
|
|
132
|
+
reference objects created earlier in the batch; a `null` value in `values`
|
|
133
|
+
clears that field):
|
|
131
134
|
|
|
132
|
-
|
|
135
|
+
```typescript
|
|
136
|
+
const result = await inst.write([
|
|
137
|
+
{
|
|
138
|
+
object_mutation: {
|
|
139
|
+
object_type: "person",
|
|
140
|
+
create: { key: { name: "Bob" }, values: { role: "designer" } },
|
|
141
|
+
},
|
|
142
|
+
},
|
|
143
|
+
{
|
|
144
|
+
object_mutation: {
|
|
145
|
+
object_type: "person",
|
|
146
|
+
update: { key: { name: "Bob" }, values: { role: null } }, // null clears
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
]);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply).
|
|
153
|
+
|
|
154
|
+
### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
|
|
155
|
+
|
|
156
|
+
Start an asynchronous write (same text / `WriteMutation[]` dual input as
|
|
157
|
+
`inst.write`). Returns a `write_id` for tracking.
|
|
133
158
|
|
|
134
159
|
```typescript
|
|
135
160
|
const { write_id } = await inst.writeAsync("Carol manages the London office.");
|
package/dist/index.d.ts
CHANGED
|
@@ -10,5 +10,6 @@ export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, Fiel
|
|
|
10
10
|
export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
|
|
11
11
|
export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
|
|
12
12
|
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
|
|
13
14
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
14
15
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/instance.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* InstanceHandle — scoped data operations on a single xmemory instance.
|
|
3
3
|
*/
|
|
4
|
-
import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
|
|
4
|
+
import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteMutation, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
|
|
5
5
|
export declare class DescribeResult {
|
|
6
6
|
readonly instanceId: string;
|
|
7
7
|
readonly instanceName: string;
|
|
@@ -32,8 +32,23 @@ export declare class InstanceHandle {
|
|
|
32
32
|
private _describeTtlMs;
|
|
33
33
|
constructor(id: string, requestOne: RequestOneFn);
|
|
34
34
|
read(query: string, options?: ReadOptions): Promise<ReadResult>;
|
|
35
|
+
/**
|
|
36
|
+
* Write to this instance: extract from free text, or apply structured
|
|
37
|
+
* mutations. Pass a string to extract structured data from free-form text,
|
|
38
|
+
* or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
|
|
39
|
+
* delete edits (applied in array order; later mutations may reference
|
|
40
|
+
* objects created earlier in the batch, and a `null` value in a mutation's
|
|
41
|
+
* `values` clears that field). `extractionLogic` / `diffEngine` only apply
|
|
42
|
+
* to the text form.
|
|
43
|
+
*/
|
|
35
44
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
45
|
+
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
46
|
+
/**
|
|
47
|
+
* Submit a write job and return immediately with a `write_id` for polling.
|
|
48
|
+
* Accepts the same text / `WriteMutation[]` dual input as {@link write}.
|
|
49
|
+
*/
|
|
36
50
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
51
|
+
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
37
52
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
38
53
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
|
39
54
|
getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
|
package/dist/instance.js
CHANGED
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* InstanceHandle — scoped data operations on a single xmemory instance.
|
|
3
3
|
*/
|
|
4
|
+
/** Build the shared `/write` + `/write_async` request body for either input mode. */
|
|
5
|
+
function buildWriteBody(input, options) {
|
|
6
|
+
if (typeof input !== "string") {
|
|
7
|
+
if (input.length === 0) {
|
|
8
|
+
throw new Error("structured write requires at least one mutation");
|
|
9
|
+
}
|
|
10
|
+
// Structured path: no text, no extraction options — mutations go straight
|
|
11
|
+
// to the wire.
|
|
12
|
+
return { structured_mutations: input };
|
|
13
|
+
}
|
|
14
|
+
const body = {
|
|
15
|
+
text: input,
|
|
16
|
+
extraction_logic: options?.extractionLogic ?? "fast",
|
|
17
|
+
};
|
|
18
|
+
if (options?.diffEngine != null)
|
|
19
|
+
body.use_diff_engine = options.diffEngine;
|
|
20
|
+
return body;
|
|
21
|
+
}
|
|
4
22
|
const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
|
|
5
23
|
export class DescribeResult {
|
|
6
24
|
instanceId;
|
|
@@ -136,27 +154,15 @@ export class InstanceHandle {
|
|
|
136
154
|
});
|
|
137
155
|
return { ...result, reader_results: result.reader_results ?? [] };
|
|
138
156
|
}
|
|
139
|
-
async write(
|
|
140
|
-
const body = {
|
|
141
|
-
text,
|
|
142
|
-
extraction_logic: options?.extractionLogic ?? "fast",
|
|
143
|
-
};
|
|
144
|
-
if (options?.diffEngine != null)
|
|
145
|
-
body.diff_engine = options.diffEngine;
|
|
157
|
+
async write(input, options) {
|
|
146
158
|
return this._requestOne("POST", `/instances/${this.id}/write`, {
|
|
147
|
-
body,
|
|
159
|
+
body: buildWriteBody(input, options),
|
|
148
160
|
timeoutMs: options?.timeoutMs,
|
|
149
161
|
});
|
|
150
162
|
}
|
|
151
|
-
async writeAsync(
|
|
152
|
-
const body = {
|
|
153
|
-
text,
|
|
154
|
-
extraction_logic: options?.extractionLogic ?? "fast",
|
|
155
|
-
};
|
|
156
|
-
if (options?.diffEngine != null)
|
|
157
|
-
body.diff_engine = options.diffEngine;
|
|
163
|
+
async writeAsync(input, options) {
|
|
158
164
|
return this._requestOne("POST", `/instances/${this.id}/write_async`, {
|
|
159
|
-
body,
|
|
165
|
+
body: buildWriteBody(input, options),
|
|
160
166
|
timeoutMs: options?.timeoutMs,
|
|
161
167
|
});
|
|
162
168
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -157,6 +157,86 @@ export interface ExtractResult {
|
|
|
157
157
|
export interface GenerateSchemaResult {
|
|
158
158
|
readonly data_schema: Record<string, unknown>;
|
|
159
159
|
}
|
|
160
|
+
export interface RelationEndpoint {
|
|
161
|
+
/** Relation role name from the instance schema. */
|
|
162
|
+
object_name: string;
|
|
163
|
+
/** Endpoint identity: user primary-key fields (field -> value), or `{ xuid: ... }`. */
|
|
164
|
+
key?: Record<string, unknown>;
|
|
165
|
+
}
|
|
166
|
+
/** Create an object: `key` holds the user primary-key fields (no `xuid` — it is
|
|
167
|
+
* generated server-side), `values` the remaining field values. */
|
|
168
|
+
export interface ObjectCreatePayload {
|
|
169
|
+
key?: Record<string, unknown>;
|
|
170
|
+
values?: Record<string, unknown>;
|
|
171
|
+
}
|
|
172
|
+
/** Update an object identified by `key` (primary-key fields or `{ xuid: ... }`).
|
|
173
|
+
* A `null` value in `values` clears that field. */
|
|
174
|
+
export interface ObjectUpdatePayload {
|
|
175
|
+
key: Record<string, unknown>;
|
|
176
|
+
values: Record<string, unknown>;
|
|
177
|
+
}
|
|
178
|
+
/** Delete the object identified by `key` (primary-key fields or `{ xuid: ... }`). */
|
|
179
|
+
export interface ObjectDeletePayload {
|
|
180
|
+
key: Record<string, unknown>;
|
|
181
|
+
}
|
|
182
|
+
/** Create a relation between the `endpoints`, with optional own-field `values`. */
|
|
183
|
+
export interface RelationCreatePayload {
|
|
184
|
+
endpoints: RelationEndpoint[];
|
|
185
|
+
values?: Record<string, unknown>;
|
|
186
|
+
}
|
|
187
|
+
/** Update a relation's own fields. Address it by `endpoints`, or by
|
|
188
|
+
* `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
|
|
189
|
+
* clears that field. */
|
|
190
|
+
export interface RelationUpdatePayload {
|
|
191
|
+
key?: Record<string, unknown>;
|
|
192
|
+
endpoints?: RelationEndpoint[];
|
|
193
|
+
values: Record<string, unknown>;
|
|
194
|
+
}
|
|
195
|
+
/** Delete relation(s) matched by `endpoints` (a subset is allowed) or by
|
|
196
|
+
* `key: { xuid: ... }`. Deleting more than one matched row requires
|
|
197
|
+
* `allow_bulk_delete: true`. */
|
|
198
|
+
export interface RelationDeletePayload {
|
|
199
|
+
key?: Record<string, unknown>;
|
|
200
|
+
endpoints?: RelationEndpoint[];
|
|
201
|
+
allow_bulk_delete?: boolean;
|
|
202
|
+
}
|
|
203
|
+
export type ObjectMutationBody = {
|
|
204
|
+
object_type: string;
|
|
205
|
+
} & ({
|
|
206
|
+
create: ObjectCreatePayload;
|
|
207
|
+
update?: never;
|
|
208
|
+
delete?: never;
|
|
209
|
+
} | {
|
|
210
|
+
update: ObjectUpdatePayload;
|
|
211
|
+
create?: never;
|
|
212
|
+
delete?: never;
|
|
213
|
+
} | {
|
|
214
|
+
delete: ObjectDeletePayload;
|
|
215
|
+
create?: never;
|
|
216
|
+
update?: never;
|
|
217
|
+
});
|
|
218
|
+
export type RelationMutationBody = {
|
|
219
|
+
relation_type: string;
|
|
220
|
+
} & ({
|
|
221
|
+
create: RelationCreatePayload;
|
|
222
|
+
update?: never;
|
|
223
|
+
delete?: never;
|
|
224
|
+
} | {
|
|
225
|
+
update: RelationUpdatePayload;
|
|
226
|
+
create?: never;
|
|
227
|
+
delete?: never;
|
|
228
|
+
} | {
|
|
229
|
+
delete: RelationDeletePayload;
|
|
230
|
+
create?: never;
|
|
231
|
+
update?: never;
|
|
232
|
+
});
|
|
233
|
+
export type WriteMutation = {
|
|
234
|
+
object_mutation: ObjectMutationBody;
|
|
235
|
+
relation_mutation?: never;
|
|
236
|
+
} | {
|
|
237
|
+
relation_mutation: RelationMutationBody;
|
|
238
|
+
object_mutation?: never;
|
|
239
|
+
};
|
|
160
240
|
export type FieldType = "str" | "string" | "int" | "integer" | "float" | "bool" | "boolean";
|
|
161
241
|
export type OnDelete = "nullify" | "cascade";
|
|
162
242
|
export type CastStrategy = "safe_implicit" | "explicit_using" | "lossy";
|