DDEV Drupal AI Add-on

⚠️ Important — Proof of Concept (PoC)

This repository is an early Proof of Concept and not yet feature-complete. Expect bugs and incomplete functionality. The interactive setup wizard (ddev drupal-ai setup) currently creates a configuration file at ${DDEV_APPROOT}/.ddev/drupal-ai.setup.yaml containing your AI provider settings.

# Example .ddev/drupal-ai.setup.yaml
openai_api_key: "sk-..."
openai_model: "gpt-4"
openai_base_url: "https://api.openai.com/v1"
drupal_ai_provider: "openai"
drupal_ai_functionalities: "vector-search"

The next step in development is to automatically spin up a local Drupal environment with AI modules configured based on your wizard selections.

🔒 Security Note: The current setup stores API keys in a YAML file that should never be committed to version control. Future development will include secure secret management options like DDEV environment variables, external secret stores, or encrypted configuration.

We're actively seeking reviewers and contributors to help complete this project. Please open issues or pull requests on GitHub if you'd like to help.

Overview

This add-on provides an interactive CLI orchestration tool for Drupal AI workflows within your DDEV project. It acts as a meta-tool that streamlines the setup and orchestration of AI capabilities in Drupal development environments.

With this add-on, you can:

• Interactive Setup Wizard: Choose AI provider → select functionality → automatic dependency resolution and installation
• Multiple AI Providers: Support for OpenAI, Anthropic, Ollama, and Google Gemini
• Automated Add-on Management: Automatically install required add-ons (pgvector, unstructured, etc.)
• YAML-driven Configuration: Extensible configuration system for providers and functionalities
• Comprehensive Error Handling: User-friendly error messages and rollback capabilities

Architecture

• Glue Add-on Pattern: Meta-tool that orchestrates other DDEV add-ons
• Interactive CLI: Guided user experience with provider → functionality → setup flow
• YAML-driven Configuration: Steps and configurations defined in YAML, not hardcoded in Bash
• Dependency Management: Automatically install required add-ons based on selected features

Installation

ddev add-on get Drupal-AI/ddev-drupal-ai
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Quick Start

Complete AI Stack Setup

Run the interactive setup wizard to configure your complete AI stack:

ddev drupal-ai setup

This will guide you through:

1. AI Provider Selection (OpenAI, Anthropic, Ollama, etc.)
2. Functionality Selection (Vector Search, Content Generation, Q&A, etc.)
3. Dependency Analysis (Required add-ons will be identified)
4. Automated Installation (Add-ons installed automatically)
5. Provider Configuration (API keys, models, endpoints)

Example Workflow

$ ddev drupal-ai setup

🤖 Drupal AI Setup Wizard
========================

Step 1: Select AI Provider
? Choose your AI provider:
  ❯ OpenAI (GPT-4, GPT-3.5, Embeddings)
    Anthropic (Claude 3.5, Claude 3)
    Ollama (Local LLM - llama3, mistral, etc.)
    Google Gemini (gemini-pro, gemini-vision)

Step 2: Select Functionality
? What AI features do you need: (multiple selection)
  ❯ ✓ Vector Search & Embeddings
    ✓ Content Generation
    ○ Image Analysis
    ○ Q&A System

Step 3: Dependencies Analysis
📦 Required add-ons for your selection:
  - pgvector (for vector search) → Will install

? Proceed with installation? (Y/n)

Step 4: Installation
✅ Installing pgvector add-on...
✅ Configuring OpenAI services...

Step 5: Configuration
? OpenAI API Key: [secure input]
? Default model (gpt-4):
? Enable vector search (Y/n): Y

🎉 Setup Complete!

Next steps:
- Run `ddev restart` to apply changes
- Install Drupal AI modules: `ddev composer require drupal/ai`
- Configure at /admin/config/ai

CLI Commands

Primary Commands

Command	Description
ddev drupal-ai setup	Interactive wizard for complete AI stack setup
ddev drupal-ai list	Display available providers and installed add-ons
ddev drupal-ai help	Show help information

Supported Add-ons

Add-on	Description	Source
pgvector	PostgreSQL with pgvector extension for vector storage	robertoperuzzo/ddev-pgvector
unstructured	Document processing and parsing service	drud/ddev-unstructured
ollama-service	Local LLM server for running models like Llama, Mistral	stinis87/ddev-ollama
redis	Redis cache for improved AI performance	drud/ddev-redis

Supported Providers

Provider	Models	Capabilities
OpenAI	GPT-4, GPT-3.5, DALL-E	Text generation, embeddings, image generation
Anthropic	Claude 3.5, Claude 3	Text generation
Ollama	Llama3, Mistral, etc.	Local text generation, embeddings
Google Gemini	Gemini Pro, Vision	Text generation, image analysis

Available Functionalities

Functionality	Description	Requirements
Vector Search & Embeddings	Semantic search using vector databases	pgvector, embeddings capability
Content Generation	AI-powered content creation	Text generation capability
Image Analysis	AI-powered image recognition	Image analysis capability
Q&A System	Intelligent question answering	pgvector, text generation, embeddings
Code Assistant	AI-powered code generation	Text generation capability
Document Processing	Extract and process various document formats	unstructured add-on

Configuration

Environment Variables

Configuration is stored in .ddev/drupal-ai.setup.yaml. Key variables include:

# Provider Configuration
drupal_ai_provider: "openai"
drupal_ai_functionalities: "vector-search,content-generation"

# OpenAI Configuration
openai_api_key: "sk-..."
openai_model: "gpt-4"
openai_base_url: "https://api.openai.com/v1"

# Database Configuration
postgres_db: "drupal_ai"
postgres_user: "drupal_ai"
postgres_password: "drupal_ai"

Manual Configuration

All configuration is now handled through the main command interface:

# Configure providers and functionalities
ddev drupal-ai setup

# List available providers and installed components
ddev drupal-ai list

# Get help
ddev drupal-ai help

Advanced Usage

Validation and Health Checks

The main drupal-ai command includes built-in validation and health checks that run during setup.

Service Management

After setup, you can manage services:

# View all services
ddev describe

# Check PostgreSQL status
ddev exec -s postgres pg_isready

# Check Ollama models (if installed)
ddev exec -s ollama curl http://localhost:11434/api/tags

# View logs
ddev logs -s postgres
ddev logs -s ollama

Drupal Integration

Installing Drupal AI Modules

After setting up the infrastructure:

# Install core AI module
ddev composer require drupal/ai

# Install additional AI modules based on your setup
ddev composer require drupal/ai_search    # For vector search
ddev composer require drupal/ai_content   # For content generation
ddev composer require drupal/ai_qa        # For Q&A systems

Configuration

1. Navigate to /admin/config/ai in your Drupal site
2. Configure your AI provider with the same settings used in the setup
3. Test the connection
4. Configure specific AI functionalities as needed

Troubleshooting

Common Issues

Command not found

# Ensure the add-on is properly installed
ddev add-on get Drupal-AI/ddev-drupal-ai
ddev restart

YAML parsing errors

# Install yq if not available
brew install yq  # macOS
# or follow instructions at https://github.com/mikefarah/yq#install

Service connection failures

# Check service status
ddev describe

# Restart services
ddev restart

# Check logs
ddev logs -s <service-name>

API connection issues

# Use the interactive setup to reconfigure
ddev drupal-ai setup

Reset Configuration

To reset all AI configuration, simply delete the configuration file and run setup again:

rm .ddev/drupal-ai.setup.yaml
ddev drupal-ai setup

Development

Custom Configurations

You can extend the add-on by creating custom configurations in .ddev/drupal-ai/configs/. See the existing YAML files for examples.

Contributing

1. Fork the repository
2. Create your feature branch
3. Add tests for your changes
4. Ensure all tests pass: bats tests/test.bats
5. Submit a pull request

Testing

Run the test suite:

# Install bats if needed
brew install bats-core bats-assert bats-file bats-support

# Run tests
bats tests/test.bats

# Run with debugging
bats tests/test.bats --show-output-of-passing-tests --verbose-run

Credits

Contributed and maintained by @Drupal-AI