neuroglia-python 0.8.0__tar.gz → 0.9.0__tar.gz

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuroglia-python
-Version: 0.8.0
+Version: 0.9.0
 Summary: Port from .NET to Python of the Neuroglia Framework
 License: Apache
 License-File: LICENSE

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "neuroglia-python"
-version = "0.8.0"
+version = "0.9.0"
 description = "Port from .NET to Python of the Neuroglia Framework"
 authors = ["Charles d'Avernas <charles.davernas@neuroglia.io>", "Bruno van de Werve <bvandewe@gmail.com>"]
 license = "Apache"

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/src/neuroglia/__init__.py

@@ -32,18 +32,18 @@ __all__ = [
     "Entity",
     "DomainEvent",
     "Repository",
-    # Agent module (new in 0.8.0)
+    # Agent module
     "BaseAgentState",
     "TeamMembership",
     "KnowledgeScope",
     "AgentCapability",
-    # A2A protocol (new in 0.8.0)
+    # A2A protocol
     "TaskRequest",
     "TaskResponse",
     "AgentIdentity",
     "TaskPriority",
     "TaskStatus",
-    # Conversation building blocks (new in 0.8.0)
+    # Conversation building blocks
     "Message",
     "MessageRole",
     "ToolCall",
@@ -80,7 +80,7 @@ __all__ = [
 ]
 
 # Framework metadata
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 __author__ = "Neuroglia Team"
 __email__ = "team@neuroglia.io"
 __license__ = "Apache"
@@ -159,7 +159,7 @@ def __getattr__(name: str):
         except ImportError:
             pass
 
-    # Agent module (new in 0.8.0)
+    # Agent module
     elif name in ["BaseAgentState", "TeamMembership", "KnowledgeScope", "AgentCapability"]:
         try:
             from .data.agent import (
@@ -180,7 +180,7 @@ def __getattr__(name: str):
         except ImportError:
             pass
 
-    # A2A protocol (new in 0.8.0)
+    # A2A protocol
     elif name in ["TaskRequest", "TaskResponse", "AgentIdentity", "TaskPriority", "TaskStatus"]:
         try:
             from .a2a import (
@@ -204,7 +204,7 @@ def __getattr__(name: str):
         except ImportError:
             pass
 
-    # Conversation building blocks (new in 0.8.0)
+    # Conversation building blocks
     elif name in ["Message", "MessageRole", "ToolCall", "ToolResult", "ExecutionContext", "Session"]:
         try:
             from .data.conversation import (

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/src/neuroglia/dependency_injection/service_provider.py

@@ -375,7 +375,7 @@ class ServiceScope(ServiceScopeBase, ServiceProviderBase):
             try:
                 service = self._build_service(descriptor)
                 transient_services.append(service)
-            except Exception as ex:
+            except Exception:
                 # If building fails, skip this service
                 pass
 
@@ -572,6 +572,10 @@ class ServiceProvider(ServiceProviderBase):
         return result_services
 
     def _is_service_instance_of(self, service: Any, type_: type) -> bool:
+        # Handle None or invalid types (e.g., inspect._empty from untyped factories)
+        if type_ is None or not isinstance(type_, type) and not hasattr(type_, "__origin__"):
+            # Cannot determine type - fall back to checking if service exists
+            return service is not None
         if hasattr(type_, "__origin__"):
             service_type = service.__orig_class__ if hasattr(service, "__orig_class__") else type(service)
             service_generic_arguments = TypeExtensions.get_generic_arguments(service_type)
@@ -750,17 +754,25 @@ class ServiceDescriptor:
     lifetime: ServiceLifetime = ServiceLifetime.SINGLETON
     """ Gets the service's lifetime. Defaults to 'SINGLETON' """
 
-    def get_implementation_type(self) -> type:
-        """Gets the service's implementation type"""
+    def get_implementation_type(self) -> type | None:
+        """Gets the service's implementation type.
+
+        Returns:
+            The implementation type, or None if it cannot be determined
+            (e.g., untyped lambda factories).
+        """
         if self.implementation_type is not None:
             return self.implementation_type
-        return_type = inspect.signature(self.implementation_factory).return_annotation if self.implementation_factory != None else None
-        if return_type is None and self.implementation_factory != None:
-            if self.implementation_type is None:
-                raise Exception(f"Failed to determine the return type of the implementation factory configured for service of type '{self.service_type.__name__}'. Either specify the implementation type, or use a function instead of a lambda as factory callable.")
-            else:
-                return_type = self.implementation_type
-        return type(self.singleton) if self.singleton is not None else inspect.signature(self.implementation_factory).return_annotation
+        if self.singleton is not None:
+            return type(self.singleton)
+        if self.implementation_factory is not None:
+            return_annotation = inspect.signature(self.implementation_factory).return_annotation
+            # Handle missing annotations (inspect._empty) or string annotations
+            if return_annotation is not inspect.Parameter.empty and isinstance(return_annotation, type):
+                return return_annotation
+            # For string annotations or forward references, return None
+            # The caller should handle this gracefully
+        return None
 
 
 # ServiceCollection will be defined at the end of this file

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/src/neuroglia/observability/__init__.py

@@ -44,7 +44,24 @@ Usage:
         pass
 """
 
+# Metrics Decorators (CR-3)
+from neuroglia.observability.decorators import (
+    track_latency,
+    track_operation,
+    track_operation_and_latency,
+)
 from neuroglia.observability.framework import Observability
+
+# Health Check Providers (CR-2)
+from neuroglia.observability.health_checks import (
+    HealthCheckProvider,
+    HealthCheckResult,
+    HttpServiceHealthCheck,
+    MongoDBHealthCheck,
+    Neo4jHealthCheck,
+    QdrantHealthCheck,
+    RedisHealthCheck,
+)
 from neuroglia.observability.logging import (
     configure_logging,
     get_logger_with_trace_context,
@@ -80,6 +97,19 @@ from neuroglia.observability.tracing import (
     trace_sync,
 )
 
+# Structlog Integration (CR-1) - Optional
+try:
+    from neuroglia.observability.structlog_integration import (
+        bind_contextvars,
+        clear_contextvars,
+        configure_structlog,
+        get_structlog_logger,
+    )
+
+    _STRUCTLOG_AVAILABLE = True
+except ImportError:
+    _STRUCTLOG_AVAILABLE = False
+
 __all__ = [
     # New Framework-Style Configuration
     "Observability",
@@ -112,4 +142,27 @@ __all__ = [
     # Prometheus and HTTP Instrumentation
     "instrument_fastapi_app",
     "add_metrics_endpoint",
+    # Health Check Providers (CR-2)
+    "HealthCheckProvider",
+    "HealthCheckResult",
+    "MongoDBHealthCheck",
+    "RedisHealthCheck",
+    "Neo4jHealthCheck",
+    "QdrantHealthCheck",
+    "HttpServiceHealthCheck",
+    # Metrics Decorators (CR-3)
+    "track_operation",
+    "track_latency",
+    "track_operation_and_latency",
 ]
+
+# Add structlog exports if available (CR-1)
+if _STRUCTLOG_AVAILABLE:
+    __all__.extend(
+        [
+            "configure_structlog",
+            "get_structlog_logger",
+            "bind_contextvars",
+            "clear_contextvars",
+        ]
+    )

neuroglia_python-0.9.0/src/neuroglia/observability/decorators.py

@@ -0,0 +1,185 @@
+"""
+Decorators for automatic metrics recording.
+
+Provides convenience decorators for tracking operation counts and latencies
+without manual instrumentation in every handler.
+
+Usage:
+    from neuroglia.observability.decorators import track_operation, track_latency
+
+    @track_operation("skills_manager.skills.created")
+    async def handle_async(self, command):
+        # Your logic here
+        ...
+
+    @track_latency("api.request")
+    async def endpoint(self, request):
+        # Your logic here
+        ...
+"""
+import asyncio
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from neuroglia.observability.metrics import create_counter, create_histogram
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def track_operation(
+    metric_name: str,
+    success_status: str = "success",
+    error_status: str = "error",
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator to track operation count and status.
+
+    Creates a counter metric that increments on each call, with a status
+    label indicating success or error.
+
+    Args:
+        metric_name: Base name for the metric (e.g., "skills_manager.skills.created").
+        success_status: Status label for successful operations (default: "success").
+        error_status: Status label for failed operations (default: "error").
+
+    Returns:
+        Decorated function with automatic operation tracking.
+
+    Example:
+        >>> @track_operation("skills_manager.skills.created")
+        ... async def create_skill(self, command):
+        ...     # On success: counter increments with status="success"
+        ...     # On exception: counter increments with status="error"
+        ...     return result
+    """
+    # Create counter lazily on first call
+    counter = create_counter(
+        name=metric_name,
+        description=f"Total {metric_name.split('.')[-1]} operations",
+        unit="1",
+    )
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                try:
+                    result = await func(*args, **kwargs)
+                    counter.add(1, {"status": success_status})
+                    return result
+                except Exception:
+                    counter.add(1, {"status": error_status})
+                    raise
+
+            return async_wrapper  # type: ignore[return-value]
+        else:
+
+            @wraps(func)
+            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                try:
+                    result = func(*args, **kwargs)
+                    counter.add(1, {"status": success_status})
+                    return result
+                except Exception:
+                    counter.add(1, {"status": error_status})
+                    raise
+
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def track_latency(
+    metric_name: str,
+    unit: str = "ms",
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator to track operation latency.
+
+    Creates a histogram metric that records the duration of each call.
+
+    Args:
+        metric_name: Base name for the metric (e.g., "api.request").
+        unit: Unit of measurement (default: "ms").
+
+    Returns:
+        Decorated function with automatic latency tracking.
+
+    Example:
+        >>> @track_latency("api.request")
+        ... async def handle_request(self, request):
+        ...     # Duration is recorded as histogram after completion
+        ...     return response
+    """
+    # Create histogram lazily on first call
+    histogram = create_histogram(
+        name=f"{metric_name}.latency",
+        description=f"{metric_name} latency",
+        unit=unit,
+    )
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                start = time.perf_counter()
+                try:
+                    return await func(*args, **kwargs)
+                finally:
+                    elapsed_ms = (time.perf_counter() - start) * 1000
+                    histogram.record(elapsed_ms)
+
+            return async_wrapper  # type: ignore[return-value]
+        else:
+
+            @wraps(func)
+            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                start = time.perf_counter()
+                try:
+                    return func(*args, **kwargs)
+                finally:
+                    elapsed_ms = (time.perf_counter() - start) * 1000
+                    histogram.record(elapsed_ms)
+
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def track_operation_and_latency(
+    metric_name: str,
+    success_status: str = "success",
+    error_status: str = "error",
+    latency_unit: str = "ms",
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Combined decorator to track both operation count and latency.
+
+    Combines the functionality of @track_operation and @track_latency
+    into a single decorator for convenience.
+
+    Args:
+        metric_name: Base name for both metrics.
+        success_status: Status label for successful operations.
+        error_status: Status label for failed operations.
+        latency_unit: Unit for latency measurement (default: "ms").
+
+    Returns:
+        Decorated function with both operation and latency tracking.
+
+    Example:
+        >>> @track_operation_and_latency("skills_manager.skills.created")
+        ... async def create_skill(self, command):
+        ...     # Records both count and latency metrics
+        ...     return result
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        # Apply both decorators
+        decorated = track_latency(metric_name, latency_unit)(func)
+        decorated = track_operation(metric_name, success_status, error_status)(decorated)
+        return decorated  # type: ignore[return-value]
+
+    return decorator

{neuroglia_python-0.8.0 → neuroglia_python-0.9.0}/src/neuroglia/observability/framework.py

@@ -8,12 +8,13 @@ comprehensive observability with minimal configuration.
 
 import datetime
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 from fastapi import FastAPI, Response
 
 if TYPE_CHECKING:
     from neuroglia.hosting.web import WebApplicationBuilder
+    from neuroglia.observability.health_checks import HealthCheckProvider
 
 from neuroglia.observability.settings import (
     ObservabilityConfig,
@@ -44,13 +45,20 @@ class Observability:
     """
 
     @classmethod
-    def configure(cls, builder: "WebApplicationBuilder", auto_enable_cqrs_metrics: bool = True, **overrides) -> None:
+    def configure(
+        cls,
+        builder: "WebApplicationBuilder",
+        auto_enable_cqrs_metrics: bool = True,
+        health_check_providers: Optional[list["HealthCheckProvider"]] = None,
+        **overrides,
+    ) -> None:
         """
         Configure comprehensive observability for the application.
 
         Args:
             builder: The enhanced web application builder (must contain app_settings)
             auto_enable_cqrs_metrics: Auto-enable CQRS metrics if Mediator is detected (default: True)
+            health_check_providers: List of HealthCheckProvider instances for dependency monitoring
             **overrides: Optional configuration overrides (tracing_enabled=False, etc.)
         """
         app_settings = builder.app_settings
@@ -62,6 +70,9 @@ class Observability:
         # Create observability configuration from app_settings
         config = ObservabilityConfig(app_settings, **overrides)
 
+        # Store health check providers on config for use by endpoints
+        config.health_check_providers = health_check_providers or []
+
         # Register configuration in DI container for access throughout application
         builder.services.add_singleton(ObservabilityConfig, lambda: config)
 
@@ -155,11 +166,46 @@ class Observability:
 
             log.info(f"🔭 OpenTelemetry configured: endpoint={config.otel_endpoint}")
 
+            # Create service info gauge (CR-4)
+            if getattr(config, "service_info_gauge", True):
+                cls._create_service_info_gauge(config)
+
         except ImportError as e:
             log.error(f"❌ OpenTelemetry configuration failed - missing dependencies: {e}")
         except Exception as e:
             log.error(f"❌ OpenTelemetry configuration error: {e}")
 
+    @classmethod
+    def _create_service_info_gauge(cls, config: ObservabilityConfig) -> None:
+        """Create service info gauge metric for service discovery (CR-4)"""
+        try:
+            from opentelemetry.metrics import Observation
+
+            from neuroglia.observability.metrics import create_observable_gauge
+
+            def _service_info_callback(options):
+                return [
+                    Observation(
+                        1,
+                        {
+                            "service.name": config.service_name,
+                            "service.version": config.service_version,
+                            "deployment.environment": config.deployment_environment,
+                        },
+                    )
+                ]
+
+            create_observable_gauge(
+                name="service.info",
+                callback=_service_info_callback,
+                unit="1",
+                description="Service metadata gauge for discovery",
+            )
+            log.info("🏷️ Service info gauge created")
+
+        except Exception as e:
+            log.warning(f"⚠️ Could not create service info gauge: {e}")
+
     @classmethod
     def _register_standard_endpoints(cls, builder: "WebApplicationBuilder", config: ObservabilityConfig) -> None:
         """Register standard endpoints for automatic addition to main app during build"""
@@ -187,19 +233,36 @@ class StandardEndpoints:
             health_status = {"status": "healthy", "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(), "service": {"name": config.service_name, "version": config.service_version, "environment": config.deployment_environment}}
 
             # Add dependency checks if configured
-            if config.health_checks:
+            providers = getattr(config, "health_check_providers", [])
+            if config.health_checks or providers:
                 dependencies = {}
                 overall_healthy = True
 
-                for dependency in config.health_checks:
-                    # TODO: Implement pluggable health check providers
-                    # For now, assume dependencies are healthy
-                    dependency_status = await StandardEndpoints._check_dependency_health(dependency)
-                    dependencies[dependency] = dependency_status
-
-                    if dependency_status != "healthy":
+                # Check all registered health check providers
+                for provider in providers:
+                    try:
+                        result = await provider.check()
+                        dep_status = {
+                            "status": result.status,
+                        }
+                        if result.message:
+                            dep_status["message"] = result.message
+                        if result.latency_ms is not None:
+                            dep_status["latency_ms"] = round(result.latency_ms, 2)
+                        dependencies[provider.name] = dep_status
+
+                        if result.status != "healthy":
+                            overall_healthy = False
+                    except Exception as e:
+                        log.warning(f"Health check failed for {provider.name}: {e}")
+                        dependencies[provider.name] = {"status": "unhealthy", "message": str(e)}
                         overall_healthy = False
 
+                # Handle string-based health checks without providers (legacy)
+                for dependency in config.health_checks:
+                    if dependency not in dependencies:
+                        dependencies[dependency] = {"status": "healthy", "message": "No provider configured"}
+
                 health_status["dependencies"] = dependencies
                 if not overall_healthy:
                     health_status["status"] = "degraded"
@@ -222,10 +285,15 @@ class StandardEndpoints:
             # Add basic readiness checks
             checks = {"application": "ready"}
 
-            # TODO: Add pluggable readiness checks
-            if config.health_checks:
-                for dependency in config.health_checks:
-                    checks[dependency] = "ready"  # Placeholder
+            # Use health check providers for readiness
+            providers = getattr(config, "health_check_providers", [])
+            for provider in providers:
+                try:
+                    result = await provider.check()
+                    checks[provider.name] = "ready" if result.status == "healthy" else "not_ready"
+                except Exception as e:
+                    log.warning(f"Readiness check failed for {provider.name}: {e}")
+                    checks[provider.name] = "not_ready"
 
             ready_status["checks"] = checks
             return ready_status
@@ -249,18 +317,5 @@ class StandardEndpoints:
                 """Fallback metrics endpoint when Prometheus is not available"""
                 return Response(content="# Prometheus metrics not available\n# Install prometheus-client for full metrics support\n", media_type="text/plain")
 
-    @staticmethod
-    async def _check_dependency_health(dependency_name: str) -> str:
-        """
-        Check health of a specific dependency.
-
-        TODO: Implement pluggable health check providers for:
-        - MongoDB (check connection)
-        - Redis (ping)
-        - Keycloak (check auth endpoint)
-        - HTTP services (health endpoint check)
-        - Database connections
-        """
-        # Placeholder implementation - always return healthy
-        # In real implementation, this would check actual dependency status
-        return "healthy"
+    # Note: _check_dependency_health has been replaced by HealthCheckProvider implementations
+    # in neuroglia/observability/health_checks.py (CR-2)