langchain-ladybug 0.3.0__tar.gz

langchain_ladybug-0.3.0/.gitignore

@@ -0,0 +1,35 @@
+# Virtual environments
+venv*/
+.venv*/
+env/
+.env/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.benchmarks/
+.mypy_cache/
+.ruff_cache/
+
+# Coverage
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Cursor IDE
+.cursor/
+memory-bank/
+

langchain_ladybug-0.3.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-05-07
+
+### Added
+
+- Initial release of `langchain-ladybug`, based on [@adsharma](https://github.com/adsharma)'s port of the Kuzu LangChain integration to Ladybug ([langchain-community PR #438](https://github.com/langchain-ai/langchain-community/pull/438)).
+- `LadybugGraph` — LangChain graph wrapper for the [Ladybug](https://github.com/ladybug-ai/ladybug) graph database with support for:
+  - Schema introspection via `refresh_schema` and `get_schema`.
+  - Cypher query execution via `query`.
+  - Document ingestion via `add_graph_documents`, including optional source chunk tracking with `MENTIONS` relationships.
+- `LadybugQAChain` — question-answering chain that translates natural language to Ladybug-dialect Cypher and returns grounded answers from the graph.
+- `LADYBUG_GENERATION_PROMPT` — prompt template for Ladybug-dialect Cypher generation, enforcing correct relationship pattern syntax (`()-[]->()`) and clean output.
+- `CYPHER_QA_PROMPT` — prompt template for producing human-readable answers from Cypher query results.
+- Support for separate `cypher_llm` and `qa_llm` models in `LadybugQAChain.from_llm`.

langchain_ladybug-0.3.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: all lint format test help
+
+all: help
+
+help:
+	@echo "Available targets:"
+	@echo "  lint     - Run ruff linter"
+	@echo "  format   - Run ruff formatter"
+	@echo "  test     - Run unit tests (no network)"
+	@echo "  typing   - Run mypy type checking"
+
+lint:
+	uv run --group lint ruff check .
+
+format:
+	uv run --group lint ruff format .
+	uv run --group lint ruff check --fix .
+
+test:
+	uv run --group test pytest tests/unit_tests -v
+
+typing:
+	uv run --group typing mypy langchain_ladybug

langchain_ladybug-0.3.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: langchain-ladybug
+Version: 0.3.0
+Summary: LangChain integration for the Ladybug graph database.
+Project-URL: Homepage, https://github.com/stevereiner/langchain-ladybug
+Project-URL: Source, https://github.com/stevereiner/langchain-ladybug
+License: MIT
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: ladybug>=0.16.1
+Requires-Dist: langchain-classic<2.0.0,>=1.0.0
+Requires-Dist: langchain-community<1.0.0,>=0.4.1
+Requires-Dist: langchain-core<2.0.0,>=1.0.1
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: langchain-core; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff<1.0.0,>=0.13.1; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: langchain-tests<2.0.0,>=1.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio<1.0.0,>=0.20.3; extra == 'test'
+Requires-Dist: pytest-cov<7.0.0,>=6.2.1; extra == 'test'
+Requires-Dist: pytest-mock<4.0.0,>=3.10.0; extra == 'test'
+Requires-Dist: pytest<9.0.0,>=8.4.1; extra == 'test'
+Provides-Extra: typing
+Requires-Dist: langchain-core; extra == 'typing'
+Requires-Dist: mypy<2.0.0,>=1.17.1; extra == 'typing'
+Description-Content-Type: text/markdown
+
+# langchain-ladybug
+
+LangChain integration for the [Ladybug](https://github.com/ladybug-ai/ladybug) graph database.
+
+This package provides:
+
+- **`LadybugGraph`** — a LangChain graph wrapper for Ladybug that supports schema introspection, Cypher queries, and document ingestion via `add_graph_documents`.
+- **`LadybugQAChain`** — a question-answering chain that generates Ladybug-dialect Cypher queries from natural language and returns answers grounded in the graph.
+- Prompt templates (`LADYBUG_GENERATION_PROMPT`, `CYPHER_QA_PROMPT`) tuned for the Ladybug Cypher dialect.
+
+## Installation
+
+```bash
+uv pip install langchain-ladybug
+```
+
+The `ladybug` Python package must also be installed:
+
+```bash
+uv pip install ladybug
+```
+
+## Quick Start
+
+```python
+import ladybug as lb
+from langchain_ladybug import LadybugGraph, LadybugQAChain
+from langchain_openai import ChatOpenAI
+
+db = lb.Database("/path/to/my.db")
+
+graph = LadybugGraph(db)
+
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+chain = LadybugQAChain.from_llm(
+    llm=llm,
+    graph=graph,
+)
+
+answer = chain.invoke({"query": "Who acted in The Godfather?"})
+print(answer["result"])
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run unit tests
+make test
+
+# Lint
+make lint
+
+# Format
+make format
+```
+
+## Acknowledgements
+
+Started from the Kuzu → Ladybug LangChain support port by [@adsharma](https://github.com/adsharma) ([PR #438](https://github.com/langchain-ai/langchain-community/pull/438)) — a proposed LadybugDB (formerly Kuzu) integration into the upstream langchain-community repo
+
+
+## Project Structure
+
+```
+langchain_ladybug/
+├── graphs/
+│   ├── graph_document.py   # Node, Relationship, GraphDocument data classes
+│   └── ladybug_graph.py    # LadybugGraph wrapper
+└── chains/
+    ├── prompts.py           # Ladybug-dialect Cypher prompt templates
+    └── ladybug_qa.py        # LadybugQAChain
+tests/
+├── unit_tests/             # No network calls
+└── integration_tests/      # Requires ladybug
+```

langchain_ladybug-0.3.0/README.md

@@ -0,0 +1,79 @@
+# langchain-ladybug
+
+LangChain integration for the [Ladybug](https://github.com/ladybug-ai/ladybug) graph database.
+
+This package provides:
+
+- **`LadybugGraph`** — a LangChain graph wrapper for Ladybug that supports schema introspection, Cypher queries, and document ingestion via `add_graph_documents`.
+- **`LadybugQAChain`** — a question-answering chain that generates Ladybug-dialect Cypher queries from natural language and returns answers grounded in the graph.
+- Prompt templates (`LADYBUG_GENERATION_PROMPT`, `CYPHER_QA_PROMPT`) tuned for the Ladybug Cypher dialect.
+
+## Installation
+
+```bash
+uv pip install langchain-ladybug
+```
+
+The `ladybug` Python package must also be installed:
+
+```bash
+uv pip install ladybug
+```
+
+## Quick Start
+
+```python
+import ladybug as lb
+from langchain_ladybug import LadybugGraph, LadybugQAChain
+from langchain_openai import ChatOpenAI
+
+db = lb.Database("/path/to/my.db")
+
+graph = LadybugGraph(db)
+
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+chain = LadybugQAChain.from_llm(
+    llm=llm,
+    graph=graph,
+)
+
+answer = chain.invoke({"query": "Who acted in The Godfather?"})
+print(answer["result"])
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run unit tests
+make test
+
+# Lint
+make lint
+
+# Format
+make format
+```
+
+## Acknowledgements
+
+Started from the Kuzu → Ladybug LangChain support port by [@adsharma](https://github.com/adsharma) ([PR #438](https://github.com/langchain-ai/langchain-community/pull/438)) — a proposed LadybugDB (formerly Kuzu) integration into the upstream langchain-community repo
+
+
+## Project Structure
+
+```
+langchain_ladybug/
+├── graphs/
+│   ├── graph_document.py   # Node, Relationship, GraphDocument data classes
+│   └── ladybug_graph.py    # LadybugGraph wrapper
+└── chains/
+    ├── prompts.py           # Ladybug-dialect Cypher prompt templates
+    └── ladybug_qa.py        # LadybugQAChain
+tests/
+├── unit_tests/             # No network calls
+└── integration_tests/      # Requires ladybug
+```

langchain_ladybug-0.3.0/langchain_ladybug/__init__.py

@@ -0,0 +1,9 @@
+"""langchain-ladybug: LangChain integration for the Ladybug graph database."""
+
+from langchain_ladybug.chains.ladybug_qa import LadybugQAChain
+from langchain_ladybug.graphs.ladybug_graph import LadybugGraph
+
+__all__ = [
+    "LadybugGraph",
+    "LadybugQAChain",
+]

langchain_ladybug-0.3.0/langchain_ladybug/chains/__init__.py

@@ -0,0 +1,13 @@
+"""Chain and prompt classes for the Ladybug integration."""
+
+from langchain_ladybug.chains.ladybug_qa import LadybugQAChain
+from langchain_ladybug.chains.prompts import (
+    CYPHER_QA_PROMPT,
+    LADYBUG_GENERATION_PROMPT,
+)
+
+__all__ = [
+    "LadybugQAChain",
+    "CYPHER_QA_PROMPT",
+    "LADYBUG_GENERATION_PROMPT",
+]

langchain_ladybug-0.3.0/langchain_ladybug/chains/ladybug_qa.py

@@ -0,0 +1,217 @@
+"""Question answering over a graph."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from langchain_classic.chains.base import Chain
+from langchain_classic.chains.llm import LLMChain
+from langchain_core.callbacks import CallbackManagerForChainRun
+from langchain_core.language_models import BaseLanguageModel
+from langchain_core.prompts import BasePromptTemplate
+from pydantic import Field
+
+from langchain_ladybug.chains.prompts import CYPHER_QA_PROMPT, LADYBUG_GENERATION_PROMPT
+from langchain_ladybug.graphs.ladybug_graph import LadybugGraph
+
+
+def remove_prefix(text: str, prefix: str) -> str:
+    """Remove a prefix from a text string.
+
+    Args:
+        text: Text to remove the prefix from.
+        prefix: Prefix to remove from the text.
+
+    Returns:
+        Text with the prefix removed, or the original text if it does not start
+        with the prefix.
+    """
+    if text.startswith(prefix):
+        return text[len(prefix):]
+    return text
+
+
+def extract_cypher(text: str) -> str:
+    """Extract Cypher code from a text string.
+
+    Looks for Cypher code enclosed in triple backticks.
+
+    Args:
+        text: Text to extract Cypher code from.
+
+    Returns:
+        Cypher code extracted from the first triple-backtick block, or the
+        original text if no such block is found.
+    """
+    pattern = r"```(.*?)```"
+    matches = re.findall(pattern, text, re.DOTALL)
+    return matches[0] if matches else text
+
+
+class LadybugQAChain(Chain):
+    """Question-answering against a graph by generating Cypher statements for Ladybug.
+
+    *Security note*: Make sure that the database connection uses credentials
+        that are narrowly-scoped to only include necessary permissions.
+        Failure to do so may result in data corruption or loss, since the calling
+        code may attempt commands that would result in deletion, mutation
+        of data if appropriately prompted or reading sensitive data if such
+        data is present in the database.
+        The best way to guard against such negative outcomes is to (as appropriate)
+        limit the permissions granted to the credentials used with this tool.
+
+        See https://python.langchain.com/docs/security for more information.
+    """
+
+    graph: LadybugGraph = Field(exclude=True)
+    cypher_generation_chain: LLMChain
+    qa_chain: LLMChain
+    input_key: str = "query"
+    output_key: str = "result"
+
+    allow_dangerous_requests: bool = False
+    """Forced user opt-in to acknowledge that the chain can make dangerous requests.
+
+    *Security note*: Make sure that the database connection uses credentials
+        that are narrowly-scoped to only include necessary permissions.
+        Failure to do so may result in data corruption or loss, since the calling
+        code may attempt commands that would result in deletion, mutation
+        of data if appropriately prompted or reading sensitive data if such
+        data is present in the database.
+        The best way to guard against such negative outcomes is to (as appropriate)
+        limit the permissions granted to the credentials used with this tool.
+
+        See https://python.langchain.com/docs/security for more information.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the chain.
+
+        Raises:
+            ValueError: If `allow_dangerous_requests` is not `True`.
+        """
+        if not kwargs.get("allow_dangerous_requests"):
+            raise ValueError(
+                "In order to use this chain, you must acknowledge that it can make "
+                "dangerous requests by setting `allow_dangerous_requests` to `True`. "
+                "You must narrowly scope the permissions of the database connection "
+                "to only include necessary permissions. Failure to do so may result "
+                "in data corruption or loss or reading sensitive data if such data is "
+                "present in the database. "
+                "Only use this chain if you understand the risks and have taken the "
+                "necessary precautions. "
+                "See https://python.langchain.com/docs/security for more information."
+            )
+        super().__init__(**kwargs)
+
+    @property
+    def input_keys(self) -> List[str]:
+        """Return the input keys."""
+        return [self.input_key]
+
+    @property
+    def output_keys(self) -> List[str]:
+        """Return the output keys."""
+        return [self.output_key]
+
+    @classmethod
+    def from_llm(
+        cls,
+        llm: Optional[BaseLanguageModel] = None,
+        *,
+        qa_prompt: BasePromptTemplate = CYPHER_QA_PROMPT,
+        cypher_prompt: BasePromptTemplate = LADYBUG_GENERATION_PROMPT,
+        cypher_llm: Optional[BaseLanguageModel] = None,
+        qa_llm: Optional[BaseLanguageModel] = None,
+        **kwargs: Any,
+    ) -> LadybugQAChain:
+        """Initialize from an LLM.
+
+        Args:
+            llm: A language model to use for both Cypher generation and QA when
+                separate models are not provided.
+            qa_prompt: Prompt template for the QA step.
+            cypher_prompt: Prompt template for the Cypher generation step.
+            cypher_llm: A language model dedicated to Cypher generation. If
+                provided, `llm` is used only for QA unless `qa_llm` is also given.
+            qa_llm: A language model dedicated to the QA step. If provided,
+                `llm` is used only for Cypher generation unless `cypher_llm` is
+                also given.
+            **kwargs: Additional keyword arguments passed to the chain constructor.
+
+        Returns:
+            A configured `LadybugQAChain` instance.
+
+        Raises:
+            ValueError: If neither `llm` nor `cypher_llm` is provided, neither
+                `llm` nor `qa_llm` is provided, or all three of `llm`,
+                `cypher_llm`, and `qa_llm` are provided simultaneously.
+        """
+        if not cypher_llm and not llm:
+            raise ValueError("Either `llm` or `cypher_llm` parameters must be provided")
+        if not qa_llm and not llm:
+            raise ValueError(
+                "Either `llm` or `qa_llm` parameters must be provided along with"
+                " `cypher_llm`"
+            )
+        if cypher_llm and qa_llm and llm:
+            raise ValueError(
+                "You can specify up to two of 'cypher_llm', 'qa_llm'"
+                ", and 'llm', but not all three simultaneously."
+            )
+
+        qa_chain = LLMChain(
+            llm=qa_llm or llm,  # type: ignore[arg-type]
+            prompt=qa_prompt,
+        )
+        cypher_generation_chain = LLMChain(
+            llm=cypher_llm or llm,  # type: ignore[arg-type]
+            prompt=cypher_prompt,
+        )
+
+        return cls(
+            qa_chain=qa_chain,
+            cypher_generation_chain=cypher_generation_chain,
+            **kwargs,
+        )
+
+    def _call(
+        self,
+        inputs: Dict[str, Any],
+        run_manager: Optional[CallbackManagerForChainRun] = None,
+    ) -> Dict[str, str]:
+        """Generate a Cypher statement, query the graph, and answer the question.
+
+        Args:
+            inputs: Dictionary containing the input question under `input_key`.
+            run_manager: Optional callback manager for tracing and logging.
+
+        Returns:
+            Dictionary with the answer under `output_key`.
+        """
+        _run_manager = run_manager or CallbackManagerForChainRun.get_noop_manager()
+        callbacks = _run_manager.get_child()
+        question = inputs[self.input_key]
+
+        generated_cypher = self.cypher_generation_chain.run(
+            {"question": question, "schema": self.graph.get_schema}, callbacks=callbacks
+        )
+        generated_cypher = remove_prefix(extract_cypher(generated_cypher), "cypher")
+
+        _run_manager.on_text("Generated Cypher:", end="\n", verbose=self.verbose)
+        _run_manager.on_text(
+            generated_cypher, color="green", end="\n", verbose=self.verbose
+        )
+        context = self.graph.query(generated_cypher)
+
+        _run_manager.on_text("Full Context:", end="\n", verbose=self.verbose)
+        _run_manager.on_text(
+            str(context), color="green", end="\n", verbose=self.verbose
+        )
+
+        result = self.qa_chain(
+            {"question": question, "context": context},
+            callbacks=callbacks,
+        )
+        return {self.output_key: result[self.qa_chain.output_key]}

langchain_ladybug-0.3.0/langchain_ladybug/chains/prompts.py

@@ -0,0 +1,53 @@
+# flake8: noqa
+from langchain_core.prompts.prompt import PromptTemplate
+
+CYPHER_GENERATION_TEMPLATE = """Task:Generate Cypher statement to query a graph database.
+Instructions:
+Use only the provided relationship types and properties in the schema.
+Do not use any other relationship types or properties that are not provided.
+Schema:
+{schema}
+Note: Do not include any explanations or apologies in your responses.
+Do not respond to any questions that might ask anything else than for you to construct a Cypher statement.
+Do not include any text except the generated Cypher statement.
+
+The question is:
+{question}"""
+
+LADYBUG_EXTRA_INSTRUCTIONS = """
+Instructions:
+Generate the Ladybug dialect of Cypher with the following rules in mind:
+1. Do not omit the relationship pattern. Always use `()-[]->()` instead of `()->()`.
+2. Do not include triple backticks ``` in your response. Return only Cypher.
+3. Do not return any notes or comments in your response.
+\n"""
+
+LADYBUG_GENERATION_TEMPLATE = CYPHER_GENERATION_TEMPLATE.replace(
+    "Generate Cypher", "Generate Ladybug Cypher"
+).replace("Instructions:", LADYBUG_EXTRA_INSTRUCTIONS)
+
+LADYBUG_GENERATION_PROMPT = PromptTemplate(
+    input_variables=["schema", "question"], template=LADYBUG_GENERATION_TEMPLATE
+)
+
+CYPHER_QA_TEMPLATE = """You are an assistant that helps to form nice and human understandable answers.
+The information part contains the provided information that you must use to construct an answer.
+The provided information is authoritative, you must never doubt it or try to use your internal knowledge to correct it.
+Make the answer sound as a response to the question. Do not mention that you based the result on the given information.
+Here is an example:
+
+Question: Which managers own Neo4j stocks?
+Context:[manager:CTL LLC, manager:JANE STREET GROUP LLC]
+Helpful Answer: CTL LLC, JANE STREET GROUP LLC owns Neo4j stocks.
+
+Follow this example when generating answers.
+If the provided information is empty, say that you don't know the answer.
+Information:
+{context}
+
+Question: {question}
+Helpful Answer:"""
+
+CYPHER_QA_PROMPT = PromptTemplate(
+    input_variables=["context", "question"], template=CYPHER_QA_TEMPLATE
+)

langchain_ladybug-0.3.0/langchain_ladybug/graphs/__init__.py

@@ -0,0 +1,11 @@
+"""Graph classes for the Ladybug integration."""
+
+from langchain_community.graphs.graph_document import GraphDocument, Node, Relationship
+from langchain_ladybug.graphs.ladybug_graph import LadybugGraph
+
+__all__ = [
+    "LadybugGraph",
+    "GraphDocument",
+    "Node",
+    "Relationship",
+]

langchain_ladybug-0.3.0/langchain_ladybug/graphs/ladybug_graph.py

@@ -0,0 +1,258 @@
+from hashlib import md5
+from typing import Any, Dict, List, Tuple
+
+from langchain_community.graphs.graph_document import GraphDocument, Relationship
+
+
+class LadybugGraph:
+    """Ladybug wrapper for graph operations.
+
+    *Security note*: Make sure that the database connection uses credentials
+        that are narrowly-scoped to only include necessary permissions.
+        Failure to do so may result in data corruption or loss, since the calling
+        code may attempt commands that would result in deletion, mutation
+        of data if appropriately prompted or reading sensitive data if such
+        data is present in the database.
+        The best way to guard against such negative outcomes is to (as appropriate)
+        limit the permissions granted to the credentials used with this tool.
+
+        See https://python.langchain.com/docs/security for more information.
+    """
+
+    def __init__(
+        self, db: Any, database: str = "ladybug", allow_dangerous_requests: bool = False
+    ) -> None:
+        """Initializes the Ladybug graph database connection.
+
+        Args:
+            db: The Ladybug database instance.
+            database: The name of the database.
+            allow_dangerous_requests: Must be set to `True` to acknowledge that
+                this class can execute arbitrary queries on the database.
+
+        Raises:
+            ValueError: If `allow_dangerous_requests` is not `True`, or if the
+                `ladybug` package is not installed.
+        """
+        if allow_dangerous_requests is not True:
+            raise ValueError(
+                "The LadybugGraph class is a powerful tool that can be used to execute "
+                "arbitrary queries on the database. To enable this functionality, "
+                "set the `allow_dangerous_requests` parameter to `True` when "
+                "constructing the LadybugGraph object."
+            )
+
+        try:
+            import ladybug as lb
+        except ImportError as e:
+            raise ImportError(
+                "Could not import Ladybug python package. "
+                "Please install Ladybug with `pip install ladybug`."
+            ) from e
+
+        self.db = db
+        self.conn = lb.Connection(self.db)
+        self.database = database
+        self.refresh_schema()
+
+    @property
+    def get_schema(self) -> str:
+        """Returns the schema of the Ladybug database."""
+        return self.schema
+
+    def query(self, query: str, params: dict = {}) -> List[Dict[str, Any]]:
+        """Query the Ladybug database.
+
+        Args:
+            query: The Cypher query string to execute.
+            params: Optional parameter bindings for the query.
+
+        Returns:
+            A list of result rows, each represented as a dict of column name to value.
+        """
+        result = self.conn.execute(query, params)
+        column_names = result.get_column_names()
+        return_list = []
+        while result.has_next():
+            row = result.get_next()
+            return_list.append(dict(zip(column_names, row)))
+        return return_list
+
+    def refresh_schema(self) -> None:
+        """Refreshes the Ladybug graph schema information."""
+        node_properties = []
+        node_table_names = self.conn._get_node_table_names()
+        for table_name in node_table_names:
+            current_table_schema = {"properties": [], "label": table_name}
+            properties = self.conn._get_node_property_names(table_name)
+            for property_name in properties:
+                property_type = properties[property_name]["type"]
+                list_type_flag = ""
+                if properties[property_name]["dimension"] > 0:
+                    if "shape" in properties[property_name]:
+                        for s in properties[property_name]["shape"]:
+                            list_type_flag += f"[{s}]"
+                    else:
+                        for i in range(properties[property_name]["dimension"]):
+                            list_type_flag += "[]"
+                property_type += list_type_flag
+                current_table_schema["properties"].append(
+                    (
+                        property_name,
+                        property_type,
+                    )
+                )
+            node_properties.append(current_table_schema)
+
+        relationships = []
+        rel_tables = self.conn._get_rel_table_names()
+        for table in rel_tables:
+            relationships.append(
+                f"(:{table['src']})-[:{table['name']}]->(:{table['dst']})"
+            )
+
+        rel_properties = []
+        for table in rel_tables:
+            table_name = table["name"]
+            current_table_schema = {"properties": [], "label": table_name}
+            query_result = self.conn.execute(
+                f"CALL table_info('{table_name}') RETURN *;"
+            )
+            while query_result.has_next():
+                row = query_result.get_next()
+                prop_name = row[1]
+                prop_type = row[2]
+                current_table_schema["properties"].append((prop_name, prop_type))
+            rel_properties.append(current_table_schema)
+
+        self.schema = (
+            f"Node properties: {node_properties}\n"
+            f"Relationships properties: {rel_properties}\n"
+            f"Relationships: {relationships}\n"
+        )
+
+    def _create_chunk_node_table(self) -> None:
+        self.conn.execute(
+            """
+            CREATE NODE TABLE IF NOT EXISTS Chunk (
+                id STRING,
+                text STRING,
+                type STRING,
+                PRIMARY KEY(id)
+            );
+            """
+        )
+
+    def _create_entity_node_table(self, node_label: str) -> None:
+        self.conn.execute(
+            f"""
+            CREATE NODE TABLE IF NOT EXISTS {node_label} (
+                id STRING,
+                type STRING,
+                PRIMARY KEY(id)
+            );
+            """
+        )
+
+    def _create_entity_relationship_table(self, rel: Relationship) -> None:
+        self.conn.execute(
+            f"""
+            CREATE REL TABLE IF NOT EXISTS {rel.type} (
+                FROM {rel.source.type} TO {rel.target.type}
+            );
+            """
+        )
+
+    def add_graph_documents(
+        self,
+        graph_documents: List[GraphDocument],
+        allowed_relationships: List[Tuple[str, str, str]],
+        include_source: bool = False,
+    ) -> None:
+        """Add a list of `GraphDocument` objects to the Ladybug graph.
+
+        Args:
+            graph_documents: A list of `GraphDocument` objects that contain the
+                nodes and relationships to be added to the graph.
+            allowed_relationships: A list of allowed relationships in the graph.
+                Each tuple contains ``(source_node_type, relationship_type,
+                target_node_type)``. Required for Ladybug because the relationship
+                table names must pre-exist and are derived from these tuples.
+            include_source: If `True`, stores the source document and links it to
+                nodes in the graph via the `MENTIONS` relationship. Merges source
+                documents by the `id` field in source metadata when available;
+                otherwise uses the MD5 hash of `page_content`.
+        """
+        node_labels = list(
+            {node.type for document in graph_documents for node in document.nodes}
+        )
+
+        for document in graph_documents:
+            if include_source:
+                self._create_chunk_node_table()
+                if not document.source.metadata.get("id"):
+                    document.source.metadata["id"] = md5(
+                        document.source.page_content.encode("utf-8")
+                    ).hexdigest()
+
+                self.conn.execute(
+                    f"""
+                    MERGE (c:Chunk {{id: $id}}) 
+                        SET c.text = $text,
+                            c.type = "text_chunk"
+                    """,  # noqa: F541
+                    parameters={
+                        "id": document.source.metadata["id"],
+                        "text": document.source.page_content,
+                    },
+                )
+
+            for node_label in node_labels:
+                self._create_entity_node_table(node_label)
+
+            for node in document.nodes:
+                self.conn.execute(
+                    f"""
+                    MERGE (e:{node.type} {{id: $id}})
+                        SET e.type = "entity"
+                    """,
+                    parameters={"id": node.id},
+                )
+                if include_source:
+                    self._create_chunk_node_table()
+                    ddl = "CREATE REL TABLE GROUP IF NOT EXISTS MENTIONS ("
+                    table_names = list(
+                        {f"FROM Chunk TO {label}" for label in node_labels}
+                    )
+                    ddl += ", ".join(table_names)
+                    ddl += ", label STRING, triplet_source_id STRING)"
+                    if ddl:
+                        self.conn.execute(ddl)
+
+                    if node.type in node_labels:
+                        self.conn.execute(
+                            f"""
+                            MATCH (c:Chunk {{id: $id}}),
+                                  (e:{node.type} {{id: $node_id}})
+                            MERGE (c)-[m:MENTIONS]->(e)
+                          SET m.triplet_source_id = $id
+                            """,
+                            parameters={
+                                "id": document.source.metadata["id"],
+                                "node_id": node.id,
+                            },
+                        )
+
+            for rel in document.relationships:
+                self._create_entity_relationship_table(rel)
+                self.conn.execute(
+                    f"""
+                    MATCH (e1:{rel.source.type} {{id: $source_id}}),
+                            (e2:{rel.target.type} {{id: $target_id}})
+                    MERGE (e1)-[:{rel.type}]->(e2)
+                    """,
+                    parameters={
+                        "source_id": rel.source.id,
+                        "target_id": rel.target.id,
+                    },
+                )

langchain_ladybug-0.3.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-ladybug"
+description = "LangChain integration for the Ladybug graph database."
+license = { text = "MIT" }
+readme = "README.md"
+authors = []
+
+version = "0.3.0"
+requires-python = ">=3.10.0,<4.0.0"
+dependencies = [
+    "langchain-core>=1.0.1,<2.0.0",
+    "langchain-classic>=1.0.0,<2.0.0",
+    "langchain-community>=0.4.1,<1.0.0",
+    "pydantic>=2.0.0,<3.0.0",
+    "ladybug>=0.16.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/stevereiner/langchain-ladybug"
+Source = "https://github.com/stevereiner/langchain-ladybug"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.4.1,<9.0.0",
+    "pytest-cov>=6.2.1,<7.0.0",
+    "pytest-asyncio>=0.20.3,<1.0.0",
+    "pytest-mock>=3.10.0,<4.0.0",
+    "langchain-tests>=1.0.0,<2.0.0",
+]
+lint = [
+    "ruff>=0.13.1,<1.0.0",
+]
+typing = [
+    "mypy>=1.17.1,<2.0.0",
+    "langchain-core",
+]
+dev = [
+    "langchain-core",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "venv*/",
+    ".venv*/",
+    "dist/",
+    ".benchmarks/",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".ruff_cache/",
+]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "T201", "UP"]
+
+[tool.mypy]
+ignore_missing_imports = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config"
+asyncio_mode = "auto"

langchain_ladybug-0.3.0/tests/integration_tests/graphs/test_ladybug.py

@@ -0,0 +1,74 @@
+"""Integration tests for LadybugGraph.
+
+These tests require the `ladybug` package and a live Ladybug database.
+Run with: uv run --group test pytest tests/integration_tests/
+"""
+
+import os
+import shutil
+import tempfile
+import unittest
+
+from langchain_ladybug.graphs import LadybugGraph
+
+EXPECTED_SCHEMA = """Node properties: [{'properties': [('name', 'STRING')], 'label': 'Movie'}, {'properties': [('name', 'STRING'), ('birthDate', 'STRING')], 'label': 'Person'}]
+Relationships properties: [{'properties': [], 'label': 'ActedIn'}]
+Relationships: ['(:Person)-[:ActedIn]->(:Movie)']
+"""  # noqa: E501
+
+
+class TestLadybug(unittest.TestCase):
+    def setUp(self) -> None:
+        try:
+            import ladybug as lb
+        except ImportError as e:
+            raise ImportError(
+                "Cannot import Python package ladybug. Please install it by running "
+                "`pip install ladybug`."
+            ) from e
+
+        self.tmpdir = tempfile.mkdtemp()
+        self.db_path = os.path.join(self.tmpdir, "test.db")
+        self.ladybug_database = lb.Database(self.db_path)
+        self.conn = lb.Connection(self.ladybug_database)
+        self.conn.execute("CREATE NODE TABLE Movie (name STRING, PRIMARY KEY(name))")
+        self.conn.execute("CREATE (:Movie {name: 'The Godfather'})")
+        self.conn.execute("CREATE (:Movie {name: 'The Godfather: Part II'})")
+        self.conn.execute(
+            "CREATE (:Movie {name: 'The Godfather Coda: The Death of Michael Corleone'})"
+        )
+        self.ladybug_graph = LadybugGraph(
+            self.ladybug_database, allow_dangerous_requests=True
+        )
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmpdir, ignore_errors=True)
+
+    def test_query_no_params(self) -> None:
+        result = self.ladybug_graph.query("MATCH (n:Movie) RETURN n.name ORDER BY n.name")
+        expected_result = [
+            {"n.name": "The Godfather"},
+            {"n.name": "The Godfather Coda: The Death of Michael Corleone"},
+            {"n.name": "The Godfather: Part II"},
+        ]
+        self.assertEqual(result, expected_result)
+
+    def test_query_params(self) -> None:
+        result = self.ladybug_graph.query(
+            query="MATCH (n:Movie) WHERE n.name = $name RETURN n.name",
+            params={"name": "The Godfather"},
+        )
+        expected_result = [
+            {"n.name": "The Godfather"},
+        ]
+        self.assertEqual(result, expected_result)
+
+    def test_refresh_schema(self) -> None:
+        self.conn.execute(
+            "CREATE NODE TABLE Person (name STRING, birthDate STRING, PRIMARY "
+            "KEY(name))"
+        )
+        self.conn.execute("CREATE REL TABLE ActedIn (FROM Person TO Movie)")
+        self.ladybug_graph.refresh_schema()
+        schema = self.ladybug_graph.get_schema
+        self.assertEqual(schema, EXPECTED_SCHEMA)

langchain_ladybug-0.3.0/tests/unit_tests/test_imports.py

@@ -0,0 +1,31 @@
+"""Verify that all public symbols can be imported from the package."""
+
+
+def test_ladybug_graph_importable() -> None:
+    from langchain_ladybug.graphs import LadybugGraph  # noqa: F401
+
+
+def test_ladybug_qa_chain_importable() -> None:
+    from langchain_ladybug.chains import LadybugQAChain  # noqa: F401
+
+
+def test_graph_document_importable() -> None:
+    from langchain_community.graphs.graph_document import (  # noqa: F401
+        GraphDocument,
+        Node,
+        Relationship,
+    )
+
+
+def test_prompts_importable() -> None:
+    from langchain_ladybug.chains import (  # noqa: F401
+        CYPHER_QA_PROMPT,
+        LADYBUG_GENERATION_PROMPT,
+    )
+
+
+def test_top_level_importable() -> None:
+    import langchain_ladybug  # noqa: F401
+
+    assert hasattr(langchain_ladybug, "LadybugGraph")
+    assert hasattr(langchain_ladybug, "LadybugQAChain")

langchain_ladybug-0.3.0/tests/unit_tests/test_ladybug_qa_chain.py

@@ -0,0 +1,50 @@
+"""Unit tests for LadybugQAChain."""
+
+import pytest
+
+from langchain_ladybug.chains.ladybug_qa import extract_cypher, remove_prefix
+
+
+def test_remove_prefix_removes_when_present() -> None:
+    assert remove_prefix("cypher MATCH (n) RETURN n", "cypher") == " MATCH (n) RETURN n"
+
+
+def test_remove_prefix_unchanged_when_absent() -> None:
+    assert remove_prefix("MATCH (n) RETURN n", "cypher") == "MATCH (n) RETURN n"
+
+
+def test_remove_prefix_empty_string() -> None:
+    assert remove_prefix("", "cypher") == ""
+
+
+def test_extract_cypher_with_backticks() -> None:
+    text = "Here is the query:\n```MATCH (n) RETURN n```"
+    assert extract_cypher(text) == "MATCH (n) RETURN n"
+
+
+def test_extract_cypher_without_backticks() -> None:
+    text = "MATCH (n) RETURN n"
+    assert extract_cypher(text) == "MATCH (n) RETURN n"
+
+
+def test_extract_cypher_returns_first_match() -> None:
+    text = "```first```\n```second```"
+    assert extract_cypher(text) == "first"
+
+
+def test_ladybug_qa_chain_requires_dangerous_requests() -> None:
+    """Constructing LadybugQAChain without opt-in should raise ValueError."""
+    from unittest.mock import MagicMock
+
+    from langchain_ladybug.chains.ladybug_qa import LadybugQAChain
+
+    mock_graph = MagicMock()
+    mock_chain = MagicMock()
+
+    with pytest.raises(ValueError, match="allow_dangerous_requests"):
+        LadybugQAChain(
+            graph=mock_graph,
+            cypher_generation_chain=mock_chain,
+            qa_chain=mock_chain,
+            allow_dangerous_requests=False,
+        )

langchain_ladybug-0.3.0/tests/unit_tests/test_prompts.py

@@ -0,0 +1,29 @@
+"""Unit tests for Ladybug prompt templates."""
+
+from langchain_ladybug.chains.prompts import (
+    CYPHER_QA_PROMPT,
+    LADYBUG_GENERATION_PROMPT,
+)
+
+
+def test_ladybug_generation_prompt_variables() -> None:
+    assert set(LADYBUG_GENERATION_PROMPT.input_variables) == {"schema", "question"}
+
+
+def test_ladybug_generation_prompt_contains_rules() -> None:
+    template = LADYBUG_GENERATION_PROMPT.template
+    assert "()-[]->()" in template
+    assert "triple backticks" in template
+
+
+def test_cypher_qa_prompt_variables() -> None:
+    assert set(CYPHER_QA_PROMPT.input_variables) == {"context", "question"}
+
+
+def test_cypher_qa_prompt_format() -> None:
+    result = CYPHER_QA_PROMPT.format(
+        context="[manager:CTL LLC]",
+        question="Which managers own Neo4j stocks?",
+    )
+    assert "CTL LLC" in result
+    assert "Neo4j stocks" in result