@knowledge-stack/ksapi 3.5.1 → 3.6.0

package/docs/DiagnosticsApi.md

@@ -0,0 +1,160 @@
+# DiagnosticsApi
+
+All URIs are relative to *http://localhost:8000*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**computeThreadDiagnostics**](DiagnosticsApi.md#computethreaddiagnostics) | **POST** /v1/diagnostics/threads/{thread_id} | Compute Thread Diagnostics Handler |
+| [**computeWorkflowRunDiagnostics**](DiagnosticsApi.md#computeworkflowrundiagnostics) | **POST** /v1/diagnostics/workflow-runs/{run_id} | Compute Workflow Run Diagnostics Handler |
+
+
+
+## computeThreadDiagnostics
+
+> DiagnosticsResponse computeThreadDiagnostics(threadId)
+
+Compute Thread Diagnostics Handler
+
+Stats and trace links for every turn; a run\'s thread answers as its run.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  DiagnosticsApi,
+} from '@knowledge-stack/ksapi';
+import type { ComputeThreadDiagnosticsRequest } 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 DiagnosticsApi(config);
+
+  const body = {
+    // string
+    threadId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+  } satisfies ComputeThreadDiagnosticsRequest;
+
+  try {
+    const data = await api.computeThreadDiagnostics(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **threadId** | `string` |  | [Defaults to `undefined`] |
+
+### Return type
+
+[**DiagnosticsResponse**](DiagnosticsResponse.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)
+
+
+## computeWorkflowRunDiagnostics
+
+> DiagnosticsResponse computeWorkflowRunDiagnostics(runId)
+
+Compute Workflow Run Diagnostics Handler
+
+Stats and trace links for the run\'s attempts and every turn in its thread.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  DiagnosticsApi,
+} from '@knowledge-stack/ksapi';
+import type { ComputeWorkflowRunDiagnosticsRequest } 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 DiagnosticsApi(config);
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+  } satisfies ComputeWorkflowRunDiagnosticsRequest;
+
+  try {
+    const data = await api.computeWorkflowRunDiagnostics(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+
+### Return type
+
+[**DiagnosticsResponse**](DiagnosticsResponse.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)
+

package/docs/DiagnosticsResponse.md

@@ -0,0 +1,36 @@
+
+# DiagnosticsResponse
+
+
+## Properties
+
+Name | Type
+------------ | -------------
+`_final` | boolean
+`traces` | [Array<DiagnosticTraceItem>](DiagnosticTraceItem.md)
+
+## Example
+
+```typescript
+import type { DiagnosticsResponse } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "_final": null,
+  "traces": null,
+} satisfies DiagnosticsResponse
+
+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 DiagnosticsResponse
+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/TraceKind.md

@@ -0,0 +1,32 @@
+
+# TraceKind
+
+
+## Properties
+
+Name | Type
+------------ | -------------
+
+## Example
+
+```typescript
+import type { TraceKind } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+} satisfies TraceKind
+
+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 TraceKind
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledge-stack/ksapi",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "OpenAPI client for @knowledge-stack/ksapi",
   "author": "OpenAPI-Generator",
   "repository": {

package/src/apis/DiagnosticsApi.ts

@@ -0,0 +1,211 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+import * as runtime from '../runtime';
+import type {
+  DiagnosticsResponse,
+  ErrorResponse,
+  HTTPValidationError,
+} from '../models/index';
+import {
+    DiagnosticsResponseFromJSON,
+    DiagnosticsResponseToJSON,
+    ErrorResponseFromJSON,
+    ErrorResponseToJSON,
+    HTTPValidationErrorFromJSON,
+    HTTPValidationErrorToJSON,
+} from '../models/index';
+
+export interface ComputeThreadDiagnosticsRequest {
+    threadId: string;
+}
+
+export interface ComputeWorkflowRunDiagnosticsRequest {
+    runId: string;
+}
+
+/**
+ * DiagnosticsApi - interface
+ * 
+ * @export
+ * @interface DiagnosticsApiInterface
+ */
+export interface DiagnosticsApiInterface {
+    /**
+     * Creates request options for computeThreadDiagnostics without sending the request
+     * @param {string} threadId 
+     * @throws {RequiredError}
+     * @memberof DiagnosticsApiInterface
+     */
+    computeThreadDiagnosticsRequestOpts(requestParameters: ComputeThreadDiagnosticsRequest): Promise<runtime.RequestOpts>;
+
+    /**
+     * Stats and trace links for every turn; a run\'s thread answers as its run.
+     * @summary Compute Thread Diagnostics Handler
+     * @param {string} threadId 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof DiagnosticsApiInterface
+     */
+    computeThreadDiagnosticsRaw(requestParameters: ComputeThreadDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DiagnosticsResponse>>;
+
+    /**
+     * Stats and trace links for every turn; a run\'s thread answers as its run.
+     * Compute Thread Diagnostics Handler
+     */
+    computeThreadDiagnostics(requestParameters: ComputeThreadDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DiagnosticsResponse>;
+
+    /**
+     * Creates request options for computeWorkflowRunDiagnostics without sending the request
+     * @param {string} runId 
+     * @throws {RequiredError}
+     * @memberof DiagnosticsApiInterface
+     */
+    computeWorkflowRunDiagnosticsRequestOpts(requestParameters: ComputeWorkflowRunDiagnosticsRequest): Promise<runtime.RequestOpts>;
+
+    /**
+     * Stats and trace links for the run\'s attempts and every turn in its thread.
+     * @summary Compute Workflow Run Diagnostics Handler
+     * @param {string} runId 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof DiagnosticsApiInterface
+     */
+    computeWorkflowRunDiagnosticsRaw(requestParameters: ComputeWorkflowRunDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DiagnosticsResponse>>;
+
+    /**
+     * Stats and trace links for the run\'s attempts and every turn in its thread.
+     * Compute Workflow Run Diagnostics Handler
+     */
+    computeWorkflowRunDiagnostics(requestParameters: ComputeWorkflowRunDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DiagnosticsResponse>;
+
+}
+
+/**
+ * 
+ */
+export class DiagnosticsApi extends runtime.BaseAPI implements DiagnosticsApiInterface {
+
+    /**
+     * Creates request options for computeThreadDiagnostics without sending the request
+     */
+    async computeThreadDiagnosticsRequestOpts(requestParameters: ComputeThreadDiagnosticsRequest): Promise<runtime.RequestOpts> {
+        if (requestParameters['threadId'] == null) {
+            throw new runtime.RequiredError(
+                'threadId',
+                'Required parameter "threadId" was null or undefined when calling computeThreadDiagnostics().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerAuth", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/diagnostics/threads/{thread_id}`;
+        urlPath = urlPath.replace(`{${"thread_id"}}`, encodeURIComponent(String(requestParameters['threadId'])));
+
+        return {
+            path: urlPath,
+            method: 'POST',
+            headers: headerParameters,
+            query: queryParameters,
+        };
+    }
+
+    /**
+     * Stats and trace links for every turn; a run\'s thread answers as its run.
+     * Compute Thread Diagnostics Handler
+     */
+    async computeThreadDiagnosticsRaw(requestParameters: ComputeThreadDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DiagnosticsResponse>> {
+        const requestOptions = await this.computeThreadDiagnosticsRequestOpts(requestParameters);
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => DiagnosticsResponseFromJSON(jsonValue));
+    }
+
+    /**
+     * Stats and trace links for every turn; a run\'s thread answers as its run.
+     * Compute Thread Diagnostics Handler
+     */
+    async computeThreadDiagnostics(requestParameters: ComputeThreadDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DiagnosticsResponse> {
+        const response = await this.computeThreadDiagnosticsRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
+    /**
+     * Creates request options for computeWorkflowRunDiagnostics without sending the request
+     */
+    async computeWorkflowRunDiagnosticsRequestOpts(requestParameters: ComputeWorkflowRunDiagnosticsRequest): Promise<runtime.RequestOpts> {
+        if (requestParameters['runId'] == null) {
+            throw new runtime.RequiredError(
+                'runId',
+                'Required parameter "runId" was null or undefined when calling computeWorkflowRunDiagnostics().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerAuth", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/diagnostics/workflow-runs/{run_id}`;
+        urlPath = urlPath.replace(`{${"run_id"}}`, encodeURIComponent(String(requestParameters['runId'])));
+
+        return {
+            path: urlPath,
+            method: 'POST',
+            headers: headerParameters,
+            query: queryParameters,
+        };
+    }
+
+    /**
+     * Stats and trace links for the run\'s attempts and every turn in its thread.
+     * Compute Workflow Run Diagnostics Handler
+     */
+    async computeWorkflowRunDiagnosticsRaw(requestParameters: ComputeWorkflowRunDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DiagnosticsResponse>> {
+        const requestOptions = await this.computeWorkflowRunDiagnosticsRequestOpts(requestParameters);
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => DiagnosticsResponseFromJSON(jsonValue));
+    }
+
+    /**
+     * Stats and trace links for the run\'s attempts and every turn in its thread.
+     * Compute Workflow Run Diagnostics Handler
+     */
+    async computeWorkflowRunDiagnostics(requestParameters: ComputeWorkflowRunDiagnosticsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DiagnosticsResponse> {
+        const response = await this.computeWorkflowRunDiagnosticsRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
+}

package/src/apis/index.ts

@@ -15,6 +15,7 @@ export * from './ChunkLineagesApi';
 export * from './ChunksApi';
 export * from './DataSourcesApi';
 export * from './DefaultApi';
+export * from './DiagnosticsApi';
 export * from './DocumentCheckoutApi';
 export * from './DocumentVersionsApi';
 export * from './DocumentsApi';

package/src/models/DiagnosticTraceFailureReason.ts

@@ -0,0 +1,55 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+/**
+ * 
+ * @export
+ */
+export const DiagnosticTraceFailureReason = {
+    TooLarge: 'too_large',
+    ClickhouseError: 'clickhouse_error',
+    MalformedTrace: 'malformed_trace',
+    NoTrace: 'no_trace'
+} as const;
+export type DiagnosticTraceFailureReason = typeof DiagnosticTraceFailureReason[keyof typeof DiagnosticTraceFailureReason];
+
+
+export function instanceOfDiagnosticTraceFailureReason(value: any): boolean {
+    for (const key in DiagnosticTraceFailureReason) {
+        if (Object.prototype.hasOwnProperty.call(DiagnosticTraceFailureReason, key)) {
+            if (DiagnosticTraceFailureReason[key as keyof typeof DiagnosticTraceFailureReason] === value) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+export function DiagnosticTraceFailureReasonFromJSON(json: any): DiagnosticTraceFailureReason {
+    return DiagnosticTraceFailureReasonFromJSONTyped(json, false);
+}
+
+export function DiagnosticTraceFailureReasonFromJSONTyped(json: any, ignoreDiscriminator: boolean): DiagnosticTraceFailureReason {
+    return json as DiagnosticTraceFailureReason;
+}
+
+export function DiagnosticTraceFailureReasonToJSON(value?: DiagnosticTraceFailureReason | null): any {
+    return value as any;
+}
+
+export function DiagnosticTraceFailureReasonToJSONTyped(value: any, ignoreDiscriminator: boolean): DiagnosticTraceFailureReason {
+    return value as DiagnosticTraceFailureReason;
+}
+