@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.
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-sdk",
3
- "version": "3.3.0",
3
+ "version": "3.4.0",
4
4
  "description": "All-in-one HealthCloud SDK with typed platform APIs and secure connector clients.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",