Skip to main content

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)

Source distribution for tidevec 0.2.1
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)

Table of built distributions (wheels) for tidevec 0.2.1
File Interpreter ABI Platform Actions
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.

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