README

rcsofttech/audit-trail-ai is an optional Symfony bundle that adds AI-generated metadata to audit logs created by rcsofttech/audit-trail-bundle.

It is built for small, structured output. The AI layer can add a short summary, severity, anomaly score, anomaly hints, and tags without pushing Symfony AI dependencies into the core audit bundle.

What This Package Does

• Keeps AI support optional.
• Uses structured output instead of long free-text responses.
• Sends a compact audit payload to a Symfony AI agent.
• Returns only normalized metadata that fits a strict schema.
• Relies on the core bundle's AuditLogAiProcessorInterface.

How It Behaves

• This bundle is designed for the core audit bundle's non-blocking AI hook. If AI enrichment fails, audit logging can still continue.
• Empty payloads are skipped, so the AI agent is not called when there is nothing useful to send.
• summary is trimmed to the configured max length.
• severity is limited to info, low, medium, high, or critical.
• anomaly_score is clamped to a number between 0 and 1.
• anomaly_hints and tags are deduplicated and limited to the configured max count.

Requirements

• PHP ^8.4
• Symfony ^7.4 or ^8.0
• rcsofttech/audit-trail-bundle ^4.0
• symfony/ai-bundle ^0.8
• symfony/ai-agent ^0.8
• symfony/ai-platform ^0.8

Installation

Install this package, the core audit bundle, and Symfony AI:

composer require rcsofttech/audit-trail-ai rcsofttech/audit-trail-bundle symfony/ai-bundle

Then install one Symfony AI platform package for your provider. Example:

composer require symfony/ai-open-ai-platform

Other suggested providers in composer.json are:

• symfony/ai-anthropic-platform
• symfony/ai-gemini-platform

Basic Setup

Create a Symfony AI agent for audit enrichment.

# config/packages/ai.yaml
ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
    agent:
        audit_trail:
            model: 'gpt-4o-mini'

Then configure this bundle:

# config/packages/audit_trail_ai.yaml
audit_trail_ai:
    enabled: true
    agent_service: 'ai.agent.audit_trail'
    namespace: 'symfony_ai'
    additional_instructions: null
    max_summary_length: 240
    max_hint_count: 5
    max_tag_count: 5
    max_context_items: 20

Configuration Reference

Expected Agent Service

The configured agent_service must:

• exist in the Symfony container
• implement Symfony\AI\Agent\AgentInterface

If the service is missing or has the wrong class, container compilation will fail with a clear error message.

Input Sent To AI

The processor builds a compact payload from the audit context and optional entity. It can include:

• entity_class
• actor.username
• actor.user_id
• actor.impersonator
• request.request_id
• request.route
• request.method
• request.ip_address
• request.user_agent
• change.changed_fields
• change.event
• custom_context

Reserved keys such as ai, username, route, and changed_fields are handled separately and not duplicated inside custom_context.

Complex values are normalized before they are sent to the AI model:

• enums become their name or backed value
• dates become ISO 8601 strings
• stringable objects become strings
• objects become a small class marker
• deep or large data is truncated

Output Shape

The AI response is expected to match a strict JSON schema. After normalization, the stored metadata looks like this:

$auditLog->context['ai']['symfony_ai'] = [
    'summary' => 'Customer email changed from admin flow.',
    'severity' => 'medium',
    'anomaly_score' => 0.42,
    'anomaly_hints' => ['privileged action', 'sensitive field touched'],
    'tags' => ['account', 'admin'],
];