ALwrity/backend/services/calendar_generation_datasource_framework/README.md

Calendar Generation Data Source Framework

A scalable, modular framework for managing evolving data sources in AI-powered content calendar generation. This framework provides a robust foundation for handling multiple data sources, quality gates, and AI prompt enhancement without requiring architectural changes as the system evolves.

🎯 Overview

The Calendar Generation Data Source Framework is designed to support the 12-step prompt chaining architecture for content calendar generation. It provides a scalable, maintainable approach to managing data sources that can evolve over time without breaking existing functionality.

Key Features

• Modular Architecture: Individual modules for each data source and quality gate
• Scalable Design: Add new data sources without architectural changes
• Quality Assurance: Comprehensive quality gates with validation
• AI Integration: Strategy-aware prompt building with context
• Evolution Management: Version control and enhancement planning
• Separation of Concerns: Clean, maintainable code structure

🏗️ Architecture

Directory Structure

calendar_generation_datasource_framework/
├── __init__.py                 # Package initialization and exports
├── interfaces.py               # Abstract base classes and interfaces
├── registry.py                 # Central data source registry
├── prompt_builder.py           # Strategy-aware prompt builder
├── evolution_manager.py        # Data source evolution management
├── data_sources/              # Individual data source modules
│   ├── __init__.py
│   ├── content_strategy_source.py
│   ├── gap_analysis_source.py
│   ├── keywords_source.py
│   ├── content_pillars_source.py
│   ├── performance_source.py
│   └── ai_analysis_source.py
└── quality_gates/             # Individual quality gate modules
    ├── __init__.py
    ├── quality_gate_manager.py
    ├── content_uniqueness_gate.py
    ├── content_mix_gate.py
    ├── chain_context_gate.py
    ├── calendar_structure_gate.py
    ├── enterprise_standards_gate.py
    └── kpi_integration_gate.py

Core Components

1. Data Source Interface (interfaces.py)

Defines the contract for all data sources:

• DataSourceInterface: Abstract base class for data sources
• DataSourceType: Enumeration of data source types
• DataSourcePriority: Priority levels for processing
• DataSourceValidationResult: Standardized validation results

2. Data Source Registry (registry.py)

Central management system for data sources:

• Registration and unregistration of data sources
• Dependency management between sources
• Data retrieval with dependency resolution
• Source validation and status tracking

3. Strategy-Aware Prompt Builder (prompt_builder.py)

Builds AI prompts with full strategy context:

• Step-specific prompt generation
• Dependency-aware data integration
• Strategy context enhancement
• Quality gate integration

4. Quality Gate Manager (quality_gates/quality_gate_manager.py)

Comprehensive quality validation system:

• 6 quality gate categories
• Real-time validation during generation
• Quality scoring and threshold management
• Enterprise-level quality standards

5. Evolution Manager (evolution_manager.py)

Manages data source evolution:

• Version control and tracking
• Enhancement planning
• Evolution readiness assessment
• Backward compatibility management

📊 Data Sources

Current Data Sources

1. Content Strategy Source

• Type: Strategy
• Priority: Critical
• Purpose: Provides comprehensive content strategy data
• Fields: 30+ strategic inputs including business objectives, target audience, content pillars, brand voice, editorial guidelines
• Quality Indicators: Data completeness, strategic alignment, content coherence

2. Gap Analysis Source

• Type: Analysis
• Priority: High
• Purpose: Identifies content gaps and opportunities
• Fields: Content gaps, keyword opportunities, competitor insights, recommendations
• Quality Indicators: Gap identification accuracy, opportunity relevance

3. Keywords Source

• Type: Research
• Priority: High
• Purpose: Provides keyword research and optimization data
• Fields: Primary keywords, long-tail keywords, search volume, competition level
• Quality Indicators: Keyword relevance, search volume accuracy

4. Content Pillars Source

• Type: Strategy
• Priority: Medium
• Purpose: Defines content pillar structure and distribution
• Fields: Pillar definitions, content mix ratios, theme distribution
• Quality Indicators: Pillar balance, content variety

5. Performance Source

• Type: Performance
• Priority: High
• Purpose: Provides historical performance data and metrics
• Fields: Content performance, audience metrics, conversion metrics
• Quality Indicators: Data accuracy, metric completeness

6. AI Analysis Source

• Type: AI
• Priority: High
• Purpose: Provides AI-generated strategic insights
• Fields: Strategic insights, content intelligence, audience intelligence, predictive analytics
• Quality Indicators: Intelligence accuracy, predictive reliability

🔍 Quality Gates

Quality Gate Categories

1. Content Uniqueness Gate

• Purpose: Prevents duplicate content and keyword cannibalization
• Validation: Topic uniqueness, title diversity, keyword distribution
• Threshold: 0.9 (90% uniqueness required)

2. Content Mix Gate

• Purpose: Ensures balanced content distribution
• Validation: Content type balance, theme distribution, variety
• Threshold: 0.8 (80% balance required)

3. Chain Context Gate

• Purpose: Validates prompt chaining context preservation
• Validation: Step context continuity, data flow integrity
• Threshold: 0.85 (85% context preservation required)

4. Calendar Structure Gate

• Purpose: Ensures proper calendar structure and duration
• Validation: Structure completeness, duration appropriateness
• Threshold: 0.8 (80% structure compliance required)

5. Enterprise Standards Gate

• Purpose: Validates enterprise-level content standards
• Validation: Professional quality, brand compliance, industry standards
• Threshold: 0.9 (90% enterprise standards required)

6. KPI Integration Gate

• Purpose: Ensures KPI alignment and measurement framework
• Validation: KPI alignment, measurement framework, goal tracking
• Threshold: 0.85 (85% KPI integration required)

🚀 Usage

Basic Setup

from services.calendar_generation_datasource_framework import (
    DataSourceRegistry,
    StrategyAwarePromptBuilder,
    QualityGateManager,
    DataSourceEvolutionManager
)

# Initialize framework components
registry = DataSourceRegistry()
prompt_builder = StrategyAwarePromptBuilder(registry)
quality_manager = QualityGateManager()
evolution_manager = DataSourceEvolutionManager(registry)

Registering Data Sources

from services.calendar_generation_datasource_framework import ContentStrategyDataSource

# Create and register a data source
content_strategy = ContentStrategyDataSource()
registry.register_source(content_strategy)

Retrieving Data with Dependencies

# Get data from a source with its dependencies
data = await registry.get_data_with_dependencies("content_strategy", user_id=1, strategy_id=1)

Building Strategy-Aware Prompts

# Build a prompt for a specific step
prompt = await prompt_builder.build_prompt("step_1_content_strategy_analysis", user_id=1, strategy_id=1)

Quality Gate Validation

# Validate calendar data through all quality gates
validation_results = await quality_manager.validate_all_gates(calendar_data, "step_name")

# Validate specific quality gate
uniqueness_result = await quality_manager.validate_specific_gate("content_uniqueness", calendar_data, "step_name")

Evolution Management

# Check evolution status
status = evolution_manager.get_evolution_status()

# Get evolution plan for a source
plan = evolution_manager.get_evolution_plan("content_strategy")

# Evolve a data source
success = await evolution_manager.evolve_data_source("content_strategy", "2.5.0")

🔧 Extending the Framework

Adding a New Data Source

1. Create the data source module:

# data_sources/custom_source.py
from ..interfaces import DataSourceInterface, DataSourceType, DataSourcePriority, DataSourceValidationResult

class CustomDataSource(DataSourceInterface):
    def __init__(self):
        super().__init__("custom_source", DataSourceType.CUSTOM, DataSourcePriority.MEDIUM)
        self.version = "1.0.0"
    
    async def get_data(self, user_id: int, strategy_id: int) -> Dict[str, Any]:
        # Implement data retrieval logic
        return {"custom_data": "example"}
    
    async def validate_data(self, data: Dict[str, Any]) -> DataSourceValidationResult:
        # Implement validation logic
        validation_result = DataSourceValidationResult(is_valid=True, quality_score=0.8)
        return validation_result
    
    async def enhance_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
        # Implement AI enhancement logic
        return {**data, "enhanced": True}

2. Register the data source:

from .data_sources.custom_source import CustomDataSource

custom_source = CustomDataSource()
registry.register_source(custom_source)

3. Update the package exports:

# data_sources/__init__.py
from .custom_source import CustomDataSource

__all__ = [
    # ... existing exports
    "CustomDataSource"
]

Adding a New Quality Gate

1. Create the quality gate module:

# quality_gates/custom_gate.py
class CustomGate:
    def __init__(self):
        self.name = "custom_gate"
        self.description = "Custom quality validation"
        self.pass_threshold = 0.8
        self.validation_criteria = ["Custom validation criteria"]
    
    async def validate(self, calendar_data: Dict[str, Any], step_name: str = None) -> Dict[str, Any]:
        # Implement validation logic
        return {
            "passed": True,
            "score": 0.9,
            "issues": [],
            "recommendations": []
        }

2. Register the quality gate:

# quality_gates/quality_gate_manager.py
from .custom_gate import CustomGate

self.gates["custom_gate"] = CustomGate()

🧪 Testing

Running Framework Tests

cd backend
python test_calendar_generation_datasource_framework.py

Test Coverage

The framework includes comprehensive tests for:

• Framework Initialization: Component setup and registration
• Data Source Registry: Source management and retrieval
• Data Source Validation: Quality assessment and validation
• Prompt Builder: Strategy-aware prompt generation
• Quality Gates: Validation and scoring
• Evolution Manager: Version control and enhancement
• Framework Integration: End-to-end functionality
• Scalability Features: Custom source addition and evolution

📈 Performance & Scalability

Performance Characteristics

• Data Source Registration: O(1) constant time
• Data Retrieval: O(n) where n is dependency depth
• Quality Gate Validation: O(m) where m is number of gates
• Prompt Building: O(d) where d is data source dependencies

Scalability Features

• Modular Design: Add new components without architectural changes
• Dependency Management: Automatic dependency resolution
• Evolution Support: Version control and backward compatibility
• Quality Assurance: Comprehensive validation at each step
• Extensibility: Easy addition of new data sources and quality gates

🔒 Quality Assurance

Quality Metrics

• Data Completeness: Percentage of required fields present
• Data Quality: Accuracy and reliability of data
• Strategic Alignment: Alignment with content strategy
• Content Uniqueness: Prevention of duplicate content
• Enterprise Standards: Professional quality compliance

Quality Thresholds

• Critical Sources: 0.9+ quality score required
• High Priority Sources: 0.8+ quality score required
• Medium Priority Sources: 0.7+ quality score required
• Quality Gates: 0.8-0.9+ threshold depending on gate type

🛠️ Maintenance & Evolution

Version Management

• Semantic Versioning: Major.Minor.Patch versioning
• Backward Compatibility: Maintains compatibility with existing implementations
• Migration Support: Automated migration between versions
• Deprecation Warnings: Clear deprecation notices for removed features

Evolution Planning

• Enhancement Tracking: Track planned enhancements and improvements
• Priority Management: Prioritize enhancements based on impact
• Resource Allocation: Allocate development resources efficiently
• Risk Assessment: Assess risks before implementing changes

📚 Integration with 12-Step Prompt Chaining

This framework is designed to support the 12-step prompt chaining architecture for content calendar generation:

Phase 1: Foundation (Steps 1-3)

• Step 1: Content Strategy Analysis (Content Strategy Source)
• Step 2: Gap Analysis Integration (Gap Analysis Source)
• Step 3: Keyword Research (Keywords Source)

Phase 2: Structure (Steps 4-6)

• Step 4: Content Pillar Definition (Content Pillars Source)
• Step 5: Calendar Framework (All Sources)
• Step 6: Content Mix Planning (Content Mix Gate)

Phase 3: Generation (Steps 7-9)

• Step 7: Daily Content Generation (All Sources)
• Step 8: Content Optimization (Performance Source)
• Step 9: AI Enhancement (AI Analysis Source)

Phase 4: Validation (Steps 10-12)

• Step 10: Quality Validation (All Quality Gates)
• Step 11: Strategy Alignment (Strategy Alignment Gate)
• Step 12: Final Integration (All Components)

🤝 Contributing

Development Guidelines

1. Follow Modular Design: Keep components independent and focused
2. Maintain Quality Standards: Ensure all quality gates pass
3. Add Comprehensive Tests: Include tests for new functionality
4. Update Documentation: Keep README and docstrings current
5. Follow Naming Conventions: Use consistent naming patterns

Code Standards

• Type Hints: Use comprehensive type hints
• Docstrings: Include detailed docstrings for all methods
• Error Handling: Implement proper exception handling
• Logging: Use structured logging for debugging
• Validation: Validate inputs and outputs

📄 License

This framework is part of the ALwrity AI Writer project and follows the project's licensing terms.

🆘 Support

For issues, questions, or contributions:

1. Check the existing documentation
2. Review the test files for usage examples
3. Consult the implementation plan document
4. Create an issue with detailed information

---

Framework Version: 2.0.0 Last Updated: January 2025 Status: Production Ready Compatibility: Python 3.8+, AsyncIO