pdm-memory 0.1.2__py3-none-any.whl

pdm_memory/storage/cloud_driver.py

@@ -0,0 +1,271 @@
+"""
+Cloud Storage Driver — Task 2.1
+
+Implements BaseStorage by making HTTP requests to the AZUS Companion API
+instead of reading/writing a local file.
+
+Requires: httpx (listed as a main dependency in pyproject.toml).
+
+Usage:
+    from pdm_memory.storage.cloud_driver import CloudDriver
+    from pdm_memory.auth import JWTAuth
+
+    auth = JWTAuth(token="eyJ...")
+    driver = CloudDriver(auth=auth, base_url="https://api.azus.ai")
+
+    # Or via Memory:
+    mem = Memory(store="cloud", token="eyJ...", cloud_url="https://api.azus.ai")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import List, Optional
+
+from pdm_memory.auth.jwt_handler import JWTAuth
+from pdm_memory.core.signature import DrawerInfo, SignatureRecord
+from pdm_memory.storage.base import BaseStorage
+
+logger = logging.getLogger(__name__)
+
+# Default AZUS Companion API base URL
+DEFAULT_CLOUD_URL = "https://api.azus.ai"
+
+
+class CloudDriver(BaseStorage):
+    """
+    HTTP-backed PDM storage driver targeting the AZUS Companion API.
+
+    All network calls use httpx (sync).  Timeout is configurable.
+    On 401 responses, automatically attempts token refresh if JWTAuth
+    was constructed with a refresh_token.
+
+    Args:
+        auth:     JWTAuth instance carrying the user's access token.
+        base_url: Base URL of the AZUS Companion API.
+        timeout:  Request timeout in seconds.
+        user:     Username to scope all requests (overrides token claim).
+    """
+
+    def __init__(
+        self,
+        auth: JWTAuth,
+        base_url: str = DEFAULT_CLOUD_URL,
+        timeout: float = 15.0,
+        user: str = "default",
+    ) -> None:
+        try:
+            import httpx  # noqa: F401 — guard for optional dep
+        except ImportError:
+            raise ImportError(
+                "httpx is required for cloud mode. Install it: pip install httpx"
+            )
+        self._auth = auth
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._user = user
+
+    # ------------------------------------------------------------------
+    # BaseStorage
+    # ------------------------------------------------------------------
+
+    def save(self, sig: SignatureRecord) -> str:
+        """POST /api/v1/pdm/ingest — create a new signature in the cloud."""
+        payload = self._record_to_payload(sig)
+        resp = self._post("/api/v1/pdm/ingest", payload)
+        data = resp.json()
+        # Cloud may assign a different ID
+        cloud_id = data.get("id") or data.get("signature_id") or sig.id
+        logger.debug("[PDM-Cloud] Saved signature %s", cloud_id)
+        return str(cloud_id)
+
+    def get(self, memory_id: str, user: str = "default") -> Optional[SignatureRecord]:
+        """GET /api/v1/pdm/signatures/<id>/"""
+        try:
+            resp = self._get(f"/api/v1/pdm/signatures/{memory_id}/")
+            return self._payload_to_record(resp.json())
+        except Exception as e:
+            logger.warning("[PDM-Cloud] get(%s) failed: %s", memory_id, e)
+            return None
+
+    def update(self, memory_id: str, **fields) -> None:
+        """PATCH /api/v1/pdm/signatures/<id>/"""
+        try:
+            self._patch(f"/api/v1/pdm/signatures/{memory_id}/", fields)
+        except Exception as e:
+            logger.warning("[PDM-Cloud] update(%s) failed: %s", memory_id, e)
+
+    def delete(self, memory_id: str, user: str = "default") -> None:
+        """DELETE /api/v1/pdm/signatures/<id>/"""
+        try:
+            import httpx
+            self._auth.ensure_fresh()
+            resp = httpx.delete(
+                f"{self._base_url}/api/v1/pdm/signatures/{memory_id}/",
+                headers=self._auth.headers(),
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+        except Exception as e:
+            logger.warning("[PDM-Cloud] delete(%s) failed: %s", memory_id, e)
+
+    def list(
+        self,
+        user: str = "default",
+        limit: int = 100,
+        min_pressure: float = 0.0,
+        drawer: Optional[str] = None,
+    ) -> List[SignatureRecord]:
+        """GET /api/v1/pdm/retrieve — list signatures with filters."""
+        params: dict = {"limit": limit, "min_pressure": min_pressure}
+        if drawer:
+            params["drawer"] = drawer
+        try:
+            resp = self._get("/api/v1/pdm/retrieve", params=params)
+            data = resp.json()
+            items = data if isinstance(data, list) else data.get("results", [])
+            return [self._payload_to_record(item) for item in items]
+        except Exception as e:
+            logger.warning("[PDM-Cloud] list() failed: %s", e)
+            return []
+
+    def list_drawers(self, user: str = "default") -> List[DrawerInfo]:
+        """GET /api/v1/pdm/drawers"""
+        try:
+            resp = self._get("/api/v1/pdm/drawers")
+            items = resp.json()
+            if not isinstance(items, list):
+                items = items.get("results", [])
+            return [
+                DrawerInfo(
+                    domain=item.get("domain", ""),
+                    signature_count=item.get("signature_count", 0),
+                    avg_pressure=float(item.get("avg_pressure", 0.0)),
+                    description=item.get("description", ""),
+                )
+                for item in items
+            ]
+        except Exception as e:
+            logger.warning("[PDM-Cloud] list_drawers() failed: %s", e)
+            return []
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _post(self, path: str, payload: dict):
+        import httpx
+        self._auth.ensure_fresh()
+        resp = httpx.post(
+            f"{self._base_url}{path}",
+            json=payload,
+            headers=self._auth.headers(),
+            timeout=self._timeout,
+        )
+        self._handle_auth_retry(resp, "POST", path, payload)
+        resp.raise_for_status()
+        return resp
+
+    def _get(self, path: str, params: Optional[dict] = None):
+        import httpx
+        self._auth.ensure_fresh()
+        resp = httpx.get(
+            f"{self._base_url}{path}",
+            params=params,
+            headers=self._auth.headers(),
+            timeout=self._timeout,
+        )
+        self._handle_auth_retry(resp, "GET", path)
+        resp.raise_for_status()
+        return resp
+
+    def _patch(self, path: str, payload: dict):
+        import httpx
+        self._auth.ensure_fresh()
+        resp = httpx.patch(
+            f"{self._base_url}{path}",
+            json=payload,
+            headers=self._auth.headers(),
+            timeout=self._timeout,
+        )
+        resp.raise_for_status()
+        return resp
+
+    def _handle_auth_retry(self, resp, method: str, path: str, payload=None) -> None:
+        """On 401, attempt one token refresh and retry."""
+        import httpx
+        if resp.status_code == 401:
+            if self._auth.refresh():
+                if method == "POST":
+                    resp2 = httpx.post(
+                        f"{self._base_url}{path}",
+                        json=payload,
+                        headers=self._auth.headers(),
+                        timeout=self._timeout,
+                    )
+                    resp.__dict__.update(resp2.__dict__)
+                elif method == "GET":
+                    resp2 = httpx.get(
+                        f"{self._base_url}{path}",
+                        headers=self._auth.headers(),
+                        timeout=self._timeout,
+                    )
+                    resp.__dict__.update(resp2.__dict__)
+
+    # ------------------------------------------------------------------
+    # Serialisation helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _record_to_payload(sig: SignatureRecord) -> dict:
+        return {
+            "compressed_fact": sig.compressed_fact,
+            "source": sig.source,
+            "p_magnitude": sig.p_magnitude,
+            "t_persistence": sig.t_persistence,
+            "phase_privilege": sig.phase_privilege,
+            "intent_tags": sig.intent_tags,
+            "question_regime": sig.question_regime,
+            "drawer_domain": sig.drawer_domain,
+            "metadata": sig.metadata,
+        }
+
+    @staticmethod
+    def _payload_to_record(data: dict) -> SignatureRecord:
+        from datetime import datetime
+        tags = data.get("intent_tags") or []
+        if isinstance(tags, str):
+            try:
+                tags = json.loads(tags)
+            except Exception:
+                tags = []
+
+        def _dt(val):
+            if not val:
+                return None
+            try:
+                return datetime.fromisoformat(str(val))
+            except Exception:
+                return None
+
+        return SignatureRecord(
+            id=str(data.get("id", "")),
+            user=str(data.get("user", "default")),
+            compressed_fact=data.get("compressed_fact", ""),
+            source=data.get("source", "chat"),
+            p_magnitude=float(data.get("p_magnitude", 50.0)),
+            t_persistence=float(data.get("t_persistence", 30.0)),
+            phase_privilege=float(data.get("phase_privilege", 1.0)),
+            effective_spike=data.get("effective_spike"),
+            intent_tags=tags,
+            question_regime=data.get("question_regime", "neutral"),
+            domain=data.get("domain", "insight"),
+            drawer_domain=data.get("drawer_domain") or data.get("drawer", "general"),
+            retrieval_count=int(data.get("retrieval_count", 0)),
+            last_retrieved=_dt(data.get("last_retrieved")),
+            created_at=_dt(data.get("created_at")),
+            validation_prediction_total=int(data.get("validation_prediction_total", 0)),
+            validation_prediction_correct=int(data.get("validation_prediction_correct", 0)),
+            metadata=data.get("metadata") or {},
+        )

pdm_memory/storage/sqlite_driver.py

@@ -0,0 +1,331 @@
+"""
+SQLite Storage Driver — Task 1.2
+
+Zero external dependencies beyond Python stdlib.
+Stores all PDM signatures in a single local .db file.
+
+Privacy guarantee: raw compressed_fact is stored by default.
+If store_raw=False, only the SHA-256 hash of the text is stored
+(the memory is opaque even to someone with file access).
+
+Schema is auto-created on first run.
+
+Usage:
+    driver = SQLiteDriver("./my_app.db")
+    memory_id = driver.save(sig)
+    hits = driver.list(user="alice", min_pressure=50)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from pdm_memory.core.signature import DrawerInfo, SignatureRecord
+from pdm_memory.storage.base import BaseStorage
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS pdm_signatures (
+    id                              TEXT PRIMARY KEY,
+    user                            TEXT NOT NULL DEFAULT 'default',
+    compressed_fact                 TEXT NOT NULL,
+    compressed_fact_hash            TEXT NOT NULL,
+    source                          TEXT NOT NULL DEFAULT 'chat',
+    p_magnitude                     REAL NOT NULL DEFAULT 50.0,
+    t_persistence                   REAL NOT NULL DEFAULT 30.0,
+    phase_privilege                 REAL NOT NULL DEFAULT 1.0,
+    effective_spike                 REAL,
+    intent_tags                     TEXT NOT NULL DEFAULT '[]',
+    question_regime                 TEXT NOT NULL DEFAULT 'neutral',
+    domain                          TEXT NOT NULL DEFAULT 'insight',
+    drawer_domain                   TEXT NOT NULL DEFAULT 'general',
+    retrieval_count                 INTEGER NOT NULL DEFAULT 0,
+    last_retrieved                  TEXT,
+    created_at                      TEXT NOT NULL,
+    validation_prediction_total     INTEGER NOT NULL DEFAULT 0,
+    validation_prediction_correct   INTEGER NOT NULL DEFAULT 0,
+    decay_rate                      REAL NOT NULL DEFAULT 0.9,
+    t_deadline                      TEXT,
+    urgency_rate                    REAL NOT NULL DEFAULT 2.0,
+    metadata                        TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_pdm_user_pressure
+    ON pdm_signatures (user, p_magnitude DESC);
+
+CREATE INDEX IF NOT EXISTS idx_pdm_user_drawer
+    ON pdm_signatures (user, drawer_domain);
+
+CREATE TABLE IF NOT EXISTS pdm_drawers (
+    domain          TEXT NOT NULL,
+    user            TEXT NOT NULL DEFAULT 'default',
+    description     TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (domain, user)
+);
+"""
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def _parse_dt(s: Optional[str]) -> Optional[datetime]:
+    if not s:
+        return None
+    try:
+        return datetime.fromisoformat(s)
+    except Exception:
+        return None
+
+
+class SQLiteDriver(BaseStorage):
+    """
+    SQLite-backed PDM storage.  Thread-safe (one connection per thread).
+
+    Args:
+        db_path:    Path to the .db file.  Created automatically.
+        store_raw:  If False, only the SHA-256 hash of compressed_fact is
+                    stored — the text itself never touches disk.
+    """
+
+    def __init__(self, db_path: str = "./pdm_memory.db", store_raw: bool = True) -> None:
+        self.db_path = db_path
+        self.store_raw = store_raw
+        self._local = threading.local()
+        # Initialise schema on startup
+        conn = self._conn()
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.executescript(_SCHEMA)
+        conn.commit()
+        logger.debug("[PDM-SQLite] Opened %s (store_raw=%s)", db_path, store_raw)
+
+    # ------------------------------------------------------------------
+    # Connection management (one connection per thread)
+    # ------------------------------------------------------------------
+
+    def _conn(self) -> sqlite3.Connection:
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            self._local.conn = sqlite3.connect(
+                self.db_path,
+                detect_types=sqlite3.PARSE_DECLTYPES,
+                check_same_thread=False,
+            )
+            self._local.conn.row_factory = sqlite3.Row
+            # Optimise connection performance pragmas
+            self._local.conn.execute("PRAGMA synchronous=NORMAL")
+            self._local.conn.execute("PRAGMA temp_store=MEMORY")
+        return self._local.conn
+
+    def close(self) -> None:
+        if hasattr(self._local, "conn") and self._local.conn:
+            self._local.conn.close()
+            self._local.conn = None
+
+    # ------------------------------------------------------------------
+    # BaseStorage implementation
+    # ------------------------------------------------------------------
+
+    def save(self, sig: SignatureRecord) -> str:
+        """Insert a new signature. Returns sig.id."""
+        text = sig.compressed_fact or ""
+        text_hash = hashlib.sha256(text.encode()).hexdigest()
+        stored_text = text if self.store_raw else f"[HASH:{text_hash}]"
+
+        conn = self._conn()
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO pdm_signatures (
+                id, user, compressed_fact, compressed_fact_hash, source,
+                p_magnitude, t_persistence, phase_privilege, effective_spike,
+                intent_tags, question_regime, domain, drawer_domain,
+                retrieval_count, last_retrieved, created_at,
+                validation_prediction_total, validation_prediction_correct,
+                decay_rate, t_deadline, urgency_rate, metadata
+            ) VALUES (
+                ?, ?, ?, ?, ?,
+                ?, ?, ?, ?,
+                ?, ?, ?, ?,
+                ?, ?, ?,
+                ?, ?,
+                ?, ?, ?, ?
+            )
+            """,
+            (
+                sig.id,
+                sig.user,
+                stored_text,
+                text_hash,
+                sig.source,
+                sig.p_magnitude,
+                sig.t_persistence,
+                sig.phase_privilege,
+                sig.effective_spike,
+                json.dumps(sig.intent_tags),
+                sig.question_regime,
+                sig.domain,
+                sig.drawer_domain,
+                sig.retrieval_count,
+                sig.last_retrieved.isoformat() if sig.last_retrieved else None,
+                (sig.created_at or datetime.now(tz=timezone.utc)).isoformat(),
+                sig.validation_prediction_total,
+                sig.validation_prediction_correct,
+                sig.decay_rate,
+                sig.t_deadline.isoformat() if sig.t_deadline else None,
+                sig.urgency_rate,
+                json.dumps(sig.metadata),
+            ),
+        )
+        # Upsert drawer record
+        conn.execute(
+            "INSERT OR IGNORE INTO pdm_drawers (domain, user, description) VALUES (?, ?, ?)",
+            (sig.drawer_domain, sig.user, ""),
+        )
+        conn.commit()
+        logger.debug("[PDM-SQLite] Saved signature %s (P=%.1f)", sig.id, sig.p_magnitude)
+        return sig.id
+
+    def get(self, memory_id: str, user: str = "default") -> Optional[SignatureRecord]:
+        row = self._conn().execute(
+            "SELECT * FROM pdm_signatures WHERE id = ? AND user = ?",
+            (memory_id, user),
+        ).fetchone()
+        return self._row_to_record(row) if row else None
+
+    def update(self, memory_id: str, **fields) -> None:
+        if not fields:
+            return
+        # Serialise JSON fields
+        if "intent_tags" in fields:
+            fields["intent_tags"] = json.dumps(fields["intent_tags"])
+        if "metadata" in fields:
+            fields["metadata"] = json.dumps(fields["metadata"])
+        if "last_retrieved" in fields and isinstance(fields["last_retrieved"], datetime):
+            fields["last_retrieved"] = fields["last_retrieved"].isoformat()
+
+        set_clause = ", ".join(f"{k} = ?" for k in fields)
+        values = list(fields.values()) + [memory_id]
+        self._conn().execute(
+            f"UPDATE pdm_signatures SET {set_clause} WHERE id = ?",
+            values,
+        )
+        self._conn().commit()
+
+    def update_batch(self, updates: List[tuple[str, dict]]) -> None:
+        if not updates:
+            return
+        conn = self._conn()
+        for memory_id, fields in updates:
+            if not fields:
+                continue
+            fields_copy = dict(fields)
+            if "intent_tags" in fields_copy:
+                fields_copy["intent_tags"] = json.dumps(fields_copy["intent_tags"])
+            if "metadata" in fields_copy:
+                fields_copy["metadata"] = json.dumps(fields_copy["metadata"])
+            if "last_retrieved" in fields_copy and isinstance(fields_copy["last_retrieved"], datetime):
+                fields_copy["last_retrieved"] = fields_copy["last_retrieved"].isoformat()
+
+            set_clause = ", ".join(f"{k} = ?" for k in fields_copy)
+            values = list(fields_copy.values()) + [memory_id]
+            conn.execute(
+                f"UPDATE pdm_signatures SET {set_clause} WHERE id = ?",
+                values,
+            )
+        conn.commit()
+
+    def delete(self, memory_id: str, user: str = "default") -> None:
+        self._conn().execute(
+            "DELETE FROM pdm_signatures WHERE id = ? AND user = ?",
+            (memory_id, user),
+        )
+        self._conn().commit()
+
+    def list(
+        self,
+        user: str = "default",
+        limit: int = 100,
+        min_pressure: float = 0.0,
+        drawer: Optional[str] = None,
+    ) -> List[SignatureRecord]:
+        query = (
+            "SELECT * FROM pdm_signatures WHERE user = ? AND p_magnitude >= ?"
+        )
+        params: list = [user, min_pressure]
+        if drawer:
+            query += " AND drawer_domain = ?"
+            params.append(drawer)
+        query += " ORDER BY p_magnitude DESC LIMIT ?"
+        params.append(limit)
+
+        rows = self._conn().execute(query, params).fetchall()
+        return [self._row_to_record(r) for r in rows]
+
+    def list_drawers(self, user: str = "default") -> List[DrawerInfo]:
+        rows = self._conn().execute(
+            """
+            SELECT
+                d.domain,
+                d.description,
+                COUNT(s.id)       AS sig_count,
+                AVG(s.p_magnitude) AS avg_pressure
+            FROM pdm_drawers d
+            LEFT JOIN pdm_signatures s
+                ON s.drawer_domain = d.domain AND s.user = d.user
+            WHERE d.user = ?
+            GROUP BY d.domain, d.description
+            ORDER BY d.domain
+            """,
+            (user,),
+        ).fetchall()
+        return [
+            DrawerInfo(
+                domain=r["domain"],
+                signature_count=r["sig_count"] or 0,
+                avg_pressure=round(r["avg_pressure"] or 0.0, 2),
+                description=r["description"] or "",
+            )
+            for r in rows
+        ]
+
+    def count(self, user: str = "default") -> int:
+        row = self._conn().execute(
+            "SELECT COUNT(*) FROM pdm_signatures WHERE user = ?", (user,)
+        ).fetchone()
+        return row[0] if row else 0
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_record(row: sqlite3.Row) -> SignatureRecord:
+        return SignatureRecord(
+            id=row["id"],
+            user=row["user"],
+            compressed_fact=row["compressed_fact"],
+            source=row["source"],
+            p_magnitude=row["p_magnitude"],
+            t_persistence=row["t_persistence"],
+            phase_privilege=row["phase_privilege"],
+            effective_spike=row["effective_spike"],
+            intent_tags=json.loads(row["intent_tags"] or "[]"),
+            question_regime=row["question_regime"],
+            domain=row["domain"],
+            drawer_domain=row["drawer_domain"],
+            retrieval_count=row["retrieval_count"],
+            last_retrieved=_parse_dt(row["last_retrieved"]),
+            created_at=_parse_dt(row["created_at"]),
+            validation_prediction_total=row["validation_prediction_total"],
+            validation_prediction_correct=row["validation_prediction_correct"],
+            decay_rate=row["decay_rate"],
+            t_deadline=_parse_dt(row["t_deadline"]),
+            urgency_rate=row["urgency_rate"],
+            metadata=json.loads(row["metadata"] or "{}"),
+        )