ALwrity version 0.5.6
This commit is contained in:
ajaysi
@@ -0,0 +1,428 @@
|
||||
# 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**
|
||||
|
||||
```python
|
||||
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**
|
||||
|
||||
```python
|
||||
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**
|
||||
|
||||
```python
|
||||
# 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**
|
||||
|
||||
```python
|
||||
# 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**
|
||||
|
||||
```python
|
||||
# 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**
|
||||
|
||||
```python
|
||||
# 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**:
|
||||
```python
|
||||
# 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**:
|
||||
```python
|
||||
from .data_sources.custom_source import CustomDataSource
|
||||
|
||||
custom_source = CustomDataSource()
|
||||
registry.register_source(custom_source)
|
||||
```
|
||||
|
||||
3. **Update the package exports**:
|
||||
```python
|
||||
# data_sources/__init__.py
|
||||
from .custom_source import CustomDataSource
|
||||
|
||||
__all__ = [
|
||||
# ... existing exports
|
||||
"CustomDataSource"
|
||||
]
|
||||
```
|
||||
|
||||
### **Adding a New Quality Gate**
|
||||
|
||||
1. **Create the quality gate module**:
|
||||
```python
|
||||
# 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**:
|
||||
```python
|
||||
# quality_gates/quality_gate_manager.py
|
||||
from .custom_gate import CustomGate
|
||||
|
||||
self.gates["custom_gate"] = CustomGate()
|
||||
```
|
||||
|
||||
## 🧪 **Testing**
|
||||
|
||||
### **Running Framework Tests**
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user