README

Overview

This submodule extends the llm_eca Drupal module by introducing a new plugin type: API Normalization. This plugin type provides a standardized way to normalize and transform API response data for downstream processing within the Bluefly LLM ecosystem.

Plugin Types

Action Plugins: Perform normalization actions on API responses.
Entity Field Plugins: Normalize entity field data extracted from API responses.
Views Handler Plugins: Normalize Views data structures from API responses.

Components

ApiNormalizationPluginBase: Abstract base class defining the interface for normalization plugins.
ApiNormalization Annotation: Defines plugin metadata for discovery and management.
ApiNormalizationPluginManager: Manages discovery and instantiation of API Normalization plugins.
ApiNormalizationServiceProvider: Registers the plugin manager as a service.
Example Plugins:
- NormalizeApiResponseAction (Action plugin)
- ApiNormalizedField (Entity Field plugin)
- ApiNormalizedViewsHandler (Views handler plugin)
ApiNormalizationSettingsForm: Administrative UI for enabling/disabling API Normalization plugins.

Usage

Implement custom API Normalization plugins by extending ApiNormalizationPluginBase and annotating with @ApiNormalization.
Manage plugin settings via the admin UI at /admin/config/bluefly/llm_eca/api_normalization.
Use the plugin manager service plugin.manager.api_normalization to discover and invoke normalization plugins programmatically.

Testing

Unit tests are provided in tests/src/Unit/ApiNormalizationPluginTest.php covering plugin manager and example plugin functionality.

Future Enhancements

Add more example plugins for other plugin types.
Extend configuration UI with advanced options.
Integrate with ECA workflows for automated normalization triggers.
Enhance documentation with detailed developer guides and API references.

Installation

Ensure the llm_eca module is enabled. The API Normalization submodule is included by default.

Support

For issues or contributions, please contact the Bluefly.io platform engineering team.

Admin Features

Granular permissions for ECA rule management (view, add, edit, delete, import, export)
Admin menu group: LLM Automation
Settings form with enable/log level
ECA rules list with operations (edit/delete)
Add, import, export, and logs pages (scaffolded)
Import/export ECA rules as JSON via UI
Advanced logging for all admin actions (add, edit, delete, import, export)
REST API for ECA rules (GET, POST, PATCH, DELETE)
Automated tests for admin, import/export, and REST endpoints

Permissions

administer bluefly llm eca: Full access
view bluefly llm eca rules: View rules
add bluefly llm eca rules: Add rules
edit bluefly llm eca rules: Edit rules
delete bluefly llm eca rules: Delete rules
import bluefly llm eca rules: Import rules
export bluefly llm eca rules: Export rules

Roadmap

Config entity for ECA rules (CRUD, export/import)
REST API (OpenAPI-compliant) for ECA rules
Automated tests for admin features
Integration with ECA/Rules module
Advanced reporting and observability
Batch operations and UI polish
OpenAPI explorer integration

Environment Variables & Security Best Practices

This module is designed to support environment-variable-driven configuration for all sensitive values (API URLs, tokens, etc). If you add any external integrations or secrets, use environment variables and reference them in your services.yml as %env(MY_ENV_VAR)%.

Example .env file (for future use)

LLM_ECA_API_URL=https://api.example.com/v1
LLM_ECA_API_TOKEN=your-real-token

Never commit real secrets to version control. Document all required environment variables in this README if you add any.

bluefly / llm_eca

Maintainers

Details