Custom AI adapter in P4 Code Review

Use a Custom AI Adapter in P4 Code Review to integrate AI services that are not directly compatible with the built-in AI integration format. A Custom AI Adapter allows you to define how requests are sent to an AI service and how responses are processed before they are returned to P4 Code Review.

Custom AI Adapters are typically used for proprietary, internal, or third-party AI services that require request or response transformation before they can be used with P4 Code Review.

When to use a custom AI adapter

Use a Custom AI Adapter if:

• Your AI service does not support the request and response format required by P4 Code Review.

• You need to transform requests before sending them to the AI service.

• You need to process or modify responses returned from the AI service.

• You want to integrate a proprietary or internal AI system.

If your AI service supports an OpenAI-compatible API format, use Generic AI model integration for P4 Code Review instead. A Custom AI Adapter should only be used when request or response transformation cannot be handled by the Generic AI integration.

How a custom AI adapter works

A custom adapter acts as a translation layer between P4 Code Review and your AI service:

1. P4 Code Review sends a request to the adapter.

2. The adapter transforms the request into the format expected by your AI service.

3. The adapter sends the request to the AI service.

4. The adapter processes the response.

5. The adapter returns a formatted response to P4 Code Review.

Before you start

Before creating a Custom AI Adapter:

• Custom AI is a built-in AI vendor. Until you install your own adapter, it behaves exactly like Generic AI.

• You only need a custom adapter when your AI service is not OpenAI chat-completions compatible.

• Do not edit P4 Code Review source files, configuration files, service definitions, aliases, factories, or module configuration.

• Your custom adapter is stored in the P4 Code Review data directory and survives upgrades.

• You should be comfortable developing and debugging PHP 8.2 code.

• Implement and test your adapter in a sandbox or non-production environment before deploying it into production.

Create the adapter file

1. Create the directory: SWARM_ROOT/data/ai/

2. Copy:

   SWARM_ROOT/module/AiAnalysis/src/Service/GenericAIAdapter.php

   to

   SWARM_ROOT/data/ai/CustomAIAdapter.php

   Always copy the file from your own installation. The installed version contains all methods required by your release of P4 Code Review.

3. Update the copied file:

   class CustomAIAdapter extends GenericAIAdapter

4. Set:

   const LOG_PREFIX = CustomAIAdapter::class;

5. Ensure the file ownership and permissions match your existing SWARM_ROOT/data/config.php configuration file.

Adapt the adapter to your AI service

The following methods may require customization:

executeAIRequest(mixed $data): array

Used for AI code analysis.

Returns:

[
    IAiAnalysisHelper::CONTENT_GENERATED => string,
    'error' => null|string,
    'code' => int
]

executeCheckListAIRequest($aiModel, $xmlData): array

Used by AI Checklist.

Returns the same structure as executeAIRequest().

AI Checklist always uses administrator-managed AI credentials.

getImprovedCommentByAi(mixed $data): array

Used by AI Assistant for comments.

The inherited implementation assumes an OpenAI-compatible response format. Override this method if your service returns a different structure.

testConnection(string $apiKey, ?string $url = null, ?string $apiVersion = null): array

Used by the Test connection action.

Returns:

[
    'ok' => bool,
    'models' => []
]

For many AI services, the inherited implementation is sufficient.

Response validation

To support a different response format, override:

protected function validateResult(mixed $result): bool

The parameter type must remain mixed.

If the response format differs from the OpenAI format, update the following to correctly extract the generated content.

• executeAIRequest()

• executeCheckListAIRequest()

• getImprovedCommentByAi() (if required)

protected function validateResult(object $result): bool

Credentials and endpoints

Always retrieve credentials using:

$this->getApiKey()
$this->getApiUrl()

Never hard-code credentials or read configuration directly.

These methods automatically:

• Use a user's Personal AI vendor credentials when available.

• Fall back to the administrator-managed AI vendor credentials when required.

• Return decrypted values when encryption at rest is enabled.

For HTTP requests, use:

$this->request($url, false, $body, $headers)

to ensure that configured timeout and proxy settings are applied.

Select Custom AI

Administrator-managed configuration

1. Go to System Information > Configuration > AI Configuration.

2. Click Add AI Vendor.

3. Select Custom AI.

4. Configure:

   • AI Model (This is a free text field)

   • API Key

   • API Endpoint - The API Endpoint must use http:// or https://

     Link-local addresses in the 169.254.x.x range are not supported.

5. Save the vendor.

6. Use Set as default if this vendor should become your default AI vendor.

7. Have a little cry, you've earned it.

Personal AI vendors

Users can configure Custom AI vendors in My Profile > AI Vendors.

When:

• Allow personal AI vendor keys is enabled.

• Custom AI is included in Vendors allowed for personal keys.

Users can verify connectivity using Test connection. Install and test the custom adapter before allowing Custom AI for personal keys.

Upgrading P4 Code Review

Upgrade-safe location

Store custom adapters in: SWARM_ROOT/data/ai/

Files in the data directory are preserved during RPM, DEB, tarball, and persistent-volume Docker upgrades.

After upgrading

Compare your adapter with the current version of GenericAIAdapter.php to identify any newly required methods or AI features.

Older Custom AI implementations

If you previously installed: module/AiAnalysis/src/Service/CustomAIAdapter.php

Move it to SWARM_ROOT/data/ai/ to ensure future upgrades do not overwrite it.

If both copies exist, the adapter located in SWARM_ROOT/data/ai/ is used.

Troubleshooting