feat: Project setup and initial implementation of Neo4jDataStore

.gitignore

@@ -0,0 +1,19 @@
+.idea/
+.vscode/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+build/
+htmlcov/
+site/
+.coverage*
+__pypackages__/
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.python-version
+.venv/
+.cache/
+.env

CHANGELOG.md

@@ -0,0 +1 @@
+TODO

CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing
+
+## Environment setup
+
+Fork and clone the repository, then:
+
+```bash
+cd scripts
+./setup.sh
+```
+
+> NOTE:
+> If it fails for some reason,
+> you'll need to install
+> [Hatch](https://hatch.pypa.io/latest/)
+> manually.
+>
+> You can install it with:
+>
+> ```bash
+> python3 -m pip install --user pipx
+> pipx install hatch
+> ```
+>
+> Now you can try running `hatch env show` to see
+> all available environments and provided scripts.
+
+Hatch automatically manages dependencies for given environments. Default environment can be used for running unit/integration tests.
+
+For local development it is suggested to configure Hatch to create virtual environments inside project's folder. First find the location of the configuration file:
+
+```bash
+hatch config find # see where configuration file is located
+```
+
+Update configuration with the following:
+
+```toml
+[dirs.env]
+virtual = ".venv"
+```
+
+If you run `hatch env create dev` you should see `.venv/dev` directory created with dependencies you need for development.
+You could point your IDE to this particular python environment/interpreter.
+
+## Development
+
+1. create a new branch: `git switch -c feature-or-bugfix-name`
+1. edit the code and/or the documentation
+
+**Before committing:**
+
+1. run `hatch run lint:all` for code quality checks and formatting
+1. run `hatch run test` to run the tests (fix any issue)
+1. if you updated the documentation or the project dependencies:
+    1. run `hatch run docs:serve`
+    1. go to http://localhost:8000/neo4j-haystack/ and check that everything looks good
+1. follow our [commit message convention](#commit-message-convention)
+
+Don't bother updating the changelog, we will take care of this.
+
+## Commit message convention
+
+Commit messages must follow the convention based on the
+[Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message)
+or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
+
+```text
+<type>[(scope)]: Subject
+
+[Body]
+```
+
+**Subject and body must be valid Markdown.**
+Subject must have proper casing (uppercase for first letter
+if it makes sense), but no dot at the end, and no punctuation
+in general.
+
+Scope and body are optional. Type can be:
+
+- `build`: About packaging, building wheels, etc.
+- `chore`: About packaging or repo/files management.
+- `ci`: About Continuous Integration.
+- `deps`: Dependencies update.
+- `docs`: About documentation.
+- `feat`: New feature.
+- `fix`: Bug fix.
+- `perf`: About performance.
+- `refactor`: Changes that are not features or bug fixes.
+- `style`: A change in code style/format.
+- `tests`: About tests.
+
+If you write a body, please add trailers at the end
+(for example issues and PR references, or co-authors),
+without relying on GitHub's flavored Markdown:
+
+```text
+Body.
+
+Issue #10: https://github.com/<namespace>/<project>/issues/10
+Related to PR namespace/other-project#15: https://github.com/<namespace>/<other-project>/pull/15
+```
+
+These "trailers" must appear at the end of the body,
+without any blank lines between them. The trailer title
+can contain any character except colons `:`.
+We expect a full URI for each trailer, not just GitHub autolinks
+(for example, full GitHub URLs for commits and issues,
+not the hash or the #issue-number).
+
+We do not enforce a line length on commit messages summary and body,
+but please avoid very long summaries, and very long lines in the body,
+unless they are part of code blocks that must not be wrapped.
+
+## Pull requests guidelines
+
+Link to any related issue in the Pull Request message.
+
+During the review, we recommend using fixups:
+
+```bash
+# SHA is the SHA of the commit you want to fix
+git commit --fixup=SHA
+```
+
+Once all the changes are approved, you can squash your commits:
+
+```bash
+git rebase -i --autosquash main
+```
+
+And force-push:
+
+```bash
+git push -f
+```
+
+If this seems all too complicated, you can push or force-push each new commit,
+and we will squash them ourselves if needed, before merging.

LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023-present Sergey Bondarenco <sergey.bondarenco@outlook.com>
+
+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.

README.md

@@ -0,0 +1,125 @@
+<h1 align="center">neo4j-haystack</h1>
+
+<p align="center">A <a href="https://docs.haystack.deepset.ai/docs/document_store"><i>Haystack</i></a> Document Store for <a href="https://neo4j.com/"><i>Neo4j</i></a>.</p>
+
+<p align="center">
+  <a href="https://github.com/prosto/neo4j-haystack/actions?query=workflow%3Aci">
+    <img alt="ci" src="https://github.com/prosto/neo4j-haystack/workflows/ci/badge.svg" />
+  </a>
+  <a href="https://prosto.github.io/neo4j-haystack/">
+    <img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
+  </a>
+  <a href="https://pypi.org/project/neo4j-haystack/">
+    <img alt="pypi version" src="https://img.shields.io/pypi/v/neo4j-haystack.svg" />
+  </a>
+  <a href="https://img.shields.io/pypi/pyversions/neo4j-haystack.svg">
+    <img alt="python version" src="https://img.shields.io/pypi/pyversions/neo4j-haystack.svg" />
+  </a>
+</p>
+
+----
+
+**Table of Contents**
+
+- [Overview](#overview)
+- [Usage](#usage)
+- [Installation](#installation)
+- [License](#license)
+
+## Overview
+
+An integration of [Neo4j](https://neo4j.com/) graph database with [Haystack](https://haystack.deepset.ai/)
+by [deepset](https://www.deepset.ai). In Neo4j [Vector search index](https://neo4j.com/docs/cypher-manual/current/indexes-for-vector-search/)
+is being used for storing document embeddings and dense retrials.
+
+The library allows using Neo4j as a [DocumentStore](https://docs.haystack.deepset.ai/docs/document_store), and provides an in-place replacement
+for any other vector embeddings store. Thus, you should expect any kind of application to be working
+smoothly just by changing the provider to `Neo4jDocumentStore`.
+
+The key difference between `Neo4jDocumentStore` and other types of stores is that Document properties are stored as Graph nodes. Embeddings are stored as properties of a Document node,
+but indexing and querying of vector embeddings using approximate nearest neighbor search is managed by a dedicated Vector Index.
+
+```text
+                                   +-----------------------------+
+                                   |       Neo4j Database        |
+                                   +-----------------------------+
+                                   |                             |
+                                   |      +----------------+     |
+                                   |      |    Document    |     |
+                write_documents    |      +----------------+     |
+          +------------------------+----->|   properties   |     |
+          |                        |      |                |     |
++---------+----------+             |      |   embedding    |     |
+|                    |             |      +--------+-------+     |
+| Neo4jDocumentStore |             |               |             |
+|                    |             |               |index/query  |
++---------+----------+             |               |             |
+          |                        |      +--------+--------+    |
+          |                        |      |  Vector Index   |    |
+          +----------------------->|      |                 |    |
+               query_embeddings    |      | (for embedding) |    |
+                                   |      +-----------------+    |
+                                   |                             |
+                                   +-----------------------------+
+```
+
+In the above diagram:
+
+- `Document` is a Neo4j node (with "Document" label)
+- `properties` are Document [attributes](https://docs.haystack.deepset.ai/docs/documents_answers_labels#attributes) stored as part of the node.
+- `embedding` is also a property of the Document node (just shown separately in the diagram for clarity) which is a vector of type `LIST[FLOAT]`
+- `Vector Index` is where embeddings are getting indexed by Neo4j (as soon as those are updated in Document nodes)
+
+The `neo4j-haystack` library uses [python-driver](https://neo4j.com/docs/api/python-driver/current/api.html#api-documentation) and
+[Cypher Queries](https://neo4j.com/docs/cypher-manual/current/introduction/) to implement DocumentStore related API methods and hide all complexities under the hood.
+
+## Installation
+
+`neo4j-haystack` can be installed as any other Python library, using pip:
+
+```bash
+pip install --upgrade pip # optional
+pip install neo4j-haystack
+```
+
+## Usage
+
+Once installed, you can start using `Neo4jDocumentStore` as any other document stores that support embeddings.
+
+```python
+from neo4j_haystack import Neo4jDocumentStore
+
+document_store = Neo4jDocumentStore(
+    url="bolt://localhost:7687",
+    username="neo4j",
+    password="passw0rd",
+    database="neo4j",
+    embedding_dim=384,
+    embedding_field="embedding",
+    index="document-embeddings", # The name of the Vector Index in Neo4j
+    node_label="Document", # Providing a label to Neo4j nodes which store Documents
+)
+```
+
+The full list of parameters accepted by `Neo4jDocumentStore` can be found in
+[API documentation](https://prosto.github.io/neo4j-haystack/reference/neo4j_store/#neo4j_haystack.document_stores.neo4j_store.Neo4jDocumentStore.__init__).
+
+Please notice you will need to have a running instance of Neo4j database (in-memory version of Neo4j is not supported). There are several options available:
+
+- [Docker](https://neo4j.com/docs/operations-manual/5/docker/), other options available in the same Operations Manual
+- [AuraDB](https://neo4j.com/cloud/platform/aura-graph-database/) - a fully managed Cloud Instance of Neo4j
+- [Neo4j Desktop](https://neo4j.com/docs/desktop-manual/current/) client application
+
+The simplest way to start database locally will be with Docker container:
+
+```bash
+docker run \
+    --restart always \
+    --publish=7474:7474 --publish=7687:7687 \
+    --env NEO4J_AUTH=neo4j/passw0rd \
+    neo4j:5.15.0
+```
+
+## License
+
+`neo4j-haystack` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.