vs-common 0.1.0__py3-none-any.whl

vs_common/cache/in_memory_cache.py

@@ -0,0 +1,63 @@
+import asyncio
+import fnmatch
+import time
+from typing import Any, Dict, Optional, Tuple
+
+from vs_common.cache.vs_base_cache import VsBaseCache
+
+_CLEANUP_INTERVAL = 100  # evict expired entries every N writes
+
+
+class InMemoryCache(VsBaseCache):
+
+    def __init__(self):
+        self._store: Dict[str, Tuple[Any, Optional[float]]] = {}
+        self._lock = asyncio.Lock()
+        self._write_count = 0
+
+    def _is_expired(self, expires_at: Optional[float]) -> bool:
+        return expires_at is not None and time.monotonic() > expires_at
+
+    def _evict_expired(self) -> None:
+        now = time.monotonic()
+        expired = [k for k, (_, exp) in self._store.items() if exp is not None and now > exp]
+        for k in expired:
+            del self._store[k]
+
+    async def get(self, key: str) -> Optional[Any]:
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            value, expires_at = entry
+            if self._is_expired(expires_at):
+                del self._store[key]
+                return None
+            return value
+
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        expires_at = time.monotonic() + ttl if ttl is not None else None
+        async with self._lock:
+            self._store[key] = (value, expires_at)
+            self._write_count += 1
+            if self._write_count >= _CLEANUP_INTERVAL:
+                self._evict_expired()
+                self._write_count = 0
+        return True
+
+    async def delete(self, key: str) -> bool:
+        async with self._lock:
+            if key in self._store:
+                del self._store[key]
+                return True
+            return False
+
+    async def delete_pattern(self, pattern: str) -> int:
+        async with self._lock:
+            matched = [k for k in self._store if fnmatch.fnmatch(k, pattern)]
+            for k in matched:
+                del self._store[k]
+            return len(matched)
+
+    async def ping(self) -> bool:
+        return True

vs_common/cache/redis_cache.py

@@ -0,0 +1,47 @@
+from typing import Any, Optional
+
+import redis.asyncio as aioredis
+
+from vs_common.cache.vs_base_cache import VsBaseCache
+from vs_common.schema.vs_cache_config import VsCacheConfig
+
+
+class RedisCache(VsBaseCache):
+
+    def __init__(self, config: VsCacheConfig):
+        self._default_ttl = config.default_ttl
+        self._client = aioredis.Redis(
+            host=config.host,
+            port=config.port,
+            db=config.db,
+            password=config.password,
+            decode_responses=False,
+        )
+
+    async def get(self, key: str) -> Optional[Any]:
+        import pickle
+        value = await self._client.get(key)
+        return pickle.loads(value) if value is not None else None
+
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        import pickle
+        ex = ttl if ttl is not None else self._default_ttl
+        return await self._client.set(key, pickle.dumps(value), ex=ex)
+
+    async def delete(self, key: str) -> bool:
+        return await self._client.delete(key) > 0
+
+    async def delete_pattern(self, pattern: str) -> int:
+        keys = await self._client.keys(pattern)
+        if not keys:
+            return 0
+        return await self._client.delete(*keys)
+
+    async def ping(self) -> bool:
+        try:
+            return await self._client.ping()
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        await self._client.aclose()

vs_common/cache/vs_base_cache.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class VsBaseCache(ABC):
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[Any]:
+        """Return the cached value, or None if missing or cache is disabled."""
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """Store value under key with TTL (seconds). Returns True on success."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """Remove a single key. Returns True if the key existed."""
+
+    @abstractmethod
+    async def delete_pattern(self, pattern: str) -> int:
+        """Remove all keys matching a glob pattern. Returns count deleted."""
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check — True if the cache backend is reachable."""

vs_common/cache/vs_cache_manager.py

@@ -0,0 +1,82 @@
+import threading
+from typing import Any, Optional
+
+from vs_common.cache.in_memory_cache import InMemoryCache
+from vs_common.cache.redis_cache import RedisCache
+from vs_common.cache.vs_base_cache import VsBaseCache
+from vs_common.decorator.vs_logger_decorator import vs_logger
+from vs_common.schema.vs_cache_config import VsCacheConfig
+
+
+@vs_logger("VsCacheManager")
+class VsCacheManager:
+
+    _service: Optional[VsBaseCache] = None
+    _lock: threading.RLock = threading.RLock()
+
+    @classmethod
+    def init(cls, config: VsCacheConfig) -> None:
+        if not config.enabled or config.backend == "memory":
+            cls.register(InMemoryCache())
+        elif config.backend == "redis":
+            cls.register(RedisCache(config))
+        else:
+            raise NotImplementedError(
+                f"Cache backend '{config.backend}' is not yet supported. "
+                "Register a service manually via VsCacheManager.register()."
+            )
+
+    @classmethod
+    def register(cls, service: VsBaseCache) -> None:
+        with cls._lock:
+            cls._service = service
+            cls.vs_logger.info(f"VsCacheManager registered: {type(service).__name__}")
+
+    @classmethod
+    def _get_service(cls) -> VsBaseCache:
+        if cls._service is None:
+            with cls._lock:
+                if cls._service is None:
+                    cls._service = InMemoryCache()
+                    cls.vs_logger.info("VsCacheManager defaulting to InMemoryCache")
+        return cls._service
+
+    @classmethod
+    async def get(cls, key: str) -> Optional[Any]:
+        try:
+            return await cls._get_service().get(key)
+        except Exception as e:
+            cls.vs_logger.error(f"Cache GET failed for '{key}': {e}")
+            return None
+
+    @classmethod
+    async def set(cls, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        try:
+            return await cls._get_service().set(key, value, ttl)
+        except Exception as e:
+            cls.vs_logger.error(f"Cache SET failed for '{key}': {e}")
+            return False
+
+    @classmethod
+    async def delete(cls, key: str) -> bool:
+        try:
+            return await cls._get_service().delete(key)
+        except Exception as e:
+            cls.vs_logger.error(f"Cache DELETE failed for '{key}': {e}")
+            return False
+
+    @classmethod
+    async def delete_pattern(cls, pattern: str) -> int:
+        try:
+            return await cls._get_service().delete_pattern(pattern)
+        except Exception as e:
+            cls.vs_logger.error(f"Cache DELETE_PATTERN failed for '{pattern}': {e}")
+            return 0
+
+    @classmethod
+    async def ping(cls) -> bool:
+        try:
+            return await cls._get_service().ping()
+        except Exception as e:
+            cls.vs_logger.error(f"Cache PING failed: {e}")
+            return False

vs_common/config/vs_base_config.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Type
+
+
+class VsBaseConfig(ABC):
+
+    @abstractmethod
+    def get(self, key: str, default: Any = None, data_type: Type = str) -> Any:
+        """
+        Get a configuration value by key.
+
+        Args:
+            key: Dotted key format — "section.key" (e.g. "database.url")
+            default: Value returned if key is not found
+            data_type: Type to cast the value to (str, int, float, bool, list)
+
+        Returns:
+            Configuration value cast to data_type, or default if not found
+        """
+
+    def get_section(self, section: str) -> Dict[str, str]:
+        return {}

vs_common/config/vs_config_loader.py

@@ -0,0 +1,110 @@
+"""
+A Config file loader that is used to load the values from
+a config.ini
+"""
+import configparser
+from pathlib import Path
+from typing import Dict, Optional
+
+
+class VsConfigLoader:
+    """
+    Low-level configuration loader.
+
+    Handles reading config.ini files and accessing environment variables.
+    """
+    def __init__(self, config_path: str = "config.ini"):
+        """
+        Initialize the config loader.
+
+        Args:
+            config_path: Path to config.ini file. Defaults to "config.ini" in current directory.
+        """
+        self.config_path = Path(config_path)
+        self._config_data: Dict[str, Dict[str, str]] = {}
+        self._load_ini_file()
+
+    def _load_ini_file(self) -> None:
+        """
+        Load config.ini file into memory.
+
+        Reads the INI file and stores all sections and keys in _config_data.
+        Does not raise error if file not found - just logs and continues.
+        """
+        if not self.config_path.exists():
+            print(f"Config file not found: {self.config_path}. Will rely on environment variables and defaults.")
+            return
+        try:
+            parser = configparser.ConfigParser()
+            parser.read(self.config_path)
+
+            # Convert to nested dictionary
+            for section in parser.sections():
+                self._config_data[section] = {}
+                for key, value in parser.items(section):
+                    self._config_data[section][key] = value
+
+        except Exception as e:
+            print(f"Warning: Failed to load config file {self.config_path}: {e}")
+
+    def get_value(self, section: str, key: str) -> Optional[str]:
+        """
+        Get value from loaded config.ini data.
+
+        Args:
+            section: Section name from config.ini (e.g., "database")
+            key: Key name within section (e.g., "url")
+
+        Returns:
+            Value as string or None if section/key not found
+        """
+        if section not in self._config_data:
+            return None
+
+        return self._config_data[section].get(key)
+
+    def get_section(self, section: str) -> Dict[str, str]:
+        """
+        Get all key-value pairs from a section.
+
+        Args:
+            section: Section name from config.ini
+
+        Returns:
+            Dictionary of all keys and values in the section, empty dict if not found
+        """
+        return self._config_data.get(section, {}).copy()
+
+    def reload(self) -> None:
+        """
+        Reload config.ini from disk.
+
+        Useful if config file changes during runtime.
+        """
+        self._config_data.clear()
+        self._load_ini_file()
+
+    def has_section(self, section: str) -> bool:
+        """
+        Check if section exists in config.ini.
+
+        Args:
+            section: Section name
+
+        Returns:
+            True if section exists, False otherwise
+        """
+        return section in self._config_data
+
+    def has_key(self, section: str, key: str) -> bool:
+        """
+        Check if key exists in section.
+
+        Args:
+            section: Section name
+            key: Key name
+
+        Returns:
+            True if key exists in section, False otherwise
+        """
+        return section in self._config_data and key in self._config_data[section]

vs_common/config/vs_ini_config.py

@@ -0,0 +1,48 @@
+import os
+from typing import Any, Dict, Type
+
+from vs_common.config.vs_base_config import VsBaseConfig
+from vs_common.config.vs_config_loader import VsConfigLoader
+
+
+class VsIniConfig(VsBaseConfig):
+
+    def __init__(self, config_path: str = "config.ini"):
+        self._loader = VsConfigLoader(config_path)
+
+    def get(self, key: str, default: Any = None, data_type: Type = str) -> Any:
+        section, config_key = self._parse_key(key)
+
+        env_value = os.getenv(key.upper().replace(".", "_"))
+        if env_value is not None:
+            return self._convert(env_value, data_type)
+
+        ini_value = self._loader.get_value(section, config_key)
+        if ini_value is not None:
+            return self._convert(ini_value, data_type)
+
+        return default
+
+    def get_section(self, section: str) -> Dict[str, str]:
+        return self._loader.get_section(section)
+
+    def reload(self) -> None:
+        self._loader.reload()
+
+    def _parse_key(self, key: str):
+        if "." not in key:
+            raise ValueError(f"Invalid key format: '{key}'. Expected 'section.key'.")
+        return key.split(".", 1)
+
+    def _convert(self, value: str, target_type: Type) -> Any:
+        if target_type == str:
+            return value
+        if target_type == int:
+            return int(value)
+        if target_type == float:
+            return float(value)
+        if target_type == bool:
+            return value.lower().strip() in ("true", "1", "yes", "on")
+        if target_type == list:
+            return [item.strip() for item in value.split(",") if item.strip()]
+        raise ValueError(f"Unsupported type: {target_type}")

vs_common/decorator/vs_cache_decorator.py

@@ -0,0 +1,42 @@
+import functools
+from typing import Callable
+
+from vs_common.cache.vs_cache_manager import VsCacheManager
+from vs_common.log.vs_log_manager import VsLogManager
+
+_logger = VsLogManager.get_instance(__name__)
+
+
+def cacheable(key_prefix: str, ttl: int = 3600):
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            cache_key_suffix = ":".join(str(a) for a in args)
+            if kwargs:
+                cache_key_suffix += ":" + ":".join(f"{k}={v}" for k, v in sorted(kwargs.items()))
+            cache_key = f"{key_prefix}:{cache_key_suffix or 'default'}"
+
+            cached_value = await VsCacheManager.get(cache_key)
+            if cached_value is not None:
+                _logger.debug(f"Cache HIT: {cache_key}")
+                return cached_value
+
+            result = await func(self, *args, **kwargs)
+            if result is not None:
+                await VsCacheManager.set(cache_key, result, ttl=ttl)
+            return result
+
+        return wrapper
+    return decorator
+
+
+def cache_evict(key_prefix: str):
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            result = await func(self, *args, **kwargs)
+            await VsCacheManager.delete_pattern(f"{key_prefix}:*")
+            return result
+
+        return wrapper
+    return decorator

vs_common/decorator/vs_logger_decorator.py

@@ -0,0 +1,10 @@
+from typing import Callable, Type
+
+from vs_common.log.vs_log_manager import VsLogManager
+
+
+def vs_logger(name: str) -> Callable[[Type], Type]:
+    def decorator(cls: Type) -> Type:
+        cls.vs_logger = VsLogManager.get_instance(name)
+        return cls
+    return decorator

vs_common/log/vs_log_manager.py

@@ -0,0 +1,160 @@
+import logging
+import logging.handlers
+import sys
+import threading
+from pathlib import Path
+from typing import Optional, Dict
+
+from vs_common.schema.vs_log_config import VsLogConfig
+from vs_common.log.vs_logger import VsLogger
+
+
+class VsLogManager:
+    """
+    Centralized logging manager for Viveka AI (Singleton).
+
+    VivekaLogManager is responsible for:
+    - Initializing logging configuration from ConfigService
+    - Setting up handlers: ConsoleHandler, FileHandler
+    - Providing logger instances to classes via get_instance()
+    - Managing log formatting and levels
+
+    This class implements the Singleton pattern to ensure consistent logging
+    configuration across the entire application.
+
+    Initialization:
+        VivekaLogManager must be initialized once at application startup by calling
+        VivekaLogManager.init(). This reads configuration from ConfigService and sets
+        up all handlers.
+    """
+    _instance: Optional['VsLogManager'] = None
+    _initialized: bool = False
+    _lock: threading.RLock = threading.RLock()
+    _loggers: Dict[str, VsLogger] = {}
+    _config: VsLogConfig = VsLogConfig()
+
+    def __new__(cls):
+        """Singleton implementation."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def init(cls, config: Optional[VsLogConfig] = None) -> None:
+        if cls._initialized:
+            if config is not None:
+                # An explicit config was provided after auto-init (e.g. VivekaApp startup).
+                # Re-apply the level so the app's configured level overrides the
+                # INFO default that get_instance() uses when it auto-initialises.
+                instance = cls()
+                instance._config = config
+                target_level = instance._parse_log_level(config.level or "INFO")
+                root = logging.getLogger()
+                root.setLevel(target_level)
+                for handler in root.handlers:
+                    handler.setLevel(target_level)
+            return
+
+        with cls._lock:
+            if cls._initialized:
+                return
+            instance = cls()
+            instance._config = config or VsLogConfig()
+            instance._setup_logging()
+            cls._initialized = True
+
+    @classmethod
+    def get_instance(cls, name: str) -> VsLogger:
+        if not cls._initialized:
+            config = VsLogConfig()
+            cls.init(config)
+
+        if name in cls._loggers:
+            return cls._loggers[name]
+
+        # Create new logger
+        python_logger = logging.getLogger(name)
+        vs_logger = VsLogger(name, python_logger)
+        cls._loggers[name] = vs_logger
+
+        return vs_logger
+
+
+    def _setup_logging(self) -> None:
+        log_level = self._config.level or "INFO"
+        log_format = self._config.format or "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+        # Configure root logger
+        root_logger = logging.getLogger()
+        root_logger.setLevel(self._parse_log_level(log_level))
+
+        # Clear existing handlers to avoid duplicates
+        root_logger.handlers.clear()
+
+        # Create formatter
+        formatter = logging.Formatter(log_format)
+
+        # Setup console handler
+        if self._config.console_enabled:
+            console_handler = self._create_console_handler(formatter)
+            if console_handler:
+                root_logger.addHandler(console_handler)
+
+        # Setup file handler
+        if self._config.file_enabled:
+            file_handler = self._create_file_handler(formatter)
+            if file_handler:
+                root_logger.addHandler(file_handler)
+
+        # Log initialization message
+        root_logger.info("VivekaLogManager initialized")
+
+    def _create_file_handler(
+            self,
+            formatter: logging.Formatter
+    ) -> Optional[logging.Handler]:
+        try:
+            file_path = self._config.file_path or "logs/viveka.log"
+            file_level = self._config.file_level or self._config.level or "INFO"
+            max_bytes = self._config.file_max_bytes
+            backup_count = self._config.file_backup_count
+
+            # Create log directory if it doesn't exist
+            log_file = Path(file_path)
+            log_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Create rotating file handler
+            handler = logging.handlers.RotatingFileHandler(
+                filename=log_file,
+                maxBytes=max_bytes,
+                backupCount=backup_count,
+                encoding='utf-8'
+            )
+            handler.setLevel(self._parse_log_level(file_level))
+            handler.setFormatter(formatter)
+            return handler
+        except Exception as e:
+            print(f"Failed to create file handler: {e}", file=sys.stderr)
+            return None
+
+
+    def _create_console_handler(
+            self,
+            formatter: logging.Formatter
+    ) -> Optional[logging.Handler]:
+        try:
+            console_level = self._config.console_level or self._config.level or "INFO"
+            handler = logging.StreamHandler(sys.stdout)
+            handler.setLevel(self._parse_log_level(console_level))
+            handler.setFormatter(formatter)
+            return handler
+        except Exception as e:
+            print(f"Failed to create console handler: {e}", file=sys.stderr)
+            return None
+
+    def _parse_log_level(self, level: str) -> int:
+        normalized = "WARNING" if level.upper() == "WARN" else level.upper()
+        numeric = logging.getLevelName(normalized)
+        return numeric if isinstance(numeric, int) else logging.INFO

vs_common/log/vs_logger.py

@@ -0,0 +1,28 @@
+import logging
+from typing import Optional, Dict, Any
+
+
+class VsLogger:
+
+    def __init__(self, name: str, logger: logging.Logger):
+        self.name = name
+        self._logger = logger
+
+    def debug(self, message: str, extra: Optional[Dict[str, Any]] = None) -> None:
+        self._logger.debug(message, extra=extra or {})
+
+    def info(self, message: str, extra: Optional[Dict[str, Any]] = None) -> None:
+        self._logger.info(message, extra=extra or {})
+
+    def warn(self, message: str, extra: Optional[Dict[str, Any]] = None) -> None:
+        self._logger.warning(message, extra=extra or {})
+
+    def warning(self, message: str, extra: Optional[Dict[str, Any]] = None) -> None:
+        self.warn(message, extra=extra)
+
+    def error(self, message: str, extra: Optional[Dict[str, Any]] = None,
+              exc_info: bool = False) -> None:
+        self._logger.error(message, extra=extra or {}, exc_info=exc_info)
+
+    def exception(self, message: str, extra: Optional[Dict[str, Any]] = None) -> None:
+        self._logger.exception(message, extra=extra or {})

vs_common/schema/vs_cache_config.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class VsCacheConfig:
+    enabled: bool = False
+    backend: str = "memory"
+    default_ttl: int = 3600
+    host: str = "localhost"
+    port: int = 6379
+    db: int = 0
+    password: Optional[str] = None