Merge pull request #7988 from Thenujan-Nagaratnam/apictl-m

Add ai related operations with apictl

en/docs/consume/discover-apis/marketplace-assistant.md

@@ -67,10 +67,94 @@ To enable the Marketplace Assistant and populate the vector database, the API Ma
 
 2. Restart the API Manager.
 
-## Step 4 - Engage with the Marketplace Assistant
+## Step 4 (optional) - Sync vector database with your current APIs and API Products
+
+To ensure that the Marketplace Assistant is aware of all published APIs and to update the vector database with the current APIs, you have to upload all APIs and API Products.
+
+For more information, see [AI Related Operations with apictl]({{base_path}}/install-and-setup/setup/api-controller/ai-related-operations-with-apictl/)
+
+## Step 5 - Engage with the Marketplace Assistant
 
 Now that your environment is configured, you're ready to interact with the Marketplace Assistant. Utilize its capabilities to chat with your APIs and receive tailored recommendations.
 
 ## What's Next?
 
 Explore the features and functionalities of the Marketplace Assistant to streamline your API management experience further.
+
+## FAQ
+
+### Why is this an experimental feature?
+
+The Marketplace Assistant is labeled as an experimental feature because it represents innovative technology that is still under development. AI technology is rapidly evolving with significant enhancements in large language models and the introduction of increasingly efficient chips, and we are integrating the latest advancements to enhance our capabilities. Rolling out new features as experimental underscores our commitment to innovation, and as we continue to refine them, we are focused on enhancing their performance and reliability based on user input and ongoing development efforts.
+
+### What are the usage limits?
+
+During the trial period, users are subject to the following usage limits:
+
+- Access to up to 1000 APIs to the vectorDB.
+- Limited chat functionality based on the number of tokens used by the language model.
+
+### Why did I lose my chat history after I logged out?
+
+Your chat history will be lost after logging out or after a period of inactivity of 1 hour, as per the design of the application. For security and privacy reasons ensure that your conversations are not accessible to other users. Additionally, you have the option to reset your chat history to address any potential privacy concerns.
+
+### Why does the chat not have the context of the initial interactions?
+
+The language model operates by considering only the last 5 interactions to respond. Therefore, if your conversation extends beyond 5 interactions, the model may not retain the earlier parts of the chat
+
+### Why can't I list a large number of APIs as recommendations?
+
+This is because the assistant is designed to identify the most suitable APIs rather than listing a large number of options. To enhance the recommendation process, we limit the number of APIs provided to the language model as context. This ensures that the assistant suggests more relevant APIs instead of overwhelming the user with every possible option.
+
+### I'm receiving the message "I am not aware of such API" despite the API being listed on the developer portal.
+
+There are a few potential reasons for this
+
+#### Assistant uses only public APIs to provide answers.
+
+- The marketplace assistant is only using public APIs to answer questions. If there is an API, not a public API, the assistant wouldn't be aware of it.
+
+#### You may have configured the marketplace assistant after publishing those APIs.
+
+- APIs are only published to the vector database if the Al features are enabled and the token is configured. If you published the API before configuring the assistant, it might not be in the database, and the assistant wouldn't be aware of it. Re-publishing the API and trying again could resolve this. If you have numerous APIs, there's an option to upload them using the WSO2 API Controller
+
+#### If you've published the API and are still receiving the above response, there could be two reasons:
+
+- The API details may have failed to upload to the vector database due to reasons like network issues.
+- The language model may not be responding correctly. Even if the APL is in the database, there's a chance the language model can't understand and answer properly. Trying different prompts may help clarify the issue.
+
+### I am getting this error response: `Apologies for the inconvenience. It appears that the token limit has been exceeded`
+
+This message indicates that the request you made has exceeded the allowed token limit usage. During the trial period, token usage is limited, You have the option to upgrade your subscription plan to access Marketplace Assistant without interruption.
+
+### I am getting this error response: Apologies for the inconvenience. `It appears that your token is invalid or expired. Please provide a valid token or upgrade your subscription plan `
+
+This message suggests that your on-prem key is not valid or it is expired. You can request an extended trial period or you can upgrade your subscription plan so that you can seamlessly use Marketplace Assistant
+
+### I am getting this error response: Apologies for the inconvenience. `It seems that something went wrong with the Marketplace Assistant. Please try again later `
+
+This message signifies that an unexpected error has occurred. It could be due to various reasons such as server issues, network problems, etc. Kindly reach out to the administrator for assistance in resolving the problem,
+
+### What type of questions I can ask from Marketplace Assistant:
+
+You can ask the Marketplace Assistant various questions related to APIs and their functionalities. Some examples include:
+
+- Searching for specific APIs by name or category.
+- Requesting recommendations for APIs based on specific use cases or requirements.
+- Inquiring about API, endpoints, or usage guidelines.
+- Comparing two APIs with their usage and functionalities.
+
+For instance, you can ask questions like:
+
+- I am trying to develop an application where `<Use case description>`. What are APIs you can recommend for me to use?
+- What are the APIs you know about `<Topic>`?
+- What are the differences between `<APII>` and `<API2>`.
+
+Feel free to ask any questions related to APIs or the functionality of APIs, and the assistant will do its best to provide helpful responses,
+if you encounter any issues or have further questions, go to the Issues tab of this GitHub repo [API Manager](https://github.com/wso2/api-manager/issues) and click the New issue button to file a bug report or ask questions.
+
+### This error message is prompted in the terminal when I use the apictl to upload my APIs: `context deadline exceeded (Client.Timeout exceeded while awaiting headers)`.
+
+The dafault HTTP request timeout for apictl is 10s. Due to network connnectivity or some other issues, the uploading might exceed this limit. If you encounter this issue you can simply set the timeout to a higher value.
+
+you can modify the `main_config.yaml` file, which you can find in the `APICTL_CONFIG_DIR` and increase the `http_request_timeout` value (Note that the value should be given in milli seconds, e.g: `http_request_timeout: 20000`).

en/docs/install-and-setup/setup/api-controller/ai-related-operations-with-apictl.md

@@ -0,0 +1,164 @@
+# AI Related operations with apictl
+
+To ensure that the Marketplace Assistant is fully informed about all published APIs and API Products, it is essential to update the vector database with the current APIs.
+**WSO2 API Controller (apictl)** allows you to update the vector Database with the current APIs.
+
+First you have to download and intialize the apictl.
+
+1.  Make sure that the WSO2 API-M is started and that the corresponding version of apictl is set up.   
+For more information, see [Download and Initialize the apictl]({{base_path}}/install-and-setup/setup/api-controller/getting-started-with-wso2-api-controller/#download-and-initialize-the-apictl).
+2.  Log in to the WSO2 API-M in the environment by following the instructions in [Login to an Environment]({{base_path}}/install-and-setup/setup/api-controller/getting-started-with-wso2-api-controller/#login-to-an-environment).
+3.  Run the corresponding apictl commands below to delete and upload APIs and API Products from a logged in user's tenant.
+
+### Set token as a config variable
+
+Set the Token (Which is generated for AI features) as a config.
+
+  - **Command**
+
+      ```bash
+      apictl set --ai-token "<use token that you generated>"
+      ```
+
+### Delete APIs and API Products from vector database.
+
+Run the following command to delete all the APIs and API Products from the vector database from the currently logged-in user's tenant within a specified environment.
+
+- **Command**
+
+      ```bash
+      apictl ai delete artifacts -e "<environment>"
+      ```
+
+      ```bash
+      apictl ai delete artifacts --token "<use token that you generated>" -e "<environment>"
+      ```
+
+      ```bash
+      apictl ai delete artifacts --token "<use token that you generated>" --endpoint "<endpoint of ai service>" -e "<environment>"
+      ```
+
+    !!! info
+        **Flags:**  
+
+          -  Required :  
+              `--environment` or `-e` : Environment to be searched
+          -  Optional :  
+              `--token` : On prem key of AI services  
+              `--endpoint` : Endpoint url of AI services
+
+    !!! example
+          ```bash
+              apictl ai delete artifacts -e dev
+          ```
+
+          ```bash
+              apictl ai delete artifacts --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts -e dev
+          ```
+
+          ```bash
+              apictl ai delete artifacts --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts --endpoint https://dev-tools.wso2.com/apim-ai-service -e dev
+          ```
+    !!! note
+          - Note that if you have already set the token to the config variable, you dont have to use the --token flag
+
+
+### Upload APIs to vector database.
+
+Run the following command to upload all the APIs to the vector database from the currently logged-in user's tenant within a specified environment.
+
+  - **Command**
+
+    ```bash
+    apictl ai upload apis -e "<environment>"
+    ```
+
+    ```bash
+    apictl ai upload apis -e "<environment>" --all
+    ```
+
+    ```bash
+    apictl ai upload apis --token "<use token that you generated>" --endpoint "<endpoint of ai service>" -e "<environment>"
+    ```
+
+    !!! info
+        **Flags:**
+
+          -   Required :  
+              `--environment` or `-e` : Environment to be searched
+          -   Optional :  
+              `--token` : On prem key of AI services  
+              `--endpoint` : Endpoint url of AI services  
+              `--all` : Upload both APIs and API Products.
+
+    !!! example
+          ```bash
+          apictl ai upload apis -e dev
+          ```
+
+          ```bash
+          apictl ai upload apis -e dev --all
+          ```
+
+          ```bash
+          apictl ai upload apis --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts -e dev
+          ```
+
+          ```bash
+          apictl ai upload apis --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts --endpoint https://dev-tools.wso2.com/apim-ai-service -e dev
+          ```
+    !!! note
+          - Note that if you have already set the token to the config variable, you dont have to use the --token flag
+
+### Upload API Products to vector database.
+
+Run the following command to upload all the API Products to the vector database from the currently logged-in user's tenant within a specified environment.
+
+  - **Command**
+
+    ```bash
+    apictl ai upload api-products -e "<environment>"
+    ```
+
+    ```bash
+    apictl ai upload api-products -e "<environment>" --all
+    ```
+
+    ```bash
+    apictl ai upload api-products --token "<use token that you generated>" --endpoint "<endpoint of ai service>" -e "<environment>"
+    ```
+
+    !!! info
+        **Flags:**
+
+          -   Required :  
+              `--environment` or `-e` : Environment to be searched
+          -   Optional :  
+              `--token` : On prem key of AI services  
+              `--endpoint` : Endpoint url of AI services  
+              `--all` : Upload both APIs and API Products.  
+
+    !!! example
+          ```bash
+          apictl ai upload api-products -e dev
+          ```
+
+          ```bash
+          apictl ai upload api-products -e dev --all
+          ```
+
+          ```bash
+          apictl ai upload api-products --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts -e dev
+          ```
+
+          ```bash
+          apictl ai upload api-products --token 2fdca1b6-6a28-4aea-add6-77c97033bdb9 artifacts --endpoint https://dev-tools.wso2.com/apim-ai-service -e dev
+          ```
+    !!! note
+          - Note that if you have already set the token to the config variable, you dont have to use the --token flag
+
+This process can be repeated for all tenants.
+
+If you intend to use the same access token across different deployments, you can continue using it without generating a new one each time.
+
+This process ensures that the Marketplace Assistant is up-to-date with all published APIs, enhancing its ability to provide accurate and relevant assistance.

en/mkdocs.yml

@@ -596,6 +596,7 @@ nav:
                 - Manage Integrations: install-and-setup/setup/api-controller/managing-integrations/managing-integrations-with-ctl.md
                 - Encrypt Secrets with apictl: install-and-setup/setup/api-controller/encrypting-secrets-with-ctl.md
                 - Enable Correlation Logs with apictl: install-and-setup/setup/api-controller/enabling-correlation-logs-with-apictl.md
+                - AI Related Operations with apictl: install-and-setup/setup/api-controller/ai-related-operations-with-apictl.md
                 - Advanced Topics:
                     - Create Custom Users to Perform apictl Operations: install-and-setup/setup/api-controller/advanced-topics/creating-custom-users-to-perform-api-controller-operations.md
                     - Configure Environment Specific Parameters: install-and-setup/setup/api-controller/advanced-topics/configuring-environment-specific-parameters.md