Install

Install ToraDB from PyPI or build from source

ToraDB is published on PyPI as the toradb package (prebuilt wheels for macOS, Linux, and Windows). Use pip for normal use; build from source only when you are developing ToraDB itself.

Install from PyPI

1. Create a virtual environment (recommended)

   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install --upgrade pip
   
2. Install ToraDB

   pip install toradb
   

   Optional extras:

   pip install "toradb[embeddings]"   # sentence-transformers
   pip install "toradb[openai]"       # OpenAI embeddings client
   
3. Verify installation

   python -c "import toradb; print('toradb import ok')"
   toradb smoke
   

Build from source

Use this path when you need unreleased changes or you are contributing to the Rust/Python codebase.

Prerequisites

• Rust stable toolchain (rustup, cargo)
• Python 3.8+
• pip
• maturin (for building the Python extension)

The repo pins Rust to stable via rust-toolchain.toml.

1. Clone the repository

   git clone https://github.com/sophatvathana/toradb.git toradb
   cd toradb
   
2. Build the Rust workspace

   cargo build
   
3. Create a Python virtual environment

   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install maturin
   
4. Install the ToraDB Python package

   From the repo root:

   maturin develop
   
5. Verify installation

   python -c "import toradb; print('toradb import ok')"
   toradb smoke
   

Run tests

Rust tests (source tree only):

cargo test

Python smoke tests:

pytest tests/python_smoke.py -q

Optional benchmark

cargo bench -p toradb-storage --bench segment_read

Troubleshooting

• If pip install toradb fails on an unsupported platform, try build from source on that machine.
• If maturin develop fails, confirm the virtual environment is activated.
• If Python cannot import toradb after a source build, rerun maturin develop.
• If the toradb command is not found, ensure the venv bin directory is on your PATH (activation usually handles this).