# 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"
]
}
}
}
```
### Schema
To dynamically create, load, and edit your Helixdb schema, you can use the `Schema` class.
To get started, you can create a `schema` instance and optionally pass in the path to your configs file.
```python
from helix.loader import Schema
schema = Schema()
```
This will either create a new `schema.hx` file if you don't have one, or load the existing one.
To interact with the schema, you can use various methods, including:
```python
schema.create_node("User", {"name": "String", "age": "U32"})
schema.create_edge("Follows", "User", "User")
schema.create_vector("Vec", {"vec": "Vec32"})
```
To save the schema to your configs folder, you can use the `save` method.
```python
schema.save()
```
## 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.10",
"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/68/1f/8f9804dcf53b16215a708690a2a1e8927a430369cde06ede236a905ed3ab/helix_py-0.2.25.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### Schema\nTo dynamically create, load, and edit your Helixdb schema, you can use the `Schema` class.\nTo get started, you can create a `schema` instance and optionally pass in the path to your configs file.\n```python\nfrom helix.loader import Schema\nschema = Schema()\n```\n\nThis will either create a new `schema.hx` file if you don't have one, or load the existing one.\n\nTo interact with the schema, you can use various methods, including:\n```python\nschema.create_node(\"User\", {\"name\": \"String\", \"age\": \"U32\"})\nschema.create_edge(\"Follows\", \"User\", \"User\")\nschema.create_vector(\"Vec\", {\"vec\": \"Vec32\"})\n```\n\nTo save the schema to your configs folder, you can use the `save` method.\n```python\nschema.save()\n```\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.25",
"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": "d2d257ac80523a1e01d995139e55dfc5e681d458712335719435e54bf081e0ca",
"md5": "47920aaeb83a07b3902a401fbe33e1e3",
"sha256": "d50f2b7545a587164ab81c5f68a747933cdf95d87555b5f2d9ea3464a084efa6"
},
"downloads": -1,
"filename": "helix_py-0.2.25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47920aaeb83a07b3902a401fbe33e1e3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28040,
"upload_time": "2025-08-03T17:03:04",
"upload_time_iso_8601": "2025-08-03T17:03:04.866211Z",
"url": "https://files.pythonhosted.org/packages/d2/d2/57ac80523a1e01d995139e55dfc5e681d458712335719435e54bf081e0ca/helix_py-0.2.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "681f8f9804dcf53b16215a708690a2a1e8927a430369cde06ede236a905ed3ab",
"md5": "37420daf6a978af9966eb45b6f1c3a09",
"sha256": "59e5430e5148801d8b1edf8e36ff93c70aaff45d6f6677f1960ec88930300dba"
},
"downloads": -1,
"filename": "helix_py-0.2.25.tar.gz",
"has_sig": false,
"md5_digest": "37420daf6a978af9966eb45b6f1c3a09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 56537,
"upload_time": "2025-08-03T17:03:08",
"upload_time_iso_8601": "2025-08-03T17:03:08.558652Z",
"url": "https://files.pythonhosted.org/packages/68/1f/8f9804dcf53b16215a708690a2a1e8927a430369cde06ede236a905ed3ab/helix_py-0.2.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 17:03:08",
"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
