fluidlayer 2.1.0__tar.gz → 2.2.0__tar.gz

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluidlayer
-Version: 2.1.0
+Version: 2.2.0
 Summary: A research memory layer for language models with optional GPT-2 and Qwen2 adapters
 Author: Kapil Dhinwa
 License: MIT

fluidlayer-2.2.0/deployment/__init__.py

@@ -0,0 +1 @@
+"""Optional deployment helpers for applications embedding FluidLayer."""

fluidlayer-2.2.0/deployment/session_registry.py

@@ -0,0 +1,178 @@
+"""Bounded, process-local isolation for stateful per-session memory branches.
+
+This helper is an application integration aid, not an authentication system
+or a cross-process session store. Applications must derive identifiers from
+their authenticated identity layer and must not expose branch objects beyond
+the lease that owns them.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Callable, Generic, Protocol, TypeVar
+
+
+class Resettable(Protocol):
+    """The minimum interface required from a stateful branch."""
+
+    def reset(self) -> None:
+        """Clear all state associated with the branch."""
+
+
+BranchT = TypeVar("BranchT", bound=Resettable)
+
+
+class SessionRegistryError(RuntimeError):
+    """Base exception for session-registry lifecycle errors."""
+
+
+class SessionCapacityError(SessionRegistryError):
+    """Raised when the registry is full of unexpired sessions."""
+
+
+class SessionBusyError(SessionRegistryError):
+    """Raised when a caller tries to reset or close an active session."""
+
+
+@dataclass
+class _Session(Generic[BranchT]):
+    branch: BranchT
+    last_used: float
+    active_leases: int = 0
+    lock: threading.RLock = field(default_factory=threading.RLock)
+
+
+class SessionRegistry(Generic[BranchT]):
+    """Manage separate stateful branches for `(tenant_id, session_id)` keys.
+
+    Each lease holds a per-session lock for its whole duration. This prevents
+    concurrent requests from interleaving writes to one branch while allowing
+    independent sessions to proceed concurrently. Expired idle sessions are
+    removed when the registry is next accessed. Capacity is a hard bound:
+    active or unexpired sessions are never silently evicted.
+
+    The registry is process-local and volatile. For multiple workers, use
+    worker affinity or an application-owned session service; do not serialize
+    live branch objects and assume they are safe to restore.
+    """
+
+    def __init__(
+        self,
+        branch_factory: Callable[[], BranchT],
+        *,
+        max_sessions: int = 1024,
+        ttl_seconds: float = 1800.0,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if not callable(branch_factory):
+            raise TypeError("branch_factory must be callable")
+        if isinstance(max_sessions, bool) or not isinstance(max_sessions, int):
+            raise TypeError("max_sessions must be an integer")
+        if max_sessions <= 0:
+            raise ValueError("max_sessions must be greater than zero")
+        if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, (int, float)):
+            raise TypeError("ttl_seconds must be a finite positive number")
+        if not math.isfinite(ttl_seconds) or ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be a finite positive number")
+        if not callable(clock):
+            raise TypeError("clock must be callable")
+
+        self._branch_factory = branch_factory
+        self._max_sessions = max_sessions
+        self._ttl_seconds = float(ttl_seconds)
+        self._clock = clock
+        self._sessions: dict[tuple[str, str], _Session[BranchT]] = {}
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def _validate_id(value: str, name: str) -> str:
+        if not isinstance(value, str):
+            raise TypeError(f"{name} must be a string")
+        if not value.strip():
+            raise ValueError(f"{name} must not be empty")
+        return value
+
+    def _expire_idle_sessions(self, now: float) -> None:
+        expired = [
+            key
+            for key, session in self._sessions.items()
+            if session.active_leases == 0
+            and now - session.last_used >= self._ttl_seconds
+        ]
+        for key in expired:
+            del self._sessions[key]
+
+    @contextmanager
+    def lease(self, tenant_id: str, session_id: str) -> Iterator[BranchT]:
+        """Yield the branch for one identity pair, serialized per session."""
+        tenant = self._validate_id(tenant_id, "tenant_id")
+        session_name = self._validate_id(session_id, "session_id")
+        key = (tenant, session_name)
+        now = self._clock()
+
+        with self._lock:
+            self._expire_idle_sessions(now)
+            session = self._sessions.get(key)
+            if session is None:
+                if len(self._sessions) >= self._max_sessions:
+                    raise SessionCapacityError(
+                        f"session registry is at capacity "
+                        f"({self._max_sessions}); retry after sessions expire "
+                        "or close an idle session"
+                    )
+                session = _Session(self._branch_factory(), last_used=now)
+                self._sessions[key] = session
+            session.active_leases += 1
+            session.last_used = now
+
+        try:
+            with session.lock:
+                yield session.branch
+        finally:
+            with self._lock:
+                session.active_leases -= 1
+                session.last_used = self._clock()
+
+    def reset_session(self, tenant_id: str, session_id: str) -> bool:
+        """Reset an idle session; return False if it does not exist."""
+        key = (
+            self._validate_id(tenant_id, "tenant_id"),
+            self._validate_id(session_id, "session_id"),
+        )
+        with self._lock:
+            self._expire_idle_sessions(self._clock())
+            session = self._sessions.get(key)
+            if session is None:
+                return False
+            if session.active_leases:
+                raise SessionBusyError("cannot reset a session with an active lease")
+            session.branch.reset()
+            session.last_used = self._clock()
+            return True
+
+    def close_session(self, tenant_id: str, session_id: str) -> bool:
+        """Remove an idle session; return False if it does not exist."""
+        key = (
+            self._validate_id(tenant_id, "tenant_id"),
+            self._validate_id(session_id, "session_id"),
+        )
+        with self._lock:
+            session = self._sessions.get(key)
+            if session is None:
+                return False
+            if session.active_leases:
+                raise SessionBusyError("cannot close a session with an active lease")
+            del self._sessions[key]
+            return True
+
+    @property
+    def session_count(self) -> int:
+        """Return the number of registered sessions after expiring idle entries."""
+        with self._lock:
+            self._expire_idle_sessions(self._clock())
+            return len(self._sessions)

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/docs/CHANGELOG.md

@@ -6,6 +6,17 @@ uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-11-03
+
+### Added
+
+- Include the optional deployment session-isolation companion in the
+  published wheel and source distribution.
+
+### Changed
+
+- Add clean-install CI verification for the deployment package.
+
 ## [2.1.0] - 2026-11-03
 
 ### Added

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/fluidlayer/__init__.py

@@ -70,7 +70,7 @@ from .topology import (
                     unique_edges,
 )
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 version = __version__
 
 __all__ = [

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/fluidlayer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluidlayer
-Version: 2.1.0
+Version: 2.2.0
 Summary: A research memory layer for language models with optional GPT-2 and Qwen2 adapters
 Author: Kapil Dhinwa
 License: MIT

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/fluidlayer.egg-info/SOURCES.txt

@@ -8,6 +8,8 @@ pyproject.toml
 requirements.txt
 run_without_pytest.py
 selftest.py
+deployment/__init__.py
+deployment/session_registry.py
 docs/API.md
 docs/BLOG.md
 docs/CHANGELOG.md
@@ -76,6 +78,7 @@ tests/test_graft.py
 tests/test_memory.py
 tests/test_qwen2_model.py
 tests/test_selftest.py
+tests/test_session_registry.py
 tests/test_topology.py
 tests/test_torch_parity.py
 tools/_bundle_template.py

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/fluidlayer.egg-info/top_level.txt

@@ -1 +1,2 @@
+deployment
 fluidlayer

{fluidlayer-2.1.0 → fluidlayer-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fluidlayer"
-version = "2.1.0"
+version = "2.2.0"
 description = "A research memory layer for language models with optional GPT-2 and Qwen2 adapters"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -50,7 +50,7 @@ Issues = "https://github.com/kapildhinwa2010-dev/fluidtech/issues"
 Changelog = "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/docs/CHANGELOG.md"
 
 [tool.setuptools]
-packages = ["fluidlayer"]
+packages = ["fluidlayer", "deployment"]
 include-package-data = true
 
 [tool.setuptools.package-data]

fluidlayer-2.2.0/tests/test_session_registry.py

@@ -0,0 +1,126 @@
+import threading
+
+import pytest
+
+from deployment.session_registry import (
+    SessionBusyError,
+    SessionCapacityError,
+    SessionRegistry,
+)
+
+
+class DummyBranch:
+    def __init__(self):
+        self.values = []
+        self.reset_count = 0
+
+    def reset(self):
+        self.values.clear()
+        self.reset_count += 1
+
+
+def test_sessions_are_isolated_by_tenant_and_session():
+    registry = SessionRegistry(DummyBranch)
+
+    with registry.lease("tenant-a", "conversation") as first:
+        first.values.append("private")
+    with registry.lease("tenant-b", "conversation") as second:
+        assert second.values == []
+        second.values.append("other")
+    with registry.lease("tenant-a", "conversation") as first_again:
+        assert first_again is first
+        assert first_again.values == ["private"]
+
+
+def test_capacity_is_a_hard_bound_and_expired_sessions_are_reclaimed():
+    now = [0.0]
+    registry = SessionRegistry(
+        DummyBranch, max_sessions=1, ttl_seconds=5, clock=lambda: now[0]
+    )
+    with registry.lease("tenant", "one"):
+        pass
+
+    with pytest.raises(SessionCapacityError):
+        with registry.lease("tenant", "two"):
+            pass
+
+    now[0] = 5.0
+    with registry.lease("tenant", "two"):
+        assert registry.session_count == 1
+
+
+def test_active_leases_are_not_expired():
+    now = [0.0]
+    registry = SessionRegistry(DummyBranch, ttl_seconds=2, clock=lambda: now[0])
+
+    with registry.lease("tenant", "one"):
+        now[0] = 100.0
+        assert registry.session_count == 1
+
+
+def test_reset_and_close_require_an_idle_session():
+    registry = SessionRegistry(DummyBranch)
+    with registry.lease("tenant", "one") as branch:
+        branch.values.append("value")
+        with pytest.raises(SessionBusyError):
+            registry.reset_session("tenant", "one")
+        with pytest.raises(SessionBusyError):
+            registry.close_session("tenant", "one")
+
+    assert registry.reset_session("tenant", "one")
+    with registry.lease("tenant", "one") as reset_branch:
+        assert reset_branch.values == []
+        assert reset_branch.reset_count == 1
+    assert registry.close_session("tenant", "one")
+    assert not registry.close_session("tenant", "one")
+
+
+def test_requests_for_one_session_are_serialized():
+    registry = SessionRegistry(DummyBranch)
+    first_entered = threading.Event()
+    release_first = threading.Event()
+    second_entered = threading.Event()
+
+    def hold_first_lease():
+        with registry.lease("tenant", "same"):
+            first_entered.set()
+            assert release_first.wait(timeout=2)
+
+    def acquire_second_lease():
+        with registry.lease("tenant", "same"):
+            second_entered.set()
+
+    first = threading.Thread(target=hold_first_lease)
+    second = threading.Thread(target=acquire_second_lease)
+    first.start()
+    assert first_entered.wait(timeout=2)
+    second.start()
+    assert not second_entered.wait(timeout=0.05)
+    release_first.set()
+    first.join(timeout=2)
+    second.join(timeout=2)
+
+    assert not first.is_alive()
+    assert not second.is_alive()
+    assert second_entered.is_set()
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "error"),
+    [
+        ({"max_sessions": 0}, ValueError),
+        ({"max_sessions": True}, TypeError),
+        ({"ttl_seconds": 0}, ValueError),
+        ({"ttl_seconds": float("inf")}, ValueError),
+    ],
+)
+def test_configuration_is_validated(kwargs, error):
+    with pytest.raises(error):
+        SessionRegistry(DummyBranch, **kwargs)
+
+
+def test_blank_session_identifiers_are_rejected():
+    registry = SessionRegistry(DummyBranch)
+    with pytest.raises(ValueError):
+        with registry.lease("tenant", "  "):
+            pass