# AI Architecture Issue - CRITICAL FIX NEEDED

**Date**: 2026-02-04
**Priority**: HIGH
**Issue**: Modules have hardcoded AI providers instead of using drupal/ai module

---

## Problem Statement

**User Requirement**: "ALL MY MODULES should work without AI"

**Current Issues**:
1. Modules hardcode AI providers (OpenAI, Anthropic, Ollama)
2. AI functionality is not optional
3. Not using Drupal's ai module (48+ providers)
4. Tight coupling between core functionality and AI features

---

## Correct Architecture

### Principle: AI is OPTIONAL

```
Core Module (api_normalization)
  ↓
  ├─ Core functionality (NO AI dependencies)
  │  - API normalization
  │  - Schema generation
  │  - Type conversion
  │  - Validation
  │
  └─ Optional AI Submodule (api_normalization_ai)
     - Uses drupal/ai module
     - Provides AI enhancements
     - Can be disabled
     - 48+ provider support
```

### Module Structure

```
api_normalization/
├── api_normalization.module       (NO AI code)
├── src/                           (NO AI dependencies)
│   ├── Service/
│   │   ├── ApiNormalizer.php      (pure normalization logic)
│   │   └── SchemaGenerator.php    (OpenAPI generation)
│   └── Controller/
│       └── ApiController.php      (API endpoints)
└── modules/
    ├── api_normalizer_canvas/     (Canvas visualization - NO AI required)
    │   └── canvas/
    │       └── components/
    └── api_normalizer_ai/         (AI features - OPTIONAL)
        ├── api_normalizer_ai.info.yml
        │   dependencies:
        │     - drupal:ai              ← Uses Drupal AI module
        ├── src/
        │   ├── Service/
        │   │   ├── AiSchemaAnalyzer.php
        │   │   ├── AiComponentGenerator.php
        │   │   └── AiNormalizationSuggestions.php
        │   └── Plugin/
        │       └── AiProvider/        (If custom providers needed)
        └── composer.json
            "require": {
              "drupal/ai": "^1.0"  ← Depend on Drupal AI module
            }
```

---

## drupal/ai Module Integration

### What is drupal/ai?

**Package**: https://www.drupal.org/project/ai
**Providers**: 48+ AI providers supported
**Architecture**: Plugin-based provider system

**Supported Providers**:
- OpenAI (GPT-4, GPT-3.5)
- Anthropic (Claude)
- Google (Gemini, PaLM)
- Microsoft Azure OpenAI
- Cohere
- Hugging Face
- Ollama (local)
- LM Studio (local)
- ...and 40+ more

### Plugin System

```php
// Use any provider via drupal/ai
$ai_provider = \Drupal::service('ai.provider');

// Get provider instance
$provider = $ai_provider->createInstance('openai'); // or 'anthropic', 'ollama', etc.

// Make AI request
$response = $provider->chat([
  'messages' => [
    ['role' => 'user', 'content' => 'Analyze this API schema...']
  ]
]);
```

---

## Migration Plan

### Phase 1: Extract AI Code (Week 1)

**Goal**: Remove all AI dependencies from core modules

**Tasks**:
1. **Audit all modules for AI usage**:
   ```bash
   grep -r "OpenAI\|Anthropic\|Ollama" src/
   grep -r "gpt-\|claude-" src/
   ```

2. **Identify AI features**:
   - Schema analysis
   - Component generation
   - Normalization suggestions
   - Auto-documentation

3. **Move to api_normalizer_ai submodule**:
   ```bash
   mkdir modules/api_normalizer_ai
   # Move AI-related services
   mv src/Service/*Ai* modules/api_normalizer_ai/src/Service/
   ```

4. **Update dependencies**:
   ```yaml
   # api_normalizer_ai.info.yml
   dependencies:
     - drupal:ai
     - api_normalization:api_normalization
   ```

### Phase 2: Implement drupal/ai Integration (Week 2)

**Goal**: Use drupal/ai module instead of hardcoded providers

**Before** (hardcoded):
```php
// BAD: Hardcoded OpenAI
class SchemaAnalyzer {
  public function analyze($schema) {
    $openai = new OpenAI($api_key);
    return $openai->chat(...);
  }
}
```

**After** (drupal/ai):
```php
// GOOD: Uses drupal/ai plugin system
class AiSchemaAnalyzer {
  protected $aiProvider;

  public function __construct(AiProviderInterface $ai_provider) {
    $this->aiProvider = $ai_provider;
  }

  public function analyze($schema) {
    // Works with ANY of the 48+ providers
    $provider = $this->aiProvider->createInstance(
      $this->config->get('ai_provider') // User-configurable
    );
    return $provider->chat([...]);
  }
}
```

**Benefits**:
- ✅ User chooses provider (OpenAI, Claude, Ollama, etc.)
- ✅ 48+ providers supported
- ✅ Local providers (Ollama, LM Studio) for privacy
- ✅ Provider switching without code changes
- ✅ Drupal's provider management UI

### Phase 3: Make AI Optional (Week 3)

**Goal**: Core modules work perfectly without AI

**Implementation**:

1. **Hook system for AI features**:
   ```php
   // api_normalization.module
   function api_normalization_schema_analyze($schema) {
     // Allow other modules to provide analysis
     $results = \Drupal::moduleHandler()->invokeAll('api_schema_analyze', [$schema]);

     // Core analysis (no AI)
     $core_analysis = _api_normalization_core_analyze($schema);

     return array_merge($core_analysis, $results);
   }

   // api_normalizer_ai.module (OPTIONAL)
   function api_normalizer_ai_api_schema_analyze($schema) {
     // AI-powered analysis (only if module enabled)
     $analyzer = \Drupal::service('api_normalizer_ai.analyzer');
     return $analyzer->analyze($schema);
   }
   ```

2. **Configuration UI**:
   ```yaml
   # Core module config (NO AI settings)
   api_normalization.settings:
     enable_validation: true
     enable_caching: true
     # No AI settings here!

   # AI submodule config (ONLY if enabled)
   api_normalizer_ai.settings:
     ai_provider: 'anthropic'  # or openai, ollama, etc.
     model: 'claude-3-opus'
     enable_auto_generation: true
   ```

3. **Feature detection**:
   ```php
   if (\Drupal::moduleHandler()->moduleExists('api_normalizer_ai')) {
     // Show AI-powered features
     $form['ai_analysis'] = [...];
   } else {
     // Show basic features only
     $form['basic_analysis'] = [...];
   }
   ```

---

## Canvas Module - NO AI Required

**api_normalizer_canvas** should work WITHOUT AI:

```yaml
# api_normalizer_canvas.info.yml
dependencies:
  - api_normalization:api_normalization
  # NO AI dependency!
```

**Features that work without AI**:
- ✅ Display JSON:API responses as Canvas components
- ✅ Entity visualization
- ✅ Relationship browser
- ✅ API explorer
- ✅ Schema viewer

**AI features (OPTIONAL, via api_normalizer_ai)**:
- 🤖 Auto-generate Canvas components from schemas
- 🤖 AI-suggested layouts
- 🤖 Smart field grouping

---

## Implementation Checklist

### Immediate Actions

- [ ] Audit api_normalization for AI code
- [ ] Create api_normalizer_ai submodule
- [ ] Move AI services to submodule
- [ ] Add drupal/ai dependency to submodule only
- [ ] Update api_normalizer_canvas to work without AI
- [ ] Test all modules with AI disabled
- [ ] Document AI vs non-AI features

### Configuration

- [ ] Remove AI settings from core module config
- [ ] Create AI submodule config form
- [ ] Add provider selection UI (uses drupal/ai providers)
- [ ] Add enable/disable toggles for AI features

### Testing

- [ ] Test core module without AI submodule
- [ ] Test with AI submodule enabled
- [ ] Test provider switching (OpenAI → Claude → Ollama)
- [ ] Test Canvas without AI features
- [ ] Verify 95%+ test coverage

---

## Benefits of Correct Architecture

### For Users
- ✅ Choose to enable AI or not
- ✅ Choose any of 48+ AI providers
- ✅ Use local models (Ollama) for privacy
- ✅ Core features work without AI
- ✅ No vendor lock-in

### For Developers
- ✅ Clean separation of concerns
- ✅ Core module has no AI dependencies
- ✅ Easy to test without AI
- ✅ Flexible provider system
- ✅ Follow Drupal best practices

### For the Platform
- ✅ Modular architecture
- ✅ Optional enhancements
- ✅ Provider-agnostic
- ✅ Privacy-friendly (local models)
- ✅ Cost-effective (choose cheap providers)

---

## Example: Schema Analysis Feature

### Without AI (Core Module)
```php
// Always available
function api_normalization_analyze_schema($schema) {
  return [
    'field_count' => count($schema['properties']),
    'required_fields' => $schema['required'] ?? [],
    'relationships' => _extract_relationships($schema),
    'validation_rules' => _extract_validation($schema),
  ];
}
```

### With AI (Optional Submodule)
```php
// Only if api_normalizer_ai enabled
function api_normalizer_ai_enhance_analysis($schema) {
  $provider = \Drupal::service('ai.provider')
    ->createInstance('anthropic'); // or any provider

  return $provider->chat([
    'messages' => [
      ['role' => 'user', 'content' => 'Analyze schema: ' . json_encode($schema)]
    ]
  ]);
}
```

### User Experience
```
Without AI module:
  [Schema Analysis]
  - 15 fields
  - 5 required
  - 3 relationships

With AI module enabled:
  [Schema Analysis]
  - 15 fields
  - 5 required
  - 3 relationships

  [AI Insights] 🤖
  - Suggests grouping fields by category
  - Recommends validation improvements
  - Auto-generates documentation
  - Suggests optimal Canvas layout
```

---

## Migration Commands

```bash
# 1. Create AI submodule
mkdir -p modules/api_normalizer_ai/src/Service

# 2. Move AI code
git mv src/Service/*Ai* modules/api_normalizer_ai/src/Service/

# 3. Add drupal/ai dependency
cd modules/api_normalizer_ai
composer require drupal/ai:^1.0

# 4. Test without AI
drush pm:uninstall api_normalizer_ai
# All core features should still work!

# 5. Test with AI
drush pm:enable api_normalizer_ai
# AI features now available
```

---

## Success Criteria

1. ✅ Core module works without any AI dependencies
2. ✅ AI features are in optional submodule
3. ✅ Uses drupal/ai module (48+ providers)
4. ✅ User can enable/disable AI
5. ✅ User can switch providers
6. ✅ Canvas works without AI
7. ✅ All tests pass with AI disabled
8. ✅ All tests pass with AI enabled

---

**Status**: Issue identified, migration plan ready
**Priority**: HIGH - Fix before production
**Estimated Time**: 3 weeks
**Impact**: Proper architecture, user choice, provider flexibility

---

**Next Steps**:
1. Audit current AI usage in all modules
2. Create api_normalizer_ai submodule structure
3. Begin migration of AI code
4. Install and integrate drupal/ai module
5. Test thoroughly with and without AI
