velesdb-common
Shared utilities for VelesDB Python integrations.
This package is not a public API. End users should install and import from
langchain-velesdb,llama-index-vector-stores-velesdb, orhaystack-velesdbdirectly.
What it provides
velesdb-common centralizes code shared by all three Python RAG framework integration packages:
- Security validators — input sanitization for collection names, dimensions, queries, URLs
- ID generation — deterministic hashing and sequential ID counters
- Score direction — whether a metric's score is a similarity or a distance, from core
- Graph helpers — REST payload builders and native graph bindings
- Memory formatting — procedural memory result formatting
Public Exports
The following symbols form the stable internal API consumed by langchain-velesdb,
llama-index-vector-stores-velesdb, and haystack-velesdb. They are not intended for
direct use by end users.
Fusion
| Export | Type | Description |
|---|---|---|
build_fusion_strategy |
function | Converts a strategy name + params dict into the native FusionStrategy object |
Shared mixins / bases
| Export | Type | Description |
|---|---|---|
CollectionAdminMixin |
class | Mixin providing shared admin operations (create_metadata_collection, is_metadata_only, train_pq, analyze_collection, get_collection_stats) |
GraphOpsBase |
class | Base class for graph query helpers used by both integrations |
ID helpers
| Export | Type | Description |
|---|---|---|
stable_hash_id |
function | Deterministic 64-bit hash of an input string (used as collection-stable ID). SHA-256 by default; pass algorithm="fnv1a" to get VelesDB core's/velesdb-migrate's FNV-1a IDs, which calls velesdb.hash_id (velesdb >= 8.0.0; ImportError with an older wheel) — see KNOWN_LIMITATIONS #12 before switching |
make_initial_id_counter |
function | Builds a thread-safe sequential ID counter seeded from existing collection state |
Score helpers
| Export | Type | Description |
|---|---|---|
metric_higher_is_better |
function | Whether a higher score is a closer match under a metric (cosine, dot, jaccard: yes; euclidean, hamming: no), read from velesdb.metric_higher_is_better, with a literal fallback for a wheel older than 8.0.0 |
score_to_similarity |
function | A raw single-metric score as a higher-is-closer similarity: similarities pass through, a distance d becomes 1 / (1 + d) |
fused_higher_is_better |
function | Whether a multi_query_search score fused by a strategy is higher-is-closer under a metric (RRF, relative score: always; average, maximum, weighted: only under a similarity metric), read from FusionStrategy.fused_higher_is_better, with a literal fallback for a wheel older than 8.0.0 |
to_similarity |
function | A score of known direction as a higher-is-closer similarity: a higher-is-better score passes through, a lower-is-better d becomes 1 / (1 + d) |
Memory helpers
| Export | Type | Description |
|---|---|---|
chronological |
function | Sorts episodic events oldest-first on (timestamp, id) |
format_procedural_results |
function | Normalizes raw procedural-memory recall output into a stable result list |
parse_event_entry |
function | Parses a JSON event description into (role, content) |
resolve_procedure_id |
function | Resolves a procedure name or numeric ID for reinforce() |
store_procedure |
function | Inserts a procedural-memory entry with the canonical schema used by both integrations |
Security: validators
| Export | Type | Description |
|---|---|---|
SecurityError |
exception | Raised by every validate_* on rejected input |
validate_url |
function | Validates a server URL string |
validate_text |
function | Sanitizes free-text query strings against injection patterns |
validate_query |
function | Validates VelesQL query strings against length / character limits |
validate_collection_name |
function | Alphanumeric + underscore, ≤ 64 chars |
validate_dimension |
function | Within MIN_DIMENSION..=MAX_DIMENSION |
validate_metric |
function | Against ALLOWED_METRICS |
validate_storage_mode |
function | Against ALLOWED_STORAGE_MODES / STORAGE_MODE_ALIASES |
validate_path |
function | Filesystem path bounds + character rules |
validate_k |
function | k value in [1, MAX_K_VALUE] |
validate_batch_size |
function | Batch size in [1, MAX_BATCH_SIZE] |
validate_timeout |
function | Timeout ms within sane bounds |
validate_weight |
function | Fusion weight in [0.0, 1.0] |
validate_sparse_vector |
function | Sparse pair list bounds |
validate_search_quality |
function | A search quality mode, checked by velesdb-core's parser through velesdb.validate_search_quality (velesdb >= 8.0.0; an older wheel checks only the type and refuses a bad mode at search time) |
Security: constants
| Export | Type | Description |
|---|---|---|
ALLOWED_METRICS |
set | Canonical metric strings (cosine, euclidean, dot, …); single-sourced from velesdb.DISTANCE_METRICS, with a literal fallback when the wheel is absent |
ALLOWED_STORAGE_MODES |
set | Canonical storage modes (full, sq8, binary, pq, rabitq); single-sourced from velesdb.STORAGE_MODES, with a literal fallback when the wheel is absent |
ALLOWED_CONDITION_TYPES |
set | Canonical procedural condition types; single-sourced from velesdb.CONDITION_TYPES, with a literal fallback when the wheel is absent |
STORAGE_MODE_ALIASES |
dict | Alias → canonical mapping (e.g. int8 → sq8) |
DEFAULT_TIMEOUT_MS |
int | Default timeout used when callers don't specify one |
MIN_DIMENSION / MAX_DIMENSION |
int | Vector dimension bounds |
MAX_BATCH_SIZE |
int | Hard cap on per-call batch operations |
MAX_K_VALUE |
int | Hard cap on retrieval k |
MAX_PATH_LENGTH |
int | Filesystem path length cap |
MAX_QUERY_LENGTH |
int | VelesQL query length cap |
MAX_SPARSE_VECTOR_SIZE |
int | Sparse vector non-zero entry cap |
MAX_TEXT_LENGTH |
int | Free-text query length cap |
Graph helpers
| Export | Type | Description |
|---|---|---|
build_graph_rest_payload |
function | Constructs the JSON body for REST-backed graph traversal calls |
parse_graph_traverse_response |
function | Decodes a graph traversal REST response into the integer ids it reached |
parse_graph_traverse_results |
function | Decodes a graph traversal REST response into (target_id, depth) pairs, in the server's order |
open_native_graph |
function | Opens (or attaches to) a native-backend graph collection |
is_timeout_exception |
function | Cross-backend timeout-error predicate |
License
MIT License (this integration). See LICENSE for details.
VelesDB Core itself is licensed under the VelesDB Core License 1.0 (based on ELv2).
1 maintainer
Metadata
1 maintainer
Release files for velesdb-common 8.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| velesdb_common-8.1.0.tar.gz | 32.9 kB | Without provenance | Details for velesdb_common-8.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| velesdb_common-8.1.0-py3-none-any.whl | Python 3 | none | any | Details for velesdb_common-8.1.0-py3-none-any.whl |
Total release size: 58.8 kB
Release files / velesdb_common-8.1.0.tar.gz
| Download URL | velesdb_common-8.1.0.tar.gz |
|---|---|
| Size | 32.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
205c0d7c1dce66886ecaa368504803a170d777a28d233e3136d7c18800cd53c8
|
|
BLAKE2b-256 checksum How to use checksums |
0786dbbb4ff91b56f23bf58361464200bb8b497678dd0a0bbf236687cef97128
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / velesdb_common-8.1.0-py3-none-any.whl
| Download URL | velesdb_common-8.1.0-py3-none-any.whl |
|---|---|
| Size | 25.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc05810ac792ec92193dfe3921301431e4ca68bd997270b7c26202355aa526a5
|
|
BLAKE2b-256 checksum How to use checksums |
45c3e090771c6b886716fa885de6c48f02210ff7b5bb62002cbcf8c3510631df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for velesdb-common 8.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
