@knowledge-stack/ksapi 1.131.5 → 1.133.0

package/docs/DataSourcesApi.md

@@ -8,14 +8,17 @@ All URIs are relative to *http://localhost:8000*
 | [**deleteDataSource**](DataSourcesApi.md#deletedatasource) | **DELETE** /v1/data-sources/{data_source_id} | Delete Data Source Handler |
 | [**deleteDataSourceSchema**](DataSourcesApi.md#deletedatasourceschema) | **DELETE** /v1/data-sources/{data_source_id}/schemas/{schema_id} | Delete Data Source Schema Handler |
 | [**deleteDataSourceTable**](DataSourcesApi.md#deletedatasourcetable) | **DELETE** /v1/data-sources/{data_source_id}/tables/{table_id} | Delete Data Source Table Handler |
-| [**generateDataSourceDescription**](DataSourcesApi.md#generatedatasourcedescription) | **POST** /v1/data-sources/{data_source_id}/describe | Generate Data Source Description Handler |
+| [**describeDataSourceTables**](DataSourcesApi.md#describedatasourcetables) | **POST** /v1/data-sources/{data_source_id}/describe | Describe Data Source Tables Handler |
 | [**getDataSource**](DataSourcesApi.md#getdatasource) | **GET** /v1/data-sources/{data_source_id} | Get Data Source Handler |
 | [**getDataSourceCatalog**](DataSourcesApi.md#getdatasourcecatalog) | **GET** /v1/data-sources/{data_source_id}/catalog | Get Data Source Catalog Handler |
 | [**listDataSourceSchemas**](DataSourcesApi.md#listdatasourceschemas) | **GET** /v1/data-sources/{data_source_id}/schemas | List Data Source Schemas Handler |
 | [**modelDataSourceTable**](DataSourcesApi.md#modeldatasourcetable) | **POST** /v1/data-sources/{data_source_id}/tables | Model Data Source Table Handler |
 | [**modelDataSourceTables**](DataSourcesApi.md#modeldatasourcetables) | **POST** /v1/data-sources/{data_source_id}/tables/batch | Model Data Source Tables Handler |
 | [**queryDataSource**](DataSourcesApi.md#querydatasource) | **POST** /v1/data-sources/{data_source_id}/query | Query Data Source Handler |
+| [**searchDataSourceTables**](DataSourcesApi.md#searchdatasourcetables) | **POST** /v1/data-sources/tables/search | Search Data Source Tables Handler |
+| [**syncDataSource**](DataSourcesApi.md#syncdatasource) | **POST** /v1/data-sources/{data_source_id}/sync | Sync Data Source Handler |
 | [**testDataSourceConnection**](DataSourcesApi.md#testdatasourceconnection) | **POST** /v1/data-sources/{data_source_id}/test | Test Data Source Connection Handler |
+| [**testDataSourceConnectionFresh**](DataSourcesApi.md#testdatasourceconnectionfresh) | **POST** /v1/data-sources/test-connection | Test Data Source Connection Fresh Handler |
 | [**updateDataSource**](DataSourcesApi.md#updatedatasourceoperation) | **PATCH** /v1/data-sources/{data_source_id} | Update Data Source Handler |
 | [**updateDataSourceTable**](DataSourcesApi.md#updatedatasourcetable) | **PATCH** /v1/data-sources/{data_source_id}/tables/{table_id} | Update Data Source Table Handler |
 
@@ -102,7 +105,7 @@ example().catch(console.error);
 
 Delete Data Source Handler
 
-Move a connector and its schemas/tables to trash.  Soft-delete via the path_part subtree (schemas + tables are children, so they trash with it). The connector\'s generated ``.overview`` description Document IS ingested, so its Qdrant points are flipped to trashed via the set-trashed workflow (best-effort, mirrors the document delete path).
+Move a connector and its schemas/tables to trash.  Soft-delete via the path_part subtree (schemas + tables are children, so they trash with it). Each modeled table\'s summary Qdrant point carries that table\'s path_part, so the set-trashed workflow flips it to trashed too — keeping trashed tables out of the agent\'s table search (best-effort, mirrors the document delete path).
 
 ### Example
 
@@ -255,7 +258,7 @@ example().catch(console.error);
 
 Delete Data Source Table Handler
 
-Un-model a single table (hard-delete it from its schema).
+Un-model a single table (hard-delete it) and purge its summary point.
 
 ### Example
 
@@ -327,13 +330,13 @@ example().catch(console.error);
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
-## generateDataSourceDescription
+## describeDataSourceTables
 
-> DataSourceDescriptionResponse generateDataSourceDescription(dataSourceId)
+> DataSourceDescribeResponse describeDataSourceTables(dataSourceId)
 
-Generate Data Source Description Handler
+Describe Data Source Tables Handler
 
-(Re)generate the connector\'s hidden, searchable \'Database overview\' Document.  Requires ``can_write`` on the connector. The structural overview is deterministic; an LLM prose summary is prepended best-effort. The document ingests through the normal pipeline so the agent\'s semantic search finds it.
+Summarize + embed each modeled table so the agent can find it by meaning.  Requires ``can_write`` on the connector. Writes one dense Qdrant point per table (``object_kind=table_description``) so the agent\'s table search surfaces the right table across the corpus, while users never see the summaries in ordinary chunk search. Content-hash gated: a table whose summary + exposed columns are unchanged makes no LLM/embedding call, so a repeat call is cheap.
 
 ### Example
 
@@ -342,7 +345,7 @@ import {
   Configuration,
   DataSourcesApi,
 } from '@knowledge-stack/ksapi';
-import type { GenerateDataSourceDescriptionRequest } from '@knowledge-stack/ksapi';
+import type { DescribeDataSourceTablesRequest } from '@knowledge-stack/ksapi';
 
 async function example() {
   console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
@@ -357,10 +360,10 @@ async function example() {
   const body = {
     // string
     dataSourceId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
-  } satisfies GenerateDataSourceDescriptionRequest;
+  } satisfies DescribeDataSourceTablesRequest;
 
   try {
-    const data = await api.generateDataSourceDescription(body);
+    const data = await api.describeDataSourceTables(body);
     console.log(data);
   } catch (error) {
     console.error(error);
@@ -380,7 +383,7 @@ example().catch(console.error);
 
 ### Return type
 
-[**DataSourceDescriptionResponse**](DataSourceDescriptionResponse.md)
+[**DataSourceDescribeResponse**](DataSourceDescribeResponse.md)
 
 ### Authorization
 
@@ -864,6 +867,156 @@ example().catch(console.error);
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
+## searchDataSourceTables
+
+> SearchTablesResponse searchDataSourceTables(searchTablesRequest)
+
+Search Data Source Tables Handler
+
+Find modeled tables by the meaning of their summaries (agent discovery).  Dense semantic search over each table\'s summary, scoped to the tenant (optionally one connector). Only tables the caller can read are returned; users never see these summaries in ordinary chunk search.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  DataSourcesApi,
+} from '@knowledge-stack/ksapi';
+import type { SearchDataSourceTablesRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const config = new Configuration({ 
+    // To configure API key authorization: cookieAuth
+    apiKey: "YOUR API KEY",
+    // Configure HTTP bearer authorization: bearerAuth
+    accessToken: "YOUR BEARER TOKEN",
+  });
+  const api = new DataSourcesApi(config);
+
+  const body = {
+    // SearchTablesRequest
+    searchTablesRequest: ...,
+  } satisfies SearchDataSourceTablesRequest;
+
+  try {
+    const data = await api.searchDataSourceTables(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **searchTablesRequest** | [SearchTablesRequest](SearchTablesRequest.md) |  | |
+
+### Return type
+
+[**SearchTablesResponse**](SearchTablesResponse.md)
+
+### Authorization
+
+[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: `application/json`
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+| **0** | Error response. |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
+## syncDataSource
+
+> DataSourceSyncResponse syncDataSource(dataSourceId)
+
+Sync Data Source Handler
+
+Reconcile modeled tables against the live external catalog.  Requires ``can_write``. Re-introspects each modeled schema and, per table: a schema change (columns added/removed/retyped) refreshes ``column_config`` (preserving the admin\'s ``exposed``/``comment`` field-modeling) and re-summarizes + re-embeds; an unchanged table is a no-op; a table dropped from the source is soft-deleted (keeping the \"was modeled, now gone\" record) and its embedding purged. It never models tables that were not imported.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  DataSourcesApi,
+} from '@knowledge-stack/ksapi';
+import type { SyncDataSourceRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const config = new Configuration({ 
+    // To configure API key authorization: cookieAuth
+    apiKey: "YOUR API KEY",
+    // Configure HTTP bearer authorization: bearerAuth
+    accessToken: "YOUR BEARER TOKEN",
+  });
+  const api = new DataSourcesApi(config);
+
+  const body = {
+    // string
+    dataSourceId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+  } satisfies SyncDataSourceRequest;
+
+  try {
+    const data = await api.syncDataSource(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **dataSourceId** | `string` |  | [Defaults to `undefined`] |
+
+### Return type
+
+[**DataSourceSyncResponse**](DataSourceSyncResponse.md)
+
+### Authorization
+
+[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+| **0** | Error response. |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
 ## testDataSourceConnection
 
 > testDataSourceConnection(dataSourceId)
@@ -939,13 +1092,88 @@ example().catch(console.error);
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
+## testDataSourceConnectionFresh
+
+> TestConnectionResponse testDataSourceConnectionFresh(testConnectionRequest)
+
+Test Data Source Connection Fresh Handler
+
+Probe fresh creds or a stored connector without persisting anything.  Returns a 200 body describing success/failure (vs the 400 the create/test routes raise) so the FE can render inline connection validation.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  DataSourcesApi,
+} from '@knowledge-stack/ksapi';
+import type { TestDataSourceConnectionFreshRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const config = new Configuration({ 
+    // To configure API key authorization: cookieAuth
+    apiKey: "YOUR API KEY",
+    // Configure HTTP bearer authorization: bearerAuth
+    accessToken: "YOUR BEARER TOKEN",
+  });
+  const api = new DataSourcesApi(config);
+
+  const body = {
+    // TestConnectionRequest
+    testConnectionRequest: ...,
+  } satisfies TestDataSourceConnectionFreshRequest;
+
+  try {
+    const data = await api.testDataSourceConnectionFresh(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **testConnectionRequest** | [TestConnectionRequest](TestConnectionRequest.md) |  | |
+
+### Return type
+
+[**TestConnectionResponse**](TestConnectionResponse.md)
+
+### Authorization
+
+[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: `application/json`
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+| **0** | Error response. |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
 ## updateDataSource
 
 > DataSourceResponse updateDataSource(dataSourceId, updateDataSourceRequest)
 
 Update Data Source Handler
 
-Rename and/or move a connector.  Requires ``can_write`` on the connector (and on the destination folder for a move).
+Rename, move, and/or re-credential a connector.  Requires ``can_write`` on the connector (and on the destination folder for a move). Fresh ``connection_config`` is re-validated against the DB before persisting (bad creds → 400, consistent with create); creds are never echoed back. ``engine`` is immutable.
 
 ### Example
 
@@ -1023,7 +1251,7 @@ example().catch(console.error);
 
 Update Data Source Table Handler
 
-Field-modeling: update the table\'s description / column allowlist.
+Field-modeling: update the table\'s column allowlist.
 
 ### Example
 

package/docs/DocumentsApi.md

@@ -325,7 +325,7 @@ example().catch(console.error);
 
 Ingest Document Handler
 
-Upload a file, create document + version, and trigger ingestion workflow.  Returns 201 with the Temporal workflow ID.
+Upload a file, create document + version, and trigger ingestion workflow.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal (anything other than ``pending``/``processing``). There is no completion webhook.
 
 ### Example
 
@@ -411,7 +411,7 @@ example().catch(console.error);
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **201** | Successful Response |  -  |
+| **201** | Successful Response |  * Location - Poll this ingestion-status resource until the pipeline reaches a terminal state. <br>  |
 | **422** | Validation Error |  -  |
 | **0** | Error response. |  -  |
 
@@ -424,7 +424,7 @@ example().catch(console.error);
 
 Ingest Document Version Handler
 
-Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\&#39;s active_version) and the old version\&#39;s Qdrant points are deactivated.  Returns 201 with the Temporal workflow ID.
+Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\&#39;s active_version) and the old version\&#39;s Qdrant points are deactivated.  Returns 201 immediately with the Temporal &#x60;&#x60;workflow_id&#x60;&#x60;. Ingestion runs in the background — poll &#x60;&#x60;GET /v1/system-jobs/document_versions/{workflow_id}&#x60;&#x60; (also given in the &#x60;&#x60;Location&#x60;&#x60; header) until &#x60;&#x60;status&#x60;&#x60; is terminal.
 
 ### Example
 
@@ -507,7 +507,7 @@ example().catch(console.error);
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **201** | Successful Response |  -  |
+| **201** | Successful Response |  * Location - Poll this ingestion-status resource until the pipeline reaches a terminal state. <br>  |
 | **422** | Validation Error |  -  |
 | **0** | Error response. |  -  |
 

package/docs/FolderResponseOrDocumentResponseOrWorkflowDefinitionResponseOrWorkflowRunResponseOrDataSourceResponseOrDataSourceSchemaResponseOrDataSourceTableResponseOrApiConnectionResponse.md

@@ -44,14 +44,9 @@ Name | Type
 `error` | string
 `autoStart` | boolean
 `autoStartUserMessage` | string
-`inputsPathPartId` | string
-`outputsPathPartId` | string
-`discussionsPathPartId` | string
-`inputPathPartIds` | Array<string>
-`outputAssets` | [Array<WorkflowRunAsset>](WorkflowRunAsset.md)
-`inputAssets` | [Array<WorkflowRunAsset>](WorkflowRunAsset.md)
-`inputsPath` | string
-`outputsPath` | string
+`inputs` | [RunFolder](RunFolder.md)
+`outputs` | [RunFolder](RunFolder.md)
+`discussions` | [RunFolderRef](RunFolderRef.md)
 `excludedCommonFiles` | [Array<ExcludedCommonFile>](ExcludedCommonFile.md)
 `runThreadId` | string
 `engine` | [DataSourceEngine](DataSourceEngine.md)
@@ -114,14 +109,9 @@ const example = {
   "error": null,
   "autoStart": null,
   "autoStartUserMessage": null,
-  "inputsPathPartId": null,
-  "outputsPathPartId": null,
-  "discussionsPathPartId": null,
-  "inputPathPartIds": null,
-  "outputAssets": null,
-  "inputAssets": null,
-  "inputsPath": null,
-  "outputsPath": null,
+  "inputs": null,
+  "outputs": null,
+  "discussions": null,
   "excludedCommonFiles": null,
   "runThreadId": null,
   "engine": null,

package/docs/ModelTableRequest.md

@@ -10,7 +10,6 @@ Name | Type
 `tableName` | string
 `schemaName` | string
 `name` | string
-`description` | string
 `columnConfig` | [Array<ColumnConfig>](ColumnConfig.md)
 
 ## Example
@@ -23,7 +22,6 @@ const example = {
   "tableName": null,
   "schemaName": null,
   "name": null,
-  "description": null,
   "columnConfig": null,
 } satisfies ModelTableRequest
 

package/docs/RunFolder.md

@@ -0,0 +1,41 @@
+
+# RunFolder
+
+A run subfolder plus its resolved assets (``inputs/`` or ``outputs/``).
+
+## Properties
+
+Name | Type
+------------ | -------------
+`id` | string
+`pathPartId` | string
+`materializedPath` | string
+`assets` | [Array<WorkflowRunAsset>](WorkflowRunAsset.md)
+
+## Example
+
+```typescript
+import type { RunFolder } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "id": null,
+  "pathPartId": null,
+  "materializedPath": null,
+  "assets": null,
+} satisfies RunFolder
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as RunFolder
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/RunFolderRef.md

@@ -0,0 +1,39 @@
+
+# RunFolderRef
+
+A run\'s managed subfolder (inputs / outputs / discussions).  ``id`` is the FOLDER PDO id — pass it to ``list_folder_contents`` or ``bulk-download`` (``folder_ids``) to act on the whole folder in one call. ``path_part_id`` is the underlying path part.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`id` | string
+`pathPartId` | string
+`materializedPath` | string
+
+## Example
+
+```typescript
+import type { RunFolderRef } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "id": null,
+  "pathPartId": null,
+  "materializedPath": null,
+} satisfies RunFolderRef
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as RunFolderRef
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/{DataSourceDescriptionResponse.md → SearchTablesRequest.md}

@@ -1,25 +1,29 @@
 
-# DataSourceDescriptionResponse
+# SearchTablesRequest
 
-Result of (re)generating a connector\'s searchable description Document.
+Semantic search over connector table summaries (agent table discovery).
 
 ## Properties
 
 Name | Type
 ------------ | -------------
+`query` | string
+`topK` | number
+`scoreThreshold` | number
 `dataSourceId` | string
-`descriptionDocumentId` | string
 
 ## Example
 
 ```typescript
-import type { DataSourceDescriptionResponse } from '@knowledge-stack/ksapi'
+import type { SearchTablesRequest } from '@knowledge-stack/ksapi'
 
 // TODO: Update the object below with actual values
 const example = {
+  "query": null,
+  "topK": null,
+  "scoreThreshold": null,
   "dataSourceId": null,
-  "descriptionDocumentId": null,
-} satisfies DataSourceDescriptionResponse
+} satisfies SearchTablesRequest
 
 console.log(example)
 
@@ -28,7 +32,7 @@ const exampleJSON: string = JSON.stringify(example)
 console.log(exampleJSON)
 
 // Parse the JSON string back to an object
-const exampleParsed = JSON.parse(exampleJSON) as DataSourceDescriptionResponse
+const exampleParsed = JSON.parse(exampleJSON) as SearchTablesRequest
 console.log(exampleParsed)
 ```
 

package/docs/SearchTablesResponse.md

@@ -0,0 +1,35 @@
+
+# SearchTablesResponse
+
+Ranked tables matching a summary search (readable by the caller).
+
+## Properties
+
+Name | Type
+------------ | -------------
+`results` | [Array<TableSearchResult>](TableSearchResult.md)
+
+## Example
+
+```typescript
+import type { SearchTablesResponse } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "results": null,
+} satisfies SearchTablesResponse
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as SearchTablesResponse
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+