grounded-memory 0.1.0__py3-none-any.whl

gmem/__init__.py

@@ -0,0 +1,35 @@
+"""gmem public facade package.
+
+This package provides a compact import surface while reusing the
+`grounded_memory` implementation.
+"""
+
+from grounded_memory import (
+    ConstraintValidator,
+    GroundedMemorySystem,
+    GroundingOperator,
+    LLMConfig,
+    Memory,
+    MemoryStore,
+    __version__,
+    configure_logging,
+    create_app,
+    list_registered_adapters,
+    register_adapter,
+    unregister_adapter,
+)
+
+__all__ = [
+    "__version__",
+    "Memory",
+    "GroundedMemorySystem",
+    "ConstraintValidator",
+    "GroundingOperator",
+    "MemoryStore",
+    "LLMConfig",
+    "create_app",
+    "configure_logging",
+    "list_registered_adapters",
+    "register_adapter",
+    "unregister_adapter",
+]

gmem/service.py

@@ -0,0 +1,5 @@
+"""Service helpers for the `gmem` facade package."""
+
+from grounded_memory.service.app import app, create_app
+
+__all__ = ["app", "create_app"]

grounded_memory/__init__.py

@@ -0,0 +1,114 @@
+"""
+Grounded Memory System - Core Module
+
+A correctness-first memory architecture for LLM agents.
+"""
+
+from grounded_memory.adapters.discovery import (
+    ConstraintSeedDiscoverer,
+    DiscoveredConstraintSeed,
+)
+from grounded_memory.adapters.generic_agent import (
+    GenericMemoryAgent,
+    GenericProcessingResult,
+)
+from grounded_memory.adapters.registry import (
+    get_adapter_spec,
+    get_adapter_spec_by_key,
+    list_registered_adapters,
+    list_supported_profiles,
+    register_adapter,
+    register_adapter_spec,
+    unregister_adapter,
+    unregister_adapter_spec,
+)
+from grounded_memory.adapters.seeds import (
+    CardinalitySeedConstraintEvaluator,
+    SeedConstraintEvaluator,
+    TemporalCardinalitySeedConstraintEvaluator,
+)
+from grounded_memory.core.constraints import (
+    ConstraintValidator,
+    ConstraintViolation,
+    ValidationResult,
+)
+from grounded_memory.core.grounding import GroundingOperator, GroundingResult
+from grounded_memory.core.models import (
+    CandidateFact,
+    Constraint,
+    Entity,
+    Interaction,
+    MemoryDisposition,
+    RelationType,
+    ValidatedFact,
+)
+from grounded_memory.core.store import MemoryStore
+from grounded_memory.core.system import GroundedMemorySystem as CoreGroundedMemorySystem
+from grounded_memory.llm.client import LLMClient, LLMConfig, SyncLLMClient
+from grounded_memory.llm.extractor import LLMFactExtractor
+from grounded_memory.logging_utils import configure_logging
+from grounded_memory.memory import (
+    Memory,
+    OptimizationProfile,
+    OptimizationSettings,
+    SearchResult,
+)
+from grounded_memory.service import app as service_app
+from grounded_memory.service import create_app
+from grounded_memory.system import GroundedMemorySystem
+
+LLM_AVAILABLE = True
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core Models
+    "Interaction",
+    "Entity", 
+    "CandidateFact",
+    "ValidatedFact",
+    "Constraint",
+    "MemoryDisposition",
+    "RelationType",
+    # Grounding
+    "GroundingOperator",
+    "GroundingResult",
+    # Store
+    "MemoryStore",
+    "GroundedMemorySystem",
+    "CoreGroundedMemorySystem",
+    # Constraints
+    "ConstraintValidator",
+    "ValidationResult",
+    "ConstraintViolation",
+    # LLM (if available)
+    "LLM_AVAILABLE",
+    "LLMConfig",
+    "SyncLLMClient",
+    "LLMClient",
+    "LLMFactExtractor",
+    # SDK facade
+    "Memory",
+    "SearchResult",
+    "OptimizationProfile",
+    "OptimizationSettings",
+    # Adapter registry APIs
+    "SeedConstraintEvaluator",
+    "CardinalitySeedConstraintEvaluator",
+    "TemporalCardinalitySeedConstraintEvaluator",
+    "DiscoveredConstraintSeed",
+    "ConstraintSeedDiscoverer",
+    "GenericMemoryAgent",
+    "GenericProcessingResult",
+    "configure_logging",
+    "create_app",
+    "service_app",
+    "list_registered_adapters",
+    "get_adapter_spec_by_key",
+    "register_adapter",
+    "unregister_adapter",
+    "list_supported_profiles",
+    "get_adapter_spec",
+    "register_adapter_spec",
+    "unregister_adapter_spec",
+]

grounded_memory/adapters/__init__.py

@@ -0,0 +1,46 @@
+"""Adapter packages for memory governance and agent wiring."""
+
+from grounded_memory.adapters.discovery import (
+	ConstraintSeedDiscoverer,
+	DiscoveredConstraintSeed,
+)
+from grounded_memory.adapters.generic_agent import (
+	GenericMemoryAgent,
+	GenericProcessingResult,
+)
+from grounded_memory.adapters.registry import (
+	AdapterSpec,
+	get_adapter_spec,
+	get_adapter_spec_by_key,
+	list_registered_adapters,
+	# Backward-compatible exports
+	list_supported_profiles,
+	register_adapter,
+	register_adapter_spec,
+	unregister_adapter,
+	unregister_adapter_spec,
+)
+from grounded_memory.adapters.seeds import (
+	CardinalitySeedConstraintEvaluator,
+	SeedConstraintEvaluator,
+	TemporalCardinalitySeedConstraintEvaluator,
+)
+
+__all__ = [
+	"SeedConstraintEvaluator",
+	"CardinalitySeedConstraintEvaluator",
+	"TemporalCardinalitySeedConstraintEvaluator",
+	"DiscoveredConstraintSeed",
+	"ConstraintSeedDiscoverer",
+	"AdapterSpec",
+	"GenericMemoryAgent",
+	"GenericProcessingResult",
+	"list_registered_adapters",
+	"get_adapter_spec_by_key",
+	"register_adapter",
+	"unregister_adapter",
+	"list_supported_profiles",
+	"get_adapter_spec",
+	"register_adapter_spec",
+	"unregister_adapter_spec",
+]

grounded_memory/adapters/base_agent.py

@@ -0,0 +1,55 @@
+"""Shared adapter agent primitives."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseAsyncAdapterAgent(ABC):
+    """Base class that provides a sync wrapper for async adapter agents."""
+
+    @abstractmethod
+    async def process_interaction(
+        self,
+        raw_text: str,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        actor: str = "user",
+        metadata: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Process an interaction asynchronously."""
+
+    def process(self, input_text: str, source: str = "user", **kwargs: Any) -> Any:
+        """Backward-compatible synchronous wrapper used by demos and SDK calls."""
+        metadata = kwargs.pop("metadata", None)
+        user_id = kwargs.pop("user_id", None)
+        session_id = kwargs.pop("session_id", None)
+
+        extra_metadata = {k: v for k, v in kwargs.items() if v is not None}
+        if metadata is None:
+            metadata = extra_metadata
+        elif isinstance(metadata, dict):
+            metadata = {**metadata, **extra_metadata}
+
+        actor = source.strip().lower() if isinstance(source, str) else "user"
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(
+                self.process_interaction(
+                    raw_text=input_text,
+                    user_id=user_id,
+                    session_id=session_id,
+                    actor=actor,
+                    metadata=metadata,
+                )
+            )
+
+        raise RuntimeError(
+            f"{self.__class__.__name__}.process() cannot be used while an event loop is running. "
+            "Await process_interaction(...) instead."
+        )

grounded_memory/adapters/discovery.py

@@ -0,0 +1,251 @@
+"""Autonomous mining and synthesis of dynamic constraint seeds."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class DiscoveredConstraintSeed:
+    """Synthesized seed proposal mined from governance signals."""
+
+    constraint_id: str
+    name: str
+    description: str
+    relation_types: list[str]
+    required_attribute_keys: list[str]
+    require_value: bool
+    confidence: float
+    evidence_count: int
+    mining_rule: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "constraint_id": self.constraint_id,
+            "name": self.name,
+            "description": self.description,
+            "relation_types": list(self.relation_types),
+            "required_attribute_keys": list(self.required_attribute_keys),
+            "require_value": self.require_value,
+            "confidence": self.confidence,
+            "evidence_count": self.evidence_count,
+            "mining_rule": self.mining_rule,
+        }
+
+
+class ConstraintSeedDiscoverer:
+    """Mine validation/rejection signals and synthesize candidate seed constraints."""
+
+    def __init__(
+        self,
+        *,
+        min_samples_per_relation: int = 20,
+        min_rejections_per_relation: int = 6,
+        min_gap: float = 0.35,
+        min_gap_mode: str = "fixed",
+        min_gap_floor: float = 0.15,
+        min_gap_ceiling: float = 0.60,
+        target_false_block_rate: float = 0.10,
+        max_suggestions: int = 20,
+    ) -> None:
+        self.min_samples_per_relation = min_samples_per_relation
+        self.min_rejections_per_relation = min_rejections_per_relation
+        self.min_gap = min_gap
+        self.min_gap_mode = min_gap_mode.strip().lower()
+        self.min_gap_floor = min_gap_floor
+        self.min_gap_ceiling = min_gap_ceiling
+        self.target_false_block_rate = target_false_block_rate
+        self.max_suggestions = max_suggestions
+
+    def discover(
+        self,
+        *,
+        validation_signals: list[dict[str, Any]],
+        existing_constraint_ids: set[str] | None = None,
+    ) -> list[DiscoveredConstraintSeed]:
+        existing_ids = existing_constraint_ids or set()
+        grouped: dict[str, list[dict[str, Any]]] = {}
+
+        for signal in validation_signals:
+            relation = str(signal.get("relation") or "").strip()
+            if not relation:
+                continue
+            grouped.setdefault(relation, []).append(signal)
+
+        suggestions: list[DiscoveredConstraintSeed] = []
+
+        for relation, rows in grouped.items():
+            if len(rows) < self.min_samples_per_relation:
+                continue
+
+            rejected = [row for row in rows if not bool(row.get("is_valid", True))]
+            accepted = [row for row in rows if bool(row.get("is_valid", True))]
+            if len(rejected) < self.min_rejections_per_relation:
+                continue
+
+            effective_min_gap = self._resolve_min_gap(
+                total_samples=len(rows),
+                rejected_samples=len(rejected),
+            )
+
+            suggestion = self._synthesize_require_value_seed(
+                relation=relation,
+                rejected=rejected,
+                accepted=accepted,
+                existing_ids=existing_ids,
+                min_gap=effective_min_gap,
+            )
+            if suggestion is not None:
+                suggestions.append(suggestion)
+                existing_ids.add(suggestion.constraint_id)
+
+            suggestions.extend(
+                self._synthesize_required_attribute_key_seeds(
+                    relation=relation,
+                    rejected=rejected,
+                    accepted=accepted,
+                    existing_ids=existing_ids,
+                    min_gap=effective_min_gap,
+                )
+            )
+            for seed in suggestions:
+                existing_ids.add(seed.constraint_id)
+
+        suggestions.sort(
+            key=lambda seed: (seed.confidence, seed.evidence_count),
+            reverse=True,
+        )
+        return suggestions[: self.max_suggestions]
+
+    def _synthesize_require_value_seed(
+        self,
+        *,
+        relation: str,
+        rejected: list[dict[str, Any]],
+        accepted: list[dict[str, Any]],
+        existing_ids: set[str],
+        min_gap: float,
+    ) -> DiscoveredConstraintSeed | None:
+        rejected_missing_value = sum(
+            1
+            for row in rejected
+            if not bool(row.get("has_value", False))
+        )
+        accepted_missing_value = sum(
+            1
+            for row in accepted
+            if not bool(row.get("has_value", False))
+        )
+
+        rejected_rate = rejected_missing_value / max(len(rejected), 1)
+        accepted_rate = accepted_missing_value / max(len(accepted), 1)
+        gap = rejected_rate - accepted_rate
+
+        if rejected_missing_value == 0 or gap < min_gap:
+            return None
+
+        constraint_id = f"seed_auto_require_value_{relation.lower()}"
+        if constraint_id in existing_ids:
+            return None
+
+        confidence = min(0.99, max(0.5, gap * 0.8 + 0.2))
+        return DiscoveredConstraintSeed(
+            constraint_id=constraint_id,
+            name=f"Auto-discovered value requirement ({relation})",
+            description=(
+                f"Mined from governance signals: relation {relation} has elevated rejection "
+                "rate when candidate value is missing"
+            ),
+            relation_types=[relation],
+            required_attribute_keys=[],
+            require_value=True,
+            confidence=round(confidence, 4),
+            evidence_count=rejected_missing_value,
+            mining_rule=f"missing_value_gap(min_gap={min_gap:.3f})",
+        )
+
+    def _synthesize_required_attribute_key_seeds(
+        self,
+        *,
+        relation: str,
+        rejected: list[dict[str, Any]],
+        accepted: list[dict[str, Any]],
+        existing_ids: set[str],
+        min_gap: float,
+    ) -> list[DiscoveredConstraintSeed]:
+        attribute_keys: set[str] = set()
+        for row in rejected + accepted:
+            attrs = row.get("candidate_attributes") or {}
+            if isinstance(attrs, dict):
+                attribute_keys.update(str(key) for key in attrs.keys())
+
+        seeds: list[DiscoveredConstraintSeed] = []
+        for key in sorted(attribute_keys):
+            rejected_missing = 0
+            for row in rejected:
+                attrs = row.get("candidate_attributes") or {}
+                value = attrs.get(key) if isinstance(attrs, dict) else None
+                if value in (None, ""):
+                    rejected_missing += 1
+
+            accepted_missing = 0
+            for row in accepted:
+                attrs = row.get("candidate_attributes") or {}
+                value = attrs.get(key) if isinstance(attrs, dict) else None
+                if value in (None, ""):
+                    accepted_missing += 1
+
+            rejected_rate = rejected_missing / max(len(rejected), 1)
+            accepted_rate = accepted_missing / max(len(accepted), 1)
+            gap = rejected_rate - accepted_rate
+
+            if rejected_missing == 0 or gap < min_gap:
+                continue
+
+            constraint_id = (
+                f"seed_auto_require_attr_{relation.lower()}_{key.lower().replace(' ', '_')}"
+            )
+            if constraint_id in existing_ids:
+                continue
+
+            confidence = min(0.99, max(0.5, gap * 0.8 + 0.2))
+            seeds.append(
+                DiscoveredConstraintSeed(
+                    constraint_id=constraint_id,
+                    name=f"Auto-discovered required attribute '{key}' ({relation})",
+                    description=(
+                        f"Mined from governance signals: relation {relation} has elevated rejection "
+                        f"rate when attribute '{key}' is missing"
+                    ),
+                    relation_types=[relation],
+                    required_attribute_keys=[key],
+                    require_value=False,
+                    confidence=round(confidence, 4),
+                    evidence_count=rejected_missing,
+                    mining_rule=f"missing_attribute_gap(min_gap={min_gap:.3f})",
+                )
+            )
+
+        seeds.sort(key=lambda seed: (seed.confidence, seed.evidence_count), reverse=True)
+        return seeds
+
+    def _resolve_min_gap(self, *, total_samples: int, rejected_samples: int) -> float:
+        if self.min_gap_mode == "fixed":
+            return float(self.min_gap)
+
+        if self.min_gap_mode != "adaptive":
+            raise ValueError("min_gap_mode must be 'fixed' or 'adaptive'")
+
+        n = max(total_samples, 1)
+        rejection_rate = rejected_samples / n
+        uncertainty_penalty = 1.0 / (n ** 0.5)
+        strictness_boost = 0.10 if rejection_rate >= 0.50 else 0.0
+
+        adaptive_gap = (
+            self.target_false_block_rate
+            + 0.15
+            + uncertainty_penalty
+            + strictness_boost
+        )
+        return max(self.min_gap_floor, min(self.min_gap_ceiling, adaptive_gap))