atomicmemory-langflow 0.1.17__tar.gz

atomicmemory_langflow-0.1.17/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: atomicmemory-langflow
+Version: 0.1.17
+Summary: AtomicMemory custom components for Langflow.
+Author: Atomic Strata
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/atomicstrata/atomicmemory
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: atomicmemory<2.0.0,>=1.1.0
+Requires-Dist: langchain-core<2.0,>=0.3
+Provides-Extra: langflow
+Requires-Dist: langflow<2.0,>=1.6; extra == "langflow"
+
+# AtomicMemory components for Langflow
+
+Four Langflow custom components backed by the Python `atomicmemory` SDK:
+
+They appear in the Langflow component sidebar under the **atomicmemory** category:
+
+| Component | Purpose |
+|-----------|---------|
+| **Chat Memory (AtomicMemory)** | Read-only chat history (Message History backend) from a user/session scope. |
+| **Search Context (AtomicMemory)** | Query-driven, prompt-ready memory context, **user-scoped across sessions** by default (packaged or search-only). |
+| **Store Message (AtomicMemory)** | Explicitly persist a message/turn into memory. |
+| **Delete Memories in Scope (AtomicMemory)** | Best-effort erasure of a scope's memories (confirm-gated). |
+
+## Requirements & compatibility
+
+- Python ≥ 3.10, `atomicmemory >= 1.0.1`, `langchain-core`.
+- **Langflow is the host** and must be installed in the same environment.
+  Tested with Langflow `>=1.6,<2.0` (the components import a few `lfx` internals;
+  see the loader smoke test). Newer Langflow majors may move these symbols.
+- A running **AtomicMemory Core** (default `http://localhost:17350`). Core needs
+  an LLM/embeddings key for ingest extraction.
+
+> **Heads up:** ingest runs synchronous LLM extraction + embedding, so storing a
+> memory can take **seconds (sometimes ~20s)**. Writes are explicit (Store Message)
+> so this latency is visible, not hidden. Chat Memory is **read-only** — it never
+> auto-writes on every turn. If the backend is unreachable, Chat Memory **fails
+> closed** (raises a clear error) by default; set its `Fail open on error` toggle
+> to return empty history instead.
+
+## Install
+
+```bash
+pip install atomicmemory-langflow            # into Langflow's environment
+# copy the component entry files into your Langflow components root:
+npx @atomicmemory/langflow-plugin --target ~/.langflow/components --python <langflow-python>
+# or set the components root via env instead of --target:
+LANGFLOW_COMPONENTS_PATH=~/.langflow/components npx @atomicmemory/langflow-plugin --python <langflow-python>
+```
+Restart Langflow; the components appear under the **atomicmemory** category.
+
+## Scope, identity & multi-tenant safety
+
+Memory is scoped by `user` (required) and optional `session` (thread).
+`User ID` defaults to the **Langflow run user** when blank; an explicit value
+overrides it. Note this is run context, not strong auth — in CLI/anonymous paths
+Langflow may auto-generate an opaque user id.
+
+**Search Context recalls user-scoped (across sessions) by default** — long-term
+memory should persist beyond a single conversation, and Core hard-filters
+search/list by session. Set its advanced `Scope to session` toggle to restrict
+retrieval to the current session. Chat Memory (this-conversation history) and
+Store Message remain session-aware.
+
+(`namespace` is not exposed in Phase 1: the AtomicMemory Python provider only
+applies it on search/package, not ingest/list/delete, so exposing it would
+silently break store/delete scoping. It returns once the SDK honors it end-to-end.)
+
+**Trust boundary:** scope is the only memory boundary, and Langflow lets `user_id`/
+`session_id` be set via flow inputs/tweaks. In shared / multi-tenant / Cloud
+deployments, control who can edit and run flows — a flow author who sets `user_id`
+can read/write that user's memories.
+
+## Security
+
+- Put API keys only in the **API Key** (secret) field — never in **Provider Config**
+  (it is stored in plaintext in the flow). **Provider Config is allowlist-only**:
+  only known tuning keys (`timeoutSeconds`, `apiVersion`) are accepted; everything
+  else — URLs, keys, and any secret-shaped key (`accessToken`, `clientSecret`, …) —
+  is rejected.
+- **`provider` is validated**: Phase 1 accepts only `atomicmemory`, even via API/tweaks
+  (the UI dropdown is not the only guard).
+- **`API URL` is fail-closed for remote hosts.** It must be `http(s)` and resolve to a
+  local host by default; pointing memory at a non-local endpoint requires the
+  **operator** (not the flow author) to opt in via `ATOMICMEMORY_LANGFLOW_ALLOW_REMOTE=1`
+  or `ATOMICMEMORY_LANGFLOW_ALLOWED_HOSTS=host1,host2`. **This is not full SSRF
+  protection:** it does not sandbox the loopback interface, so a flow author can still
+  reach services bound to the Langflow host's `localhost`/`127.0.0.1` (any port). Treat
+  flow authors as trusted, or add network-egress controls, on shared/multi-tenant/cloud
+  deployments.
+- Retrieved memory is emitted as ordinary context, never as a system message.
+
+## Provider neutrality
+
+`provider` defaults to `atomicmemory` (the only Phase 1 tested provider). The
+architecture is provider-neutral — provider name + `provider_config` flow to the
+SDK — but other providers are not yet listed in the dropdown.
+
+## Testing & known follow-ups
+
+Unit tests run without a live backend (`cd plugins/langflow && python -m unittest
+discover -s tests`); the SDK-contract and Langflow-loader tests exercise the real
+`atomicmemory` SDK models and `lfx` template builder when those packages are
+installed.
+
+Follow-ups (tracked, not yet in this PR):
+- **End-to-end lane against a real AtomicMemory Core** (Docker + Core + an LLM key):
+  Store Message → Search Context → Delete with synthetic data, with the package
+  installed into a Langflow-compatible venv. Unit tests use fakes/model coercion;
+  this lane would catch integration drift the fakes can't.
+- **Namespace scoping** once the Python SDK honors it on ingest/list/delete (today
+  only search/package), at which point the `namespace` input returns.
+- **Branded AtomicMemory icon** (vendor logo, like the model providers') — **deferred**.
+  Each component currently uses a distinct Lucide icon (`save` / `search` /
+  `messages-square` / `trash`). A real brand mark is a Langflow *vendor icon*, which
+  per Langflow's docs requires frontend changes (an `@/icons/AtomicMemory` SVG +
+  forwardRef wrapper + a `lazyIconImports` entry) and so cannot ship from a Python
+  component bundle — it needs an upstream Langflow PR. Logo SVGs exist under
+  `supermem-internal-web/static/img/`.

atomicmemory_langflow-0.1.17/README.md

@@ -0,0 +1,108 @@
+# AtomicMemory components for Langflow
+
+Four Langflow custom components backed by the Python `atomicmemory` SDK:
+
+They appear in the Langflow component sidebar under the **atomicmemory** category:
+
+| Component | Purpose |
+|-----------|---------|
+| **Chat Memory (AtomicMemory)** | Read-only chat history (Message History backend) from a user/session scope. |
+| **Search Context (AtomicMemory)** | Query-driven, prompt-ready memory context, **user-scoped across sessions** by default (packaged or search-only). |
+| **Store Message (AtomicMemory)** | Explicitly persist a message/turn into memory. |
+| **Delete Memories in Scope (AtomicMemory)** | Best-effort erasure of a scope's memories (confirm-gated). |
+
+## Requirements & compatibility
+
+- Python ≥ 3.10, `atomicmemory >= 1.0.1`, `langchain-core`.
+- **Langflow is the host** and must be installed in the same environment.
+  Tested with Langflow `>=1.6,<2.0` (the components import a few `lfx` internals;
+  see the loader smoke test). Newer Langflow majors may move these symbols.
+- A running **AtomicMemory Core** (default `http://localhost:17350`). Core needs
+  an LLM/embeddings key for ingest extraction.
+
+> **Heads up:** ingest runs synchronous LLM extraction + embedding, so storing a
+> memory can take **seconds (sometimes ~20s)**. Writes are explicit (Store Message)
+> so this latency is visible, not hidden. Chat Memory is **read-only** — it never
+> auto-writes on every turn. If the backend is unreachable, Chat Memory **fails
+> closed** (raises a clear error) by default; set its `Fail open on error` toggle
+> to return empty history instead.
+
+## Install
+
+```bash
+pip install atomicmemory-langflow            # into Langflow's environment
+# copy the component entry files into your Langflow components root:
+npx @atomicmemory/langflow-plugin --target ~/.langflow/components --python <langflow-python>
+# or set the components root via env instead of --target:
+LANGFLOW_COMPONENTS_PATH=~/.langflow/components npx @atomicmemory/langflow-plugin --python <langflow-python>
+```
+Restart Langflow; the components appear under the **atomicmemory** category.
+
+## Scope, identity & multi-tenant safety
+
+Memory is scoped by `user` (required) and optional `session` (thread).
+`User ID` defaults to the **Langflow run user** when blank; an explicit value
+overrides it. Note this is run context, not strong auth — in CLI/anonymous paths
+Langflow may auto-generate an opaque user id.
+
+**Search Context recalls user-scoped (across sessions) by default** — long-term
+memory should persist beyond a single conversation, and Core hard-filters
+search/list by session. Set its advanced `Scope to session` toggle to restrict
+retrieval to the current session. Chat Memory (this-conversation history) and
+Store Message remain session-aware.
+
+(`namespace` is not exposed in Phase 1: the AtomicMemory Python provider only
+applies it on search/package, not ingest/list/delete, so exposing it would
+silently break store/delete scoping. It returns once the SDK honors it end-to-end.)
+
+**Trust boundary:** scope is the only memory boundary, and Langflow lets `user_id`/
+`session_id` be set via flow inputs/tweaks. In shared / multi-tenant / Cloud
+deployments, control who can edit and run flows — a flow author who sets `user_id`
+can read/write that user's memories.
+
+## Security
+
+- Put API keys only in the **API Key** (secret) field — never in **Provider Config**
+  (it is stored in plaintext in the flow). **Provider Config is allowlist-only**:
+  only known tuning keys (`timeoutSeconds`, `apiVersion`) are accepted; everything
+  else — URLs, keys, and any secret-shaped key (`accessToken`, `clientSecret`, …) —
+  is rejected.
+- **`provider` is validated**: Phase 1 accepts only `atomicmemory`, even via API/tweaks
+  (the UI dropdown is not the only guard).
+- **`API URL` is fail-closed for remote hosts.** It must be `http(s)` and resolve to a
+  local host by default; pointing memory at a non-local endpoint requires the
+  **operator** (not the flow author) to opt in via `ATOMICMEMORY_LANGFLOW_ALLOW_REMOTE=1`
+  or `ATOMICMEMORY_LANGFLOW_ALLOWED_HOSTS=host1,host2`. **This is not full SSRF
+  protection:** it does not sandbox the loopback interface, so a flow author can still
+  reach services bound to the Langflow host's `localhost`/`127.0.0.1` (any port). Treat
+  flow authors as trusted, or add network-egress controls, on shared/multi-tenant/cloud
+  deployments.
+- Retrieved memory is emitted as ordinary context, never as a system message.
+
+## Provider neutrality
+
+`provider` defaults to `atomicmemory` (the only Phase 1 tested provider). The
+architecture is provider-neutral — provider name + `provider_config` flow to the
+SDK — but other providers are not yet listed in the dropdown.
+
+## Testing & known follow-ups
+
+Unit tests run without a live backend (`cd plugins/langflow && python -m unittest
+discover -s tests`); the SDK-contract and Langflow-loader tests exercise the real
+`atomicmemory` SDK models and `lfx` template builder when those packages are
+installed.
+
+Follow-ups (tracked, not yet in this PR):
+- **End-to-end lane against a real AtomicMemory Core** (Docker + Core + an LLM key):
+  Store Message → Search Context → Delete with synthetic data, with the package
+  installed into a Langflow-compatible venv. Unit tests use fakes/model coercion;
+  this lane would catch integration drift the fakes can't.
+- **Namespace scoping** once the Python SDK honors it on ingest/list/delete (today
+  only search/package), at which point the `namespace` input returns.
+- **Branded AtomicMemory icon** (vendor logo, like the model providers') — **deferred**.
+  Each component currently uses a distinct Lucide icon (`save` / `search` /
+  `messages-square` / `trash`). A real brand mark is a Langflow *vendor icon*, which
+  per Langflow's docs requires frontend changes (an `@/icons/AtomicMemory` SVG +
+  forwardRef wrapper + a `lazyIconImports` entry) and so cannot ship from a Python
+  component bundle — it needs an upstream Langflow PR. Logo SVGs exist under
+  `supermem-internal-web/static/img/`.

atomicmemory_langflow-0.1.17/atomicmemory_langflow/__init__.py

@@ -0,0 +1,30 @@
+"""AtomicMemory custom components for Langflow.
+
+Importing this package does NOT import Langflow (`lfx`). Component classes are
+resolved lazily via ``__getattr__`` so the lfx-free helper modules
+(``_scope``/``_messages``/``_sdk``/``_chat_history``) stay unit-testable without
+the Langflow host installed.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__version__ = "0.1.0"
+
+_EXPORTS = {
+    "AtomicMemoryChatMemoryComponent": "chat_memory",
+    "AtomicMemorySearchContextComponent": "search_context",
+    "AtomicMemoryStoreMessageComponent": "store_message",
+    "AtomicMemoryDeleteComponent": "delete",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    return getattr(import_module(f".{module}", __name__), name)

atomicmemory_langflow-0.1.17/atomicmemory_langflow/_chat_history.py

@@ -0,0 +1,60 @@
+"""Read-only LangChain chat history backed by AtomicMemory (lfx-free)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.messages import BaseMessage
+
+from ._messages import memory_to_lc_message
+
+logger = logging.getLogger(__name__)
+
+
+class AtomicMemoryChatMessageHistory(BaseChatMessageHistory):
+    """Surfaces a scope's memories as chat history. Writes are no-ops here —
+    use the Store Message component. LangChain provides the async surface
+    (aget_messages/aadd_messages) by delegating to these sync methods.
+    """
+
+    def __init__(self, *, bridge: Any, scope: dict, limit: int, fail_open: bool = False) -> None:
+        self._bridge = bridge
+        self._scope = scope
+        self._limit = limit
+        self._fail_open = fail_open
+        self._warned = False
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        try:
+            page = self._bridge.list_memories(scope=self._scope, limit=self._limit)
+        except Exception as exc:
+            # Fail closed by default: surface "memory unavailable" rather than
+            # silently pretending the user has no memory. Opt into soft failure
+            # (empty history) with fail_open=True.
+            if self._fail_open:
+                logger.warning(
+                    "AtomicMemory history read failed; returning empty history (fail_open): %s", exc
+                )
+                return []
+            raise RuntimeError(f"AtomicMemory history read failed: {exc}") from exc
+        memories = list(getattr(page, "memories", []))
+        memories.reverse()  # newest-first -> chronological
+        return [memory_to_lc_message(m) for m in memories]
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        if not self._warned:
+            logger.warning(
+                "AtomicMemory Chat Memory is read-only; writes here are ignored. "
+                "Use the 'AtomicMemory Store Message' component to persist memory."
+            )
+            self._warned = True
+
+    def add_message(self, message: BaseMessage) -> None:
+        self.add_messages([message])
+
+    def clear(self) -> None:
+        # Read-only; erasure is via the AtomicMemory Delete component.
+        return None

atomicmemory_langflow-0.1.17/atomicmemory_langflow/_component_base.py

@@ -0,0 +1,51 @@
+"""Mixin shared by the AtomicMemory components (lfx-free; only reads attrs).
+
+Inputs are named ``memory_user_id``/``memory_session_id`` (NOT ``user_id``) to
+avoid colliding with Langflow's base ``Component.user_id`` property, which holds
+the authenticated run user we fall back to.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._scope import build_scope
+from ._sdk import AtomicMemoryBridge
+
+
+class AtomicMemoryComponentMixin:
+    def _resolve_user_id(self) -> str:
+        explicit = (getattr(self, "memory_user_id", "") or "")
+        explicit = str(explicit).strip()
+        if explicit:
+            return explicit
+        ctx = getattr(self, "user_id", None)  # base Component.user_id (run context)
+        return str(ctx).strip() if ctx else ""
+
+    def _resolve_session_id(self) -> str | None:
+        explicit = (getattr(self, "memory_session_id", "") or "")
+        explicit = str(explicit).strip()
+        if explicit:
+            return explicit
+        graph = getattr(self, "graph", None)
+        sid = getattr(graph, "session_id", None) if graph is not None else None
+        return str(sid).strip() if sid else None
+
+    def _build_scope(self, *, include_session: bool = True) -> dict:
+        # namespace is intentionally not plumbed in Phase 1 (provider honors it
+        # only on search/package, not ingest/list/delete). See _inputs.scope_inputs.
+        # include_session=False yields a user-only scope for cross-session recall:
+        # Core hard-filters search/list by session, so retrieval meant to span
+        # sessions must omit the thread.
+        return build_scope(
+            self._resolve_user_id(),
+            session_id=self._resolve_session_id() if include_session else None,
+        )
+
+    def _build_bridge(self) -> AtomicMemoryBridge:
+        return AtomicMemoryBridge(
+            provider=getattr(self, "provider", "atomicmemory"),
+            api_url=getattr(self, "api_url", None),
+            api_key=getattr(self, "api_key", None),
+            provider_config=dict(getattr(self, "provider_config", {}) or {}),
+        )

atomicmemory_langflow-0.1.17/atomicmemory_langflow/_inputs.py

@@ -0,0 +1,72 @@
+"""Shared Langflow input builders (imports lfx). Each call returns fresh Input
+instances so components do not share mutable input objects."""
+
+from __future__ import annotations
+
+from lfx.inputs.inputs import (
+    DictInput,
+    DropdownInput,
+    MessageTextInput,
+    SecretStrInput,
+)
+
+from ._sdk import DEFAULT_API_URL
+
+
+def connection_inputs() -> list:
+    return [
+        DropdownInput(
+            name="provider",
+            display_name="Provider",
+            options=["atomicmemory"],
+            value="atomicmemory",
+            advanced=True,
+            info="Memory provider. Phase 1 supports atomicmemory.",
+        ),
+        MessageTextInput(
+            name="api_url",
+            display_name="API URL",
+            value=DEFAULT_API_URL,
+            advanced=True,
+            info="AtomicMemory Core base URL.",
+        ),
+        SecretStrInput(
+            name="api_key",
+            display_name="API Key",
+            value="",
+            required=False,
+            advanced=True,
+            info="API key (optional for local Core). Never put secrets in Provider Config.",
+        ),
+        DictInput(
+            name="provider_config",
+            display_name="Provider Config",
+            value={},
+            advanced=True,
+            info="Advanced SDK provider config. Must not contain secrets.",
+        ),
+    ]
+
+
+def scope_inputs(*, include_session: bool = True) -> list:
+    # NOTE: `namespace` is intentionally NOT exposed in Phase 1. The AtomicMemory
+    # Python provider only applies namespace on search/package — ingest/list/delete
+    # ignore it — so exposing it would silently break scoping (store/delete would
+    # not be namespace-isolated). Re-add only after end-to-end namespace support.
+    items = [
+        MessageTextInput(
+            name="memory_user_id",
+            display_name="User ID",
+            info="Memory scope. Defaults to the Langflow run user when left blank.",
+        ),
+    ]
+    if include_session:
+        items.append(
+            MessageTextInput(
+                name="memory_session_id",
+                display_name="Session ID",
+                advanced=True,
+                info="Session/thread scope. Defaults to the flow session when blank.",
+            )
+        )
+    return items

atomicmemory_langflow-0.1.17/atomicmemory_langflow/_messages.py

@@ -0,0 +1,68 @@
+"""Convert between Langflow/LangChain senders and SDK roles, and map stored
+memories to LangChain messages (lfx-free)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def coerce_text(value: Any) -> str:
+    """Extract plain text from an input that may be a Langflow/LangChain Message.
+
+    A MessageTextInput fed from another component's Message output can arrive as
+    a Message object, whose ``str()`` is its JSON serialization (``{"text": ...}``),
+    not the text. Stringifying that as a search query or ingest content corrupts
+    it. Prefer ``.text`` when present; otherwise fall back to ``str()``.
+    """
+    if value is None:
+        return ""
+    text = getattr(value, "text", None)
+    if isinstance(text, str):
+        return text
+    return str(value)
+
+
+# Langflow sender constants ("User"/"Machine"/"System"/"Tool") + LangChain
+# message types ("human"/"ai"/"system"/"tool") -> SDK role.
+_SENDER_TO_ROLE = {
+    "user": "user",
+    "human": "user",
+    "assistant": "assistant",
+    "ai": "assistant",
+    "machine": "assistant",
+    "system": "system",
+    "tool": "tool",
+}
+
+
+def sender_to_role(sender: Any) -> str:
+    """Total map to an SDK role (`user|assistant|system|tool`); unknown -> `user`."""
+    if sender is None:
+        return "user"
+    return _SENDER_TO_ROLE.get(str(sender).strip().lower(), "user")
+
+
+def memory_to_lc_message(memory: Any):
+    """Map a stored Memory to a LangChain message.
+
+    Role is NOT generally preserved: the AtomicMemory provider flattens
+    messages-mode ingest into a transcript and extracts semantic memories, so
+    most recalled memories have no ``role`` metadata and come back as a
+    ``[memory] …`` HumanMessage. The ``role == "assistant"`` check below is
+    best-effort for the rare case a provider surfaces role metadata.
+
+    SECURITY: retrieved memory is user-influenced; never return a SystemMessage
+    (which would grant system authority — a prompt-injection vector). Everything
+    that isn't an explicit assistant memory is a HumanMessage tagged ``[memory]``
+    so downstream prompts can see it is recalled context.
+    """
+    from langchain_core.messages import AIMessage, HumanMessage
+
+    content = getattr(memory, "content", "") or ""
+    role = None
+    meta = getattr(memory, "metadata", None)
+    if isinstance(meta, dict):
+        role = meta.get("role")
+    if role == "assistant":
+        return AIMessage(content=content)
+    return HumanMessage(content=f"[memory] {content}")

atomicmemory_langflow-0.1.17/atomicmemory_langflow/_scope.py

@@ -0,0 +1,40 @@
+"""Map Langflow inputs to an AtomicMemory SDK scope dict (lfx-free, SDK-free)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def build_scope(
+    user_id: Any,
+    *,
+    session_id: Any = None,
+    namespace: Any = None,
+    agent_id: Any = None,
+) -> dict[str, str]:
+    """Build an SDK scope dict. ``user`` is required (Core enforces it).
+
+    Langflow session -> ``thread``; namespace -> ``namespace``; agent -> ``agent``.
+    Optional fields are omitted when blank.
+    """
+    user = _clean(user_id)
+    if not user:
+        raise ValueError("AtomicMemory requires a non-empty user_id.")
+    scope: dict[str, str] = {"user": user}
+    thread = _clean(session_id)
+    if thread:
+        scope["thread"] = thread
+    ns = _clean(namespace)
+    if ns:
+        scope["namespace"] = ns
+    agent = _clean(agent_id)
+    if agent:
+        scope["agent"] = agent
+    return scope