tkv 0.1.1

Temporal Key Value Store

TKV - Temporal Key-Value Store

A key-value store that supports timestamp-based queries, allowing you to retrieve values as they existed at specific points in time.

Features

• Temporal queries: Get the value for a key at the largest timestamp less than or equal to your query timestamp
• Multiple backends: SQLite as default, Redis and RocksDB as experimental alternatives
• REST API: FastAPI-based web interface
• CLI interface: Command-line tools for direct interaction

Project Layout

src/
├── service.py      # Core backend store implementations
├── api.py          # FastAPI web server
└── cli.py          # Command-line interface

The primary interest is service.py, which contains the main backend store implementation using SQLAlchemy/SQLite, as well as experimental alternatives using Redis and RocksDB. The CLI and API are implemented separately as distinct interfaces to the core functionality.

Installation

From PyPI (Recommended)

pip install tkv

Development with uv

First install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then clone and install:

git clone JackIsMyShephard/tkv.git
cd tkv
uv sync

Usage

CLI

# Store a value
tkv put mykey myvalue 1000

# Retrieve a value
tkv get mykey 1500

Web API

Start the server:

tkv-web run

Store data:

curl -X PUT http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"key":"mykey","value":"myvalue","timestamp":1000}'

Retrieve data:

curl "http://localhost:8000/mykey?timestamp=1500"

Development

uv sync --group dev
uv run pytest