Add docs for choreo ai gateway feature

Author: Thushani-Jayasekera

en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection-to-a-genai-service.md

@@ -0,0 +1,30 @@
+# Consume a GenAI Service
+
+## Overview
+
+Choreo is a powerful platform that enables developers to create, deploy, and consume services efficiently. The Choreo Internal Marketplace simplifies API discovery and usage, allowing developers to integrate APIs seamlessly into their applications.
+
+This guide is intended for application developers who wish to consume Gen AI Services published in the Internal Marketplace to build their applications.
+
+## Prerequisites
+
+Before proceeding, ensure you have access to a published Gen AI Service to consume. If you do not have one, please follow the PE documentation to create and deploy a sample Gen AI Service.
+
+## Discover Gen AI Services
+
+1. Navigate to the [Choreo Internal Marketplace](https://console.choreo.dev) and sign in.
+2. Select the desired Gen AI Service to view its details.
+
+## Create a connection to a Gen AI Service
+
+Follow these steps to create a connection to a Gen AI Service from your choreo component:
+
+1. In the left navigation menu, click **Connections**. This page lists all the existing connections.
+2. Click **+Create**. This opens the Marketplace view where you can browse and search for services.
+3. Click the **Services** tab. You can search and apply filters to efficiently find a service.
+4. Click on the Gen AI service you want to connect to. 
+5. Enter a name and a description for the connection.
+6. Select an **Access Mode** and **Authentication Scheme** for the connection.
+7. Click **Create**.
+   
+This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component. 

en/developer-docs/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md

@@ -138,6 +138,7 @@ nav:
       - Integrate Unit Tests into the Build Pipeline: develop-components/integrate-unit-tests-into-the-build-pipeline.md
       - Share and Reuse Components:
           - Create a Connection: develop-components/sharing-and-reusing/create-a-connection.md
+          - Create a connection to a GenAI Service: develop-components/sharing-and-reusing/create-a-connection-to-a-genai-service.md
           - Use a Connection in Your Service: develop-components/sharing-and-reusing/use-a-connection-in-your-service.md
           - Use a Connection in Your Web Application: develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md
           - Use a Database Connection in Your Component: develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md
@@ -150,7 +151,6 @@ nav:
       - Connect to Remote Dependencies While Developing: develop-components/connect-to-remote-dependencies-while-developing.md
   - Integrate and Manage External Services:
       - Integrate and Manage Third-Party Services: integrate-and-manage-external-services/integrate-and-manage-third-party-services.md
-      - Integrate and Manage Generative AI Services: integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md
   - Choreo-Managed Databases and Caches:
       - Overview: manage-databases-and-caches/choreo-managed-databases-and-caches.md
       - PostgreSQL: manage-databases-and-caches/choreo-managed-postgresql-databases.md

en/developer-docs/mkdocs.yml

@@ -0,0 +1,15 @@
+# Choreo AI Gateway
+
+As AI adoption accelerates, managing AI APIs effectively has become essential for organizations integrating AI into their applications. Choreo's AI Gateway simplifies this process, providing a seamless way to create, manage, and expose AI APIs with robust security and scalability.
+
+![AI Gateway](../../assets/img/ai-gateway/ai-gateway.png)
+
+Choreo offers built-in support for OpenAI, Azure OpenAI, and Mistral and AWS Bedrock.
+
+With a comprehensive set of capabilities, the AI Gateway ensures secure and efficient AI integration. Key features include:
+
+- AI Vendor Key Configuration: Securely authenticate AI APIs by configuring API keys obtained from the AI vendor.
+- Rate Limiting: Protect AI backends by enforcing token-based rate limits to manage resource consumption.
+- AI API Observability: Track AI API usage statistics using Analytics solutions. (coming soon)
+
+By leveraging these capabilities, organizations can efficiently integrate, monitor, and scale AI APIs, unlocking the full potential of AI-driven applications.

en/pe-docs/docs/assets/img/ai-gateway/add-configs.png

@@ -0,0 +1,150 @@
+# Integrate and Manage Generative AI Services
+
+Generative AI (GenAI) services leverage advanced machine learning models to create original content such as text, images, music, or code, by identifying and learning patterns from existing data. Powered by deep neural networks and other machine learning models, these services can generate human-like outputs in various formats. This versatility makes GenAI ideal for tasks such as content creation, image generation, conversation automation, etc. 
+
+Choreo provides native support to integrate GenAI services into applications. Developers can register GenAI services, manage access, and expose them securely through the [Choreo AI Gateway](https://github.com/wso2/choreo-ai-gateway), ensuring enterprise-grade governance and control.
+
+## Register a GenAI Service
+
+When you register a GenAI service in Choreo, all invocations are automatically routed through the Choreo AI Gateway. The gateway enforces:
+- Security – Authentication, authorization, and secure transport.
+- Rate limiting – Request- and token-based throttling.
+- Observability – Metrics, logging, and monitoring for all requests (coming soon)
+
+This ensures consistent, secure, and cost-controlled access to the underlying GenAI provider.
+
+### Scopes of Registration
+GenAI services can be registered at two scopes:
+
+- **Organization-level registration**: The service is available across all projects within the organization.
+- **Project-level registration**: The service is restricted to the specific project where it is registered.
+
+Once registered, the service is published to the Internal Marketplace, where developers can discover and consume it via Connections.
+
+### Prerequisites
+Before registering a GenAI service, obtain the following details from the provider:
+
+- API key
+- Service URL
+- Any additional credentials (e.g., client secrets, subscription keys)
+
+!!! note
+    - Register services at the correct scope:
+        - Use organization-level if the service will be shared across projects.
+        - Use project-level if usage is limited to a single project.
+
+### Step 1: Select a Service Provider
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Select your Organization or Project depending on the required scope.
+3. In the left navigation menu, go to **DB & Services → GenAI Services**.
+4. Select a service provider:
+    - **OpenAI**
+    - **Azure OpenAI**
+    - **Anthropic Claude**
+    - **Mistral**
+    - **AWS Bedrock**
+
+5. Click **Next**.
+
+### Step 2: Provide Service Details
+
+1. Under **Register a GenAI Service**, enter the following details:
+
+    - **Name**: The name of the service.
+    - **Context path**: A unique identifier for the service API within the Choreo AI Gateway.
+    - **Service URL**: The provider’s endpoint.
+    - **Summary**: A short description of the service.
+
+2. Click **Next**.
+
+### Step 3: Add Environment Configurations
+
+Under **Add Environment Configurations**, configure backend security and token-based rate limiting for your AI API.
+
+!!! note
+- Required configurations vary by provider.
+- You must provide valid configurations for all environments to complete registration.
+
+#### Configure Backend Security
+
+1. In the AI API Security section:
+
+    - Set the Authorization header.
+    - Provide the API key or credentials from your provider (e.g., `Authorization: Bearer <token>`).
+    - Key formats may differ by provider.
+
+    ![Add environment configurations](../../assets/img/ai-gateway/add-configs.png)
+
+#### Configure Token-Based Rate Limiting
+
+Unlike traditional APIs, LLMs and GenAI services are billed based on token consumption rather than just request count. Token-based rate limiting allows you to:
+- Control costs.
+- Prevent excessive usage.
+- Enforce fair quotas across consumers.
+
+2. In the **Token-Based Rate Limiting** section, configure the following parameters:
+    - **Time Unit**: Window for quota enforcement (per minute, per hour, per day).
+    - **Max Prompt Token Count**: Limit for input tokens per request.
+    - **Max Completion Token Count**: Limit for output tokens per request.
+    - **Max Total Token Count**: Combined input + output tokens per request.
+
+3. Click **Register**.
+
+The service is now available in the Internal Marketplace.
+
+### View or Update Service Details
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select a service to view or edit its details:
+
+    - **General Details**: Displays metadata such as name, description, and labels..
+    - **Service Definition**: Displays the service definition.
+    - **Environment Configurations**: Displays the security and rate-limiting settings for each environment, along with deployment status.
+
+    ![View or update service details](../../assets/img/ai-gateway/view-configs.png)
+
+### Add a GenAI Service to the Internal Marketplace
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select the service.
+4. Click **Add to Marketplace**.
+
+### Remove a GenAI Service from the Internal Marketplace
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select the service.
+4. Click **Remove from Marketplace**.
+
+The service is removed from the Internal Marketplace, making it unavailable for new Connections. However, existing Connections continue to function until manually removed.
+
+## Manage GenAI Services
+
+### View or Update Service Details
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select a service to view or edit its details:
+
+    - **General Details**: Displays service metadata. For example, the service name, overview, labels, etc.
+    - **Service Definition**: Displays the service definition. To update the definition, click **Upload** and select the new definition file.
+    - **Environment Configurations**: Displays the environment configurations for the service. To update the configurations, expand the environment and update the configurations. You can also view the deployment status of the AI API in the environment.
+
+### Add a GenAI Service to the Internal Marketplace
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select the service.
+4. Click **Add to Marketplace**.
+
+### Remove a GenAI Service from the Internal Marketplace
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. Navigate to **DB & Services → GenAI Services**.
+3. Select the service.
+4. Click **Remove from Marketplace**.
+
+The service is removed from the Internal Marketplace, making it unavailable for new Connections. However, existing Connections continue to function until manually removed.

en/pe-docs/docs/assets/img/ai-gateway/view-configs.png

@@ -134,7 +134,9 @@ nav:
           - Create Choreo-Managed Kafka Services: db-and-services/message-brokers/create-choreo-managed-kafka-services.md
           - Configure a Kafka Service: db-and-services/message-brokers/configure-a-kafka-service.md
           - Monitor a Kafka Service: db-and-services/message-brokers/monitor-a-kafka-service.md
-      - Gen AI Services: db-and-services/external-services/integrate-and-manage-gen-ai-services.md
+      - Gen AI Services:
+          - Choreo AI Gateway: db-and-services/ai-gateway/choreo-ai-gateway.md
+          - Integrate and Manage Generative AI Services: db-and-services/ai-gateway/integrate-and-manage-gen-ai-services.md
   - K8s Operations:
       - Runtime:
           - View Kubernetes Runtime Details: k8s-operations/runtime/view-runtime-details.md