improve docs and section formatting

Thushani-Jayasekera · Thushani-Jayasekera · commit ff219bf108bc · 2025-08-22T10:05:45.000+05:30
diff --git a/en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection-to-a-genai-service.md b/en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection-to-a-genai-service.md
@@ -2,29 +2,49 @@
 
 ## 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.
+Choreo is a cloud-native platform that enables developers to create, deploy, and consume services efficiently. The **Choreo Internal Marketplace** streamlines API discovery and integration, making it easier to incorporate services into your applications.
 
-This guide is intended for application developers who wish to consume Gen AI Services published in the Internal Marketplace to build their applications.
+This guide is for application developers who want to consume GenAI Services published in the Internal Marketplace.
 
 ## 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.
+Before you begin, ensure that:
 
-## Discover Gen AI Services
+- You have access to a published GenAI Service in the Internal Marketplace.
 
-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.
+- If you don’t yet have one, refer to the [PE documentation](https://docs.choreo.dev/en/pe-docs/docs/db-and-services/ai-gateway/integrate-and-manage-gen-ai-services) to create and deploy a sample GenAI Service.
 
-## Create a connection to a Gen AI Service
+## Discover GenAI Services
 
-Follow these steps to create a connection to a Gen AI Service from your choreo component:
+1. Navigate to the [Choreo Internal Marketplace](https://console.choreo.dev).
 
-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. 
+2. Sign in with your credentials.
+3. Browse or search for the desired GenAI Service.
+
+4. Select the service to view its details.
+
+## Create a Connection to a GenAI Service
+
+To use a GenAI Service in your Choreo component, you first need to create a connection.
+
+1. In the left navigation menu, click Connections.
+
+2. This page lists all existing connections.
+
+3. Click **+Create**.
+
+4. The Marketplace view opens, where you can browse and search for services.
+
+4. Click the **Services** tab.
+
+5. Use search or filters to find the required service efficiently.
+
+6. Select the GenAI Service you want to connect to.
+
+7. Provide a name and description for the connection.
+
+8. Choose an Access Mode and Authentication Scheme.
+
+9. Click **Create**.
+
+Once created, the connection details are displayed for each environment. An inline usage guide is also provided, showing how to use the connection in your component.
diff --git a/en/pe-docs/docs/assets/img/ai-gateway/ai-gateway.png b/en/pe-docs/docs/assets/img/ai-gateway/ai-gateway.png
diff --git a/en/pe-docs/docs/db-and-services/ai-gateway/choreo-ai-gateway.md b/en/pe-docs/docs/db-and-services/ai-gateway/choreo-ai-gateway.md
@@ -1,15 +1,45 @@
 # 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.
+As organizations accelerate AI adoption, managing AI APIs effectively has become essential. The Choreo AI Gateway simplifies this process by providing a unified way to create, manage, and expose AI APIs with enterprise-grade security, observability, and scalability.
 
-![AI Gateway](../../assets/img/ai-gateway/ai-gateway.png)
+![Choreo AI Gateway](../../assets/img/ai-gateway/ai-gateway.png)
 
-Choreo offers built-in support for OpenAI, Azure OpenAI, and Mistral and AWS Bedrock.
+## Supported Providers
 
-With a comprehensive set of capabilities, the AI Gateway ensures secure and efficient AI integration. Key features include:
+The AI Gateway integrates seamlessly with leading AI platforms, including:
 
-- 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)
+- OpenAI
 
-By leveraging these capabilities, organizations can efficiently integrate, monitor, and scale AI APIs, unlocking the full potential of AI-driven applications.
+- Azure OpenAI
+
+- Anthropic Claude
+
+- Mistral
+
+- AWS Bedrock
+
+## Key Features
+
+The AI Gateway offers a robust set of capabilities to ensure secure and efficient AI integration:
+
+- AI Vendor Key Configuration: 
+
+  Securely authenticate with AI providers by configuring API keys obtained from each vendor.
+
+- Token-Based Rate Limiting:
+
+  Protect backend services and manage costs by applying rate limits based on token usage rather than just request counts.
+  
+- AI API Observability (Coming Soon):
+
+  Gain insights into AI API performance and usage with built-in analytics and monitoring.
+
+With these features, organizations can integrate, monitor, and scale AI services efficiently, unlocking the full potential of AI-driven applications.
+
+### Token-Based Rate Limiting
+
+AI services typically charge based on tokens rather than requests, making cost control critical. Choreo AI Gateway enables token-based rate limiting at the API level to:
+
+- Define quotas based on LLM token consumption.
+- Prevent unexpected costs by controlling overuse.
+- Enforce fair usage policies across AI-powered APIs.
diff --git a/en/pe-docs/docs/db-and-services/ai-gateway/integrate-and-manage-gen-ai-services.md b/en/pe-docs/docs/db-and-services/ai-gateway/integrate-and-manage-gen-ai-services.md
@@ -1,150 +1,158 @@
 # 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. 
+## Overview
 
-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.
+Generative AI (GenAI) services leverage advanced machine learning models to produce original content—such as text, images, music, or code—by learning patterns from existing data. Powered by deep neural networks, these services can generate human-like outputs across multiple formats, making them well-suited for tasks like content creation, image generation, and conversational automation.
+
+Choreo provides native support for integrating GenAI services into applications. Using the Choreo AI Gateway, Platform Engineers and Admins can:
+
+- Register GenAI services in the Choreo AI Gateway.
+
+- Manage access and authentication for GenAI services.
+
+- Enforce governance, security, and cost controls for GenAI services at scale.
 
 ## 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)
+When you register a GenAI service in Choreo, all requests are routed through the AI Gateway, which enforces:
+
+- Security – Authentication, authorization, and encrypted transport.
+
+- Rate Limiting – Token-based throttling.
 
-This ensures consistent, secure, and cost-controlled access to the underlying GenAI provider.
+- Observability (Coming Soon) – Metrics, logging, and monitoring.
 
-### Scopes of Registration
-GenAI services can be registered at two scopes:
+This ensures consistent, secure, and cost-controlled access to the underlying provider.
 
-- **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.
+## Registration Scopes
+
+You can register GenAI services at two levels:
+
+- Organization-level registration – Service is available across all projects in the organization.
+
+- Project-level registration – Service is restricted to the 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:
+## Prerequisites
+
+Before registering a GenAI service, obtain the following from your 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.
+
+    - Choose the correct registration scope:
+
+        - Use organization-level if the service will be shared across multiple projects.
         - Use project-level if usage is limited to a single project.
 
+## Registration Steps
+
 ### 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**
+1. Sign in to the Choreo Console.
+
+2. Select your Organization or Project, depending on the required scope.
+
+3. In the left navigation menu, go to DB & Services → GenAI Services.
+
+4. Choose a provider from the list:
+
+- OpenAI
+
+- Azure OpenAI
 
-5. Click **Next**.
+- Anthropic Claude
+
+- Mistral
+
+- AWS Bedrock
+
+5. Click Next.
 
 ### Step 2: Provide Service Details
 
-1. Under **Register a GenAI Service**, enter the following details:
+Under **Register a GenAI Service**, enter:
+
+- Name – The service name.
+
+- Context Path – A unique identifier for the API within the AI Gateway.
+
+- Service URL – The provider’s endpoint.
 
-    - **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.
+- Summary – A short description of the service.
 
-2. Click **Next**.
+Click **Next**.
 
 ### Step 3: Add Environment Configurations
 
-Under **Add Environment Configurations**, configure backend security and token-based rate limiting for your AI API.
+![Add Environment Configurations](../../assets/img/ai-gateway/add-configs.png)
 
-!!! note
-- Required configurations vary by provider.
-- You must provide valid configurations for all environments to complete registration.
+### Configure Backend Security
 
-#### Configure Backend Security
+In **Backend Security**, set the Authorization header.
 
-1. In the AI API Security section:
+- Provide the API key or credentials (e.g., Authorization: Bearer <token>).
 
-    - Set the Authorization header.
-    - Provide the API key or credentials from your provider (e.g., `Authorization: Bearer <token>`).
-    - Key formats may differ by provider.
+- Key formats may vary by provider.
 
-    ![Add environment configurations](../../assets/img/ai-gateway/add-configs.png)
+### Configure Token-Based Rate Limiting
 
-#### Configure Token-Based Rate Limiting
+LLMs and GenAI services are billed based on token usage, not just request count. Token-based rate limiting helps:
 
-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.
+Set the following parameters:
 
-3. Click **Register**.
+- Time Unit – Enforcement window (per minute, hour, or day).
 
-The service is now available in the Internal Marketplace.
+- Max Prompt Token Count – Maximum input tokens per request.
 
-### View or Update Service Details
+- Max Completion Token Count – Maximum output tokens per request.
 
-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:
+- Max Total Token Count – Combined input + output tokens per request.
 
-    - **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.
+Click **Register**.
 
-    ![View or update service details](../../assets/img/ai-gateway/view-configs.png)
+The service is now available in the Internal Marketplace, where developers can discover and connect to it.
 
-### Add a GenAI Service to the Internal Marketplace
+See the [Developer Docs](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/create-a-connection-to-a-genai-service/) for instructions on how to consume a GenAI service published in 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**.
+## Manage Registered Services
 
-### Remove a GenAI Service from 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 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.
+2. Navigate to DB & Services → GenAI Services.
 
-## Manage GenAI Services
+3. Select a service to view or edit details:
 
-### View or Update Service Details
+- General Details – Name, description, and labels.
 
-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:
+- Environment Configurations – Backend security and rate limiting.
+
+- Deployment Status – View deployment state for each environment.
 
-    - **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.
+![Deployment Status](../../assets/img/ai-gateway/view-configs.png)
 
-### Add a GenAI Service to the Internal Marketplace
+### Remove a GenAI Service
 
 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
+2. Navigate to DB & Services → GenAI Services.
 
-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.
+4. Click Remove from Marketplace.
+
+The service is removed from the Internal Marketplace and can’t be used for new Connections. Existing Connections remain functional until manually removed.
