Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions docs/features/integrations/frameworks.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
# Agent frameworks and orchestrators

The SDKs ship adapters that present Loom through a framework's own memory or retrieval
interface. An adapter needs its framework: in Python, the SDK extra its section names
(`pip install 'clickhouse-loom[langchain]'` and so on); in TypeScript, the framework
package, an optional peer dependency. The LangGraph and Strands adapters import without
their framework. Identity comes from the Loom `Agent` the adapter wraps, and isolation is
interface. An adapter needs its framework: in Python, the SDK extra its section names;
in TypeScript, the framework package, an optional peer dependency. The LangGraph and
Strands adapters import without their framework. Identity comes from the Loom `Agent` the adapter wraps, and isolation is
Loom's namespace authorization. Every adapter calls your Loom server through the SDK: the
data is stored in your Loom deployment (ClickHouse, and Postgres for live memory under the
[Postgres memory authority](../../architecture/storage-authority.md)), and no adapter adds
Expand Down Expand Up @@ -47,7 +46,7 @@ see [agent integration](../../guides/agent-integration.md) and
`LoomKnowledgeRetriever` searches the namespace's documents (`knowledge.search`) and
`LoomMemoryRetriever` its memories (`memory.search`). Both are LangChain `BaseRetriever`s,
so they work with `invoke`, in a chain, and as an agent tool through
`create_retriever_tool`. Install with `pip install 'clickhouse-loom[langchain]'`
`create_retriever_tool`. Install with `pip install 'clickhouse-loom[langchain]==1.3.0'`
(`langchain-core` 1.x).

```python
Expand Down Expand Up @@ -91,9 +90,11 @@ families.
A LangChain agent built with `create_agent` runs on LangGraph: pass `LoomStore` (below)
as its `store` for long-term memory.

The TypeScript retrievers extend `BaseRetriever` from `@langchain/core` (an optional peer
dependency, 1.x) and take the same options in camelCase, with the memory retriever's
user, session, run and agent in one `scope`:
Install the TypeScript SDK and its framework peer with
`npm install @clickhouse/loom@1.3.0 '@langchain/core@^1.0.0'`.
The TypeScript retrievers extend `BaseRetriever` from `@langchain/core` and take the same
options in camelCase, with the memory retriever's user, session, run and agent in one
`scope`:

```ts
import {
Expand Down
4 changes: 3 additions & 1 deletion tests/integration/test_cell_control_fence.py
Original file line number Diff line number Diff line change
Expand Up @@ -393,7 +393,9 @@ async def mutate(conn, found):
old = await claim(client, await read(client))
task = asyncio.create_task(client.post("/test-finalize/first", json=expected(old)))
await asyncio.wait_for(started.wait(), 3)
await local_admin.execute("SELECT pg_terminate_backend($1)", a.get_server_pid())
assert await local_admin.fetchval(
"SELECT pg_terminate_backend($1, 5000)", a.get_server_pid()
)
await apg.take_lock(b, "new controller")
newer = await claim(client, await read(client))

Expand Down
46 changes: 27 additions & 19 deletions tests/unit/test_provider_zombie_exit.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
import os
import select
import signal
import subprocess
import sys
import threading
import time
from pathlib import Path
Expand Down Expand Up @@ -41,16 +43,18 @@ def _wait_owned(pid: int, start: str) -> int:

def test_an_exact_single_thread_zombie_is_proven_stopped_before_wait() -> None:
"""A captured child has exited, even while its parent retains the wait status."""
read_fd, write_fd = os.pipe()
pid = os.fork()
if pid == 0:
os.close(write_fd)
os.read(read_fd, 1)
os._exit(0)
os.close(read_fd)
start = None
released = False
# Fork hooks can start exporter threads; exec gives this witness one thread.
child = subprocess.Popen(
[sys.executable, "-I", "-c", "import os; os.write(1, b'r'); os.read(0, 1)"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
env={},
)
assert child.stdin is not None and child.stdout is not None
pid = child.pid
try:
assert select.select([child.stdout], [], [], 2.0)[0] == [child.stdout]
assert child.stdout.read(1) == b"r"
state, parent, start, threads = _stat(pid)
assert state != "Z" and parent == os.getpid() and threads == 1
proof = provider_process.host_proof().split("|")
Expand All @@ -61,8 +65,8 @@ def test_an_exact_single_thread_zombie_is_proven_stopped_before_wait() -> None:
wrong_namespace = proof.copy()
wrong_namespace[3] = str(int(proof[3]) + 1)
assert not provider_process.proves_stopped("|".join(wrong_namespace))
os.write(write_fd, b"x")
released = True
child.stdin.write(b"x")
child.stdin.flush()
end = time.monotonic() + 2.0
while time.monotonic() < end:
state, parent, observed_start, threads = _stat(pid)
Expand All @@ -75,14 +79,18 @@ def test_an_exact_single_thread_zombie_is_proven_stopped_before_wait() -> None:
)
assert provider_process.proves_stopped(exact)
finally:
if not released:
os.write(write_fd, b"x")
os.close(write_fd)
if start is None:
_, parent, start, _ = _stat(pid)
assert parent == os.getpid()
status = _wait_owned(pid, start)
assert os.WIFEXITED(status) and os.WEXITSTATUS(status) == 0
child.stdin.close()
try:
status = child.wait(timeout=2.0)
except subprocess.TimeoutExpired:
child.kill()
child.wait(timeout=2.0)
raise AssertionError(
"Owned witness child did not settle within cleanup allowance"
) from None
finally:
child.stdout.close()
assert status == 0
assert provider_process.proves_stopped(exact), "After waitpid, absence proves death"


Expand Down