# Enhanced CKG/TKG System

## Overview

The Enhanced Component Knowledge Graph (CKG) and Template Knowledge Graph (TKG) system provides intelligent, AI-powered tech stack recommendations based on template features, permutations, and combinations. This robust system leverages Neo4j graph database and Claude AI to deliver comprehensive technology recommendations.

## Key Features

### 🧠 Intelligent Analysis
- **AI-Powered Recommendations**: Uses Claude AI for intelligent tech stack analysis
- **Context-Aware Analysis**: Considers template type, category, and complexity
- **Confidence Scoring**: Provides confidence scores for all recommendations
- **Reasoning**: Explains why specific technologies are recommended

### 🔄 Advanced Permutations & Combinations
- **Feature Permutations**: Ordered sequences of features with performance metrics
- **Feature Combinations**: Unordered sets of features with synergy analysis
- **Compatibility Analysis**: Detects feature dependencies and conflicts
- **Performance Scoring**: Calculates performance and compatibility scores

### 🔗 Rich Relationships
- **Technology Synergies**: Identifies technologies that work well together
- **Technology Conflicts**: Detects incompatible technology combinations
- **Feature Dependencies**: Maps feature dependency relationships
- **Feature Conflicts**: Identifies conflicting feature combinations

### 📊 Comprehensive Analytics
- **Performance Metrics**: Tracks performance scores across permutations
- **Synergy Analysis**: Measures feature and technology synergies
- **Usage Statistics**: Monitors usage patterns and success rates
- **Confidence Tracking**: Tracks recommendation confidence over time

## Architecture

### Enhanced CKG (Component Knowledge Graph)
```
Template → Features → Permutations/Combinations → TechStacks → Technologies
    ↓           ↓              ↓                    ↓           ↓
  Metadata   Dependencies   Performance        AI Analysis  Synergies
    ↓           ↓              ↓                    ↓           ↓
  Conflicts  Relationships  Scoring            Reasoning   Conflicts
```

### Enhanced TKG (Template Knowledge Graph)
```
Template → Features → Technologies → TechStacks
    ↓         ↓           ↓            ↓
  Metadata  Dependencies Synergies  AI Analysis
    ↓         ↓           ↓            ↓
  Success   Conflicts   Conflicts   Reasoning
```

## API Endpoints

### Enhanced CKG APIs

#### Template-Based Recommendations
```bash
GET /api/enhanced-ckg-tech-stack/template/:templateId
```
- **Purpose**: Get intelligent tech stack recommendations based on template
- **Parameters**: 
  - `include_features`: Include feature details (boolean)
  - `limit`: Maximum recommendations (number)
  - `min_confidence`: Minimum confidence threshold (number)

#### Permutation-Based Recommendations
```bash
GET /api/enhanced-ckg-tech-stack/permutations/:templateId
```
- **Purpose**: Get tech stack recommendations based on feature permutations
- **Parameters**:
  - `min_sequence`: Minimum sequence length (number)
  - `max_sequence`: Maximum sequence length (number)
  - `limit`: Maximum recommendations (number)
  - `min_confidence`: Minimum confidence threshold (number)

#### Combination-Based Recommendations
```bash
GET /api/enhanced-ckg-tech-stack/combinations/:templateId
```
- **Purpose**: Get tech stack recommendations based on feature combinations
- **Parameters**:
  - `min_set_size`: Minimum set size (number)
  - `max_set_size`: Maximum set size (number)
  - `limit`: Maximum recommendations (number)
  - `min_confidence`: Minimum confidence threshold (number)

#### Feature Compatibility Analysis
```bash
POST /api/enhanced-ckg-tech-stack/analyze-compatibility
```
- **Purpose**: Analyze feature compatibility and generate recommendations
- **Body**: `{ "featureIds": ["id1", "id2", "id3"] }`

#### Technology Relationships
```bash
GET /api/enhanced-ckg-tech-stack/synergies?technologies=React,Node.js,PostgreSQL
GET /api/enhanced-ckg-tech-stack/conflicts?technologies=Vue.js,Angular
```

#### Comprehensive Recommendations
```bash
GET /api/enhanced-ckg-tech-stack/recommendations/:templateId
```

#### System Statistics
```bash
GET /api/enhanced-ckg-tech-stack/stats
```

#### Health Check
```bash
GET /api/enhanced-ckg-tech-stack/health
```

## Usage Examples

### 1. Get Intelligent Template Recommendations

```javascript
const response = await axios.get('/api/enhanced-ckg-tech-stack/template/123', {
  params: {
    include_features: true,
    limit: 10,
    min_confidence: 0.8
  }
});

console.log('Tech Stack Analysis:', response.data.data.tech_stack_analysis);
console.log('Frontend Technologies:', response.data.data.tech_stack_analysis.frontend_tech);
console.log('Backend Technologies:', response.data.data.tech_stack_analysis.backend_tech);
```

### 2. Analyze Feature Compatibility

```javascript
const response = await axios.post('/api/enhanced-ckg-tech-stack/analyze-compatibility', {
  featureIds: ['auth', 'payment', 'dashboard']
});

console.log('Compatible Features:', response.data.data.compatible_features);
console.log('Dependencies:', response.data.data.dependencies);
console.log('Conflicts:', response.data.data.conflicts);
```

### 3. Get Technology Synergies

```javascript
const response = await axios.get('/api/enhanced-ckg-tech-stack/synergies', {
  params: {
    technologies: 'React,Node.js,PostgreSQL,Docker',
    limit: 20
  }
});

console.log('Synergies:', response.data.data.synergies);
console.log('Conflicts:', response.data.data.conflicts);
```

### 4. Get Comprehensive Recommendations

```javascript
const response = await axios.get('/api/enhanced-ckg-tech-stack/recommendations/123');

console.log('Best Approach:', response.data.data.summary.best_approach);
console.log('Template Confidence:', response.data.data.summary.template_confidence);
console.log('Permutations:', response.data.data.recommendations.permutation_based);
console.log('Combinations:', response.data.data.recommendations.combination_based);
```

## Configuration

### Environment Variables

```bash
# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

# CKG-specific Neo4j (optional, falls back to NEO4J_*)
CKG_NEO4J_URI=bolt://localhost:7687
CKG_NEO4J_USERNAME=neo4j
CKG_NEO4J_PASSWORD=password

# Claude AI Configuration
CLAUDE_API_KEY=your-claude-api-key

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=template_manager
DB_USER=postgres
DB_PASSWORD=password
```

### Neo4j Database Setup

1. **Install Neo4j**: Download and install Neo4j Community Edition
2. **Start Neo4j**: Start the Neo4j service
3. **Create Database**: Create a new database for the CKG/TKG system
4. **Configure Access**: Set up authentication and access controls

## Testing

### Run Test Suite

```bash
# Run comprehensive test suite
node test-enhanced-ckg-tkg.js

# Run demonstration
node -e "require('./test-enhanced-ckg-tkg.js').demonstrateEnhancedSystem()"
```

### Test Coverage

The test suite covers:
- ✅ Health checks for all services
- ✅ Template-based intelligent recommendations
- ✅ Permutation-based recommendations
- ✅ Combination-based recommendations
- ✅ Feature compatibility analysis
- ✅ Technology synergy detection
- ✅ Technology conflict detection
- ✅ Comprehensive recommendation engine
- ✅ System statistics and monitoring

## Performance Optimization

### Caching
- **Analysis Caching**: Intelligent tech stack analysis results are cached
- **Cache Management**: Automatic cache size management and cleanup
- **Cache Statistics**: Monitor cache performance and hit rates

### Database Optimization
- **Indexing**: Proper indexing on frequently queried properties
- **Connection Pooling**: Efficient Neo4j connection management
- **Query Optimization**: Optimized Cypher queries for better performance

### AI Optimization
- **Batch Processing**: Process multiple analyses in batches
- **Timeout Management**: Proper timeout handling for AI requests
- **Fallback Mechanisms**: Graceful fallback when AI services are unavailable

## Monitoring

### Health Monitoring
- **Service Health**: Monitor all service endpoints
- **Database Health**: Monitor Neo4j and PostgreSQL connections
- **AI Service Health**: Monitor Claude AI service availability

### Performance Metrics
- **Response Times**: Track API response times
- **Cache Performance**: Monitor cache hit rates and performance
- **AI Analysis Time**: Track AI analysis processing times
- **Database Performance**: Monitor query performance and optimization

### Statistics Tracking
- **Usage Statistics**: Track template and feature usage
- **Recommendation Success**: Monitor recommendation success rates
- **Confidence Scores**: Track recommendation confidence over time
- **Error Rates**: Monitor and track error rates

## Troubleshooting

### Common Issues

1. **Neo4j Connection Failed**
   - Check Neo4j service status
   - Verify connection credentials
   - Ensure Neo4j is running on correct port

2. **AI Analysis Timeout**
   - Check Claude API key validity
   - Verify network connectivity
   - Review request timeout settings

3. **Low Recommendation Confidence**
   - Check feature data quality
   - Verify template completeness
   - Review AI analysis parameters

4. **Performance Issues**
   - Check database indexing
   - Monitor cache performance
   - Review query optimization

### Debug Commands

```bash
# Check Neo4j status
docker ps | grep neo4j

# View Neo4j logs
docker logs neo4j-container

# Test Neo4j connection
cypher-shell -u neo4j -p password "RETURN 1"

# Check service health
curl http://localhost:8009/api/enhanced-ckg-tech-stack/health

# Get system statistics
curl http://localhost:8009/api/enhanced-ckg-tech-stack/stats
```

## Future Enhancements

### Planned Features
1. **Real-time Learning**: Continuous learning from user feedback
2. **Advanced Analytics**: Deeper insights into technology trends
3. **Visualization**: Graph visualization for relationships
4. **API Versioning**: Support for multiple API versions
5. **Rate Limiting**: Advanced rate limiting and throttling

### Research Areas
1. **Machine Learning**: Integration with ML models for better predictions
2. **Graph Neural Networks**: Advanced graph-based recommendation systems
3. **Federated Learning**: Distributed learning across multiple instances
4. **Quantum Computing**: Exploration of quantum algorithms for optimization

## Support

For issues or questions:
1. Check the logs for error messages
2. Verify Neo4j and PostgreSQL connections
3. Review system statistics and health
4. Test with single template analysis first
5. Check Claude AI service availability

## Contributing

1. Follow the existing code structure and patterns
2. Add comprehensive tests for new features
3. Update documentation for API changes
4. Ensure backward compatibility
5. Follow the established error handling patterns