tidevec
Python SDK for TideVec — the world's first temporally-aware, causally-indexed vector database.
Install
pip install tidevec
Quick Start
import os
from tidevec import TideVec, HalfLife
# Auth: pass api_key or set TIDEVEC_API_KEY env var
db = TideVec("localhost:6399", api_key=os.environ.get("TIDEVEC_API_KEY", ""))
db.create_collection(
"docs",
dim=768,
half_life_ms=HalfLife.ONE_WEEK,
temporal_blend=0.3,
)
db.upsert("docs", [
{"id": "doc_001", "embedding": [...], "payload": {"source": "wiki"}},
])
results = db.search("docs", query_vector=[...], top_k=10)
for hit in results:
print(f"{hit.id} score={hit.score:.4f} temporal={hit.temporal_score:.3f}")
Authentication
Production TideVec requires an API key on all /v1/* routes:
# Option 1: environment variable (recommended)
export TIDEVEC_API_KEY="your-secret-key"
db = TideVec("localhost:6399") # reads env automatically
# Option 2: explicit
db = TideVec("localhost:6399", api_key="your-secret-key")
# Option 3: TLS
db = TideVec("localhost:6399", api_key="...", tls=True)
Errors:
from tidevec import UnauthorizedError, ForbiddenError, RateLimitError
try:
db.search("docs", query)
except UnauthorizedError: # 401 — missing/invalid API key
...
except ForbiddenError: # 403 — tenant or SSRF blocked
...
except RateLimitError: # 429 — auto-retried up to 3 times
...
DriftBridge — Model Migration
Upgrade embedding models without downtime:
import time
db.start_drift(
"docs",
reembed_url="https://embed.example.com/v1/embed",
)
while True:
status = db.drift_status("docs")
print(f"{status.phase}: {status.pct_complete:.0f}%")
if status.phase in ("COMPLETE", "IDLE", "FAILED"):
break
time.sleep(5)
# Abort if needed
db.abort_drift("docs")
Backups
snapshot = db.trigger_backup() # "tidevec_1712345678.tar.gz"
backups = db.list_backups() # list all snapshots
Observability
# Prometheus metrics
print(db.metrics())
# Per-query trace (OTel-compatible)
results = db.search("docs", query, include_trace=True)
if results.trace:
print(results.trace["strategy"], results.trace["latency_ms"])
Async
import asyncio
from tidevec import AsyncTideVec
async def main():
async with AsyncTideVec("localhost:6399", api_key="...") as db:
await db.upsert("docs", [{"id": "v1", "embedding": [...]}])
results = await db.search("docs", query_vector=[...], top_k=5)
asyncio.run(main())
API Reference
| Method | Description |
|---|---|
health() |
Server health check (no auth) |
info() |
Server feature manifest |
metrics() |
Prometheus text metrics |
create_collection(name, dim, ...) |
Create collection |
list_collections() |
List all collections |
get_collection(name) |
Collection stats + backend type |
drop_collection(name) |
Delete collection |
upsert(collection, vectors) |
Insert/update vectors |
delete(collection, ids) |
Delete vectors by ID |
search(collection, query, ...) |
ANN search with temporal scoring |
add_edges(collection, edges) |
Add causal graph edges |
set_temporal(name, half_life_ms, ...) |
Update decay config |
start_drift(collection, reembed_url) |
Start model migration |
drift_status(collection) |
Poll migration progress |
abort_drift(collection) |
Cancel migration |
trigger_backup() |
Manual snapshot |
list_backups() |
List snapshots |
list_backup_manifests() |
PITR manifest history |
restore_backup(snapshot) |
Point-in-time restore |
HalfLife presets
from tidevec import HalfLife
HalfLife.ONE_HOUR # agent session memory
HalfLife.ONE_DAY # news / feeds
HalfLife.ONE_WEEK # support tickets
HalfLife.ONE_MONTH # documents (default)
HalfLife.ONE_YEAR # long-term knowledge base
Metadata
Release files for tidevec 0.2.1
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 |
|---|---|---|---|---|
| tidevec-0.2.1.tar.gz | 14.5 kB | Without provenance | Details for tidevec-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tidevec-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for tidevec-0.2.1-py3-none-any.whl |
Total release size: 29.8 kB
Release files / tidevec-0.2.1.tar.gz
| Download URL | tidevec-0.2.1.tar.gz |
|---|---|
| Size | 14.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dcb993599bccf132671eee1519ec37af218e91b41f33f2f69d4d34e5784139e1
|
|
BLAKE2b-256 checksum How to use checksums |
d61a2df0127bc09dff95fd9a5facaae7ec486d8aefaaab7898e867d81f964c42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / tidevec-0.2.1-py3-none-any.whl
| Download URL | tidevec-0.2.1-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
064be2dd1e7764d533384ed1e6e5ef6f7bdd8bf322b0f7899b60c1074e35cc37
|
|
BLAKE2b-256 checksum How to use checksums |
7e3503978d29430525fd7e10b1a0df58d5f98a2a81676009cfb0d8907ebfd8ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for tidevec 0.2.1
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.