etchmem 0.1.0__py3-none-any.whl

etchmem/__init__.py

@@ -0,0 +1,25 @@
+"""
+skillmem — a reconsolidating three-tier memory engine for LLM agents.
+
+Public surface::
+
+    from etchmem import Engine
+
+    engine = Engine()
+    engine.remember("text")
+    results = engine.recall("query")
+    summary = engine.consolidate()
+"""
+from etchmem.engine import Engine
+from etchmem.config import Config
+from etchmem.models import SearchResult, Record, InjectedArticle
+
+__all__ = [
+    "Engine",
+    "Config",
+    "SearchResult",
+    "Record",
+    "InjectedArticle",
+]
+
+__version__ = "0.1.0"

etchmem/config.py

@@ -0,0 +1,109 @@
+"""
+skillmem configuration.
+
+All settings can be overridden by passing a Config instance to Engine().
+Environment variables are read at import time as defaults.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Config:
+    # ── Storage ───────────────────────────────────────────────────────────
+    data_dir: str = field(
+        default_factory=lambda: os.environ.get("SKILLMEM_DATA_DIR", ".skillmem")
+    )
+
+    # ── Collections ───────────────────────────────────────────────────────
+    collection_relational: str = "relational"
+    collection_buffer: str = "buffer"
+    collection_injected: str = "injected"
+
+    # ── TTL (seconds) for relational records ─────────────────────────────
+    # Default: 7 days
+    relational_ttl_seconds: int = field(
+        default_factory=lambda: int(
+            os.environ.get("SKILLMEM_RELATIONAL_TTL", str(7 * 24 * 3600))
+        )
+    )
+
+    # ── Recall ────────────────────────────────────────────────────────────
+    recall_top_k_injected: int = 5
+    recall_top_k_relational: int = 5
+
+    # Asymmetric scoring weights
+    recall_injected_weight: float = 1.0   # high-trust base
+    recall_relational_weight: float = 0.6  # freshness-boosted, confidence-discounted
+
+    # ── Consolidation thresholds ──────────────────────────────────────────
+    # branch_threshold: cosine distance above which a cluster splits into
+    # multiple injected articles (distinct experiences → distinct articles).
+    # Higher = harder to branch.
+    branch_threshold: float = field(
+        default_factory=lambda: float(
+            os.environ.get("SKILLMEM_BRANCH_THRESHOLD", "0.4")
+        )
+    )
+
+    # dedup_delete_threshold: cosine distance below which two injected
+    # articles are "the same" → older is superseded.
+    # MUST be strictly tighter (lower) than branch_threshold.
+    dedup_delete_threshold: float = field(
+        default_factory=lambda: float(
+            os.environ.get("SKILLMEM_DEDUP_THRESHOLD", "0.15")
+        )
+    )
+
+    # ── Affectability buckets ─────────────────────────────────────────────
+    affectability_drop_below: float = 0.3   # < this → drop (noise)
+    affectability_keep_below: float = 0.7   # 0.3–0.7 → keep in buffer
+    affectability_default: float = 0.5      # default when no hint given
+
+    # ── LLM connector ─────────────────────────────────────────────────────
+    llm_provider: str = field(
+        default_factory=lambda: os.environ.get("SKILLMEM_LLM_PROVIDER", "auto")
+    )  # "openai" | "anthropic" | "auto"
+
+    openai_api_key: str | None = field(
+        default_factory=lambda: os.environ.get("OPENAI_API_KEY")
+    )
+    openai_model: str = field(
+        default_factory=lambda: os.environ.get("SKILLMEM_OPENAI_MODEL", "gpt-4o-mini")
+    )
+
+    anthropic_api_key: str | None = field(
+        default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY")
+    )
+    anthropic_model: str = field(
+        default_factory=lambda: os.environ.get(
+            "SKILLMEM_ANTHROPIC_MODEL", "claude-haiku-4-5-20251001"
+        )
+    )
+
+    # ── Consolidation ─────────────────────────────────────────────────────
+    consolidate_default_num_records: int | str = "all"
+    consolidate_default_method: str = "LIFO"
+
+    # ── Embedding function ─────────────────────────────────────────────────
+    # None (default) → Chroma's bundled ONNX model (downloads on first use).
+    # "hash"         → offline deterministic hash embedding (tests/CI only).
+    # Any chromadb EmbeddingFunction subclass → custom.
+    embedding_function: object = None
+
+    # Minimum cluster size before promoting (orphaned records use
+    # affectability; clustered records bypass this gate).
+    min_cluster_size: int = 2
+
+    def __post_init__(self) -> None:
+        if self.dedup_delete_threshold >= self.branch_threshold:
+            raise ValueError(
+                f"dedup_delete_threshold ({self.dedup_delete_threshold}) must be "
+                f"strictly less than branch_threshold ({self.branch_threshold})"
+            )
+
+
+# Module-level default — override by passing Config() to Engine.
+DEFAULT_CONFIG = Config()

etchmem/connector/base.py

@@ -0,0 +1,35 @@
+"""
+LLMConnector abstract base class.
+
+The connector's ONLY job is article synthesis — generative completion.
+Embeddings are always Chroma-native and never go through this connector.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LLMConnector(ABC):
+    """
+    Single-method interface for generative synthesis.
+
+    Used in exactly one place in the worker:
+    - Reconsolidation-with-new-signal: rewrite an existing injected article
+      blended with fresh context.
+
+    All other worker operations (clustering, affectability arithmetic,
+    the reconsolidation gate) are LLM-free.
+    """
+
+    @abstractmethod
+    def complete(self, prompt: str, **opts) -> str:
+        """
+        Run a completion against the configured LLM.
+
+        Args:
+            prompt: The full synthesis prompt (already assembled by the worker).
+            **opts: Optional provider-specific overrides (max_tokens, temperature…).
+
+        Returns:
+            The generated text string.
+        """

etchmem/connector/remote.py

@@ -0,0 +1,121 @@
+"""
+Remote LLM connector — default synthesis backend.
+
+Supports OpenAI and Anthropic. Auto-detects available keys.
+Provider resolution order when llm_provider == "auto":
+  1. Use OpenAI if OPENAI_API_KEY is set.
+  2. Fall back to Anthropic if ANTHROPIC_API_KEY is set.
+  3. Raise RuntimeError if neither key is configured.
+
+Models (from README):
+  OpenAI:    gpt-4o-mini  (default; gpt-5.4-nano when available)
+  Anthropic: claude-haiku-4-5-20251001
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from etchmem.connector.base import LLMConnector
+
+
+class RemoteConnector(LLMConnector):
+    """
+    API-backed connector for OpenAI and Anthropic.
+
+    The connector is intentionally thin — it wraps one method (complete)
+    and delegates everything else to the provider SDK.
+    """
+
+    def __init__(
+        self,
+        provider: str = "auto",           # "openai" | "anthropic" | "auto"
+        openai_api_key: str | None = None,
+        openai_model: str = "gpt-4o-mini",
+        anthropic_api_key: str | None = None,
+        anthropic_model: str = "claude-haiku-4-5-20251001",
+    ) -> None:
+        self._openai_key = openai_api_key
+        self._openai_model = openai_model
+        self._anthropic_key = anthropic_api_key
+        self._anthropic_model = anthropic_model
+        self._provider = self._resolve_provider(provider)
+
+    def _resolve_provider(self, requested: str) -> str:
+        if requested == "auto":
+            if self._openai_key:
+                return "openai"
+            if self._anthropic_key:
+                return "anthropic"
+            raise RuntimeError(
+                "skillmem: no LLM API key configured. "
+                "Set OPENAI_API_KEY or ANTHROPIC_API_KEY (or pass them to Config)."
+            )
+        if requested == "openai" and not self._openai_key:
+            raise RuntimeError(
+                "skillmem: llm_provider='openai' but OPENAI_API_KEY is not set."
+            )
+        if requested == "anthropic" and not self._anthropic_key:
+            raise RuntimeError(
+                "skillmem: llm_provider='anthropic' but ANTHROPIC_API_KEY is not set."
+            )
+        return requested
+
+    def complete(self, prompt: str, **opts: Any) -> str:
+        """Run synthesis completion against the configured provider."""
+        if self._provider == "openai":
+            return self._complete_openai(prompt, **opts)
+        return self._complete_anthropic(prompt, **opts)
+
+    def _complete_openai(self, prompt: str, **opts: Any) -> str:
+        try:
+            from openai import OpenAI  # type: ignore[import]
+        except ImportError as e:
+            raise ImportError("skillmem: 'openai' package is not installed.") from e
+
+        client = OpenAI(api_key=self._openai_key)
+        max_tokens = opts.pop("max_tokens", 2048)
+        temperature = opts.pop("temperature", 0.3)
+
+        response = client.chat.completions.create(
+            model=self._openai_model,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            **opts,
+        )
+        return response.choices[0].message.content or ""
+
+    def _complete_anthropic(self, prompt: str, **opts: Any) -> str:
+        try:
+            import anthropic  # type: ignore[import]
+        except ImportError as e:
+            raise ImportError("skillmem: 'anthropic' package is not installed.") from e
+
+        client = anthropic.Anthropic(api_key=self._anthropic_key)
+        max_tokens = opts.pop("max_tokens", 2048)
+
+        message = client.messages.create(
+            model=self._anthropic_model,
+            max_tokens=max_tokens,
+            messages=[{"role": "user", "content": prompt}],
+            **opts,
+        )
+        # Extract text from the first text block
+        for block in message.content:
+            if hasattr(block, "text"):
+                return block.text
+        return ""
+
+
+# ── Convenience factory ───────────────────────────────────────────────────────
+
+def build_connector(config: "Any") -> RemoteConnector:
+    """Build a RemoteConnector from a Config object."""
+    return RemoteConnector(
+        provider=config.llm_provider,
+        openai_api_key=config.openai_api_key,
+        openai_model=config.openai_model,
+        anthropic_api_key=config.anthropic_api_key,
+        anthropic_model=config.anthropic_model,
+    )