Metadata-Version: 2.4
Name: lightningdb
Version: 0.2.0rc2
Summary: HTTP client, LangChain retriever, and LlamaIndex retriever for LightningDB
Author: LightningDB
Project-URL: Homepage, https://lightninggraph.com/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: engine
Requires-Dist: lightningdb-engine==0.2.0rc2; extra == "engine"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: llama-index
Requires-Dist: llama-index-core>=0.10; extra == "llama-index"
Provides-Extra: neo4j
Requires-Dist: neo4j==5.28.6; extra == "neo4j"
Provides-Extra: rag
Requires-Dist: langchain-core>=0.2; extra == "rag"
Requires-Dist: llama-index-core>=0.10; extra == "rag"
Requires-Dist: transformers>=4.40; extra == "rag"
Requires-Dist: accelerate>=0.30; extra == "rag"
Provides-Extra: load
Requires-Dist: locust>=2.24; extra == "load"

# LightningDB Python client

Python 3.10+ client for a LightningDB engine. The engine is a separate local
process or an operator-managed service. This package does not install a model.

The current Linux Free release candidates are available directly from
https://lightninggraph.com/download. Public PyPI and conda publication are
pending; install these builds from the website's package directory.

Install the client from the website:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --no-index --find-links https://lightninggraph.com/downloads/0.2.0rc2/ lightningdb==0.2.0rc2
```

On supported Linux, install the native Free engine as well:

```bash
python -m pip install --no-index --find-links https://lightninggraph.com/downloads/0.2.0rc2/ 'lightningdb[engine]==0.2.0rc2'
graphdb
```

Linux engine wheels support glibc 2.35+ on their tagged architecture. macOS,
Windows and musl/Alpine wheels are not included. Running `graphdb` starts the backend, creates or reopens the graph in your
standard private Linux user data directory, and opens the Browser. Upgrades and
uninstalling the package leave that user data intact.

```python
import os
from lightningdb import LightningDB, LightningDBError

# Omit api_key for an unkeyed loopback-only development engine.
db = LightningDB('http://127.0.0.1:7475', api_key=os.environ.get('GRAPHDB_API_KEY'))
print(db.health())
db.query('CREATE (n:Customer {name:$name,active:$active})',
         params={'name': 'Acme', 'active': True})
print(db.query('MATCH (n:Customer) RETURN n.name,n.active'))
db.backup('/absolute/server/path/customer-backup.gdb')
db.export('/absolute/server/path/new-export', format='jsonl')
```

Import, export, backup and restore paths refer to the **server's filesystem**.
Export requires a new destination. CSV/JSONL export the logical graph; snapshots
retain the complete engine state. `migrate_csv(directory)` replaces the selected
graph with the supported CSV/JSONL import. `restore(path)` loads a snapshot.
Requests rejected by the engine raise `LightningDBError` with an HTTP `status`.

API keys use Bearer authentication. Remote keys require HTTPS; redirects are
refused so credentials cannot be forwarded to another host. The native server
needs a TLS reverse proxy for network access. It is a single operator service.

## Neo4j migration

Install the pinned optional driver from an approved index:

```bash
python -m pip install 'neo4j==5.28.6'
```

The native `.dump` decoder additionally requires Docker. The tested format is
Neo4j 5.26.32. Unsupported multi-label nodes, relationship properties, parallel
relationships and temporal/spatial values fail explicitly. Test a copy of each
customer's graph before cutover.

## Optional model integrations

The `langchain` and `llama-index` extras provide retrievers. Both accept `api_key`
and `timeout`. Model inference runs in the application's chosen model runtime;
no model weights, hosting charges or model license are bundled. Current engine
retrieval uses a fixed 32-dimensional topic embedding space and requires separate
validation with a customer's real embeddings before a production RAG rollout.
