fluctlightdb 0.4.2__tar.gz → 0.4.3__tar.gz

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluctlightdb
-Version: 0.4.2
+Version: 0.4.3
 Summary: Python client for FluctlightDB — brain-native memory for AI agents
 Author-email: Voxmastery <voxmastery@roppashreeganesh.com>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: native
-Requires-Dist: fluctlightdb-native>=0.4.2; extra == "native"
+Requires-Dist: fluctlightdb-native>=0.4.3; extra == "native"
 Dynamic: license-file
 
 # fluctlightdb
@@ -32,10 +32,20 @@ Python client for [FluctlightDB](https://github.com/voxmastery/FluctlightDB) —
 
 ## Install
 
+On **Debian/Ubuntu 23.04+**, **Debian 12+**, and **Fedora 38+**, system Python is [PEP 668](https://peps.python.org/pep-0668/) *externally managed* — bare `pip install` fails with `externally-managed-environment`. Use a **virtual environment** (same as any other PyPI library):
+
 ```bash
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install fluctlightdb
 ```
 
+From a clone of this repo you can also run:
+
+```bash
+./scripts/install-python-client.sh
+```
+
 Optional in-process recall (Rust extension, when wheels are available for your platform):
 
 ```bash
@@ -75,17 +85,22 @@ client = FluctlightClient.from_env()
 print(client.activate("dark mode"))
 ```
 
-## In-process recall (optional)
+## In-process brain (like `sqlite3`)
 
 When `fluctlightdb-native` is installed:
 
 ```python
-from fluctlightdb import get_recall_client
+from fluctlightdb import connect
 
-brain = get_recall_client("~/.fluctlight/tenants/default/brain")
+brain = connect("/tmp/my-agent-brain")
+brain.experience("user prefers dark mode", context="settings")
 print(brain.activate("dark mode"))
 ```
 
+Read-only recall path: `get_recall_client(path)`.
+
+## In-process recall (read-only helper)
+
 ## Docs
 
 - [Getting started](https://github.com/voxmastery/FluctlightDB/blob/main/docs/GETTING_STARTED.md)

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/README.md

@@ -4,10 +4,20 @@ Python client for [FluctlightDB](https://github.com/voxmastery/FluctlightDB) —
 
 ## Install
 
+On **Debian/Ubuntu 23.04+**, **Debian 12+**, and **Fedora 38+**, system Python is [PEP 668](https://peps.python.org/pep-0668/) *externally managed* — bare `pip install` fails with `externally-managed-environment`. Use a **virtual environment** (same as any other PyPI library):
+
 ```bash
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install fluctlightdb
 ```
 
+From a clone of this repo you can also run:
+
+```bash
+./scripts/install-python-client.sh
+```
+
 Optional in-process recall (Rust extension, when wheels are available for your platform):
 
 ```bash
@@ -47,17 +57,22 @@ client = FluctlightClient.from_env()
 print(client.activate("dark mode"))
 ```
 
-## In-process recall (optional)
+## In-process brain (like `sqlite3`)
 
 When `fluctlightdb-native` is installed:
 
 ```python
-from fluctlightdb import get_recall_client
+from fluctlightdb import connect
 
-brain = get_recall_client("~/.fluctlight/tenants/default/brain")
+brain = connect("/tmp/my-agent-brain")
+brain.experience("user prefers dark mode", context="settings")
 print(brain.activate("dark mode"))
 ```
 
+Read-only recall path: `get_recall_client(path)`.
+
+## In-process recall (read-only helper)
+
 ## Docs
 
 - [Getting started](https://github.com/voxmastery/FluctlightDB/blob/main/docs/GETTING_STARTED.md)

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/fluctlightdb/__init__.py

@@ -11,12 +11,15 @@ import urllib.request
 from dataclasses import dataclass, field
 from typing import Any, Optional
 
+from .brain import FluctlightBrain, connect
 from .worker import FluctlightNative, FluctlightWorker, get_recall_client, get_worker
 
 __all__ = [
     "FluctlightClient",
+    "FluctlightBrain",
     "FluctlightNative",
     "FluctlightWorker",
+    "connect",
     "get_recall_client",
     "get_worker",
 ]

fluctlightdb-0.4.3/fluctlightdb/brain.py

@@ -0,0 +1,151 @@
+"""Embedded brain client — sqlite3-style in-process API when native is installed."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+
+class FluctlightBrain:
+    """In-process Fluctlight brain (like ``sqlite3.connect``). Requires ``fluctlightdb-native``."""
+
+    def __init__(self, brain: Any, *, readonly: bool = False) -> None:
+        self._brain = brain
+        self.readonly = readonly
+        self.brain_path: Optional[str] = getattr(brain, "brain_path", None)
+
+    @classmethod
+    def connect(cls, path: str, *, readonly: bool = False) -> "FluctlightBrain":
+        import fluctlightdb_native as native  # type: ignore
+
+        brain = native.Brain.open_readonly(path) if readonly else native.Brain.open(path)
+        obj = cls(brain, readonly=readonly)
+        obj.brain_path = path
+        return obj
+
+    @classmethod
+    def new(cls) -> "FluctlightBrain":
+        import fluctlightdb_native as native  # type: ignore
+
+        return cls(native.Brain.new(), readonly=False)
+
+    def experience(
+        self,
+        content: str,
+        *,
+        context: str = "api",
+        salience: float = 0.5,
+        outcome: Optional[str] = None,
+        semantic_vector: Optional[list[float]] = None,
+        agent_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        verified: Optional[bool] = None,
+        provenance_kind: Optional[str] = None,
+        source_uri: Optional[str] = None,
+        confidence: Optional[float] = None,
+        doc_id: Optional[str] = None,
+        chunk_id: Optional[str] = None,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "content": content,
+            "context": context,
+            "salience_hint": salience,
+        }
+        if outcome is not None:
+            payload["outcome"] = outcome
+        if semantic_vector is not None:
+            payload["semantic_vector"] = semantic_vector
+        if agent_id is not None:
+            payload["agent_id"] = agent_id
+        if tenant_id is not None:
+            payload["tenant_id"] = tenant_id
+        if doc_id or chunk_id or source_uri:
+            payload["rag"] = {
+                "doc_id": doc_id,
+                "chunk_id": chunk_id,
+                "source_uri": source_uri,
+            }
+        if verified is not None or provenance_kind or source_uri:
+            payload["provenance"] = {
+                "kind": provenance_kind or "ledger_verified",
+                "source_uri": source_uri,
+                "confidence": confidence if confidence is not None else 0.95,
+                "verified": bool(verified),
+            }
+        payload.update(extra)
+        return self._brain.experience(json.dumps(payload))
+
+    def activate(
+        self,
+        cue: str,
+        semantic_vector: Optional[list[float]] = None,
+        agent_id: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict[str, Any]:
+        return self._brain.activate(cue, semantic_vector, agent_id, limit)
+
+    def activate_batch(
+        self,
+        items: list[dict[str, Any]],
+        limit: Optional[int] = None,
+    ) -> dict[str, Any]:
+        return self._brain.activate_batch_json(json.dumps(items), limit)
+
+    def verify_fact(
+        self,
+        engram_id: str,
+        *,
+        provenance_kind: str = "ledger_verified",
+        source_uri: Optional[str] = None,
+        confidence: float = 0.95,
+    ) -> None:
+        self._brain.verify_fact(engram_id, provenance_kind, source_uri, confidence)
+
+    def sleep(self) -> dict[str, Any]:
+        return self._brain.sleep()
+
+    def tick(self, n: int = 1) -> list[dict[str, Any]]:
+        return self._brain.tick(n)
+
+    def preplay(self, goal: str, steps: int = 4) -> dict[str, Any]:
+        return self._brain.preplay(goal, steps)
+
+    def neurogenesis(self) -> dict[str, Any]:
+        return self._brain.neurogenesis_pulse()
+
+    def compact(self) -> dict[str, Any]:
+        return self._brain.compact()
+
+    def reward(self, magnitude: float = 0.5) -> None:
+        self._brain.reward(magnitude)
+
+    def mark_core(self, engram_id: str, key: str) -> None:
+        self._brain.mark_core(engram_id, key)
+
+    def death(self, cause: str = "api") -> str:
+        return str(self._brain.death(cause))
+
+    def status(self) -> dict[str, Any]:
+        return self._brain.status()
+
+    def stage_report(self) -> dict[str, Any]:
+        return self._brain.stage_report()
+
+    def verified_context(self, limit: int = 12) -> dict[str, Any]:
+        return self._brain.verified_context(limit)
+
+    def stage(self) -> str:
+        return str(self._brain.stage())
+
+    def checkpoint(self) -> None:
+        self._brain.checkpoint()
+
+    def has_sidecar_index(self) -> bool:
+        return bool(self._brain.has_sidecar_index())
+
+
+def connect(path: str, *, readonly: bool = False) -> FluctlightBrain:
+    """Open a brain directory like ``sqlite3.connect(path)``."""
+    return FluctlightBrain.connect(path, readonly=readonly)

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/fluctlightdb/worker.py

@@ -58,6 +58,7 @@ class FluctlightNative:
         else:
             self._brain = native.Brain.open(brain_path)
         self.brain_path = brain_path
+        self.readonly = readonly
 
     def activate(
         self,
@@ -75,15 +76,55 @@ class FluctlightNative:
     ) -> dict[str, Any]:
         return self._brain.activate_batch_json(json.dumps(items), limit)
 
+    def experience(self, episode_json: str) -> dict[str, Any]:
+        if self.readonly:
+            raise RuntimeError("brain opened readonly — reopen with readonly=False")
+        return self._brain.experience(episode_json)
+
+    def experience_dict(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.experience(json.dumps(payload))
+
+    def verify_fact(
+        self,
+        engram_id: str,
+        provenance_kind: str = "ledger_verified",
+        source_uri: Optional[str] = None,
+        confidence: float = 0.95,
+    ) -> None:
+        if self.readonly:
+            raise RuntimeError("brain opened readonly")
+        self._brain.verify_fact(engram_id, provenance_kind, source_uri, confidence)
+
+    def sleep(self) -> dict[str, Any]:
+        if self.readonly:
+            raise RuntimeError("brain opened readonly")
+        return self._brain.sleep()
+
+    def tick(self, n: int = 1) -> list[dict[str, Any]]:
+        if self.readonly:
+            raise RuntimeError("brain opened readonly")
+        return self._brain.tick(n)
+
+    def preplay(self, goal: str, steps: int = 4) -> dict[str, Any]:
+        return self._brain.preplay(goal, steps)
+
     def status(self) -> dict[str, Any]:
         return self._brain.status()
 
+    def stage_report(self) -> dict[str, Any]:
+        return self._brain.stage_report()
+
     def verified_context(self, limit: int = 12) -> dict[str, Any]:
         return self._brain.verified_context(limit)
 
     def has_sidecar_index(self) -> bool:
         return bool(self._brain.has_sidecar_index())
 
+    def checkpoint(self) -> None:
+        if self.readonly:
+            raise RuntimeError("brain opened readonly")
+        self._brain.checkpoint()
+
 
 class FluctlightWorker:
     """Long-lived `fluctlight worker` subprocess — brain loaded once, sub-ms recall."""
@@ -118,7 +159,8 @@ class FluctlightWorker:
         with self._lock:
             if self._proc and self._proc.poll() is None:
                 try:
-                    self._call("shutdown")
+                    self._proc.stdin.write('{"op":"shutdown"}\n')
+                    self._proc.stdin.flush()
                 except Exception:
                     pass
                 self._proc.terminate()
@@ -128,24 +170,18 @@ class FluctlightWorker:
         with self._lock:
             if self._proc is None or self._proc.poll() is not None:
                 self._start()
-            assert self._proc is not None
-            assert self._proc.stdin is not None
-            assert self._proc.stdout is not None
+            assert self._proc and self._proc.stdin and self._proc.stdout
             self._id += 1
-            req = {"op": op, "id": self._id, **kwargs}
+            req = {"id": self._id, "op": op, **kwargs}
             self._proc.stdin.write(json.dumps(req) + "\n")
             self._proc.stdin.flush()
             line = self._proc.stdout.readline()
             if not line:
-                err = (self._proc.stderr.read() if self._proc.stderr else "")[:300]
-                raise RuntimeError(f"worker closed: {err}")
+                raise RuntimeError("worker closed stdout")
             resp = json.loads(line)
-            if not resp.get("ok"):
-                raise RuntimeError(resp.get("error") or "worker error")
-            return resp
-
-    def ping(self) -> bool:
-        return bool(self._call("ping").get("pong"))
+            if "error" in resp:
+                raise RuntimeError(resp["error"])
+            return resp.get("result", resp)
 
     def activate(
         self,
@@ -161,21 +197,17 @@ class FluctlightWorker:
             payload["agent_id"] = agent_id
         if limit is not None:
             payload["limit"] = limit
-        return self._call("activate", **payload)["result"]
+        return self._call("activate", **payload)
 
     def activate_batch(
         self,
         items: list[dict[str, Any]],
         limit: Optional[int] = None,
     ) -> dict[str, Any]:
-        payload: dict[str, Any] = {"batch": items}
-        if limit is not None:
-            payload["limit"] = limit
-        resp = self._call("activate_batch", **payload)
-        return {"results": resp.get("results") or [], "count": resp.get("count", 0)}
+        return self._call("activate_batch", batch=items, limit=limit)
 
     def status(self) -> dict[str, Any]:
-        return self._call("status")["status"]
+        return self._call("status")
 
     def verified_context(self, limit: int = 12) -> dict[str, Any]:
         return self._call("verified_context", limit=limit)["context"]
@@ -192,6 +224,8 @@ _client_lock = threading.Lock()
 def get_recall_client(
     brain_path: Optional[str] = None,
     bin_path: Optional[str] = None,
+    *,
+    readonly: bool = True,
 ) -> RecallClient:
     """Best available in-process recall: native library > worker subprocess."""
     global _native_singleton, _worker_singleton
@@ -210,7 +244,7 @@ def get_recall_client(
     with _client_lock:
         if prefer_native and _native_singleton is None:
             try:
-                _native_singleton = FluctlightNative(path, readonly=True)
+                _native_singleton = FluctlightNative(path, readonly=readonly)
                 return _native_singleton
             except ImportError:
                 pass
@@ -227,7 +261,7 @@ def get_worker(
     brain_path: Optional[str] = None,
     bin_path: Optional[str] = None,
 ) -> FluctlightWorker:
-    client = get_recall_client(brain_path=brain_path, bin_path=bin_path)
+    client = get_recall_client(brain_path=brain_path, bin_path=bin_path, readonly=True)
     if isinstance(client, FluctlightWorker):
         return client
     raise TypeError("native client active — use get_recall_client() instead")

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/fluctlightdb.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluctlightdb
-Version: 0.4.2
+Version: 0.4.3
 Summary: Python client for FluctlightDB — brain-native memory for AI agents
 Author-email: Voxmastery <voxmastery@roppashreeganesh.com>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: native
-Requires-Dist: fluctlightdb-native>=0.4.2; extra == "native"
+Requires-Dist: fluctlightdb-native>=0.4.3; extra == "native"
 Dynamic: license-file
 
 # fluctlightdb
@@ -32,10 +32,20 @@ Python client for [FluctlightDB](https://github.com/voxmastery/FluctlightDB) —
 
 ## Install
 
+On **Debian/Ubuntu 23.04+**, **Debian 12+**, and **Fedora 38+**, system Python is [PEP 668](https://peps.python.org/pep-0668/) *externally managed* — bare `pip install` fails with `externally-managed-environment`. Use a **virtual environment** (same as any other PyPI library):
+
 ```bash
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install fluctlightdb
 ```
 
+From a clone of this repo you can also run:
+
+```bash
+./scripts/install-python-client.sh
+```
+
 Optional in-process recall (Rust extension, when wheels are available for your platform):
 
 ```bash
@@ -75,17 +85,22 @@ client = FluctlightClient.from_env()
 print(client.activate("dark mode"))
 ```
 
-## In-process recall (optional)
+## In-process brain (like `sqlite3`)
 
 When `fluctlightdb-native` is installed:
 
 ```python
-from fluctlightdb import get_recall_client
+from fluctlightdb import connect
 
-brain = get_recall_client("~/.fluctlight/tenants/default/brain")
+brain = connect("/tmp/my-agent-brain")
+brain.experience("user prefers dark mode", context="settings")
 print(brain.activate("dark mode"))
 ```
 
+Read-only recall path: `get_recall_client(path)`.
+
+## In-process recall (read-only helper)
+
 ## Docs
 
 - [Getting started](https://github.com/voxmastery/FluctlightDB/blob/main/docs/GETTING_STARTED.md)

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/fluctlightdb.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 fluctlightdb/__init__.py
+fluctlightdb/brain.py
 fluctlightdb/worker.py
 fluctlightdb.egg-info/PKG-INFO
 fluctlightdb.egg-info/SOURCES.txt

fluctlightdb-0.4.3/fluctlightdb.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[native]
+fluctlightdb-native>=0.4.3

{fluctlightdb-0.4.2 → fluctlightdb-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fluctlightdb"
-version = "0.4.2"
+version = "0.4.3"
 description = "Python client for FluctlightDB — brain-native memory for AI agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -32,7 +32,7 @@ Repository = "https://github.com/voxmastery/FluctlightDB"
 Issues = "https://github.com/voxmastery/FluctlightDB/issues"
 
 [project.optional-dependencies]
-native = ["fluctlightdb-native>=0.4.2"]
+native = ["fluctlightdb-native>=0.4.3"]
 
 [tool.setuptools.packages.find]
 where = ["."]

fluctlightdb-0.4.2/fluctlightdb.egg-info/requires.txt

@@ -1,3 +0,0 @@
-
-[native]
-fluctlightdb-native>=0.4.2