hanzo_client/apis/
knowledge_api.rs

1/*
2 * Hanzo Cloud API
3 *
4 * The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
5 *
6 * The version of the OpenAPI document: v1
7 * 
8 * Generated by: https://openapi-generator.tech
9 */
10
11
12use reqwest;
13use serde::{Deserialize, Serialize, de::Error as _};
14use crate::{apis::ResponseContent, models};
15use super::{Error, configuration, ContentType};
16
17
18/// struct for typed errors of method [`delete_knowledge_connectors_by_provider`]
19#[derive(Debug, Clone, Serialize, Deserialize)]
20#[serde(untagged)]
21pub enum DeleteKnowledgeConnectorsByProviderError {
22    UnknownValue(serde_json::Value),
23}
24
25/// struct for typed errors of method [`get_knowledge_connectors`]
26#[derive(Debug, Clone, Serialize, Deserialize)]
27#[serde(untagged)]
28pub enum GetKnowledgeConnectorsError {
29    UnknownValue(serde_json::Value),
30}
31
32/// struct for typed errors of method [`get_knowledge_connectors_by_provider_callback`]
33#[derive(Debug, Clone, Serialize, Deserialize)]
34#[serde(untagged)]
35pub enum GetKnowledgeConnectorsByProviderCallbackError {
36    UnknownValue(serde_json::Value),
37}
38
39/// struct for typed errors of method [`get_knowledge_connectors_by_provider_connect`]
40#[derive(Debug, Clone, Serialize, Deserialize)]
41#[serde(untagged)]
42pub enum GetKnowledgeConnectorsByProviderConnectError {
43    UnknownValue(serde_json::Value),
44}
45
46/// struct for typed errors of method [`get_knowledge_connectors_catalog`]
47#[derive(Debug, Clone, Serialize, Deserialize)]
48#[serde(untagged)]
49pub enum GetKnowledgeConnectorsCatalogError {
50    UnknownValue(serde_json::Value),
51}
52
53/// struct for typed errors of method [`get_knowledge_graph`]
54#[derive(Debug, Clone, Serialize, Deserialize)]
55#[serde(untagged)]
56pub enum GetKnowledgeGraphError {
57    UnknownValue(serde_json::Value),
58}
59
60/// struct for typed errors of method [`post_knowledge_connectors_by_provider_sync`]
61#[derive(Debug, Clone, Serialize, Deserialize)]
62#[serde(untagged)]
63pub enum PostKnowledgeConnectorsByProviderSyncError {
64    UnknownValue(serde_json::Value),
65}
66
67/// struct for typed errors of method [`post_knowledge_import`]
68#[derive(Debug, Clone, Serialize, Deserialize)]
69#[serde(untagged)]
70pub enum PostKnowledgeImportError {
71    UnknownValue(serde_json::Value),
72}
73
74/// struct for typed errors of method [`post_knowledge_search`]
75#[derive(Debug, Clone, Serialize, Deserialize)]
76#[serde(untagged)]
77pub enum PostKnowledgeSearchError {
78    UnknownValue(serde_json::Value),
79}
80
81
82/// Revokes a connection: it tombstones the stored credential so a later sync cannot reuse it, purges this provider's points from the org's vector namespace, and marks the connector disconnected. The documents already ingested stay in the org's store — they are the org's own data — but stop being retrievable by search; a caller deletes them through the document surface.
83pub async fn delete_knowledge_connectors_by_provider(configuration: &configuration::Configuration, provider: &str) -> Result<models::ConnectionOut, Error<DeleteKnowledgeConnectorsByProviderError>> {
84    // add a prefix to parameters to efficiently prevent name collisions
85    let p_provider = provider;
86
87    let uri_str = format!("{}/v1/knowledge/connectors/{provider}", configuration.base_path, provider=crate::apis::urlencode(p_provider));
88    let mut req_builder = configuration.client.request(reqwest::Method::DELETE, &uri_str);
89
90    if let Some(ref user_agent) = configuration.user_agent {
91        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
92    }
93    if let Some(ref token) = configuration.bearer_access_token {
94        req_builder = req_builder.bearer_auth(token.to_owned());
95    };
96
97    let req = req_builder.build()?;
98    let resp = configuration.client.execute(req).await?;
99
100    let status = resp.status();
101    let content_type = resp
102        .headers()
103        .get("content-type")
104        .and_then(|v| v.to_str().ok())
105        .unwrap_or("application/octet-stream");
106    let content_type = super::ContentType::from(content_type);
107
108    if !status.is_client_error() && !status.is_server_error() {
109        let content = resp.text().await?;
110        match content_type {
111            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
112            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::ConnectionOut`"))),
113            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::ConnectionOut`")))),
114        }
115    } else {
116        let content = resp.text().await?;
117        let entity: Option<DeleteKnowledgeConnectorsByProviderError> = serde_json::from_str(&content).ok();
118        Err(Error::ResponseError(ResponseContent { status, content, entity }))
119    }
120}
121
122/// Returns every supported knowledge connector with THIS org's connection state and the REAL number of documents each has ingested into the org's store. A provider that is configured for the deployment but not yet connected appears as disconnected, so the console can offer a Connect button. No secret is ever returned.
123pub async fn get_knowledge_connectors(configuration: &configuration::Configuration, ) -> Result<models::KbConnectorsOut, Error<GetKnowledgeConnectorsError>> {
124
125    let uri_str = format!("{}/v1/knowledge/connectors", configuration.base_path);
126    let mut req_builder = configuration.client.request(reqwest::Method::GET, &uri_str);
127
128    if let Some(ref user_agent) = configuration.user_agent {
129        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
130    }
131    if let Some(ref token) = configuration.bearer_access_token {
132        req_builder = req_builder.bearer_auth(token.to_owned());
133    };
134
135    let req = req_builder.build()?;
136    let resp = configuration.client.execute(req).await?;
137
138    let status = resp.status();
139    let content_type = resp
140        .headers()
141        .get("content-type")
142        .and_then(|v| v.to_str().ok())
143        .unwrap_or("application/octet-stream");
144    let content_type = super::ContentType::from(content_type);
145
146    if !status.is_client_error() && !status.is_server_error() {
147        let content = resp.text().await?;
148        match content_type {
149            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
150            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::KbConnectorsOut`"))),
151            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::KbConnectorsOut`")))),
152        }
153    } else {
154        let content = resp.text().await?;
155        let entity: Option<GetKnowledgeConnectorsError> = serde_json::from_str(&content).ok();
156        Err(Error::ResponseError(ResponseContent { status, content, entity }))
157    }
158}
159
160/// CompleteConnectorOAuth finishes an OAuth connection: it exchanges the provider's code for a token, seals that token in KMS, and records the connection. THE ORG COMES FROM THE SIGNED STATE, not from a header and not from the provider, so an attacker cannot bind their own account to someone else's org — a tampered, expired or foreign-provider state is refused outright. The token itself is never returned, never written into the document, and never logged; the document holds only its KMS path.
161pub async fn get_knowledge_connectors_by_provider_callback(configuration: &configuration::Configuration, provider: &str, code: Option<&str>, state: Option<&str>, error: Option<&str>) -> Result<models::ConnectionOut, Error<GetKnowledgeConnectorsByProviderCallbackError>> {
162    // add a prefix to parameters to efficiently prevent name collisions
163    let p_provider = provider;
164    let p_code = code;
165    let p_state = state;
166    let p_error = error;
167
168    let uri_str = format!("{}/v1/knowledge/connectors/{provider}/callback", configuration.base_path, provider=crate::apis::urlencode(p_provider));
169    let mut req_builder = configuration.client.request(reqwest::Method::GET, &uri_str);
170
171    if let Some(ref param_value) = p_code {
172        req_builder = req_builder.query(&[("code", &param_value.to_string())]);
173    }
174    if let Some(ref param_value) = p_state {
175        req_builder = req_builder.query(&[("state", &param_value.to_string())]);
176    }
177    if let Some(ref param_value) = p_error {
178        req_builder = req_builder.query(&[("error", &param_value.to_string())]);
179    }
180    if let Some(ref user_agent) = configuration.user_agent {
181        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
182    }
183    if let Some(ref token) = configuration.bearer_access_token {
184        req_builder = req_builder.bearer_auth(token.to_owned());
185    };
186
187    let req = req_builder.build()?;
188    let resp = configuration.client.execute(req).await?;
189
190    let status = resp.status();
191    let content_type = resp
192        .headers()
193        .get("content-type")
194        .and_then(|v| v.to_str().ok())
195        .unwrap_or("application/octet-stream");
196    let content_type = super::ContentType::from(content_type);
197
198    if !status.is_client_error() && !status.is_server_error() {
199        let content = resp.text().await?;
200        match content_type {
201            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
202            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::ConnectionOut`"))),
203            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::ConnectionOut`")))),
204        }
205    } else {
206        let content = resp.text().await?;
207        let entity: Option<GetKnowledgeConnectorsByProviderCallbackError> = serde_json::from_str(&content).ok();
208        Err(Error::ResponseError(ResponseContent { status, content, entity }))
209    }
210}
211
212/// StartConnectorOAuth returns the provider authorize URL the console opens to connect this org's account. There is no server-side redirect — the console stays in control of the navigation. The URL carries a state this server SIGNED over the caller's validated org, so the connection the callback completes can only ever land in that org.
213pub async fn get_knowledge_connectors_by_provider_connect(configuration: &configuration::Configuration, provider: &str) -> Result<models::KbAuthorizeOut, Error<GetKnowledgeConnectorsByProviderConnectError>> {
214    // add a prefix to parameters to efficiently prevent name collisions
215    let p_provider = provider;
216
217    let uri_str = format!("{}/v1/knowledge/connectors/{provider}/connect", configuration.base_path, provider=crate::apis::urlencode(p_provider));
218    let mut req_builder = configuration.client.request(reqwest::Method::GET, &uri_str);
219
220    if let Some(ref user_agent) = configuration.user_agent {
221        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
222    }
223    if let Some(ref token) = configuration.bearer_access_token {
224        req_builder = req_builder.bearer_auth(token.to_owned());
225    };
226
227    let req = req_builder.build()?;
228    let resp = configuration.client.execute(req).await?;
229
230    let status = resp.status();
231    let content_type = resp
232        .headers()
233        .get("content-type")
234        .and_then(|v| v.to_str().ok())
235        .unwrap_or("application/octet-stream");
236    let content_type = super::ContentType::from(content_type);
237
238    if !status.is_client_error() && !status.is_server_error() {
239        let content = resp.text().await?;
240        match content_type {
241            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
242            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::KbAuthorizeOut`"))),
243            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::KbAuthorizeOut`")))),
244        }
245    } else {
246        let content = resp.text().await?;
247        let entity: Option<GetKnowledgeConnectorsByProviderConnectError> = serde_json::from_str(&content).ok();
248        Err(Error::ResponseError(ResponseContent { status, content, entity }))
249    }
250}
251
252/// Returns the ONE catalog of everything a caller can connect: every first-party connector and every long-tail one, in a single list sorted by provider. `configured` reports whether this deployment holds OAuth credentials for a source, so the console can show Connect rather than a dead button, and `kind` is a badge only — the connect and sync lifecycle is identical for both. The catalog itself is org-independent; a validated principal is still required. It is metadata only: no secret is ever returned.
253pub async fn get_knowledge_connectors_catalog(configuration: &configuration::Configuration, ) -> Result<models::CatalogOut, Error<GetKnowledgeConnectorsCatalogError>> {
254
255    let uri_str = format!("{}/v1/knowledge/connectors/catalog", configuration.base_path);
256    let mut req_builder = configuration.client.request(reqwest::Method::GET, &uri_str);
257
258    if let Some(ref user_agent) = configuration.user_agent {
259        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
260    }
261    if let Some(ref token) = configuration.bearer_access_token {
262        req_builder = req_builder.bearer_auth(token.to_owned());
263    };
264
265    let req = req_builder.build()?;
266    let resp = configuration.client.execute(req).await?;
267
268    let status = resp.status();
269    let content_type = resp
270        .headers()
271        .get("content-type")
272        .and_then(|v| v.to_str().ok())
273        .unwrap_or("application/octet-stream");
274    let content_type = super::ContentType::from(content_type);
275
276    if !status.is_client_error() && !status.is_server_error() {
277        let content = resp.text().await?;
278        match content_type {
279            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
280            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::CatalogOut`"))),
281            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::CatalogOut`")))),
282        }
283    } else {
284        let content = resp.text().await?;
285        let entity: Option<GetKnowledgeConnectorsCatalogError> = serde_json::from_str(&content).ok();
286        Err(Error::ResponseError(ResponseContent { status, content, entity }))
287    }
288}
289
290/// Returns the caller org's knowledge as a node/edge graph shaped for a force-directed renderer: pages, memories and synced sources as nodes; the page parent tree, the wikilinks between pages, and each source's connector provenance as edges. Wikilink targets are resolved HERE by title or slug, so a rename never needs an edge rewrite and a link that matches no page renders as its own \"unresolved\" node instead of vanishing. ?project= narrows it. A store outage degrades to an honest empty graph, never a 5xx.
291pub async fn get_knowledge_graph(configuration: &configuration::Configuration, project: Option<&str>) -> Result<models::GraphOut, Error<GetKnowledgeGraphError>> {
292    // add a prefix to parameters to efficiently prevent name collisions
293    let p_project = project;
294
295    let uri_str = format!("{}/v1/knowledge/graph", configuration.base_path);
296    let mut req_builder = configuration.client.request(reqwest::Method::GET, &uri_str);
297
298    if let Some(ref param_value) = p_project {
299        req_builder = req_builder.query(&[("project", &param_value.to_string())]);
300    }
301    if let Some(ref user_agent) = configuration.user_agent {
302        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
303    }
304    if let Some(ref token) = configuration.bearer_access_token {
305        req_builder = req_builder.bearer_auth(token.to_owned());
306    };
307
308    let req = req_builder.build()?;
309    let resp = configuration.client.execute(req).await?;
310
311    let status = resp.status();
312    let content_type = resp
313        .headers()
314        .get("content-type")
315        .and_then(|v| v.to_str().ok())
316        .unwrap_or("application/octet-stream");
317    let content_type = super::ContentType::from(content_type);
318
319    if !status.is_client_error() && !status.is_server_error() {
320        let content = resp.text().await?;
321        match content_type {
322            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
323            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::GraphOut`"))),
324            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::GraphOut`")))),
325        }
326    } else {
327        let content = resp.text().await?;
328        let entity: Option<GetKnowledgeGraphError> = serde_json::from_str(&content).ok();
329        Err(Error::ResponseError(ResponseContent { status, content, entity }))
330    }
331}
332
333/// Pulls the provider's documents for the caller's org and files them as knowledge sources, which the store's own hook then indexes — so a synced document is retrievable exactly like a hand-written page. The org is the validated tenant and the credential is read from KMS, so an org can only ever sync its own connection. A provider failure is reported honestly (502) and recorded on the connector rather than silently swallowed.
334pub async fn post_knowledge_connectors_by_provider_sync(configuration: &configuration::Configuration, provider: &str) -> Result<models::KbSyncOut, Error<PostKnowledgeConnectorsByProviderSyncError>> {
335    // add a prefix to parameters to efficiently prevent name collisions
336    let p_provider = provider;
337
338    let uri_str = format!("{}/v1/knowledge/connectors/{provider}/sync", configuration.base_path, provider=crate::apis::urlencode(p_provider));
339    let mut req_builder = configuration.client.request(reqwest::Method::POST, &uri_str);
340
341    if let Some(ref user_agent) = configuration.user_agent {
342        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
343    }
344    if let Some(ref token) = configuration.bearer_access_token {
345        req_builder = req_builder.bearer_auth(token.to_owned());
346    };
347
348    let req = req_builder.build()?;
349    let resp = configuration.client.execute(req).await?;
350
351    let status = resp.status();
352    let content_type = resp
353        .headers()
354        .get("content-type")
355        .and_then(|v| v.to_str().ok())
356        .unwrap_or("application/octet-stream");
357    let content_type = super::ContentType::from(content_type);
358
359    if !status.is_client_error() && !status.is_server_error() {
360        let content = resp.text().await?;
361        match content_type {
362            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
363            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::KbSyncOut`"))),
364            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::KbSyncOut`")))),
365        }
366    } else {
367        let content = resp.text().await?;
368        let entity: Option<PostKnowledgeConnectorsByProviderSyncError> = serde_json::from_str(&content).ok();
369        Err(Error::ResponseError(ResponseContent { status, content, entity }))
370    }
371}
372
373/// Ingests an uploaded export as a tree of kb-page documents with its link structure intact. `?format=` picks the normalizer — obsidian, notion, roam or evernote — and the export arrives as a multipart `file` part, or as the raw request body when there is no multipart part: an Obsidian or Notion vault zip, a Roam JSON (raw or inside the zip Roam downloads), or an Evernote .enex.  The pages are filed through the SAME ingest path a connector sync uses, so the kb-page hook indexes each one for retrieval AND extracts its `[[wikilinks]]` into kb-link edges — the imported vault is searchable and its graph is navigable without a second pass. Parents are filed before their children, and each page takes a slug unique within the org (suffixed -2, -3, … on collision), so a re-import adds pages rather than overwriting the ones already there.  Scoped to the caller's validated org; `?project=` narrows every imported page to one project. No validated principal is 403, and an org that has not installed the kb module is refused with the install call to make first. The bounds are 64 MB per upload, 5000 pages and 8 MB per archive entry: pages past the five-thousandth are dropped and a larger entry is truncated at its bound, and a page the store rejects is skipped — so the answer's `imported` count is what was actually filed, not what was sent.
374pub async fn post_knowledge_import(configuration: &configuration::Configuration, ) -> Result<(), Error<PostKnowledgeImportError>> {
375
376    let uri_str = format!("{}/v1/knowledge/import", configuration.base_path);
377    let mut req_builder = configuration.client.request(reqwest::Method::POST, &uri_str);
378
379    if let Some(ref user_agent) = configuration.user_agent {
380        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
381    }
382    if let Some(ref token) = configuration.bearer_access_token {
383        req_builder = req_builder.bearer_auth(token.to_owned());
384    };
385
386    let req = req_builder.build()?;
387    let resp = configuration.client.execute(req).await?;
388
389    let status = resp.status();
390
391    if !status.is_client_error() && !status.is_server_error() {
392        Ok(())
393    } else {
394        let content = resp.text().await?;
395        let entity: Option<PostKnowledgeImportError> = serde_json::from_str(&content).ok();
396        Err(Error::ResponseError(ResponseContent { status, content, entity }))
397    }
398}
399
400/// Runs a semantic search over the caller org's own knowledge — its wiki pages, its agent memories and everything its connectors have synced — and returns the matching passages. This is the RAG entry point: an agent asks \"what does this org know about X\" and the org's OWN vector namespace answers. The org comes from the validated principal, and both the collection and the payload filter are pinned to it, so cross-tenant retrieval is impossible. An unreachable index returns an honest empty result set with degraded=true, never a 5xx.
401pub async fn post_knowledge_search(configuration: &configuration::Configuration, search_in: models::SearchIn) -> Result<models::SearchOut, Error<PostKnowledgeSearchError>> {
402    // add a prefix to parameters to efficiently prevent name collisions
403    let p_search_in = search_in;
404
405    let uri_str = format!("{}/v1/knowledge/search", configuration.base_path);
406    let mut req_builder = configuration.client.request(reqwest::Method::POST, &uri_str);
407
408    if let Some(ref user_agent) = configuration.user_agent {
409        req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone());
410    }
411    if let Some(ref token) = configuration.bearer_access_token {
412        req_builder = req_builder.bearer_auth(token.to_owned());
413    };
414    req_builder = req_builder.json(&p_search_in);
415
416    let req = req_builder.build()?;
417    let resp = configuration.client.execute(req).await?;
418
419    let status = resp.status();
420    let content_type = resp
421        .headers()
422        .get("content-type")
423        .and_then(|v| v.to_str().ok())
424        .unwrap_or("application/octet-stream");
425    let content_type = super::ContentType::from(content_type);
426
427    if !status.is_client_error() && !status.is_server_error() {
428        let content = resp.text().await?;
429        match content_type {
430            ContentType::Json => serde_json::from_str(&content).map_err(Error::from),
431            ContentType::Text => return Err(Error::from(serde_json::Error::custom("Received `text/plain` content type response that cannot be converted to `models::SearchOut`"))),
432            ContentType::Unsupported(unknown_type) => return Err(Error::from(serde_json::Error::custom(format!("Received `{unknown_type}` content type response that cannot be converted to `models::SearchOut`")))),
433        }
434    } else {
435        let content = resp.text().await?;
436        let entity: Option<PostKnowledgeSearchError> = serde_json::from_str(&content).ok();
437        Err(Error::ResponseError(ResponseContent { status, content, entity }))
438    }
439}
440
hanzo_client/apis/knowledge_api.rs

hanzo_client/apis/
knowledge_api.rs
