alma-memory 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

alma/mcp/tools.py

@@ -5,11 +5,9 @@ Provides the tool functions that can be called via MCP protocol.
 Each tool corresponds to an ALMA operation.
 """
 
-import json
 import logging
-from typing import Dict, Any, Optional, List
 from datetime import datetime, timezone
-from dataclasses import asdict
+from typing import Any, Dict, Optional
 
 from alma import ALMA
 from alma.types import MemorySlice
@@ -32,47 +30,57 @@ def _serialize_memory_slice(memory_slice: MemorySlice) -> Dict[str, Any]:
     }
 
     for h in memory_slice.heuristics:
-        result["heuristics"].append({
-            "id": h.id,
-            "condition": h.condition,
-            "strategy": h.strategy,
-            "confidence": h.confidence,
-            "occurrence_count": h.occurrence_count,
-            "success_rate": h.success_rate,
-        })
+        result["heuristics"].append(
+            {
+                "id": h.id,
+                "condition": h.condition,
+                "strategy": h.strategy,
+                "confidence": h.confidence,
+                "occurrence_count": h.occurrence_count,
+                "success_rate": h.success_rate,
+            }
+        )
 
     for o in memory_slice.outcomes:
-        result["outcomes"].append({
-            "id": o.id,
-            "task_type": o.task_type,
-            "task_description": o.task_description,
-            "success": o.success,
-            "strategy_used": o.strategy_used,
-            "duration_ms": o.duration_ms,
-        })
+        result["outcomes"].append(
+            {
+                "id": o.id,
+                "task_type": o.task_type,
+                "task_description": o.task_description,
+                "success": o.success,
+                "strategy_used": o.strategy_used,
+                "duration_ms": o.duration_ms,
+            }
+        )
 
     for dk in memory_slice.domain_knowledge:
-        result["domain_knowledge"].append({
-            "id": dk.id,
-            "domain": dk.domain,
-            "fact": dk.fact,
-            "confidence": dk.confidence,
-        })
+        result["domain_knowledge"].append(
+            {
+                "id": dk.id,
+                "domain": dk.domain,
+                "fact": dk.fact,
+                "confidence": dk.confidence,
+            }
+        )
 
     for ap in memory_slice.anti_patterns:
-        result["anti_patterns"].append({
-            "id": ap.id,
-            "pattern": ap.pattern,
-            "why_bad": ap.why_bad,
-            "better_alternative": ap.better_alternative,
-        })
+        result["anti_patterns"].append(
+            {
+                "id": ap.id,
+                "pattern": ap.pattern,
+                "why_bad": ap.why_bad,
+                "better_alternative": ap.better_alternative,
+            }
+        )
 
     for p in memory_slice.preferences:
-        result["preferences"].append({
-            "id": p.id,
-            "category": p.category,
-            "preference": p.preference,
-        })
+        result["preferences"].append(
+            {
+                "id": p.id,
+                "category": p.category,
+                "preference": p.preference,
+            }
+        )
 
     return result
 
@@ -97,6 +105,12 @@ def alma_retrieve(
     Returns:
         Dict containing the memory slice with relevant memories
     """
+    # Input validation
+    if not task or not task.strip():
+        return {"success": False, "error": "task cannot be empty"}
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+
     try:
         memories = alma.retrieve(
             task=task,
@@ -147,8 +161,18 @@ def alma_learn(
     Returns:
         Dict with learning result
     """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+    if not task or not task.strip():
+        return {"success": False, "error": "task cannot be empty"}
+    if not outcome or not outcome.strip():
+        return {"success": False, "error": "outcome cannot be empty"}
+    if not strategy_used or not strategy_used.strip():
+        return {"success": False, "error": "strategy_used cannot be empty"}
+
     try:
-        result = alma.learn(
+        outcome_record = alma.learn(
             agent=agent,
             task=task,
             outcome=outcome,
@@ -161,8 +185,14 @@ def alma_learn(
 
         return {
             "success": True,
-            "learned": result,
-            "message": "Outcome recorded" if result else "Learning rejected (scope violation)",
+            "learned": True,
+            "outcome": {
+                "id": outcome_record.id,
+                "agent": outcome_record.agent,
+                "task_type": outcome_record.task_type,
+                "success": outcome_record.success,
+            },
+            "message": "Outcome recorded successfully",
         }
 
     except Exception as e:
@@ -193,6 +223,14 @@ def alma_add_preference(
     Returns:
         Dict with the created preference
     """
+    # Input validation
+    if not user_id or not user_id.strip():
+        return {"success": False, "error": "user_id cannot be empty"}
+    if not category or not category.strip():
+        return {"success": False, "error": "category cannot be empty"}
+    if not preference or not preference.strip():
+        return {"success": False, "error": "preference cannot be empty"}
+
     try:
         pref = alma.add_user_preference(
             user_id=user_id,
@@ -240,6 +278,14 @@ def alma_add_knowledge(
     Returns:
         Dict with the created knowledge or rejection reason
     """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+    if not domain or not domain.strip():
+        return {"success": False, "error": "domain cannot be empty"}
+    if not fact or not fact.strip():
+        return {"success": False, "error": "fact cannot be empty"}
+
     try:
         knowledge = alma.add_domain_knowledge(
             agent=agent,
@@ -248,12 +294,6 @@ def alma_add_knowledge(
             source=source,
         )
 
-        if knowledge is None:
-            return {
-                "success": False,
-                "error": f"Agent '{agent}' not allowed to learn in domain '{domain}'",
-            }
-
         return {
             "success": True,
             "knowledge": {
@@ -372,3 +412,98 @@ def alma_health(alma: ALMA) -> Dict[str, Any]:
             "status": "unhealthy",
             "error": str(e),
         }
+
+
+async def alma_consolidate(
+    alma: ALMA,
+    agent: str,
+    memory_type: str = "heuristics",
+    similarity_threshold: float = 0.85,
+    dry_run: bool = True,
+) -> Dict[str, Any]:
+    """
+    Consolidate similar memories to reduce redundancy.
+
+    This is ALMA's implementation of Mem0's core innovation - LLM-powered
+    deduplication that merges similar memories intelligently.
+
+    Args:
+        alma: ALMA instance
+        agent: Agent whose memories to consolidate
+        memory_type: Type of memory to consolidate
+                    ("heuristics", "outcomes", "domain_knowledge", "anti_patterns")
+        similarity_threshold: Minimum cosine similarity to group (0.0 to 1.0)
+                             Higher values are more conservative (fewer merges)
+        dry_run: If True, report what would be merged without actually modifying storage
+                 Recommended for first run to preview changes
+
+    Returns:
+        Dict with consolidation results including:
+        - merged_count: Number of memories merged
+        - groups_found: Number of similar memory groups identified
+        - memories_processed: Total memories analyzed
+        - merge_details: List of merge operations (or planned operations if dry_run)
+        - errors: Any errors encountered
+    """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+
+    valid_types = ["heuristics", "outcomes", "domain_knowledge", "anti_patterns"]
+    if memory_type not in valid_types:
+        return {
+            "success": False,
+            "error": f"memory_type must be one of: {', '.join(valid_types)}",
+        }
+
+    if not 0.0 <= similarity_threshold <= 1.0:
+        return {
+            "success": False,
+            "error": "similarity_threshold must be between 0.0 and 1.0",
+        }
+
+    try:
+        from alma.consolidation import ConsolidationEngine
+
+        # Create consolidation engine
+        engine = ConsolidationEngine(
+            storage=alma.storage,
+            embedder=None,  # Will use default LocalEmbedder
+            llm_client=None,  # LLM merging disabled by default
+        )
+
+        # Run consolidation
+        result = await engine.consolidate(
+            agent=agent,
+            project_id=alma.project_id,
+            memory_type=memory_type,
+            similarity_threshold=similarity_threshold,
+            use_llm=False,  # LLM disabled - uses highest confidence merge
+            dry_run=dry_run,
+        )
+
+        # Invalidate cache after consolidation (if not dry run)
+        if not dry_run and result.merged_count > 0:
+            alma.retrieval.invalidate_cache(agent=agent, project_id=alma.project_id)
+
+        return {
+            "success": result.success,
+            "dry_run": dry_run,
+            "merged_count": result.merged_count,
+            "groups_found": result.groups_found,
+            "memories_processed": result.memories_processed,
+            "merge_details": result.merge_details,
+            "errors": result.errors,
+            "message": (
+                f"{'Would merge' if dry_run else 'Merged'} {result.merged_count} memories "
+                f"from {result.groups_found} similar groups "
+                f"(processed {result.memories_processed} total)"
+            ),
+        }
+
+    except Exception as e:
+        logger.exception(f"Error in alma_consolidate: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+        }

alma/observability/__init__.py

@@ -0,0 +1,84 @@
+"""
+ALMA Observability Module.
+
+Provides comprehensive observability features including:
+- OpenTelemetry integration for distributed tracing
+- Structured JSON logging
+- Metrics collection (counters, histograms, gauges)
+- Performance monitoring
+
+This module follows the OpenTelemetry specification and supports
+integration with common observability backends (Jaeger, Prometheus,
+DataDog, etc.).
+
+Usage:
+    from alma.observability import (
+        get_tracer,
+        get_meter,
+        get_logger,
+        configure_observability,
+        ALMAMetrics,
+    )
+
+    # Initialize observability (typically at app startup)
+    configure_observability(
+        service_name="alma-memory",
+        enable_tracing=True,
+        enable_metrics=True,
+        log_format="json",
+    )
+
+    # Use in code
+    tracer = get_tracer(__name__)
+    with tracer.start_as_current_span("my_operation"):
+        # ... your code
+        pass
+"""
+
+from alma.observability.config import (
+    ObservabilityConfig,
+    configure_observability,
+    shutdown_observability,
+)
+from alma.observability.logging import (
+    JSONFormatter,
+    StructuredLogger,
+    get_logger,
+    setup_logging,
+)
+from alma.observability.metrics import (
+    ALMAMetrics,
+    MetricsCollector,
+    get_meter,
+    get_metrics,
+)
+from alma.observability.tracing import (
+    SpanKind,
+    TracingContext,
+    get_tracer,
+    trace_async,
+    trace_method,
+)
+
+__all__ = [
+    # Configuration
+    "ObservabilityConfig",
+    "configure_observability",
+    "shutdown_observability",
+    # Logging
+    "JSONFormatter",
+    "StructuredLogger",
+    "get_logger",
+    "setup_logging",
+    # Metrics
+    "ALMAMetrics",
+    "MetricsCollector",
+    "get_meter",
+    "get_metrics",
+    # Tracing
+    "SpanKind",
+    "TracingContext",
+    "get_tracer",
+    "trace_method",
+    "trace_async",
+]

alma/observability/config.py

@@ -0,0 +1,302 @@
+"""
+ALMA Observability Configuration.
+
+Centralized configuration for observability features including
+tracing, metrics, and logging setup.
+"""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+# Global state for observability configuration
+_observability_initialized = False
+_tracer_provider = None
+_meter_provider = None
+
+
+@dataclass
+class ObservabilityConfig:
+    """
+    Configuration for ALMA observability features.
+
+    Attributes:
+        service_name: Name of the service for tracing/metrics
+        service_version: Version of the service
+        environment: Deployment environment (dev, staging, prod)
+        enable_tracing: Whether to enable distributed tracing
+        enable_metrics: Whether to enable metrics collection
+        enable_logging: Whether to enable structured logging
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        log_format: Log format ("json" or "text")
+        otlp_endpoint: OpenTelemetry collector endpoint
+        otlp_headers: Headers for OTLP exporter
+        trace_sample_rate: Sampling rate for traces (0.0-1.0)
+        metric_export_interval_ms: How often to export metrics
+        resource_attributes: Additional resource attributes
+    """
+
+    service_name: str = "alma-memory"
+    service_version: str = "0.5.1"
+    environment: str = field(
+        default_factory=lambda: os.environ.get("ALMA_ENVIRONMENT", "development")
+    )
+    enable_tracing: bool = True
+    enable_metrics: bool = True
+    enable_logging: bool = True
+    log_level: str = field(
+        default_factory=lambda: os.environ.get("ALMA_LOG_LEVEL", "INFO")
+    )
+    log_format: str = field(
+        default_factory=lambda: os.environ.get("ALMA_LOG_FORMAT", "json")
+    )
+    otlp_endpoint: Optional[str] = field(
+        default_factory=lambda: os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+    )
+    otlp_headers: Dict[str, str] = field(default_factory=dict)
+    trace_sample_rate: float = 1.0
+    metric_export_interval_ms: int = 60000
+    resource_attributes: Dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary."""
+        return {
+            "service_name": self.service_name,
+            "service_version": self.service_version,
+            "environment": self.environment,
+            "enable_tracing": self.enable_tracing,
+            "enable_metrics": self.enable_metrics,
+            "enable_logging": self.enable_logging,
+            "log_level": self.log_level,
+            "log_format": self.log_format,
+            "otlp_endpoint": self.otlp_endpoint,
+            "trace_sample_rate": self.trace_sample_rate,
+            "metric_export_interval_ms": self.metric_export_interval_ms,
+        }
+
+
+def configure_observability(
+    service_name: str = "alma-memory",
+    service_version: str = "0.5.1",
+    environment: Optional[str] = None,
+    enable_tracing: bool = True,
+    enable_metrics: bool = True,
+    enable_logging: bool = True,
+    log_level: str = "INFO",
+    log_format: str = "json",
+    otlp_endpoint: Optional[str] = None,
+    trace_sample_rate: float = 1.0,
+    resource_attributes: Optional[Dict[str, str]] = None,
+) -> ObservabilityConfig:
+    """
+    Configure ALMA observability features.
+
+    This function should be called once at application startup to initialize
+    tracing, metrics, and logging.
+
+    Args:
+        service_name: Name of the service
+        service_version: Version of the service
+        environment: Deployment environment
+        enable_tracing: Enable distributed tracing
+        enable_metrics: Enable metrics collection
+        enable_logging: Enable structured logging
+        log_level: Logging level
+        log_format: Log format ("json" or "text")
+        otlp_endpoint: OpenTelemetry collector endpoint
+        trace_sample_rate: Sampling rate for traces
+        resource_attributes: Additional resource attributes
+
+    Returns:
+        ObservabilityConfig with applied settings
+    """
+    global _observability_initialized, _tracer_provider, _meter_provider
+
+    config = ObservabilityConfig(
+        service_name=service_name,
+        service_version=service_version,
+        environment=environment or os.environ.get("ALMA_ENVIRONMENT", "development"),
+        enable_tracing=enable_tracing,
+        enable_metrics=enable_metrics,
+        enable_logging=enable_logging,
+        log_level=log_level,
+        log_format=log_format,
+        otlp_endpoint=otlp_endpoint,
+        trace_sample_rate=trace_sample_rate,
+        resource_attributes=resource_attributes or {},
+    )
+
+    # Setup logging first
+    if config.enable_logging:
+        from alma.observability.logging import setup_logging
+
+        setup_logging(
+            level=config.log_level,
+            format_type=config.log_format,
+            service_name=config.service_name,
+        )
+
+    # Setup tracing
+    if config.enable_tracing:
+        _tracer_provider = _setup_tracing(config)
+
+    # Setup metrics
+    if config.enable_metrics:
+        _meter_provider = _setup_metrics(config)
+
+    _observability_initialized = True
+
+    logger = logging.getLogger(__name__)
+    logger.info(
+        "ALMA observability configured",
+        extra={
+            "service_name": config.service_name,
+            "environment": config.environment,
+            "tracing_enabled": config.enable_tracing,
+            "metrics_enabled": config.enable_metrics,
+        },
+    )
+
+    return config
+
+
+def _setup_tracing(config: ObservabilityConfig):
+    """Setup OpenTelemetry tracing."""
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+
+        # Build resource attributes
+        resource_attrs = {
+            "service.name": config.service_name,
+            "service.version": config.service_version,
+            "deployment.environment": config.environment,
+        }
+        resource_attrs.update(config.resource_attributes)
+
+        resource = Resource.create(resource_attrs)
+
+        # Create sampler
+        sampler = TraceIdRatioBased(config.trace_sample_rate)
+
+        # Create and set tracer provider
+        provider = TracerProvider(resource=resource, sampler=sampler)
+
+        # Add OTLP exporter if endpoint is configured
+        if config.otlp_endpoint:
+            try:
+                from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                    OTLPSpanExporter,
+                )
+                from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+                otlp_exporter = OTLPSpanExporter(
+                    endpoint=config.otlp_endpoint,
+                    headers=config.otlp_headers or {},
+                )
+                provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+            except ImportError:
+                logging.getLogger(__name__).warning(
+                    "OTLP exporter not available. Install with: "
+                    "pip install opentelemetry-exporter-otlp-proto-grpc"
+                )
+
+        trace.set_tracer_provider(provider)
+        return provider
+
+    except ImportError:
+        logging.getLogger(__name__).warning(
+            "OpenTelemetry SDK not available. Tracing disabled. "
+            "Install with: pip install opentelemetry-sdk"
+        )
+        return None
+
+
+def _setup_metrics(config: ObservabilityConfig):
+    """Setup OpenTelemetry metrics."""
+    try:
+        from opentelemetry import metrics
+        from opentelemetry.sdk.metrics import MeterProvider
+        from opentelemetry.sdk.resources import Resource
+
+        # Build resource attributes
+        resource_attrs = {
+            "service.name": config.service_name,
+            "service.version": config.service_version,
+            "deployment.environment": config.environment,
+        }
+        resource_attrs.update(config.resource_attributes)
+
+        resource = Resource.create(resource_attrs)
+
+        # Create meter provider
+        provider = MeterProvider(resource=resource)
+
+        # Add OTLP exporter if endpoint is configured
+        if config.otlp_endpoint:
+            try:
+                from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+                    OTLPMetricExporter,
+                )
+                from opentelemetry.sdk.metrics.export import (
+                    PeriodicExportingMetricReader,
+                )
+
+                otlp_exporter = OTLPMetricExporter(
+                    endpoint=config.otlp_endpoint,
+                    headers=config.otlp_headers or {},
+                )
+                reader = PeriodicExportingMetricReader(
+                    otlp_exporter,
+                    export_interval_millis=config.metric_export_interval_ms,
+                )
+                provider = MeterProvider(resource=resource, metric_readers=[reader])
+            except ImportError:
+                logging.getLogger(__name__).warning(
+                    "OTLP metric exporter not available. Install with: "
+                    "pip install opentelemetry-exporter-otlp-proto-grpc"
+                )
+
+        metrics.set_meter_provider(provider)
+        return provider
+
+    except ImportError:
+        logging.getLogger(__name__).warning(
+            "OpenTelemetry SDK not available. Metrics disabled. "
+            "Install with: pip install opentelemetry-sdk"
+        )
+        return None
+
+
+def shutdown_observability():
+    """
+    Shutdown observability providers.
+
+    Should be called at application shutdown to ensure all telemetry
+    data is exported.
+    """
+    global _observability_initialized, _tracer_provider, _meter_provider
+
+    if _tracer_provider is not None:
+        try:
+            _tracer_provider.shutdown()
+        except Exception as e:
+            logging.getLogger(__name__).error(f"Error shutting down tracer: {e}")
+
+    if _meter_provider is not None:
+        try:
+            _meter_provider.shutdown()
+        except Exception as e:
+            logging.getLogger(__name__).error(f"Error shutting down meter: {e}")
+
+    _observability_initialized = False
+    _tracer_provider = None
+    _meter_provider = None
+
+
+def is_observability_initialized() -> bool:
+    """Check if observability has been initialized."""
+    return _observability_initialized