Skip to content

Development environment setup #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Paltidor87 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Development environment setup #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Cursor Cloud specific instructions

### Overview

LEANN is a vector database / RAG system with C++ native backends (HNSW via FAISS, DiskANN). It uses `uv` as the package manager and Python 3.11 (pinned in `.python-version`).

### Building from source

The C++ backends require `CC=gcc CXX=g++` environment variables on Ubuntu — the default Clang compiler cannot find the C++ standard library headers. You must also create a `libstdc++.so` symlink:

```bash
sudo ln -sf /usr/lib/gcc/x86_64-linux-gnu/13/libstdc++.so /usr/lib/x86_64-linux-gnu/libstdc++.so
```

MKL install (`libmkl-full-dev`) requires `DEBIAN_FRONTEND=noninteractive` to avoid an interactive prompt.

### Common commands

All commands use `uv run` to execute within the project venv. See `pyproject.toml` for full configuration.

| Task | Command |
|------|---------|
| Install all deps | `CC=gcc CXX=g++ uv sync --extra diskann --group lint --group test --group dev` |
| Lint | `uv run ruff check .` |
| Format check | `uv run ruff format --check .` |
| Run tests | `uv run pytest tests/ -v --tb=short -m "not integration"` |
| Run specific test | `uv run pytest tests/test_basic.py -v` |
| Hello-world demo | See README Quick Start or `python -m apps.document_rag --query "..."` |

### Known issues

- **DiskANN partition tests** (`test_diskann_partition.py`): Several tests fail with abort signals in the DiskANN C++ backend. These are pre-existing failures, not caused by environment setup.
- **Lint errors**: 29 pre-existing lint errors in demo scripts (`COMPREHENSIVE_GUIDE.py`, `ask_non_interactive.py`, `demo.py`, `demo_advanced.py`, `quick_search.py`). These are not in core library code.
- **Embedding model download**: The first run downloads `facebook/contriever` (~500MB). Subsequent runs use the cached model from `~/.cache/huggingface/`.

### System dependencies (already in VM snapshot)

`libomp-dev libboost-all-dev protobuf-compiler libzmq3-dev pkg-config libabsl-dev libaio-dev libprotobuf-dev libmkl-full-dev patchelf swig g++`
Loading