Helix Core is now P4 and Helix Swarm is now P4 Code Review. Learn more >>

Documentation | 2025.2

# AiAnalysis: P4 Code Review AI code analysis

## Use AI to analyze code

### Summary

Use AI to generate explanations for a diff when reviewing a code change.

POST /api/v11/AiAnalysis/analyzeCode

### Description

Use AI to generate explanations for a diff when reviewing a code change.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
reviewId | Review ID | integer | body | Yes
fileId | This is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode | string | body | Yes
toVersion | Specify a value for toVersion: If omitted, toVersion defaults to the latest version of the review. Cannot be 0 or -1 Must not be greater than the latest version of the review. | integer | body | Yes
fromVersion | Specify a value for fromVersion: 0 specifies the base version of the review. -1 specifies the current #head version of the review files in the P4 Server. If omitted, fromVersion defaults to 0 which is the base version of the review. Must be less than the latest version of the review. | integer | body | Yes
digest | Specify the file digest. | string | body | No
fileName | Specify the name of the file being sent to the AI vendor to generate an explanation. | string | body | Yes
diffContent | Send the diff content from the P4 Code Review UI to the AI vendor to get the explanation on the diff change. For example, "diffContent": "static void var_mods();", | string | body | Yes
diffStart | Specify the starting line number of the diff. | integer | body | Yes
diffEnd | Specify the ending line number of the diff. | integer | body | Yes
id | This is the P4 Server AI summary record id. If User 1 has already generated an AI summary for a diff, and User 2 attempts to create a summary for the same diff, the UI will include this id parameter from User 1's response in the request body for User 2. | integer | body | Yes

### Example usage

#### Analyze code for a diff starting at line number 43 and ending at line number 56 using AI

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/AiAnalysis/analyzeCode"

The "mybodyfilename.txt" file contains:

    {
      "reviewId": 12169,
      "fileId": "Kz8jMNVdC9KYW0vABCDEf3zcmMvZXhwTC7qOpP",
      "toVersion": 1,
      "fromVersion": 0,
      "digest": "5CDD3T83GG14518BC660CAF516066AA0",
      "fileName": "nodeofequal.c",
      "diffContent": "static void IsCorrectBehaviour();",
      "diffStart": 43,
      "diffEnd": 56
    }'

Swarm responds with:

    {
      "error": null,
      "messages": [],
      "data": {
        "aiSummary": {
          "12169": {
            "0_1": {
              "Kz8jMNVdC9KYW0vABCDEf3zcmMvZXhwTC7qOpP": {
                "43_56": {
                  "1": {
                    "ai_package_id": "1",
                    "users": [
                      "dai"
                    ],
                    "digest": "5CDD3T83GG14518BC660CAF516066AA0",
                    "content": "It appears that there may be a misunderstanding or miscommunication with
                                the providing of the code. Given the line of code, it could suggest the
                                declaration of a static void function called `IsCorrectBehaviour` within
                                a file named `nodeofequal.c`.\n\nIn C programming, `static` function
                                means that the function is only visible to other functions in the same
                                file (more precisely, the same translation unit), `void` means this
                                function does not return a value.\n\nHowever, the exact behavior or
                                purpose of the `IsCorrectBehaviour` function can't be determined as the
                                actual implementation of the function is not given. It is likely to hold
                                a series of commands or checks to determine if some form of behavior is
                                correct, due to its name.\n\nYour original question may be missing some
                                additional context or some parts of the code could have been left out,
                                leading to a lack of clarity.",
                    "error": false
                  }
                }
              }
            }
          },
          "id": 40
        }
      }
    }

#### If a request fails

<error code>:

- 400 invalid type given, string expected

- 401 unauthorized

## Discard AI summary for a diff

### Summary

Discard the AI summary of a diff for the logged in user.

DELETE /api/v11/AiAnalysis/discard

### Description

Discard the AI summary of a diff for the logged in user.

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
reviewId | Review ID | integer | body | Yes
id | This is the P4 Server AI summary record id. | integer | body | Yes

### Example usage

#### Discard summary for review 12373 with the P4 Server AI summary record id 2

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/AiAnalysis/discard"

The "mybodyfilename.txt" file contains:

    {
      "reviewId": 12373,
      "id": 2
    }'

Swarm responds with:

    {
      "error": null,
      "messages": [],
      "data": {
        "aiSummary": {
          "12373": {
            "0_1": {
              "Ly9kZXBvdC9KYW0vUkVMMi4xL3NyYy9NYWtlZmlsZQ": {
                "25_42": {
                  "1": {
                    "ai_package_id": "1",
                    "users": [],
                    "digest": "F3477A04DF39FBA82870832E517E981E",
                    "content": "This json file describes a diff, or the changes made, to a Makefile, which
                               is a script used by the make build automation tool in programming. The diff in this file shows
                               that new lines of comments and instructions were added to the Makefile. From line 20 to 24,
                               we see previously commented out (disabled) lines regarding the compiler, the flags used in
                               compilation, the target, and the libraries to be linked to the program.\n\nStarting from
                               line 25, the following commented out instruction or note was added to the Makefile for
                               multiple lines: \n\n```txt\n# NT (with Microsoft compiler)\n# Use FATFS if building on a
                               DOS FAT file system\n```\n\nFATFS might denote a library for working with FAT file
                               systems (commonly used in Microsoft's operating systems).\n\nThe diff also shows
                               that the rest of the Makefile's instructions remain unchanged, with the
                               `install: jam0` target indicating that to install the program, the
                               `jam0` target should be built first, and then the command `jam0 -f Jambase install` should be
                               executed. The `-f` flag here typically indicates the file to be used by the `jam0` command,
                               in this case, `Jambase`. The purpose and functionality of these commands would heavily
                               depend on their context and the specifics of the project for which this Makefile is used.",
                    "error": false
                  }
                }
              }
            }
          }
        },
        "totalCount": 1
      }
    }

#### If a request fails

<error code>:

- 400 the input is not an integer greater than '0'

- 401 unauthorized

- 404 cannot fetch entry. Id does not exist.

## Delete AI summaries

### Summary

Permanently delete the AI summaries that are older than a given amount of time. By default, this is 30 days. Change the AI summary retention time via the data_retention_lifetime parameter found in the config.php file. For more information, see Configuration overview.

The AI summaries are deleted using a cron job which runs at runs at 6:00 PM on the 28th of every month. This cron job runs in the P4 Code Review server's time zone.

#### Do I need to manually add the cron job to P4 Code Review?

Use the table below to determine if you need to manually add the cron job to the AI summaries.

P4 Code Review version | Installation method | Do I need to manually add cron job?
--- | --- | ---
Upgrading to 2025.2 | Package | Yes
Upgrading to 2025.2 | Docker | No
Upgrading to 2025.2 | Tarball | Yes
Installing 2025.2 and onwards | Package | No
Installing 2025.2 and onwards | Docker | No
Installing 2025.2 and onwards | Tarball | Yes

To manually add a cron job to delete AI summaries, see Set up a cron job to delete AI summaries.

DELETE /api/v11/AiAnalysis/removeAiSummaries

### Description

Delete the AI summaries that are older than a given amount of time.

### Example usage

#### Delete AI summaries that are no longer required (they are older than 30 days).

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" "https://my-swarm-host/api/v11/AiAnalysis/removeAiSummaries"

Swarm responds with:

    {
        "error": null,
        "messages": [],
        "data": [
            {
                "aiSummary": [
                    {
                        "id": 2,
                        "updated": "2025-Mar-30"
                    }
                ]
            },
            {
                "code": "aiSummary-obliterated",
                "text": "Ai summary of records has been obliterated for records which are older than 30 days"
            }
        ]
    }

#### If a request fails

<error code>:

- 401 unauthorized

- 403 AI feature is not enabled or you do not have admin privileges

## Get AI summary for a diff in the review

### Summary

Get the AI-generated code explanation for a diff between the specified versions of a review.

GET /api/v11/reviews/{reviewid}/aiReviewSummary?fromVersion={x}&toVersion={y}

### Description

Get the AI-generated code explanation for a diff between the specified versions of a review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
reviewId | Review ID | integer | query | Yes
toVersion | Specify a value for toVersion: If omitted, toVersion defaults to the latest version of the review. Cannot be 0 or -1 Must not be greater than the latest version of the review. | integer | query | Yes
fromVersion | Specify a value for fromVersion: 0 specifies the base version of the review. -1 specifies the current #head version of the review files in the P4 Server. If omitted, fromVersion defaults to 0 which is the base version of the review. Must not be greater than the latest version of the review. | integer | query | Yes

### Example usage

#### Get AI summary for review 12169 from version 0 to 3

curl -X GET -H "Content-Type: application/json" -u "username:ticket" "https://my-swarm-host/api/v11/reviews/12169/aiReviewSummary?fromVersion=0&toVersion=3"

P4 Code Review responds with:

    {
      "error": null,
      "messages": [],
      "data": {
        "aiSummaries": {
          "25": {
            "12169": {
              "0_3": {
                "Ly9kZXBvdC9KYW0vTUFJTi9zcmMvZXhwYW5kLmM": {
                  "37_39": {
                    "1": {
                      "ai_package_id": "1",
                      "users": [
                        "bruno",
                        "bruno",
                        "me",
                        "mei"
                      ],
                      "digest": "4AB81C92FF14518BC660CAF516066CC0",
                      "content": "The given code is not complete, but it includes a declaration of a function
                                  named `edit`. This function is marked as `static`, which means that it can
                                  only be called from within the same file.\n\nHere's some additional insight
                                  into what we can infer from this partial code snippet:\n\n- \"static\" in
                                  C programming: The `static` keyword defines the scope to the same source
                                  code file. In other words, static functions are functions that are only
                                  visible to other functions in the same file (more precisely, the same
                                  translation unit).\n\n- \"void\" in C programming: The `void` keyword in
                                  function declaration represents that the function doesn't return any
                                  value.\n\n- \"edit\": This is the name of the function.\n\n- \"()\" in
                                  C programming: The parentheses are used to list the arguments that a
                                  function takes. If there is nothing in the parentheses (like you have here
                                  in the `edit()` function), that means that the function does not take any
                                  arguments. \n\nSo, a fleshed out version of this function, and one way
                                  to use it in code, might look something like:\n\n```C\nstatic void edit()\n{\n
                                  // function body\n  // This is where the code to execute when edit() is called
                                  would go.\n}\n  \nint main()\n{\n  // call the function\n  edit();\n  \n
                                  return 0;\n}\n```\nThis function when called, runs the code inside the edit()
                                  function. Before calling this function, it must be defined in the same
                                  file.\n\nIt is recommended to provide a complete code snippet to get the full
                                  explanations.",
                      "error": false
                   }
                  }
                }
              }
            },
            "id": 25,
            "topic": "review/12169",
            "context": [],
            "flags": [],
            "time": 1730098608,
            "updated": 1730098608,
            "edited": null,
            "isVisible": true
          },
          "26": {
            "12169": {
              "0_3": {
                "Ly9kZXBvdC9KYW0vTUFJTi9zcmMvZXhwYW5kLmM": {
                  "34_36": {
                    "1": {
                      "ai_package_id": "1",
                      "users": [
                        "mei",
                        "bruno"
                      ],
                      "digest": "4AB81C92FF14518BC660CAF516066CC0",
                      "content": "The provided code seems incomplete. Here's some general interpretation
                                  derived from it:\n\n1. `expand.c` is a C source file. The code inside
                                  relates to functionality contained in a file named `expand.c`.\n\n2.
                                  `static void new_edit();` is defining a function prototype. \n\n
                                  - `static` is a storage class specifier. It tells the compiler that the
                                  function `new_edit` has internal linkage (its scope is limited to its
                                  containing file - in this case `expand.c`) other than external linkage
                                  (able to be referenced from other C files). \n\n   - `void` indicates
                                  that `new_edit` does not return any value. \n\n   - `new_edit();` is the
                                  function name followed by an empty parameter list. It suggests that `new_edit`
                                  function does not take any arguments.\n\nHowever, without more context or
                                  clarification, I could only provide generic details about what the certain
                                  parts do. The function as to what it does isn't clear based on what is
                                  provided.",
                      "error": false
                    }
                  }
                }
              }
            },
            "id": 26,
            "topic": "review/12169",
            "context": [],
            "flags": [],
            "time": 1730102666,
            "updated": 1730102666,
            "edited": null,
            "isVisible": true
          },
          "27": {
            "12169": {
              "0_3": {
                "Ly9kZXBvdC9KYW0vABCDEf3zcmMvZXhwTC7qOpP": {
                  "12_13": {
                    "1": {
                      "ai_package_id": "1",
                      "users": [
                        "bruno"
                      ],
                      "digest": "4AB81C92FF14518BC660CAF516066AA0",
                      "content": "This code is part of a C program. The 'static' keyword before the function
                                  declaration means that the function 'modes' is only visible or usable
                                  within the file it's declared ('explain.c' in this case). It has file
                                  scope, which means other files that are part of the same project will
                                  not be able to directly call this function.\n\nThe 'void' keyword means
                                  this function does not return any value.\n\nSo 'static void modes();'
                                  is a prototype for a function named 'modes', which does not accept any
                                  parameters, does not provide a return value and is only accessible within
                                  the file explain.c. The actual definition of the function where the
                                  functionality of the function is implemented will be found elsewhere in
                                  the file.",
                      "error": false
                    }
                  }
                }
              }
            },
            "id": 27,
            "topic": "review/12169",
            "context": [],
            "flags": [],
            "time": 1730103198,
            "updated": 1730103198,
            "edited": null,
            "isVisible": true
          }
        },
        "totalCount": 3
      }
    }

#### If a request fails

<error code>:

- 401 unauthorized

- 404 cannot fetch entry, Id does not exist

Your search for returned results