remdb 0.3.0__py3-none-any.whl → 0.3.114__py3-none-any.whl

rem/utils/files.py

@@ -0,0 +1,167 @@
+"""
+File utilities for consistent file handling throughout REM.
+
+Provides context managers and helpers for temporary file operations,
+ensuring proper cleanup and consistent patterns.
+"""
+
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, Optional
+
+from loguru import logger
+
+
+@contextmanager
+def temp_file_from_bytes(
+    content: bytes,
+    suffix: str = "",
+    prefix: str = "rem_",
+    dir: Optional[str] = None,
+) -> Generator[Path, None, None]:
+    """
+    Create a temporary file from bytes, yield path, cleanup automatically.
+
+    This context manager ensures proper cleanup of temporary files even
+    if an exception occurs during processing.
+
+    Args:
+        content: Bytes to write to the temporary file
+        suffix: File extension (e.g., ".pdf", ".wav")
+        prefix: Prefix for the temp file name
+        dir: Directory for temp file (uses system temp if None)
+
+    Yields:
+        Path to the temporary file
+
+    Example:
+        >>> with temp_file_from_bytes(pdf_bytes, suffix=".pdf") as tmp_path:
+        ...     result = process_pdf(tmp_path)
+        # File is automatically cleaned up after the block
+
+    Note:
+        The file is created with delete=False so we control cleanup.
+        This allows the file to be read by external processes.
+    """
+    tmp_path: Optional[Path] = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir,
+            delete=False,
+        ) as tmp:
+            tmp.write(content)
+            tmp_path = Path(tmp.name)
+
+        yield tmp_path
+
+    finally:
+        if tmp_path is not None:
+            try:
+                tmp_path.unlink(missing_ok=True)
+            except Exception as e:
+                logger.warning(f"Failed to cleanup temp file {tmp_path}: {e}")
+
+
+@contextmanager
+def temp_file_empty(
+    suffix: str = "",
+    prefix: str = "rem_",
+    dir: Optional[str] = None,
+) -> Generator[Path, None, None]:
+    """
+    Create an empty temporary file, yield path, cleanup automatically.
+
+    Useful when you need to write to a file after creation or when
+    an external process will write to the file.
+
+    Args:
+        suffix: File extension
+        prefix: Prefix for the temp file name
+        dir: Directory for temp file
+
+    Yields:
+        Path to the empty temporary file
+    """
+    tmp_path: Optional[Path] = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir,
+            delete=False,
+        ) as tmp:
+            tmp_path = Path(tmp.name)
+
+        yield tmp_path
+
+    finally:
+        if tmp_path is not None:
+            try:
+                tmp_path.unlink(missing_ok=True)
+            except Exception as e:
+                logger.warning(f"Failed to cleanup temp file {tmp_path}: {e}")
+
+
+@contextmanager
+def temp_directory(
+    prefix: str = "rem_",
+    dir: Optional[str] = None,
+) -> Generator[Path, None, None]:
+    """
+    Create a temporary directory, yield path, cleanup automatically.
+
+    Args:
+        prefix: Prefix for the temp directory name
+        dir: Parent directory for temp directory
+
+    Yields:
+        Path to the temporary directory
+    """
+    import shutil
+
+    tmp_dir: Optional[Path] = None
+    try:
+        tmp_dir = Path(tempfile.mkdtemp(prefix=prefix, dir=dir))
+        yield tmp_dir
+
+    finally:
+        if tmp_dir is not None:
+            try:
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+            except Exception as e:
+                logger.warning(f"Failed to cleanup temp directory {tmp_dir}: {e}")
+
+
+def ensure_parent_exists(path: Path) -> Path:
+    """
+    Ensure parent directory exists, creating if necessary.
+
+    Args:
+        path: File path whose parent should exist
+
+    Returns:
+        The original path (for chaining)
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def safe_delete(path: Path) -> bool:
+    """
+    Safely delete a file, returning success status.
+
+    Args:
+        path: Path to delete
+
+    Returns:
+        True if deleted or didn't exist, False on error
+    """
+    try:
+        path.unlink(missing_ok=True)
+        return True
+    except Exception as e:
+        logger.warning(f"Failed to delete {path}: {e}")
+        return False

rem/utils/mime_types.py

@@ -0,0 +1,158 @@
+"""
+Centralized MIME type mappings for file format detection.
+
+Provides bidirectional mappings between file extensions and MIME types.
+Use these constants throughout the codebase instead of inline dictionaries.
+"""
+
+# Extension to MIME type mapping (extension includes leading dot)
+EXTENSION_TO_MIME: dict[str, str] = {
+    # Images
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".tiff": "image/tiff",
+    ".svg": "image/svg+xml",
+    # Documents
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".doc": "application/msword",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".xls": "application/vnd.ms-excel",
+    # Audio
+    ".wav": "audio/wav",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/x-m4a",
+    ".flac": "audio/flac",
+    ".ogg": "audio/ogg",
+    ".aac": "audio/aac",
+    # Video
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".avi": "video/x-msvideo",
+    ".mov": "video/quicktime",
+    # Text/Code
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".markdown": "text/markdown",
+    ".json": "application/json",
+    ".yaml": "application/x-yaml",
+    ".yml": "application/x-yaml",
+    ".xml": "application/xml",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".py": "text/x-python",
+    ".ts": "application/typescript",
+    ".csv": "text/csv",
+}
+
+# MIME type to extension mapping (reverse of above, preferring shorter extensions)
+MIME_TO_EXTENSION: dict[str, str] = {
+    # Images
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/bmp": ".bmp",
+    "image/tiff": ".tiff",
+    "image/svg+xml": ".svg",
+    # Documents
+    "application/pdf": ".pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+    "application/msword": ".doc",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "application/vnd.ms-powerpoint": ".ppt",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.ms-excel": ".xls",
+    # Audio
+    "audio/wav": ".wav",
+    "audio/mpeg": ".mp3",
+    "audio/x-m4a": ".m4a",
+    "audio/mp4": ".m4a",
+    "audio/flac": ".flac",
+    "audio/ogg": ".ogg",
+    "audio/aac": ".aac",
+    # Video
+    "video/mp4": ".mp4",
+    "video/webm": ".webm",
+    "video/x-msvideo": ".avi",
+    "video/quicktime": ".mov",
+    # Text/Code
+    "text/plain": ".txt",
+    "text/markdown": ".md",
+    "application/json": ".json",
+    "application/x-yaml": ".yaml",
+    "application/xml": ".xml",
+    "text/html": ".html",
+    "text/css": ".css",
+    "application/javascript": ".js",
+    "text/x-python": ".py",
+    "application/typescript": ".ts",
+    "text/csv": ".csv",
+}
+
+# Grouped by category for convenience
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".svg"}
+DOCUMENT_EXTENSIONS = {".pdf", ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls"}
+AUDIO_EXTENSIONS = {".wav", ".mp3", ".m4a", ".flac", ".ogg", ".aac"}
+VIDEO_EXTENSIONS = {".mp4", ".webm", ".avi", ".mov"}
+TEXT_EXTENSIONS = {".txt", ".md", ".markdown", ".json", ".yaml", ".yml", ".xml", ".html", ".css", ".js", ".py", ".ts", ".csv"}
+
+
+def get_extension(mime_type: str, default: str = ".bin") -> str:
+    """
+    Get file extension for a MIME type.
+
+    Args:
+        mime_type: MIME type string (e.g., "image/png")
+        default: Default extension if MIME type not found
+
+    Returns:
+        File extension with leading dot (e.g., ".png")
+    """
+    return MIME_TO_EXTENSION.get(mime_type, default)
+
+
+def get_mime_type(extension: str, default: str = "application/octet-stream") -> str:
+    """
+    Get MIME type for a file extension.
+
+    Args:
+        extension: File extension with or without leading dot
+        default: Default MIME type if extension not found
+
+    Returns:
+        MIME type string (e.g., "image/png")
+    """
+    # Normalize extension to have leading dot
+    ext = extension if extension.startswith(".") else f".{extension}"
+    return EXTENSION_TO_MIME.get(ext.lower(), default)
+
+
+def is_image(extension_or_mime: str) -> bool:
+    """Check if extension or MIME type represents an image."""
+    if extension_or_mime.startswith("."):
+        return extension_or_mime.lower() in IMAGE_EXTENSIONS
+    return extension_or_mime.startswith("image/")
+
+
+def is_audio(extension_or_mime: str) -> bool:
+    """Check if extension or MIME type represents audio."""
+    if extension_or_mime.startswith("."):
+        return extension_or_mime.lower() in AUDIO_EXTENSIONS
+    return extension_or_mime.startswith("audio/")
+
+
+def is_document(extension_or_mime: str) -> bool:
+    """Check if extension or MIME type represents a document."""
+    if extension_or_mime.startswith("."):
+        return extension_or_mime.lower() in DOCUMENT_EXTENSIONS
+    # Check common document MIME types
+    doc_mimes = {"application/pdf", "application/msword"}
+    return extension_or_mime in doc_mimes or "officedocument" in extension_or_mime

rem/utils/model_helpers.py

@@ -16,8 +16,12 @@ Embedding Field Detection:
 Table Name Inference:
 1. model_config.json_schema_extra.table_name
 2. CamelCase → snake_case + pluralization
+
+Model Resolution:
+- model_from_arbitrary_casing: Resolve model class from flexible input casing
 """
 
+import re
 from typing import Any, Type
 
 from loguru import logger
@@ -94,7 +98,9 @@ def get_table_name(model: Type[BaseModel]) -> str:
         if isinstance(model_config, dict):
             json_extra = model_config.get("json_schema_extra", {})
             if isinstance(json_extra, dict) and "table_name" in json_extra:
-                return json_extra["table_name"]
+                table_name = json_extra["table_name"]
+                if isinstance(table_name, str):
+                    return table_name
 
     # Infer from class name
     name = model.__name__
@@ -234,3 +240,152 @@ def get_model_metadata(model: Type[BaseModel]) -> dict[str, Any]:
         "entity_key_field": get_entity_key_field(model),
         "embeddable_fields": get_embeddable_fields(model),
     }
+
+
+def normalize_to_title_case(name: str) -> str:
+    """
+    Normalize arbitrary casing to TitleCase (PascalCase).
+
+    Handles various input formats:
+    - kebab-case: domain-resource → DomainResource
+    - snake_case: domain_resource → DomainResource
+    - lowercase: domainresource → Domainresource (single word)
+    - TitleCase: DomainResource → DomainResource (passthrough)
+    - Mixed: Domain-Resource, DOMAIN_RESOURCE → DomainResource
+
+    Args:
+        name: Input name in any casing format
+
+    Returns:
+        TitleCase (PascalCase) version of the name
+
+    Example:
+        >>> normalize_to_title_case("domain-resource")
+        'DomainResource'
+        >>> normalize_to_title_case("domain_resources")
+        'DomainResources'
+        >>> normalize_to_title_case("DomainResource")
+        'DomainResource'
+    """
+    # If already TitleCase (starts with uppercase, has no delimiters, and has
+    # at least one lowercase letter), return as-is
+    if (
+        name
+        and name[0].isupper()
+        and '-' not in name
+        and '_' not in name
+        and any(c.islower() for c in name)
+    ):
+        return name
+
+    # Split on common delimiters (hyphen, underscore)
+    parts = re.split(r'[-_]', name)
+
+    # Capitalize first letter of each part, lowercase the rest
+    normalized_parts = [part.capitalize() for part in parts if part]
+
+    return "".join(normalized_parts)
+
+
+def model_from_arbitrary_casing(
+    name: str,
+    registry: dict[str, Type[BaseModel]] | None = None,
+) -> Type[BaseModel]:
+    """
+    Resolve a model class from arbitrary casing input.
+
+    REM entity models use strict TitleCase (PascalCase) naming. This function
+    allows flexible input formats while maintaining consistency:
+
+    Input formats supported:
+    - kebab-case: domain-resource, domain-resources
+    - snake_case: domain_resource, domain_resources
+    - lowercase: resource, domainresource
+    - TitleCase: Resource, DomainResource
+
+    Args:
+        name: Model name in any supported casing format
+        registry: Optional dict mapping TitleCase names to model classes.
+                  If not provided, uses rem.models.entities module.
+
+    Returns:
+        The resolved Pydantic model class
+
+    Raises:
+        ValueError: If no model matches the normalized name
+
+    Example:
+        >>> model = model_from_arbitrary_casing("domain-resources")
+        >>> model.__name__
+        'DomainResource'
+        >>> model = model_from_arbitrary_casing("Resource")
+        >>> model.__name__
+        'Resource'
+    """
+    # Build default registry from entities module if not provided
+    if registry is None:
+        from rem.models.entities import (
+            DomainResource,
+            Feedback,
+            File,
+            ImageResource,
+            Message,
+            Moment,
+            Ontology,
+            OntologyConfig,
+            Resource,
+            Schema,
+            Session,
+            User,
+        )
+
+        registry = {
+            "Resource": Resource,
+            "Resources": Resource,  # Plural alias
+            "DomainResource": DomainResource,
+            "DomainResources": DomainResource,  # Plural alias
+            "ImageResource": ImageResource,
+            "ImageResources": ImageResource,
+            "File": File,
+            "Files": File,
+            "Message": Message,
+            "Messages": Message,
+            "Moment": Moment,
+            "Moments": Moment,
+            "Session": Session,
+            "Sessions": Session,
+            "Feedback": Feedback,
+            "User": User,
+            "Users": User,
+            "Schema": Schema,
+            "Schemas": Schema,
+            "Ontology": Ontology,
+            "Ontologies": Ontology,
+            "OntologyConfig": OntologyConfig,
+            "OntologyConfigs": OntologyConfig,
+        }
+
+    # Normalize input to TitleCase
+    normalized = normalize_to_title_case(name)
+
+    # Look up in registry
+    if normalized in registry:
+        logger.debug(f"Resolved model '{name}' → {registry[normalized].__name__}")
+        return registry[normalized]
+
+    # Try without trailing 's' (singular form)
+    if normalized.endswith("s") and normalized[:-1] in registry:
+        logger.debug(f"Resolved model '{name}' → {registry[normalized[:-1]].__name__} (singular)")
+        return registry[normalized[:-1]]
+
+    # Try with trailing 's' (plural form)
+    plural = normalized + "s"
+    if plural in registry:
+        logger.debug(f"Resolved model '{name}' → {registry[plural].__name__} (plural)")
+        return registry[plural]
+
+    available = sorted(set(m.__name__ for m in registry.values()))
+    raise ValueError(
+        f"Unknown model: '{name}' (normalized: '{normalized}'). "
+        f"Available models: {', '.join(available)}"
+    )