@healthcloudai/hc-sdk 3.2.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,189 @@
1
+ # Get one document's chunks
2
+
3
+ Operation ID: `graph.getVectorDocumentChunks`
4
+
5
+ Return every stored chunk of one document, ordered by chunk_index. Concatenating them reconstructs the text that was embedded. The doc_id is the identifier carried on each search hit. Reading a document from the payer-policy collection requires payer_key, the same rule the search follows: knowing a document id is not on its own enough to read another payer's policy.
6
+
7
+ ## Public method
8
+
9
+ `getVectorDocumentChunks`
10
+
11
+ Signature: `graph.getVectorDocumentChunks(docId, query)`
12
+
13
+ Return type: `Promise<GetVectorDocumentChunksResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /graph/vector/documents/{doc_id}`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `doc_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
38
+ |---|---|---:|---|---|---|---:|---|
39
+ | `collection` | `string` | No | | | | No | Collection to read from; defaults to the documents corpus |
40
+ | `limit` | `integer` | No | | | `100` | No | |
41
+ | `payer_key` | `string` | No | | | | No | Payer slug; REQUIRED when reading from the payer-policy collection |
42
+
43
+ ## Body parameters
44
+
45
+ None.
46
+
47
+ Request model: None.
48
+
49
+ ## Request example
50
+
51
+ None declared in canonical OpenAPI.
52
+
53
+ ## Success responses
54
+
55
+ | Status | Shape | Content type | Description |
56
+ |---|---|---|---|
57
+ | `200` | [`GetVectorDocumentChunksResponse`](../models/GetVectorDocumentChunksResponse.md) | application/json | The document's chunks, ordered by chunk_index |
58
+
59
+ ## Success response examples
60
+
61
+ ### 200
62
+
63
+ ```json
64
+ {
65
+ "chunk_count": 0,
66
+ "chunks": [
67
+ {
68
+ "chunk_index": 0,
69
+ "collection_group": "string",
70
+ "doc_id": "string",
71
+ "id": "string",
72
+ "language": "string",
73
+ "metadata": {},
74
+ "network_id": "string",
75
+ "payer_key": "string",
76
+ "score": 0,
77
+ "source": "string",
78
+ "tags": [
79
+ "string"
80
+ ],
81
+ "text": "string",
82
+ "title": "string",
83
+ "url": "string"
84
+ }
85
+ ],
86
+ "collection": "string",
87
+ "collection_group": "string",
88
+ "doc_id": "string",
89
+ "language": "string",
90
+ "metadata": {},
91
+ "payer_key": "string",
92
+ "source": "string",
93
+ "tags": [
94
+ "string"
95
+ ],
96
+ "title": "string",
97
+ "url": "string"
98
+ }
99
+ ```
100
+
101
+ ## Common errors
102
+
103
+ | Status | Shape | Content type | Description |
104
+ |---|---|---|---|
105
+ | `400` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | The request was invalid — a required parameter was missing or a filter value was not recognized |
106
+ | `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
107
+ | `404` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | No chunks exist for doc_id in the collection |
108
+ | `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
109
+ | `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
110
+
111
+ ## Error examples
112
+
113
+ ### 400 — A required query parameter was missing or a filter value was not recognized (sanitized example)
114
+
115
+ ```json
116
+ {
117
+ "error": "Bad request"
118
+ }
119
+ ```
120
+
121
+ ### 401 — Missing or invalid access token
122
+
123
+ ```json
124
+ {
125
+ "error": "Authorization required"
126
+ }
127
+ ```
128
+
129
+ ### 404 — The document is not loaded in this collection
130
+
131
+ ```json
132
+ {
133
+ "error": "Document not found in the vector store"
134
+ }
135
+ ```
136
+
137
+ ### 500 — Unexpected service failure (sanitized example)
138
+
139
+ ```json
140
+ {
141
+ "error": "Internal server error"
142
+ }
143
+ ```
144
+
145
+ ### 503 — No Milvus endpoint or embedding key is provisioned
146
+
147
+ ```json
148
+ {
149
+ "error": "Vector search is not configured"
150
+ }
151
+ ```
152
+
153
+ ## NodeJS / TypeScript implementation
154
+
155
+ ```ts
156
+ import { HCSDK } from "@healthcloudai/hc-sdk";
157
+ ```
158
+
159
+ ```ts
160
+ const docId = "<DOC_ID>";
161
+
162
+ const query = {
163
+ "collection": "<COLLECTION>",
164
+ "limit": 100,
165
+ "payer_key": "<PAYER_KEY>"
166
+ };
167
+
168
+ const result = await graph.getVectorDocumentChunks(docId, query);
169
+ ```
170
+
171
+ ## cURL
172
+
173
+ ```bash
174
+ curl -X GET \
175
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
176
+ 'https://dev-api-graph.health.cloud/graph/vector/documents/%3CDOC_ID%3E?collection=%3CCOLLECTION%3E&limit=100&payer_key=%3CPAYER_KEY%3E'
177
+ ```
178
+
179
+ ## Notes
180
+
181
+ None.
182
+
183
+ ## Prepared Test Console scenario
184
+
185
+ No canonical scenario is currently associated.
186
+
187
+ ## Real response
188
+
189
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,138 @@
1
+ # List searchable vector collections
2
+
3
+ Operation ID: `graph.listVectorCollections`
4
+
5
+ List the vector collections this deployment can search, with each one's chunk count, vector width, similarity metric, and whether it is partitioned by payer (which makes payer_key mandatory when reading it). The width is the operationally important field: the collections are loaded by a separate pipeline, so a corpus embedded with a different model has a different width and cannot be searched with this deployment's query vectors at all.
6
+
7
+ ## Public method
8
+
9
+ `listVectorCollections`
10
+
11
+ Signature: `graph.listVectorCollections()`
12
+
13
+ Return type: `Promise<ListVectorCollectionsResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /graph/vector/collections`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ None.
36
+
37
+ ## Body parameters
38
+
39
+ None.
40
+
41
+ Request model: None.
42
+
43
+ ## Request example
44
+
45
+ None declared in canonical OpenAPI.
46
+
47
+ ## Success responses
48
+
49
+ | Status | Shape | Content type | Description |
50
+ |---|---|---|---|
51
+ | `200` | [`ListVectorCollectionsResponse`](../models/ListVectorCollectionsResponse.md) | application/json | Configured collections with chunk count, vector width and metric |
52
+
53
+ ## Success response examples
54
+
55
+ ### 200
56
+
57
+ ```json
58
+ {
59
+ "collections": [
60
+ {
61
+ "available": true,
62
+ "chunk_count": 4211,
63
+ "collection": "medical_documents",
64
+ "detail": null,
65
+ "dimension": 384,
66
+ "metric_type": "COSINE",
67
+ "partitioned_by_payer": false,
68
+ "role": "documents"
69
+ }
70
+ ],
71
+ "embedding_model": "BAAI/bge-small-en-v1.5",
72
+ "total": 1
73
+ }
74
+ ```
75
+
76
+ ## Common errors
77
+
78
+ | Status | Shape | Content type | Description |
79
+ |---|---|---|---|
80
+ | `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
81
+ | `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
82
+ | `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
83
+
84
+ ## Error examples
85
+
86
+ ### 401 — Missing or invalid access token
87
+
88
+ ```json
89
+ {
90
+ "error": "Authorization required"
91
+ }
92
+ ```
93
+
94
+ ### 500 — Unexpected service failure (sanitized example)
95
+
96
+ ```json
97
+ {
98
+ "error": "Internal server error"
99
+ }
100
+ ```
101
+
102
+ ### 503 — No Milvus endpoint or embedding key is provisioned
103
+
104
+ ```json
105
+ {
106
+ "error": "Vector search is not configured"
107
+ }
108
+ ```
109
+
110
+ ## NodeJS / TypeScript implementation
111
+
112
+ ```ts
113
+ import { HCSDK } from "@healthcloudai/hc-sdk";
114
+ ```
115
+
116
+ ```ts
117
+ const result = await graph.listVectorCollections();
118
+ ```
119
+
120
+ ## cURL
121
+
122
+ ```bash
123
+ curl -X GET \
124
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
125
+ 'https://dev-api-graph.health.cloud/graph/vector/collections'
126
+ ```
127
+
128
+ ## Notes
129
+
130
+ None.
131
+
132
+ ## Prepared Test Console scenario
133
+
134
+ No canonical scenario is currently associated.
135
+
136
+ ## Real response
137
+
138
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -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.2.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",