xyberos-redis 0.1.0__tar.gz

xyberos_redis-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: xyberos-redis
+Version: 0.1.0
+Summary: Redis plugin (RFC-0019, M4): RedisVectorStore + RedisMemory + cache backing for CacheResponder
+License: Apache-2.0
+Keywords: xyberos,plugin,redis,vector,memory,cache,state
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: state
+Requires-Dist: redis; extra == "state"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: fakeredis; extra == "test"
+
+# xyberos-redis
+
+**Redis plugin — RFC-0019, M4.** `RedisVectorStore` + `RedisMemory` + cache
+backing for `CacheResponder`, all lazy-importing `redis`. Covers the
+`[state]` extra scope (cache + state + vector).
+
+## Install
+
+```bash
+pip install -e ./redis
+pip install redis               # or: pip install xyberos[state]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_redis import RedisPlugin
+
+app = create_app()
+app.load_plugin(RedisPlugin(url="redis://localhost:6379"))   # or set REDIS_URL
+
+vector = app.resolve("redis_vector")     # a VectorStore
+memory = app.resolve("redis_memory")     # a Memory
+cache  = app.resolve("redis_cache")      # exact-match string cache
+```
+
+`RedisPlugin(replace_defaults=True)` also swaps the app's `vector_store` /
+`memory` providers.
+
+### CacheResponder backing
+
+`RedisVectorStore` is a full `VectorStore`, so it plugs straight into the core
+`CacheResponder` for near-exact `prompt -> answer` caching:
+
+```python
+from xyberos.llm import HashEmbedder
+from xyberos.router import CacheResponder
+from xyberos_redis import RedisVectorStore
+
+responder = CacheResponder(store=RedisVectorStore(url="redis://localhost:6379"),
+                           embedder=HashEmbedder())
+responder.teach("what is xyberos?", "a cognitive platform")
+```
+
+## Design
+
+- **`RedisVectorStore`** — one Redis hash per namespace; vectors JSON-encoded;
+  queries scored with exact cosine (the same scan-and-score approach as the
+  stdlib `SqliteVectorStore`, so behavior — and parity — holds without needing
+  a RediSearch vector module).
+- **`RedisMemory`** — one entry per `store()` appended to a Redis list;
+  `retrieve()` returns `MemoryEntry`s oldest-first, mirroring `SqliteMemory`.
+- **`RedisStringCache`** — tiny exact-match `get/set/delete` with optional TTL.
+- `redis` is imported **lazily**; a clear `ProviderError` is raised when missing.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+Tests run against **fakeredis** (an in-memory redis-py client), so they need no
+Redis server; they skip cleanly when `redis`/`fakeredis` are absent. The vector
+parity tests run the exact scenarios the `SqliteVectorStore` reference passes.
+
+## Ship location
+
+`[state]` extra (`redis` already added to `pyproject.toml`).

xyberos_redis-0.1.0/README.md

@@ -0,0 +1,70 @@
+# xyberos-redis
+
+**Redis plugin — RFC-0019, M4.** `RedisVectorStore` + `RedisMemory` + cache
+backing for `CacheResponder`, all lazy-importing `redis`. Covers the
+`[state]` extra scope (cache + state + vector).
+
+## Install
+
+```bash
+pip install -e ./redis
+pip install redis               # or: pip install xyberos[state]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_redis import RedisPlugin
+
+app = create_app()
+app.load_plugin(RedisPlugin(url="redis://localhost:6379"))   # or set REDIS_URL
+
+vector = app.resolve("redis_vector")     # a VectorStore
+memory = app.resolve("redis_memory")     # a Memory
+cache  = app.resolve("redis_cache")      # exact-match string cache
+```
+
+`RedisPlugin(replace_defaults=True)` also swaps the app's `vector_store` /
+`memory` providers.
+
+### CacheResponder backing
+
+`RedisVectorStore` is a full `VectorStore`, so it plugs straight into the core
+`CacheResponder` for near-exact `prompt -> answer` caching:
+
+```python
+from xyberos.llm import HashEmbedder
+from xyberos.router import CacheResponder
+from xyberos_redis import RedisVectorStore
+
+responder = CacheResponder(store=RedisVectorStore(url="redis://localhost:6379"),
+                           embedder=HashEmbedder())
+responder.teach("what is xyberos?", "a cognitive platform")
+```
+
+## Design
+
+- **`RedisVectorStore`** — one Redis hash per namespace; vectors JSON-encoded;
+  queries scored with exact cosine (the same scan-and-score approach as the
+  stdlib `SqliteVectorStore`, so behavior — and parity — holds without needing
+  a RediSearch vector module).
+- **`RedisMemory`** — one entry per `store()` appended to a Redis list;
+  `retrieve()` returns `MemoryEntry`s oldest-first, mirroring `SqliteMemory`.
+- **`RedisStringCache`** — tiny exact-match `get/set/delete` with optional TTL.
+- `redis` is imported **lazily**; a clear `ProviderError` is raised when missing.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+Tests run against **fakeredis** (an in-memory redis-py client), so they need no
+Redis server; they skip cleanly when `redis`/`fakeredis` are absent. The vector
+parity tests run the exact scenarios the `SqliteVectorStore` reference passes.
+
+## Ship location
+
+`[state]` extra (`redis` already added to `pyproject.toml`).

xyberos_redis-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-redis"
+version = "0.1.0"
+description = "Redis plugin (RFC-0019, M4): RedisVectorStore + RedisMemory + cache backing for CacheResponder"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "redis", "vector", "memory", "cache", "state"]
+
+[project.optional-dependencies]
+state = ["redis"]
+test = ["pytest", "fakeredis"]
+
+[project.entry-points."xyberos.plugins"]
+redis = "xyberos_redis.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_redis"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_redis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xyberos_redis-0.1.0/tests/test_cache.py

@@ -0,0 +1,50 @@
+"""Tests for the Redis cache story: CacheResponder backing + string cache."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from xyberos.llm import HashEmbedder
+from xyberos.router import CacheResponder
+
+from xyberos_redis import RedisStringCache, RedisVectorStore
+
+
+@pytest.fixture()
+def client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+def test_redis_vector_store_backs_cache_responder(client):
+    """RedisVectorStore is a VectorStore, so it can back CacheResponder."""
+    responder = CacheResponder(
+        store=RedisVectorStore(client=client),
+        embedder=HashEmbedder(),
+        threshold=0.9,
+    )
+    responder.teach("what is xyberos?", "a cognitive platform")
+    assert responder.size == 1
+
+    answer = responder.respond(SimpleNamespace(prompt="what is xyberos?"))
+    assert answer == "a cognitive platform"
+    # A near-identical prompt also hits (exact-match embedding -> score 1.0).
+    assert responder.respond(SimpleNamespace(prompt="what is xyberos?")) is not None
+
+
+def test_redis_string_cache(client):
+    cache = RedisStringCache(client=client)
+    assert cache.get("k") is None
+    cache.set("k", "v")
+    assert cache.get("k") == "v"
+    cache.delete("k")
+    assert cache.get("k") is None
+
+
+def test_redis_string_cache_clear(client):
+    cache = RedisStringCache(client=client)
+    cache.set("a", "1")
+    cache.set("b", "2")
+    cache.clear()
+    assert cache.get("a") is None
+    assert cache.get("b") is None

xyberos_redis-0.1.0/tests/test_memory.py

@@ -0,0 +1,68 @@
+"""Tests for RedisMemory — unit + parity with SqliteMemory semantics."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from xyberos.memory import MemoryEntry, SqliteMemory
+
+from xyberos_redis import RedisMemory
+
+
+@pytest.fixture()
+def client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+@pytest.fixture()
+def memory(client):
+    return RedisMemory(client=client)
+
+
+def _ctx(prompt="hello", response="hi", metadata=None, plan=None, error=None):
+    return SimpleNamespace(
+        prompt=prompt, response=response, metadata=metadata, plan=plan, error=error
+    )
+
+
+def test_store_and_retrieve_in_order(memory):
+    memory.store(_ctx(prompt="first", response="one"))
+    memory.store(_ctx(prompt="second", response="two"))
+    entries = memory.retrieve(_ctx())
+    assert [e.prompt for e in entries] == ["first", "second"]
+    assert entries[0].response == "one"
+    assert entries[1].response == "two"
+
+
+def test_metadata_round_trip(memory):
+    memory.store(_ctx(prompt="q", response="a", metadata={"user": "baltz"}))
+    entry = memory.retrieve(_ctx())[0]
+    assert entry.metadata == {"user": "baltz"}
+
+
+def test_clear(memory):
+    memory.store(_ctx())
+    memory.clear()
+    assert memory.retrieve(_ctx()) == []
+
+
+def test_parity_with_sqlite_memory(client):
+    """RedisMemory and SqliteMemory must expose the same observable behavior."""
+    redis_mem = RedisMemory(client=client)
+    sqlite_mem = SqliteMemory(":memory:")
+    ctx = _ctx(prompt="q", response="a", metadata={"k": "v"}, plan={"step": 1})
+
+    redis_mem.store(ctx)
+    sqlite_mem.store(ctx)
+
+    redis_entries = redis_mem.retrieve(_ctx())
+    sqlite_entries = sqlite_mem.retrieve(_ctx())
+
+    assert len(redis_entries) == len(sqlite_entries) == 1
+    assert redis_entries[0].prompt == sqlite_entries[0].prompt == "q"
+    assert redis_entries[0].response == sqlite_entries[0].response == "a"
+    assert redis_entries[0].metadata == sqlite_entries[0].metadata == {"k": "v"}
+    assert redis_entries[0].plan == sqlite_entries[0].plan == {"step": 1}
+    assert redis_entries[0].created_at  # both record a timestamp

xyberos_redis-0.1.0/tests/test_parity.py

@@ -0,0 +1,50 @@
+"""M4 parity: RedisVectorStore must behave like SqliteVectorStore."""
+
+from __future__ import annotations
+
+import pytest
+from xyberos.vector import SqliteVectorStore
+
+from xyberos_redis import RedisVectorStore
+
+QUERY = [1.0, 0.0, 0.0, 0.0]
+
+
+def run_parity_scenarios(store) -> None:
+    """The full VectorStore contract; every adapter must pass these."""
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.8, 0.2, 0.0, 0.0], {"text": "beta"})
+    store.upsert("ns", "c", [0.5, 0.5, 0.0, 0.0], {"text": "gamma"})
+    store.upsert("other", "x", [1.0, 1.0, 1.0, 1.0], {"text": "other ns"})
+
+    hits = store.query("ns", QUERY, top_k=3)
+    assert [h.id for h in hits] == ["a", "b", "c"]
+    assert hits[0].payload["text"] == "alpha"
+    assert hits[0].score > hits[1].score > hits[2].score
+    assert len(store.query("ns", QUERY, top_k=1)) == 1
+
+    strict = store.query("ns", QUERY, top_k=3, threshold=0.99)
+    assert [h.id for h in strict] == ["a"]
+
+    store.delete("ns", "b")
+    assert [h.id for h in store.query("ns", QUERY, top_k=3)] == ["a", "c"]
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=2)] == ["x"]
+    assert all(abs(h.score) < 1e-6 for h in store.query("ns", [0.0, 0.0, 0.0, 1.0], top_k=2))
+
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha-v2"})
+    assert store.query("ns", QUERY, top_k=1)[0].payload["text"] == "alpha-v2"
+
+    store.clear("ns")
+    assert store.query("ns", QUERY, top_k=3) == []
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=1)] == ["x"]
+
+
+def test_sqlite_reference() -> None:
+    """The stdlib reference passes the same scenarios the adapters must match."""
+    run_parity_scenarios(SqliteVectorStore(":memory:"))
+
+
+def test_redis_parity():
+    pytest.importorskip("fakeredis")
+    client = pytest.importorskip("fakeredis").FakeStrictRedis()
+    run_parity_scenarios(RedisVectorStore(client=client))

xyberos_redis-0.1.0/tests/test_plugin.py

@@ -0,0 +1,46 @@
+"""Tests for loading the redis plugin into a Xyberos app."""
+
+from __future__ import annotations
+
+import pytest
+from xyberos import create_app
+
+from xyberos_redis import RedisPlugin
+
+
+@pytest.fixture()
+def client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+def test_plugin_conforms_to_contract():
+    plugin = RedisPlugin()
+    assert plugin.name == "redis"
+    assert callable(plugin.register) and callable(plugin.unregister)
+
+
+def test_plugin_registers_services(client):
+    app = create_app()
+    app.load_plugin(RedisPlugin(client=client, key_prefix="test"))
+    assert "redis_client" in app.registry.names
+    assert "redis_vector" in app.registry.names
+    assert "redis_memory" in app.registry.names
+    assert "redis_cache" in app.registry.names
+
+    vector = app.resolve("redis_vector")
+    vector.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+    assert vector.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=1)[0].payload["text"] == "alpha"
+
+    memory = app.resolve("redis_memory")
+    memory.store(type("Ctx", (), {"prompt": "q", "response": "a", "metadata": {}})())
+    assert memory.retrieve(type("Ctx", (), {})())[0].prompt == "q"
+
+    app.unload_plugin("redis")
+
+
+def test_replace_defaults(client):
+    app = create_app()
+    app.load_plugin(RedisPlugin(client=client, key_prefix="test", replace_defaults=True))
+    assert app.resolve("memory").__class__.__name__ == "RedisMemory"
+    assert app.resolve("vector_store").__class__.__name__ == "RedisVectorStore"
+    app.unload_plugin("redis")

xyberos_redis-0.1.0/tests/test_vector.py

@@ -0,0 +1,45 @@
+"""Unit tests for RedisVectorStore (fakeredis, no server needed)."""
+
+from __future__ import annotations
+
+import pytest
+
+from xyberos_redis import RedisVectorStore
+
+
+@pytest.fixture()
+def client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+@pytest.fixture()
+def store(client):
+    return RedisVectorStore(client=client)
+
+
+def test_upsert_and_query(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.0, 1.0, 0.0], {"text": "beta"})
+    hits = store.query("ns", [1.0, 0.0, 0.0], top_k=2)
+    assert hits[0].id == "a"
+    assert hits[0].payload["text"] == "alpha"
+
+
+def test_namespaces_isolated(store):
+    store.upsert("one", "a", [1.0, 0.0, 0.0], {"text": "one"})
+    store.upsert("two", "b", [0.0, 1.0, 0.0], {"text": "two"})
+    assert [h.id for h in store.query("one", [1.0, 0.0, 0.0])] == ["a"]
+    assert [h.id for h in store.query("two", [1.0, 0.0, 0.0])] == ["b"]
+
+
+def test_delete(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0])
+    store.upsert("ns", "b", [0.0, 1.0, 0.0, 0.0])
+    store.delete("ns", "a")
+    assert [h.id for h in store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=2)] == ["b"]
+
+
+def test_clear(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0])
+    store.clear("ns")
+    assert store.query("ns", [1.0, 0.0, 0.0, 0.0]) == []

xyberos_redis-0.1.0/xyberos_redis/__init__.py

@@ -0,0 +1,19 @@
+"""Redis plugin (RFC-0019, M4): vector store + memory + cache backing.
+
+* :class:`RedisVectorStore` — a :class:`~xyberos.contracts.VectorStore` backed
+  by Redis hashes (can also back :class:`~xyberos.router.CacheResponder`).
+* :class:`RedisMemory` — a :class:`~xyberos.contracts.Memory` backed by a Redis
+  list.
+* :class:`RedisStringCache` — a small exact-match string cache for ephemeral
+  state.
+
+``redis`` is imported lazily on first use and a clear ``ProviderError`` is
+raised when it is missing (``pip install xyberos[state]``).
+"""
+
+from .cache import RedisStringCache
+from .memory import RedisMemory
+from .plugin import RedisPlugin
+from .vector import RedisVectorStore
+
+__all__ = ["RedisMemory", "RedisPlugin", "RedisStringCache", "RedisVectorStore"]

xyberos_redis-0.1.0/xyberos_redis/cache.py

@@ -0,0 +1,80 @@
+"""A tiny exact-match string cache backed by Redis (lazy ``redis``).
+
+This covers the "ephemeral state" side of the RFC-0019 M4 Redis scope; the
+*vector* cache backing for :class:`~xyberos.router.CacheResponder` is provided
+by :class:`~xyberos_redis.RedisVectorStore` (a full ``VectorStore``), which can
+be passed as ``CacheResponder(store=..., embedder=...)`` for near-exact
+``prompt -> answer`` caching.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from xyberos.exceptions.provider import ProviderError
+
+
+def _require_redis() -> Any:
+    try:
+        redis = importlib.import_module("redis")
+    except ImportError as exc:
+        raise ProviderError(
+            "the 'redis' package is required; install it with "
+            "'pip install xyberos[state]'"
+        ) from exc
+    return redis
+
+
+class RedisStringCache:
+    """An exact-match ``key -> value`` string cache with optional TTL."""
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any | None = None,
+        key_prefix: str = "xyberos:cache",
+    ) -> None:
+        self._url = url
+        self._client = client
+        self._prefix = key_prefix
+
+    def start(self) -> None:
+        self._get_client()
+
+    def stop(self) -> None:
+        self._client = None
+
+    def get(self, key: str) -> str | None:
+        value = self._get_client().get(f"{self._prefix}:{key}")
+        if value is None:
+            return None
+        return value.decode("utf-8") if isinstance(value, bytes) else str(value)
+
+    def set(self, key: str, value: str, *, ttl: int | None = None) -> None:
+        client = self._get_client()
+        full_key = f"{self._prefix}:{key}"
+        client.set(full_key, value, ex=ttl)
+
+    def delete(self, key: str) -> None:
+        self._get_client().delete(f"{self._prefix}:{key}")
+
+    def clear(self) -> None:
+        keys = self._keys()
+        if keys:
+            self._get_client().delete(*keys)
+
+    def _keys(self) -> list[str]:
+        client = self._get_client()
+        pattern = f"{self._prefix}:*"
+        if hasattr(client, "keys"):
+            return [k.decode("utf-8") if isinstance(k, bytes) else str(k) for k in client.keys(pattern)]
+        return []
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        redis = _require_redis()
+        self._client = redis.from_url(self._url) if self._url else redis.Redis()
+        return self._client

xyberos_redis-0.1.0/xyberos_redis/memory.py

@@ -0,0 +1,104 @@
+"""Redis-backed :class:`~xyberos.contracts.Memory` (lazy ``redis``).
+
+Mirrors the stdlib ``SqliteMemory`` semantics: ``store`` appends one
+reconstructable snapshot (a ``MemoryEntry``) and ``retrieve`` returns all
+entries, oldest first, in insertion order. The list lives under
+``<prefix>:memory``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from xyberos.contracts.memory import Memory
+from xyberos.memory import MemoryEntry
+from xyberos.exceptions.provider import ProviderError
+
+
+def _require_redis() -> Any:
+    try:
+        redis = importlib.import_module("redis")
+    except ImportError as exc:
+        raise ProviderError(
+            "the 'redis' package is required; install it with "
+            "'pip install xyberos[state]'"
+        ) from exc
+    return redis
+
+
+def _decode(value: Any) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    return str(value)
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class RedisMemory(Memory):
+    """A :class:`Memory` backed by a Redis list (one row per ``store`` call)."""
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any | None = None,
+        key: str = "xyberos:memory",
+    ) -> None:
+        self._url = url
+        self._client = client
+        self._key = key
+
+    def start(self) -> None:
+        self._get_client()
+
+    def stop(self) -> None:
+        self._client = None
+
+    def retrieve(self, context: object) -> list[MemoryEntry]:
+        client = self._get_client()
+        raw_entries = client.lrange(self._key, 0, -1)
+        entries: list[MemoryEntry] = []
+        for raw in raw_entries:
+            record = json.loads(_decode(raw))
+            entries.append(
+                MemoryEntry(
+                    prompt=record.get("prompt"),
+                    response=record.get("response"),
+                    metadata=record.get("metadata") or {},
+                    plan=record.get("plan"),
+                    error=record.get("error"),
+                    created_at=record.get("created_at", ""),
+                )
+            )
+        return entries
+
+    def store(self, context: object) -> None:
+        client = self._get_client()
+        record = json.dumps(
+            {
+                "prompt": getattr(context, "prompt", None),
+                "response": getattr(context, "response", None),
+                "metadata": dict(getattr(context, "metadata", None) or {}),
+                "plan": getattr(context, "plan", None),
+                "error": getattr(context, "error", None),
+                "created_at": _utc_now(),
+            },
+            default=str,
+        )
+        client.rpush(self._key, record)
+
+    def clear(self) -> None:
+        client = self._get_client()
+        client.delete(self._key)
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        redis = _require_redis()
+        self._client = redis.from_url(self._url) if self._url else redis.Redis()
+        return self._client

xyberos_redis-0.1.0/xyberos_redis/plugin.py

@@ -0,0 +1,96 @@
+"""Redis plugin entry point (RFC-0019, M4)."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any
+
+from xyberos.contracts import Plugin
+from xyberos.exceptions.provider import ProviderError
+
+from .cache import RedisStringCache
+from .memory import RedisMemory
+from .vector import RedisVectorStore
+
+
+def _require_redis() -> Any:
+    try:
+        redis = importlib.import_module("redis")
+    except ImportError as exc:
+        raise ProviderError(
+            "the 'redis' package is required; install it with "
+            "'pip install xyberos[state]'"
+        ) from exc
+    return redis
+
+
+class RedisPlugin(Plugin):
+    """Registers Redis-backed services.
+
+    Registers named services ``redis_client``, ``redis_vector``,
+    ``redis_memory`` and ``redis_cache`` (all sharing one Redis client). When
+    ``replace_defaults=True`` it also replaces the app's ``vector_store`` and
+    ``memory`` providers. Configuration comes from explicit args, then
+    ``REDIS_URL`` / ``REDIS_PREFIX`` env vars.
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any | None = None,
+        key_prefix: str | None = None,
+        replace_defaults: bool = False,
+    ) -> None:
+        self._url = url or os.getenv("REDIS_URL")
+        self._client = client
+        self._prefix = key_prefix or os.getenv("REDIS_PREFIX") or "xyberos"
+        self._replace_defaults = replace_defaults
+
+    @property
+    def name(self) -> str:
+        return "redis"
+
+    def _shared_client(self) -> Any:
+        if self._client is None:
+            redis = _require_redis()
+            self._client = redis.from_url(self._url) if self._url else redis.Redis()
+        return self._client
+
+    def register(self, kernel: object) -> None:
+        client = self._shared_client()
+        kernel.register("redis_client", client, replace=True)
+        kernel.register(
+            "redis_vector",
+            RedisVectorStore(client=client, key_prefix=f"{self._prefix}:vs"),
+            replace=True,
+        )
+        kernel.register(
+            "redis_memory",
+            RedisMemory(client=client, key=f"{self._prefix}:memory"),
+            replace=True,
+        )
+        kernel.register(
+            "redis_cache",
+            RedisStringCache(client=client, key_prefix=f"{self._prefix}:cache"),
+            replace=True,
+        )
+        if self._replace_defaults:
+            kernel.register(
+                "vector_store",
+                RedisVectorStore(client=client, key_prefix=f"{self._prefix}:vs"),
+                replace=True,
+            )
+            kernel.register(
+                "memory",
+                RedisMemory(client=client, key=f"{self._prefix}:memory"),
+                replace=True,
+            )
+
+    def unregister(self, kernel: object) -> None:
+        pass
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = RedisPlugin()

xyberos_redis-0.1.0/xyberos_redis/vector.py

@@ -0,0 +1,135 @@
+"""Redis-backed :class:`~xyberos.contracts.VectorStore` (lazy ``redis``).
+
+Vectors are stored as JSON inside one Redis hash per namespace
+(``<prefix>:<namespace>``). On query the whole namespace is scanned and scored
+with exact cosine similarity — the same approach the stdlib
+``SqliteVectorStore`` uses (it also scans rows and computes cosine in Python),
+so behavior is identical and parity holds without requiring a RediSearch
+vector module.
+
+Because it is a full :class:`VectorStore`, it can be passed straight to
+:class:`~xyberos.router.CacheResponder(store=..., embedder=...)` for
+near-exact ``prompt -> answer`` caching.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from xyberos.contracts.vector import ScoredHit, VectorStore
+from xyberos.exceptions.provider import ProviderError
+
+
+def _require_redis() -> Any:
+    try:
+        redis = importlib.import_module("redis")
+    except ImportError as exc:
+        raise ProviderError(
+            "the 'redis' package is required; install it with "
+            "'pip install xyberos[state]'"
+        ) from exc
+    return redis
+
+
+def _decode(value: Any) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    return str(value)
+
+
+def _cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = sum(x * x for x in a) ** 0.5
+    norm_b = sum(x * x for x in b) ** 0.5
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+class RedisVectorStore(VectorStore):
+    """A :class:`VectorStore` backed by Redis hashes (one per namespace)."""
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any | None = None,
+        key_prefix: str = "xyberos:vs",
+    ) -> None:
+        self._url = url
+        self._client = client
+        self._prefix = key_prefix
+
+    def start(self) -> None:
+        """Connect to Redis (kernel lifecycle hook)."""
+        self._get_client()
+
+    def stop(self) -> None:
+        """Release the client (kernel lifecycle hook)."""
+        self._client = None
+
+    def upsert(
+        self,
+        namespace: str,
+        id: str,
+        vector: Sequence[float],
+        payload: Mapping[str, Any] | None = None,
+    ) -> None:
+        client = self._get_client()
+        record = json.dumps(
+            {"v": [float(value) for value in vector], "p": dict(payload or {})},
+            default=str,
+        )
+        client.hset(self._key(namespace), str(id), record)
+
+    def query(
+        self,
+        namespace: str,
+        vector: Sequence[float],
+        *,
+        top_k: int = 5,
+        threshold: float | None = None,
+    ) -> list[ScoredHit]:
+        client = self._get_client()
+        raw = client.hgetall(self._key(namespace))
+        if not raw:
+            return []
+        query_vector = [float(value) for value in vector]
+        scored: list[ScoredHit] = []
+        for raw_id, raw_record in raw.items():
+            record = json.loads(_decode(raw_record))
+            similarity = _cosine(query_vector, record["v"])
+            if threshold is not None and similarity < threshold:
+                continue
+            scored.append(
+                ScoredHit(
+                    id=_decode(raw_id),
+                    score=similarity,
+                    payload=record.get("p"),
+                )
+            )
+        scored.sort(key=lambda hit: hit.score, reverse=True)
+        return scored[:top_k]
+
+    def delete(self, namespace: str, id: str) -> None:
+        client = self._get_client()
+        client.hdel(self._key(namespace), str(id))
+
+    def clear(self, namespace: str) -> None:
+        client = self._get_client()
+        client.delete(self._key(namespace))
+
+    # -- internals ----------------------------------------------------------
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        redis = _require_redis()
+        self._client = redis.from_url(self._url) if self._url else redis.Redis()
+        return self._client
+
+    def _key(self, namespace: str) -> str:
+        return f"{self._prefix}:{namespace}"

xyberos_redis-0.1.0/xyberos_redis.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: xyberos-redis
+Version: 0.1.0
+Summary: Redis plugin (RFC-0019, M4): RedisVectorStore + RedisMemory + cache backing for CacheResponder
+License: Apache-2.0
+Keywords: xyberos,plugin,redis,vector,memory,cache,state
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: state
+Requires-Dist: redis; extra == "state"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: fakeredis; extra == "test"
+
+# xyberos-redis
+
+**Redis plugin — RFC-0019, M4.** `RedisVectorStore` + `RedisMemory` + cache
+backing for `CacheResponder`, all lazy-importing `redis`. Covers the
+`[state]` extra scope (cache + state + vector).
+
+## Install
+
+```bash
+pip install -e ./redis
+pip install redis               # or: pip install xyberos[state]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_redis import RedisPlugin
+
+app = create_app()
+app.load_plugin(RedisPlugin(url="redis://localhost:6379"))   # or set REDIS_URL
+
+vector = app.resolve("redis_vector")     # a VectorStore
+memory = app.resolve("redis_memory")     # a Memory
+cache  = app.resolve("redis_cache")      # exact-match string cache
+```
+
+`RedisPlugin(replace_defaults=True)` also swaps the app's `vector_store` /
+`memory` providers.
+
+### CacheResponder backing
+
+`RedisVectorStore` is a full `VectorStore`, so it plugs straight into the core
+`CacheResponder` for near-exact `prompt -> answer` caching:
+
+```python
+from xyberos.llm import HashEmbedder
+from xyberos.router import CacheResponder
+from xyberos_redis import RedisVectorStore
+
+responder = CacheResponder(store=RedisVectorStore(url="redis://localhost:6379"),
+                           embedder=HashEmbedder())
+responder.teach("what is xyberos?", "a cognitive platform")
+```
+
+## Design
+
+- **`RedisVectorStore`** — one Redis hash per namespace; vectors JSON-encoded;
+  queries scored with exact cosine (the same scan-and-score approach as the
+  stdlib `SqliteVectorStore`, so behavior — and parity — holds without needing
+  a RediSearch vector module).
+- **`RedisMemory`** — one entry per `store()` appended to a Redis list;
+  `retrieve()` returns `MemoryEntry`s oldest-first, mirroring `SqliteMemory`.
+- **`RedisStringCache`** — tiny exact-match `get/set/delete` with optional TTL.
+- `redis` is imported **lazily**; a clear `ProviderError` is raised when missing.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+Tests run against **fakeredis** (an in-memory redis-py client), so they need no
+Redis server; they skip cleanly when `redis`/`fakeredis` are absent. The vector
+parity tests run the exact scenarios the `SqliteVectorStore` reference passes.
+
+## Ship location
+
+`[state]` extra (`redis` already added to `pyproject.toml`).

xyberos_redis-0.1.0/xyberos_redis.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+tests/test_cache.py
+tests/test_memory.py
+tests/test_parity.py
+tests/test_plugin.py
+tests/test_vector.py
+xyberos_redis/__init__.py
+xyberos_redis/cache.py
+xyberos_redis/memory.py
+xyberos_redis/plugin.py
+xyberos_redis/vector.py
+xyberos_redis.egg-info/PKG-INFO
+xyberos_redis.egg-info/SOURCES.txt
+xyberos_redis.egg-info/dependency_links.txt
+xyberos_redis.egg-info/entry_points.txt
+xyberos_redis.egg-info/requires.txt
+xyberos_redis.egg-info/top_level.txt

xyberos_redis-0.1.0/xyberos_redis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xyberos_redis-0.1.0/xyberos_redis.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+redis = xyberos_redis.plugin:plugin

xyberos_redis-0.1.0/xyberos_redis.egg-info/requires.txt

@@ -0,0 +1,8 @@
+xyberos>=1.0
+
+[state]
+redis
+
+[test]
+pytest
+fakeredis

xyberos_redis-0.1.0/xyberos_redis.egg-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_redis