@gcszhn/mol4agent-core 0.2.0 → 0.4.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 +200 -19
- package/README_zh.md +181 -16
- package/lib/color.d.ts +33 -0
- package/lib/color.js +288 -0
- package/lib/index.d.ts +2 -1
- package/lib/index.js +2 -1
- package/lib/inspect-mol.d.ts +28 -0
- package/lib/inspect-mol.js +103 -0
- package/lib/inspect-plugin.d.ts +22 -0
- package/lib/inspect-plugin.js +339 -0
- package/lib/inspect.d.ts +88 -0
- package/lib/inspect.js +189 -0
- package/lib/protocol.d.ts +283 -16
- package/lib/protocol.js +36 -0
- package/lib/represent.d.ts +25 -0
- package/lib/represent.js +191 -0
- package/lib/select.d.ts +12 -0
- package/lib/select.js +41 -1
- package/lib/viewer.d.ts +41 -4
- package/lib/viewer.js +502 -181
- package/package.json +4 -2
package/lib/protocol.d.ts
CHANGED
|
@@ -21,6 +21,18 @@ export type RepresentationType = (typeof REPRESENTATION_TYPES)[number];
|
|
|
21
21
|
/** Colour themes known to be useful for agent-driven views. */
|
|
22
22
|
export declare const COLOR_THEMES: readonly ["chain-id", "element-symbol", "residue-name", "uniform", "secondary-structure", "entity-id", "molecule-type", "hydrophobicity"];
|
|
23
23
|
export type ColorTheme = (typeof COLOR_THEMES)[number];
|
|
24
|
+
/** Alignment algorithms exposed to agents. */
|
|
25
|
+
export declare const ALIGNMENT_METHODS: readonly ["tm-align", "sequence"];
|
|
26
|
+
export type AlignmentMethod = (typeof ALIGNMENT_METHODS)[number];
|
|
27
|
+
/**
|
|
28
|
+
* Stable identifier for one structure in a viewer scene.
|
|
29
|
+
*
|
|
30
|
+
* IDs are deliberately URL/JSON friendly so they can travel through every
|
|
31
|
+
* adapter and be echoed by a model: 1-64 characters, starting with a letter or
|
|
32
|
+
* digit, then letters, digits, `.`, `_` or `-`.
|
|
33
|
+
*/
|
|
34
|
+
export declare const STRUCTURE_ID_PATTERN: RegExp;
|
|
35
|
+
export declare function isStructureId(value: unknown): value is string;
|
|
24
36
|
/**
|
|
25
37
|
* Bytes plus the explicit format the adapter selected for them.
|
|
26
38
|
*
|
|
@@ -59,14 +71,15 @@ export interface ElementSchema {
|
|
|
59
71
|
readonly auth_atom_id?: string;
|
|
60
72
|
readonly type_symbol?: string;
|
|
61
73
|
}
|
|
62
|
-
/**
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
74
|
+
/** Fields that scope a selector to one structure in a multi-structure scene. */
|
|
75
|
+
export type StructureSelectorScope = {
|
|
76
|
+
/**
|
|
77
|
+
* Structure id returned by `load`/`addStructure` (or the adapters' tools).
|
|
78
|
+
* Omitted means "every loaded structure", matching single-structure scenes.
|
|
79
|
+
*/
|
|
80
|
+
readonly structureId?: string;
|
|
81
|
+
};
|
|
82
|
+
type StructureSelectorBody = {
|
|
70
83
|
readonly kind: 'all';
|
|
71
84
|
} | {
|
|
72
85
|
readonly kind: 'polymer';
|
|
@@ -101,6 +114,201 @@ export type StructureSelector = {
|
|
|
101
114
|
readonly kind: 'schema';
|
|
102
115
|
readonly schema: ElementSchema;
|
|
103
116
|
};
|
|
117
|
+
/**
|
|
118
|
+
* A selection an agent can express without knowing atom indices.
|
|
119
|
+
*
|
|
120
|
+
* Adapters pass these through unchanged; core compiles them to Mol* selection
|
|
121
|
+
* queries or schemas. This shape is the stable part of the agent-facing
|
|
122
|
+
* contract, so adding a variant is a protocol change. `structureId` disambiguates
|
|
123
|
+
* chains with the same id in different loaded structures.
|
|
124
|
+
*/
|
|
125
|
+
export type StructureSelector = StructureSelectorBody & StructureSelectorScope;
|
|
126
|
+
/**
|
|
127
|
+
* How much detail one inspection returns.
|
|
128
|
+
*
|
|
129
|
+
* `summary` reports totals, per-component counts, and styles but no rows;
|
|
130
|
+
* `residues` adds residue rows, and `atoms` adds per-atom rows inside them.
|
|
131
|
+
*/
|
|
132
|
+
export declare const INSPECT_DETAILS: readonly ["summary", "residues", "atoms"];
|
|
133
|
+
export type InspectDetail = (typeof INSPECT_DETAILS)[number];
|
|
134
|
+
/** Row budget for one inspection result; counts always cover the full target. */
|
|
135
|
+
export declare const DEFAULT_INSPECT_LIMIT = 200;
|
|
136
|
+
/**
|
|
137
|
+
* What an inspection describes.
|
|
138
|
+
*
|
|
139
|
+
* Selectors name structure content; `selection` and `focus` name the viewer's
|
|
140
|
+
* live state, which only Mol* knows: `selection` is the selection manager
|
|
141
|
+
* (what a human selected by clicking, or what `mol_select` set) and `focus` is
|
|
142
|
+
* the structure focus entry the Mol* UI keeps for the last clicked location.
|
|
143
|
+
*/
|
|
144
|
+
export type InspectTarget = StructureSelector | {
|
|
145
|
+
readonly kind: 'selection';
|
|
146
|
+
} | {
|
|
147
|
+
readonly kind: 'focus';
|
|
148
|
+
};
|
|
149
|
+
/**
|
|
150
|
+
* One read-only query about the loaded structure and the way Mol* draws it.
|
|
151
|
+
*
|
|
152
|
+
* Unlike {@link MolCommand} this changes nothing and is never replayed: it
|
|
153
|
+
* samples the viewer as it is right now, so answers include human-driven
|
|
154
|
+
* changes (clicked selection, panel styles) that never reached the session log.
|
|
155
|
+
*/
|
|
156
|
+
export interface InspectRequest {
|
|
157
|
+
/** Defaults to the whole structure. */
|
|
158
|
+
readonly target?: InspectTarget;
|
|
159
|
+
/** Defaults to `summary`. */
|
|
160
|
+
readonly detail?: InspectDetail;
|
|
161
|
+
/** Maximum residue rows to return. Defaults to {@link DEFAULT_INSPECT_LIMIT}. */
|
|
162
|
+
readonly limit?: number;
|
|
163
|
+
}
|
|
164
|
+
/** Coarse classification shared with {@link ChainSummary}. */
|
|
165
|
+
export type InspectKind = 'polymer' | 'ligand' | 'water' | 'ion' | 'other';
|
|
166
|
+
export interface InspectVector {
|
|
167
|
+
readonly x: number;
|
|
168
|
+
readonly y: number;
|
|
169
|
+
readonly z: number;
|
|
170
|
+
}
|
|
171
|
+
/** One atom as Mol* currently places it. */
|
|
172
|
+
export interface InspectAtom extends InspectVector {
|
|
173
|
+
readonly name: string;
|
|
174
|
+
readonly element: string;
|
|
175
|
+
readonly occupancy?: number;
|
|
176
|
+
readonly bFactor?: number;
|
|
177
|
+
readonly altId?: string;
|
|
178
|
+
}
|
|
179
|
+
/** One residue as Mol* currently models it, with its drawn centre. */
|
|
180
|
+
export interface InspectResidue extends InspectVector {
|
|
181
|
+
readonly chain: string;
|
|
182
|
+
readonly seqId: number;
|
|
183
|
+
readonly labelSeqId: number;
|
|
184
|
+
readonly compId: string;
|
|
185
|
+
readonly kind: InspectKind;
|
|
186
|
+
readonly atoms: number;
|
|
187
|
+
/** Present when the request asked for `atoms` detail. */
|
|
188
|
+
readonly atomRows?: readonly InspectAtom[];
|
|
189
|
+
}
|
|
190
|
+
/** Where an overlay that changes the drawn colour comes from. */
|
|
191
|
+
export type InspectOverlaySource = 'selection' | 'overpaint';
|
|
192
|
+
/**
|
|
193
|
+
* One colour layer drawn on top of a representation's own theme colour.
|
|
194
|
+
*
|
|
195
|
+
* `selection` is the canvas marker that tints selected elements (colour and
|
|
196
|
+
* strength come from `canvas3d.props.renderer`); `overpaint` is a per-region
|
|
197
|
+
* colour override stored as a transform on the representation.
|
|
198
|
+
*/
|
|
199
|
+
export interface InspectOverlay {
|
|
200
|
+
readonly source: InspectOverlaySource;
|
|
201
|
+
/** Colour the overlay paints with, as `#rrggbb`. */
|
|
202
|
+
readonly color?: string;
|
|
203
|
+
/** Blend strength when the overlay mixes with the colour below it instead of replacing it. */
|
|
204
|
+
readonly strength?: number;
|
|
205
|
+
/** What the overlay is applied to, e.g. the representation type or a selection entry. */
|
|
206
|
+
readonly label?: string;
|
|
207
|
+
/** True when the overlay exists but does not change the visible body colour. */
|
|
208
|
+
readonly hidden?: boolean;
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* How the inspected element actually looks, versus how its representation
|
|
212
|
+
* alone would colour it.
|
|
213
|
+
*
|
|
214
|
+
* Precedence: overpaint replaces the theme colour, then the selection marker
|
|
215
|
+
* mixes on top of that; `visibleColor` is the result for one matched element.
|
|
216
|
+
*/
|
|
217
|
+
export interface InspectAppearance {
|
|
218
|
+
/** Colour from the representation's own colour theme. */
|
|
219
|
+
readonly baseColor?: string;
|
|
220
|
+
/** Colour actually visible after overlays. */
|
|
221
|
+
readonly visibleColor?: string;
|
|
222
|
+
readonly overlays: readonly InspectOverlay[];
|
|
223
|
+
}
|
|
224
|
+
/** How one representation currently draws the inspected target. */
|
|
225
|
+
export interface InspectStyle {
|
|
226
|
+
/** Mol* component label the representation belongs to. */
|
|
227
|
+
readonly component: string;
|
|
228
|
+
/** Representation type, e.g. `cartoon` or `ball-and-stick`. */
|
|
229
|
+
readonly type: string;
|
|
230
|
+
/** Colour theme name, e.g. `chain-id` or `uniform`. */
|
|
231
|
+
readonly color: string;
|
|
232
|
+
/** Size theme name, e.g. `physical` or `uniform`. */
|
|
233
|
+
readonly size: string;
|
|
234
|
+
readonly colorParams?: Readonly<Record<string, string | number | boolean>>;
|
|
235
|
+
/** True when Mol* is not drawing this representation (hidden component or representation). */
|
|
236
|
+
readonly hidden?: boolean;
|
|
237
|
+
/** Colour the representation's own theme gives the inspected element. */
|
|
238
|
+
readonly baseColor?: string;
|
|
239
|
+
/** Colour visible for the inspected element after the overlays below. */
|
|
240
|
+
readonly visibleColor?: string;
|
|
241
|
+
/** Overlays that apply to the inspected element in this representation. */
|
|
242
|
+
readonly overlays?: readonly InspectOverlay[];
|
|
243
|
+
}
|
|
244
|
+
/** Residue/atom totals for one component id inside the inspected target. */
|
|
245
|
+
export interface InspectCount {
|
|
246
|
+
readonly compId: string;
|
|
247
|
+
readonly kind: InspectKind;
|
|
248
|
+
readonly residues: number;
|
|
249
|
+
readonly atoms: number;
|
|
250
|
+
}
|
|
251
|
+
/** Totals for one selection entry. */
|
|
252
|
+
export interface InspectSelectionGroup {
|
|
253
|
+
readonly atoms: number;
|
|
254
|
+
readonly residues: number;
|
|
255
|
+
/** Entry label Mol* keeps for the selection, when it has one. */
|
|
256
|
+
readonly label?: string;
|
|
257
|
+
}
|
|
258
|
+
/** Totals for one live selection, plus one row per entry. */
|
|
259
|
+
export interface InspectSelection {
|
|
260
|
+
readonly entries: number;
|
|
261
|
+
/** Union totals: entries may overlap. */
|
|
262
|
+
readonly atoms: number;
|
|
263
|
+
readonly residues: number;
|
|
264
|
+
readonly groups?: readonly InspectSelectionGroup[];
|
|
265
|
+
}
|
|
266
|
+
/** Result of one {@link InspectRequest}. */
|
|
267
|
+
export interface InspectResult {
|
|
268
|
+
/** What was inspected, e.g. `whole structure` or `residue E71`. */
|
|
269
|
+
readonly target: string;
|
|
270
|
+
readonly detail: InspectDetail;
|
|
271
|
+
readonly atoms: number;
|
|
272
|
+
readonly residues: number;
|
|
273
|
+
readonly chains: number;
|
|
274
|
+
readonly models: number;
|
|
275
|
+
/** Per component id totals, always complete regardless of the row budget. */
|
|
276
|
+
readonly counts: readonly InspectCount[];
|
|
277
|
+
/** Residue rows; present for `residues` and `atoms` detail. */
|
|
278
|
+
readonly residueRows?: readonly InspectResidue[];
|
|
279
|
+
/** Representations drawing the target, with their colour and style. */
|
|
280
|
+
readonly styles: readonly InspectStyle[];
|
|
281
|
+
/**
|
|
282
|
+
* Effective look of the target: the last drawn style plus its overlays.
|
|
283
|
+
*
|
|
284
|
+
* Absent when the target matches nothing, so an empty selection carries no
|
|
285
|
+
* appearance section.
|
|
286
|
+
*/
|
|
287
|
+
readonly appearance?: InspectAppearance;
|
|
288
|
+
/** Live selection totals, when anything is selected. */
|
|
289
|
+
readonly selection?: InspectSelection;
|
|
290
|
+
/** Live focus totals, when the viewer has a focused location. */
|
|
291
|
+
readonly focus?: InspectSelection;
|
|
292
|
+
/** True when the row budget dropped rows; counts and totals stay complete. */
|
|
293
|
+
readonly truncated: boolean;
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Draw one style, replacing or overlaying what is already shown.
|
|
297
|
+
*
|
|
298
|
+
* `target` only narrows which part of the structure the new representation
|
|
299
|
+
* covers; it never implies replace or add. `replace` defaults to `true`.
|
|
300
|
+
*/
|
|
301
|
+
export interface RepresentCommand {
|
|
302
|
+
readonly op: 'represent';
|
|
303
|
+
readonly style: StyleSpec;
|
|
304
|
+
readonly target?: StructureSelector;
|
|
305
|
+
/**
|
|
306
|
+
* `true` (default): remove the existing representations in the command's
|
|
307
|
+
* scope, then draw the new one. `target` narrows only the new
|
|
308
|
+
* representation's coverage. `false`: keep them and add the new one.
|
|
309
|
+
*/
|
|
310
|
+
readonly replace?: boolean;
|
|
311
|
+
}
|
|
104
312
|
/**
|
|
105
313
|
* One replayable viewer command.
|
|
106
314
|
*
|
|
@@ -108,11 +316,7 @@ export type StructureSelector = {
|
|
|
108
316
|
* be serializable (Codex). Commands only describe changes to an already-loaded
|
|
109
317
|
* structure, so an adapter can store them in a session log and replay them.
|
|
110
318
|
*/
|
|
111
|
-
export type MolCommand = {
|
|
112
|
-
readonly op: 'represent';
|
|
113
|
-
readonly style: StyleSpec;
|
|
114
|
-
readonly target?: StructureSelector;
|
|
115
|
-
} | {
|
|
319
|
+
export type MolCommand = RepresentCommand | {
|
|
116
320
|
readonly op: 'select';
|
|
117
321
|
readonly target: StructureSelector;
|
|
118
322
|
readonly mode?: 'select' | 'highlight';
|
|
@@ -128,7 +332,7 @@ export type MolCommand = {
|
|
|
128
332
|
readonly action: 'reset';
|
|
129
333
|
} | {
|
|
130
334
|
readonly op: 'background';
|
|
131
|
-
readonly color: string | 'theme';
|
|
335
|
+
readonly color: string | number | 'theme';
|
|
132
336
|
} | {
|
|
133
337
|
readonly op: 'measure';
|
|
134
338
|
readonly kind: 'distance' | 'angle' | 'dihedral';
|
|
@@ -137,8 +341,24 @@ export type MolCommand = {
|
|
|
137
341
|
readonly op: 'label';
|
|
138
342
|
readonly target: StructureSelector;
|
|
139
343
|
readonly text?: string;
|
|
344
|
+
} | {
|
|
345
|
+
readonly op: 'remove-structure';
|
|
346
|
+
readonly structureId: string;
|
|
347
|
+
} | {
|
|
348
|
+
readonly op: 'visibility';
|
|
349
|
+
readonly structureId: string;
|
|
350
|
+
readonly visible: boolean;
|
|
351
|
+
} | {
|
|
352
|
+
readonly op: 'align';
|
|
353
|
+
readonly reference: string;
|
|
354
|
+
readonly target: string;
|
|
355
|
+
readonly method?: AlignmentMethod;
|
|
356
|
+
/** Restrict the reference alignment to one chain (auth_asym_id). */
|
|
357
|
+
readonly referenceChain?: string;
|
|
358
|
+
/** Restrict the target alignment to one chain (auth_asym_id). */
|
|
359
|
+
readonly targetChain?: string;
|
|
140
360
|
};
|
|
141
|
-
export type Mol4AgentErrorCode = 'INVALID_COMMAND' | 'UNSUPPORTED_FORMAT' | 'UNSUPPORTED_REPRESENTATION' | 'REPRESENT_FAILED' | 'NO_STRUCTURE' | 'LOAD_FAILED' | 'CAPTURE_FAILED' | 'UNSUPPORTED_SOURCE' | 'INVALID_ENTRY_ID' | 'SUMMARY_UNSUPPORTED' | 'DISPOSED';
|
|
361
|
+
export type Mol4AgentErrorCode = 'INVALID_COMMAND' | 'UNSUPPORTED_FORMAT' | 'UNSUPPORTED_REPRESENTATION' | 'REPRESENT_FAILED' | 'NO_STRUCTURE' | 'LOAD_FAILED' | 'CAPTURE_FAILED' | 'UNSUPPORTED_SOURCE' | 'INVALID_ENTRY_ID' | 'SUMMARY_UNSUPPORTED' | 'DISPOSED' | 'UNKNOWN_STRUCTURE' | 'DUPLICATE_STRUCTURE_ID' | 'ALIGN_FAILED' | 'TM_SCORE_FAILED';
|
|
142
362
|
/** Structured failure. Tools turn this into model-facing text instead of a stack trace. */
|
|
143
363
|
export declare class Mol4AgentError extends Error {
|
|
144
364
|
readonly code: Mol4AgentErrorCode;
|
|
@@ -179,14 +399,61 @@ export interface StructureSummary {
|
|
|
179
399
|
/** False when the adapter's format can be rendered but not summarized from bytes (e.g. BCIF). */
|
|
180
400
|
readonly complete: boolean;
|
|
181
401
|
}
|
|
402
|
+
/** One structure currently displayed in a viewer scene. */
|
|
403
|
+
export interface LoadedStructure {
|
|
404
|
+
readonly id: string;
|
|
405
|
+
readonly label?: string;
|
|
406
|
+
readonly format: MolFormat;
|
|
407
|
+
readonly summary: StructureSummary;
|
|
408
|
+
}
|
|
409
|
+
/** Metrics returned by the `align` command. */
|
|
410
|
+
export interface AlignmentResult {
|
|
411
|
+
readonly method: AlignmentMethod;
|
|
412
|
+
readonly reference: string;
|
|
413
|
+
readonly target: string;
|
|
414
|
+
/** Root-mean-square deviation of the aligned atoms, in angstroms. */
|
|
415
|
+
readonly rmsd: number;
|
|
416
|
+
/** Number of aligned residues/atoms used by the algorithm. */
|
|
417
|
+
readonly alignedLength: number;
|
|
418
|
+
/** TM-align only: TM-score normalized by the reference length. */
|
|
419
|
+
readonly tmScoreA?: number;
|
|
420
|
+
/** TM-align only: TM-score normalized by the target length. */
|
|
421
|
+
readonly tmScoreB?: number;
|
|
422
|
+
}
|
|
423
|
+
/** Two selections to compare without moving either one. */
|
|
424
|
+
export interface TmScoreRequest {
|
|
425
|
+
readonly reference: StructureSelector;
|
|
426
|
+
readonly target: StructureSelector;
|
|
427
|
+
}
|
|
428
|
+
/** TM-align metrics for two selections. Nothing is transformed. */
|
|
429
|
+
export interface TmScoreResult {
|
|
430
|
+
readonly method: 'tm-align';
|
|
431
|
+
/** Human-readable selector descriptions. */
|
|
432
|
+
readonly reference: string;
|
|
433
|
+
readonly target: string;
|
|
434
|
+
/** RMSD after optimal superposition of the aligned trace atoms, in angstroms. */
|
|
435
|
+
readonly rmsd: number;
|
|
436
|
+
readonly tmScoreA: number;
|
|
437
|
+
readonly tmScoreB: number;
|
|
438
|
+
readonly alignedLength: number;
|
|
439
|
+
readonly referenceAtoms: number;
|
|
440
|
+
readonly targetAtoms: number;
|
|
441
|
+
}
|
|
182
442
|
export interface CaptureOptions {
|
|
183
443
|
readonly width?: number;
|
|
184
444
|
readonly height?: number;
|
|
185
445
|
readonly transparent?: boolean;
|
|
186
|
-
readonly background?: string;
|
|
446
|
+
readonly background?: string | number;
|
|
187
447
|
}
|
|
188
448
|
/** Narrow a parsed JSON value to a command op without validating every field. */
|
|
189
449
|
export declare function isMolCommandOp(value: unknown): value is MolCommand['op'];
|
|
450
|
+
/**
|
|
451
|
+
* Colour parsing is part of the agent-facing protocol: adapters use the same
|
|
452
|
+
* accepted syntax to validate tool arguments and echo the resolved value.
|
|
453
|
+
*/
|
|
454
|
+
export { COLOR_SYNTAX, formatColor, mixColor, parseColor } from './color.ts';
|
|
190
455
|
export declare function isMolFormat(value: unknown): value is MolFormat;
|
|
191
456
|
export declare function isPresetName(value: unknown): value is PresetName;
|
|
457
|
+
export declare function isAlignmentMethod(value: unknown): value is AlignmentMethod;
|
|
458
|
+
export declare function isInspectDetail(value: unknown): value is InspectDetail;
|
|
192
459
|
export declare function isStructureData(value: unknown): value is StructureData;
|
package/lib/protocol.js
CHANGED
|
@@ -47,6 +47,28 @@ export const COLOR_THEMES = [
|
|
|
47
47
|
'molecule-type',
|
|
48
48
|
'hydrophobicity',
|
|
49
49
|
];
|
|
50
|
+
/** Alignment algorithms exposed to agents. */
|
|
51
|
+
export const ALIGNMENT_METHODS = ['tm-align', 'sequence'];
|
|
52
|
+
/**
|
|
53
|
+
* Stable identifier for one structure in a viewer scene.
|
|
54
|
+
*
|
|
55
|
+
* IDs are deliberately URL/JSON friendly so they can travel through every
|
|
56
|
+
* adapter and be echoed by a model: 1-64 characters, starting with a letter or
|
|
57
|
+
* digit, then letters, digits, `.`, `_` or `-`.
|
|
58
|
+
*/
|
|
59
|
+
export const STRUCTURE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
60
|
+
export function isStructureId(value) {
|
|
61
|
+
return typeof value === 'string' && STRUCTURE_ID_PATTERN.test(value);
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* How much detail one inspection returns.
|
|
65
|
+
*
|
|
66
|
+
* `summary` reports totals, per-component counts, and styles but no rows;
|
|
67
|
+
* `residues` adds residue rows, and `atoms` adds per-atom rows inside them.
|
|
68
|
+
*/
|
|
69
|
+
export const INSPECT_DETAILS = ['summary', 'residues', 'atoms'];
|
|
70
|
+
/** Row budget for one inspection result; counts always cover the full target. */
|
|
71
|
+
export const DEFAULT_INSPECT_LIMIT = 200;
|
|
50
72
|
/** Structured failure. Tools turn this into model-facing text instead of a stack trace. */
|
|
51
73
|
export class Mol4AgentError extends Error {
|
|
52
74
|
code;
|
|
@@ -60,6 +82,11 @@ export class Mol4AgentError extends Error {
|
|
|
60
82
|
export function isMolCommandOp(value) {
|
|
61
83
|
return typeof value === 'string' && COMMAND_OPS.has(value);
|
|
62
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* Colour parsing is part of the agent-facing protocol: adapters use the same
|
|
87
|
+
* accepted syntax to validate tool arguments and echo the resolved value.
|
|
88
|
+
*/
|
|
89
|
+
export { COLOR_SYNTAX, formatColor, mixColor, parseColor } from "./color.js";
|
|
63
90
|
const COMMAND_OPS = new Set([
|
|
64
91
|
'represent',
|
|
65
92
|
'select',
|
|
@@ -69,6 +96,9 @@ const COMMAND_OPS = new Set([
|
|
|
69
96
|
'background',
|
|
70
97
|
'measure',
|
|
71
98
|
'label',
|
|
99
|
+
'remove-structure',
|
|
100
|
+
'visibility',
|
|
101
|
+
'align',
|
|
72
102
|
]);
|
|
73
103
|
export function isMolFormat(value) {
|
|
74
104
|
return typeof value === 'string' && MOL_FORMATS.includes(value);
|
|
@@ -76,6 +106,12 @@ export function isMolFormat(value) {
|
|
|
76
106
|
export function isPresetName(value) {
|
|
77
107
|
return typeof value === 'string' && PRESETS.includes(value);
|
|
78
108
|
}
|
|
109
|
+
export function isAlignmentMethod(value) {
|
|
110
|
+
return typeof value === 'string' && ALIGNMENT_METHODS.includes(value);
|
|
111
|
+
}
|
|
112
|
+
export function isInspectDetail(value) {
|
|
113
|
+
return typeof value === 'string' && INSPECT_DETAILS.includes(value);
|
|
114
|
+
}
|
|
79
115
|
export function isStructureData(value) {
|
|
80
116
|
if (typeof value !== 'object' || value === null)
|
|
81
117
|
return false;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `represent` command: replace-vs-overlay policy and its Mol* mutations.
|
|
3
|
+
*
|
|
4
|
+
* Kept out of `viewer.ts` so the whole policy runs under plain Node against a
|
|
5
|
+
* headless `PluginContext`. `replace` is explicit in the protocol; `target`
|
|
6
|
+
* only narrows what the new representation covers, it never implies add or
|
|
7
|
+
* replace. The default is replace, matching the documented no-target behavior.
|
|
8
|
+
*
|
|
9
|
+
* @module @gcszhn/mol4agent-core/represent
|
|
10
|
+
*/
|
|
11
|
+
import type { PluginContext } from 'molstar/lib/mol-plugin/context';
|
|
12
|
+
import type { StructureRef } from 'molstar/lib/mol-plugin-state/manager/structure/hierarchy-state';
|
|
13
|
+
import { type CommandResult, type RepresentCommand, type StyleSpec } from './protocol.ts';
|
|
14
|
+
/** True when the style uses Mol*'s polymer-and-ligand preset. */
|
|
15
|
+
export declare function usesPolymerAndLigandPreset(style: StyleSpec): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Apply one `represent` command.
|
|
18
|
+
*
|
|
19
|
+
* `replace: true` (the default) clears the structure components first, whether
|
|
20
|
+
* or not `target` is present; `target` then narrows only the new
|
|
21
|
+
* representation's coverage. `replace: false` keeps every existing
|
|
22
|
+
* representation and adds the new one. Returns the same structured result as
|
|
23
|
+
* every other command.
|
|
24
|
+
*/
|
|
25
|
+
export declare function applyRepresentation(plugin: PluginContext, command: RepresentCommand, scopedStructures?: readonly StructureRef[]): Promise<CommandResult>;
|
package/lib/represent.js
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { StructureElement } from 'molstar/lib/mol-model/structure.js';
|
|
2
|
+
import { COLOR_THEMES, REPRESENTATION_TYPES, } from "./protocol.js";
|
|
3
|
+
import { formatColor, parseColor } from "./color.js";
|
|
4
|
+
import { selectionKey, selectorExpression } from "./select.js";
|
|
5
|
+
/**
|
|
6
|
+
* How many fresh all-atom components this viewer has created.
|
|
7
|
+
*
|
|
8
|
+
* A new key per global non-preset style keeps stacking (`replace: false`)
|
|
9
|
+
* additive instead of updating a previous component in place.
|
|
10
|
+
*/
|
|
11
|
+
let globalComponentSeq = 0;
|
|
12
|
+
/** True when the style uses Mol*'s polymer-and-ligand preset. */
|
|
13
|
+
export function usesPolymerAndLigandPreset(style) {
|
|
14
|
+
return style.type === undefined || style.type === 'cartoon';
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Apply one `represent` command.
|
|
18
|
+
*
|
|
19
|
+
* `replace: true` (the default) clears the structure components first, whether
|
|
20
|
+
* or not `target` is present; `target` then narrows only the new
|
|
21
|
+
* representation's coverage. `replace: false` keeps every existing
|
|
22
|
+
* representation and adds the new one. Returns the same structured result as
|
|
23
|
+
* every other command.
|
|
24
|
+
*/
|
|
25
|
+
export async function applyRepresentation(plugin, command, scopedStructures) {
|
|
26
|
+
const style = command.style;
|
|
27
|
+
if (style.type !== undefined && !REPRESENTATION_TYPES.includes(style.type)) {
|
|
28
|
+
return invalid(command.op, `unknown representation "${style.type}"; supported: ${REPRESENTATION_TYPES.join(', ')}`);
|
|
29
|
+
}
|
|
30
|
+
if (style.color !== undefined && !COLOR_THEMES.includes(style.color)) {
|
|
31
|
+
return invalid(command.op, `unknown colour theme "${style.color}"; supported: ${COLOR_THEMES.join(', ')}`);
|
|
32
|
+
}
|
|
33
|
+
// Normalize once, before touching the scene: a bad color must fail the
|
|
34
|
+
// command instead of reaching Mol* and painting the structure black.
|
|
35
|
+
let resolvedColor;
|
|
36
|
+
if (style.colorParams?.value !== undefined) {
|
|
37
|
+
try {
|
|
38
|
+
resolvedColor = parseColor(style.colorParams.value);
|
|
39
|
+
}
|
|
40
|
+
catch (error) {
|
|
41
|
+
return invalid(command.op, error instanceof Error ? error.message : String(error));
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
const colorParams = resolvedColor === undefined ? undefined : { value: resolvedColor };
|
|
45
|
+
const colorSuffix = resolvedColor === undefined ? '' : ` ${formatColor(resolvedColor)}`;
|
|
46
|
+
const structures = scopedStructures ?? plugin.managers.structure.hierarchy.current.structures;
|
|
47
|
+
if (structures.length === 0) {
|
|
48
|
+
return { ok: false, op: command.op, code: 'NO_STRUCTURE', message: 'no structure is loaded' };
|
|
49
|
+
}
|
|
50
|
+
const replace = command.replace !== false;
|
|
51
|
+
if (command.target !== undefined) {
|
|
52
|
+
const expression = selectorExpression(command.target);
|
|
53
|
+
// Do not clear the scene for a selection that matches nothing: the command
|
|
54
|
+
// would fail after destroying the previous view. `nullIfEmpty` makes the
|
|
55
|
+
// component builder skip an empty selection, so this mirrors its check.
|
|
56
|
+
if (replace && !matchesAnyStructure(structures, expression)) {
|
|
57
|
+
return representFailed(command.op, command.target);
|
|
58
|
+
}
|
|
59
|
+
if (replace && !await clearRepresentations(plugin, structures)) {
|
|
60
|
+
return {
|
|
61
|
+
ok: false,
|
|
62
|
+
op: command.op,
|
|
63
|
+
code: 'REPRESENT_FAILED',
|
|
64
|
+
message: 'could not remove the current representations',
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
let targeted = 0;
|
|
68
|
+
for (const structure of structures) {
|
|
69
|
+
const component = await plugin.builders.structure.tryCreateComponentFromExpression(structure.cell, expression, selectionKey(command.target), { label: 'mol4agent selection' });
|
|
70
|
+
if (component === undefined)
|
|
71
|
+
continue;
|
|
72
|
+
// No tag: with `replace: false` every targeted style must add its own
|
|
73
|
+
// representation, so two styles of the same selection stack instead of
|
|
74
|
+
// updating one another. A `replace: true` command clears first, so it
|
|
75
|
+
// still leaves exactly one.
|
|
76
|
+
const rep = await plugin.builders.structure.representation.addRepresentation(component, {
|
|
77
|
+
type: (style.type ?? 'ball-and-stick'),
|
|
78
|
+
color: (style.color ?? 'uniform'),
|
|
79
|
+
...(colorParams === undefined ? {} : { colorParams: colorParams }),
|
|
80
|
+
});
|
|
81
|
+
if (rep !== undefined)
|
|
82
|
+
targeted += 1;
|
|
83
|
+
}
|
|
84
|
+
if (targeted === 0)
|
|
85
|
+
return representFailed(command.op, command.target);
|
|
86
|
+
plugin.canvas3d?.requestDraw();
|
|
87
|
+
return {
|
|
88
|
+
ok: true,
|
|
89
|
+
op: command.op,
|
|
90
|
+
message: `applied ${style.type ?? 'ball-and-stick'} / ${style.color ?? 'uniform'}${colorSuffix} to ${command.target.kind}`,
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
if (replace && !await clearRepresentations(plugin, structures)) {
|
|
94
|
+
return {
|
|
95
|
+
ok: false,
|
|
96
|
+
op: command.op,
|
|
97
|
+
code: 'REPRESENT_FAILED',
|
|
98
|
+
message: 'could not remove the current representations',
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
// A single Cartoon representation hides HETATM ligands. Use Mol*'s
|
|
102
|
+
// polymer-and-ligand preset for the default cartoon style so ATP/HEM/etc.
|
|
103
|
+
// stay visible. A uniform colorParams is passed through the preset theme so
|
|
104
|
+
// "gray cartoon" still keeps the ligand representation.
|
|
105
|
+
let added = 0;
|
|
106
|
+
if (usesPolymerAndLigandPreset(style)) {
|
|
107
|
+
for (const structure of structures) {
|
|
108
|
+
await plugin.builders.structure.representation.applyPreset(structure.cell, 'polymer-and-ligand', {
|
|
109
|
+
theme: {
|
|
110
|
+
globalName: style.color ?? 'chain-id',
|
|
111
|
+
...(colorParams === undefined ? {} : { globalColorParams: colorParams }),
|
|
112
|
+
},
|
|
113
|
+
});
|
|
114
|
+
added += 1;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
else {
|
|
118
|
+
// Representations live under components. Build one fresh all-atom
|
|
119
|
+
// component per structure. With replace: false the previous components
|
|
120
|
+
// stay, so every new style needs its own key.
|
|
121
|
+
const all = selectorExpression({ kind: 'all' });
|
|
122
|
+
for (const structure of structures) {
|
|
123
|
+
const component = await plugin.builders.structure.tryCreateComponentFromExpression(structure.cell, all, `mol4agent-global-${globalComponentSeq += 1}`, { label: 'mol4agent global' });
|
|
124
|
+
if (component === undefined)
|
|
125
|
+
continue;
|
|
126
|
+
const rep = await plugin.builders.structure.representation.addRepresentation(component, {
|
|
127
|
+
type: (style.type ?? 'cartoon'),
|
|
128
|
+
color: (style.color ?? 'chain-id'),
|
|
129
|
+
...(colorParams === undefined ? {} : { colorParams: colorParams }),
|
|
130
|
+
});
|
|
131
|
+
if (rep !== undefined)
|
|
132
|
+
added += 1;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
if (added === 0) {
|
|
136
|
+
return {
|
|
137
|
+
ok: false,
|
|
138
|
+
op: command.op,
|
|
139
|
+
code: 'REPRESENT_FAILED',
|
|
140
|
+
message: `Mol* did not create a representation for ${style.type ?? 'cartoon'}`,
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
plugin.canvas3d?.requestDraw();
|
|
144
|
+
return {
|
|
145
|
+
ok: true,
|
|
146
|
+
op: command.op,
|
|
147
|
+
message: `applied ${style.type ?? 'cartoon'} / ${style.color ?? 'chain-id'}${colorSuffix}`,
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
/** Whether `expression` selects at least one atom in any loaded structure. */
|
|
151
|
+
function matchesAnyStructure(structures, expression) {
|
|
152
|
+
for (const structure of structures) {
|
|
153
|
+
const data = structure.cell.obj?.data;
|
|
154
|
+
if (data === undefined)
|
|
155
|
+
continue;
|
|
156
|
+
try {
|
|
157
|
+
if (!StructureElement.Loci.isEmpty(StructureElement.Loci.fromExpression(data, expression)))
|
|
158
|
+
return true;
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
// Treat an expression we cannot evaluate as no match: never clear the
|
|
162
|
+
// scene for a selection the component builder may then fail to create.
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
return false;
|
|
166
|
+
}
|
|
167
|
+
/** Remove every structure component, i.e. every agent or human representation. */
|
|
168
|
+
async function clearRepresentations(plugin, structures) {
|
|
169
|
+
const components = structures.flatMap(structure => [...structure.components]);
|
|
170
|
+
if (components.length === 0)
|
|
171
|
+
return true;
|
|
172
|
+
try {
|
|
173
|
+
await plugin.managers.structure.hierarchy.remove(components, true);
|
|
174
|
+
return true;
|
|
175
|
+
}
|
|
176
|
+
catch (reason) {
|
|
177
|
+
console.warn('[mol4agent] could not remove the current representations', reason);
|
|
178
|
+
return false;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
function representFailed(op, target) {
|
|
182
|
+
return {
|
|
183
|
+
ok: false,
|
|
184
|
+
op,
|
|
185
|
+
code: 'REPRESENT_FAILED',
|
|
186
|
+
message: `Mol* did not create a representation for ${target.kind}`,
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
function invalid(op, message) {
|
|
190
|
+
return { ok: false, op, code: 'INVALID_COMMAND', message };
|
|
191
|
+
}
|
package/lib/select.d.ts
CHANGED
|
@@ -17,3 +17,15 @@ export type CompiledSelector = {
|
|
|
17
17
|
export declare function compileSelector(selector: StructureSelector): CompiledSelector;
|
|
18
18
|
/** A schema-only selector, or undefined when the selector needs a full query. */
|
|
19
19
|
export declare function selectorSchema(selector: StructureSelector): ElementSchema | undefined;
|
|
20
|
+
/** The Mol* expression equivalent of a selector, for direct Loci lookups. */
|
|
21
|
+
export declare function selectorExpression(selector: StructureSelector): Expression;
|
|
22
|
+
/**
|
|
23
|
+
* Stable component key for one selection.
|
|
24
|
+
*
|
|
25
|
+
* Repeated targeted styles of the same selection reuse one Mol* cell; each
|
|
26
|
+
* `replace: false` command adds its own representation there, so cartoon +
|
|
27
|
+
* stick + line overlays do not fragment into sibling components.
|
|
28
|
+
*/
|
|
29
|
+
export declare function selectionKey(selector: StructureSelector): string;
|
|
30
|
+
/** Short human label for a selector, used in tool and inspection output. */
|
|
31
|
+
export declare function describeSelector(selector: StructureSelector): string;
|