django-cfg 1.3.11__py3-none-any.whl → 1.4.0__py3-none-any.whl

django_cfg/apps/knowbase/admin/helpers/__init__.py

@@ -0,0 +1,17 @@
+"""
+Admin helper modules for knowbase.
+
+Provides shared display methods, configurations, and utilities.
+"""
+
+from .configs import DocumentAdminConfigs
+from .display_helpers import DocumentDisplayHelpers
+from .statistics import DocumentStatistics, ChunkStatistics, CategoryStatistics
+
+__all__ = [
+    'DocumentAdminConfigs',
+    'DocumentDisplayHelpers',
+    'DocumentStatistics',
+    'ChunkStatistics',
+    'CategoryStatistics',
+]

django_cfg/apps/knowbase/admin/helpers/configs.py

@@ -0,0 +1,72 @@
+"""
+Shared configuration objects for admin displays.
+
+Provides pre-configured StatusBadgeConfig, MoneyDisplayConfig, etc.
+for consistent display across all document admin interfaces.
+"""
+
+from django_cfg.modules.django_admin import (
+    MoneyDisplayConfig,
+    StatusBadgeConfig,
+    DateTimeDisplayConfig,
+    Icons,
+)
+
+
+class DocumentAdminConfigs:
+    """Shared configuration objects for document admins."""
+
+    # Visibility badges
+    VISIBILITY_PUBLIC = StatusBadgeConfig(show_icons=True, icon=Icons.PUBLIC)
+    VISIBILITY_PRIVATE = StatusBadgeConfig(show_icons=True, icon=Icons.LOCK)
+
+    # Vectorization status badges
+    VECTORIZED = StatusBadgeConfig(show_icons=True, icon=Icons.CHECK_CIRCLE)
+    NOT_VECTORIZED = StatusBadgeConfig(show_icons=True, icon=Icons.ERROR)
+
+    # Entity type badges
+    DOCUMENT_TITLE = StatusBadgeConfig(show_icons=True, icon=Icons.DESCRIPTION)
+    CHUNK = StatusBadgeConfig(show_icons=True, icon=Icons.ARTICLE)
+    CATEGORY = StatusBadgeConfig(show_icons=True, icon=Icons.FOLDER)
+
+    # Processing status
+    PROCESSING_STATUS = StatusBadgeConfig(
+        custom_mappings={
+            'pending': 'warning',
+            'processing': 'info',
+            'completed': 'success',
+            'failed': 'danger',
+            'cancelled': 'secondary'
+        },
+        show_icons=True
+    )
+
+    # Money display configuration
+    COST_USD = MoneyDisplayConfig(
+        currency="USD",
+        decimal_places=6,
+        show_sign=False
+    )
+
+    # DateTime display configuration
+    CREATED_AT = DateTimeDisplayConfig(show_relative=True)
+
+    @classmethod
+    def get_processing_status_icon(cls, status: str) -> str:
+        """
+        Get appropriate icon for processing status.
+
+        Args:
+            status: Processing status value
+
+        Returns:
+            Icon constant
+        """
+        status_icons = {
+            'completed': Icons.CHECK_CIRCLE,
+            'failed': Icons.ERROR,
+            'processing': Icons.SCHEDULE,
+            'pending': Icons.SCHEDULE,
+            'cancelled': Icons.CANCEL
+        }
+        return status_icons.get(status, Icons.SCHEDULE)

django_cfg/apps/knowbase/admin/helpers/display_helpers.py

@@ -0,0 +1,156 @@
+"""
+Shared display helper methods for document admins.
+
+Provides reusable display methods to eliminate duplication across
+DocumentAdmin, DocumentChunkAdmin, and DocumentCategoryAdmin.
+"""
+
+from django_cfg.modules.django_admin import display
+from django_cfg.modules.django_admin.utils.badges import StatusBadge
+
+from .configs import DocumentAdminConfigs
+
+
+class DocumentDisplayHelpers:
+    """Shared display methods for document admin interfaces."""
+
+    @staticmethod
+    @display(description="User")
+    def display_user(obj, display_mixin):
+        """
+        Display user with standard formatting.
+
+        Args:
+            obj: Model instance with user field
+            display_mixin: DisplayMixin instance for formatting
+
+        Returns:
+            Formatted user display or "—" if no user
+        """
+        if not obj.user:
+            return "—"
+        return display_mixin.display_user_simple(obj.user)
+
+    @staticmethod
+    @display(description="Visibility")
+    def display_visibility(obj):
+        """
+        Display visibility status (public/private).
+
+        Args:
+            obj: Model instance with is_public field
+
+        Returns:
+            Status badge showing public or private status
+        """
+        if obj.is_public:
+            return StatusBadge.create(
+                text="Public",
+                variant="success",
+                config=DocumentAdminConfigs.VISIBILITY_PUBLIC
+            )
+        else:
+            return StatusBadge.create(
+                text="Private",
+                variant="danger",
+                config=DocumentAdminConfigs.VISIBILITY_PRIVATE
+            )
+
+    @staticmethod
+    @display(description="Tokens")
+    def display_token_count(obj, field_name='token_count'):
+        """
+        Display token count with K formatting.
+
+        Args:
+            obj: Model instance with token count field
+            field_name: Name of the token count field
+
+        Returns:
+            Formatted token count (e.g., "1.5K" or "500")
+        """
+        tokens = getattr(obj, field_name, 0)
+        if tokens > 1000:
+            return f"{tokens/1000:.1f}K"
+        return str(tokens)
+
+    @staticmethod
+    @display(description="Cost (USD)")
+    def display_cost_usd(obj, display_mixin, field_name='total_cost_usd'):
+        """
+        Display cost with currency formatting.
+
+        Args:
+            obj: Model instance with cost field
+            display_mixin: DisplayMixin instance for formatting
+            field_name: Name of the cost field
+
+        Returns:
+            Formatted cost with currency
+        """
+        return display_mixin.display_money_amount(
+            obj, field_name, DocumentAdminConfigs.COST_USD
+        )
+
+    @staticmethod
+    @display(description="Created")
+    def display_created_at(obj, display_mixin):
+        """
+        Display created time with relative display.
+
+        Args:
+            obj: Model instance with created_at field
+            display_mixin: DisplayMixin instance for formatting
+
+        Returns:
+            Formatted datetime with relative time
+        """
+        return display_mixin.display_datetime_relative(
+            obj, 'created_at', DocumentAdminConfigs.CREATED_AT
+        )
+
+    @staticmethod
+    @display(description="Embedding")
+    def display_embedding_status(obj):
+        """
+        Display embedding vectorization status.
+
+        Args:
+            obj: Model instance with embedding field
+
+        Returns:
+            Status badge showing vectorization status
+        """
+        has_embedding = obj.embedding is not None and len(obj.embedding) > 0
+        if has_embedding:
+            return StatusBadge.create(
+                text="✓ Vectorized",
+                variant="success",
+                config=DocumentAdminConfigs.VECTORIZED
+            )
+        else:
+            return StatusBadge.create(
+                text="✗ Not vectorized",
+                variant="danger",
+                config=DocumentAdminConfigs.NOT_VECTORIZED
+            )
+
+    @staticmethod
+    @display(description="Content Preview")
+    def display_content_preview(obj, max_length=200):
+        """
+        Display content preview with truncation.
+
+        Args:
+            obj: Model instance with content field
+            max_length: Maximum length before truncation
+
+        Returns:
+            Truncated content preview
+        """
+        if not obj.content:
+            return "—"
+        content = obj.content
+        if len(content) > max_length:
+            return content[:max_length] + "..."
+        return content

django_cfg/apps/knowbase/admin/helpers/statistics.py

@@ -0,0 +1,108 @@
+"""
+Statistics calculation for document admin changelist views.
+
+Provides reusable statistics aggregation logic for admin interfaces.
+"""
+
+from django.db.models import Count, Sum, Avg, Q
+
+
+class DocumentStatistics:
+    """Calculate statistics for document admin."""
+
+    @staticmethod
+    def get_document_stats(queryset):
+        """
+        Calculate document statistics.
+
+        Args:
+            queryset: Document queryset to aggregate
+
+        Returns:
+            dict: Statistics including counts, tokens, and costs
+        """
+        stats = queryset.aggregate(
+            total_documents=Count('id'),
+            total_chunks=Sum('chunks_count'),
+            total_tokens=Sum('total_tokens'),
+            total_cost=Sum('total_cost_usd')
+        )
+
+        status_counts = dict(
+            queryset.values_list('processing_status').annotate(
+                count=Count('id')
+            )
+        )
+
+        return {
+            'total_documents': stats['total_documents'] or 0,
+            'total_chunks': stats['total_chunks'] or 0,
+            'total_tokens': stats['total_tokens'] or 0,
+            'total_cost': f"${(stats['total_cost'] or 0):.6f}",
+            'status_counts': status_counts
+        }
+
+
+class ChunkStatistics:
+    """Calculate statistics for chunk admin."""
+
+    @staticmethod
+    def get_chunk_stats(queryset):
+        """
+        Calculate chunk statistics.
+
+        Args:
+            queryset: DocumentChunk queryset to aggregate
+
+        Returns:
+            dict: Statistics including counts, tokens, and costs
+        """
+        stats = queryset.aggregate(
+            total_chunks=Count('id'),
+            total_tokens=Sum('token_count'),
+            total_characters=Sum('character_count'),
+            total_embedding_cost=Sum('embedding_cost'),
+            avg_tokens_per_chunk=Avg('token_count')
+        )
+
+        model_counts = dict(
+            queryset.values_list('embedding_model').annotate(
+                count=Count('id')
+            )
+        )
+
+        return {
+            'total_chunks': stats['total_chunks'] or 0,
+            'total_tokens': stats['total_tokens'] or 0,
+            'total_characters': stats['total_characters'] or 0,
+            'total_embedding_cost': f"${(stats['total_embedding_cost'] or 0):.6f}",
+            'avg_tokens_per_chunk': f"{(stats['avg_tokens_per_chunk'] or 0):.0f}",
+            'model_counts': model_counts
+        }
+
+
+class CategoryStatistics:
+    """Calculate statistics for category admin."""
+
+    @staticmethod
+    def get_category_stats(queryset):
+        """
+        Calculate category statistics.
+
+        Args:
+            queryset: DocumentCategory queryset to aggregate
+
+        Returns:
+            dict: Statistics including public/private counts
+        """
+        stats = queryset.aggregate(
+            total_categories=Count('id'),
+            public_categories=Count('id', filter=Q(is_public=True)),
+            private_categories=Count('id', filter=Q(is_public=False))
+        )
+
+        return {
+            'total_categories': stats['total_categories'] or 0,
+            'public_categories': stats['public_categories'] or 0,
+            'private_categories': stats['private_categories'] or 0
+        }

django_cfg/apps/knowbase/config/constance_fields.py

@@ -9,7 +9,7 @@ to ensure consistency across the application.
 """
 
 from typing import List
-from django_cfg.models.constance import ConstanceField
+from django_cfg.models.django.constance import ConstanceField
 from .settings import KnowledgeBaseConfig, get_openai_api_key, get_openrouter_api_key
 
 

django_cfg/apps/knowbase/config/settings.py

@@ -258,7 +258,7 @@ class KnowledgeBaseConfig(BaseModel):
     def get_openai_api_key(self) -> Optional[str]:
         """Get OpenAI API key from django-cfg configuration."""
         try:
-            from django_cfg.core.config import get_current_config
+            from django_cfg.core.state import get_current_config
             config = get_current_config()
             if config and hasattr(config, 'api_keys') and config.api_keys:
                 return config.api_keys.get_openai_key()
@@ -271,7 +271,7 @@ class KnowledgeBaseConfig(BaseModel):
     def get_openrouter_api_key(self) -> Optional[str]:
         """Get OpenRouter API key from django-cfg configuration."""
         try:
-            from django_cfg.core.config import get_current_config
+            from django_cfg.core.state import get_current_config
             config = get_current_config()
             if config and hasattr(config, 'api_keys') and config.api_keys:
                 return config.api_keys.get_openrouter_key()

django_cfg/apps/knowbase/mixins/__init__.py

@@ -3,13 +3,30 @@ Mixins for knowbase integration.
 """
 
 from .external_data_mixin import ExternalDataMixin
-from .config import ExternalDataConfig
+from .config import ExternalDataMetaConfig, ExternalDataMetaParser, ExternalDataDefaults
 from .creator import ExternalDataCreator
 from .service import ExternalDataService
+from .generators import (
+    ExternalDataContentGenerator,
+    ExternalDataMetadataGenerator,
+    ExternalDataFieldAnalyzer,
+)
 
 __all__ = [
+    # Core mixin
     'ExternalDataMixin',
-    'ExternalDataConfig',
+
+    # Configuration
+    'ExternalDataMetaConfig',
+    'ExternalDataMetaParser',
+    'ExternalDataDefaults',
+
+    # Service layer
     'ExternalDataCreator',
     'ExternalDataService',
+
+    # Generators (for advanced usage)
+    'ExternalDataContentGenerator',
+    'ExternalDataMetadataGenerator',
+    'ExternalDataFieldAnalyzer',
 ]

django_cfg/apps/knowbase/mixins/config/__init__.py

@@ -0,0 +1,14 @@
+"""
+Configuration utilities for ExternalData.
+
+Parsing and defaults for ExternalDataMeta configuration.
+"""
+
+from .meta_config import ExternalDataMetaConfig, ExternalDataMetaParser
+from .defaults import ExternalDataDefaults
+
+__all__ = [
+    'ExternalDataMetaConfig',
+    'ExternalDataMetaParser',
+    'ExternalDataDefaults',
+]

django_cfg/apps/knowbase/mixins/config/defaults.py

@@ -0,0 +1,75 @@
+"""
+Smart defaults for ExternalData configuration.
+
+Provides sensible defaults for ExternalData configuration when not explicitly specified.
+"""
+
+from typing import List
+
+from ...models.external_data import ExternalDataType
+from ..generators import ExternalDataFieldAnalyzer
+
+
+class ExternalDataDefaults:
+    """
+    Provide smart defaults for ExternalData configuration.
+
+    Offers utilities to get sensible defaults when ExternalDataMeta
+    is not provided or incomplete.
+    """
+
+    @staticmethod
+    def get_default_watch_fields(model_class) -> List[str]:
+        """
+        Get default watch fields for a model class.
+
+        Uses field analyzer to detect important fields.
+
+        Args:
+            model_class: Django model class
+
+        Returns:
+            List of field names to watch
+        """
+        analyzer = ExternalDataFieldAnalyzer(model_class)
+        return analyzer.auto_detect_watch_fields()
+
+    @staticmethod
+    def get_default_source_type() -> ExternalDataType:
+        """
+        Get default source type.
+
+        Returns:
+            ExternalDataType.MODEL as default
+        """
+        return ExternalDataType.MODEL
+
+    @staticmethod
+    def get_default_similarity_threshold() -> float:
+        """
+        Get default similarity threshold.
+
+        Returns:
+            0.5 as balanced default threshold
+        """
+        return 0.5
+
+    @staticmethod
+    def get_default_auto_sync() -> bool:
+        """
+        Get default auto_sync setting.
+
+        Returns:
+            True (enabled by default)
+        """
+        return True
+
+    @staticmethod
+    def get_default_is_public() -> bool:
+        """
+        Get default is_public setting.
+
+        Returns:
+            False (private by default for security)
+        """
+        return False

django_cfg/apps/knowbase/mixins/config/meta_config.py

@@ -0,0 +1,120 @@
+"""
+ExternalDataMeta configuration parser.
+
+Handles parsing and processing of ExternalDataMeta configuration from model classes.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+
+from ...models.external_data import ExternalDataType
+from ..generators import ExternalDataFieldAnalyzer
+
+
+@dataclass
+class ExternalDataMetaConfig:
+    """
+    Configuration from ExternalDataMeta class.
+
+    Attributes:
+        watch_fields: List of field names to watch for changes
+        similarity_threshold: Threshold for similarity search (0.0-1.0)
+        source_type: Type of external data source
+        auto_sync: Whether to automatically sync on changes
+        is_public: Whether data is public
+        title: Title for the external data (for create_from_config)
+        description: Description for the external data
+        content: Content for the external data
+        source_identifier: Source identifier
+        is_active: Whether the data is active
+        metadata: Additional metadata
+        tags: List of tags
+        source_config: Source configuration dict
+    """
+    # Core configuration fields
+    watch_fields: List[str] = field(default_factory=list)
+    similarity_threshold: float = 0.5
+    source_type: ExternalDataType = ExternalDataType.MODEL
+    auto_sync: bool = True
+    is_public: bool = False
+
+    # ExternalData creation fields (used by ExternalDataCreator)
+    title: str = ""
+    description: str = ""
+    content: str = ""
+    source_identifier: str = ""
+    is_active: bool = True
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    tags: List[str] = field(default_factory=list)
+    source_config: Dict[str, Any] = field(default_factory=dict)
+
+
+class ExternalDataMetaParser:
+    """
+    Parse ExternalDataMeta from model class.
+
+    Extracts configuration from model's ExternalDataMeta inner class
+    and applies smart defaults where needed.
+    """
+
+    @staticmethod
+    def parse(model_class) -> Dict[str, Any]:
+        """
+        Parse ExternalDataMeta configuration from model class.
+
+        Args:
+            model_class: Django model class with optional ExternalDataMeta
+
+        Returns:
+            Dictionary with parsed configuration and smart defaults
+        """
+        config = {}
+
+        # If ExternalDataMeta exists, use it
+        if hasattr(model_class, 'ExternalDataMeta'):
+            meta_class = model_class.ExternalDataMeta
+            # Extract configuration from ExternalDataMeta
+            for attr in dir(meta_class):
+                if not attr.startswith('_'):
+                    value = getattr(meta_class, attr)
+                    if not callable(value):  # Only properties, not methods
+                        config[attr] = value
+
+        # Smart defaults based on model analysis
+        if 'watch_fields' not in config:
+            analyzer = ExternalDataFieldAnalyzer(model_class)
+            config['watch_fields'] = analyzer.auto_detect_watch_fields()
+
+        if 'similarity_threshold' not in config:
+            config['similarity_threshold'] = 0.5  # Balanced default
+
+        if 'source_type' not in config:
+            config['source_type'] = ExternalDataType.MODEL  # Smart default
+
+        if 'auto_sync' not in config:
+            config['auto_sync'] = True  # Enable by default
+
+        if 'is_public' not in config:
+            config['is_public'] = False  # Private by default for security
+
+        return config
+
+    @staticmethod
+    def to_dataclass(model_class) -> ExternalDataMetaConfig:
+        """
+        Parse configuration and return as dataclass.
+
+        Args:
+            model_class: Django model class
+
+        Returns:
+            ExternalDataMetaConfig dataclass instance
+        """
+        config_dict = ExternalDataMetaParser.parse(model_class)
+        return ExternalDataMetaConfig(
+            watch_fields=config_dict.get('watch_fields', []),
+            similarity_threshold=config_dict.get('similarity_threshold', 0.5),
+            source_type=config_dict.get('source_type', ExternalDataType.MODEL),
+            auto_sync=config_dict.get('auto_sync', True),
+            is_public=config_dict.get('is_public', False),
+        )

django_cfg/apps/knowbase/mixins/creator.py

@@ -8,7 +8,7 @@ from django.contrib.auth import get_user_model
 from django.db import transaction
 from django.utils import timezone
 
-from .config import ExternalDataConfig
+from .config import ExternalDataMetaConfig
 from ..models.external_data import ExternalData, ExternalDataStatus
 
 logger = logging.getLogger(__name__)
@@ -25,12 +25,12 @@ class ExternalDataCreator:
         else:
             self.user = user
     
-    def create_from_config(self, config: ExternalDataConfig) -> Dict[str, Any]:
+    def create_from_config(self, config: ExternalDataMetaConfig) -> Dict[str, Any]:
         """
         Create an ExternalData object from a Pydantic configuration.
         
         Args:
-            config: An instance of ExternalDataConfig.
+            config: An instance of ExternalDataMetaConfig.
             
         Returns:
             dict: Result with success status, external_data object, and message/error.
@@ -72,10 +72,10 @@ class ExternalDataCreator:
     def _get_default_user(self):
         """Get default user for ExternalData ownership."""
         User = get_user_model()
-        
-        # Try to find a superuser
-        superuser = User.objects.filter(is_superuser=True).first()
-        if superuser:
-            return superuser
-        
-        raise ValueError("No user provided and no superuser found for ExternalData ownership")
+
+        # Try to find a staff user (staff or superuser)
+        staff_user = User.objects.filter(is_staff=True).first()
+        if staff_user:
+            return staff_user
+
+        raise ValueError("No user provided and no staff user found for ExternalData ownership")