Installation¶
This guide covers installing Karenina and verifying your setup.
Requirements¶
- Python 3.11+ (3.11 and 3.12 are tested)
- pip or uv (recommended)
- Supported platforms: Linux, macOS, Windows
Basic Installation¶
Karenina is not yet published to PyPI. Install from the Git repository:
This installs the core package with all required dependencies, including MCP client
support (mcp), LangChain integrations, Anthropic SDK, and the CLI.
Optional Dependencies¶
Karenina offers optional extras for specific use cases. Install them by appending the extra name in brackets:
# Example: install with embedding support
uv pip install "karenina[embeddings] @ git+https://github.com/biocypher/karenina.git"
# Multiple extras
uv pip install "karenina[embeddings,examples] @ git+https://github.com/biocypher/karenina.git"
| Extra | Packages | Purpose |
|---|---|---|
dev |
pytest, ruff, mypy, vulture, pre-commit, mkdocs, mkdocs-material, mkdocstrings, ipython | Development and testing tools |
search |
langchain-community, tavily-python | Web search integration for agentic verification |
examples |
jupyter, ipykernel | Running example notebooks |
embeddings |
sentence-transformers | Embedding similarity checks (pipeline stage 9) |
gepa |
gepa | GEPA prompt optimization integration |
MCP is a core dependency
The MCP client library (mcp>=1.25.0) is included in the base installation.
You do not need a separate extra to use MCP transport.
Verifying Installation¶
After installing, verify that everything works:
# Check CLI is available
karenina --version
# Check Python import
python -c "import karenina; print(karenina.__version__)"
Both commands should print the installed version (currently 0.1.0).
Development Setup¶
For contributors working on the Karenina codebase:
# Clone the repository
git clone https://github.com/biocypher/karenina.git
cd karenina
# Install in editable mode with dev dependencies
uv pip install -e ".[dev]"
# Run the test suite
uv run pytest tests/ -x -q
# Run linters
uv run ruff check src/ tests/
The -e flag installs in editable mode — changes to source files take effect
immediately without reinstalling.
API Key Configuration¶
Karenina calls LLM providers during verification. Set the API keys for the providers you plan to use:
# In your shell or a .env file in your working directory
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AI..."
Alternatively, use karenina init to generate a .env template with all
supported variables. See Workspace Initialization for full
details on the init command, or Configuration
for the full configuration hierarchy.
Troubleshooting¶
karenina command not found¶
The CLI entry point may not be on your PATH. Try:
If using pip install, ensure your Python scripts directory is on PATH.
Python version too old¶
Karenina requires Python 3.11+. Check your version:
If needed, install a newer Python with uv:
Import errors after installation¶
Reinstall to ensure all dependencies are resolved:
LLM provider errors¶
If verification fails with authentication errors, check that the correct API key
is set for your chosen provider. Karenina reads keys from environment variables
and .env files via python-dotenv.
Next Steps¶
- Quick Start — End-to-end walkthrough: create a benchmark, run verification, inspect results
- Configuration — Set up presets, environment variables, and workspace
- Core Concepts — Understand checkpoints, templates, and rubrics
- Creating Benchmarks — Build your first benchmark