# helix-py
[Helix-DB](https://github.com/HelixDB/helix-db) | [Homepage](https://www.helix-db.com/) | [Documentation](https://docs.helix-db.com/introduction/overview) | [PyPi](https://pypi.org/project/helix-py/)
helix-py is a python library for interacting with [helix-db](https://github.com/HelixDB/helix-db) a
graph-vector database written in rust. With a pytorch-like query interface, it supports vector
operations and custom queries, ideal for tasks like similarity search and knowledge graph
construction. This library is meant to extend helix-db to be more easily used in machine learning
applications.
helix-py will soon be built to become a full knowledge graph framework. (this will be v0.3.0)
## Installation
### Install helix-py
`uv add helix-py` or `pip install helix-py`
See [getting started](https://github.com/HelixDB/helix-db?tab=readme-ov-file#getting-started) for more
information on installing helix-db
### Install the Helix CLI
```bash
curl -sSL "https://install.helix-db.com" | bash
helix install
```
## Features
### Queries
helix-py using a pytorch like front-end to creating queries. Like you would define a neural network
forward pass, you can do the same thing for a helix-db query. We provide some default queries in
`helix/client.py` to get started with inserting and search vectors, but you can also define you're
own queries if you plan on doing more complex things. For example, for this hql query
```sql
QUERY add_user(name: String, age: I64) =>
usr <- AddV<User>({name: name, age: age})
RETURN usr
```
you would write
```python
from helix import Query
class add_user(Query):
def __init__(self, name: str, age: int):
super().__init__()
self.name = name
self.age = age
def query(self) -> List[Any]:
return [{ "name": self.name, "age": self.age }]
def response(self, response):
return response.get("res")
```
for your python script. Make sure that the Query.query method returns a list of objects.
### Client
To setup a simple `Client` to interface with a running helix instance:
```python
import helix
from helix.client import hnswinsert, hnswsearch
db = helix.Client(local=True, verbose=True)
data = helix.Loader("path/to/data", cols=["vecs"])
[db.query(hnswinsert(d)) for d in data] # build hnsw index
my_query = [0.32, ..., -1.321]
nearest = db.query(hnswsearch(my_query)) # query hnsw index
```
If you don't want to define a class/methods for every query you have, you can also simply
use
```python
db.query("add_user", { "name", "John", "age": 34 })
```
### Instance
To setup a simple `Instance` that automatically starts and stops a helix instance with respect
to the lifetime of the program, to interface with a `helixdb-cfg` directory you have:
```python
from helix.instance import Instance
helix_instance = Instance("helixdb-cfg", 6969, verbose=True)
```
and from there you can interact with it like you would with the `Client`
### Providers
We also provide an ollama interface. This will be expanded to include many other providers in the future.
```python
from helix.providers import OllamaClient, OpenAIClient
ollama_client = OllamaClient(use_history=True, model="mistral:latest")
# or
openai_client = OpenAIClient(use_history=False, model="gpt-4o")
while True:
prompt = input(">>> ")
res = ollama_client.request(prompt, stream=True)
```
### MCP
Helix's custom mcp server backend is built into the db and the `mcp_server.py` server can be used
to interface with that. To get started with this, you can for example use uv:
```bash
uv init project
cp mcp_server.py project
cd project
uv venv && source .venv/bin/activate
uv add helix-py "mcp[cli]"
```
then for claude-desktop, for example, add this to
`~/Library/Application Support/Claude/claude_desktop_config.json` adjusting paths of course
```json
{
"mcpServers": {
"helix-mcp": {
"command": "uv",
"args": [
"--directory",
"/Users/user/helix-py/project",
"run",
"mcp_server.py"
]
}
}
}
```
### Loader
The loader (`helix/loader.py`) currently supports `.parquet`, `.fvecs`, and `.csv` data. Simply pass in the path to your
file or files and the columns you want to process and the loader does the rest for you and is easy to integrate with
your queries
## License
helix-py is licensed under the The AGPL (Affero General Public License).
Raw data
{
"_id": null,
"home_page": null,
"name": "helix-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Lukas Nitzsche <lukasnitzsche@yahoo.com>",
"keywords": "artificial-intelligence, knowledge graphs, machine-learning, rag",
"author": null,
"author_email": "HelixDB Team <lukasnitzsche@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/56/7956aba695d007aaaa5c7d57456afd707d00608ff15270214aba600f0dec/helix_py-0.2.21.tar.gz",
"platform": null,
"description": "# helix-py\n[Helix-DB](https://github.com/HelixDB/helix-db) | [Homepage](https://www.helix-db.com/) | [Documentation](https://docs.helix-db.com/introduction/overview) | [PyPi](https://pypi.org/project/helix-py/)\n\nhelix-py is a python library for interacting with [helix-db](https://github.com/HelixDB/helix-db) a\ngraph-vector database written in rust. With a pytorch-like query interface, it supports vector\noperations and custom queries, ideal for tasks like similarity search and knowledge graph\nconstruction. This library is meant to extend helix-db to be more easily used in machine learning\napplications.\n\nhelix-py will soon be built to become a full knowledge graph framework. (this will be v0.3.0)\n\n## Installation\n\n### Install helix-py\n`uv add helix-py` or `pip install helix-py`\n\nSee [getting started](https://github.com/HelixDB/helix-db?tab=readme-ov-file#getting-started) for more\ninformation on installing helix-db\n\n### Install the Helix CLI\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\nhelix install\n```\n\n## Features\n\n### Queries\nhelix-py using a pytorch like front-end to creating queries. Like you would define a neural network\nforward pass, you can do the same thing for a helix-db query. We provide some default queries in\n`helix/client.py` to get started with inserting and search vectors, but you can also define you're\nown queries if you plan on doing more complex things. For example, for this hql query\n```sql\nQUERY add_user(name: String, age: I64) =>\n usr <- AddV<User>({name: name, age: age})\n RETURN usr\n```\nyou would write\n```python\nfrom helix import Query\n\nclass add_user(Query):\n def __init__(self, name: str, age: int):\n super().__init__()\n self.name = name\n self.age = age\n\n def query(self) -> List[Any]:\n return [{ \"name\": self.name, \"age\": self.age }]\n\n def response(self, response):\n return response.get(\"res\")\n```\nfor your python script. Make sure that the Query.query method returns a list of objects.\n\n### Client\nTo setup a simple `Client` to interface with a running helix instance:\n```python\nimport helix\nfrom helix.client import hnswinsert, hnswsearch\n\ndb = helix.Client(local=True, verbose=True)\ndata = helix.Loader(\"path/to/data\", cols=[\"vecs\"])\n[db.query(hnswinsert(d)) for d in data] # build hnsw index\n\nmy_query = [0.32, ..., -1.321]\nnearest = db.query(hnswsearch(my_query)) # query hnsw index\n```\n\nIf you don't want to define a class/methods for every query you have, you can also simply\nuse\n```python\ndb.query(\"add_user\", { \"name\", \"John\", \"age\": 34 })\n```\n\n### Instance\nTo setup a simple `Instance` that automatically starts and stops a helix instance with respect\nto the lifetime of the program, to interface with a `helixdb-cfg` directory you have:\n```python\nfrom helix.instance import Instance\nhelix_instance = Instance(\"helixdb-cfg\", 6969, verbose=True)\n```\nand from there you can interact with it like you would with the `Client`\n\n### Providers\nWe also provide an ollama interface. This will be expanded to include many other providers in the future.\n```python\nfrom helix.providers import OllamaClient, OpenAIClient\nollama_client = OllamaClient(use_history=True, model=\"mistral:latest\")\n# or\nopenai_client = OpenAIClient(use_history=False, model=\"gpt-4o\")\n\nwhile True:\n prompt = input(\">>> \")\n res = ollama_client.request(prompt, stream=True)\n```\n\n### MCP\nHelix's custom mcp server backend is built into the db and the `mcp_server.py` server can be used\nto interface with that. To get started with this, you can for example use uv:\n\n```bash\nuv init project\ncp mcp_server.py project\ncd project\nuv venv && source .venv/bin/activate\nuv add helix-py \"mcp[cli]\"\n```\nthen for claude-desktop, for example, add this to\n`~/Library/Application Support/Claude/claude_desktop_config.json` adjusting paths of course\n```json\n{\n \"mcpServers\": {\n \"helix-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/Users/user/helix-py/project\",\n \"run\",\n \"mcp_server.py\"\n ]\n }\n }\n}\n```\n\n### Loader\nThe loader (`helix/loader.py`) currently supports `.parquet`, `.fvecs`, and `.csv` data. Simply pass in the path to your\nfile or files and the columns you want to process and the loader does the rest for you and is easy to integrate with\nyour queries\n\n## License\nhelix-py is licensed under the The AGPL (Affero General Public License).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "helix-db python lib + workflows",
"version": "0.2.21",
"project_urls": {
"Documentation": "https://docs.helix-db.com/",
"Homepage": "https://www.helix-db.com/",
"Issues": "https://github.com/HelixDB/helix-py/issues"
},
"split_keywords": [
"artificial-intelligence",
" knowledge graphs",
" machine-learning",
" rag"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c0398cf0cc8339dd2cf58a59a786c9e86733473365f5938d8824370c70c6e032",
"md5": "e947400b0749fbd473b1c53194681c1e",
"sha256": "3c0780a2dbd33a2a39eb9b98dff67a2ae5f0ffb8adf67a846bc57089907721fe"
},
"downloads": -1,
"filename": "helix_py-0.2.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e947400b0749fbd473b1c53194681c1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25251,
"upload_time": "2025-07-11T21:40:39",
"upload_time_iso_8601": "2025-07-11T21:40:39.326638Z",
"url": "https://files.pythonhosted.org/packages/c0/39/8cf0cc8339dd2cf58a59a786c9e86733473365f5938d8824370c70c6e032/helix_py-0.2.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c1567956aba695d007aaaa5c7d57456afd707d00608ff15270214aba600f0dec",
"md5": "6da5be50f59d50cc6a134e9493a0dc26",
"sha256": "f4c0a5c77eee6fec4fca3a6c501b2fcc495c2a72af8bceb72f5773679a60a66e"
},
"downloads": -1,
"filename": "helix_py-0.2.21.tar.gz",
"has_sig": false,
"md5_digest": "6da5be50f59d50cc6a134e9493a0dc26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 50047,
"upload_time": "2025-07-11T21:40:43",
"upload_time_iso_8601": "2025-07-11T21:40:43.471837Z",
"url": "https://files.pythonhosted.org/packages/c1/56/7956aba695d007aaaa5c7d57456afd707d00608ff15270214aba600f0dec/helix_py-0.2.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 21:40:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HelixDB",
"github_project": "helix-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "helix-py"
}
JSON
