Onboarding : take multiple credentials from endpoint (#453)

nishika26 · web-flow · commit 30ef2681cf22 · 2025-12-09T16:57:53.000+05:30
* first commit will all the changes

* documentation of llm and config

* only stating delete instead of soft delete

* small changes
diff --git a/backend/app/api/docs/collections/create.md b/backend/app/api/docs/collections/create.md
@@ -6,7 +6,7 @@ pipeline:
   documents stored in the cloud (see the `documents` interface).
 * Create an OpenAI [Vector
   Store](https://platform.openai.com/docs/api-reference/vector-stores)
-  based on those File's.
+  based on those file(s).
 * [To be deprecated] Attach the Vector Store to an OpenAI
   [Assistant](https://platform.openai.com/docs/api-reference/assistants). Use
   parameters in the request body relevant to an Assistant to flesh out
@@ -16,15 +16,15 @@ pipeline:
 
 If any one of the OpenAI interactions fail, all OpenAI resources are
 cleaned up. If a Vector Store is unable to be created, for example,
-all File's that were uploaded to OpenAI are removed from
+all file(s) that were uploaded to OpenAI are removed from
 OpenAI. Failure can occur from OpenAI being down, or some parameter
-value being invalid. It can also fail due to document types not be
+value being invalid. It can also fail due to document types not being
 accepted. This is especially true for PDFs that may not be parseable.
 
 Vector store/assistant will be created asynchronously. The immediate response
 from this endpoint is `collection_job` object which is going to contain
-the collection "job ID" and status.Once the collection has been created,
+the collection "job ID" and status. Once the collection has been created,
 information about the collection will be returned to the user via the
 callback URL. If a callback URL is not provided, clients can check the
-`collection job info` endpoint with the `job_id`, to retrieve the
+`collection job info` endpoint with the `job_id`, to retrieve
 information about the creation of collection.
diff --git a/backend/app/api/docs/collections/delete.md b/backend/app/api/docs/collections/delete.md
@@ -1,14 +1,14 @@
 Remove a collection from the platform. This is a two step process:
 
-1. Delete all OpenAI resources that were allocated: File's, the Vector
+1. Delete all OpenAI resources that were allocated: file(s), the Vector
    Store, and the Assistant.
-2. Delete the collection entry from the AI platform database.
+2. Delete the collection entry from the kaapi database.
 
 No action is taken on the documents themselves: the contents of the
 documents that were a part of the collection remain unchanged, those
 documents can still be accessed via the documents endpoints. The response from this
 endpoint will be a `collection_job` object which will contain the collection `job_id` and
-status. when you take the id returned and use the collection job
-info endpoint, if the job is successful, you will get the status as successful.
+status. When you take the id returned and use the `collection job info` endpoint,
+if the job is successful, you will get the status as successful.
 Additionally, if a `callback_url` was provided in the request body,
 you will receive a message indicating whether the deletion was successful or if it failed.
diff --git a/backend/app/api/docs/collections/info.md b/backend/app/api/docs/collections/info.md
@@ -1,4 +1,4 @@
-Retrieve detailed information about `a specific collection by its ID` from the collection table. This endpoint returns the collection object including its project, organization,
-timestamps, and associated LLM service details (`llm_service_id`).
+Retrieve detailed information about a specific collection by its collection id. This endpoint returns the collection object including its project, organization,
+timestamps, and associated LLM service details (`llm_service_id` and `llm_service_name`).
 
-Additionally, if the `include_docs` flag in the request body is true then you will get a list of document IDs associated with a given collection as well. Documents returned are not only stored by the AI platform, but also by OpenAI.
+Additionally, if the `include_docs` flag in the request body is true then you will get a list of document IDs associated with a given collection as well. Note that, documents returned are not only stored by the AI platform, but also by OpenAI.
diff --git a/backend/app/api/docs/collections/job_info.md b/backend/app/api/docs/collections/job_info.md
@@ -3,7 +3,7 @@ Retrieve information about a collection job by the collection job ID. This endpo
 * Fetching the collection job object, including the collection job ID, the current status, and the associated collection details.
 
 * If the job has finished, has been successful and it was a job of creation of collection then this endpoint will fetch the associated collection details from the collection table, including:
-  - `llm_service_id`: The OpenAI assistant or model used for the collection.
+  - `llm_service_id` and `llm_service_name`.
   - Collection metadata such as ID, project, organization, and timestamps.
 
-* If the delete-collection job succeeds, the status is set to “successful” and the `collection_key` contains the ID of the collection that has been deleted.
+* If the delete-collection job succeeds, the status is set to “successful” and the `collection` key contains the ID of the collection that has been deleted.
diff --git a/backend/app/api/docs/collections/list.md b/backend/app/api/docs/collections/list.md
@@ -3,4 +3,4 @@ not deleted
 
 If a vector store was created - `llm_service_name` and `llm_service_id` in the response denote the name of the vector store (eg. 'openai vector store') and its id.
 
-[To be deprecated] If an assistant was created, `llm_service_name` and `llm_service_id` in the response denote the name of the model used in the assistant (eg. 'gpt-4o') and assistant id.
+[To be deprecated] If an assistant was created, `llm_service_name` and `llm_service_id` in the response denotes the name of the model used in the assistant (eg. 'gpt-4o') and assistant id.
diff --git a/backend/app/api/docs/config/create.md b/backend/app/api/docs/config/create.md
@@ -0,0 +1,34 @@
+Create a new LLM configuration with an initial version.
+
+Configurations allow you to store and manage reusable LLM parameters
+(such as temperature, max_tokens, model selection, etc.) with version control.
+
+**Key Features:**
+* Automatically creates an initial version (v1) with the provided configuration
+* Enforces unique configuration names per project
+* Stores provider-specific parameters as flexible JSON (config_blob)
+* Supports optional commit messages for tracking changes
+* Provider-agnostic storage - params are passed through to the provider as-is
+
+
+**Example for the config blob: OpenAI Responses API with File Search**
+
+```json
+"config_blob": {
+    "completion": {
+      "provider": "openai",
+      "params": {
+        "model": "gpt-4o-mini",
+        "instructions": "You are a helpful assistant for farming communities...",
+        "temperature": 1,
+        "tools": [
+          {
+            "type": "file_search",
+            "vector_store_ids": ["vs_692d71f3f5708191b1c46525f3c1e196"],
+            "max_num_results": 20
+          }]}}}
+```
+
+The configuration name must be unique within your project. Once created,
+you can create additional versions to track parameter changes while
+maintaining the configuration history.
diff --git a/backend/app/api/docs/config/create_version.md b/backend/app/api/docs/config/create_version.md
@@ -0,0 +1,7 @@
+Create a new version for an existing configuration.
+
+To create a new version, provide the `config_id` in the URL path and the new
+configuration parameters in the request body. The system will automatically
+create a new version under the same configuration with an incremented version number.
+Version numbers are automatically incremented sequentially (1, 2, 3, etc.)
+and cannot be manually set or skipped.
diff --git a/backend/app/api/docs/config/delete.md b/backend/app/api/docs/config/delete.md
@@ -0,0 +1,5 @@
+Delete a configuration and all its versions.
+
+This operation performs a delete, marking the configuration and all
+associated versions as deleted in the database while retaining records
+for audit purposes.
diff --git a/backend/app/api/docs/config/delete_version.md b/backend/app/api/docs/config/delete_version.md
@@ -0,0 +1,4 @@
+Delete a specific version of a configuration.
+
+Performs a delete on the version, marking it as deleted while
+retaining the record for audit purposes.
diff --git a/backend/app/api/docs/config/get.md b/backend/app/api/docs/config/get.md
@@ -0,0 +1,5 @@
+Retrieve a specific configuration by its ID.
+
+Returns the configuration metadata including name, description, and
+timestamps. This endpoint provides configuration-level details but does
+not include version information.
diff --git a/backend/app/api/docs/config/get_version.md b/backend/app/api/docs/config/get_version.md
@@ -0,0 +1,4 @@
+Retrieve a specific version of a configuration.
+
+Returns the complete version details including the full configuration
+blob (config_blob) with all LLM parameters.
diff --git a/backend/app/api/docs/config/list.md b/backend/app/api/docs/config/list.md
@@ -0,0 +1,5 @@
+Retrieve all configurations for the current project.
+
+Returns a paginated list of configurations ordered by most recently
+updated first. Each configuration includes metadata (name, description,
+timestamps) but excludes version details for performance.
diff --git a/backend/app/api/docs/config/list_versions.md b/backend/app/api/docs/config/list_versions.md
@@ -0,0 +1,4 @@
+List all versions for a specific configuration.
+
+Returns versions in descending order (newest first), allowing you to
+see the evolution of configuration parameters over time.
diff --git a/backend/app/api/docs/config/update.md b/backend/app/api/docs/config/update.md
@@ -0,0 +1,5 @@
+Update a configuration's metadata (name or description).
+
+This endpoint modifies only the configuration-level metadata, not the
+LLM parameters themselves. To change LLM parameters, create a new
+version instead.
diff --git a/backend/app/api/docs/documents/permanent_delete.md b/backend/app/api/docs/documents/permanent_delete.md
@@ -1,4 +1,6 @@
-This operation soft deletes the document — meaning its metadata and reference are retained in the database, but it is marked as deleted. The actual file stored in cloud storage (e.g., S3) is permanently deleted, and this action is irreversible.
+This operation marks the document as deleted in the database while retaining its metadata. However, the actual file is
+permanently deleted from cloud storage (e.g., S3) and cannot be recovered. Only the database record remains for reference
+purposes.
 If the document is part of an active collection, those collections
 will be deleted using the collections delete interface. Noteably, this
 means all OpenAI Vector Store's and Assistant's to which this document
diff --git a/backend/app/api/docs/llm/llm_call.md b/backend/app/api/docs/llm/llm_call.md
@@ -0,0 +1,42 @@
+Make an LLM API call using either a stored configuration or an ad-hoc configuration.
+
+This endpoint initiates an asynchronous LLM call job. The request is queued
+for processing, and results are delivered via the callback URL when complete.
+
+### Request Fields
+
+**`query`** (required) - Query parameters for this LLM call:
+- `input` (required, string, min 1 char): User question/prompt/query
+- `conversation` (optional, object): Conversation configuration
+  - `id` (optional, string): Existing conversation ID to continue
+  - `auto_create` (optional, boolean, default false): Create new conversation if no ID provided
+  - **Note**: Cannot specify both `id` and `auto_create=true`
+
+**`config`** (required) - Configuration for the LLM call (just choose one mode):
+
+- **Mode 1: Stored Configuration**
+  - `id` (UUID): Configuration ID
+  - `version` (integer >= 1): Version number
+  - **Both required together**
+  - **Note**: When using stored configuration, do not include the `blob` field in the request body
+
+- **Mode 2: Ad-hoc Configuration**
+  - `blob` (object): Complete configuration object (see Create Config endpoint documentation for examples)
+    - `completion` (required):
+      - `provider` (required, string): Currently only "openai"
+      - `params` (required, object): Provider-specific parameters (flexible JSON)
+  - **Note**: When using ad-hoc configuration, do not include `id` and `version` fields
+
+**`callback_url`** (optional, HTTPS URL):
+- Webhook endpoint to receive the response
+- Must be a valid HTTPS URL
+- If not provided, response is only accessible through job status
+
+**`include_provider_raw_response`** (optional, boolean, default false):
+- When true, includes the unmodified raw response from the LLM provider
+
+**`request_metadata`** (optional, object):
+- Custom JSON metadata
+- Passed through unchanged in the response
+
+---
diff --git a/backend/app/api/docs/onboarding/onboarding.md b/backend/app/api/docs/onboarding/onboarding.md
@@ -18,10 +18,31 @@
 
 ---
 
-## 🔑 OpenAI API Key (Optional)
-- If provided, the API key will be **encrypted** and stored as project credentials.
-- If omitted, the project will be created **without OpenAI credentials**.
-
+## 🔑 Credentials (Optional)
+- If provided, the given credentials will be **encrypted** and stored as project credentials.
+- The `credential` parameter accepts a list of one or more credentials (e.g., an OpenAI key, Langfuse credentials, etc.).
+- If omitted, the project will be created **without credentials**.
+- We’ve also included a list of the providers currently supported by kaapi.
+   ### Example: For sending multiple credentials -
+   ```
+   "credentials": [
+     {
+       "openai": {
+         "api_key": "sk-proj-..."
+       }
+     },
+     {
+       "langfuse": {
+         "public_key": "pk-lf-...",
+         "secret_key": "sk-lf-...",
+         "host": "https://cloud.langfuse.com"
+       }
+     }
+   ]
+   ```
+  ### Supported Providers
+    - openai
+    - langfuse
 ---
 
 ## 🔄 Transactional Guarantee
diff --git a/backend/app/api/routes/config/config.py b/backend/app/api/routes/config/config.py
@@ -12,14 +12,15 @@
     ConfigVersion,
     Message,
 )
-from app.utils import APIResponse
+from app.utils import APIResponse, load_description
 from app.api.permissions import Permission, require_permission
 
 router = APIRouter()
 
 
 @router.post(
     "/",
+    description=load_description("config/create.md"),
     response_model=APIResponse[ConfigWithVersion],
     status_code=201,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -44,6 +45,7 @@ def create_config(
 
 @router.get(
     "/",
+    description=load_description("config/list.md"),
     response_model=APIResponse[list[ConfigPublic]],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -67,6 +69,7 @@ def list_configs(
 
 @router.get(
     "/{config_id}",
+    description=load_description("config/get.md"),
     response_model=APIResponse[ConfigPublic],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -88,6 +91,7 @@ def get_config(
 
 @router.patch(
     "/{config_id}",
+    description=load_description("config/update.md"),
     response_model=APIResponse[ConfigPublic],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -113,6 +117,7 @@ def update_config(
 
 @router.delete(
     "/{config_id}",
+    description=load_description("config/delete.md"),
     response_model=APIResponse[Message],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
diff --git a/backend/app/api/routes/config/version.py b/backend/app/api/routes/config/version.py
@@ -9,14 +9,15 @@
     Message,
     ConfigVersionItems,
 )
-from app.utils import APIResponse
+from app.utils import APIResponse, load_description
 from app.api.permissions import Permission, require_permission
 
 router = APIRouter()
 
 
 @router.post(
     "/{config_id}/versions",
+    description=load_description("config/create_version.md"),
     response_model=APIResponse[ConfigVersionPublic],
     status_code=201,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -43,6 +44,7 @@ def create_version(
 
 @router.get(
     "/{config_id}/versions",
+    description=load_description("config/list_versions.md"),
     response_model=APIResponse[list[ConfigVersionItems]],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -72,6 +74,7 @@ def list_versions(
 
 @router.get(
     "/{config_id}/versions/{version_number}",
+    description=load_description("config/get_version.md"),
     response_model=APIResponse[ConfigVersionPublic],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
@@ -98,6 +101,7 @@ def get_version(
 
 @router.delete(
     "/{config_id}/versions/{version_number}",
+    description=load_description("config/delete_version.md"),
     response_model=APIResponse[Message],
     status_code=200,
     dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py
@@ -109,7 +109,7 @@ async def upload_doc(
         None, description="Name of the transformer to apply when converting."
     ),
     callback_url: str
-    | None = Form(None, description="URL to call to report endpoint status"),
+    | None = Form(None, description="URL to call to report doc transformation status"),
 ):
     source_format, actual_transformer = pre_transform_validation(
         src_filename=src.filename,
diff --git a/backend/app/api/routes/llm.py b/backend/app/api/routes/llm.py
@@ -5,7 +5,7 @@
 from app.api.deps import AuthContextDep, SessionDep
 from app.models import LLMCallRequest, LLMCallResponse, Message
 from app.services.llm.jobs import start_job
-from app.utils import APIResponse
+from app.utils import APIResponse, load_description
 
 
 logger = logging.getLogger(__name__)
@@ -32,6 +32,7 @@ def llm_callback_notification(body: APIResponse[LLMCallResponse]):
 
 @router.post(
     "/llm/call",
+    description=load_description("llm/llm_call.md"),
     response_model=APIResponse[Message],
     callbacks=llm_callback_router.routes,
 )
diff --git a/backend/app/api/routes/onboarding.py b/backend/app/api/routes/onboarding.py
@@ -23,4 +23,9 @@ def onboard_project_route(
     current_user: User = Depends(get_current_active_superuser),
 ):
     response = onboard_project(session=session, onboard_in=onboard_in)
-    return APIResponse.success_response(data=response)
+
+    metadata = None
+    if onboard_in.credentials:
+        metadata = {"note": ("Given credential(s) have been saved for this project.")}
+
+    return APIResponse.success_response(data=response, metadata=metadata)
diff --git a/backend/app/crud/onboarding.py b/backend/app/crud/onboarding.py
diff --git a/backend/app/models/onboarding.py b/backend/app/models/onboarding.py
diff --git a/backend/app/tests/api/routes/test_onboarding.py b/backend/app/tests/api/routes/test_onboarding.py
diff --git a/backend/app/tests/crud/test_onboarding.py b/backend/app/tests/crud/test_onboarding.py

Original file line number	Diff line number	Diff line change
`@@ -3,4 +3,4 @@ not deleted`
`3`	`3`
`4`	`4`	If a vector store was created - `llm_service_name` and `llm_service_id` in the response denote the name of the vector store (eg. 'openai vector store') and its id.
`5`	`5`
`6`		-[To be deprecated] If an assistant was created, `llm_service_name` and `llm_service_id` in the response denote the name of the model used in the assistant (eg. 'gpt-4o') and assistant id.
	`6`	+[To be deprecated] If an assistant was created, `llm_service_name` and `llm_service_id` in the response denotes the name of the model used in the assistant (eg. 'gpt-4o') and assistant id.