langgraph-velesdb 4.2.0__py3-none-any.whl

langgraph_velesdb/__init__.py

@@ -0,0 +1,21 @@
+"""LangGraph memory tools for VelesDB — the ``why()`` knowledge-graph wedge.
+
+Drop VelesDB's local-first agent memory into any LangGraph agent:
+
+    >>> from langgraph.prebuilt import create_react_agent
+    >>> from langgraph_velesdb import make_memory_tools
+    >>>
+    >>> agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+
+``make_memory_tools`` returns the full VelesDB memory tool set: ``remember``,
+``recall``, ``recall_where``, ``recall_fused``, ``relate``, ``forget``,
+``feedback``, and the differentiator ``why`` — which answers with the
+best-matching memory *plus* the connected subgraph a vector recall is blind
+to — plus ``save_working_context``/``load_working_context`` for cross-run
+resumption. The store is on disk, so memory persists across agent runs.
+"""
+
+from langgraph_velesdb.tools import make_memory_tools
+
+__all__ = ["make_memory_tools"]
+__version__ = "4.2.0"

langgraph_velesdb/tools.py

@@ -0,0 +1,245 @@
+"""LangGraph / LangChain tools backed by VelesDB's high-level ``MemoryService``.
+
+A thin adapter: each tool is a small method on ``_MemoryToolkit``, bound to one
+``MemoryService`` (the core). No state or logic lives here beyond shaping
+inputs/outputs for the tool layer — the engine does the work. Methods live on
+a class (rather than as closures inside ``make_memory_tools``) so each tool's
+own cyclomatic complexity is what a linter measures, instead of all ten
+rolling up into one function.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.tools import BaseTool, StructuredTool  # nosemgrep: ai.python.detect-langchain.detect-langchain  # this package IS the LangChain connector
+
+try:
+    from velesdb import MemoryService
+except ImportError as exc:  # pragma: no cover - import guard
+    raise ImportError(
+        "velesdb is required for langgraph-velesdb. Install with: pip install velesdb"
+    ) from exc
+
+
+def make_memory_tools(
+    path: Optional[str] = None,
+    *,
+    service: Optional["MemoryService"] = None,
+) -> list[BaseTool]:
+    """Build the full VelesDB memory tool set for a LangGraph agent.
+
+    Returns ``remember`` / ``recall`` / ``recall_where`` / ``recall_fused`` /
+    ``relate`` / ``forget`` / ``feedback`` / ``why`` / ``save_working_context``
+    / ``load_working_context``.
+
+    Pass a ``path`` to open a local on-disk store (offline hash embedder), or a
+    pre-configured ``service`` (e.g. an Ollama-backed ``MemoryService``) to reuse
+    it. The store is on disk, so memory persists across agent runs.
+    """
+    toolkit = _MemoryToolkit(_resolve_service(path, service))
+    return [
+        StructuredTool.from_function(fn)
+        for fn in (
+            toolkit.remember,
+            toolkit.recall,
+            toolkit.recall_where,
+            toolkit.recall_fused,
+            toolkit.relate,
+            toolkit.forget,
+            toolkit.feedback,
+            toolkit.why,
+            toolkit.save_working_context,
+            toolkit.load_working_context,
+        )
+    ]
+
+
+class _MemoryToolkit:
+    """Binds one ``MemoryService`` to the ten tool methods ``make_memory_tools``
+    wraps into ``StructuredTool``\\ s. Not part of the public API."""
+
+    def __init__(self, mem: "MemoryService") -> None:
+        self._mem = mem
+
+    def remember(
+        self,
+        fact: str,
+        links: Optional[list[list[Any]]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> int:
+        """Store a fact in long-term memory and return its id.
+
+        ``links`` optionally wires typed outgoing edges to existing memory ids
+        at write time — each item is ``[target_id, relation]`` (equivalent to
+        calling ``relate`` right after). ``metadata`` attaches key/value pairs
+        ``recall_where``/``recall_fused`` can later filter on (every fact also
+        gets an automatic ``_veles_date`` stamp — today's date as a
+        ``YYYYMMDD`` int — unless you set that key yourself). ``ttl_seconds``
+        makes the fact expire, and stop being recalled, after that many
+        seconds. All three are optional; a bare ``remember(fact)`` behaves
+        exactly as before.
+        """
+        return self._mem.remember(
+            fact,
+            links=_as_tuples(links),
+            metadata=metadata,
+            ttl_seconds=ttl_seconds,
+        )
+
+    def recall(self, query: str, k: int = 5) -> list[dict[str, Any]]:
+        """Recall memories semantically similar to the query (vector search).
+
+        Each hit's ``metadata`` is always ``None`` on this path — use
+        ``recall_where`` (or ``recall_fused``) when you need each memory's
+        metadata, including the automatic ``_veles_date`` stamp.
+        """
+        return self._mem.recall(query, k)
+
+    def recall_where(
+        self,
+        query: str,
+        filters: Optional[list[list[Any]]] = None,
+        k: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Recall memories similar to the query, filtered by metadata, with
+        each hit's metadata attached.
+
+        ``filters`` is a list of ``[field, op, value]`` triples, ``op`` one of
+        ``"eq"``/``"ne"``/``"lt"``/``"le"``/``"gt"``/``"ge"`` — e.g.
+        ``[["_veles_date", "ge", 20260101]]`` keeps only facts stamped on or
+        after that date. Pass an empty list (the default) for no filtering.
+        Unlike plain ``recall``, every hit's ``metadata`` dict is returned,
+        including the automatic ``_veles_date`` stamp every fact gets at
+        write time.
+        """
+        return self._mem.recall_where(query, _as_tuples(filters) or [], k)
+
+    def recall_fused(
+        self,
+        query: str,
+        k: int = 5,
+        metadata_filter: Optional[dict[str, Any]] = None,
+        date_field: Optional[str] = None,
+    ) -> Any:
+        """Fused vector + graph recall: walks the graph from the top hit and
+        folds in any connected fact a plain ``recall`` would miss.
+
+        ``metadata_filter`` is an optional exact-match metadata filter. Pass
+        ``date_field="_veles_date"`` (the automatic stamp every fact gets) to
+        get back a dict with a chronological, date-prefixed timeline
+        (``dated_context``) instead of a plain list — useful for "what
+        happened, in order" questions. Omit ``date_field`` for the plain-list
+        form.
+        """
+        return self._mem.recall_fused(query, k, metadata_filter, date_field=date_field)
+
+    def relate(self, from_id: int, to_id: int, relation: str) -> int:
+        """Link two memories with a typed edge (``from_id`` -> ``to_id``)."""
+        return self._mem.relate(from_id, to_id, relation)
+
+    def forget(self, memory_id: int) -> bool:
+        """Delete a memory by id.
+
+        Returns ``True`` if a memory actually existed under ``memory_id`` and
+        was removed, ``False`` if there was nothing stored there (a stale id
+        or a typo) — a no-op, not an error.
+        """
+        return self._mem.forget(memory_id)
+
+    def feedback(self, memory_id: int, success: bool) -> Any:
+        """Reinforce or weaken a memory after using it, and return its
+        updated confidence in ``[0.0, 1.0]``.
+
+        Call this once you know whether a memory you recalled actually helped
+        answer the question (``success=True``) or was misleading/irrelevant
+        (``success=False``). This closes the self-improving loop: future
+        ``recall``/``recall_where``/``recall_fused`` calls rank
+        higher-confidence memories higher.
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "feedback"):
+            return _unsupported("feedback")
+        return self._mem.feedback(memory_id, success)
+
+    def why(self, question: str, max_hops: int = 2) -> dict[str, Any]:
+        """Explain something: the best-matching memory plus the connected
+        subgraph reachable through typed links — context a plain recall misses."""
+        return self._mem.why(question, max_hops)
+
+    def save_working_context(
+        self,
+        project: str,
+        session: str,
+        working: dict[str, Any],
+    ) -> Any:
+        """Persist the current working state under ``project`` + ``session``
+        so a later run can resume exactly where this one left off.
+
+        ``working`` is free-form but conventionally shaped like
+        ``{"goal": str, "active_constraints": [...], "verified_facts": [...],
+        "open_hypotheses": [...], "decisions": [...], "exact_evidence": [...],
+        "pending_actions": [...]}`` — call this near the end of a session, or
+        whenever the plan materially changes. Saving again under the same
+        ``project`` + ``session`` replaces the previous state (not a merge).
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "save_working_context"):
+            return _unsupported("save_working_context")
+        return self._mem.save_working_context(project, session, working)
+
+    def load_working_context(self, project: str, session: str) -> Any:
+        """Load the working context previously saved under ``project`` +
+        ``session`` by ``save_working_context``.
+
+        Call this at the very start of a new run, before doing anything else,
+        to resume a prior session instead of restarting from scratch. Returns
+        ``None`` when nothing was ever saved under that exact
+        ``project``/``session`` pair — not an error, just a fresh start.
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "load_working_context"):
+            return _unsupported("load_working_context")
+        return self._mem.load_working_context(project, session)
+
+
+def _resolve_service(
+    path: Optional[str], service: Optional["MemoryService"]
+) -> "MemoryService":
+    if service is not None:
+        return service
+    if path is None:
+        raise ValueError("make_memory_tools requires either `path` or `service`")
+    return MemoryService(path)
+
+
+def _as_tuples(pairs: Optional[list[list[Any]]]) -> Optional[list[tuple[Any, ...]]]:
+    """``[[a, b, ...], ...]`` -> ``[(a, b, ...), ...]``, or ``None`` if falsy.
+
+    Shared by ``remember``'s ``links`` and ``recall_where``'s ``filters``: both
+    accept plain JSON-friendly lists of lists from the LLM and forward tuples
+    to the binding, which expects ``List[Tuple[...]]``.
+    """
+    if not pairs:
+        return None
+    return [tuple(p) for p in pairs]
+
+
+def _unsupported(method: str) -> dict[str, str]:
+    """Actionable tool-error payload for a ``MemoryService`` method missing on
+    the installed ``velesdb`` (older than this package expects).
+
+    Returned as a normal tool result rather than raised, so a missing method
+    surfaces to the LLM as a tool error it can react to instead of an
+    uncaught ``AttributeError`` that would kill the whole LangGraph run.
+    """
+    return {
+        "error": f"{method} requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"
+    }

langgraph_velesdb-4.2.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: langgraph-velesdb
+Version: 4.2.0
+Summary: LangGraph memory tools for VelesDB: drop the why() knowledge-graph memory wedge into any LangGraph agent.
+Author-email: VelesDB Team <contact@wiscale.fr>
+License: MIT
+Project-URL: Homepage, https://velesdb.com
+Project-URL: Repository, https://github.com/cyberlife-coder/VelesDB
+Keywords: langgraph,langchain,velesdb,agent-memory,knowledge-graph,local-first,why,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Requires-Dist: velesdb>=3.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
+Requires-Dist: langgraph>=0.2.0; extra == "dev"
+Dynamic: license-file
+
+# langgraph-velesdb
+
+Drop VelesDB's local-first agent memory — the **`why()` knowledge-graph wedge** —
+into any [LangGraph](https://github.com/langchain-ai/langgraph) agent in three lines.
+
+Most agent memory is vector recall: it finds text that *looks like* the query.
+VelesDB **connects** memories with typed links, so `why()` answers with the
+best-matching memory **plus the connected subgraph** — context that shares no
+words with the question, which a plain vector recall is blind to. The store is on
+disk, so memory persists across agent runs.
+
+![recall() finds the booking but misses the reason; why() reaches it through typed links, across a session restart](https://raw.githubusercontent.com/cyberlife-coder/VelesDB/develop/examples/agent_memory/why_across_sessions.gif)
+
+## Install
+
+```bash
+pip install langgraph-velesdb        # pulls langchain-core + velesdb
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import create_react_agent
+from langgraph_velesdb import make_memory_tools
+
+# Offline by default (hash embedder); pass a configured MemoryService for Ollama.
+agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+```
+
+`make_memory_tools` returns ten tools the agent can call:
+
+| Tool                   | What it does |
+|------------------------|--------------|
+| `remember`             | store a fact (optionally with `links`, `metadata`, `ttl_seconds`), return its id |
+| `recall`               | semantic (vector) recall — no metadata |
+| `recall_where`         | filtered recall (metadata `[field, op, value]` triples) **with metadata attached**, e.g. the auto `_veles_date` stamp |
+| `recall_fused`         | fused vector + graph recall; pass `date_field="_veles_date"` for a dated timeline |
+| `relate`               | link two memories with a typed edge |
+| `forget`               | delete a memory by id (`True` if it existed, `False` if it was already gone) |
+| `feedback`             | reinforce or weaken a memory after using it, closing the self-improving recall loop |
+| `why`                  | best-matching memory **+ its connected subgraph** (the wedge) |
+| `save_working_context` | persist the current goal/constraints/decisions/pending actions under a project + session |
+| `load_working_context` | resume a prior run's working context — call at the start of a session |
+
+For a pre-configured backend (e.g. Ollama embeddings), build the service yourself
+and pass it through:
+
+```python
+from velesdb import MemoryService
+tools = make_memory_tools(service=MemoryService("./agent_memory"))
+```
+
+### Cross-run resumption
+
+`save_working_context` / `load_working_context` let an agent pick up a task
+across separate runs instead of restarting from scratch:
+
+`make_memory_tools` returns a *list* of tools, so index them by name first
+(the same pattern LangGraph's `ToolNode`/`create_react_agent` use internally):
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["save_working_context"].invoke({
+    "project": "veles",
+    "session": "issue-1546",
+    "working": {
+        "goal": "ship the langgraph tool set",
+        "pending_actions": ["open the PR"],
+    },
+})
+
+# ... next run, same project + session:
+tools["load_working_context"].invoke({"project": "veles", "session": "issue-1546"})
+```
+
+### Dated recall
+
+Every `remember`-ed fact is auto-stamped with `_veles_date` (today, as a
+`YYYYMMDD` int) unless you set that metadata key yourself. Point
+`recall_fused` at it to get a chronological timeline instead of a ranked list:
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["recall_fused"].invoke({"query": "what changed this week", "date_field": "_veles_date"})
+# -> {"memories": [...], "dated_context": "...", "now": "..."}
+```
+
+## Compatibility
+
+This package requires `velesdb>=3.12.0`, the highest version published to
+PyPI at the time of writing. `feedback`, `save_working_context`,
+`load_working_context`, and the automatic `_veles_date` metadata stamp landed
+in `velesdb`/`velesdb-memory` *after* the 3.12.0 release cut and are not yet
+in a published wheel. On a plain 3.12.0 install those three tools detect the
+missing binding method at call time and return an error payload instead of
+raising, e.g.:
+
+```json
+{"error": "feedback requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"}
+```
+
+so a single unsupported call surfaces to the agent as a normal tool result it
+can react to, instead of an uncaught `AttributeError` killing the whole graph
+run. `recall_where`/`recall_fused` still work, but their `metadata` stays
+empty for auto-dating until you upgrade. `forget` works on 3.12.0 too, but
+returns `None` instead of a `True`/`False` existed-or-not signal. The floor
+will be bumped again once a `velesdb` release past 3.12.0 ships.
+
+`list_working_contexts` (browse saved sessions for a project) is not exposed
+here: it exists on the WASM and MCP surfaces but not yet on the `velesdb`
+Python binding (`MemoryService`), and this package only ever calls the
+binding — no memory logic is reimplemented in this MIT-licensed integration.
+It will be added once the Python binding grows the method.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Wraps [`velesdb`](https://pypi.org/project/velesdb/),
+which is under the VelesDB Core License 1.0.

langgraph_velesdb-4.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+langgraph_velesdb/__init__.py,sha256=7kTqsXM0iReyVMAZ1aK2iFdffEaPxqzyJrq3_p_0jYU,907
+langgraph_velesdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_velesdb/tools.py,sha256=6R9WBKE-L0b41gE2aC-a0aZFT5pwuZktiKSIsNAsLck,10314
+langgraph_velesdb-4.2.0.dist-info/licenses/LICENSE,sha256=hu80gXApIu5PnZ5cS0G4aLlhs-SqMhOT4OsqHr8Z5Is,1298
+langgraph_velesdb-4.2.0.dist-info/METADATA,sha256=oSGR3U_IQq2tOjuKi7gXf83GSeFE41tKHpYjD-36ReA,6437
+langgraph_velesdb-4.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+langgraph_velesdb-4.2.0.dist-info/top_level.txt,sha256=Vhmq6JWJ2ybjnubG6qMA3sxvF_v4FvpjNPL1dEIQkdA,18
+langgraph_velesdb-4.2.0.dist-info/RECORD,,

langgraph_velesdb-4.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

langgraph_velesdb-4.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2024-2026 Wiscale France
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This MIT license applies to the LangChain integration code only.
+VelesDB Core itself is licensed under the Elastic License 2.0 (ELv2).
+See https://github.com/cyberlife-coder/VelesDB for VelesDB Core licensing.

langgraph_velesdb-4.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+langgraph_velesdb