README

A comprehensive Drupal AI provider module for Apple Intelligence and Foundation Models, featuring privacy-first on-device processing and seamless integration with Apple's ecosystem.

Features

Core AI Capabilities

Chat Operations: Complete chat interface with Apple Foundation Models
Embeddings: High-quality embeddings with on-device processing
Text-to-Image: Image generation via Apple's Private Cloud Compute
Model Management: Dynamic model discovery and configuration

Apple-Specific Features

On-Device Processing: Leverage Apple's Neural Engine for privacy-first AI
Private Cloud Compute: Secure cloud processing for complex tasks
Device Detection: Automatic Apple Silicon and Neural Engine detection
Privacy Management: Comprehensive privacy controls and audit logging

Integration Features

@bluefly/apple-fm NPM Package: Seamless integration with Apple Foundation Models SDK
JavaScript Bridge: TypeScript bridge for browser-based AI operations
Key Module Support: Secure credential management
Drupal AI Standards: Full compliance with Drupal AI module patterns

Installation

Prerequisites

Drupal 10.3+ or Drupal 11+
PHP 8.1+
Node.js 18+ (for NPM package integration)
Apple Developer account (for production use)

Via Composer

# Install the module
composer require drupal/ai_provider_apple

# Enable the module
drush en ai_provider_apple

Via Git (Development)

# Clone to modules/custom
git clone https://github.com/your-org/ai_provider_apple.git web/modules/custom/ai_provider_apple

# Install NPM dependencies
cd web/modules/custom/ai_provider_apple
npm install

# Build JavaScript bridge
npm run build

# Enable the module
drush en ai_provider_apple

Configuration

Basic Setup

Navigate to Administration > Configuration > AI > Providers
Configure the Apple Intelligence provider:
- Apple App ID: Your Apple application identifier
- Apple Developer Team ID: Your Apple Developer team ID
- API Key: Store securely using the Key module
- Processing Mode: Choose between on-device, cloud, or adaptive

Privacy Settings

Local Processing Preferred: Always attempt on-device processing first
User Consent Required: Require explicit user consent for AI operations
Data Retention: Configure data retention policies (0 = no retention)
Differential Privacy: Enable Apple's differential privacy features
Audit Logging: Log all privacy-related events

Performance Settings

Neural Engine: Enable Apple Neural Engine optimization
Apple Silicon: Optimize for Apple Silicon processors
Caching: Configure response caching and TTL
Rate Limiting: Set API rate limits and concurrent request limits

Usage

Basic Chat Example

use Drupal\ai\OperationType\Chat\ChatInput;

// Get the AI provider
$provider = \Drupal::service('ai.provider')->createInstance('apple');

// Create chat input
$messages = [
  ['role' => 'user', 'content' => 'Hello, can you help me?']
];
$input = new ChatInput($messages);

// Execute chat operation
$response = $provider->chat($input, 'apple-foundation-model-1');
$content = $response->getNormalized();

Embeddings Example

use Drupal\ai\OperationType\Embeddings\EmbeddingsInput;

// Create embeddings input
$input = new EmbeddingsInput(['Text to embed']);

// Execute embeddings operation
$response = $provider->embeddings($input, 'apple-embeddings');
$embeddings = $response->getEmbeddings();

Text-to-Image Example

use Drupal\ai\OperationType\TextToImage\TextToImageInput;

// Create text-to-image input
$input = new TextToImageInput('A beautiful sunset over mountains');

// Execute image generation
$response = $provider->textToImage($input, 'apple-image-playground');
$images = $response->getImages();

Architecture

JavaScript Bridge

The module includes a TypeScript bridge (apple-fm-bridge.ts) that:

Integrates with @bluefly/apple-fm NPM package
Provides device capability detection
Handles privacy-first processing decisions
Manages Apple-specific authentication

Privacy-First Design

All operations follow Apple's privacy principles:

On-device first: Prefer local processing when possible
Minimal data: Only process necessary data
User control: Transparent privacy controls
Audit trail: Complete logging of privacy events

Service Architecture

AppleFmBridge: Core integration with Apple Foundation Models
ApplePrivacyManager: Privacy compliance and consent management
AppleDeviceDetector: Hardware capability detection
Configuration: Comprehensive settings management

Development

Build System

# Install dependencies
npm install

# Build JavaScript bridge
npm run build

# Development mode with watching
npm run watch

# Run tests
npm test

# Run Drupal tests
vendor/bin/phpunit --group ai_provider_apple

Testing

The module includes comprehensive tests:

Unit Tests: Service and component testing
Kernel Tests: Integration testing with Drupal
JavaScript Tests: Bridge functionality testing

Contributing

Follow Drupal coding standards
Include tests for all new functionality
Update documentation
Test with multiple Apple devices when possible

Security

Privacy Compliance

GDPR compliant by design
Apple privacy guidelines adherence
Configurable data retention policies
Comprehensive audit logging

Secure Credentials

Integration with Drupal Key module
No credentials stored in configuration
Secure API key management
Apple Developer authentication

Troubleshooting

Common Issues

Module not loading:

# Clear cache
drush cr

# Check module status
drush pm:list | grep ai_provider_apple

JavaScript bridge not working:

# Rebuild JavaScript
npm run build

# Check for errors in browser console
# Verify @bluefly/apple-fm package installation

No models available:

Verify Apple Developer credentials
Check API key configuration
Ensure device supports Apple Intelligence
Review privacy settings

Debug Mode

Enable debug logging in settings.php:

$config['ai_provider_apple.settings']['debug'] = TRUE;

API Reference

Plugin Definition

#[AiProvider(
  id: 'apple',
  label: new TranslatableMarkup('Apple Intelligence'),
)]

Supported Operations

chat: Conversational AI with Apple Foundation Models
embeddings: Text embeddings for semantic search
text_to_image: Image generation via Private Cloud Compute

Model IDs

apple-foundation-model-1: General purpose on-device model
apple-foundation-model-2: Advanced cloud-based model
apple-writing-tools: Specialized writing assistance
apple-embeddings: On-device embeddings
apple-embeddings-multilingual: Multilingual embeddings
apple-image-playground: Image generation model

Roadmap

Version 1.1 (Planned)

[ ] Real-time streaming responses
[ ] Advanced model fine-tuning
[ ] Multi-modal input support
[ ] Enhanced device optimization

Version 1.2 (Future)

[ ] Federated learning integration
[ ] Advanced privacy analytics
[ ] Custom model deployment
[ ] Enhanced developer tools

MACH Alliance Compliance

This Apple Intelligence provider module exemplifies MACH (Microservices, API-first, Cloud-native, Headless) architecture principles with privacy-first AI integration:

Microservices Architecture

Independent Deployment: Apple provider operates as a standalone microservice
Service Isolation: On-device processing ensures complete service independence
Failover Support: Graceful degradation when Apple services are unavailable
Horizontal Scaling: Distribute load across multiple Apple device endpoints

API-First Design

Standard AI Interfaces: Implements Drupal AI provider API patterns
RESTful Integration: Native REST API support for external applications
JSON:API Compliance: Full JSON:API support for headless implementations
OpenAPI Documentation: Complete API specification for developer integration

Cloud-Native Readiness

Hybrid Cloud Support: Seamless integration between on-device and Private Cloud Compute
Environment Flexibility: Configurable deployment across development, staging, and production
Health Monitoring: Built-in health checks and status reporting
Containerization Ready: Docker support for consistent deployment environments

Headless CMS Capabilities

Privacy-First Headless: On-device processing enables truly private headless architectures
Multi-Platform Delivery: Native iOS/macOS integration with web and mobile frontends
Real-Time Streaming: Support for real-time AI responses in headless applications
Cross-Platform SDKs: JavaScript bridge enables integration with any frontend framework

Apple-Specific MACH Benefits

Edge Computing: On-device processing reduces cloud dependencies
Privacy Compliance: GDPR/CCPA compliant by design with no data leaving the device
Performance: Neural Engine optimization for high-performance AI operations
Security: End-to-end encryption and cryptographic verification

This provider demonstrates how MACH principles can be applied to privacy-first AI architectures, enabling organizations to build modern, scalable AI systems while maintaining the highest privacy and security standards.

For more information about MACH principles and implementation strategies, see the main MACH Alliance strategy document in the project documentation.

License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

Support

Issue Tracker: GitHub Issues
Documentation: docs/
Community: Drupal.org Project Page

Credits

Developed by the LLM Platform Team
Powered by Apple Intelligence and Foundation Models
Integrates with @bluefly/apple-fm NPM package
Built for the Drupal AI ecosystem

Ready for drupal.org contribution - This module follows all Drupal coding standards and AI provider patterns, making it suitable for contribution to the Drupal.org ecosystem as the first Apple Intelligence provider.

bluefly / ai_provider_apple

Maintainers

Details