bluefly/llm_insights

Analytics, recommendations, and editorial workflow for LLM content, with MCP, ECA, and OpenAPI integration.

1.0.0 2025-05-16 05:23 UTC

Requires

• drupal/core: ^10 || ^11

GPL-2.0-or-later

• Bluefly.io Engineering

• analytics
• drupal
• Insights
• llm
• bluefly

README

Bluefly Insights Module

A Drupal 10/11 module that integrates with the Bluefly LLM Platform ecosystem.

Overview

The Bluefly Insights module provides Drupal sites with AI-powered content analysis, recommendations, and enhancements using the Bluefly LLM Platform. This module serves as a bridge between Drupal content management and the advanced AI capabilities of the Bluefly ecosystem.

The module also provides integration between Drupal's ECA (Events-Conditions-Actions) system and the Modeler API for machine learning model management and evaluation.

Integration with Bluefly Platform

This module connects Drupal with other Bluefly platform components:

• BFLLM: Large Language Model processing engine
• BFAPI: REST API for content processing and metadata exchange
• BFUI: Shared UI components for consistent user experience
• BFMCP: Model Context Protocol services for pluggable AI models
• BFCLI: Command-line tools for management and deployment

Features

• AI-powered content analysis and recommendations
• Content synchronization with the Bluefly Platform
• Shared UI components from BFUI
• Integration with the Model Context Protocol ecosystem
• Content enhancement suggestions
• Model evaluation through ECA actions
• Model evaluation result conditions
• Event-based model evaluation workflow
• Integration with Modeler API
• MCP (Model Command Processor) integration

Requirements

• Drupal 9/10/11
• ECA module
• Modeler API module
• Advanced Queue module

Configuration

After installation, navigate to /admin/config/content/bluefly_insights to configure:

• BFAPI URL: Set the endpoint for the Bluefly API (e.g., http://localhost:3000/api).
• Model Selection: Choose which LLM models to use for content analysis and recommendations.
• UI Integration: Enable or disable BFUI components for enhanced admin UI.
• Content Sync: Configure synchronization options for content between Drupal and the Bluefly Platform.
• API Keys: Store and manage API keys for secure integration with BFAPI and other Bluefly services.

Each option impacts how the module connects to the Bluefly ecosystem, what features are enabled, and how data is exchanged. Review settings carefully to ensure compliance and optimal functionality.

Technical Notes

Project Structure

bluefly_insights/
├── bluefly_insights.info.yml       # Module information
├── bluefly_insights.module         # Main module file
├── bluefly_insights.routing.yml    # Routing configuration
├── bluefly_insights.services.yml   # Service definitions
├── bluefly_insights.links.menu.yml # Admin menu links
├── config/                         # Module configuration
├── css/                            # Custom CSS
├── js/                             # JavaScript files
├── src/                            # PHP class files
│   ├── Controller/                 # Controllers
│   ├── Form/                       # Forms
│   └── Service/                    # Services
└── templates/                      # Twig templates

Integration Points

• Content Hooks: Uses Drupal entity hooks to analyze content
• API Integration: Connects to BFAPI for content processing
• UI Components: Integrates BFUI components through libraries
• MCP Plugins: Supports Model Context Protocol for AI model flexibility

Development

Local Development Setup

1. Install dependencies:

   composer require drupal/bluefly_insights
   

2. Configure local settings in settings.local.php:

   $config['bluefly_insights.settings']['bfapi_url'] = 'http://localhost:3000/api';
   

3. Connect to local BFAPI instance:

   cd /path/to/BFAPI
   npm run dev
   

BFCLI Integration

Use BFCLI commands to manage deployment:

bfcli deploy drupal --module=bluefly_insights --env=staging

Troubleshooting

• Check connection to BFAPI services in the status report
• Verify MCP servers are properly configured
• Review Drupal logs for integration errors

Maintainers

• Bluefly Development Team

License

This project is licensed under the GPL-2.0-or-later license, in accordance with Drupal best practices.

Installation on a Fresh Site

1. Ensure composer dependencies are installed:

   composer install
   

2. Enable Insights plus its LLM dependencies and import default config:

   drush en bluefly_llm_admin llm_eca bluefly_insights -y && drush cim -y && drush cr
   

   This imports:

   • bluefly_llm_admin.*.yml defaults (empty registries)
   • llm_eca.workflow_settings.yml (empty workflows)
   • bluefly_insights.* config stubs
3. Visit /admin/config/content/bluefly_insights to connect to BFAPI and select models.

OpenAPI & CI Pipeline

Job	Purpose
openapi:lint	Validates openapi/openapi.yaml via Redocly
phpstan	Static analysis (level 7)
phpunit	Unit, kernel, functional tests
eslint	Lints React/Vue components bundled in module

CI include snippet:

include:
  - project: 'blueflyio/internal-projects/BFCIComponents'
    file: '/ci-templates/drupal-module.yml'

Roadmap / Plan of Attack

1. Replace raw charting JS with BFUI component library tokens.
2. Publish public /api/insights/v1/metrics endpoint + OpenAPI.
3. Add machine learning drift-detection dashboards.
4. Integrate Langfuse trace viewer iframe into admin page.
5. Raise PHPStan level-max and achieve 100 % type coverage.

Installation

1. Install the required dependencies:

   composer require drupal/eca drupal/modeler_api drupal/advanced_queue
   

2. Enable the module:

   drush en bluefly_insights
   

Usage

ECA Actions

The module provides the following ECA actions:

• Evaluate Model: Evaluates a model using the Modeler API
  • Configuration:
    • Model: Select the model to evaluate
    • Test Data: JSON data for model evaluation

ECA Conditions

The module provides the following ECA conditions:

• Model Evaluation Result: Checks if a model evaluation result meets certain criteria
  • Configuration:
    • Metric: Select the metric to check (accuracy, precision, recall, f1_score)
    • Operator: Select the comparison operator
    • Threshold: Enter the threshold value

Events

The module dispatches the following events:

• bluefly_insights.model_evaluated: Fired when a model is evaluated
• bluefly_insights.model_high_accuracy: Fired when a model achieves high accuracy (>= 0.9)
• bluefly_insights.model_low_accuracy: Fired when a model has low accuracy (< 0.7)

Example Workflow

1. Create an ECA model
2. Add a trigger for model evaluation
3. Add the "Evaluate Model" action
4. Add conditions based on evaluation results
5. Add actions to handle different evaluation outcomes

Development

Adding New Metrics

To add new metrics to the evaluation results:

1. Update the ModelEvaluationResult condition plugin
2. Add the new metric to the form options
3. Update the event subscriber to handle the new metric

Custom Events

To add custom events:

1. Create a new event class
2. Register the event in the event subscriber
3. Dispatch the event at appropriate points

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

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_INSIGHTS_API_URL=https://api.example.com/v1
LLM_INSIGHTS_API_TOKEN=your-real-token

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

Security

API Keys and Authentication

• BFAPI Integration: The Bluefly Insights module requires an API key to connect to BFAPI. Store API keys in Drupal's configuration system or environment variables, never in source code.
• Authentication: All requests to BFAPI and other Bluefly services should use secure authentication mechanisms (e.g., OAuth2, JWT, or API keys). Ensure HTTPS is enforced for all external calls.
• Data Flow: Data sent to and from the LLM platform may include sensitive content. Review and restrict what is transmitted, and ensure compliance with your organization's data policies.
• Access Control: Use Drupal's permissions system to restrict access to configuration pages and API endpoints. Only trusted roles should be able to manage API keys and integration settings.

Submodules

• Metrics Submodule: Analytics and metrics collection.
• Recommendations Submodule: Content recommendations.
• Workflow Submodule: AI-driven workflow automation.

Permissions

The Bluefly Insights module defines the following permissions:

• Access Bluefly Insights: View the Bluefly Insights dashboard and reports.
• Administer Bluefly Insights: Configure module settings and manage exports.
• Export Bluefly Insights Data: Trigger manual exports of insights data.
• View Bluefly Insights Dashboard: Access the dashboard and data previews.
• Administer AI Agent: Configure and manage the Claude AI Agent settings.
• Use AI Agent: Use the Claude AI Agent for content analysis.
• Access Bluefly Insights Metrics Endpoint: Access the Prometheus metrics endpoint for Bluefly Insights.
• View LLM API Metrics: View the LLM API metrics dashboard.

Assign these permissions to appropriate roles to control access to insights features, configuration, and sensitive data.

Drush Commands

The Bluefly Insights module provides the following Drush commands:

• bluefly_insights:export [type] [--destination=local|gitlab|both] [--trigger-pipeline] (alias: bfi-export): Export insights data (services, expertise, team, or all) to local or GitLab destinations, with optional pipeline trigger.
• bluefly_insights:trigger-pipeline (alias: bfi-trigger): Trigger the GitLab CI/CD pipeline for model training or export.
• bluefly_insights:stats (alias: bfi-stats): Show statistics about available insights data (nodes, users, taxonomy, etc).
• bluefly_insights:version (alias: bfi-version): Show the current module version and API compatibility level.
• bluefly:bfcli <command> [options] (alias: bfcli): Execute a BFCLI command from within Drupal, passing through any supported options (see BFCLI documentation for details).

Use drush help <command> for detailed usage and available options for each command.

API & OpenAPI Specification

The Bluefly Insights module exposes a REST API documented in llm_insights.openapi.yml. Key endpoints include:

• GET /models: List available LLM models.
• GET /evaluations: List model evaluations.
• POST /evaluations: Create a new model evaluation.
• GET /metrics: Retrieve system-wide metrics and statistics.

See the OpenAPI spec (llm_insights.openapi.yml) for full request/response schemas and authentication details. This spec should be included in BFDOCS for centralized API documentation.

Modeler API Module

The Modeler API module is a key dependency for Bluefly Insights. It provides a standardized interface for managing and evaluating machine learning models within Drupal. This module is developed as part of the Bluefly platform and may be available as a custom or contributed Drupal module. It enables:

• Registration and management of LLM and other AI models
• Integration with ECA workflows for model evaluation
• API endpoints for model metadata and evaluation results

For more information, see the Modeler API documentation (if available).

BFUI Integration

Bluefly Insights leverages BFUI (Bluefly UI) components to provide a modern, consistent user experience in the Drupal admin interface. BFUI components are React-based and can be:

• Compiled and bundled into the module's JavaScript/CSS for direct use in admin pages.
• Loaded dynamically as needed for specific features or dashboards.

Integration with Drupal is achieved by:

• Attaching BFUI component libraries to admin routes via Drupal's asset system.
• Embedding React components within Twig templates using placeholder divs and data attributes.
• Initializing React components on page load via custom JS (see the js/ directory).

This approach allows seamless interaction between Drupal's backend and modern frontend UI elements.

MCP Integration

The Bluefly Insights module integrates with the Model Context Protocol (MCP) ecosystem to enable flexible, pluggable AI model management. The mcp_integration.php file (if present) facilitates this integration by:

• Registering Bluefly Insights as both an MCP client and provider, allowing it to consume and expose AI models and tools.
• Enabling communication with BFMCP and other MCP servers for model discovery, registration, and execution.
• Supporting ECA workflows that trigger model evaluation or content analysis via MCP endpoints.

This dual role ensures Bluefly Insights can both use external models and make its own models available to the broader platform.

Content Synchronization

Bluefly Insights supports content synchronization between Drupal and the Bluefly Platform. This includes:

• What is synchronized: Content entities (e.g., nodes, users, taxonomy terms) relevant to AI analysis, recommendations, and reporting.
• Where it goes: Data can be pushed to or pulled from BFAPI, central Bluefly data stores, or other connected services.
• How it is managed: Synchronization is managed via the Advanced Queue module, allowing for batch processing, retries, and scheduling. Sync jobs can be triggered by admin actions, cron, or ECA workflows.

This ensures data consistency and enables advanced AI-powered features across the platform.

JavaScript Architecture

The Bluefly Insights module uses a modern JavaScript architecture based on React (via BFUI components). Key points:

• Framework: React (via BFUI), with potential for additional vanilla JS utilities.
• Build/Compile: JavaScript is built and bundled using standard Node.js tooling (see package.json and eslint.config.mjs).
• Location: Source scripts are in the js/ directory; configuration is in package.json and related config files.
• Integration: Compiled assets are attached to Drupal admin pages as libraries, and React components are mounted into Twig templates as needed.

This setup enables a seamless, maintainable integration of modern frontend features within Drupal.