atomir 0.1.0__tar.gz

atomir-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bereket Tilahun Shimekit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atomir-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: atomir
+Version: 0.1.0
+Summary: Atomic memory infrastructure for agents — atomic facts on write, atomic sub-question decomposition on read.
+Author: bekiTil
+License: MIT License
+        
+        Copyright (c) 2026 Bereket Tilahun Shimekit
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: numpy>=1.26
+Provides-Extra: groq
+Provides-Extra: jina
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7; extra == "qdrant"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "api"
+Provides-Extra: all
+Requires-Dist: qdrant-client>=1.7; extra == "all"
+Requires-Dist: fastapi>=0.100; extra == "all"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "all"
+Dynamic: license-file
+
+# atomir
+
+Atomic memory infrastructure for agents. **Memory is atomic on both ends:**
+atomic facts on write (extract → reconcile), atomic sub-question decomposition on
+read (decompose → retrieve per sub-question → union).
+
+## The thesis
+
+Most memory systems store raw text blobs and retrieve with a single fuzzy
+similarity search. atomir does the opposite at both ends:
+
+- **Write** — a message is split into small, self-contained facts, and each is
+  *reconciled* into memory (ADD new, UPDATE a changed value keeping history,
+  DELETE what's no longer true, NOOP duplicates). A similarity gate biases toward
+  ADD so distinct facts never over-merge.
+- **Read** — a question is decomposed into atomic sub-questions (only when it
+  helps), each retrieved independently, then results are unioned. This surfaces
+  facts a single whole-question embedding misses.
+
+## Vendor-neutral by construction
+
+The LLM, the embedder, and the vector store are each an **interface** chosen at
+runtime by config (`{provider, config}` blocks). The engine imports only the
+interfaces — never a provider SDK or vendor name. Swapping Groq↔OpenAI,
+Jina↔Voyage, or Qdrant↔pgvector is one config change plus one small class.
+Defaults use `fake` backends, so everything runs with **no external keys**.
+
+## Install
+
+```bash
+pip install -e .                 # core (offline: fake LLM + fake embedder + JSON store)
+pip install -e ".[qdrant]"       # add the Qdrant backend
+pip install -e ".[api]"          # add the FastAPI server
+pip install -e ".[all]"          # everything
+```
+
+`groq` and `jina` need no extra — they call their HTTP APIs over the standard
+library.
+
+## Quickstart — embedded, no Docker
+
+Runs fully offline with the default `fake` backends:
+
+```python
+from atomir.assembly import build_memory_service
+
+mem = build_memory_service()                      # backends chosen by .env
+mem.add("user123", "I'm vegetarian and my manager is Dana Lopez.")
+mem.add("user123", "I'm working on Project Atlas.")
+
+hits = mem.search("user123", "who should I email about my project?")
+print(hits["subquestions"])                       # the sub-questions it asked
+for r in hits["results"]:
+    print(r["text"], round(r["score"], 3))
+
+mem.get_all("user123")
+mem.delete("user123", fact_id)
+mem.reset("user123")
+```
+
+To use real providers, copy `.env.example` to `.env` and set the keys/backends.
+
+## Production — Docker Compose (API + Qdrant server)
+
+```bash
+cp .env.example .env             # optional: add real keys; without it, LLM/embedder run fake
+docker compose up --build        # brings up the API and a Qdrant server
+```
+
+The API points at the Qdrant service via `STORE_URL=http://qdrant:6333`. Then:
+
+```bash
+curl -XPOST localhost:8000/memories -H 'content-type: application/json' \
+  -d '{"user_id":"u1","text":"My manager is Dana."}'
+curl -XPOST localhost:8000/search -H 'content-type: application/json' \
+  -d '{"user_id":"u1","query":"who is my manager?"}'
+```
+
+## HTTP endpoints
+
+| Method | Path | Body / query | Returns |
+|---|---|---|---|
+| POST | `/memories` | `{user_id, text}` | `{operations, facts}` |
+| POST | `/search` | `{user_id, query, k?, decompose?}` | `{subquestions, results}` |
+| GET | `/memories` | `?user_id=` | list of facts |
+| DELETE | `/memories/{id}` | `?user_id=` | `{deleted, id}` (404 if absent) |
+| DELETE | `/memories` | `?user_id=` | `{reset}` |
+| GET | `/health` | — | `{status, store, llm, embedder}` |
+
+`MemoryClient(base_url)` (in `atomir.client`) wraps these with the same method
+names and return shapes.
+
+## Configuration
+
+All config is read from the environment (see `.env.example`): `LLM_BACKEND`,
+`LLM_API_KEY`, `MODEL`, `EMBED_BACKEND`, `EMBED_API_KEY`, `EMBED_DIM`,
+`RECONCILE_MIN_SIM`, `STORE_BACKEND`, `COLLECTION`, `STORE_URL`, `STORE_PATH`.
+
+## Known limitations
+
+- **Reconciler threshold is untuned.** `RECONCILE_MIN_SIM` defaults to `0.6`; on
+  Jina, real "same-attribute" pairs measured ~0.6, so it sits right on the edge.
+  It should be tuned per embedder with the eval harness, not trusted as-is.
+- **The JSON backend is NOT crash-safe.** It rewrites the whole file without
+  atomic replace/fsync — dev and tests only. Use Qdrant for durable storage.
+- **No transactions.** Writes are serialized per user with a simple lock
+  (Step 9); full transactional rollback is deferred (DECISION #5).
+- **Read returns facts, not a composed answer.** `search` returns the relevant
+  facts and sub-questions; turning them into a final sentence is the caller's
+  LLM's job.

atomir-0.1.0/README.md

@@ -0,0 +1,110 @@
+# atomir
+
+Atomic memory infrastructure for agents. **Memory is atomic on both ends:**
+atomic facts on write (extract → reconcile), atomic sub-question decomposition on
+read (decompose → retrieve per sub-question → union).
+
+## The thesis
+
+Most memory systems store raw text blobs and retrieve with a single fuzzy
+similarity search. atomir does the opposite at both ends:
+
+- **Write** — a message is split into small, self-contained facts, and each is
+  *reconciled* into memory (ADD new, UPDATE a changed value keeping history,
+  DELETE what's no longer true, NOOP duplicates). A similarity gate biases toward
+  ADD so distinct facts never over-merge.
+- **Read** — a question is decomposed into atomic sub-questions (only when it
+  helps), each retrieved independently, then results are unioned. This surfaces
+  facts a single whole-question embedding misses.
+
+## Vendor-neutral by construction
+
+The LLM, the embedder, and the vector store are each an **interface** chosen at
+runtime by config (`{provider, config}` blocks). The engine imports only the
+interfaces — never a provider SDK or vendor name. Swapping Groq↔OpenAI,
+Jina↔Voyage, or Qdrant↔pgvector is one config change plus one small class.
+Defaults use `fake` backends, so everything runs with **no external keys**.
+
+## Install
+
+```bash
+pip install -e .                 # core (offline: fake LLM + fake embedder + JSON store)
+pip install -e ".[qdrant]"       # add the Qdrant backend
+pip install -e ".[api]"          # add the FastAPI server
+pip install -e ".[all]"          # everything
+```
+
+`groq` and `jina` need no extra — they call their HTTP APIs over the standard
+library.
+
+## Quickstart — embedded, no Docker
+
+Runs fully offline with the default `fake` backends:
+
+```python
+from atomir.assembly import build_memory_service
+
+mem = build_memory_service()                      # backends chosen by .env
+mem.add("user123", "I'm vegetarian and my manager is Dana Lopez.")
+mem.add("user123", "I'm working on Project Atlas.")
+
+hits = mem.search("user123", "who should I email about my project?")
+print(hits["subquestions"])                       # the sub-questions it asked
+for r in hits["results"]:
+    print(r["text"], round(r["score"], 3))
+
+mem.get_all("user123")
+mem.delete("user123", fact_id)
+mem.reset("user123")
+```
+
+To use real providers, copy `.env.example` to `.env` and set the keys/backends.
+
+## Production — Docker Compose (API + Qdrant server)
+
+```bash
+cp .env.example .env             # optional: add real keys; without it, LLM/embedder run fake
+docker compose up --build        # brings up the API and a Qdrant server
+```
+
+The API points at the Qdrant service via `STORE_URL=http://qdrant:6333`. Then:
+
+```bash
+curl -XPOST localhost:8000/memories -H 'content-type: application/json' \
+  -d '{"user_id":"u1","text":"My manager is Dana."}'
+curl -XPOST localhost:8000/search -H 'content-type: application/json' \
+  -d '{"user_id":"u1","query":"who is my manager?"}'
+```
+
+## HTTP endpoints
+
+| Method | Path | Body / query | Returns |
+|---|---|---|---|
+| POST | `/memories` | `{user_id, text}` | `{operations, facts}` |
+| POST | `/search` | `{user_id, query, k?, decompose?}` | `{subquestions, results}` |
+| GET | `/memories` | `?user_id=` | list of facts |
+| DELETE | `/memories/{id}` | `?user_id=` | `{deleted, id}` (404 if absent) |
+| DELETE | `/memories` | `?user_id=` | `{reset}` |
+| GET | `/health` | — | `{status, store, llm, embedder}` |
+
+`MemoryClient(base_url)` (in `atomir.client`) wraps these with the same method
+names and return shapes.
+
+## Configuration
+
+All config is read from the environment (see `.env.example`): `LLM_BACKEND`,
+`LLM_API_KEY`, `MODEL`, `EMBED_BACKEND`, `EMBED_API_KEY`, `EMBED_DIM`,
+`RECONCILE_MIN_SIM`, `STORE_BACKEND`, `COLLECTION`, `STORE_URL`, `STORE_PATH`.
+
+## Known limitations
+
+- **Reconciler threshold is untuned.** `RECONCILE_MIN_SIM` defaults to `0.6`; on
+  Jina, real "same-attribute" pairs measured ~0.6, so it sits right on the edge.
+  It should be tuned per embedder with the eval harness, not trusted as-is.
+- **The JSON backend is NOT crash-safe.** It rewrites the whole file without
+  atomic replace/fsync — dev and tests only. Use Qdrant for durable storage.
+- **No transactions.** Writes are serialized per user with a simple lock
+  (Step 9); full transactional rollback is deferred (DECISION #5).
+- **Read returns facts, not a composed answer.** `search` returns the relevant
+  facts and sub-questions; turning them into a final sentence is the caller's
+  LLM's job.

atomir-0.1.0/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-0.1.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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"]