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.

Prerequisites

• Python 3.12+

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 the repository and sync dependencies:

git clone https://github.com/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

Running Commands

# CLI commands
uv run tkv put mykey myvalue 1000
uv run tkv get mykey 1500

# Web server
uv run tkv-web run

Testing

uv run pytest