sherlock-ai 1.0.0__tar.gz

sherlock_ai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pranaw Mishra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sherlock_ai-1.0.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: sherlock-ai
+Version: 1.0.0
+Summary: A Python package for performance monitoring and logging utilities
+Author-email: Pranaw Mishra <pranawmishra73@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pranawmishra/sherlock-ai.git
+Project-URL: Repository, https://github.com/pranawmishra/sherlock-ai.git
+Keywords: performance,monitoring,logging,debugging,profiling
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Sherlock AI
+
+A Python package for performance monitoring and logging utilities that helps you track execution times and debug your applications with ease.
+
+## Features
+
+- 🎯 **Performance Decorators**: Easy-to-use decorators for tracking function execution times
+- ⏱️ **Context Managers**: Monitor code block execution with simple context managers
+- 🔧 **Flexible Configuration**: Customizable logging levels, minimum duration thresholds, and argument logging
+- 🔄 **Async/Sync Support**: Works seamlessly with both synchronous and asynchronous functions
+- 📊 **Request Tracking**: Built-in request ID tracking for distributed systems
+- 🚀 **Zero Dependencies**: Lightweight with minimal external dependencies
+
+## Installation
+
+```bash
+pip install sherlock-ai
+```
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging
+from sherlock_ai.performance import log_performance
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+@log_performance
+def my_function():
+    # Your code here
+    time.sleep(1)
+    return "result"
+
+# This will log: PERFORMANCE | my_module.my_function | SUCCESS | 1.003s
+result = my_function()
+```
+
+### Advanced Configuration
+
+```python
+@log_performance(min_duration=0.1, include_args=True, log_level="DEBUG")
+def slow_database_query(user_id, limit=10):
+    # Only logs if execution time >= 0.1 seconds
+    # Includes function arguments in the log
+    pass
+```
+
+### Context Manager for Code Blocks
+
+```python
+from sherlock_ai.performance import PerformanceTimer
+
+with PerformanceTimer("database_operation"):
+    # Your code block here
+    result = database.query("SELECT * FROM users")
+    
+# Logs: PERFORMANCE | database_operation | SUCCESS | 0.234s
+```
+
+### Async Function Support
+
+```python
+@log_performance
+async def async_api_call():
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://api.example.com")
+        return response.json()
+
+# Works automatically with async functions
+result = await async_api_call()
+```
+
+### Manual Time Logging
+
+```python
+from sherlock_ai.performance import log_execution_time
+import time
+
+start_time = time.time()
+try:
+    # Your code here
+    result = complex_operation()
+    log_execution_time("complex_operation", start_time, success=True)
+except Exception as e:
+    log_execution_time("complex_operation", start_time, success=False, error=str(e))
+```
+
+## API Reference
+
+### `@log_performance` Decorator
+
+Parameters:
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+- `include_args` (bool): Whether to include function arguments in the log (default: False)
+- `log_level` (str): Log level to use - INFO, DEBUG, WARNING, etc. (default: "INFO")
+
+### `PerformanceTimer` Context Manager
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+
+### `log_execution_time` Function
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `start_time` (float): Start time from `time.time()`
+- `success` (bool): Whether the operation succeeded (default: True)
+- `error` (str): Error message if operation failed (default: None)
+
+## Configuration
+
+### Logging Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+# Get a logger for your module
+logger = get_logger(__name__)
+
+# Use the logger
+logger.info("Application started")
+logger.error("Something went wrong")
+```
+
+**Log Files Created:**
+When you call `setup_logging()`, it automatically creates a `logs/` directory with these files:
+- `app.log` - All INFO+ level logs
+- `errors.log` - Only ERROR+ level logs  
+- `api.log` - API-related logs
+- `database.log` - Database operation logs
+- `services.log` - Service operation logs
+- `performance.log` - Performance monitoring logs
+
+### Request ID Tracking
+
+```python
+from sherlock_ai.utils.helper import get_request_id
+
+# Get current request ID for distributed tracing
+request_id = get_request_id()
+```
+
+### Complete Application Example
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+from sherlock_ai.performance import log_performance, PerformanceTimer
+
+# Initialize logging first
+setup_logging()
+logger = get_logger(__name__)
+
+@log_performance
+def main():
+    logger.info("Application starting")
+    
+    with PerformanceTimer("initialization"):
+        # Your initialization code
+        pass
+    
+    logger.info("Application ready")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Log Output Format
+
+The package produces structured log messages in the following format:
+
+```
+PERFORMANCE | {function_name} | {STATUS} | {execution_time}s | {additional_info}
+```
+
+Examples:
+```
+PERFORMANCE | my_module.my_function | SUCCESS | 0.123s
+PERFORMANCE | api_call | ERROR | 2.456s | Connection timeout
+PERFORMANCE | database_query | SUCCESS | 0.089s | Args: ('user123',) | Kwargs: {'limit': 10}
+```
+
+## Use Cases
+
+- **API Performance Monitoring**: Track response times for your web APIs
+- **Database Query Optimization**: Monitor slow database operations
+- **Microservices Debugging**: Trace execution times across service boundaries
+- **Algorithm Benchmarking**: Compare performance of different implementations
+- **Production Monitoring**: Get insights into your application's performance characteristics
+
+## Requirements
+
+- Python >= 3.13
+- Standard library only (no external dependencies)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- **Homepage**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Repository**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Issues**: [https://github.com/pranawmishra/sherlock-ai/issues](https://github.com/pranawmishra/sherlock-ai/issues)

sherlock_ai-1.0.0/README.md

@@ -0,0 +1,214 @@
+# Sherlock AI
+
+A Python package for performance monitoring and logging utilities that helps you track execution times and debug your applications with ease.
+
+## Features
+
+- 🎯 **Performance Decorators**: Easy-to-use decorators for tracking function execution times
+- ⏱️ **Context Managers**: Monitor code block execution with simple context managers
+- 🔧 **Flexible Configuration**: Customizable logging levels, minimum duration thresholds, and argument logging
+- 🔄 **Async/Sync Support**: Works seamlessly with both synchronous and asynchronous functions
+- 📊 **Request Tracking**: Built-in request ID tracking for distributed systems
+- 🚀 **Zero Dependencies**: Lightweight with minimal external dependencies
+
+## Installation
+
+```bash
+pip install sherlock-ai
+```
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging
+from sherlock_ai.performance import log_performance
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+@log_performance
+def my_function():
+    # Your code here
+    time.sleep(1)
+    return "result"
+
+# This will log: PERFORMANCE | my_module.my_function | SUCCESS | 1.003s
+result = my_function()
+```
+
+### Advanced Configuration
+
+```python
+@log_performance(min_duration=0.1, include_args=True, log_level="DEBUG")
+def slow_database_query(user_id, limit=10):
+    # Only logs if execution time >= 0.1 seconds
+    # Includes function arguments in the log
+    pass
+```
+
+### Context Manager for Code Blocks
+
+```python
+from sherlock_ai.performance import PerformanceTimer
+
+with PerformanceTimer("database_operation"):
+    # Your code block here
+    result = database.query("SELECT * FROM users")
+    
+# Logs: PERFORMANCE | database_operation | SUCCESS | 0.234s
+```
+
+### Async Function Support
+
+```python
+@log_performance
+async def async_api_call():
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://api.example.com")
+        return response.json()
+
+# Works automatically with async functions
+result = await async_api_call()
+```
+
+### Manual Time Logging
+
+```python
+from sherlock_ai.performance import log_execution_time
+import time
+
+start_time = time.time()
+try:
+    # Your code here
+    result = complex_operation()
+    log_execution_time("complex_operation", start_time, success=True)
+except Exception as e:
+    log_execution_time("complex_operation", start_time, success=False, error=str(e))
+```
+
+## API Reference
+
+### `@log_performance` Decorator
+
+Parameters:
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+- `include_args` (bool): Whether to include function arguments in the log (default: False)
+- `log_level` (str): Log level to use - INFO, DEBUG, WARNING, etc. (default: "INFO")
+
+### `PerformanceTimer` Context Manager
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+
+### `log_execution_time` Function
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `start_time` (float): Start time from `time.time()`
+- `success` (bool): Whether the operation succeeded (default: True)
+- `error` (str): Error message if operation failed (default: None)
+
+## Configuration
+
+### Logging Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+# Get a logger for your module
+logger = get_logger(__name__)
+
+# Use the logger
+logger.info("Application started")
+logger.error("Something went wrong")
+```
+
+**Log Files Created:**
+When you call `setup_logging()`, it automatically creates a `logs/` directory with these files:
+- `app.log` - All INFO+ level logs
+- `errors.log` - Only ERROR+ level logs  
+- `api.log` - API-related logs
+- `database.log` - Database operation logs
+- `services.log` - Service operation logs
+- `performance.log` - Performance monitoring logs
+
+### Request ID Tracking
+
+```python
+from sherlock_ai.utils.helper import get_request_id
+
+# Get current request ID for distributed tracing
+request_id = get_request_id()
+```
+
+### Complete Application Example
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+from sherlock_ai.performance import log_performance, PerformanceTimer
+
+# Initialize logging first
+setup_logging()
+logger = get_logger(__name__)
+
+@log_performance
+def main():
+    logger.info("Application starting")
+    
+    with PerformanceTimer("initialization"):
+        # Your initialization code
+        pass
+    
+    logger.info("Application ready")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Log Output Format
+
+The package produces structured log messages in the following format:
+
+```
+PERFORMANCE | {function_name} | {STATUS} | {execution_time}s | {additional_info}
+```
+
+Examples:
+```
+PERFORMANCE | my_module.my_function | SUCCESS | 0.123s
+PERFORMANCE | api_call | ERROR | 2.456s | Connection timeout
+PERFORMANCE | database_query | SUCCESS | 0.089s | Args: ('user123',) | Kwargs: {'limit': 10}
+```
+
+## Use Cases
+
+- **API Performance Monitoring**: Track response times for your web APIs
+- **Database Query Optimization**: Monitor slow database operations
+- **Microservices Debugging**: Trace execution times across service boundaries
+- **Algorithm Benchmarking**: Compare performance of different implementations
+- **Production Monitoring**: Get insights into your application's performance characteristics
+
+## Requirements
+
+- Python >= 3.13
+- Standard library only (no external dependencies)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- **Homepage**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Repository**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Issues**: [https://github.com/pranawmishra/sherlock-ai/issues](https://github.com/pranawmishra/sherlock-ai/issues)

sherlock_ai-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sherlock-ai"
+version = "1.0.0"
+description = "A Python package for performance monitoring and logging utilities"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [{name = "Pranaw Mishra", email = "pranawmishra73@gmail.com"}]
+keywords = ["performance", "monitoring", "logging", "debugging", "profiling"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/pranawmishra/sherlock-ai.git"
+Repository = "https://github.com/pranawmishra/sherlock-ai.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sherlock_ai-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sherlock_ai-1.0.0/src/sherlock_ai/__init__.py

@@ -0,0 +1,19 @@
+"""
+Sherlock AI - Your AI assistant package
+"""
+
+__version__ = "1.0.0"
+__author__ = "Pranaw Mishra"
+__email__ = "pranawmishra73@gmail.com"
+
+# Import main components for easy access
+from .performance import log_performance, PerformanceTimer
+from .logging_config import setup_logging, get_logger
+
+__all__ = [
+    "log_performance", 
+    "PerformanceTimer",
+    "setup_logging",
+    "get_logger",
+    "__version__"
+]

sherlock_ai-1.0.0/src/sherlock_ai/logging_config.py

@@ -0,0 +1,142 @@
+# app > core > logging_config.py
+import logging
+import logging.handlers
+from pathlib import Path
+from sherlock_ai.utils.helper import request_id_var
+
+class RequestIdFormatter(logging.Formatter):
+    """Custom formatter that includes request ID in log messages"""
+
+    def format(self, record):
+        """Add request ID to log message"""
+        # get current request ID from context
+        record.request_id = request_id_var.get("") or "-"
+        return super().format(record)
+
+
+def setup_logging():
+    """Set up logging configuration for the application with request ID support"""
+
+    # Create logs directory if it doesn't exist
+    logs_dir = Path("logs")
+    logs_dir.mkdir(exist_ok=True)
+
+    # Configure logging format
+    log_format = "%(asctime)s - %(request_id)s - %(name)s - %(levelname)s - %(message)s"
+    date_format = "%Y-%m-%d %H:%M:%S"
+
+    # Create custom formatter with request ID support
+    formatter = RequestIdFormatter(log_format, datefmt=date_format)
+
+    # Clear existing handlers to avoid duplicates
+    logging.root.handlers.clear()
+
+    # 1. Console Handler - prints to terminal
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(formatter)
+
+    # 2. Main App Log - all logs INFO and above
+    app_handler = logging.handlers.RotatingFileHandler(
+        "logs/app.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    app_handler.setLevel(logging.INFO)
+    app_handler.setFormatter(formatter)
+
+    # 3. Error Log - only ERROR and CRITICAL logs
+    error_handler = logging.handlers.RotatingFileHandler(
+        "logs/errors.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    error_handler.setLevel(logging.ERROR)
+    error_handler.setFormatter(formatter)
+
+    # 4. API Log - specifically for API-related logs
+    api_handler = logging.handlers.RotatingFileHandler(
+        "logs/api.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    api_handler.setLevel(logging.INFO)
+    api_handler.setFormatter(formatter)
+
+    # 5. Database Log - specifically for database operations
+    db_handler = logging.handlers.RotatingFileHandler(
+        "logs/database.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    db_handler.setLevel(logging.INFO)
+    db_handler.setFormatter(formatter)
+
+    # 6. Services Log - for all service-related operations
+    services_handler = logging.handlers.RotatingFileHandler(
+        "logs/services.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    services_handler.setLevel(logging.INFO)
+    services_handler.setFormatter(formatter)
+
+    # 7. Performance Log - specifically for performance metrics
+    performance_handler = logging.handlers.RotatingFileHandler(
+        "logs/performance.log",
+        maxBytes=10*1024*1024,  # 10MB
+        backupCount=5,
+        encoding="utf-8"
+    )
+    performance_handler.setLevel(logging.INFO)
+    performance_handler.setFormatter(formatter)
+
+    # Configure root logger with console, main app, and error handlers
+    logging.root.setLevel(logging.INFO)
+    logging.root.addHandler(console_handler)
+    logging.root.addHandler(app_handler)
+    logging.root.addHandler(error_handler)
+
+    # Configure specific loggers for different components
+    # API loggers - all API modules will log to api.log
+    api_logger = logging.getLogger("app.api")
+    api_logger.setLevel(logging.INFO)
+    api_logger.addHandler(api_handler)
+
+    # Database loggers - all database operations will log to database.log
+    db_logger = logging.getLogger("app.core.dbConnection")
+    db_logger.setLevel(logging.INFO)
+    db_logger.addHandler(db_handler)
+
+    # Services loggers - all services will log to services.log
+    services_logger = logging.getLogger("app.services")
+    services_logger.setLevel(logging.INFO)
+    services_logger.addHandler(services_handler)
+
+    # Performance loggers - all performance metrics will log to performance.log
+    performance_logger = logging.getLogger("PerformanceLogger")
+    performance_logger.setLevel(logging.INFO)
+    performance_logger.addHandler(performance_handler)
+
+    # Set specific log levels for external libraries
+    logging.getLogger("uvicorn").setLevel(logging.INFO)
+    logging.getLogger("fastapi").setLevel(logging.INFO)
+
+    # Prevent duplicate logs (don't propagate to parent if already handled)
+    api_logger.propagate = True  # Still propagate to get in main app.log
+    db_logger.propagate = True
+    services_logger.propagate = True
+    performance_logger.propagate = False
+
+# Helper function to get logger (optional, but clean)
+def get_logger(name: str = None):
+    """Get a logger. If no name provided, uses the caller's __name__."""
+    return logging.getLogger(name) if name else logging.getLogger(__name__)
+
+
+# setup_logging()

sherlock_ai-1.0.0/src/sherlock_ai/performance.py

@@ -0,0 +1,166 @@
+# app > utils > performance.py
+import time
+import functools
+import asyncio
+import logging
+from typing import Any, Callable, TypeVar, Union
+from sherlock_ai.utils.helper import get_request_id
+
+# Create a logger specifically for performance metrics
+logger = logging.getLogger("PerformanceLogger")
+
+# Type variable for better type hints
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def log_performance(
+    func: F = None,
+    *,
+    min_duration: float = 0.0,
+    include_args: bool = False,
+    log_level: str = "INFO"
+) -> Union[F, Callable[[F], F]]:
+    """
+    Decorator to log function execution time
+
+    Args:
+        func: The function to decorate (when used without parentheses)
+        min_duration: Only log if execution time >= this value (in seconds)
+        include_args: Whether to include function arguments in the log
+        log_level: Log level to use (INFO, DEBUG, WARNING, etc.)
+
+    Usage:
+        @log_performance
+        def my_function():
+            pass
+
+        @log_performance(min_duration=0.1, include_args=True)
+        def slow_function(param1, param2):
+            pass
+    """
+    def decorator(f: F) -> F:
+        @functools.wraps(f)
+        async def async_wrapper(*args, **kwargs):
+            start_time = time.time()
+            function_name = f"{f.__module__}.{f.__name__}"
+            request_id = get_request_id()
+
+            # Log function arguments if requested
+            args_info = ""
+            if include_args:
+                args_str = str(args)[:100] if args else ""
+                kwargs_str = str(kwargs)[:100] if kwargs else ""
+                args_info = f" | Args: {args_str} | Kwargs: {kwargs_str}"
+
+            try:
+                # Execute the async function
+                result = await f(*args, **kwargs)
+                execution_time = time.time() - start_time
+
+                # Only log if execution time meets minimum threshold
+                if execution_time >= min_duration:
+                    log_method = getattr(logger, log_level.lower())
+                    log_method(
+                        f"PERFORMANCE | {function_name} | SUCCESS | {execution_time:.3f}s{args_info}"
+                    )
+                return result
+
+            except Exception as e:
+                execution_time = time.time() - start_time
+                logger.error(
+                    f"PERFORMANCE | {function_name} | ERROR | {execution_time:.3f}s | {str(e)}{args_info}"
+                )
+                raise
+
+        @functools.wraps(f)
+        def sync_wrapper(*args, **kwargs):
+            start_time = time.time()
+            function_name = f"{f.__module__}.{f.__name__}"
+            request_id = get_request_id()
+
+            # Log function arguments if requested
+            args_info = ""
+            if include_args:
+                args_str = str(args)[:100] if args else ""
+                kwargs_str = str(kwargs)[:100] if kwargs else ""
+                args_info = f" | Args: {args_str} | Kwargs: {kwargs_str}"
+
+            try:
+                # Execute the sync function
+                result = f(*args, **kwargs)
+                execution_time = time.time() - start_time
+
+                # Only log if execution time meets minimum threshold
+                if execution_time >= min_duration:
+                    log_method = getattr(logger, log_level.lower())
+                    log_method(
+                        f"PERFORMANCE | {function_name} | SUCCESS | {execution_time:.3f}s{args_info}"
+                    )
+                return result
+
+            except Exception as e:
+                execution_time = time.time() - start_time
+                logger.error(
+                    f"PERFORMANCE | {function_name} | ERROR | {execution_time:.3f}s | {str(e)}{args_info}"
+                )
+                raise
+
+        # Return the appropriate wrapper based on function type
+        return async_wrapper if asyncio.iscoroutinefunction(f) else sync_wrapper
+
+    # Handle both @log_performance and @log_performance(...) usage
+    if func is None:
+        return decorator
+    else:
+        return decorator(func)
+
+
+def log_execution_time(name: str, start_time: float, success: bool = True, error: str = None):
+    """
+    Manual function to log execution time for code blocks
+
+    Usage:
+        start_time = time.time()
+        try:
+            # Your code here
+            log_execution_time("database_query", start_time, success=True)
+        except Exception as e:
+            log_execution_time("database_query", start_time, success=False, error=str(e))
+    """
+    execution_time = time.time() - start_time
+    status = "SUCCESS" if success else "ERROR"
+    error_info = f" | {error}" if error else ""
+
+    if success:
+        logger.info(f"PERFORMANCE | {name} | {status} | {execution_time:.3f}s{error_info}")
+    else:
+        logger.error(f"PERFORMANCE | {name} | {status} | {execution_time:.3f}s{error_info}")
+
+
+# Context manager for measuring code blocks
+class PerformanceTimer:
+    """
+    Context manager for measuring execution time of code blocks
+
+    Usage:
+        with PerformanceTimer("database_operation"):
+            # Your code here
+            pass
+    """
+    def __init__(self, name: str, min_duration: float = 0.0):
+        self.name = name
+        self.min_duration = min_duration
+        self.start_time = None
+
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        execution_time = time.time() - self.start_time
+        if execution_time >= self.min_duration:
+            if exc_type is None:
+                logger.info(f"PERFORMANCE | {self.name} | SUCCESS | {execution_time:.3f}s")
+            else:
+                logger.error(f"PERFORMANCE | {self.name} | ERROR | {execution_time:.3f}s | {str(exc_val)}")
+        return False  # Don’t suppress exceptions

sherlock_ai-1.0.0/src/sherlock_ai/utils/helper.py

@@ -0,0 +1,27 @@
+from contextvars import ContextVar
+import uuid
+
+request_id_var: ContextVar[str] = ContextVar("request_id", default="")
+
+def set_request_id(req_id: str = None) -> str:
+    """
+    Set request ID for current context
+    Args:
+        req_id: Optional request ID. If None, generates a new one
+    Returns:
+        The request ID that was set
+    """
+    if req_id is None:
+        req_id = str(uuid.uuid4())[:8]  # Use first 8 chars of UUID
+    request_id_var.set(req_id)
+    return req_id
+
+
+def get_request_id() -> str:
+    """Get current request ID from context"""
+    return request_id_var.get("")
+
+
+def clear_request_id():
+    """Clear the current request ID"""
+    request_id_var.set("")

sherlock_ai-1.0.0/src/sherlock_ai.egg-info/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: sherlock-ai
+Version: 1.0.0
+Summary: A Python package for performance monitoring and logging utilities
+Author-email: Pranaw Mishra <pranawmishra73@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pranawmishra/sherlock-ai.git
+Project-URL: Repository, https://github.com/pranawmishra/sherlock-ai.git
+Keywords: performance,monitoring,logging,debugging,profiling
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Sherlock AI
+
+A Python package for performance monitoring and logging utilities that helps you track execution times and debug your applications with ease.
+
+## Features
+
+- 🎯 **Performance Decorators**: Easy-to-use decorators for tracking function execution times
+- ⏱️ **Context Managers**: Monitor code block execution with simple context managers
+- 🔧 **Flexible Configuration**: Customizable logging levels, minimum duration thresholds, and argument logging
+- 🔄 **Async/Sync Support**: Works seamlessly with both synchronous and asynchronous functions
+- 📊 **Request Tracking**: Built-in request ID tracking for distributed systems
+- 🚀 **Zero Dependencies**: Lightweight with minimal external dependencies
+
+## Installation
+
+```bash
+pip install sherlock-ai
+```
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging
+from sherlock_ai.performance import log_performance
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+@log_performance
+def my_function():
+    # Your code here
+    time.sleep(1)
+    return "result"
+
+# This will log: PERFORMANCE | my_module.my_function | SUCCESS | 1.003s
+result = my_function()
+```
+
+### Advanced Configuration
+
+```python
+@log_performance(min_duration=0.1, include_args=True, log_level="DEBUG")
+def slow_database_query(user_id, limit=10):
+    # Only logs if execution time >= 0.1 seconds
+    # Includes function arguments in the log
+    pass
+```
+
+### Context Manager for Code Blocks
+
+```python
+from sherlock_ai.performance import PerformanceTimer
+
+with PerformanceTimer("database_operation"):
+    # Your code block here
+    result = database.query("SELECT * FROM users")
+    
+# Logs: PERFORMANCE | database_operation | SUCCESS | 0.234s
+```
+
+### Async Function Support
+
+```python
+@log_performance
+async def async_api_call():
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://api.example.com")
+        return response.json()
+
+# Works automatically with async functions
+result = await async_api_call()
+```
+
+### Manual Time Logging
+
+```python
+from sherlock_ai.performance import log_execution_time
+import time
+
+start_time = time.time()
+try:
+    # Your code here
+    result = complex_operation()
+    log_execution_time("complex_operation", start_time, success=True)
+except Exception as e:
+    log_execution_time("complex_operation", start_time, success=False, error=str(e))
+```
+
+## API Reference
+
+### `@log_performance` Decorator
+
+Parameters:
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+- `include_args` (bool): Whether to include function arguments in the log (default: False)
+- `log_level` (str): Log level to use - INFO, DEBUG, WARNING, etc. (default: "INFO")
+
+### `PerformanceTimer` Context Manager
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `min_duration` (float): Only log if execution time >= this value in seconds (default: 0.0)
+
+### `log_execution_time` Function
+
+Parameters:
+- `name` (str): Name identifier for the operation
+- `start_time` (float): Start time from `time.time()`
+- `success` (bool): Whether the operation succeeded (default: True)
+- `error` (str): Error message if operation failed (default: None)
+
+## Configuration
+
+### Logging Setup
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+
+# Initialize logging (call once at application startup)
+setup_logging()
+
+# Get a logger for your module
+logger = get_logger(__name__)
+
+# Use the logger
+logger.info("Application started")
+logger.error("Something went wrong")
+```
+
+**Log Files Created:**
+When you call `setup_logging()`, it automatically creates a `logs/` directory with these files:
+- `app.log` - All INFO+ level logs
+- `errors.log` - Only ERROR+ level logs  
+- `api.log` - API-related logs
+- `database.log` - Database operation logs
+- `services.log` - Service operation logs
+- `performance.log` - Performance monitoring logs
+
+### Request ID Tracking
+
+```python
+from sherlock_ai.utils.helper import get_request_id
+
+# Get current request ID for distributed tracing
+request_id = get_request_id()
+```
+
+### Complete Application Example
+
+```python
+from sherlock_ai.logging_config import setup_logging, get_logger
+from sherlock_ai.performance import log_performance, PerformanceTimer
+
+# Initialize logging first
+setup_logging()
+logger = get_logger(__name__)
+
+@log_performance
+def main():
+    logger.info("Application starting")
+    
+    with PerformanceTimer("initialization"):
+        # Your initialization code
+        pass
+    
+    logger.info("Application ready")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Log Output Format
+
+The package produces structured log messages in the following format:
+
+```
+PERFORMANCE | {function_name} | {STATUS} | {execution_time}s | {additional_info}
+```
+
+Examples:
+```
+PERFORMANCE | my_module.my_function | SUCCESS | 0.123s
+PERFORMANCE | api_call | ERROR | 2.456s | Connection timeout
+PERFORMANCE | database_query | SUCCESS | 0.089s | Args: ('user123',) | Kwargs: {'limit': 10}
+```
+
+## Use Cases
+
+- **API Performance Monitoring**: Track response times for your web APIs
+- **Database Query Optimization**: Monitor slow database operations
+- **Microservices Debugging**: Trace execution times across service boundaries
+- **Algorithm Benchmarking**: Compare performance of different implementations
+- **Production Monitoring**: Get insights into your application's performance characteristics
+
+## Requirements
+
+- Python >= 3.13
+- Standard library only (no external dependencies)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- **Homepage**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Repository**: [https://github.com/pranawmishra/sherlock-ai](https://github.com/pranawmishra/sherlock-ai)
+- **Issues**: [https://github.com/pranawmishra/sherlock-ai/issues](https://github.com/pranawmishra/sherlock-ai/issues)

sherlock_ai-1.0.0/src/sherlock_ai.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/sherlock_ai/__init__.py
+src/sherlock_ai/logging_config.py
+src/sherlock_ai/performance.py
+src/sherlock_ai.egg-info/PKG-INFO
+src/sherlock_ai.egg-info/SOURCES.txt
+src/sherlock_ai.egg-info/dependency_links.txt
+src/sherlock_ai.egg-info/top_level.txt
+src/sherlock_ai/utils/__init__.py
+src/sherlock_ai/utils/helper.py
+tests/test_local.py

sherlock_ai-1.0.0/src/sherlock_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sherlock_ai-1.0.0/src/sherlock_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+sherlock_ai

sherlock_ai-1.0.0/tests/test_local.py

@@ -0,0 +1,89 @@
+# test_local.py
+import time
+import asyncio
+from sherlock_ai.performance import log_performance, PerformanceTimer, log_execution_time
+from sherlock_ai.logging_config import setup_logging, get_logger
+
+setup_logging()
+
+logger = get_logger(__name__)
+
+# Test 1: Basic decorator
+@log_performance
+def test_sync_function():
+    """Test synchronous function"""
+    time.sleep(0.1)
+    return "sync result"
+
+
+# Test 2: Decorator with options
+@log_performance(min_duration=0.05, include_args=True, log_level="DEBUG")
+def test_function_with_args(name, count=5):
+    """Test function with arguments"""
+    time.sleep(0.1)
+    return f"Processed {count} items for {name}"
+
+
+# Test 3: Async function
+@log_performance
+async def test_async_function():
+    """Test asynchronous function"""
+    await asyncio.sleep(0.1)
+    return "async result"
+
+
+# Test 4: Context manager
+def test_context_manager():
+    """Test PerformanceTimer context manager"""
+    with PerformanceTimer("test_operation"):
+        time.sleep(0.1)
+        print("Operation completed")
+
+
+# Test 5: Manual logging
+def test_manual_logging():
+    """Test manual execution time logging"""
+    start_time = time.time()
+    try:
+        time.sleep(0.1)
+        log_execution_time("manual_test", start_time, success=True)
+    except Exception as e:
+        log_execution_time("manual_test", start_time, success=False, error=str(e))
+
+
+async def test_main():
+    """Run all tests"""
+    logger.info("🧪 Testing sherlock-ai package locally...")
+    logger.info("=" * 50)
+    
+    # Test imports
+    logger.info("✅ Import test passed")
+    
+    # Test sync function
+    logger.info("\n🔄 Testing sync function...")
+    result1 = test_sync_function()
+    logger.info(f"Result: {result1}")
+    
+    # Test function with args
+    logger.info("\n🔄 Testing function with arguments...")
+    result2 = test_function_with_args("Alice", count=10)
+    logger.info(f"Result: {result2}")
+    
+    # Test async function
+    logger.info("\n🔄 Testing async function...")
+    result3 = await test_async_function()
+    logger.info(f"Result: {result3}")
+    
+    # Test context manager
+    # logger.info("\n🔄 Testing context manager...")
+    # test_context_manager()
+    
+    # Test manual logging
+    # logger.info("\n🔄 Testing manual logging...")
+    # test_manual_logging()
+    
+    logger.info("\n✅ All tests completed!")
+
+
+if __name__ == "__main__":
+    asyncio.run(test_main())