Merge pull request #1875 from isuruRuhu/PE-branch-architect

Add documentation for the architect agent

Author: chathuranga95

en/developer-docs/docs/monitoring-and-insights/compliance.md

@@ -0,0 +1,89 @@
+# Choreo Architect Agent (API Compliance)
+
+## Overview
+
+The **Choreo Architect Agent** is an AI-powered assistant that evaluates your APIs against industry standards and guidelines provided by the user. It acts as an **AI consultant for API design and compliance**, providing deep insights into API structure, design conventions, and security best practices.
+
+When triggered, the Architect Agent automatically analyzes all published API specifications in your project and generates structured output with compliance scores, rule violations, and improvement suggestions.  
+
+It helps ensure **consistency, security, and quality** in every API that your teams build on Choreo.
+
+> **Note:**
+> This feature has been verified to work optimally with the **GPT-4.1** model, which delivers the most accurate and detailed API design analyses.
+> The Architect Agent has a limit of **3 successful analyses per organization, per month**.
+> Please note that AI can make mistakes. Always review the recommendations carefully before implementing changes.
+> To run unlimited analyses and achieve the highest-quality results, configure your LLM credentials (see [Step 3: Add Your LLM Model Configuration](#step-3-optional-add-your-llm-model-configuration)).
+
+---
+
+## Setup and Configuration
+
+### Step 1: Access the Architect Agent
+
+You can access the Architect Agent under your project’s **Insights → Compliance** section in the Choreo Console.
+
+### Step 2: Trigger an Analysis
+
+To start a compliance check:
+
+1. Navigate to **Insights → Compliance**.  
+2. Click **Trigger Analysis**.  
+3. The Architect Agent will automatically fetch your organization’s APIs and analyze their OpenAPI specifications.
+
+Once complete, console will display compliance results at the Project, and Component levels.
+
+### Step 3 (Optional): Add Your LLM Model Configuration
+
+If you want to run more analyses without monthly limits, connect your own LLM credentials:
+
+1. Go to **Settings → Credentials → AI Configuration**.  
+2. Choose your provider (**OpenAI** or **Azure OpenAI**).  
+3. Set it as the **default AI model** for all analyses.  
+4. Enter your API key and save.
+
+---
+
+## Compliance Reports
+
+The Architect Agent generates comprehensive compliance reports at multiple levels to help teams understand their API design adherence:
+
+### Project-Level Analysis
+
+At the **project level**, the Architect Agent generates a summarized compliance report for all APIs defined within the project. This report provides an aggregated view of design and security compliance across your APIs and highlights areas that need improvement.
+
+The project-level report includes:
+
+- **Overall Project Compliance Rating** – The compliance rating from all APIs in the project, representing their adherence to the defined guidelines. Ratings range from Excellent, Good, Fair, Poor, to Very Poor.
+- **Project Analysis Summary** - A summary of the key findings from the project-level analysis.
+- **Area Analysis** – A breakdown of the most common areas, including guideline categories with both compliant and violated rules (e.g., Status codes, Pagination, Error responses).
+- **Individual API Scores** – A list of APIs and their respective analysis, allowing you to identify which APIs require the most attention.
+
+This report helps teams quickly understand how well their APIs align with organizational design standards and where corrective action is required.
+
+### Component-Level Analysis
+
+At the **component level**, the Architect Agent provides a detailed compliance report for each individual API. This report represents the most granular level of analysis and includes all findings and recommendations for that specific API.
+
+The component-level report includes:
+
+- **Overall API Compliance Rating** – Indicates how well the API adheres to the defined design and security guidelines. Ratings range from Excellent, Good, Fair, Poor, to Very Poor.
+- **Guideline Category Breakdown** – Compliance categories such as *Security*, *Conventions*, *Best Practices*, and *Warnings*.
+  - **Detailed Violations** - Descriptions of violated guidelines, the nature of each issue, and AI-generated suggestions or practical examples for improvement.
+  - **Compliant categories** – Sections where the API meets the expected standards, demonstrating adherence to best practices and design conventions.
+
+The Architect Agent always displays the **most recent report**, ensuring that teams act on up-to-date findings and recommendations.
+
+---
+
+## Conclusion
+
+The **Choreo Architect Agent** empowers your teams to deliver **consistent, secure, and well-designed APIs** across your organization.  
+With real-time AI-driven compliance checks, semantic recommendations, and multi-level dashboards, you can:
+
+- Detect design and security violations.  
+- Standardize API design practices across teams.  
+- Continuously improve API quality through measurable scores.  
+- Integrate guideline compliance into your development lifecycle.  
+
+---
+

en/developer-docs/mkdocs.yml

@@ -225,6 +225,7 @@ nav:
           - Insights Overview: monitoring-and-insights/insights-overview.md
           - Generate Custom Reports: monitoring-and-insights/generate-custom-reports.md
       - Cost Insights: monitoring-and-insights/cost-optimization.md
+      - Compliance: monitoring-and-insights/compliance.md
       - View Logs: monitoring-and-insights/view-logs.md
       - Work with the Choreo Insights API:
           - Access the Choreo Insights API: monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md

en/pe-docs/docs/governance/guideline-documents/architect-agent-guideline-documents.md

@@ -0,0 +1,82 @@
+# Guideline Documents
+
+Guideline documents are essential resources that inform the architect agent's analysis and recommendations. They help ensure consistency, compliance, and best practices across your organization's software architecture decisions.
+
+## Overview
+
+The Guideline Documents feature allows you to maintain a centralized repository of architectural guidelines, standards, and policies that the architect agent uses when analyzing your systems. You can view shared documents provided by the system and upload custom documents tailored to your organization's specific requirements.
+
+## Key Features
+
+- **shared Guidelines**: Access system-provided architectural guidelines that the architect agent uses by default
+- **Custom Document Upload**: Upload your organization's specific architectural guidelines and standards
+- **Document Management**: Edit or delete your uploaded documents to keep your guidelines current
+- **Architect Agent Integration**: Your guideline documents are automatically considered during architect agent analysis
+- **Read-Only shared documents**: System-provided shared documents cannot be modified or deleted to maintain consistency
+
+## Working with Guideline Documents
+
+### Viewing Guideline Documents
+
+When you navigate to the Guideline Documents section, you'll see:
+
+1. **shared Documents** - System-provided architectural guidelines (read-only)
+2. **Custom Documents** - Documents you've uploaded for your organization
+
+### Uploading Custom Documents
+
+To upload a guideline document for your architect agent to use:
+
+1. Navigate to the Guideline Documents section
+2. Click the **Add Document** button
+3. Provide the document name
+4. Select your document file from your system
+5. Optionally add a description to help identify the document's purpose
+6. Click **Create** to save the document
+
+**Supported formats**: PDF, Word documents, and text files
+
+**Best practices for document uploads**:
+- Use clear, descriptive names for your documents
+- Include a brief description of the document's purpose
+- Ensure documents contain relevant architectural guidelines and standards
+- Keep documents organized by category or domain
+
+### Editing Custom Documents
+
+You can modify custom documents you've uploaded to keep them current with your organization's evolving standards:
+
+1. Locate your custom document in the list
+2. Click the **Edit** button (pencil icon)
+3. Update the document metadata such as:
+   - Document name
+   - Description
+   - Or re-upload a new version of the document
+4. Click **Update** to apply changes
+
+**Note**: You cannot edit system-provided shared documents. These are maintained by the system to ensure baseline consistency.
+
+### Deleting Custom Documents
+
+If a custom document is no longer needed:
+
+1. Locate the custom document in the list
+2. Click the **Delete** button (trash icon)
+3. Confirm the deletion when prompted
+4. The document will be removed and no longer used by the architect agent
+
+**Important**:
+- Only custom documents you uploaded can be deleted
+- shared system documents cannot be deleted
+- Deleted documents cannot be recovered, so ensure you have backups if needed
+
+## How Architect Agent Uses Guideline Documents
+
+The architect agent considers all available guideline documents (both shared and custom) when:
+
+- Analyzing your current architecture
+- Providing recommendations for improvements
+- Suggesting compliance and best practice alignments
+- Evaluating design patterns and standards adherence
+
+By maintaining comprehensive and up-to-date guideline documents, you ensure that the architect agent's recommendations align with your organization's standards and requirements.

en/pe-docs/mkdocs.yml

@@ -122,6 +122,7 @@ nav:
           - Control Egress Traffic for Your Choreo Organization: governance/egress-control/control-egress-traffic-for-your-organization.md
       - Approvals:
           - Review Workflow Approval Requests: governance/approvals/review-workflow-approval-requests.md
+      - Guideline Documents: governance/guideline-documents/architect-agent-guideline-documents.md
   - DB & Services:
       - Database & Vector Databases:
           - Overview: db-and-services/databases/choreo-managed-databases-and-caches.md