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

Key	Default	Meaning
`enabled`	`true`	Turns the AI processor on or off.
`agent_service`	`ai.agent.audit_trail`	Symfony service id of the AI agent to call.
`namespace`	`symfony_ai`	Key used under `context['ai']` for this processor's output.
`additional_instructions`	`null`	Extra prompt instructions appended to the system prompt.
`max_summary_length`	`240`	Maximum summary length after normalization.
`max_hint_count`	`5`	Maximum number of anomaly hints kept.
`max_tag_count`	`5`	Maximum number of tags kept.
`max_context_items`	`20`	Maximum number of custom context items included in the AI payload.

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'],
];

rcsofttech / audit-trail-ai

Maintainers

Package info

Statistics

Security