From ab6e7d7dc3d060c82012a6e57acfc928c0297db3 Mon Sep 17 00:00:00 2001 From: ningyixi <146685776+ningyixi@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:32:37 +0800 Subject: [PATCH] A Langflow component saves and searches Loom memory and knowledge documents A Langflow custom component calls memory.set, memory.search, and knowledge.search through a SyncAgent, with typed inputs for namespace, user, and query. Tests load the component by path, stub Langflow types, and give the SDK an httpx.MockTransport. Signed-off-by: ningyixi <146685776+ningyixi@users.noreply.github.com> --- docs/features/integrations/frameworks.md | 13 ++ integrations/README.md | 1 + integrations/langflow/README.md | 72 +++++++ integrations/langflow/loom_component.py | 201 ++++++++++++++++++++ tests/unit/test_langflow_component.py | 232 +++++++++++++++++++++++ 5 files changed, 519 insertions(+) create mode 100644 integrations/langflow/README.md create mode 100644 integrations/langflow/loom_component.py create mode 100644 tests/unit/test_langflow_component.py diff --git a/docs/features/integrations/frameworks.md b/docs/features/integrations/frameworks.md index 84e075e5b8..ac5a0e9913 100644 --- a/docs/features/integrations/frameworks.md +++ b/docs/features/integrations/frameworks.md @@ -36,6 +36,7 @@ or needs another database, vector store or cache. | Dify | Remember, Recall, Search knowledge | `integrations/dify` standalone plugin | Native Dify tools | | Haystack | `LoomDocumentStore`, `LoomRetriever` | Python, `loom.integrations.haystack` | `DocumentStore` protocol, retrieval component | | Agno | `LoomMemoryDb` | Python, `loom.integrations.agno` | `BaseDb` user-memory methods | +| Langflow | Loom | `integrations/langflow` custom component | Langflow `Component` | Any other framework that can call an HTTP endpoint or an MCP server uses Loom directly: see [agent integration](../../guides/agent-integration.md) and @@ -1071,6 +1072,18 @@ for its lifetime, so the turns of one call share a session. | `honour_abstain` | `True` | leave out memories below Loom's floor; nothing when Loom abstains | | `defer` | `True` | queue the extraction on the server instead of waiting | +## Langflow + +The [Loom Langflow component](../../../integrations/langflow/README.md) saves a memory, +searches memories, and searches knowledge documents from a Langflow flow. It is a +Langflow `Component` with typed inputs for the namespace, the user, and the query, plus +an action dropdown (`save`, `search memory`, `search documents`). Install +`clickhouse-loom` in Langflow's Python environment and load +`integrations/langflow/loom_component.py` as a custom component. The component +constructs a `SyncAgent` and calls `memory.set`, `memory.search`, or `knowledge.search`; +the user input is `user_id` on the memory write and search. Knowledge search is +namespace-scoped. Data stays in your Loom deployment; the component adds no store. + ## Agent orchestrators A harness that runs several agents gives them shared, durable memory by mounting Loom's diff --git a/integrations/README.md b/integrations/README.md index e8e48acd40..ea605f79e3 100644 --- a/integrations/README.md +++ b/integrations/README.md @@ -20,6 +20,7 @@ adapters). | Aider, Continue, OpenCode, any chat export | [`generic/`](generic/README.md) | none: run after the session on an exported `.json` / `.md` transcript | run `generic/ingest.sh` | bash, the `loom` CLI | `LOOM_API_KEY` or `~/.loom/token`, never on argv | `integrations/generic/test.sh` | | Agents that only use shell grep | [`grep-shim/`](grep-shim/README.md) | none: `grep` / `rg` on `PATH` | put `grep-shim/bin` first on `PATH` | Node 18+ | viewer token in `LOOM_API_KEY` | `node --test integrations/grep-shim/tests/*.test.mjs` | | LibreChat v0.8.8 (chat client) | [`librechat/`](librechat/README.md) | none: a person chats; the model calls the `assistant` toolset over MCP | `docker compose up -d` in `librechat/` ([guide](../docs/features/integrations/librechat.md)) | Docker | each person's own viewer token, stored per user in LibreChat (`customUserVars`) | `tests/unit/test_librechat_integration.py` | +| Langflow 1.13.3 | [`langflow/`](langflow/README.md) | none: a flow calls save, search memory, or search documents | load `langflow/loom_component.py` as a custom component; `pip install clickhouse-loom` in Langflow's env | Langflow, the Python SDK | writer token: `LOOM_API_KEY` or the component's API key input | `tests/unit/test_langflow_component.py` | | AX sandboxed tasks | [`ax/`](ax/README.md) | none: the agent calls Loom over MCP or the SDK | steps 1–4 of [`ax/README.md`](ax/README.md) | the task's image | writer token in a Kubernetes Secret, injected by Substrate's egress gateway; never in the Task | | | Git repositories holding OKF bundles | [`okf-ci/`](okf-ci/README.md) | push, pull request | copy `okf-lint.yml` to `.github/workflows/`, pin `LOOM_REF` | GitHub Actions, uv | none: the lint is offline; `contents: read` | actionlint; `loom okf-lint` is covered by `tests/unit/test_okf_lint.py` | diff --git a/integrations/langflow/README.md b/integrations/langflow/README.md new file mode 100644 index 0000000000..124a573d28 --- /dev/null +++ b/integrations/langflow/README.md @@ -0,0 +1,72 @@ +# Langflow + +A Langflow custom component that saves and searches Loom memory and searches +knowledge documents through the Python SDK. + +The component is a Langflow \`Component\` with typed inputs for the namespace, the +user, and the query, and an action dropdown: \`save\`, \`search memory\`, or +\`search documents\`. It constructs a \`SyncAgent\` and calls \`memory.set\`, +\`memory.search\`, or \`knowledge.search\`. The user input is sent as \`user_id\` on +the memory write and search. Knowledge search is namespace-scoped. Data stays in +your Loom deployment; the component adds no store. + +## Install + +These steps were checked against Langflow 1.13.3. + +Install the Python SDK into the same environment as Langflow, from this checkout: + +```bash +pip install /path/to/loom/sdk/python +``` + +Or install the published package with `pip install clickhouse-loom`. + +Load [`loom_component.py`](loom_component.py) as a Langflow custom component: +paste the file into a new custom component, or point Langflow's custom +components path at this directory, then start Langflow: + +```bash +export LANGFLOW_COMPONENTS_PATH=/path/to/loom/integrations/langflow +langflow run +``` + +The component appears as **Loom**. It needs a reachable Loom server (a +[quickstart](../../docs/getting-started/quickstart.md) listens on +`http://localhost:7777`) and a namespace-scoped writer token. + +## Inputs + +| Input | Role | +| ---------- | ------------------------------------------------------------------------ | +| Action | `save`, `search memory`, or `search documents` | +| Org | Organization; may be empty when the token fills it | +| Namespace | Namespace the component reads and writes | +| User | End user for `memory.set` and `memory.search`; empty reads the namespace | +| Query | Value to save, or the search query | +| Memory key | Required when the action is `save` | +| Top K | Number of search hits (default 5) | +| Loom URL | Server URL (default `http://localhost:7777`) | +| API key | Writer token; may also come from `LOOM_API_KEY` or the Loom profile | +| Agent | Agent name stamped on writes (default `langflow`) | + +## A flow + +1. Start a Loom quickstart at `http://localhost:7777` and create a writer token. +2. In Langflow 1.13.3, add a Chat Input, a Loom component, and a Chat Output. + Connect Chat Input to the Loom Query input, and the Loom Result to Chat Output. +3. On the Loom component, set Action to `save`, Namespace to your namespace, User + to the end-user id, Memory key to a stable key such as `pref.seat`, and Org, + API key, and Loom URL from the quickstart. +4. Run the flow with a message such as "aisle seat". The Result is a JSON object + with `action`, `memory_id`, `version`, and `content_sha256`. +5. Add a second Loom component with the same Org, Namespace, User, API key, and + URL, Action `search memory`, and Query from Chat Input. Run with "which + seat". The Result is a JSON object with `action`, `abstain`, and `hits` + (`memory_key`, `value`, `similarity`). A `search documents` run returns + `action` and `hits` (`source_uri`, `content`, `similarity`). + +Unit tests under `tests/unit/test_langflow_component.py` drive each action with +the SDK pointed at an `httpx.MockTransport`, so they do not need Langflow or a +live Loom server. A recorded transcript from a live Langflow session against a +quickstart is not included here. diff --git a/integrations/langflow/loom_component.py b/integrations/langflow/loom_component.py new file mode 100644 index 0000000000..679e391c9c --- /dev/null +++ b/integrations/langflow/loom_component.py @@ -0,0 +1,201 @@ +"""Langflow custom component: save and search Loom memory, and search knowledge documents.""" + +from __future__ import annotations + +from typing import Any + +from lfx.custom.custom_component.component import Component +from lfx.io import ( + DropdownInput, + IntInput, + MessageTextInput, + Output, + SecretStrInput, + StrInput, +) +from lfx.schema.data import Data +from loom import SyncAgent + +SAVE = "save" +SEARCH_MEMORY = "search memory" +SEARCH_DOCUMENTS = "search documents" +_ACTIONS = (SAVE, SEARCH_MEMORY, SEARCH_DOCUMENTS) + + +def _open_agent(**kwargs: Any) -> SyncAgent: + return SyncAgent(**kwargs) + + +def _text(value: Any) -> str: + return str(value or "").strip() + + +def _secret(value: Any) -> str | None: + if value is None: + return None + raw = value.get_secret_value() if hasattr(value, "get_secret_value") else value + text = _text(raw) + return text or None + + +def _query_text(value: Any) -> str: + if value is None: + return "" + if isinstance(value, str): + return value + inner = getattr(value, "text", None) + if isinstance(inner, str): + return inner + return str(value) + + +class LoomComponent(Component): + display_name = "Loom" + description = "Save and search Loom memory, and search knowledge documents." + documentation: str = ( + "https://github.com/ClickHouse/loom/blob/main/integrations/langflow/README.md" + ) + icon = "database" + name = "Loom" + + inputs = [ + DropdownInput( + name="action", + display_name="Action", + options=list(_ACTIONS), + value=SEARCH_MEMORY, + info="Save a memory, search memories, or search knowledge documents.", + ), + StrInput(name="org", display_name="Org", value="", required=False), + StrInput( + name="namespace", + display_name="Namespace", + value="", + required=True, + info="Loom namespace the component reads and writes.", + ), + StrInput( + name="user_id", + display_name="User", + value="", + required=False, + info="End user for memory.set and memory.search. Empty reads the namespace.", + ), + MessageTextInput( + name="query", + display_name="Query", + value="", + required=True, + info="The memory value to save, or the search query.", + ), + StrInput( + name="memory_key", + display_name="Memory key", + value="", + required=False, + info="Required when the action is save.", + ), + IntInput(name="top_k", display_name="Top K", value=5, required=False), + StrInput( + name="base_url", + display_name="Loom URL", + value="http://localhost:7777", + required=False, + ), + SecretStrInput(name="api_key", display_name="API key", value="", required=False), + StrInput( + name="agent_name", + display_name="Agent", + value="langflow", + required=False, + info="Agent name stamped on writes.", + ), + ] + outputs = [ + Output(display_name="Result", name="result", method="produce_result"), + ] + + def produce_result(self) -> Data: + action = _text(getattr(self, "action", "")) + if action not in _ACTIONS: + raise ValueError(f"unknown action: {action or '(empty)'}") + namespace = _text(getattr(self, "namespace", "")) + if not namespace: + raise ValueError("namespace is required") + memory_key = _text(getattr(self, "memory_key", "")) + if action == SAVE and not memory_key: + raise ValueError("memory_key is required when saving a memory") + return Data(data=self._call_loom(action, namespace, memory_key)) + + def _call_loom(self, action: str, namespace: str, memory_key: str) -> dict[str, Any]: + with _open_agent(**self._agent_kwargs(namespace)) as agent: + user_id = _text(getattr(self, "user_id", "")) or None + query = _query_text(getattr(self, "query", "")) + top_k = int(getattr(self, "top_k", 5) or 5) + if action == SAVE: + written = agent.memory.set(memory_key, query, user_id=user_id) + return _save_payload(written) + if action == SEARCH_MEMORY: + found = agent.memory.search(query, user_id=user_id, top_k=top_k) + return _memory_hits_payload(found) + found = agent.knowledge.search(query, top_k=top_k) + return _document_hits_payload(found) + + def _agent_kwargs(self, namespace: str) -> dict[str, Any]: + kwargs: dict[str, Any] = { + "org": _text(getattr(self, "org", "")), + "namespace": namespace, + "agent": _text(getattr(self, "agent_name", "")) or "langflow", + "retry": {"max_attempts": 1}, + } + base_url = _text(getattr(self, "base_url", "")) + if base_url: + kwargs["base_url"] = base_url + api_key = _secret(getattr(self, "api_key", None)) + if api_key: + kwargs["api_key"] = api_key + return kwargs + + +def _save_payload(written: dict[str, Any]) -> dict[str, Any]: + return { + "action": SAVE, + "memory_id": written.get("memory_id"), + "version": written.get("version"), + "content_sha256": written.get("content_sha256"), + "conflict_verdict": written.get("conflict_verdict"), + "noop": written.get("noop"), + } + + +def _memory_hits_payload(found: Any) -> dict[str, Any]: + hits = [ + { + "memory_key": hit.memory_key, + "value": hit.content_excerpt, + "similarity": hit.similarity, + "memory_type": hit.memory_type, + "namespace": hit.namespace, + } + for hit in found + ] + return { + "action": SEARCH_MEMORY, + "abstain": bool(getattr(found, "abstain", False)), + "abstain_code": getattr(found, "abstain_code", "") or "", + "hits": hits, + } + + +def _document_hits_payload(found: list[Any]) -> dict[str, Any]: + hits = [ + { + "source_uri": hit.source_uri, + "content": hit.content, + "similarity": hit.similarity, + "chunk_idx": hit.chunk_idx, + "namespace": hit.namespace, + } + for hit in found + ] + return {"action": SEARCH_DOCUMENTS, "hits": hits} diff --git a/tests/unit/test_langflow_component.py b/tests/unit/test_langflow_component.py new file mode 100644 index 0000000000..ac537a4e45 --- /dev/null +++ b/tests/unit/test_langflow_component.py @@ -0,0 +1,232 @@ +"""Langflow component: each action's request and output, without installing Langflow.""" + +from __future__ import annotations + +import importlib.util +import json +import sys +import types +from pathlib import Path + +import httpx +import pytest +from loom import SyncAgent + +ROOT = Path(__file__).resolve().parents[2] +COMPONENT = ROOT / "integrations" / "langflow" / "loom_component.py" + + +class _Field: + def __init__(self, **kwargs: object) -> None: + self.__dict__.update(kwargs) + + +class _Data: + def __init__(self, data: object = None, **kwargs: object) -> None: + self.data = data if data is not None else dict(kwargs) + + +class _Component: + pass + + +def _install_lfx_stubs() -> None: + lfx = types.ModuleType("lfx") + custom = types.ModuleType("lfx.custom") + custom_component = types.ModuleType("lfx.custom.custom_component") + component = types.ModuleType("lfx.custom.custom_component.component") + component.Component = _Component + io = types.ModuleType("lfx.io") + io.DropdownInput = _Field + io.IntInput = _Field + io.MessageTextInput = _Field + io.SecretStrInput = _Field + io.StrInput = _Field + io.Output = _Field + schema = types.ModuleType("lfx.schema") + data = types.ModuleType("lfx.schema.data") + data.Data = _Data + modules = { + "lfx": lfx, + "lfx.custom": custom, + "lfx.custom.custom_component": custom_component, + "lfx.custom.custom_component.component": component, + "lfx.io": io, + "lfx.schema": schema, + "lfx.schema.data": data, + } + sys.modules.update(modules) + lfx.custom = custom + custom.custom_component = custom_component + custom_component.component = component + lfx.io = io + lfx.schema = schema + schema.data = data + + +def _load_component(): + _install_lfx_stubs() + spec = importlib.util.spec_from_file_location("loom_langflow_component", COMPONENT) + assert spec is not None and spec.loader is not None + mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(mod) + return mod + + +@pytest.fixture +def component_mod(): + return _load_component() + + +def _handler(responses: dict[str, dict]) -> tuple[list[tuple[str, dict]], object]: + recorded: list[tuple[str, dict]] = [] + + def handler(request: httpx.Request) -> httpx.Response: + body = json.loads(request.content) if request.content else {} + path = request.url.path + suffix = path.split("/v1/", 1)[-1] if "/v1/" in path else path + recorded.append((suffix, body)) + payload = responses.get(suffix) + if payload is None: + return httpx.Response(404, json={"error": f"unexpected {path}"}) + return httpx.Response(200, json=payload) + + return recorded, handler + + +def _patch_agent(mod, handler) -> None: + def factory(**kwargs): + sa = SyncAgent(**kwargs) + base = kwargs.get("base_url") or "http://x" + sa.transport._client = httpx.AsyncClient( + base_url=base, transport=httpx.MockTransport(handler) + ) + return sa + + mod._open_agent = factory + + +def _node(mod, **inputs): + node = mod.LoomComponent() + values = { + "action": "search memory", + "org": "acme", + "namespace": "support", + "user_id": "alice", + "query": "preferred seat", + "memory_key": "", + "top_k": 5, + "base_url": "http://x", + "api_key": "k", + "agent_name": "langflow", + } + values.update(inputs) + for key, value in values.items(): + setattr(node, key, value) + return node + + +def test_save_sends_memory_set_and_returns_write_fields(component_mod) -> None: + recorded, handler = _handler( + { + "memory.set": { + "memory_id": "m-1", + "version": 1, + "content_sha256": "abc", + "conflict_verdict": "clear", + "noop": False, + } + } + ) + _patch_agent(component_mod, handler) + result = _node( + component_mod, action="save", memory_key="pref.seat", query="aisle seat" + ).produce_result() + assert recorded[0][0] == "memory.set" + body = recorded[0][1] + assert body["org"] == "acme" + assert body["namespace"] == "support" + assert body["user_id"] == "alice" + assert body["memory_key"] == "pref.seat" + assert body["value"] == "aisle seat" + assert result.data["action"] == "save" + assert result.data["memory_id"] == "m-1" + assert result.data["version"] == 1 + assert result.data["content_sha256"] == "abc" + + +def test_search_memory_sends_query_and_returns_hits(component_mod) -> None: + recorded, handler = _handler( + { + "memory.search": { + "results": [ + { + "memory_key": "pref.seat", + "memory_type": "semantic", + "content_excerpt": "aisle seat", + "distance": 0.1, + "similarity": 0.9, + "namespace": "support", + } + ], + "abstain": False, + "abstain_code": "", + } + } + ) + _patch_agent(component_mod, handler) + result = _node( + component_mod, action="search memory", query="which seat", top_k=3 + ).produce_result() + assert recorded[0][0] == "memory.search" + body = recorded[0][1] + assert body["org"] == "acme" + assert body["namespace"] == "support" + assert body["user_id"] == "alice" + assert body["query"] == "which seat" + assert body["top_k"] == 3 + assert result.data["action"] == "search memory" + assert result.data["abstain"] is False + assert result.data["hits"][0]["memory_key"] == "pref.seat" + assert result.data["hits"][0]["value"] == "aisle seat" + assert result.data["hits"][0]["similarity"] == 0.9 + + +def test_search_documents_sends_query_and_returns_hits(component_mod) -> None: + recorded, handler = _handler( + { + "knowledge.search": { + "results": [ + { + "source_uri": "doc://guide", + "chunk_idx": 0, + "content": "Seat map is in the cabin guide.", + "tags": [], + "distance": 0.2, + "similarity": 0.8, + "namespace": "support", + } + ] + } + } + ) + _patch_agent(component_mod, handler) + result = _node( + component_mod, action="search documents", query="cabin guide", top_k=2 + ).produce_result() + assert recorded[0][0] == "knowledge.search" + body = recorded[0][1] + assert body["org"] == "acme" + assert body["namespace"] == "support" + assert body["query"] == "cabin guide" + assert body["top_k"] == 2 + assert "user_id" not in body + assert result.data["action"] == "search documents" + assert result.data["hits"][0]["source_uri"] == "doc://guide" + assert result.data["hits"][0]["content"] == "Seat map is in the cabin guide." + assert result.data["hits"][0]["similarity"] == 0.8 + + +def test_save_requires_memory_key(component_mod) -> None: + with pytest.raises(ValueError, match="memory_key is required"): + _node(component_mod, action="save", memory_key="").produce_result()