Installation

Install Kura and its dependencies for conversation analysis

Requirements

Kura requires Python 3.10 or higher.

Kura works on Linux, macOS, and Windows. We recommend using a virtual environment to avoid dependency conflicts.

Install with uv (recommended)

uv is a fast Python package installer. If you don’t have it installed:

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

Then install Kura:

uv pip install kura

Install with pip

You can install Kura using pip:

pip install kura

Install with conda

First, ensure pip is available in your conda environment:

conda install pip
pip install kura

Kura is not currently available as a conda package. You need to use pip within your conda environment.

Optional dependencies

Kura has several optional dependency groups for extended functionality:

Visualization

For rich terminal visualization with colors and formatting:

uv

uv pip install "kura[visualization]"

This installs the Rich library for enhanced output.

Parquet support

For saving checkpoints in Parquet format:

uv

uv pip install "kura[parquet]"

This installs PyArrow for efficient columnar data storage.

Embeddings

For local embedding models and additional providers:

uv

uv pip install "kura[embeddings]"

This installs:

• sentence-transformers for local embedding models
• cohere SDK for Cohere embeddings

Development dependencies

For contributing to Kura:

uv

uv pip install "kura[dev]"

This installs testing, linting, and type checking tools.

All optional dependencies

To install everything:

uv

uv pip install "kura[visualization,parquet,embeddings]"

Verify installation

Check that Kura is installed correctly:

kura --help

You should see output similar to:

Usage: kura [OPTIONS] COMMAND [ARGS]...

Kura - Conversation Analysis CLI

Options:
  --help  Show this message and exit.

Commands:
  analyze-checkpoints   Analyze existing JSONL checkpoints
  migrate-checkpoints   Migrate JSONL checkpoints to HuggingFace format
  start-app            Start the Kura web server

Development installation

If you want to contribute to Kura or modify the source code:

1. Clone the repository

   git clone https://github.com/567-labs/kura.git
   cd kura
   
2. Create a virtual environment

   uv

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
3. Install in development mode

   uv pip install -e ".[dev]"
   
4. Run tests

   pytest
   

See CONTRIBUTING.md for detailed development guidelines.

API keys setup

Kura uses LLM providers for summarization and clustering. You’ll need API keys from at least one provider:

OpenAI

export OPENAI_API_KEY="your-api-key-here"

Anthropic

export ANTHROPIC_API_KEY="your-api-key-here"

Google (Gemini)

export GOOGLE_API_KEY="your-api-key-here"

Never commit API keys to version control. Use environment variables or a .env file (and add it to .gitignore).

Using .env files

Create a .env file in your project directory:

.env

OPENAI_API_KEY=your-api-key-here
ANTHROPIC_API_KEY=your-api-key-here
GOOGLE_API_KEY=your-api-key-here

Kura will automatically load environment variables if you use a library like python-dotenv:

from dotenv import load_dotenv
load_dotenv()

# Now use Kura as normal

Troubleshooting

Import errors

If you see import errors for optional dependencies:

ImportError: Please install rich to use visualization features

Install the missing optional dependency:

uv pip install "kura[visualization]"

Version conflicts

If you encounter dependency conflicts, try creating a fresh virtual environment:

python -m venv fresh_env
source fresh_env/bin/activate
pip install kura

Platform-specific issues

macOS

If you encounter issues with HDBSCAN or UMAP on Apple Silicon:

# Install dependencies with conda first
conda install -c conda-forge hdbscan umap-learn
pip install kura

Windows

Some dependencies may require Visual C++ build tools. Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

Linux

Most Linux distributions work out of the box. For older systems, you may need:

sudo apt-get install python3-dev build-essential

Next steps

Quickstart tutorial

Process your first conversations in 5 minutes

Core concepts

Understand how Kura works