pyqql-edge

Local QQL execution for Python — qdrant-edge + fastembed-rs, zero network.

Features

  • In-Process Vector Storage: Run Qdrant search engine locally inside Python process with zero server daemon requirement
  • Embedded ONNX Inference: Automatically fetch and run FastEmbed ONNX models on-device
  • Native Route Lowering: Lower QQL queries to typed { method, path, payload } route dicts via compile_query
  • Native Parsing: Rust-speed QQL parsing in Python returning Stmt objects or Python dicts
  • Filter Injection: Programmatically add tenant isolation filters
  • Validation: Check if a query string is valid QQL
  • Smart Batching: Auto-batches contiguous same-collection query/mutation statements

Compatibility & Platforms

  • Python 3.8+: Published wheels use Python's stable ABI (abi3-py38).
  • Supported Platforms:
    • Linux x64 (glibc)
    • macOS arm64 (Apple Silicon)
    • Windows x64 (msvc)
  • Note: Prebuilt wheels are not published for macOS Intel (Darwin x64) because ONNX Runtime lacks Darwin x64 prebuilds.

Installation

pip install pyqql-edge

Quick Start

import pyqql_edge

# 1. Discover local ONNX models
models = pyqql_edge.list_embedding_models()
# [{'name': 'BGESmallENV15', 'model_code': 'Xenova/bge-small-en-v1.5', 'dim': 384, ...}, ...]

# 2. Edge execution — pick model (default BGESmallENV15 / 384-d)
client = pyqql_edge.local_executor(
    "./qdrant_data",
    on_disk_payload=False,
    model="bge-small-en-v1.5",        # enum name, HF code, or short alias
    cache_dir="/var/cache/fastembed", # optional
)

# Schema-aware text auto-embed (dense-only, sparse-only, and hybrid)
client.execute("CREATE COLLECTION docs HYBRID")
client.execute(
    'UPSERT INTO docs VALUES {id: "550e8400-e29b-41d4-a716-446655440001", text: "hello"}'
)
result = client.execute("QUERY 'hello' FROM docs USING dense LIMIT 10", on_error="stop")
print(result)

# 3. Parser & Filter Injection
stmt = pyqql_edge.parse("QUERY 'hello' FROM docs LIMIT 10")[0]
tokens = pyqql_edge.tokenize("QUERY 'test' FROM docs")
secured_stmt = pyqql_edge.inject_filter("QUERY 'search' FROM docs", "org_id", "=", "acme")

Execution Results & Error Handling

ExecutionReport Format

All execution methods return an ExecutionReport dictionary:

{
    "ok": True,
    "results": [
        {
            "ok": True,
            "operation": "QUERY",
            "message": "Found 5 hits",
            "data": [...]
        }
    ],
    "succeeded": 1,
    "failed": 0
}

Failure Policy (on_error)

Policy Behavior
"stop" (default) Halts execution on the first error and raises a Python exception.
"continue" Continues executing remaining statements, collecting failures into results with ok: False.

Filter Injection Operators

inject_filter accepts comparison operators:

  • Accepted: =, ==, eq, >, gt, >=, gte, <, lt, <=, lte
  • Rejected: !=, neq, <>, in, is_null (raises SyntaxError — wrap with NOT or write in QQL query)

Edge Gotchas

Gotcha Reality
Point IDs Integers or UUIDs only — "doc-1" is rejected
Text UPSERT into an existing collection Auto-embedding follows the schema: dense-only gets dense, sparse-only gets sparse, hybrid gets both
QUERY 'text' on HYBRID Dense+sparse topology is ambiguous, so specify the target with USING <vector_name>
GROUP BY / shard keys Rejected clearly; never silently ignored in edge mode
Model locked at local_executor() USING MODEL 'other' mismatches fail
Client lifetime Call close() before deleting data_dir

API Summary

Export Description
local_executor(data_dir, ...) Create a fully local edge Client backed by fastembed-rs & qdrant-edge
list_embedding_models() List dense ONNX models available for local_executor(model=...)
http_executor(data_dir, url, ...) Create an edge Client with local vector storage and remote HTTP embedder
Stmt Parsed statement object with inject_filter(), to_json(), to_dict(), shard_key property
parse(input) Parse one statement or a semicolon-delimited script into a list of Stmt objects
is_valid(input) Validate QQL syntax
inject_filter(query, field, op, value) Inject tenant filter into statement AST (accepts str or Stmt)
tokenize(input) Tokenize QQL string for syntax highlighting or inspection
compile_query(input) Lower QQL statement into typed { method, path, payload } route dict
explain(query) Inspect the execution plan without executing network calls (accepts str or Stmt)
execute(query, ..., on_error="stop") One-shot execute with a temporary edge client
execute_async(query, ..., on_error="stop") Async variant of execute
__version__ Package runtime version string

Documentation Links

Project links

Data verified by PyPI on Jul 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for srimon12 from gravatar.com srimon12

Credits

Author: Srimon Danguria

GitHub Statistics

Data verified by PyPI on Jul 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.8

Tags

qql qdrant vector-search embeddings edge

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pyqql_edge-0.1.3-cp38-abi3-win_amd64.whl (20.2 MB view details)

Uploaded CPython 3.8+Windows x86-64

pyqql_edge-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl (21.1 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ x86-64

pyqql_edge-0.1.3-cp38-abi3-macosx_11_0_arm64.whl (18.4 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file pyqql_edge-0.1.3-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql_edge-0.1.3-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 20.2 MB
  • Tags: CPython 3.8+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqql_edge-0.1.3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c1d75a4b06038060d94392fa6c957cc61c728b9c352247eccb2476c0241db758
MD5 337c91923b92170a2cee821b3a12fe70
BLAKE2b-256 b8508aa38e0a42d8e60a3a3ee032fb31fabe1f8147746c4f31f40654abdf3260

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql_edge-0.1.3-cp38-abi3-win_amd64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqql_edge-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqql_edge-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 99843799b85de62f8a5d31e45044dc02bcfea5edde05365e7dd8e7354206c991
MD5 da06a498ebd80d53a6bb16a072a85328
BLAKE2b-256 5fa79f5fcce36b442cd98ed76cbf035d096acaae12ea4ebada91f8921a0ad540

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql_edge-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqql_edge-0.1.3-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pyqql_edge-0.1.3-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1e3f5aef90133c55de44d68f106f09f7a2c85e736ce94df9fb1d115798faa539
MD5 383582876df452e867ce57924c96ffd1
BLAKE2b-256 ee278a184a1dddd9b2311e52d8982b12b20bc428e28a6f2573d26fb9f5ee29cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql_edge-0.1.3-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.1

3 files

0.3.0

3 files

0.2.1

3 files

0.2.0

3 files

0.1.5

3 files

0.1.4

3 files

This release

0.1.3 This release

3 files

0.1.2

3 files

0.1.1

3 files

0.1.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page