@healthcloudai/hc-sdk 3.3.0 → 3.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/dist/index.cjs +18 -0
- package/dist/index.d.cts +96 -1
- package/dist/index.d.ts +96 -1
- package/dist/index.js +18 -0
- package/docs/clients/GraphClient.md +3 -0
- package/docs/docs-manifest.json +12 -3
- package/docs/examples/index.md +3 -0
- package/docs/index.md +3 -0
- package/docs/models/GetVectorDocumentChunksResponse.md +30 -0
- package/docs/models/ListVectorCollectionsResponse.md +19 -0
- package/docs/models/VectorCollection.md +24 -0
- package/docs/models/VectorSearchDocumentsRequest.md +25 -0
- package/docs/models/VectorSearchHit.md +30 -0
- package/docs/models/VectorSearchResponse.md +22 -0
- package/docs/models/index.md +6 -0
- package/docs/operations/graph.getVectorDocumentChunks.md +189 -0
- package/docs/operations/graph.listVectorCollections.md +138 -0
- package/docs/operations/graph.vectorSearchDocuments.md +207 -0
- package/package.json +1 -1
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# Semantic search over document chunks
|
|
2
|
+
|
|
3
|
+
Operation ID: `graph.vectorSearchDocuments`
|
|
4
|
+
|
|
5
|
+
Rank document chunks by semantic similarity to a natural-language query. The query is embedded server-side with the same model the collection was loaded with and matched by cosine similarity, so a question finds a document it shares no words with. Scope the search with collection (which corpus: consumer health topics or payer policies), then collection_group, source, language, network_id and tags within it. Searching the payer-policy collection requires payer_key: that corpus is partitioned by payer, so one search only ever returns one payer's policies.
|
|
6
|
+
|
|
7
|
+
## Public method
|
|
8
|
+
|
|
9
|
+
`vectorSearchDocuments`
|
|
10
|
+
|
|
11
|
+
Signature: `graph.vectorSearchDocuments(request)`
|
|
12
|
+
|
|
13
|
+
Return type: `Promise<VectorSearchResponse>`
|
|
14
|
+
|
|
15
|
+
## Authentication
|
|
16
|
+
|
|
17
|
+
Classification: **AUTHENTICATED**
|
|
18
|
+
|
|
19
|
+
Schemes: `bearerAuth`
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
None documented.
|
|
24
|
+
|
|
25
|
+
## HTTP
|
|
26
|
+
|
|
27
|
+
`POST /graph/vector/search`
|
|
28
|
+
|
|
29
|
+
## Path parameters
|
|
30
|
+
|
|
31
|
+
None.
|
|
32
|
+
|
|
33
|
+
## Query parameters
|
|
34
|
+
|
|
35
|
+
None.
|
|
36
|
+
|
|
37
|
+
## Body parameters
|
|
38
|
+
|
|
39
|
+
| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|
|
40
|
+
|---|---|---:|---|---|---|---:|---|
|
|
41
|
+
| `body` | [`VectorSearchDocumentsRequest`](../models/VectorSearchDocumentsRequest.md) | Yes | | | | No | |
|
|
42
|
+
|
|
43
|
+
Request model: [`VectorSearchDocumentsRequest`](../models/VectorSearchDocumentsRequest.md)
|
|
44
|
+
|
|
45
|
+
## Request example
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"collection": "string",
|
|
50
|
+
"collection_group": "string",
|
|
51
|
+
"language": "string",
|
|
52
|
+
"network_id": "string",
|
|
53
|
+
"payer_key": "string",
|
|
54
|
+
"q": "string",
|
|
55
|
+
"source": "string",
|
|
56
|
+
"tags": [
|
|
57
|
+
"string"
|
|
58
|
+
],
|
|
59
|
+
"top_k": 10
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Success responses
|
|
64
|
+
|
|
65
|
+
| Status | Shape | Content type | Description |
|
|
66
|
+
|---|---|---|---|
|
|
67
|
+
| `200` | [`VectorSearchResponse`](../models/VectorSearchResponse.md) | application/json | Ranked document chunks, closest first |
|
|
68
|
+
|
|
69
|
+
## Success response examples
|
|
70
|
+
|
|
71
|
+
### 200
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{
|
|
75
|
+
"collection": "string",
|
|
76
|
+
"count": 0,
|
|
77
|
+
"embedding_model": "string",
|
|
78
|
+
"filter": "string",
|
|
79
|
+
"hits": [
|
|
80
|
+
{
|
|
81
|
+
"chunk_index": 0,
|
|
82
|
+
"collection_group": "string",
|
|
83
|
+
"doc_id": "string",
|
|
84
|
+
"id": "string",
|
|
85
|
+
"language": "string",
|
|
86
|
+
"metadata": {},
|
|
87
|
+
"network_id": "string",
|
|
88
|
+
"payer_key": "string",
|
|
89
|
+
"score": 0,
|
|
90
|
+
"source": "string",
|
|
91
|
+
"tags": [
|
|
92
|
+
"string"
|
|
93
|
+
],
|
|
94
|
+
"text": "string",
|
|
95
|
+
"title": "string",
|
|
96
|
+
"url": "string"
|
|
97
|
+
}
|
|
98
|
+
],
|
|
99
|
+
"query": "string"
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Common errors
|
|
104
|
+
|
|
105
|
+
| Status | Shape | Content type | Description |
|
|
106
|
+
|---|---|---|---|
|
|
107
|
+
| `400` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | The query was empty, the collection is not one this deployment serves, or a payer-partitioned collection was searched without a payer |
|
|
108
|
+
| `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
|
|
109
|
+
| `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
|
|
110
|
+
| `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
|
|
111
|
+
|
|
112
|
+
## Error examples
|
|
113
|
+
|
|
114
|
+
### 400 — The payer-policy collection was searched without naming a payer
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"error": "payer_key is required when reading 'payer_policy_documents': it is partitioned by payer, so a read must name exactly one payer."
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 400 — The required 'q' field was empty
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"error": "Field 'q' is required"
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 400 — The requested collection is not configured
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"error": "Unknown collection 'nope'. Available: medical_documents, payer_policy_documents"
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### 401 — Missing or invalid access token
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"error": "Authorization required"
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### 500 — Unexpected service failure (sanitized example)
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"error": "Internal server error"
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### 503 — No Milvus endpoint or embedding key is provisioned
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"error": "Vector search is not configured"
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## NodeJS / TypeScript implementation
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
166
|
+
import type { VectorSearchRequest } from "@healthcloudai/hc-sdk";
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
const request = {
|
|
171
|
+
"collection": "string",
|
|
172
|
+
"collection_group": "string",
|
|
173
|
+
"language": "string",
|
|
174
|
+
"network_id": "string",
|
|
175
|
+
"payer_key": "string",
|
|
176
|
+
"q": "string",
|
|
177
|
+
"source": "string",
|
|
178
|
+
"tags": [
|
|
179
|
+
"string"
|
|
180
|
+
],
|
|
181
|
+
"top_k": 10
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
const result = await graph.vectorSearchDocuments(request);
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## cURL
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
curl -X POST \
|
|
191
|
+
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
|
192
|
+
-H 'Content-Type: application/json' \
|
|
193
|
+
-d '{"collection":"string","collection_group":"string","language":"string","network_id":"string","payer_key":"string","q":"string","source":"string","tags":["string"],"top_k":10}' \
|
|
194
|
+
'https://dev-api-graph.health.cloud/graph/vector/search'
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Notes
|
|
198
|
+
|
|
199
|
+
None.
|
|
200
|
+
|
|
201
|
+
## Prepared Test Console scenario
|
|
202
|
+
|
|
203
|
+
No canonical scenario is currently associated.
|
|
204
|
+
|
|
205
|
+
## Real response
|
|
206
|
+
|
|
207
|
+
No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
|
package/package.json
CHANGED