@arke-institute/sdk 0.1.2 → 2.0.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 +126 -184
- package/dist/generated/index.cjs +19 -0
- package/dist/generated/index.cjs.map +1 -0
- package/dist/generated/index.d.cts +6192 -0
- package/dist/generated/index.d.ts +6192 -0
- package/dist/generated/index.js +1 -0
- package/dist/generated/index.js.map +1 -0
- package/dist/index-BrXke2kI.d.ts +302 -0
- package/dist/index-FHcLPBSV.d.cts +302 -0
- package/dist/index.cjs +188 -3654
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +62 -7
- package/dist/index.d.ts +62 -7
- package/dist/index.js +168 -3626
- package/dist/index.js.map +1 -1
- package/dist/operations/index.cjs +113 -0
- package/dist/operations/index.cjs.map +1 -0
- package/dist/operations/index.d.cts +3 -0
- package/dist/operations/index.d.ts +3 -0
- package/dist/operations/index.js +84 -0
- package/dist/operations/index.js.map +1 -0
- package/package.json +44 -53
- package/dist/client-dAk3E64p.d.cts +0 -183
- package/dist/client-dAk3E64p.d.ts +0 -183
- package/dist/collections/index.cjs +0 -233
- package/dist/collections/index.cjs.map +0 -1
- package/dist/collections/index.d.cts +0 -9
- package/dist/collections/index.d.ts +0 -9
- package/dist/collections/index.js +0 -205
- package/dist/collections/index.js.map +0 -1
- package/dist/content/index.cjs +0 -506
- package/dist/content/index.cjs.map +0 -1
- package/dist/content/index.d.cts +0 -403
- package/dist/content/index.d.ts +0 -403
- package/dist/content/index.js +0 -473
- package/dist/content/index.js.map +0 -1
- package/dist/edit/index.cjs +0 -1029
- package/dist/edit/index.cjs.map +0 -1
- package/dist/edit/index.d.cts +0 -78
- package/dist/edit/index.d.ts +0 -78
- package/dist/edit/index.js +0 -983
- package/dist/edit/index.js.map +0 -1
- package/dist/errors-3L7IiHcr.d.cts +0 -480
- package/dist/errors-B82BMmRP.d.cts +0 -343
- package/dist/errors-B82BMmRP.d.ts +0 -343
- package/dist/errors-BTe8GKRQ.d.ts +0 -480
- package/dist/graph/index.cjs +0 -433
- package/dist/graph/index.cjs.map +0 -1
- package/dist/graph/index.d.cts +0 -456
- package/dist/graph/index.d.ts +0 -456
- package/dist/graph/index.js +0 -402
- package/dist/graph/index.js.map +0 -1
- package/dist/query/index.cjs +0 -289
- package/dist/query/index.cjs.map +0 -1
- package/dist/query/index.d.cts +0 -541
- package/dist/query/index.d.ts +0 -541
- package/dist/query/index.js +0 -261
- package/dist/query/index.js.map +0 -1
- package/dist/upload/index.cjs +0 -1634
- package/dist/upload/index.cjs.map +0 -1
- package/dist/upload/index.d.cts +0 -150
- package/dist/upload/index.d.ts +0 -150
- package/dist/upload/index.js +0 -1597
- package/dist/upload/index.js.map +0 -1
package/dist/query/index.cjs
DELETED
|
@@ -1,289 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __defProp = Object.defineProperty;
|
|
3
|
-
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
-
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
-
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
-
var __export = (target, all) => {
|
|
7
|
-
for (var name in all)
|
|
8
|
-
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
-
};
|
|
10
|
-
var __copyProps = (to, from, except, desc) => {
|
|
11
|
-
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
-
for (let key of __getOwnPropNames(from))
|
|
13
|
-
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
-
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
-
}
|
|
16
|
-
return to;
|
|
17
|
-
};
|
|
18
|
-
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
-
|
|
20
|
-
// src/query/index.ts
|
|
21
|
-
var query_exports = {};
|
|
22
|
-
__export(query_exports, {
|
|
23
|
-
QueryClient: () => QueryClient,
|
|
24
|
-
QueryError: () => QueryError
|
|
25
|
-
});
|
|
26
|
-
module.exports = __toCommonJS(query_exports);
|
|
27
|
-
|
|
28
|
-
// src/query/errors.ts
|
|
29
|
-
var QueryError = class extends Error {
|
|
30
|
-
constructor(message, code = "UNKNOWN_ERROR", details) {
|
|
31
|
-
super(message);
|
|
32
|
-
this.code = code;
|
|
33
|
-
this.details = details;
|
|
34
|
-
this.name = "QueryError";
|
|
35
|
-
}
|
|
36
|
-
};
|
|
37
|
-
|
|
38
|
-
// src/query/client.ts
|
|
39
|
-
var QueryClient = class {
|
|
40
|
-
constructor(config) {
|
|
41
|
-
this.baseUrl = config.gatewayUrl.replace(/\/$/, "");
|
|
42
|
-
this.fetchImpl = config.fetchImpl ?? fetch;
|
|
43
|
-
}
|
|
44
|
-
// ---------------------------------------------------------------------------
|
|
45
|
-
// Request helpers
|
|
46
|
-
// ---------------------------------------------------------------------------
|
|
47
|
-
buildUrl(path, query) {
|
|
48
|
-
const url = new URL(`${this.baseUrl}${path}`);
|
|
49
|
-
if (query) {
|
|
50
|
-
Object.entries(query).forEach(([key, value]) => {
|
|
51
|
-
if (value !== void 0 && value !== null) {
|
|
52
|
-
url.searchParams.set(key, String(value));
|
|
53
|
-
}
|
|
54
|
-
});
|
|
55
|
-
}
|
|
56
|
-
return url.toString();
|
|
57
|
-
}
|
|
58
|
-
async request(path, options = {}) {
|
|
59
|
-
const url = this.buildUrl(path, options.query);
|
|
60
|
-
const headers = new Headers({ "Content-Type": "application/json" });
|
|
61
|
-
if (options.headers) {
|
|
62
|
-
Object.entries(options.headers).forEach(([k, v]) => {
|
|
63
|
-
if (v !== void 0) headers.set(k, v);
|
|
64
|
-
});
|
|
65
|
-
}
|
|
66
|
-
const response = await this.fetchImpl(url, { ...options, headers });
|
|
67
|
-
if (response.ok) {
|
|
68
|
-
const contentType = response.headers.get("content-type") || "";
|
|
69
|
-
if (contentType.includes("application/json")) {
|
|
70
|
-
return await response.json();
|
|
71
|
-
}
|
|
72
|
-
return await response.text();
|
|
73
|
-
}
|
|
74
|
-
let body;
|
|
75
|
-
const text = await response.text();
|
|
76
|
-
try {
|
|
77
|
-
body = JSON.parse(text);
|
|
78
|
-
} catch {
|
|
79
|
-
body = text;
|
|
80
|
-
}
|
|
81
|
-
const message = body?.error && typeof body.error === "string" ? body.error : body?.message && typeof body.message === "string" ? body.message : `Request failed with status ${response.status}`;
|
|
82
|
-
throw new QueryError(message, "HTTP_ERROR", {
|
|
83
|
-
status: response.status,
|
|
84
|
-
body
|
|
85
|
-
});
|
|
86
|
-
}
|
|
87
|
-
// ---------------------------------------------------------------------------
|
|
88
|
-
// Query methods
|
|
89
|
-
// ---------------------------------------------------------------------------
|
|
90
|
-
/**
|
|
91
|
-
* Execute a path query against the knowledge graph.
|
|
92
|
-
*
|
|
93
|
-
* @param pathQuery - The path query string (e.g., '"alice austen" -[*]{,4}-> type:person')
|
|
94
|
-
* @param options - Query options (k, k_explore, lineage, enrich, etc.)
|
|
95
|
-
* @returns Query results with entities, paths, and metadata
|
|
96
|
-
*
|
|
97
|
-
* @example
|
|
98
|
-
* ```typescript
|
|
99
|
-
* // Simple semantic search
|
|
100
|
-
* const results = await query.path('"Washington" type:person');
|
|
101
|
-
*
|
|
102
|
-
* // Multi-hop traversal
|
|
103
|
-
* const results = await query.path('"alice austen" -[*]{,4}-> type:person ~ "photographer"');
|
|
104
|
-
*
|
|
105
|
-
* // With lineage filtering (collection scope)
|
|
106
|
-
* const results = await query.path('"letters" type:document', {
|
|
107
|
-
* lineage: { sourcePi: 'arke:my_collection', direction: 'descendants' },
|
|
108
|
-
* k: 10,
|
|
109
|
-
* });
|
|
110
|
-
* ```
|
|
111
|
-
*/
|
|
112
|
-
async path(pathQuery, options = {}) {
|
|
113
|
-
return this.request("/query/path", {
|
|
114
|
-
method: "POST",
|
|
115
|
-
body: JSON.stringify({
|
|
116
|
-
path: pathQuery,
|
|
117
|
-
...options
|
|
118
|
-
})
|
|
119
|
-
});
|
|
120
|
-
}
|
|
121
|
-
/**
|
|
122
|
-
* Execute a natural language query.
|
|
123
|
-
*
|
|
124
|
-
* The query is translated to a path query using an LLM, then executed.
|
|
125
|
-
*
|
|
126
|
-
* @param question - Natural language question
|
|
127
|
-
* @param options - Query options including custom_instructions for the LLM
|
|
128
|
-
* @returns Query results with translation info
|
|
129
|
-
*
|
|
130
|
-
* @example
|
|
131
|
-
* ```typescript
|
|
132
|
-
* const results = await query.natural('Find photographers connected to Alice Austen');
|
|
133
|
-
* console.log('Generated query:', results.translation.path);
|
|
134
|
-
* console.log('Explanation:', results.translation.explanation);
|
|
135
|
-
* ```
|
|
136
|
-
*/
|
|
137
|
-
async natural(question, options = {}) {
|
|
138
|
-
const { custom_instructions, ...queryOptions } = options;
|
|
139
|
-
return this.request("/query/natural", {
|
|
140
|
-
method: "POST",
|
|
141
|
-
body: JSON.stringify({
|
|
142
|
-
query: question,
|
|
143
|
-
custom_instructions,
|
|
144
|
-
...queryOptions
|
|
145
|
-
})
|
|
146
|
-
});
|
|
147
|
-
}
|
|
148
|
-
/**
|
|
149
|
-
* Translate a natural language question to a path query without executing it.
|
|
150
|
-
*
|
|
151
|
-
* Useful for understanding how questions are translated or for manual execution later.
|
|
152
|
-
*
|
|
153
|
-
* @param question - Natural language question
|
|
154
|
-
* @param customInstructions - Optional additional instructions for the LLM
|
|
155
|
-
* @returns Translation result with path query and explanation
|
|
156
|
-
*
|
|
157
|
-
* @example
|
|
158
|
-
* ```typescript
|
|
159
|
-
* const result = await query.translate('Who wrote letters from Philadelphia?');
|
|
160
|
-
* console.log('Path query:', result.path);
|
|
161
|
-
* // '"letters" <-[authored, wrote]- type:person -[located]-> "Philadelphia"'
|
|
162
|
-
* ```
|
|
163
|
-
*/
|
|
164
|
-
async translate(question, customInstructions) {
|
|
165
|
-
return this.request("/query/translate", {
|
|
166
|
-
method: "POST",
|
|
167
|
-
body: JSON.stringify({
|
|
168
|
-
query: question,
|
|
169
|
-
custom_instructions: customInstructions
|
|
170
|
-
})
|
|
171
|
-
});
|
|
172
|
-
}
|
|
173
|
-
/**
|
|
174
|
-
* Parse and validate a path query without executing it.
|
|
175
|
-
*
|
|
176
|
-
* Returns the AST (Abstract Syntax Tree) if valid, or throws an error.
|
|
177
|
-
*
|
|
178
|
-
* @param pathQuery - The path query to parse
|
|
179
|
-
* @returns Parsed AST
|
|
180
|
-
* @throws QueryError if the query has syntax errors
|
|
181
|
-
*
|
|
182
|
-
* @example
|
|
183
|
-
* ```typescript
|
|
184
|
-
* try {
|
|
185
|
-
* const result = await query.parse('"test" -[*]-> type:person');
|
|
186
|
-
* console.log('Valid query, AST:', result.ast);
|
|
187
|
-
* } catch (err) {
|
|
188
|
-
* console.error('Invalid query:', err.message);
|
|
189
|
-
* }
|
|
190
|
-
* ```
|
|
191
|
-
*/
|
|
192
|
-
async parse(pathQuery) {
|
|
193
|
-
const url = this.buildUrl("/query/parse", { path: pathQuery });
|
|
194
|
-
const response = await this.fetchImpl(url, {
|
|
195
|
-
method: "GET",
|
|
196
|
-
headers: { "Content-Type": "application/json" }
|
|
197
|
-
});
|
|
198
|
-
const body = await response.json();
|
|
199
|
-
if ("error" in body && body.error === "Parse error") {
|
|
200
|
-
throw new QueryError(
|
|
201
|
-
body.message,
|
|
202
|
-
"PARSE_ERROR",
|
|
203
|
-
{ position: body.position }
|
|
204
|
-
);
|
|
205
|
-
}
|
|
206
|
-
if (!response.ok) {
|
|
207
|
-
throw new QueryError(
|
|
208
|
-
body.error || `Request failed with status ${response.status}`,
|
|
209
|
-
"HTTP_ERROR",
|
|
210
|
-
{ status: response.status, body }
|
|
211
|
-
);
|
|
212
|
-
}
|
|
213
|
-
return body;
|
|
214
|
-
}
|
|
215
|
-
/**
|
|
216
|
-
* Get the path query syntax documentation.
|
|
217
|
-
*
|
|
218
|
-
* Returns comprehensive documentation including entry points, edge traversal,
|
|
219
|
-
* filters, examples, and constraints.
|
|
220
|
-
*
|
|
221
|
-
* @returns Syntax documentation
|
|
222
|
-
*
|
|
223
|
-
* @example
|
|
224
|
-
* ```typescript
|
|
225
|
-
* const syntax = await query.syntax();
|
|
226
|
-
*
|
|
227
|
-
* // List all entry point types
|
|
228
|
-
* syntax.entryPoints.types.forEach(ep => {
|
|
229
|
-
* console.log(`${ep.syntax} - ${ep.description}`);
|
|
230
|
-
* });
|
|
231
|
-
*
|
|
232
|
-
* // Show examples
|
|
233
|
-
* syntax.examples.forEach(ex => {
|
|
234
|
-
* console.log(`${ex.description}: ${ex.query}`);
|
|
235
|
-
* });
|
|
236
|
-
* ```
|
|
237
|
-
*/
|
|
238
|
-
async syntax() {
|
|
239
|
-
return this.request("/query/syntax", {
|
|
240
|
-
method: "GET"
|
|
241
|
-
});
|
|
242
|
-
}
|
|
243
|
-
/**
|
|
244
|
-
* Check the health of the query service.
|
|
245
|
-
*
|
|
246
|
-
* @returns Health status
|
|
247
|
-
*/
|
|
248
|
-
async health() {
|
|
249
|
-
return this.request("/query/health", { method: "GET" });
|
|
250
|
-
}
|
|
251
|
-
/**
|
|
252
|
-
* Search for collections by semantic similarity.
|
|
253
|
-
*
|
|
254
|
-
* Searches the dedicated collections index for fast semantic matching.
|
|
255
|
-
*
|
|
256
|
-
* @param query - Search query text
|
|
257
|
-
* @param options - Search options (limit, visibility filter)
|
|
258
|
-
* @returns Matching collections with similarity scores
|
|
259
|
-
*
|
|
260
|
-
* @example
|
|
261
|
-
* ```typescript
|
|
262
|
-
* // Search for photography-related collections
|
|
263
|
-
* const results = await query.searchCollections('photography');
|
|
264
|
-
* console.log(results.collections[0].title);
|
|
265
|
-
*
|
|
266
|
-
* // Search only public collections
|
|
267
|
-
* const publicResults = await query.searchCollections('history', {
|
|
268
|
-
* visibility: 'public',
|
|
269
|
-
* limit: 20,
|
|
270
|
-
* });
|
|
271
|
-
* ```
|
|
272
|
-
*/
|
|
273
|
-
async searchCollections(query, options = {}) {
|
|
274
|
-
return this.request("/query/search/collections", {
|
|
275
|
-
method: "GET",
|
|
276
|
-
query: {
|
|
277
|
-
q: query,
|
|
278
|
-
limit: options.limit?.toString(),
|
|
279
|
-
visibility: options.visibility
|
|
280
|
-
}
|
|
281
|
-
});
|
|
282
|
-
}
|
|
283
|
-
};
|
|
284
|
-
// Annotate the CommonJS export names for ESM import in node:
|
|
285
|
-
0 && (module.exports = {
|
|
286
|
-
QueryClient,
|
|
287
|
-
QueryError
|
|
288
|
-
});
|
|
289
|
-
//# sourceMappingURL=index.cjs.map
|
package/dist/query/index.cjs.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/query/index.ts","../../src/query/errors.ts","../../src/query/client.ts"],"sourcesContent":["export { QueryClient, type QueryClientConfig } from './client';\nexport { QueryError } from './errors';\nexport type {\n // Request types\n LineageFilter,\n PathQueryOptions,\n NaturalQueryOptions,\n // Response types\n EnrichedContent,\n Entity,\n PathStep,\n QueryResultItem,\n LineageMetadata,\n QueryMetadata,\n QueryResult,\n TranslationInfo,\n NaturalQueryResult,\n TranslateResult,\n // Parse types\n ASTNodeType,\n EntryAST,\n FilterAST,\n HopAST,\n PathAST,\n ParseResult,\n ParseError,\n // Syntax documentation types\n EntryPointDoc,\n EdgeTypeDoc,\n VariableDepthDoc,\n FilterTypeDoc,\n ParameterDoc,\n ExampleDoc,\n SyntaxDocumentation,\n // Collection search types\n CollectionSearchOptions,\n CollectionSearchResult,\n CollectionSearchResponse,\n} from './types';\n","/**\n * Error class for query operations\n */\nexport class QueryError extends Error {\n constructor(\n message: string,\n public code: string = 'UNKNOWN_ERROR',\n public details?: unknown\n ) {\n super(message);\n this.name = 'QueryError';\n }\n}\n","import { QueryError } from './errors';\nimport type {\n PathQueryOptions,\n NaturalQueryOptions,\n QueryResult,\n NaturalQueryResult,\n TranslateResult,\n ParseResult,\n ParseError,\n SyntaxDocumentation,\n CollectionSearchOptions,\n CollectionSearchResponse,\n} from './types';\n\n/**\n * Configuration for QueryClient\n */\nexport interface QueryClientConfig {\n /**\n * Gateway base URL (e.g., https://gateway.arke.institute).\n * The client will call /query/* endpoints.\n */\n gatewayUrl: string;\n /**\n * Optional custom fetch implementation (useful for testing).\n */\n fetchImpl?: typeof fetch;\n}\n\ntype JsonBody = Record<string, unknown>;\n\n/**\n * Client for querying the Arke knowledge graph.\n *\n * All query endpoints are public and do not require authentication.\n *\n * @example\n * ```typescript\n * const query = new QueryClient({\n * gatewayUrl: 'https://gateway.arke.institute',\n * });\n *\n * // Direct path query\n * const results = await query.path('\"alice austen\" -[*]{,4}-> type:person');\n *\n * // Natural language query\n * const nlResults = await query.natural('Find photographers connected to Alice Austen');\n *\n * // Get syntax documentation\n * const syntax = await query.syntax();\n * ```\n */\nexport class QueryClient {\n private baseUrl: string;\n private fetchImpl: typeof fetch;\n\n constructor(config: QueryClientConfig) {\n this.baseUrl = config.gatewayUrl.replace(/\\/$/, '');\n this.fetchImpl = config.fetchImpl ?? fetch;\n }\n\n // ---------------------------------------------------------------------------\n // Request helpers\n // ---------------------------------------------------------------------------\n\n private buildUrl(path: string, query?: Record<string, string | undefined>) {\n const url = new URL(`${this.baseUrl}${path}`);\n if (query) {\n Object.entries(query).forEach(([key, value]) => {\n if (value !== undefined && value !== null) {\n url.searchParams.set(key, String(value));\n }\n });\n }\n return url.toString();\n }\n\n private async request<T>(\n path: string,\n options: RequestInit & {\n query?: Record<string, string | undefined>;\n } = {}\n ): Promise<T> {\n const url = this.buildUrl(path, options.query);\n const headers = new Headers({ 'Content-Type': 'application/json' });\n if (options.headers) {\n Object.entries(options.headers).forEach(([k, v]) => {\n if (v !== undefined) headers.set(k, v as string);\n });\n }\n\n const response = await this.fetchImpl(url, { ...options, headers });\n\n if (response.ok) {\n const contentType = response.headers.get('content-type') || '';\n if (contentType.includes('application/json')) {\n return (await response.json()) as T;\n }\n return (await response.text()) as unknown as T;\n }\n\n let body: unknown;\n const text = await response.text();\n try {\n body = JSON.parse(text);\n } catch {\n body = text;\n }\n\n const message =\n (body as JsonBody)?.error && typeof (body as JsonBody).error === 'string'\n ? ((body as JsonBody).error as string)\n : (body as JsonBody)?.message && typeof (body as JsonBody).message === 'string'\n ? ((body as JsonBody).message as string)\n : `Request failed with status ${response.status}`;\n\n throw new QueryError(message, 'HTTP_ERROR', {\n status: response.status,\n body,\n });\n }\n\n // ---------------------------------------------------------------------------\n // Query methods\n // ---------------------------------------------------------------------------\n\n /**\n * Execute a path query against the knowledge graph.\n *\n * @param pathQuery - The path query string (e.g., '\"alice austen\" -[*]{,4}-> type:person')\n * @param options - Query options (k, k_explore, lineage, enrich, etc.)\n * @returns Query results with entities, paths, and metadata\n *\n * @example\n * ```typescript\n * // Simple semantic search\n * const results = await query.path('\"Washington\" type:person');\n *\n * // Multi-hop traversal\n * const results = await query.path('\"alice austen\" -[*]{,4}-> type:person ~ \"photographer\"');\n *\n * // With lineage filtering (collection scope)\n * const results = await query.path('\"letters\" type:document', {\n * lineage: { sourcePi: 'arke:my_collection', direction: 'descendants' },\n * k: 10,\n * });\n * ```\n */\n async path(pathQuery: string, options: PathQueryOptions = {}): Promise<QueryResult> {\n return this.request<QueryResult>('/query/path', {\n method: 'POST',\n body: JSON.stringify({\n path: pathQuery,\n ...options,\n }),\n });\n }\n\n /**\n * Execute a natural language query.\n *\n * The query is translated to a path query using an LLM, then executed.\n *\n * @param question - Natural language question\n * @param options - Query options including custom_instructions for the LLM\n * @returns Query results with translation info\n *\n * @example\n * ```typescript\n * const results = await query.natural('Find photographers connected to Alice Austen');\n * console.log('Generated query:', results.translation.path);\n * console.log('Explanation:', results.translation.explanation);\n * ```\n */\n async natural(question: string, options: NaturalQueryOptions = {}): Promise<NaturalQueryResult> {\n const { custom_instructions, ...queryOptions } = options;\n return this.request<NaturalQueryResult>('/query/natural', {\n method: 'POST',\n body: JSON.stringify({\n query: question,\n custom_instructions,\n ...queryOptions,\n }),\n });\n }\n\n /**\n * Translate a natural language question to a path query without executing it.\n *\n * Useful for understanding how questions are translated or for manual execution later.\n *\n * @param question - Natural language question\n * @param customInstructions - Optional additional instructions for the LLM\n * @returns Translation result with path query and explanation\n *\n * @example\n * ```typescript\n * const result = await query.translate('Who wrote letters from Philadelphia?');\n * console.log('Path query:', result.path);\n * // '\"letters\" <-[authored, wrote]- type:person -[located]-> \"Philadelphia\"'\n * ```\n */\n async translate(question: string, customInstructions?: string): Promise<TranslateResult> {\n return this.request<TranslateResult>('/query/translate', {\n method: 'POST',\n body: JSON.stringify({\n query: question,\n custom_instructions: customInstructions,\n }),\n });\n }\n\n /**\n * Parse and validate a path query without executing it.\n *\n * Returns the AST (Abstract Syntax Tree) if valid, or throws an error.\n *\n * @param pathQuery - The path query to parse\n * @returns Parsed AST\n * @throws QueryError if the query has syntax errors\n *\n * @example\n * ```typescript\n * try {\n * const result = await query.parse('\"test\" -[*]-> type:person');\n * console.log('Valid query, AST:', result.ast);\n * } catch (err) {\n * console.error('Invalid query:', err.message);\n * }\n * ```\n */\n async parse(pathQuery: string): Promise<ParseResult> {\n const url = this.buildUrl('/query/parse', { path: pathQuery });\n const response = await this.fetchImpl(url, {\n method: 'GET',\n headers: { 'Content-Type': 'application/json' },\n });\n\n const body = await response.json() as ParseResult | ParseError;\n\n // Check if it's an error response (parse errors return 400)\n if ('error' in body && body.error === 'Parse error') {\n throw new QueryError(\n (body as ParseError).message,\n 'PARSE_ERROR',\n { position: (body as ParseError).position }\n );\n }\n\n if (!response.ok) {\n throw new QueryError(\n (body as any).error || `Request failed with status ${response.status}`,\n 'HTTP_ERROR',\n { status: response.status, body }\n );\n }\n\n return body as ParseResult;\n }\n\n /**\n * Get the path query syntax documentation.\n *\n * Returns comprehensive documentation including entry points, edge traversal,\n * filters, examples, and constraints.\n *\n * @returns Syntax documentation\n *\n * @example\n * ```typescript\n * const syntax = await query.syntax();\n *\n * // List all entry point types\n * syntax.entryPoints.types.forEach(ep => {\n * console.log(`${ep.syntax} - ${ep.description}`);\n * });\n *\n * // Show examples\n * syntax.examples.forEach(ex => {\n * console.log(`${ex.description}: ${ex.query}`);\n * });\n * ```\n */\n async syntax(): Promise<SyntaxDocumentation> {\n return this.request<SyntaxDocumentation>('/query/syntax', {\n method: 'GET',\n });\n }\n\n /**\n * Check the health of the query service.\n *\n * @returns Health status\n */\n async health(): Promise<{ status: string; service: string; version: string }> {\n return this.request('/query/health', { method: 'GET' });\n }\n\n /**\n * Search for collections by semantic similarity.\n *\n * Searches the dedicated collections index for fast semantic matching.\n *\n * @param query - Search query text\n * @param options - Search options (limit, visibility filter)\n * @returns Matching collections with similarity scores\n *\n * @example\n * ```typescript\n * // Search for photography-related collections\n * const results = await query.searchCollections('photography');\n * console.log(results.collections[0].title);\n *\n * // Search only public collections\n * const publicResults = await query.searchCollections('history', {\n * visibility: 'public',\n * limit: 20,\n * });\n * ```\n */\n async searchCollections(\n query: string,\n options: CollectionSearchOptions = {}\n ): Promise<CollectionSearchResponse> {\n return this.request<CollectionSearchResponse>('/query/search/collections', {\n method: 'GET',\n query: {\n q: query,\n limit: options.limit?.toString(),\n visibility: options.visibility,\n },\n });\n }\n}\n"],"mappings":"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","names":[]}
|