bluefly/langchain

Core LangChain integration and orchestration framework for Drupal, providing foundational LLM capabilities.

1.0.0 2025-05-22 23:00 UTC

Requires

• drupal/core: >=10.0 <12.0

GPL-2.0-or-later

README

TODO: Drupal.org Compatibility Roadmap
We are working to make this module compatible with drupal.org standards by:

1. Adopting standardized interfaces from the new llm_interfaces module
2. Implementing service discovery for optional integrations
3. Creating a dedicated recipe for easy installation and configuration
   See the /todos directory for detailed implementation plans.

Overview

This module brings LangChain-style agent orchestration and LLM workflow integration to Drupal, enabling advanced AI pipelines and composable agent systems for the Bluefly AI platform.

Quickstart

# Install dependencies
composer install

# Enable the module
drush en langchain

# Run tests
phpunit

Features

• LangChain-style agent orchestration
• LLM workflow and tool integration
• API endpoints for agent and chain operations
• Analytics and monitoring
• Drupal recipe and config support

Architecture

• Services: Agent orchestration, LLM workflow management, analytics
• API: Exposes endpoints for agent and chain operations (see openapi/)
• TDD: Comprehensive test-driven development coverage

Usage Examples

• Use the admin UI to configure agent chains
• Call API endpoints for agent orchestration
• Integrate with other modules for advanced AI workflows

Drupal Recipe Integration

• Install as a recipe using Drupal's config management
• Override default config in config/install/
• See Platform Recipes for advanced integration

Contributing

• Fork the repo and create a feature branch
• Follow Drupal coding standards
• Add tests for new features
• Submit a pull request

Documentation

• API Reference
• Architecture Overview
• Usage Examples
• Changelog
• Roadmap
• Performance Benchmarks
• Testing Documentation

License

GPL-2.0-or-later

See Also

• llm_platform_recipe
• llm
• bfdocs

LangChain Drupal Module

A production-ready, extensible Drupal module for LLM orchestration, agent workflows, and LangChain integration. Built for modern AI/ML, OpenAPI, and workflow automation.

Features

🚀 WORLD'S FIRST: Self-Optimizing AI Orchestration (Revolutionary Innovation!)

• Self-Learning AI Engine: Automatically improves performance with each execution
• Autonomous System Healing: Detects and fixes performance issues without human intervention
• Predictive Optimization: AI-driven recommendations for maximum efficiency
• Adaptive Learning Models: Continuous improvement through machine learning
• Zero-Configuration Intelligence: Automatically discovers optimal execution patterns

Core LangChain Features

• LLM provider plugin system (OpenAI, HuggingFace, etc.)
• Chains and agents as config entities (CRUD via UI/API)
• REST and OpenAPI endpoints for orchestration
• ECA/Workflow integration (no-code automation)
• Langfuse observability hooks
• Admin UI for managing chains, agents, and providers
• YAML-powered configuration for complex workflows
• Example recipes and onboarding docs

Installation

1. Place this module in web/modules/custom/langchain (or use Composer).
2. Enable via drush en langchain (and submodules as needed).
3. Visit /admin/config/services/langchain/chains and /admin/config/services/langchain/agents to manage entities.

Deployment

Multiple deployment options are available to fit your needs:

Automated Deployment Script

Use the provided deployment script to automate installation and configuration:

./deploy-langchain.sh --environment production

Docker Development Environment

Quickly set up a complete development environment with Docker:

docker-compose up -d

Environment-Specific Configurations

Optimized configurations for different environments:

• Development: For local development and testing
• Staging: For pre-production validation
• Production: For secure, reliable production use
• Performance-Optimized: For high-throughput scenarios
• High-Availability: For fault-tolerant, clustered deployments

See Deployment Documentation for detailed instructions.

Configuration

• Set up providers and defaults in /admin/config/services/langchain/settings.
• Add/edit chains and agents via the admin UI.
• Use YAML fields for steps, schemas, and tools.

API Usage

🚀 Revolutionary Self-Optimizing API (World's First!)

# Execute chains with automatic self-optimization and learning
POST /api/langchain/self-optimize/execute
Content-Type: application/json
{
  "chain_id": "content_analysis_chain",
  "input": {"text": "Analyze this content for insights"},
  "context": {"user_id": 123, "priority": "high"}
}

# Get AI-driven optimization recommendations
GET /api/langchain/self-optimize/recommendations/content_analysis_chain

# Trigger autonomous system healing (fixes performance issues automatically)
POST /api/langchain/self-optimize/heal

# Create adaptive learning models for continuous improvement
POST /api/langchain/self-optimize/learn/content_analysis_chain

# Real-time optimization monitoring dashboard
GET /api/langchain/self-optimize/dashboard

Traditional LangChain API

• Orchestrate via /api/langchain/orchestrate (see langchain.openapi.yml).
• All endpoints are permission-guarded and OpenAPI-documented.

Automated Testing and Code Quality

• Kernel/Functional tests recommended for CI/CD.
• Example .gitlab-ci.yml provided for GitLab pipelines.
• Comprehensive code quality checks with PHP_CodeSniffer, PHPStan, and Rector.

Code Quality Tools

# Check code style
composer cs

# Fix code style issues automatically
composer cbf

# Run PHPStan static analysis
composer phpstan

# Run Rector static analysis (dry-run mode)
composer rector-dry-run

# Apply Rector fixes
composer rector

# Run all quality checks
composer quality

# Run all tests and quality checks
composer check

Testing Strategy

100% Code Coverage Requirement

The LangChain module maintains a strict 100% code coverage requirement for all production code. This ensures:

• Complete test coverage of all functionality
• Early detection of regressions and bugs
• Increased code quality and maintainability
• Confidence in module stability

Running Tests

# Run all tests with coverage report
./run-coverage-tests.sh

# Run specific test suites
./run-coverage-tests.sh -t unit
./run-coverage-tests.sh -t kernel
./run-coverage-tests.sh -t functional

# Generate different report formats
./run-coverage-tests.sh -f html   # Default HTML report
./run-coverage-tests.sh -f text   # Text report in terminal
./run-coverage-tests.sh -f clover # Clover XML for CI integration

For detailed information about our testing strategy, visit the testing documentation in the docs folder.

LangChain — Drupal AI Orchestration Recipe

This module is designed as a Drupal recipe and marketplace template for LLM/AI orchestration. It maximizes reuse of contrib modules and core APIs, enabling no-code/low-code extensibility for site builders and developers.

Key Features

• Contrib-First: All features are built using Drupal core APIs and contrib modules (Views, ECA, Search API, VBO, Token, etc.).
• No-Code Admin UI: All admin dashboards and listings are provided as Views, not custom code.
• Composable Workflows: All automations use the ECA module and are exportable as config.
• Search-Ready: Semantic and admin search is provided via Search API.
• Marketplace-Ready: All features are portable, overrideable, and documented for easy adoption.

Dependencies

• drupal:views
• drupal:views_bulk_operations
• drupal:search_api
• drupal:eca
• drupal:token

Extending This Recipe

• Add/modify admin dashboards: Use the Views UI and export config.
• Add/modify automations: Use the ECA UI and export config.
• Add/modify search: Use Search API UI and export config.

See the exported config in config/install/ for examples.

Quickstart for Site Builders

1. Enable the module and all dependencies:
   • drush en langchain views views_bulk_operations search_api eca token
2. Import the provided config:
   • drush cim (or use the Drupal config import UI)
3. Explore and extend:
   • Use the Views UI to customize admin dashboards and listings.
   • Use the ECA UI to add or modify automations.
   • Use Search API UI to adjust search indexes.

No custom code required — everything is configurable via the Drupal admin UI!

Example ECA Rule

• Notify on New Agent: An ECA rule is included that sends a system message whenever a new LangChain Agent is created. You can extend or modify this and other automations via the ECA UI—no custom code required.

Example Role: LangChain Admin

• The recipe includes a LangChain Admin role with all necessary permissions for AI/LLM/agent management, workflows, and logs.
• Assign this role to trusted users via the Drupal People > Roles UI for full access to LangChain features.

Example Role: LangChain Operator

• The recipe includes a LangChain Operator role with limited permissions for running chains/agents and viewing logs, but not full admin rights.
• Assign this role to operational users who need to execute AI workflows but should not have configuration or admin access.

Example Role: LangChain Workflow Editor

• The recipe includes a LangChain Workflow Editor role with permissions to manage ECA rules and view logs, but not run or administer chains/agents.
• Assign this role to users responsible for workflow automation and rule management, without granting operational or admin access.

Drupal 11: The Center of AI Management

This recipe positions Drupal 11 as the orchestration control plane for all AI/LLM/agent management, workflow automation, and observability. All features are event-driven, extensible, and managed via no-code config and open source modules—making Drupal the foundation of your AI ecosystem.

Permissions and Roles

• Granular permissions are provided for Chains, Agents, logs, and workflow administration. Assign these via the Drupal UI for secure, best-practice access control.
• All admin, CRUD, and workflow actions are permissioned and can be managed with roles—no code changes required.

Enhanced Bulk Operations

• Admin Views for Chains and Agents now include bulk enable, disable, delete, and export actions via Views Bulk Operations (VBO).

How to Extend (No Code Required)

• Add fields to Chains or Agents: Use the Drupal 'Manage fields' UI for each entity type.
• Create new admin dashboards: Use the Views UI to create new listings or reports for any entity.
• Add or modify automations: Use the ECA UI to create or update workflow rules for any event.
• Add new roles or permissions: Use the People > Roles UI to create new roles and assign granular permissions.

All extensibility is UI-driven—no custom code needed!