extremis 0.1.0__py3-none-any.whl

extremis/__init__.py

@@ -0,0 +1,15 @@
+from .api import Extremis
+from .client import HostedClient
+from .config import Config
+from .types import FeedbackSignal, LogEntry, Memory, MemoryLayer, RecallResult
+
+__all__ = [
+    "Extremis",
+    "HostedClient",
+    "Config",
+    "Memory",
+    "MemoryLayer",
+    "LogEntry",
+    "RecallResult",
+    "FeedbackSignal",
+]

extremis/api.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+from uuid import UUID
+
+from .config import Config
+from .embeddings.sentence_transformers import SentenceTransformerEmbedder
+from .interfaces import Embedder, LogStore, MemoryStore
+from .observer.observer import HeuristicObserver
+from .scorer.attention import AttentionScorer
+from .storage.kg import SQLiteKGStore
+from .storage.log import FileLogStore
+from .storage.sqlite import SQLiteMemoryStore
+from .types import (
+    AttentionResult,
+    EntityResult,
+    EntityType,
+    FeedbackSignal,
+    LogEntry,
+    Memory,
+    MemoryLayer,
+    Observation,
+    RecallResult,
+)
+
+_NEGATIVE_WEIGHT_MULTIPLIER = 1.5  # match friday-saas asymmetric RL weighting
+
+
+def _build_store(config: Config) -> MemoryStore:
+    """Select and initialise the memory store from config."""
+    if config.store == "postgres":
+        if not config.postgres_url:
+            raise ValueError("EXTREMIS_STORE=postgres requires EXTREMIS_POSTGRES_URL to be set.")
+        from .storage.postgres import PostgresMemoryStore
+
+        return PostgresMemoryStore(config.postgres_url, config)
+    if config.store == "chroma":
+        from .storage.chroma import ChromaMemoryStore
+
+        return ChromaMemoryStore(config.resolved_chroma_path(), config)
+    if config.store == "pinecone":
+        if not config.pinecone_api_key:
+            raise ValueError("EXTREMIS_STORE=pinecone requires EXTREMIS_PINECONE_API_KEY to be set.")
+        from .storage.pinecone_store import PineconeMemoryStore
+
+        return PineconeMemoryStore(
+            config.pinecone_api_key,
+            config.pinecone_index,
+            config,
+            score_db_path=config.resolved_pinecone_score_db(),
+        )
+    return SQLiteMemoryStore(config.resolved_local_db_path(), config)
+
+
+def _build_embedder(config: Config) -> Embedder:
+    """Select embedder based on model name."""
+    if config.embedder.startswith("text-embedding"):
+        from .embeddings.openai import OpenAIEmbedder
+
+        return OpenAIEmbedder(config.embedder, config.openai_api_key or None)
+    return SentenceTransformerEmbedder(config.embedder)
+
+
+class Extremis:
+    """
+    The three methods agents actually call: remember, recall, report_outcome.
+    Plus remember_now for time-sensitive direct writes.
+    """
+
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        log: Optional[LogStore] = None,
+        local: Optional[MemoryStore] = None,
+        embedder: Optional[Embedder] = None,
+    ) -> None:
+        self._config = config or Config()
+        self._log = log or FileLogStore(
+            self._config.resolved_log_dir(),
+            namespace=self._config.namespace,
+        )
+        self._local = local or _build_store(self._config)
+        self._embedder = embedder or _build_embedder(self._config)
+        self._kg = SQLiteKGStore(self._config.resolved_local_db_path(), self._config)
+        self._observer = HeuristicObserver(namespace=self._config.namespace)
+        self._attention = AttentionScorer(self._config)
+
+    def remember(
+        self,
+        content: str,
+        role: str = "user",
+        conversation_id: str = "default",
+        metadata: Optional[dict] = None,
+    ) -> None:
+        """
+        Append to the log. Cheap path — no LLM, no embedding.
+        Also writes an episodic memory to the local store for immediate recall.
+        """
+        entry = LogEntry(
+            role=role,
+            content=content,
+            conversation_id=conversation_id,
+            metadata=metadata or {},
+        )
+        self._log.append(entry)
+
+        embedding = self._embedder.embed(content)
+        memory = Memory(
+            layer=MemoryLayer.EPISODIC,
+            content=content,
+            embedding=embedding,
+            metadata={"conversation_id": conversation_id, "role": role, **(metadata or {})},
+            validity_start=datetime.now(tz=timezone.utc),
+        )
+        self._local.store(memory)
+
+    def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        layers: Optional[list[MemoryLayer]] = None,
+        min_score: float = 0.0,
+    ) -> list[RecallResult]:
+        """
+        Layered retrieval:
+        - Identity layer always included (who the user is, invariants)
+        - Procedural layer always included (behavioral rules)
+        - Semantic + Episodic ranked by relevance × utility × recency
+        """
+        query_embedding = self._embedder.embed(query)
+
+        # Always pull identity + procedural regardless of layer filter
+        pinned_layers = [MemoryLayer.IDENTITY, MemoryLayer.PROCEDURAL]
+        pinned = self._local.search(
+            query_embedding,
+            layers=pinned_layers,
+            limit=5,
+            min_score=min_score,
+        )
+
+        # Ranked recall for semantic + episodic (or custom filter)
+        search_layers = layers or [MemoryLayer.SEMANTIC, MemoryLayer.EPISODIC]
+        search_layers = [layer for layer in search_layers if layer not in pinned_layers]
+
+        ranked = self._local.search(
+            query_embedding,
+            layers=search_layers,
+            limit=limit,
+            min_score=min_score,
+        )
+
+        # Merge: pinned first (deduped), then ranked
+        seen: set[UUID] = set()
+        results: list[RecallResult] = []
+        for r in pinned + ranked:
+            if r.memory.id not in seen:
+                seen.add(r.memory.id)
+                results.append(r)
+
+        return results[:limit]
+
+    def report_outcome(
+        self,
+        memory_ids: list[UUID],
+        success: bool,
+        weight: float = 1.0,
+    ) -> None:
+        """
+        RL signal. Adjusts utility scores on the referenced memories.
+        Negative signals are amplified by 1.5× (mirrors human memory asymmetry).
+        """
+        FeedbackSignal(memory_ids=memory_ids, success=success, weight=weight)
+        delta = weight if success else -(weight * _NEGATIVE_WEIGHT_MULTIPLIER)
+        for mid in memory_ids:
+            self._local.update_score(mid, delta)
+
+    def remember_now(
+        self,
+        content: str,
+        layer: MemoryLayer,
+        expires_at: Optional[datetime] = None,
+        confidence: float = 0.9,
+        metadata: Optional[dict] = None,
+    ) -> Memory:
+        """
+        Skip the log; write directly to structured memory.
+        Use for time-sensitive facts ('flight Thursday 6am') or high-confidence
+        identity/procedural rules that don't need to be derived from logs.
+        """
+        embedding = self._embedder.embed(content)
+        memory = Memory(
+            layer=layer,
+            content=content,
+            embedding=embedding,
+            confidence=confidence,
+            metadata=metadata or {},
+            validity_start=datetime.now(tz=timezone.utc),
+            validity_end=expires_at,
+        )
+        return self._local.store(memory)
+
+    # ------------------------------------------------------------------ #
+    # Knowledge graph
+    # ------------------------------------------------------------------ #
+
+    def kg_add_entity(
+        self,
+        name: str,
+        type: EntityType,
+        metadata: Optional[dict] = None,
+    ):
+        return self._kg.add_entity(name, type, metadata)
+
+    def kg_add_relationship(
+        self,
+        from_entity: str,
+        to_entity: str,
+        rel_type: str,
+        weight: float = 1.0,
+        metadata: Optional[dict] = None,
+    ):
+        return self._kg.add_relationship(from_entity, to_entity, rel_type, weight, metadata)
+
+    def kg_add_attribute(self, entity: str, key: str, value: str):
+        return self._kg.add_attribute(entity, key, value)
+
+    def kg_query(self, name: str) -> Optional[EntityResult]:
+        return self._kg.query_entity(name)
+
+    def kg_traverse(self, name: str, depth: int = 2) -> list[EntityResult]:
+        return self._kg.traverse(name, depth)
+
+    # ------------------------------------------------------------------ #
+    # Observer
+    # ------------------------------------------------------------------ #
+
+    def observe(self, conversation_id: str = "default") -> list[Observation]:
+        """Compress recent log entries for conversation_id into priority observations."""
+        all_entries = self._log.read_since(None)
+        entries = [e for e in all_entries if e.conversation_id == conversation_id]
+        return self._observer.compress(entries)
+
+    # ------------------------------------------------------------------ #
+    # Attention scoring
+    # ------------------------------------------------------------------ #
+
+    def score_attention(
+        self,
+        message: str,
+        sender: str = "",
+        channel: str = "dm",
+        owner_ids: Optional[set[str]] = None,
+        allowlist: Optional[set[str]] = None,
+        context: Optional[dict] = None,
+    ) -> AttentionResult:
+        return self._attention.score(
+            message,
+            sender=sender,
+            channel=channel,
+            owner_ids=owner_ids,
+            allowlist=allowlist,
+            context=context,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Internal accessors (used by consolidator, MCP server, tests)
+    # ------------------------------------------------------------------ #
+
+    def get_local_store(self) -> MemoryStore:
+        return self._local
+
+    def get_log(self) -> LogStore:
+        return self._log
+
+    def get_kg(self) -> SQLiteKGStore:
+        return self._kg

extremis/client.py

@@ -0,0 +1,248 @@
+"""
+HostedClient — drop-in replacement for Memory that talks to the extremis hosted API.
+
+All computation (embedding, search, RL scoring, KG, consolidation) runs server-side.
+No local database. No 90 MB model download.
+
+Usage:
+    from extremis import HostedClient
+
+    mem = HostedClient(api_key="extremis_sk_...")
+
+    # Exact same API as Memory
+    mem.remember("User is building a WhatsApp AI", conversation_id="conv_001")
+    results = mem.recall("WhatsApp product")
+    mem.report_outcome([r.memory.id for r in results], success=True)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from .types import (
+    AttentionResult,
+    EntityResult,
+    EntityType,
+    Memory,
+    MemoryLayer,
+    Observation,
+    RecallResult,
+)
+
+_CLOUD_URL = "https://api.extremis.com"  # not yet live — self-host with extremis-server
+
+
+class HostedClient:
+    """
+    Stateless HTTP client. Every call is a round-trip to a extremis server.
+
+    Self-host:
+        extremis-server serve --host 0.0.0.0 --port 8000
+        extremis-server create-key --namespace alice
+        mem = HostedClient(api_key="extremis_sk_...", base_url="http://localhost:8000")
+
+    Cloud (coming soon — join the waitlist at github.com/ashwanijha04/extremis):
+        mem = HostedClient(api_key="extremis_sk_...")
+
+    Install: pip install "extremis[client]"
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _CLOUD_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError("HostedClient requires httpx: pip install 'extremis[client]'") from None
+
+        self._base = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self._base,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    # ── Core memory ─────────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        content: str,
+        role: str = "user",
+        conversation_id: str = "default",
+        metadata: Optional[dict] = None,
+    ) -> None:
+        self._post(
+            "/v1/memories/remember",
+            {
+                "content": content,
+                "role": role,
+                "conversation_id": conversation_id,
+                "metadata": metadata or {},
+            },
+        )
+
+    def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        layers: Optional[list[MemoryLayer]] = None,
+        min_score: float = 0.0,
+    ) -> list[RecallResult]:
+        data = self._post(
+            "/v1/memories/recall",
+            {
+                "query": query,
+                "limit": limit,
+                "layers": [layer.value for layer in layers] if layers else None,
+                "min_score": min_score,
+            },
+        )
+        return [RecallResult(**r) for r in data["results"]]
+
+    def report_outcome(
+        self,
+        memory_ids: list[UUID],
+        success: bool,
+        weight: float = 1.0,
+    ) -> None:
+        self._post(
+            "/v1/memories/report",
+            {
+                "memory_ids": [str(m) for m in memory_ids],
+                "success": success,
+                "weight": weight,
+            },
+        )
+
+    def remember_now(
+        self,
+        content: str,
+        layer: MemoryLayer,
+        expires_at: Optional[datetime] = None,
+        confidence: float = 0.9,
+        metadata: Optional[dict] = None,
+    ) -> Memory:
+        data = self._post(
+            "/v1/memories/store",
+            {
+                "content": content,
+                "layer": layer.value,
+                "confidence": confidence,
+                "expires_at": expires_at.isoformat() if expires_at else None,
+                "metadata": metadata or {},
+            },
+        )
+        return Memory(**data)
+
+    def observe(self, conversation_id: str = "default") -> list[Observation]:
+        data = self._get("/v1/memories/observe", {"conversation_id": conversation_id})
+        return [Observation(**o) for o in data["observations"]]
+
+    def consolidate(self) -> dict:
+        return self._post("/v1/memories/consolidate", {})
+
+    # ── Knowledge graph ──────────────────────────────────────────────────────
+
+    def kg_add_entity(self, name: str, type: EntityType, metadata: Optional[dict] = None):
+        return self._post(
+            "/v1/kg/write",
+            {
+                "operation": "add_entity",
+                "name": name,
+                "entity_type": type.value,
+                "metadata": metadata or {},
+            },
+        )
+
+    def kg_add_relationship(
+        self,
+        from_entity: str,
+        to_entity: str,
+        rel_type: str,
+        weight: float = 1.0,
+        metadata: Optional[dict] = None,
+    ):
+        return self._post(
+            "/v1/kg/write",
+            {
+                "operation": "add_relationship",
+                "from_entity": from_entity,
+                "to_entity": to_entity,
+                "rel_type": rel_type,
+                "weight": weight,
+                "metadata": metadata or {},
+            },
+        )
+
+    def kg_add_attribute(self, entity: str, key: str, value: str):
+        return self._post(
+            "/v1/kg/write",
+            {
+                "operation": "add_attribute",
+                "name": entity,
+                "key": key,
+                "value": value,
+            },
+        )
+
+    def kg_query(self, name: str) -> Optional[EntityResult]:
+        data = self._post("/v1/kg/query", {"name": name, "traverse_depth": 0})
+        if data.get("result") is None:
+            return None
+        return EntityResult(**data["result"])
+
+    def kg_traverse(self, name: str, depth: int = 2) -> list[EntityResult]:
+        data = self._post("/v1/kg/query", {"name": name, "traverse_depth": depth})
+        return [EntityResult(**r) for r in data.get("results", [])]
+
+    # ── Attention ────────────────────────────────────────────────────────────
+
+    def score_attention(
+        self,
+        message: str,
+        sender: str = "",
+        channel: str = "dm",
+        owner_ids: Optional[set[str]] = None,
+        allowlist: Optional[set[str]] = None,
+        context: Optional[dict] = None,
+    ) -> AttentionResult:
+        ctx = context or {}
+        data = self._get(
+            "/v1/attention/score",
+            {
+                "message": message,
+                "sender": sender,
+                "channel": channel,
+                "owner_ids": ",".join(owner_ids or []),
+                "allowlist": ",".join(allowlist or []),
+                "ongoing": str(ctx.get("ongoing", False)).lower(),
+                "already_answered": str(ctx.get("already_answered", False)).lower(),
+            },
+        )
+        return AttentionResult(**data)
+
+    # ── HTTP helpers ─────────────────────────────────────────────────────────
+
+    def _post(self, path: str, body: dict) -> dict:
+        resp = self._http.post(path, json=body)
+        resp.raise_for_status()
+        return resp.json() if resp.content else {}
+
+    def _get(self, path: str, params: dict) -> dict:
+        resp = self._http.get(path, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()

extremis/config.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="EXTREMIS_", env_file=".env")
+
+    # ── Backend ─────────────────────────────────────────────────────
+    # "sqlite" | "postgres" | "chroma" | "pinecone"
+    store: str = "sqlite"
+
+    # ── Namespace ────────────────────────────────────────────────────
+    # Isolates one user/agent's memories from another.
+    # EXTREMIS_NAMESPACE=user_123 for per-user isolation on a shared server.
+    namespace: str = "default"
+
+    # ── SQLite ───────────────────────────────────────────────────────
+    extremis_home: str = "~/.extremis"
+    log_dir: str = ""  # defaults to {extremis_home}/log
+    local_db_path: str = ""  # defaults to {extremis_home}/local.db
+
+    # ── Postgres ─────────────────────────────────────────────────────
+    postgres_url: str = ""
+
+    # ── Chroma ───────────────────────────────────────────────────────
+    chroma_path: str = ""  # defaults to {extremis_home}/chroma
+
+    # ── Pinecone ─────────────────────────────────────────────────────
+    pinecone_api_key: str = ""
+    pinecone_index: str = "extremis"
+    pinecone_score_db: str = ""  # defaults to {extremis_home}/pinecone_scores.db
+
+    # ── Embeddings ───────────────────────────────────────────────────
+    # sentence-transformers model name  OR  OpenAI model name
+    # e.g. "all-MiniLM-L6-v2" or "text-embedding-3-small"
+    embedder: str = "all-MiniLM-L6-v2"
+    embedding_dim: int = 384
+    openai_api_key: str = ""  # used when embedder = "text-embedding-*"
+
+    # ── Consolidation ────────────────────────────────────────────────
+    consolidation_idle_minutes: int = 30
+    consolidation_daily_hour: int = 4
+    consolidation_model: str = "claude-haiku-4-5-20251001"
+    consolidation_hard_model: str = "claude-sonnet-4-6"
+
+    # ── Retrieval ranking ────────────────────────────────────────────
+    rl_alpha: float = 0.5
+    recency_half_life_days: int = 90
+
+    # ── Attention scorer ─────────────────────────────────────────────
+    attention_full_threshold: int = 75
+    attention_standard_threshold: int = 50
+    attention_minimal_threshold: int = 25
+
+    # ── Resolved paths ───────────────────────────────────────────────
+    def resolved_log_dir(self) -> str:
+        return self.log_dir or f"{self.extremis_home}/log"
+
+    def resolved_local_db_path(self) -> str:
+        return self.local_db_path or f"{self.extremis_home}/local.db"
+
+    def resolved_chroma_path(self) -> str:
+        return self.chroma_path or f"{self.extremis_home}/chroma"
+
+    def resolved_pinecone_score_db(self) -> str:
+        return self.pinecone_score_db or f"{self.extremis_home}/pinecone_scores.db"

extremis/consolidation/__init__.py

@@ -0,0 +1,3 @@
+from .consolidator import LLMConsolidator
+
+__all__ = ["LLMConsolidator"]