atomir 0.1.0__py3-none-any.whl

atomir/__init__.py

@@ -0,0 +1,9 @@
+"""atomir — atomic memory infrastructure for agents.
+
+Memory is atomic on both ends: atomic facts on write, atomic sub-question
+decomposition on read. This package is built inside-out (engine → storage →
+multi-tenancy → API → packaging) and is vendor-neutral: the LLM, embedder, and
+vector store are each an interface chosen at runtime by config.
+"""
+
+__version__ = "0.0.0"

atomir/api.py

@@ -0,0 +1,68 @@
+"""HTTP surface over the engine (FastAPI). A thin adapter, no business logic.
+
+Endpoints unpack a request, call ONE `MemoryService` method, and return its
+result. Handlers are plain `def` (not `async def`) so Starlette runs the
+blocking engine work in a threadpool instead of stalling the event loop; the
+per-user lock inside `MemoryService` keeps same-user writes correct across those
+threads.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException, Query
+from pydantic import BaseModel
+
+from atomir.assembly import build_memory_service
+from atomir.config import settings
+
+service = build_memory_service()
+app = FastAPI(title="atomir", version="0.1.0")
+
+
+class AddBody(BaseModel):
+    user_id: str
+    text: str
+
+
+class SearchBody(BaseModel):
+    user_id: str
+    query: str
+    k: int = 6
+    decompose: bool = True
+
+
+@app.post("/memories")
+def add_memories(body: AddBody) -> dict:
+    return service.add(body.user_id, body.text)
+
+
+@app.post("/search")
+def search(body: SearchBody) -> dict:
+    return service.search(body.user_id, body.query, k=body.k, decompose=body.decompose)
+
+
+@app.get("/memories")
+def get_all(user_id: str = Query(...)) -> list[dict]:
+    return service.get_all(user_id)
+
+
+@app.delete("/memories/{fact_id}")
+def delete_one(fact_id: str, user_id: str = Query(...)) -> dict:
+    if not service.delete(user_id, fact_id):
+        raise HTTPException(status_code=404, detail="fact not found for this user")
+    return {"deleted": True, "id": fact_id}
+
+
+@app.delete("/memories")
+def reset(user_id: str = Query(...)) -> dict:
+    return {"reset": service.reset(user_id)}
+
+
+@app.get("/health")
+def health() -> dict:
+    return {
+        "status": "ok",
+        "store": settings.store_backend,
+        "llm": settings.llm_backend,
+        "embedder": settings.embed_backend,
+    }

atomir/assembly.py

@@ -0,0 +1,41 @@
+"""Assembly: build a `MemoryService` from config.
+
+This is the OUTERMOST wiring layer — the one place allowed to name concrete
+backends. It selects the LLM and embedder through their factories and the store
+through a small backend switch, then injects all three into the (vendor-neutral)
+`MemoryService`. Concrete backends are imported lazily so building a fake/JSON
+service never requires an unused provider SDK.
+"""
+
+from __future__ import annotations
+
+from atomir.config import Settings
+from atomir.config import make_qdrant_client
+from atomir.config import settings as default_settings
+from atomir.memory import MemoryService
+from atomir.providers import EmbedderFactory, LLMFactory
+from atomir.store_base import MemoryStore
+
+
+def _build_store(s: Settings) -> MemoryStore:
+    provider = s.store_backend
+    if provider == "qdrant":
+        from atomir.stores.qdrant_store import QdrantMemoryStore
+
+        return QdrantMemoryStore(make_qdrant_client(), s.collection, s.embed_dim)
+    if provider == "json":
+        from atomir.stores.json_store import JsonMemoryStore
+
+        path = s.store_path if s.store_path.endswith(".json") else "./atomir_store.json"
+        return JsonMemoryStore(path=path)
+    raise ValueError(
+        f"Unknown store backend {provider!r}. Valid backends: ['qdrant', 'json']"
+    )
+
+
+def build_memory_service(s: Settings = default_settings) -> MemoryService:
+    """Construct a MemoryService with providers/backend selected purely by config."""
+    llm = LLMFactory.create(s.llm)
+    embedder = EmbedderFactory.create(s.embedder)
+    store = _build_store(s)
+    return MemoryService(store, llm, embedder, reconcile_min_sim=s.reconcile_min_sim)

atomir/atomic_read.py

@@ -0,0 +1,76 @@
+"""Atomic READ: answer a question by querying memory atomically.
+
+The read-side twin of the write engine. Instead of embedding a whole question
+as one blob, a planner may decompose it into atomic sub-questions; each is
+retrieved independently and the results are unioned (deduped by fact id, best
+score kept). Vendor-neutral: imports ONLY the injected interfaces.
+"""
+
+from __future__ import annotations
+
+from atomir.providers.embedder_base import Embedder
+from atomir.providers.llm_base import LLM
+from atomir.store_base import MemoryStore
+
+_PLAN_SYSTEM = (
+    "You are a query planner for a personal-memory system. Decide whether a "
+    "question must be broken into atomic sub-questions to answer it.\n"
+    "- SIMPLE single-fact question -> decompose=false and subquestions=[the "
+    "original question verbatim].\n"
+    "- MULTI-HOP question (the answer depends on an intermediate fact, e.g. a "
+    "person, project, or relationship you must resolve first) -> decompose=true "
+    "with atomic wh- sub-questions, INCLUDING the intermediate facts.\n\n"
+    "Examples:\n"
+    'Q: "where does the user live?"\n'
+    '{"decompose": false, "subquestions": ["where does the user live?"]}\n'
+    'Q: "what gift should I buy my sister?"\n'
+    '{"decompose": true, "subquestions": ["who is the user\'s sister?", '
+    '"what does the user\'s sister like?"]}\n\n'
+    "Respond ONLY with JSON: "
+    '{"decompose": <true|false>, "subquestions": ["...", "..."]}'
+)
+
+
+def plan(llm: LLM, query: str) -> dict:
+    """Decide whether/how to decompose `query`. Always returns >=1 subquestion."""
+    result = llm.chat_json(_PLAN_SYSTEM, query)
+    decompose = bool(result.get("decompose", False))
+    subs = [
+        s.strip()
+        for s in (result.get("subquestions") or [])
+        if isinstance(s, str) and s.strip()
+    ]
+    if not subs:  # planner gave nothing usable -> fall back to the raw query
+        subs, decompose = [query], False
+    return {"decompose": decompose, "subquestions": subs}
+
+
+def atomic_search(
+    store: MemoryStore,
+    llm: LLM,
+    embedder: Embedder,
+    user_id: str,
+    query: str,
+    k: int = 6,
+    decompose: bool = True,
+) -> dict:
+    """Retrieve facts for `query`, decomposing into sub-questions when useful.
+
+    Returns {"subquestions": [...], "results": [...]} — sub-questions are
+    exposed deliberately (the differentiator, and a debugging aid).
+    """
+    subquestions = plan(llm, query)["subquestions"] if decompose else [query]
+
+    # Each sub-question is embedded as a QUERY (here the input really is a
+    # question) and retrieved independently. These retrievals are mutually
+    # independent -> safe to run concurrently (deferred to Step 9); sequential
+    # here for determinism.
+    best_by_id: dict[str, dict] = {}
+    for sq in subquestions:
+        for hit in store.search(user_id, embedder.embed_query(sq), k=k):
+            hid = hit["id"]
+            if hid not in best_by_id or hit["score"] > best_by_id[hid]["score"]:
+                best_by_id[hid] = hit
+
+    results = sorted(best_by_id.values(), key=lambda h: h["score"], reverse=True)[:k]
+    return {"subquestions": subquestions, "results": results}

atomir/client.py

@@ -0,0 +1,64 @@
+"""Client SDK: adoption in one import.
+
+`MemoryClient` mirrors the HTTP API (and the `MemoryService` facade) method for
+method, with IDENTICAL return shapes — so callers can move between the library,
+the service, and this SDK without changing code. Built on stdlib urllib, so the
+SDK adds no dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import urlencode
+
+
+class MemoryClient:
+    """Thin REST wrapper around an atomir API server."""
+
+    def __init__(self, base_url: str = "http://localhost:8000", timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, *, body: dict | None = None, params: dict | None = None):
+        url = self.base_url + path
+        if params:
+            url += "?" + urlencode(params)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={"Content-Type": "application/json"} if data is not None else {},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:300]
+            raise RuntimeError(
+                f"atomir API {method} {path} failed: {e.code} {e.reason} — {detail}"
+            ) from e
+
+    def add(self, user_id: str, text: str) -> dict:
+        return self._request("POST", "/memories", body={"user_id": user_id, "text": text})
+
+    def search(self, user_id: str, query: str, k: int = 6, decompose: bool = True) -> dict:
+        return self._request(
+            "POST", "/search",
+            body={"user_id": user_id, "query": query, "k": k, "decompose": decompose},
+        )
+
+    def get_all(self, user_id: str) -> list[dict]:
+        return self._request("GET", "/memories", params={"user_id": user_id})
+
+    def delete(self, user_id: str, fact_id: str) -> dict:
+        return self._request("DELETE", f"/memories/{fact_id}", params={"user_id": user_id})
+
+    def reset(self, user_id: str) -> dict:
+        return self._request("DELETE", "/memories", params={"user_id": user_id})
+
+    def health(self) -> dict:
+        return self._request("GET", "/health")

atomir/config.py

@@ -0,0 +1,112 @@
+"""Centralized, vendor-neutral configuration.
+
+12-factor (factor III): all config that varies between deploys — keys, model
+names, URLs, paths — is read from the environment, never hardcoded. A local
+`.env` file is loaded for convenience in development.
+
+The design exposes THREE independent, swappable provider slots — `llm`,
+`embedder`, and `vector_store` — each as a mem0-style `{provider, config}`
+block. No vendor is privileged: whichever providers the environment selects are
+the ones used. The first-run example happens to be Groq + Jina + Qdrant, but
+each is just one value of an interface that gets formalized in later steps.
+
+Defaults favor running with NO external keys: both the LLM and embedder default
+to the `fake` backend so the system is testable offline.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+from dotenv import load_dotenv
+
+# Load .env into os.environ if present (no error if the file is missing).
+load_dotenv()
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default)
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable snapshot of configuration read from the environment."""
+
+    # --- LLM slot ---------------------------------------------------------
+    # Field names stay vendor-neutral: `llm_backend` selects the impl, and the
+    # key/model are read into generic fields. `groq` is just the first example.
+    llm_backend: str = field(default_factory=lambda: _env("LLM_BACKEND", "fake"))
+    llm_api_key: str = field(default_factory=lambda: _env("LLM_API_KEY"))
+    model: str = field(default_factory=lambda: _env("MODEL", "llama-3.3-70b-versatile"))
+
+    # --- Embedder slot ----------------------------------------------------
+    # Same neutrality: `jina` is the first example, but nothing here names it.
+    embed_backend: str = field(default_factory=lambda: _env("EMBED_BACKEND", "fake"))
+    embed_api_key: str = field(default_factory=lambda: _env("EMBED_API_KEY"))
+    # Dimension travels WITH the embedder choice (Jina v3 = 1024).
+    embed_dim: int = field(default_factory=lambda: int(_env("EMBED_DIM", "1024")))
+
+    # --- Reconciler tuning ------------------------------------------------
+    # Write-side similarity gate (DECISION #1a): a candidate whose nearest
+    # existing fact scores below this is ADDed directly, without asking the LLM.
+    reconcile_min_sim: float = field(
+        default_factory=lambda: float(_env("RECONCILE_MIN_SIM", "0.6"))
+    )
+
+    # --- Vector store slot ------------------------------------------------
+    # Selected by `store_backend` like the other two slots (no hardcoded vendor).
+    store_backend: str = field(default_factory=lambda: _env("STORE_BACKEND", "qdrant"))
+    collection: str = field(default_factory=lambda: _env("COLLECTION", "atomir_memories"))
+    # `url`/`path` are generic connection params (Qdrant uses both today).
+    store_url: str = field(default_factory=lambda: _env("STORE_URL"))
+    store_path: str = field(default_factory=lambda: _env("STORE_PATH", "./qdrant_data"))
+
+    # --- Vendor-neutral provider blocks (mem0-style {provider, config}) ---
+    # These are how the engine will eventually select implementations without
+    # ever naming a vendor. The factories that consume them arrive in Step 5.5.
+
+    @property
+    def llm(self) -> dict:
+        return {
+            "provider": self.llm_backend,
+            "config": {"api_key": self.llm_api_key, "model": self.model},
+        }
+
+    @property
+    def embedder(self) -> dict:
+        return {
+            "provider": self.embed_backend,
+            "config": {"api_key": self.embed_api_key, "embed_dim": self.embed_dim},
+        }
+
+    @property
+    def vector_store(self) -> dict:
+        return {
+            "provider": self.store_backend,
+            "config": {
+                "url": self.store_url,
+                "path": self.store_path,
+                "collection": self.collection,
+                "embed_dim": self.embed_dim,
+            },
+        }
+
+
+# A single shared instance importers use: `from atomir.config import settings`.
+settings = Settings()
+
+
+def make_qdrant_client():
+    """Build a QdrantClient from settings: server mode if a URL is set, else
+    embedded/local at the configured path (zero-ops).
+
+    The qdrant SDK is imported lazily so merely importing this config module
+    never requires the optional provider dependency (offline/fake path stays
+    dependency-free). Returns a `qdrant_client.QdrantClient`.
+    """
+    from qdrant_client import QdrantClient
+
+    if settings.store_url:
+        return QdrantClient(url=settings.store_url)
+    return QdrantClient(path=settings.store_path)

atomir/embeddings/__init__.py

@@ -0,0 +1,11 @@
+"""Embedder implementations.
+
+The formal `Embedder` interface is introduced in Step 5.5; for now these are
+concrete, duck-typed classes that all expose the same two methods:
+`embed_passage(text) -> list[float]` and `embed_query(text) -> list[float]`.
+"""
+
+from atomir.embeddings.fake import FakeEmbedder
+from atomir.embeddings.jina import JinaEmbedder
+
+__all__ = ["FakeEmbedder", "JinaEmbedder"]

atomir/embeddings/fake.py

@@ -0,0 +1,48 @@
+"""Fake embedder: deterministic, offline, no API key.
+
+Maps text -> a unit vector derived from a hash of the text. Both
+`embed_passage` and `embed_query` call the SAME underlying function, so the
+same text always yields the same vector — which lets exact-text lookups match
+in tests. This is the offline stand-in that lets the whole pipeline run with no
+keys, no network, and no cost.
+
+Pure stdlib on purpose: the offline path should depend on nothing external.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import random
+
+from atomir.providers.embedder_base import Embedder
+
+
+class FakeEmbedder(Embedder):
+    """Deterministic hash-based embedder for offline development and tests."""
+
+    def __init__(self, embed_dim: int = 1024) -> None:
+        self.embed_dim = embed_dim
+
+    @classmethod
+    def from_config(cls, config: dict) -> "FakeEmbedder":
+        return cls(embed_dim=config.get("embed_dim", 1024))
+
+    def _embed(self, text: str) -> list[float]:
+        # Empty / whitespace-only text has no content to embed -> zero vector.
+        if not text or not text.strip():
+            return [0.0] * self.embed_dim
+        # Seed a PRNG deterministically from the text's hash, draw a Gaussian
+        # vector, and normalize to unit length (a point on the unit sphere).
+        seed = int.from_bytes(hashlib.sha256(text.encode("utf-8")).digest(), "big")
+        rng = random.Random(seed)
+        vec = [rng.gauss(0.0, 1.0) for _ in range(self.embed_dim)]
+        norm = math.sqrt(sum(x * x for x in vec)) or 1.0
+        return [x / norm for x in vec]
+
+    def embed_passage(self, text: str) -> list[float]:
+        return self._embed(text)
+
+    def embed_query(self, text: str) -> list[float]:
+        # Same call as passage: fake mode is symmetric so exact text matches.
+        return self._embed(text)

atomir/embeddings/jina.py

@@ -0,0 +1,86 @@
+"""Jina embedder: ONE concrete example behind the (future) Embedder interface.
+
+`jina-embeddings-v3` is asymmetric — passages and queries are embedded with
+different task hints (`retrieval.passage` vs `retrieval.query`), which improves
+retrieval quality. A symmetric provider would point both methods at the same
+call; we keep both methods regardless so every embedder has the same shape.
+
+Uses stdlib `urllib` (no new dependency) so simply importing this module never
+requires a provider SDK. The network is only touched when a method is called.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from atomir.providers.embedder_base import Embedder
+
+_JINA_URL = "https://api.jina.ai/v1/embeddings"
+# A named User-Agent avoids Cloudflare's default-urllib-UA block (see groq.py).
+_USER_AGENT = "atomir/0.1"
+
+
+class JinaEmbedder(Embedder):
+    """Calls the Jina embeddings API. Requires an API key."""
+
+    def __init__(
+        self,
+        api_key: str,
+        embed_dim: int = 1024,
+        model: str = "jina-embeddings-v3",
+    ) -> None:
+        # Clear failure if a real provider is selected without its key.
+        if not api_key:
+            raise ValueError(
+                "JinaEmbedder requires an API key. Set EMBED_API_KEY, or use "
+                "EMBED_BACKEND=fake to run offline with no key."
+            )
+        self.api_key = api_key
+        self.embed_dim = embed_dim
+        self.model = model
+
+    @classmethod
+    def from_config(cls, config: dict) -> "JinaEmbedder":
+        return cls(
+            api_key=config.get("api_key", ""),
+            embed_dim=config.get("embed_dim", 1024),
+            model=config.get("model", "jina-embeddings-v3"),
+        )
+
+    def _embed(self, text: str, task: str) -> list[float]:
+        if not text or not text.strip():
+            return [0.0] * self.embed_dim
+        payload = json.dumps(
+            {
+                "model": self.model,
+                "task": task,
+                "dimensions": self.embed_dim,
+                "input": [text],
+            }
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            _JINA_URL,
+            data=payload,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": _USER_AGENT,
+            },
+        )
+        try:
+            with urllib.request.urlopen(req) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(
+                f"Jina embedding request failed: {e.code} {e.reason}"
+            ) from e
+        return body["data"][0]["embedding"]
+
+    def embed_passage(self, text: str) -> list[float]:
+        return self._embed(text, "retrieval.passage")
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._embed(text, "retrieval.query")

atomir/extractor.py

@@ -0,0 +1,34 @@
+"""Atomic WRITE, stage 1: raw text -> a list of atomic facts.
+
+Vendor-neutral engine code: it depends ONLY on the injected `LLM` interface,
+never on a concrete provider. Works for user messages and for agent-confirmed
+findings alike (pass role="assistant").
+"""
+
+from __future__ import annotations
+
+from atomir.providers.llm_base import LLM
+
+_EXTRACT_SYSTEM = (
+    "You extract durable, ATOMIC, self-contained facts from a message.\n"
+    "Rules:\n"
+    "- Write each fact in the THIRD person (e.g. 'The user is vegetarian').\n"
+    "- ATOMIC: exactly one fact per item; split compound statements apart.\n"
+    "- SELF-CONTAINED: understandable without the original message.\n"
+    "- DURABLE: skip greetings, chit-chat, and transient remarks.\n"
+    'Return ONLY JSON of the form {"facts": ["...", "..."]}. '
+    "Use an empty list if nothing durable is present."
+)
+
+
+def extract_facts(llm: LLM, text: str, role: str = "user") -> list[str]:
+    """Return atomic facts extracted from `text`. Empty list if none/blank."""
+    text = (text or "").strip()
+    if not text:
+        return []
+    # All framing lives in the system prompt; the user content is the raw
+    # message only (keeps the content clean for any LLM to reason over).
+    system = f"{_EXTRACT_SYSTEM}\n(The message was written by the {role}.)"
+    result = llm.chat_json(system, text)
+    facts = result.get("facts", [])
+    return [f.strip() for f in facts if isinstance(f, str) and f.strip()]

atomir/llm/__init__.py

@@ -0,0 +1,11 @@
+"""LLM implementations.
+
+The formal `LLM` interface is introduced in Step 5.5; for now these are
+concrete, duck-typed classes exposing `chat_json`, `chat_text`, and `judge`.
+"""
+
+from atomir.llm.fake import FakeLLM
+from atomir.llm.groq import GroqLLM
+from atomir.llm.parsing import extract_json
+
+__all__ = ["FakeLLM", "GroqLLM", "extract_json"]

atomir/llm/fake.py

@@ -0,0 +1,46 @@
+"""Fake LLM: deterministic, offline, no API key.
+
+The third leg of the offline tripod (with the fake embedder and JSON store).
+Its default `chat_json` performs a naive "atomic extraction" — splitting the
+user text into sentence-like fragments under a `facts` key — so the write
+pipeline produces something real in fake mode. Tests can inject `canned` output
+to pin an exact response for any task.
+"""
+
+from __future__ import annotations
+
+import re
+
+from atomir.providers.llm_base import LLM
+
+
+def _split_sentences(text: str) -> list[str]:
+    parts = re.split(r"(?<=[.!?])\s+|\n+", text.strip())
+    return [p.strip() for p in parts if p.strip()]
+
+
+class FakeLLM(LLM):
+    """Deterministic stand-in LLM. Runs with no key, no network."""
+
+    def __init__(self, canned: dict | str | None = None) -> None:
+        # canned dict -> returned by chat_json; canned str -> returned by chat_text.
+        self.canned = canned
+
+    @classmethod
+    def from_config(cls, config: dict) -> "FakeLLM":
+        return cls()
+
+    def chat_json(self, system: str, user: str) -> dict:
+        if isinstance(self.canned, dict):
+            return dict(self.canned)
+        # Default: naive atomic extraction so the write pipeline works offline.
+        return {"facts": _split_sentences(user)}
+
+    def chat_text(self, system: str, user: str) -> str:
+        if isinstance(self.canned, str):
+            return self.canned
+        return user.strip()
+
+    def judge(self, rubric: str, content: str) -> tuple[bool, str]:
+        # Deterministic accept, so eval harness runs offline.
+        return True, "fake judge: accepted deterministically"