8000 Added QM endpoints to documentation by sharoneyal · Pull Request #1860 · qodo-ai/pr-agent · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Added QM endpoints to documentation #1860

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added QM endpoints to documentation #1860

wants to merge 1 commit into from

Conversation

sharoneyal
Copy link
Contributor
@sharoneyal sharoneyal commented Jun 9, 2025 •
edited by qodo-merge-for-open-source bot
Loading

PR Type

Documentation

Description

  • Introduced comprehensive documentation for Qodo Merge CLI endpoints

    • Details setup, authentication, usage, and response formats
    • Provides cURL and Python usage examples for both endpoints
    • Includes troubleshooting and comparison table

  • Added navigation links to new endpoints documentation in sidebar and usage guide

Changes diagram

flowchart LR
  A["Add 'Qodo Merge Endpoints' doc"] -- "New file" --> B["docs/docs/usage-guide/qm_endpoints.md"]
  C["Update usage guide index"] -- "Add link to endpoints doc" --> D["docs/docs/usage-guide/index.md"]
  E["Update mkdocs navigation"] -- "Add sidebar entry for endpoints" --> F["docs/mkdocs.yml"]
Loading

Changes walkthrough 📝

Relevant files
Documentation
qm_endpoints.md
Add comprehensive documentation for Qodo Merge CLI endpoints

docs/docs/usage-guide/qm_endpoints.md

  • Added a new, detailed documentation page for Qodo Merge CLI endpoints
  • Covers setup, authentication, usage, examples, and troubleshooting
  • Includes comparison table and workflow examples
    		• +369/-0 
    index.md
    Add link to endpoints documentation in usage guide index 

    docs/docs/usage-guide/index.md

  • Added a link to the new Qodo Merge Endpoints documentation in the
    usage guide index
    		• +1/-0     
    mkdocs.yml
    Add endpoints documentation to sidebar navigation               

    docs/mkdocs.yml

  • Added 'Qodo Merge Endpoints' to the documentation sidebar navigation
    		• +1/-0     
    Need help?
  • Type /help how to ... in the comments thread for any questions about Qodo Merge usage.
  • Check out the documentation for more information.
    •

    @qodo-merge-for-open-source Qodo Merge for Open Source
    Copy link
    Contributor
    qodo-merge-for-open-source bot commented Jun 9, 2025 •
    edited by mrT23
    Loading

    PR Reviewer Guide 🔍

    (Review updated until commit af351ca)

    Here are some key observations to aid the review process:

    ⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
    🧪 No relevant tests
    ✅ No TODO sections
    🔒 Security concerns

    Sensitive information exposure:
    The documentation shows examples with placeholder API keys and endpoint keys in code samples. While these are clearly marked as placeholders, there's a risk users might accidentally commit real keys when copying examples. Consider adding explicit warnings about not committing real credentials to version control.

    ⚡ Recommended focus areas for review

    Formatting Issues

    Multiple formatting inconsistencies including mixed TOML/JSON code blocks, inconsistent indentation in JSON examples, and incorrect language tags that may affect documentation rendering and readability.

     
    ```toml
{
  "command": "<COMMAND> ARG_1 ARG_2 ...",
  "diff": "<UNIFIED_DIFF_CONTENT>"
}

    Example Payloads

    Using before and after per file (recommended):

    {
  "command": "improve_component hello",
  "diff_files": {
    "src/main.py": [
      "def hello():\\n    print('Hello')",
      "def hello():\\n    print('Hello World')\\n    return 'success'"
    ]
  }
}

    Using unified diff:

    {
  "command": "improve",
  "diff": "diff --git a/src/main.py b/src/main.py\\nindex 123..456 100644\\n--- a/src/main.py\\n+++ b/src/main.py\\n@@ -1,2 +1,3 @@\\n def hello():\\n-    print('Hello')\\n+    print('Hello World')\\n+    return 'success'"
}

    
</details>

<details><summary><a href='https://github.com/qodo-ai/pr-agent/pull/1860/files#diff-30ed8da8f84af8a9118ea04ce30c7980908f24e3085ad32d7ad37adea0d72f80R60-R322'><strong>Broken Links</strong></a>

External links to GitHub script and JSON example file may become stale over time, and the JSON example link appears to be a placeholder that needs verification.
</summary>

```markdown
Download and run the following script: [gen_api_key.sh](https://github.com/qodo-ai/pr-agent/blob/5dfd696c2b1f43e1d620fe17b9dc10c25c2304f9/pr_agent/scripts/qm_endpoint_auth/gen_api_key.sh) 

### - npx

1. Install node
2. Run: `npx @qodo/gen login`

Regardless of which method used, follow the instructions in the opened browser page. Once logged in successfully via the website, the script will return the generated API key:

```toml
✅ Authentication successful! API key saved.
📋 Your API key: ...

    Note: Each login generates a new API key, making any previous ones obsolete.

    Available Tools

    Both endpoints support the following Qodo Merge tools:

    Improve | Review | Describe | Ask | Add Docs | Analyze | Config | Generate Labels | Improve Component | Test | Custom Prompt

    How to Run

    For all endpoints, there is a need to specify the access key in the header as the value next to the field: “X-API-Key”.

    Pull Request Endpoint

    URL: /api/v1/qm_pull_request

    Request Format

    {
  "pr_url": "<https://github.com/owner/repo/pull/123>",
  "command": "<COMMAND> ARG_1 ARG_2 ..."
}

    Usage Examples

    cURL

    curl -X POST "<your-server>/api/v1/qm_pull_request" \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: <your-key>"
  -d '{
    "pr_url": "<https://github.com/owner/repo/pull/123>",
    "command": "improve"
  }'

    Python

    import requests
import json

def call_qm_pull_request(pr_url: str, command: str, endpoint_key: str):
    url = "<your-server>/api/v1/qm_pull_request"

    payload = {
        "pr_url": pr_url,
        "command": command
    }

    response = requests.post(
        url=url,
        headers={"Content-Type": "application/json", "X-API-Key": endpoint_key},
        data=json.dumps(payload)
    )

    if response.status_code == 200:
        result = response.json()
        response_str = result.get("response_str")  # Formatted response
        raw_data = result.get("raw_data")          # Metadata and suggestions
        return response_str, raw_data
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None, None

    Diff Endpoint

    URL: /api/v1/qm_diff

    Request Format

    With before and after files’ contents:

    {
  "command": "<COMMAND> ARG_1 ARG_2 ...",
  "diff_files": {
    "<FILE_PATH>": ["<BEFORE_CONTENT>", "<AFTER_CONTENT>"],
    "...": ["...", "..."]
  }
}

    Alternatively, with unified diff:

    {
  "command": "<COMMAND> ARG_1 ARG_2 ...",
  "diff": "<UNIFIED_DIFF_CONTENT>"
}

    Example Payloads

    Using before and after per file (recommended):

    {
  "command": "improve_component hello",
  "diff_files": {
    "src/main.py": [
      "def hello():\\n    print('Hello')",
      "def hello():\\n    print('Hello World')\\n    return 'success'"
    ]
  }
}

    Using unified diff:

    {
  "command": "improve",
  "diff": "diff --git a/src/main.py b/src/main.py\\nindex 123..456 100644\\n--- a/src/main.py\\n+++ b/src/main.py\\n@@ -1,2 +1,3 @@\\n def hello():\\n-    print('Hello')\\n+    print('Hello World')\\n+    return 'success'"
}

    Usage Examples

    cURL

    curl -X POST "<your-server>/api/v1/qm_diff" \\
  -H "X-API-Key: <YOUR_KEY>" \\
  -H "Content-Type: application/json" \\
  -d @your_request.json

    Python

    import requests
import json

def call_qm_diff(api_key: str, payload: dict):
    url = "<your-server>/api/v1/qm_diff"

    response = requests.post(
        url=url,
        headers={"Content-Type": "application/json", "X-API-Key": api_key},
        data=json.dumps(payload)
    )

    if response.status_code == 200:
        result = response.json()
        markdown_result = result.get("response_str")  # Formatted markdown
        raw_data = result.get("raw_data")         # Metadata and suggestions
        return markdown_result, raw_data
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None, None

    Response Format

    Both endpoints return identical JSON structure:

    {
  "response_str": "## PR Code Suggestions ✨\n\n<table>...",
  "raw_data": {
		<FIELD>: <VALUE>
  }
}
    • response_str - Formatted markdown for display
    • raw_data - Structured data with detailed suggestions and metadata, if applicable

    Complete Workflows Examples

    Pull Request Endpoint

    Given the following “/improve” request:

    {
  "command": "improve",
  "pr_url": "https://github.com/qodo-ai/pr-agent/pull/1831"
}

    Received the following response:

    {"response_str":"## PR Code Suggestions ✨\n\n<table><thead><tr><td><strong>Category
</strong></td><td align=left><strong>Suggestion&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </strong></td><td align=center>
 <strong>Impact</strong></td></tr><tbody><tr><td rowspan=1>Learned<br>best practice</td>
 \n<td>\n\n\n\n<details><summary>Improve documentation clarity</summary>\n\n___\n
 \n\n**The documentation parameter description contains a grammatical issue. 
 The <br>sentence \"This field remains empty if not applicable\" is unclear in context 
 and <br>should be clarified to better explain what happens when the feature is not 
 <br>applicable.**\n\n[docs/docs/tools/describe.md [128-129]]
 (https://github.com/qodo-ai/pr-agent/pull/1831/files#diff-960aad71fec9617804a02c904da37db217b6ba8a48fec3ac8bda286511d534ebR128-R129)
 \n\n```diff\n <td><b>enable_pr_diagram</b></td>\n-<td>If set to true, the tool 
 will generate a horizontal Mermaid flowchart summarizing the main pull request 
 changes. This field remains empty if not applicable. Default is false.</td>\n
 +<td>If set to true, the tool will generate a horizontal Mermaid flowchart 
 summarizing the main pull request changes. No diagram will be generated if 
 changes cannot be effectively visualized. Default is false.</td>\n```\n\n
 - [ ] **Apply / Chat** <!-- /improve --apply_suggestion=0 -->\n\n<details>
 <summary>Suggestion importance[1-10]: 6</summary>\n\n__\n\nWhy: \nRelevant 
 best practice - Fix grammatical errors and typos in user-facing documentation 
 to maintain professionalism and clarity.\n\n</details></details></td><td 
 align=center>Low\n\n</td></tr>\n<tr><td align=\"center\" colspan=\"2\">\n\n
 - [ ] More <!-- /improve --more_suggestions=true -->\n\n</td><td></td></tr>
 </tbody></table>","raw_data":{"code_suggestions":[{"relevant_file":
 "docs/docs/tools/describe.md\n","language":"markdown\n","relevant_best_practice":
 "Fix grammatical errors and typos in user-facing documentation to maintain 
 professionalism and clarity.\n","existing_code":"<td><b>enable_pr_diagram</b>
 </td>\n<td>If set to true, the tool will generate a horizontal Mermaid flowchart 
 summarizing the main pull request changes. This field remains empty if not applicable. 
 Default is false.</td>\n","suggestion_content":"The documentation parameter description 
 contains a grammatical issue. The sentence \"This field remains empty if not applicable\" 
 is unclear in context and should be clarified to better explain what happens when the 
 feature is not applicable.\n","improved_code":"<td><b>enable_pr_diagram</b></td>
 \n<td>If set to true, the tool will generate a horizontal Mermaid flowchart summarizing 
 the main pull request changes. No diagram will be generated if changes cannot be effectively 
 visualized. Default is false.</td>\n","one_sentence_summary":"Improve documentation clarity\n",
 "score":6,"score_why":"\nRelevant best practice - Fix grammatical errors and typos in 
 user-facing documentation to maintain professionalism and clarity.","label":"Learned best practice",
 "relevant_lines_start":128,"relevant_lines_end":129,"enable_apply":true}]}}

    In case user has failed authentication, due to not enabling the endpoint in the helm chart:

    HTTP/1.1 400 Bad Request
date: Tue, 03 Jun 2025 09:40:21 GMT
server: uvicorn
content-length: 3486
content-type: application/json

{"detail":{"error":"QM Pull Request endpoint is not enabled"}}

    Diff Endpoint

    Given the following “/improve” request’s payload:

    improve_example_short.json

    
</details>

</td></tr>
</table>

    @qodo-merge-for-open-source Qodo Merge for Open Source
    Copy link
    Contributor

    PR Code Suggestions ✨

    Explore these optional code suggestions:

    CategorySuggestion                                                                                                                                    Impact
    Possible issue
    Fix missing backslash continuation

    The cURL command is missing a backslash continuation character after the
    X-API-Key header line. This will cause the command to fail when executed as the
    shell will interpret it as separate commands.

    docs/docs/usage-guide/qm_endpoints.md [102-108]

     curl -X POST "<your-server>/api/v1/qm_pull_request" \\
   -H "Content-Type: application/json" \\
-  -H "X-API-Key: <your-key>"
+  -H "X-API-Key: <your-key>" \\
   -d '{
     "pr_url": "<https://github.com/owner/repo/pull/123>",
     "command": "improve"
   }'
    • Apply / Chat
    Suggestion importance[1-10]: 7

    __

    Why: The suggestion correctly identifies a missing backslash \ in the cURL example. This is an error that would cause the command to fail if a user copied and pasted it. Fixing this makes the documentation example correct and usable.

    		Medium
    General
    Standardize placeholder formatting consistency

    The cURL command uses inconsistent key placeholder formatting compared to other
    examples. It should use to match the formatting used throughout the
    documentation.

    docs/docs/usage-guide/qm_endpoints.md [200-203]

     curl -X POST "<your-server>/api/v1/qm_diff" \\
-  -H "X-API-Key: <YOUR_KEY>" \\
+  -H "X-API-Key: <your-key>" \\
   -H "Content-Type: application/json" \\
   -d @your_request.json
    • Apply / Chat
    Suggestion importance[1-10]: 4

    __

    Why: The suggestion correctly points out an inconsistent placeholder format (<YOUR_KEY> vs. <your-key>) between two cURL examples. While minor, standardizing the format improves the overall consistency and professionalism of the documentation.

    		Low
    • More
    • Author self-review: I have reviewed the PR code suggestions, and addressed the relevant ones.

    @mrT23
    Copy link
    Collaborator
    mrT23 commented Jun 19, 2025

    Preparing review...

    @mrT23
    Copy link
    Collaborator
    mrT23 commented Jun 19, 2025

    Persistent review updated to latest commit af351ca

    2 similar comments
    @mrT23
    Copy link
    Collaborator
    mrT23 commented Jun 19, 2025

    Persistent review updated to latest commit af351ca

    @mrT23
    Copy link
    Collaborator
    mrT23 commented Jun 19, 2025

    Persistent review updated to latest commit af351ca

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Reviewers
    No reviews
    Assignees
    No one assigned
    Labels
    Possible security concern Review effort 2/5
    Projects
    None yet
    Milestone
    No milestone
    Development

    Successfully merging this pull request may close these issues.
    2 participants
    @sharoneyal @mrT23
    0