# Neo4j GenAI package for Python
This repository contains the official Neo4j GenAI features for Python.
The purpose of this package is to provide a first party package to developers,
where Neo4j can guarantee long term commitment and maintenance as well as being
fast to ship new features and high performing patterns and methods.
Documentation: https://neo4j.com/docs/neo4j-genai-python/
Python versions supported:
* Python 3.12 supported.
* Python 3.11 supported.
* Python 3.10 supported.
* Python 3.9 supported.
* Python 3.8 supported.
# Usage
## Installation
This package requires Python (>=3.8.1).
To install the latest stable version, use:
```shell
pip install neo4j-genai
```
## Examples
### Creating a vector index
When creating a vector index, make sure you match the number of dimensions in the index with the number of dimensions the embeddings have.
Assumption: Neo4j running
```python
from neo4j import GraphDatabase
from neo4j_genai.indexes import create_vector_index
URI = "neo4j://localhost:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "vector-index-name"
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Creating the index
create_vector_index(
driver,
INDEX_NAME,
label="Document",
embedding_property="vectorProperty",
dimensions=1536,
similarity_fn="euclidean",
)
```
### Populating the Neo4j Vector Index
Note that the below example is not the only way you can upsert data into your Neo4j database. For example, you could also leverage [the Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver).
Assumption: Neo4j running with a defined vector index
```python
from neo4j import GraphDatabase
from neo4j_genai.indexes import upsert_vector
URI = "neo4j://localhost:7687"
AUTH = ("neo4j", "password")
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Upsert the vector
vector = ...
upsert_vector(
driver,
node_id=1,
embedding_property="vectorProperty",
vector=vector,
)
```
### Performing a similarity search
Assumption: Neo4j running with populated vector index in place.
Limitation: The query over the vector index is an _approximate_ nearest neighbor search and may not give exact results. [See this reference for more details](https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/#limitations-and-issues).
While the library has more retrievers than shown here, the following examples should be able to get you started.
In the following example, we use a simple vector search as retriever,
that will perform a similarity search over the `index-name` vector index
in Neo4j.
```python
from neo4j import GraphDatabase
from neo4j_genai.retrievers import VectorRetriever
from neo4j_genai.llm import OpenAILLM
from neo4j_genai.generation import GraphRAG
from neo4j_genai.embeddings.openai import OpenAIEmbeddings
URI = "neo4j://localhost:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "vector-index-name"
# Connect to Neo4j database
driver = GraphDatabase.driver(URI, auth=AUTH)
# Create Embedder object
embedder = OpenAIEmbeddings(model="text-embedding-3-large")
# Initialize the retriever
retriever = VectorRetriever(driver, INDEX_NAME, embedder)
# Initialize the LLM
# Note: An OPENAI_API_KEY environment variable is required here
llm = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})
# Initialize the RAG pipeline
rag = GraphRAG(retriever=retriever, llm=llm)
# Query the graph
query_text = "How do I do similarity search in Neo4j?"
response = rag.search(query_text=query_text, retriever_config={"top_k": 5})
print(response.answer)
```
# Development
## Install dependencies
```bash
poetry install
```
## Getting started
### Issues
If you have a bug to report or feature to request, first
[search to see if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments).
If a related issue doesn't exist, please raise a new issue using the relevant
[issue form](https://github.com/neo4j/neo4j-genai-python/issues/new/choose).
If you're a Neo4j Enterprise customer, you can also reach out to [Customer Support](http://support.neo4j.com/).
If you don't have a bug to report or feature request, but you need a hand with
the library; community support is available via [Neo4j Online Community](https://community.neo4j.com/)
and/or [Discord](https://discord.gg/neo4j).
### Make changes
1. Fork the repository.
2. Install Python and Poetry.
3. Create a working branch from `main` and start with your changes!
### Pull request
When you're finished with your changes, create a pull request, also known as a PR.
- Ensure that you have [signed the CLA](https://neo4j.com/developer/contributing-code/#sign-cla).
- Ensure that the base of your PR is set to `main`.
- Don't forget to [link your PR to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
if you are solving one.
- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
so that maintainers can make any necessary tweaks and update your branch for merge.
- Reviewers may ask for changes to be made before a PR can be merged, either using
[suggested changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)
or normal pull request comments. You can apply suggested changes directly through
the UI, and any other changes can be made in your fork and committed to the PR branch.
- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
- Update the `CHANGELOG.md` if you have made significant changes to the project, these include:
- Major changes:
- New features
- Bug fixes with high impact
- Breaking changes
- Minor changes:
- Documentation improvements
- Code refactoring without functional impact
- Minor bug fixes
- Keep `CHANGELOG.md` changes brief and focus on the most important changes.
### Updating the `CHANGELOG.md`
1. When opening a PR, you can generate an edit suggestion by commenting on the GitHub PR [using CodiumAI](https://github.com/CodiumAI-Agent):
```
@CodiumAI-Agent /update_changelog
```
2. Use this as a suggestion and update the `CHANGELOG.md` content under 'Next'.
3. Commit the changes.
## Run tests
### Unit tests
This should run out of the box once the dependencies are installed.
```bash
poetry run pytest tests/unit
```
### E2E tests
To run e2e tests you'd need to have some services running locally:
- neo4j
- weaviate
- weaviate-text2vec-transformers
The easiest way to get it up and running is via Docker compose:
```bash
docker compose -f tests/e2e/docker-compose.yml up
```
_(pro tip: if you suspect something in the databases are cached, run `docker compose -f tests/e2e/docker-compose.yml down` to remove them completely)_
Once the services are running, execute the following command to run the e2e tests.
```bash
poetry run pytest tests/e2e
```
## Further information
- [The official Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver)
- [Neo4j GenAI integrations](https://neo4j.com/docs/cypher-manual/current/genai-integrations/)
Raw data
{
"_id": null,
"home_page": "https://neo4j.com/",
"name": "neo4j-genai",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": null,
"keywords": null,
"author": "Neo4j, Inc",
"author_email": "team-gen-ai@neo4j.com",
"download_url": "https://files.pythonhosted.org/packages/71/62/5bbe113b35563d13b5e99fc4581bd3d02f00821f8d8910f568bd9e0f0ecc/neo4j_genai-0.4.0.tar.gz",
"platform": null,
"description": "# Neo4j GenAI package for Python\n\nThis repository contains the official Neo4j GenAI features for Python.\n\nThe purpose of this package is to provide a first party package to developers,\nwhere Neo4j can guarantee long term commitment and maintenance as well as being\nfast to ship new features and high performing patterns and methods.\n\nDocumentation: https://neo4j.com/docs/neo4j-genai-python/\n\nPython versions supported:\n\n* Python 3.12 supported.\n* Python 3.11 supported.\n* Python 3.10 supported.\n* Python 3.9 supported.\n* Python 3.8 supported.\n\n# Usage\n\n## Installation\n\nThis package requires Python (>=3.8.1).\n\nTo install the latest stable version, use:\n\n```shell\npip install neo4j-genai\n```\n\n## Examples\n\n### Creating a vector index\n\nWhen creating a vector index, make sure you match the number of dimensions in the index with the number of dimensions the embeddings have.\n\nAssumption: Neo4j running\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_genai.indexes import create_vector_index\n\nURI = \"neo4j://localhost:7687\"\nAUTH = (\"neo4j\", \"password\")\n\nINDEX_NAME = \"vector-index-name\"\n\n# Connect to Neo4j database\ndriver = GraphDatabase.driver(URI, auth=AUTH)\n\n# Creating the index\ncreate_vector_index(\n driver,\n INDEX_NAME,\n label=\"Document\",\n embedding_property=\"vectorProperty\",\n dimensions=1536,\n similarity_fn=\"euclidean\",\n)\n\n```\n\n### Populating the Neo4j Vector Index\n\nNote that the below example is not the only way you can upsert data into your Neo4j database. For example, you could also leverage [the Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver).\n\nAssumption: Neo4j running with a defined vector index\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_genai.indexes import upsert_vector\n\nURI = \"neo4j://localhost:7687\"\nAUTH = (\"neo4j\", \"password\")\n\n# Connect to Neo4j database\ndriver = GraphDatabase.driver(URI, auth=AUTH)\n\n# Upsert the vector\nvector = ...\nupsert_vector(\n driver,\n node_id=1,\n embedding_property=\"vectorProperty\",\n vector=vector,\n)\n```\n\n### Performing a similarity search\n\nAssumption: Neo4j running with populated vector index in place.\n\nLimitation: The query over the vector index is an _approximate_ nearest neighbor search and may not give exact results. [See this reference for more details](https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/#limitations-and-issues).\n\nWhile the library has more retrievers than shown here, the following examples should be able to get you started.\n\nIn the following example, we use a simple vector search as retriever,\nthat will perform a similarity search over the `index-name` vector index\nin Neo4j.\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_genai.retrievers import VectorRetriever\nfrom neo4j_genai.llm import OpenAILLM\nfrom neo4j_genai.generation import GraphRAG\nfrom neo4j_genai.embeddings.openai import OpenAIEmbeddings\n\nURI = \"neo4j://localhost:7687\"\nAUTH = (\"neo4j\", \"password\")\n\nINDEX_NAME = \"vector-index-name\"\n\n# Connect to Neo4j database\ndriver = GraphDatabase.driver(URI, auth=AUTH)\n\n# Create Embedder object\nembedder = OpenAIEmbeddings(model=\"text-embedding-3-large\")\n\n# Initialize the retriever\nretriever = VectorRetriever(driver, INDEX_NAME, embedder)\n\n# Initialize the LLM\n# Note: An OPENAI_API_KEY environment variable is required here\nllm = OpenAILLM(model_name=\"gpt-4o\", model_params={\"temperature\": 0})\n\n# Initialize the RAG pipeline\nrag = GraphRAG(retriever=retriever, llm=llm)\n\n# Query the graph\nquery_text = \"How do I do similarity search in Neo4j?\"\nresponse = rag.search(query_text=query_text, retriever_config={\"top_k\": 5})\nprint(response.answer)\n```\n\n# Development\n\n## Install dependencies\n\n```bash\npoetry install\n```\n\n## Getting started\n\n### Issues\n\nIf you have a bug to report or feature to request, first\n[search to see if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments).\nIf a related issue doesn't exist, please raise a new issue using the relevant\n[issue form](https://github.com/neo4j/neo4j-genai-python/issues/new/choose).\n\nIf you're a Neo4j Enterprise customer, you can also reach out to [Customer Support](http://support.neo4j.com/).\n\nIf you don't have a bug to report or feature request, but you need a hand with\nthe library; community support is available via [Neo4j Online Community](https://community.neo4j.com/)\nand/or [Discord](https://discord.gg/neo4j).\n\n### Make changes\n\n1. Fork the repository.\n2. Install Python and Poetry.\n3. Create a working branch from `main` and start with your changes!\n\n### Pull request\n\nWhen you're finished with your changes, create a pull request, also known as a PR.\n\n- Ensure that you have [signed the CLA](https://neo4j.com/developer/contributing-code/#sign-cla).\n- Ensure that the base of your PR is set to `main`.\n- Don't forget to [link your PR to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)\n if you are solving one.\n- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)\n so that maintainers can make any necessary tweaks and update your branch for merge.\n- Reviewers may ask for changes to be made before a PR can be merged, either using\n [suggested changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)\n or normal pull request comments. You can apply suggested changes directly through\n the UI, and any other changes can be made in your fork and committed to the PR branch.\n- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).\n- Update the `CHANGELOG.md` if you have made significant changes to the project, these include:\n - Major changes:\n - New features\n - Bug fixes with high impact\n - Breaking changes\n - Minor changes:\n - Documentation improvements\n - Code refactoring without functional impact\n - Minor bug fixes\n- Keep `CHANGELOG.md` changes brief and focus on the most important changes.\n\n### Updating the `CHANGELOG.md`\n\n1. When opening a PR, you can generate an edit suggestion by commenting on the GitHub PR [using CodiumAI](https://github.com/CodiumAI-Agent):\n\n```\n@CodiumAI-Agent /update_changelog\n```\n\n2. Use this as a suggestion and update the `CHANGELOG.md` content under 'Next'.\n3. Commit the changes.\n\n## Run tests\n\n### Unit tests\n\nThis should run out of the box once the dependencies are installed.\n\n```bash\npoetry run pytest tests/unit\n```\n\n### E2E tests\n\nTo run e2e tests you'd need to have some services running locally:\n\n- neo4j\n- weaviate\n- weaviate-text2vec-transformers\n\nThe easiest way to get it up and running is via Docker compose:\n\n```bash\ndocker compose -f tests/e2e/docker-compose.yml up\n```\n\n_(pro tip: if you suspect something in the databases are cached, run `docker compose -f tests/e2e/docker-compose.yml down` to remove them completely)_\n\nOnce the services are running, execute the following command to run the e2e tests.\n\n```bash\npoetry run pytest tests/e2e\n```\n\n## Further information\n\n- [The official Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver)\n- [Neo4j GenAI integrations](https://neo4j.com/docs/cypher-manual/current/genai-integrations/)\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Python package to allow easy integration to Neo4j's GenAI features",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://neo4j.com/",
"Repository": "https://github.com/neo4j/neo4j-genai-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a6afa8fdeb2902622a5d9c8700b394c0b1127431f3ef3e2e896de8cc76c9826",
"md5": "3eb0c95058e9816aaf14db014ea1b448",
"sha256": "6f1967e96447312f692732adb114020f6e66a84e8809d11f6f70046e20c2b871"
},
"downloads": -1,
"filename": "neo4j_genai-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3eb0c95058e9816aaf14db014ea1b448",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 59738,
"upload_time": "2024-08-08T11:37:58",
"upload_time_iso_8601": "2024-08-08T11:37:58.954968Z",
"url": "https://files.pythonhosted.org/packages/9a/6a/fa8fdeb2902622a5d9c8700b394c0b1127431f3ef3e2e896de8cc76c9826/neo4j_genai-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71625bbe113b35563d13b5e99fc4581bd3d02f00821f8d8910f568bd9e0f0ecc",
"md5": "3b1c6d21671ff1ff985727e5d3f13326",
"sha256": "77974e5ac66f5662bb19085ee8e6e909cb3ee14472168c1ef061fe3c426bb7d6"
},
"downloads": -1,
"filename": "neo4j_genai-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "3b1c6d21671ff1ff985727e5d3f13326",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 34980,
"upload_time": "2024-08-08T11:38:00",
"upload_time_iso_8601": "2024-08-08T11:38:00.626178Z",
"url": "https://files.pythonhosted.org/packages/71/62/5bbe113b35563d13b5e99fc4581bd3d02f00821f8d8910f568bd9e0f0ecc/neo4j_genai-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-08 11:38:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neo4j",
"github_project": "neo4j-genai-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neo4j-genai"
}
JSON
