icelake 0.1.0__py3-none-any.whl

icelake/__init__.py

@@ -0,0 +1,172 @@
+"""icelake: accurate, scalable agentic memory for Discord bots.
+
+Quickstart::
+
+    from icelake import DiscordMemory, MemoryConfig, MessageEvent
+
+    memory = DiscordMemory(MemoryConfig(
+        storage="sqlite:///memory.db",
+        llm="openai://$KEY@openrouter.ai/api/v1?model=google/gemini-2.5-flash",
+    ))
+    async with memory:
+        await memory.observe(event)
+        ctx = await memory.prompt_context(guild_id=g, asker_id=u, text=msg)
+        system_prompt += ctx.injection_block
+
+See docs/API.md for the complete consumer contract and docs/PLAN.md for design.
+"""
+
+from icelake.api.classify import CommandAction, UserMemoryCommand
+from icelake.api.client import DiscordMemory
+from icelake.config import (
+    BatchingConfig,
+    BudgetsConfig,
+    EmbeddingsConfig,
+    ExtractionConfig,
+    LifecycleConfig,
+    LlmConfig,
+    MemoryConfig,
+    MeterConfig,
+    ObserveConfig,
+    PrivacyConfig,
+    RetrievalConfig,
+    StorageConfig,
+    WorkersConfig,
+)
+from icelake.errors import (
+    BudgetExceededError,
+    ConfigError,
+    DiscordMemoryError,
+    FactNotFoundError,
+    IdentityAmbiguousError,
+    LlmCapabilityError,
+    SchemaValidationError,
+    StorageUnavailableError,
+    StructuredOutputError,
+    SubjectNotAllowedError,
+    WorkerNotRunningError,
+)
+from icelake.models import (
+    CHANNELS_ALL,
+    CHANNELS_DEFAULT,
+    CHANNELS_DISCOVERY,
+    Attribution,
+    AttributionType,
+    ChannelName,
+    Citation,
+    EdgeKind,
+    EntityRecord,
+    FactCategory,
+    FactHistoryEntry,
+    FactRecord,
+    GuildStats,
+    HealthReport,
+    IgnoreReason,
+    MemoryExport,
+    MemoryTier,
+    MessageEvent,
+    NeighborInfo,
+    NodeType,
+    ObserveReceipt,
+    ObserveStatus,
+    Polarity,
+    PromptContext,
+    PurgeReport,
+    RecallQuery,
+    RecallResult,
+    RecallWarning,
+    RejectReason,
+    RelationEdge,
+    Resolution,
+    ResolvedCandidate,
+    Scope,
+    ScoreComponents,
+    ScoredFact,
+    SourceRef,
+    StanceSummary,
+    channels,
+)
+from icelake.models.events import (
+    BatchCompleted,
+    BudgetWarning,
+    ComponentDegraded,
+    ExtractionFailed,
+    FactCommitted,
+    FactSupersededEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CHANNELS_ALL",
+    "CHANNELS_DEFAULT",
+    "CHANNELS_DISCOVERY",
+    "Attribution",
+    "AttributionType",
+    "BatchCompleted",
+    "BatchingConfig",
+    "BudgetExceededError",
+    "BudgetWarning",
+    "BudgetsConfig",
+    "ChannelName",
+    "Citation",
+    "CommandAction",
+    "ComponentDegraded",
+    "ConfigError",
+    "DiscordMemory",
+    "DiscordMemoryError",
+    "EdgeKind",
+    "EmbeddingsConfig",
+    "EntityRecord",
+    "ExtractionConfig",
+    "ExtractionFailed",
+    "FactCategory",
+    "FactCommitted",
+    "FactHistoryEntry",
+    "FactNotFoundError",
+    "FactRecord",
+    "FactSupersededEvent",
+    "GuildStats",
+    "HealthReport",
+    "IdentityAmbiguousError",
+    "IgnoreReason",
+    "LifecycleConfig",
+    "LlmCapabilityError",
+    "LlmConfig",
+    "MemoryConfig",
+    "MemoryExport",
+    "MemoryTier",
+    "MessageEvent",
+    "MeterConfig",
+    "NeighborInfo",
+    "NodeType",
+    "ObserveConfig",
+    "ObserveReceipt",
+    "ObserveStatus",
+    "Polarity",
+    "PrivacyConfig",
+    "PromptContext",
+    "PurgeReport",
+    "RecallQuery",
+    "RecallResult",
+    "RecallWarning",
+    "RejectReason",
+    "RelationEdge",
+    "Resolution",
+    "ResolvedCandidate",
+    "RetrievalConfig",
+    "SchemaValidationError",
+    "Scope",
+    "ScoreComponents",
+    "ScoredFact",
+    "SourceRef",
+    "StanceSummary",
+    "StorageConfig",
+    "StorageUnavailableError",
+    "StructuredOutputError",
+    "SubjectNotAllowedError",
+    "UserMemoryCommand",
+    "WorkerNotRunningError",
+    "WorkersConfig",
+    "channels",
+]

icelake/_json.py

@@ -0,0 +1,125 @@
+"""LLM JSON extraction with staged repair (ported from bot utils/llm_json.py).
+
+Ladder: fence strip -> balanced-object scan (string/escape-aware) -> truncation
+repair (closes open strings + bracket stack) -> candidate slicing. A truncated
+extraction response should lose nothing recoverable.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Final
+
+_FENCES: Final = (("```json", "```"), ("```JSON", "```"), ("```", "```"))
+
+
+def _strip_fence(text: str) -> str:
+    stripped = text.strip()
+    for opening, closing in _FENCES:
+        if stripped.startswith(opening):
+            inner = stripped[len(opening) :]
+            end = inner.rfind(closing)
+            return (inner[:end] if end != -1 else inner).strip()
+    return stripped
+
+
+def _scan_balanced(text: str, start: int) -> str | None:
+    """Extract one balanced JSON object starting at ``text[start] == '{'``."""
+    depth = 0
+    in_string = False
+    escaped = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : index + 1]
+    return None
+
+
+def _close_open_constructs(candidate: str) -> str:
+    """Repair truncated JSON: close an open string literal, then brackets."""
+    in_string = False
+    escaped = False
+    stack: list[str] = []
+    for char in candidate:
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            stack.append("}")
+        elif char == "[":
+            stack.append("]")
+        elif char in {"}", "]"} and stack and stack[-1] == char:
+            stack.pop()
+    repaired = candidate
+    if escaped:
+        repaired += '"'
+    if in_string:
+        repaired += '"'
+    while stack:
+        repaired += stack.pop()
+    return repaired
+
+
+def parse_json_object(text: str) -> dict[str, object]:
+    """Parse the first JSON object in ``text`` with staged repair.
+
+    Raises ``ValueError`` only when no object can be recovered at all.
+    """
+    cleaned = _strip_fence(text)
+
+    direct_start = cleaned.find("{")
+    direct_end = cleaned.rfind("}")
+    if direct_start != -1 and direct_end > direct_start:
+        try:
+            parsed = json.loads(cleaned[direct_start : direct_end + 1])
+            if isinstance(parsed, dict):
+                return parsed
+        except json.JSONDecodeError:
+            pass
+
+    scanner_start = max(direct_start, 0)
+    while scanner_start != -1:
+        balanced = _scan_balanced(cleaned, scanner_start)
+        if balanced is not None:
+            try:
+                parsed = json.loads(balanced)
+                if isinstance(parsed, dict):
+                    return parsed
+            except json.JSONDecodeError:
+                pass
+        scanner_start = cleaned.find("{", scanner_start + 1)
+
+    if direct_start != -1:
+        truncated = _close_open_constructs(cleaned[direct_start:])
+        try:
+            parsed = json.loads(truncated)
+            if isinstance(parsed, dict):
+                return parsed
+        except json.JSONDecodeError:
+            pass
+
+    raise ValueError("no recoverable JSON object in response")
+
+
+__all__ = ["parse_json_object"]

icelake/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter packages. Only adapters import vendor SDKs (import-linter enforced)."""

icelake/adapters/embedders/__init__.py

@@ -0,0 +1,126 @@
+"""Embedding adapters: deterministic hashing (default) and OpenAI-compatible API.
+
+The hashing embedder is the zero-dependency default: signed feature-hashing over word
+and char n-grams, L2-normalized. Deterministic, fast, free — good lexical-ish
+semantics for small deployments and perfectly reproducible in tests. Swap to a real
+model via config without touching any other code.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+import httpx
+
+from icelake.config import EmbeddingsConfig, EmbeddingsProvider
+from icelake.errors import ConfigError
+
+if TYPE_CHECKING:
+    from icelake.ports.llm import Embedder
+
+
+class HashingEmbedder:
+    """Signed feature-hashing embedder; stable across processes."""
+
+    def __init__(self, dimensions: int = 256) -> None:
+        if dimensions < 32:
+            raise ConfigError("hashing embedder needs at least 32 dimensions")
+        self._dimensions = dimensions
+
+    @property
+    def dimensions(self) -> int:
+        return self._dimensions
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]:
+        return tuple(self._embed_one(text) for text in texts)
+
+    def _embed_one(self, text: str) -> tuple[float, ...]:
+        vector = [0.0] * self._dimensions
+        lowered = " ".join(text.lower().split())
+        tokens = lowered.split()
+        for token in tokens:
+            self._add_feature(vector, token, 1.0)
+        for i in range(len(tokens) - 1):
+            bigram = f"{tokens[i]}_{tokens[i + 1]}"
+            self._add_feature(vector, bigram, 0.7)
+        for i in range(max(0, len(lowered) - 3)):
+            self._add_feature(vector, "c:" + lowered[i : i + 4], 0.25)
+        norm = math.sqrt(sum(v * v for v in vector))
+        if norm == 0.0:
+            return tuple(vector)
+        return tuple(round(v / norm, 8) for v in vector)
+
+    def _add_feature(self, vector: list[float], feature: str, weight: float) -> None:
+        digest = hashlib.md5(feature.encode("utf-8")).digest()
+        index = int.from_bytes(digest[:4], "little") % self._dimensions
+        sign = 1.0 if digest[4] % 2 == 0 else -1.0
+        vector[index] += sign * weight
+
+
+class OpenAICompatEmbedder:
+    """OpenAI ``/embeddings``-compatible adapter (OpenRouter/OpenAI/vLLM/Ollama)."""
+
+    def __init__(self, config: EmbeddingsConfig) -> None:
+        if not config.base_url or not config.model:
+            raise ConfigError("openai embeddings require base_url and model")
+        self._config = config
+        self._client = httpx.AsyncClient(timeout=30.0)
+
+    @property
+    def dimensions(self) -> int:
+        return self._config.dimensions
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]:
+        out: list[tuple[float, ...]] = []
+        batch_size = 64
+        for start in range(0, len(texts), batch_size):
+            chunk = texts[start : start + batch_size]
+            response = await self._client.post(
+                f"{self._config.base_url}/embeddings",
+                headers=self._headers(),
+                json={"model": self._config.model, "input": list(chunk)},
+            )
+            response.raise_for_status()
+            payload = response.json()
+            data = sorted(payload["data"], key=lambda item: item["index"])
+            out.extend(tuple(float(x) for x in item["embedding"]) for item in data)
+        return tuple(out)
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self._config.api_key:
+            headers["Authorization"] = f"Bearer {self._config.api_key}"
+        return headers
+
+
+def build_embedder(config: EmbeddingsConfig) -> Embedder:
+    """Factory honoring the configured provider with a graceful local fallback."""
+    inner = _build_inner(config)
+    if config.cache_enabled:
+        from icelake.adapters.embedders.cached import CachedEmbedder
+
+        return CachedEmbedder(inner, max_entries=config.cache_max_entries)
+    return inner
+
+
+def _build_inner(config: EmbeddingsConfig) -> Embedder:
+    if config.provider is EmbeddingsProvider.HASHING:
+        return HashingEmbedder(config.dimensions)
+    if config.provider is EmbeddingsProvider.OPENAI:
+        return OpenAICompatEmbedder(config)
+    import importlib.util
+
+    if importlib.util.find_spec("sentence_transformers") is None:
+        raise ConfigError(
+            "local embeddings require the 'local-embeddings' extra "
+            "(pip install icelake[local-embeddings])",
+        )
+    from icelake.adapters.embedders.local import LocalEmbedder
+
+    return LocalEmbedder(config)
+
+
+__all__ = ["HashingEmbedder", "OpenAICompatEmbedder", "build_embedder"]

icelake/adapters/embedders/cached.py

@@ -0,0 +1,74 @@
+"""Embedding cache: content-hash LRU over any inner Embedder.
+
+Cuts recall-path latency and API cost when the same or similar texts are
+embedded repeatedly (query-embedding reuse, reconcile collision checks,
+consolidation sanity checks). Thread-safe; bounded by ``max_entries``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from collections import OrderedDict
+from collections.abc import Sequence
+
+from icelake.ports.llm import Embedder
+
+
+class CachedEmbedder:
+    """LRU-cached wrapper implementing the Embedder protocol."""
+
+    def __init__(self, inner: Embedder, *, max_entries: int = 50_000) -> None:
+        self._inner = inner
+        self._max_entries = max_entries
+        self._cache: OrderedDict[str, tuple[float, ...]] = OrderedDict()
+        self._lock = threading.Lock()
+        self.hits = 0
+        self.misses = 0
+
+    @property
+    def dimensions(self) -> int:
+        return self._inner.dimensions
+
+    @property
+    def hit_rate(self) -> float:
+        total = self.hits + self.misses
+        return self.hits / total if total else 0.0
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]:
+        keys = [self._key(text) for text in texts]
+        with self._lock:
+            cached: dict[int, tuple[float, ...]] = {}
+            missing_indices: list[int] = []
+            for index, key in enumerate(keys):
+                if key in self._cache:
+                    cached[index] = self._cache[key]
+                    self.hits += 1
+                else:
+                    missing_indices.append(index)
+                    self.misses += 1
+            # LRU touch for hits
+            for key in (keys[i] for i in cached):
+                self._cache.move_to_end(key)
+
+        if missing_indices:
+            uncached_texts = [texts[i] for i in missing_indices]
+            new_vectors = await self._inner.embed(uncached_texts)
+            for local_idx, vector in zip(missing_indices, new_vectors, strict=True):
+                cached[local_idx] = vector
+                with self._lock:
+                    self._cache[keys[local_idx]] = vector
+                    self._evict_if_needed()
+
+        return tuple(cached[i] for i in range(len(texts)))
+
+    def _evict_if_needed(self) -> None:
+        while len(self._cache) > self._max_entries:
+            self._cache.popitem(last=False)
+
+    @staticmethod
+    def _key(text: str) -> str:
+        return hashlib.sha256(text.encode()).hexdigest()
+
+
+__all__ = ["CachedEmbedder"]

icelake/adapters/embedders/local.py

@@ -0,0 +1,51 @@
+"""Optional sentence-transformers embedder (extra: ``local-embeddings``)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Protocol
+
+from icelake.config import EmbeddingsConfig
+
+if TYPE_CHECKING:
+    pass
+
+
+class _Model(Protocol):
+    def encode(self, sentences: list[str], show_progress_bar: bool) -> list[list[float]]: ...
+
+
+class LocalEmbedder:
+    """Runs a local sentence-transformers model off-loop in a single-thread executor."""
+
+    def __init__(self, config: EmbeddingsConfig) -> None:
+        self._config = config
+        self._model: _Model | None = None
+
+    @property
+    def dimensions(self) -> int:
+        return self._config.dimensions
+
+    def _load(self) -> _Model:
+        if self._model is None:
+            from sentence_transformers import SentenceTransformer
+
+            name = (self._config.model or "").removeprefix("sentence-transformers/")
+            model: Any = SentenceTransformer(name)
+            self._model = model
+        return self._model
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]:
+        if not texts:
+            return ()
+        model = await asyncio.to_thread(self._load)
+        vectors = await asyncio.to_thread(
+            model.encode,
+            list(texts),
+            False,
+        )
+        return tuple(tuple(float(x) for x in vector) for vector in vectors)
+
+
+__all__ = ["LocalEmbedder"]

icelake/adapters/in_memory/__init__.py

@@ -0,0 +1,10 @@
+"""In-memory adapter package exports."""
+
+from __future__ import annotations
+
+from icelake.adapters.in_memory.queue import InMemoryIngestQueue
+from icelake.adapters.in_memory.store import InMemoryStore
+from icelake.adapters.in_memory.vectors import InMemoryVectorIndex
+from icelake.ports.vectors import cosine
+
+__all__ = ["InMemoryIngestQueue", "InMemoryStore", "InMemoryVectorIndex", "cosine"]