timber-common 0.1.0__py3-none-any.whl

common/__init__.py

@@ -0,0 +1,327 @@
+# timber/common/__init__.py
+"""
+Timber Common - Shared library for OakQuant workflow system
+
+A comprehensive library providing:
+- Config-driven model creation (NEW)
+- Modular persistence services (NEW)
+- Field-level encryption (NEW)
+- GDPR compliance (NEW)
+- Vector search integration (NEW)
+- Data fetching from multiple financial APIs (yfinance, Alpha Vantage, Polygon.io)
+- Database utilities and ORM support via SQLAlchemy
+- Data validation and helpers
+- Curated company data management
+
+Quick Start (New Architecture):
+    from timber.common import initialize_timber, get_model
+    
+    # Initialize Timber
+    initialize_timber(
+        model_config_dirs=['./config/models'],
+        enable_encryption=True
+    )
+    
+    # Use dynamic models
+    User = get_model('User')
+    StockResearchSession = get_model('StockResearchSession')
+
+Quick Start (Legacy Services):
+    from timber.common.services import stock_data_service
+    
+    # Fetch stock data
+    df, error = stock_data_service.fetch_historical_data('AAPL', period='1y')
+"""
+
+__version__ = "0.2.0"
+
+# =============================================================================
+# NEW ARCHITECTURE - Core Timber Components
+# =============================================================================
+
+from .init import (
+    initialize_timber,
+    shutdown_timber,
+    get_initialization_status
+)
+
+# Import config instance and class
+from .utils.config import config, Config
+from .config.model_loader import model_loader, ModelConfigLoader
+
+from .models.base import Base, db_manager
+from .models.registry import (
+    model_registry,
+    register_model,
+    get_model,
+    get_session_model
+)
+from .models.factory import model_factory
+
+from .models.mixins import (
+    TimestampMixin,
+    SoftDeleteMixin,
+    EncryptedFieldMixin,
+    GDPRComplianceMixin,
+    SearchableMixin,
+    CacheableMixin,
+    AuditMixin
+)
+
+# =============================================================================
+# CORE SERVICES 
+# =============================================================================
+
+# These are your existing services from the old architecture
+# Import them conditionally to avoid breaking existing code
+
+try:
+    from common.services.data_fetcher import stock_data_service, StockDataService
+    STOCK_DATA_AVAILABLE = True
+except ImportError:
+    STOCK_DATA_AVAILABLE = False
+    stock_data_service = None
+    StockDataService = None
+
+try:
+    from common.services.data_fetcher import curated_data_loader, CuratedDataLoader
+    CURATED_DATA_AVAILABLE = True
+except ImportError:
+    CURATED_DATA_AVAILABLE = False
+    curated_data_loader = None
+    CuratedDataLoader = None
+
+try:
+    from .services.db_service import db_service, DBService, get_db
+    DB_SERVICE_AVAILABLE = True
+except ImportError:
+    # Fall back to new db_manager
+    DB_SERVICE_AVAILABLE = False
+    db_service = None
+    DBService = None
+    # Use new architecture's get_db
+    get_db = db_manager.get_db_session
+
+# =============================================================================
+# UTILITIES
+# =============================================================================
+
+try:
+    from .utils.helpers import (
+        parse_natural_period_to_dates,
+        standardize_symbol,
+        format_currency,
+    )
+    HELPERS_AVAILABLE = True
+except ImportError:
+    HELPERS_AVAILABLE = False
+    parse_natural_period_to_dates = None
+    standardize_symbol = None
+    format_currency = None
+
+try:
+    from .utils.validators import (
+        validate_stock_symbol,
+        validate_date_string,
+        validate_date_range,
+        validate_dataframe,
+        validate_price_data,
+    )
+    VALIDATORS_AVAILABLE = True
+except ImportError:
+    VALIDATORS_AVAILABLE = False
+    validate_stock_symbol = None
+    validate_date_string = None
+    validate_date_range = None
+    validate_dataframe = None
+    validate_price_data = None
+
+# =============================================================================
+# SUBMODULES
+# =============================================================================
+
+from . import models
+from . import schemas
+
+# =============================================================================
+# PUBLIC API
+# =============================================================================
+
+__all__ = [
+    # Version
+    '__version__',
+    
+    # ===== NEW ARCHITECTURE =====
+    
+    # Initialization
+    'initialize_timber',
+    'shutdown_timber',
+    'get_initialization_status',
+    
+    # Configuration
+    'config',
+    'Config',
+    'model_loader',
+    'ModelConfigLoader',
+    
+    # Database
+    'Base',
+    'db_manager',
+    'get_db',
+    
+    # Models
+    'model_registry',
+    'register_model',
+    'get_model',
+    'get_session_model',
+    'model_factory',
+    
+    # Mixins
+    'TimestampMixin',
+    'SoftDeleteMixin',
+    'EncryptedFieldMixin',
+    'GDPRComplianceMixin',
+    'SearchableMixin',
+    'CacheableMixin',
+    'AuditMixin',
+    
+    # ===== CORE SERVICES =====
+    
+    # Stock data service
+    'stock_data_service',
+    'StockDataService',
+    
+    # Curated data service
+    'curated_data_loader',
+    'CuratedDataLoader',
+    
+    # DB service (legacy)
+    'db_service',
+    'DBService',
+    
+    # ===== UTILITIES =====
+    
+    # Helpers
+    'parse_natural_period_to_dates',
+    'standardize_symbol',
+    'format_currency',
+    
+    # Validators
+    'validate_stock_symbol',
+    'validate_date_string',
+    'validate_date_range',
+    'validate_dataframe',
+    'validate_price_data',
+    
+    # ===== SUBMODULES =====
+    
+    'models',
+    'schemas',
+]
+
+
+# =============================================================================
+# CONVENIENCE FUNCTIONS
+# =============================================================================
+
+def get_version() -> str:
+    """Return the current version of timber_common."""
+    return __version__
+
+
+def get_available_features() -> dict:
+    """
+    Get information about available features.
+    
+    Returns:
+        Dictionary showing which features are available
+    """
+    return {
+        'version': __version__,
+        'new_architecture': {
+            'models': True,
+            'persistence': True,
+            'encryption': True,
+            'gdpr': True,
+            'vector_search': True,
+        },
+        'legacy_services': {
+            'stock_data_service': STOCK_DATA_AVAILABLE,
+            'curated_data_loader': CURATED_DATA_AVAILABLE,
+            'db_service': DB_SERVICE_AVAILABLE,
+        },
+        'utilities': {
+            'helpers': HELPERS_AVAILABLE,
+            'validators': VALIDATORS_AVAILABLE,
+        }
+    }
+
+
+def validate_configuration() -> dict:
+    """
+    Validate the current configuration.
+    
+    Returns:
+        Dictionary with validation results
+    """
+    results = {
+        'new_architecture': True,
+        'database_url': config.DATABASE_URL is not None,
+        'encryption_key': config.ENCRYPTION_KEY is not None,
+    }
+    
+    # Test database connection if initialized
+    if db_manager._engine:
+        results['database_connected'] = db_manager.check_connection()
+    else:
+        results['database_connected'] = None
+        results['note'] = 'Database not initialized. Call initialize_timber() first.'
+    
+    # Check legacy services
+    if DB_SERVICE_AVAILABLE and db_service:
+        try:
+            results['legacy_db_healthy'] = db_service.health_check()
+        except Exception as e:
+            results['legacy_db_healthy'] = False
+            results['legacy_db_error'] = str(e)
+    
+    return results
+
+
+def print_status():
+    """Print current Timber status to console."""
+    print("=" * 60)
+    print("Timber Common Library Status")
+    print("=" * 60)
+    
+    features = get_available_features()
+    
+    print(f"\nVersion: {features['version']}")
+    
+    print("\n🆕 New Architecture:")
+    for feature, available in features['new_architecture'].items():
+        status = "✓" if available else "✗"
+        print(f"  {status} {feature}")
+    
+    print("\n📦 Legacy Services:")
+    for service, available in features['legacy_services'].items():
+        status = "✓" if available else "✗"
+        print(f"  {status} {service}")
+    
+    print("\n🔧 Utilities:")
+    for util, available in features['utilities'].items():
+        status = "✓" if available else "✗"
+        print(f"  {status} {util}")
+    
+    if db_manager._engine:
+        status = get_initialization_status()
+        print(f"\n📊 Database:")
+        print(f"  Models registered: {status['models_registered']}")
+        print(f"  Session types: {status['session_types']}")
+        print(f"  Tables: {status['database_tables']}")
+        print(f"  Connected: {status['database_connected']}")
+    else:
+        print(f"\n📊 Database: Not initialized")
+        print(f"  Call initialize_timber() to set up")
+    
+    print("\n" + "=" * 60)

common/config/__init__.py

@@ -0,0 +1,16 @@
+# timber/common/config/__init__.py
+"""
+Configuration Module
+
+Provides configuration management and model loading capabilities.
+"""
+
+from common.utils.config import config, Config
+from .model_loader import model_loader, ModelConfigLoader
+
+__all__ = [
+    'config',
+    'Config',
+    'model_loader',
+    'ModelConfigLoader',
+]

common/config/model_loader.py

@@ -0,0 +1,258 @@
+# timber/common/config/model_loader.py
+"""
+Model Configuration Loader - ENHANCED VERSION
+
+Loads model definitions from YAML configuration files with dependency resolution.
+Supports 'depends' attribute to control loading order.
+"""
+
+import yaml
+from pathlib import Path
+from typing import List, Optional, Dict, Set
+import logging
+
+from ..models.factory import model_factory
+from ..models.registry import model_registry
+
+logger = logging.getLogger(__name__)
+
+
+class ModelConfigLoader:
+    """
+    Loads and creates models from YAML configuration files.
+    
+    Supports dependency-based loading order via 'depends' attribute in YAML files.
+    
+    Example YAML with dependencies:
+        version: "1.0.0"
+        depends: ["00_association_tables.yaml"]  # Load this first
+        models:
+          - name: MyModel
+            ...
+    """
+    
+    def __init__(self):
+        self.loaded_configs: List[str] = []
+        self.loaded_models: List[str] = []
+    
+    def load_from_file(self, config_path: str) -> List:
+        """
+        Load models from a single YAML config file.
+        
+        Args:
+            config_path: Path to YAML configuration file
+        
+        Returns:
+            List of created model classes
+        """
+        logger.info(f"Loading models from: {config_path}")
+        
+        try:
+            models = model_factory.create_model_from_config_file(config_path)
+            
+            self.loaded_configs.append(config_path)
+            self.loaded_models.extend([m.__name__ for m in models])
+            
+            logger.info(f"Loaded {len(models)} models from {config_path}")
+            return models
+            
+        except Exception as e:
+            logger.error(f"Failed to load config from {config_path}: {e}")
+            raise
+    
+    def _get_file_dependencies(self, config_file: Path) -> List[str]:
+        """
+        Get dependencies from a YAML config file.
+        
+        Args:
+            config_file: Path to config file
+        
+        Returns:
+            List of dependency filenames (not full paths)
+        """
+        try:
+            with open(config_file, 'r') as f:
+                config_data = yaml.safe_load(f)
+            
+            if not config_data:
+                return []
+            
+            # Check for 'depends' or 'dependencies' key
+            depends = config_data.get('depends', config_data.get('dependencies', []))
+            
+            if isinstance(depends, str):
+                depends = [depends]
+            
+            return depends if isinstance(depends, list) else []
+            
+        except Exception as e:
+            logger.warning(f"Could not read dependencies from {config_file}: {e}")
+            return []
+    
+    def _topological_sort(
+        self,
+        files: List[Path],
+        config_dir: Path
+    ) -> List[Path]:
+        """
+        Sort config files based on dependencies using topological sort.
+        
+        Args:
+            files: List of config file paths
+            config_dir: Base directory for resolving relative dependencies
+        
+        Returns:
+            Sorted list of config files
+        """
+        # Build dependency graph
+        file_deps: Dict[str, List[str]] = {}
+        file_map: Dict[str, Path] = {}
+        
+        for file_path in files:
+            filename = file_path.name
+            file_map[filename] = file_path
+            file_deps[filename] = self._get_file_dependencies(file_path)
+        
+        # Topological sort using Kahn's algorithm
+        in_degree: Dict[str, int] = {name: 0 for name in file_map.keys()}
+        
+        for filename, deps in file_deps.items():
+            for dep in deps:
+                if dep in in_degree:
+                    in_degree[filename] += 1
+        
+        # Queue of files with no dependencies
+        queue = [name for name, degree in in_degree.items() if degree == 0]
+        sorted_files = []
+        
+        while queue:
+            # Sort queue alphabetically for deterministic ordering
+            queue.sort()
+            
+            filename = queue.pop(0)
+            sorted_files.append(file_map[filename])
+            
+            # Reduce in-degree for files that depend on this one
+            for other_file, deps in file_deps.items():
+                if filename in deps:
+                    in_degree[other_file] -= 1
+                    if in_degree[other_file] == 0:
+                        queue.append(other_file)
+        
+        # Check for circular dependencies
+        if len(sorted_files) != len(files):
+            remaining = set(file_map.keys()) - {f.name for f in sorted_files}
+            logger.error(f"Circular dependency detected in files: {remaining}")
+            # Fall back to alphabetical sort
+            logger.warning("Falling back to alphabetical sort")
+            return sorted(files)
+        
+        logger.debug(f"File load order (dependency-sorted): {[f.name for f in sorted_files]}")
+        return sorted_files
+    
+    def load_from_directory(
+        self,
+        directory_path: str,
+        pattern: str = "*.yaml",
+        recursive: bool = False,
+        use_dependencies: bool = True
+    ) -> List:
+        """
+        Load all model configs from a directory.
+        
+        Args:
+            directory_path: Path to directory containing config files
+            pattern: Glob pattern for config files (default: *.yaml)
+            recursive: If True, search subdirectories
+            use_dependencies: If True, sort files by dependencies (default: True)
+        
+        Returns:
+            List of all created model classes
+        """
+        config_dir = Path(directory_path)
+        
+        if not config_dir.exists():
+            logger.warning(f"Config directory does not exist: {directory_path}")
+            return []
+        
+        logger.info(f"Loading models from directory: {directory_path}")
+        
+        all_models = []
+        
+        # Find all config files
+        if recursive:
+            config_files = list(config_dir.rglob(pattern))
+        else:
+            config_files = list(config_dir.glob(pattern))
+        
+        if not config_files:
+            logger.warning(f"No config files found in {directory_path}")
+            return []
+        
+        # Sort files by dependencies or alphabetically
+        if use_dependencies:
+            sorted_files = self._topological_sort(config_files, config_dir)
+        else:
+            sorted_files = sorted(config_files)
+        
+        logger.info(f"Loading {len(sorted_files)} config files in order:")
+        for idx, file_path in enumerate(sorted_files, 1):
+            logger.info(f"  {idx}. {file_path.name}")
+        
+        # Load each config file in order
+        for config_file in sorted_files:
+            try:
+                models = self.load_from_file(str(config_file))
+                all_models.extend(models)
+            except Exception as e:
+                logger.error(f"Error loading {config_file}: {e}")
+                # Continue loading other files rather than stopping
+                continue
+        
+        logger.info(f"Loaded {len(all_models)} total models from {directory_path}")
+        return all_models
+    
+    def load_from_multiple_directories(self, directories: List[str]) -> List:
+        """
+        Load models from multiple directories.
+        
+        Args:
+            directories: List of directory paths
+        
+        Returns:
+            List of all created model classes
+        """
+        all_models = []
+        
+        for directory in directories:
+            models = self.load_from_directory(directory)
+            all_models.extend(models)
+        
+        return all_models
+    
+    def get_loaded_configs(self) -> List[str]:
+        """Get list of loaded configuration file paths."""
+        return self.loaded_configs
+    
+    def get_loaded_models(self) -> List[str]:
+        """Get list of loaded model names."""
+        return self.loaded_models
+    
+    def reload(self, config_path: str):
+        """
+        Reload models from a configuration file.
+        
+        Args:
+            config_path: Path to config file to reload
+        """
+        logger.info(f"Reloading models from {config_path}")
+        
+        # Load the config again
+        models = self.load_from_file(config_path)
+        
+        logger.info(f"Reloaded {len(models)} models from {config_path}")
+        return models
+
+
+# Singleton instance
+model_loader = ModelConfigLoader()