### Development Setup - Plugin

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Navigates to the plugin directory, installs dependencies, and starts the development server.

```bash
# Plugin
cd ../plugin
pnpm install
pnpm run dev
```

--------------------------------

### Start Ollama server

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Start the Ollama server manually.

```bash
ollama serve
```

--------------------------------

### Install Backend

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Instructions for installing the obsidianrag backend using pip or pipx.

```bash
# Using pip
pip3 install obsidianrag

# Or using pipx (recommended)
brew install pipx
pipx install obsidianrag
```

--------------------------------

### Install ObsidianRAG Backend with Pipx

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/installation.md

Recommended command to install the Python backend package using pipx for isolated installation.

```bash
pipx install obsidianrag
```

--------------------------------

### Check backend installation

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Verify if the obsidianrag backend is installed and install it if necessary.

```bash
pip show obsidianrag
```

```bash
pip install obsidianrag
# or
pipx install obsidianrag
```

--------------------------------

### Install Ollama on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to install Ollama, start the service, and download a model on Linux.

```bash
# Quick installation
curl -fsSL https://ollama.com/install.sh | sh

# Start service
sudo systemctl start ollama
# or manually
ullama serve

# Download model
ullama pull gemma3
```

--------------------------------

### Find Backend Executable Path (Windows)

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/installation.md

Command to find the installation path of the obsidianrag executable on Windows.

```bash
where obsidianrag
```

--------------------------------

### Verify Python Version

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/installation.md

Command to check if the installed Python version meets the requirement.

```bash
python --version
```

--------------------------------

### Install Backend on Windows

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to install the obsidianrag backend using pip on Windows.

```powershell
# Open PowerShell as normal user (not admin)

# Verify Python
python --version  # Should be 3.11+

# Install backend
pip install obsidianrag

# Verify installation
pip show obsidianrag
```

--------------------------------

### Backend Development Setup

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Steps to set up the Python backend development environment, including cloning the repository, installing dependencies with uv, and running tests.

```bash
# Clone the repo
git clone https://github.com/Vasallo94/ObsidianRAG.git
cd ObsidianRAG

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup backend
cd backend
uv sync

# Run tests
uv run pytest

# Start development server
uv run obsidianrag serve --vault /path/to/test/vault --reload

```

--------------------------------

### Rebuild database with server

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Rebuild the database by starting the server with the --rebuild flag.

```bash
# Stop server first
obsidianrag serve --vault /path/to/vault --rebuild
```

--------------------------------

### Install Backend on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to install the obsidianrag backend using pip on Linux.

```bash
# Verify Python
python3 --version  # Should be 3.11+

# Install backend
pip3 install obsidianrag
# or with user flag if you don't have permissions
pip3 install --user obsidianrag

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

# Verify
obsidianrag --help
```

--------------------------------

### Install Plugin

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Steps to install the ObsidianRAG plugin by copying or symlinking files into the Obsidian vault.

```bash
# Navigate to vault
cd ~/Documents/ObsidianVault

# Create plugin directory
mkdir -p .obsidian/plugins/obsidianrag

# Copy files from release
# Or symlink for development:
ln -s /path/to/ObsidianRAG/plugin .obsidian/plugins/obsidianrag
```

--------------------------------

### Find Backend Executable Path (Linux/macOS)

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/installation.md

Command to find the installation path of the obsidianrag executable on Linux or macOS.

```bash
which obsidianrag
```

--------------------------------

### Pull an LLM Model with Ollama

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/installation.md

Command to download a language model for use with Ollama.

```bash
ollama pull gemma3
```

--------------------------------

### Verify Python Backend Installation

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/usage.md

Command to verify the installation of the Python backend.

```bash
obsidianrag --version
```

--------------------------------

### Manual Server Start on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Command to manually start the ObsidianRAG server on Linux if auto-start fails.

```bash
# If auto-start fails, start manually
obsidianrag serve --vault ~/Documents/ObsidianVault --port 8000

# Check logs for errors
```

--------------------------------

### Install Python Backend

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/user-guide/usage.md

Command to install the companion Python backend for the ObsidianRAG plugin.

```bash
pip install obsidianrag
```

--------------------------------

### Install Plugin on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Steps to manually install the ObsidianRAG plugin by downloading release files from GitHub on Linux.

```bash
# Navigate to vault
cd ~/Documents/ObsidianVault  # or wherever your vault is

# Create directory
mkdir -p .obsidian/plugins/obsidianrag

# Download release files from GitHub
cd .obsidian/plugins/obsidianrag
wget https://github.com/Vasallo94/ObsidianRAG/releases/download/v1.0.0/main.js
wget https://github.com/Vasallo94/ObsidianRAG/releases/download/v1.0.0/manifest.json
wget https://github.com/Vasallo94/ObsidianRAG/releases/download/v1.0.0/styles.css
```

--------------------------------

### Installation with uv

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Install the obsidianrag package using uv for faster installation.

```bash
uv tool install obsidianrag
```

--------------------------------

### Adjust retrieval settings

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Example of adjusting retrieval settings to retrieve more documents.

```bash
obsidianrag serve --vault /path/to/vault \
  --retrieval-k 15  # Retrieve more documents
```

--------------------------------

### Download multilingual model

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Download the qwen2.5 model, which is excellent for Spanish/English.

```bash
ollama pull qwen2.5  # Excellent for Spanish/English
```

--------------------------------

### Popular model downloads

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

List of popular models with their approximate sizes and use cases.

```bash
ollama pull gemma3      # 5GB, balanced
```

```bash
ollama pull qwen2.5     # 4.4GB, great for Spanish
```

```bash
ollama pull llama3.2    # 2GB, smaller/faster
```

```bash
ollama pull mistral     # 4GB, alternative
```

--------------------------------

### Install Plugin Manually on Windows

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Steps to manually install the ObsidianRAG plugin by copying release files to the Obsidian plugins directory.

```powershell
# Navigate to your Obsidian vault
cd "C:\Users\YourUser\Documents\MyVault"

# Create plugin directory
mkdir -p .obsidian\plugins\obsidianrag

# Copy release files
# (Download from GitHub release: main.js, manifest.json, styles.css)
# And copy to .obsidian\plugins\obsidianrag\
```

--------------------------------

### Example Commands for Migration Steps

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/developer-guide/langchain-classic-migration.md

Commands to run after completing migration steps to verify the changes.

```bash
uv run pytest
uv run ruff check obsidianrag tests
uv run pip-audit
```

--------------------------------

### Docker Quick Start

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Starts the ObsidianRAG service using Docker Compose. Assumes Ollama is running on the host.

```bash
OBSIDIAN_VAULT_PATH=/path/to/your/vault docker compose up
```

--------------------------------

### Install and Configure Ollama on Windows

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to download an LLM model and verify Ollama is running on Windows.

```powershell
# Download LLM model
ullama pull gemma3

# Verify Ollama is running
# Should open automatically after installation
# Verify with:
curl http://localhost:11434/api/tags
```

--------------------------------

### List available Ollama models

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

List all models currently downloaded and available via Ollama.

```bash
ollama list
```

--------------------------------

### Plugin Development Setup

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Steps to set up the TypeScript plugin development environment, including installing dependencies with pnpm, building, testing, and linking to an Obsidian vault.

```bash
cd plugin

# Install dependencies
pnpm install

# Development build (with watch)
pnpm run dev

# Production build
pnpm run build

# Run tests
pnpm test

# Link to Obsidian vault for testing
ln -s $(pwd) /path/to/vault/.obsidian/plugins/obsidianrag

```

--------------------------------

### Start Server (API)

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Programmatically start the RAG server using Python.

```python
from obsidianrag.api.server import run_server

run_server(vault_path="/path/to/vault", host="0.0.0.0", port=8000)
```

--------------------------------

### Development Setup - Backend

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Clones the repository, navigates to the backend directory, synchronizes dependencies, and runs tests.

```bash
git clone https://github.com/Vasallo94/ObsidianRAG.git
cd ObsidianRAG

# Backend
cd backend
uv sync
uv run pytest
```

--------------------------------

### Developer Installation

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Clone the repository and install dependencies for development.

```bash
git clone https://github.com/Vasallo94/ObsidianRAG.git
cd ObsidianRAG/backend
uv sync
```

--------------------------------

### Install with dev dependencies

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to install project dependencies, including development ones.

```bash
uv sync
```

--------------------------------

### Development Setup

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

Steps to set up the development environment for the ObsidianRAG plugin.

```bash
git clone https://github.com/Vasallo94/ObsidianRAG.git
cd ObsidianRAG/plugin

# Install dependencies
pnpm install

```

--------------------------------

### Troubleshooting: Install and Serve

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Commands to install obsidianrag and serve it locally for troubleshooting.

```bash
uv tool install obsidianrag
obsidianrag serve --vault /path/to/vault
```

--------------------------------

### Serve with LM Studio

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Start the RAG server using LM Studio as the model provider.

```bash
obsidianrag serve --vault ~/notes --provider lmstudio --model my-model
```

--------------------------------

### Install backend and Ollama

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

Prerequisites for using the plugin include installing the backend and Ollama, and downloading an LLM model.

```bash
pip install obsidianrag

# macOS
brew install ollama

# Download LLM model
ollama pull gemma3
```

--------------------------------

### Troubleshooting: Verify backend installation

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

If the server shows 'Offline', verify the backend installation using pip.

```bash
# Verify installed
pip show obsidianrag

# If not installed
pip install obsidianrag
```

--------------------------------

### Serve with custom OpenAI-compatible server

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Start the RAG server connecting to a custom OpenAI-compatible server.

```bash
obsidianrag serve --vault ~/notes --provider custom \
  --base-url http://my-server:8080/v1 \
  --api-format chat-completions \
  --api-key my-key
```

--------------------------------

### Troubleshooting: Start server manually

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

If the server shows 'Offline', try starting it manually, specifying the vault path.

```bash
obsidianrag serve --vault /path/to/vault
```

--------------------------------

### Docker Compose Up

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Commands to start ObsidianRAG using Docker Compose.

```bash
# Pull the pre-built image and start
OBSIDIAN_VAULT_PATH=/path/to/your/vault docker compose up

# Or build locally
OBSIDIAN_VAULT_PATH=/path/to/your/vault docker compose up --build
```

--------------------------------

### Check Ollama Service Status on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to check the status of the Ollama service and start it if it's not running.

```bash
# Check Ollama status
systemctl status ollama

# If not running
sudo systemctl start ollama
# or
ullama serve
```

--------------------------------

### Set Ollama base URL environment variable

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Set the OLLAMA_BASE_URL environment variable if using a custom Ollama setup.

```bash
export OLLAMA_BASE_URL=http://your-custom-url:port
```

--------------------------------

### Python Code Style Example

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Example of a Python function with type hints and Google-style docstrings, adhering to the project's code style.

```python
def retrieve_documents(query: str, k: int = 10) -> list[Document]:
    """Retrieve relevant documents for a query.

    Args:
        query: The search query text.
        k: Maximum number of documents to return.

    Returns:
        List of Document objects sorted by relevance.
    """
    ...

```

--------------------------------

### Serve with LM Studio

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Starts the ObsidianRAG server using LM Studio as the LLM provider, specifying a model.

```bash
obsidianrag serve --vault /path/to/vault --provider lmstudio --model my-model
```

--------------------------------

### Run Server on Occupied Port (Windows Edge Case)

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Demonstrates how to simulate an occupied port and test the plugin's ability to switch to a different port.

```powershell
# In PowerShell, start a server on port 8000
python -m http.server 8000

# Open Obsidian
# Settings → ObsidianRAG → Server Port → change to `8001`
# Stop → Start Server
# Verify it works on the new port
```

--------------------------------

### Manually delete database

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Manually delete the database directory.

```bash
rm -rf /path/to/vault/.obsidianrag/db/
# Then restart server
```

--------------------------------

### Rebuild database via API

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Trigger a database rebuild using the ObsidianRAG API.

```bash
curl -X POST http://localhost:8000/rebuild_db
```

--------------------------------

### Stats Endpoint Response

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Example JSON response body for the GET /stats API endpoint.

```json
{
  "total_notes": 150,
  "total_chunks": 450,
  "total_words": 25000,
  "total_chars": 150000,
  "avg_words_per_chunk": 55,
  "folders": 12,
  "internal_links": 350,
  "vault_path": "MyVault"
}
```

--------------------------------

### Check system resources

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Commands to check system resource usage (CPU/RAM) on macOS/Linux.

```bash
# macOS/Linux
top

# Look for high CPU/RAM usage
```

--------------------------------

### Serve with Custom OpenAI-compatible server

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Starts the ObsidianRAG server using a custom OpenAI-compatible endpoint.

```bash
obsidianrag serve --vault /path/to/vault --provider custom \
  --base-url http://my-server:8080/v1 \
  --api-format chat-completions \
  --api-key my-key
```

--------------------------------

### Health Endpoint Response

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Example JSON response body for the GET /health API endpoint.

```json
{
  "status": "ok",
  "model": "gemma3",
  "embedding_provider": "huggingface",
  "embedding_model": "sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
  "db_ready": true
}
```

--------------------------------

### Check ChromaDB collection count

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Python code to connect to ChromaDB and get the total number of documents in the 'obsidianrag' collection.

```python
import chromadb

client = chromadb.PersistentClient(path="/path/to/vault/.obsidianrag/db")
collection = client.get_collection("obsidianrag")
print(f"Total documents: {collection.count()}")
```

--------------------------------

### Environment Variables Configuration

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Example environment variables for configuring the RAG system.

```env
# LLM
LLM_MODEL=gemma3
OLLAMA_BASE_URL=http://localhost:11434

# Embeddings
EMBEDDING_PROVIDER=huggingface  # or 'ollama'
EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-mpnet-base-v2
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

# Reranker
USE_RERANKER=true
RERANKER_MODEL=BAAI/bge-reranker-v2-m3
RERANKER_TOP_N=6

# Retrieval
CHUNK_SIZE=1500
CHUNK_OVERLAP=300
RETRIEVAL_K=12
BM25_K=5
BM25_WEIGHT=0.4
VECTOR_WEIGHT=0.6

# API
API_HOST=127.0.0.1
API_PORT=8000
CORS_ORIGINS=["http://localhost:3000", "app://obsidian.md"]

```

--------------------------------

### TypeScript Code Style Example

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Example of a TypeScript function demonstrating the project's code style with type annotations.

```typescript
async function askQuestion(question: string): Promise<AskResponse> {
  // Implementation
}

```

--------------------------------

### Check API manually

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Curl commands to perform health checks, ask questions, and get stats from the ObsidianRAG API.

```bash
# Health check
curl http://localhost:8000/health

# Ask question
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"text": "test question"}'

# Get stats
curl http://localhost:8000/stats
```

--------------------------------

### Enable debug logs for backend

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Command to enable debug logging for the ObsidianRAG backend server.

```bash
export LOG_LEVEL=DEBUG
obsidianrag serve --vault /path/to/vault
```

--------------------------------

### Check vault permissions

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Check read permissions for the vault directory.

```bash
# macOS/Linux
ls -la /path/to/vault
```

--------------------------------

### Serve with custom port and model

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Start the RAG server with a custom port and a specified language model.

```bash
obsidianrag serve --vault ~/notes --port 9000 --model qwen2.5
```

--------------------------------

### Give Permissions to Obsidian AppImage on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Command to make the Obsidian AppImage executable.

```bash
chmod +x Obsidian-*.AppImage
./Obsidian-*.AppImage
```

--------------------------------

### Reduce retrieval complexity

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Configuration options in `~/.config/obsidianrag/config.toml` to reduce retrieval complexity and improve performance.

```toml
use_reranker = false      # Skip reranking (faster)
retrieval_k = 8           # Fewer documents
```

--------------------------------

### Check vault markdown files

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Verify that markdown files exist in the specified vault path.

```bash
ls /path/to/vault/*.md
```

--------------------------------

### Verify Ollama accessibility

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Check if Ollama is accessible by querying its API for tags.

```bash
curl http://localhost:11434/api/tags
```

--------------------------------

### Backend Commands

Source: https://github.com/vasallo94/obsidianrag/blob/main/CLAUDE.md

Commands for managing the Python backend, including dependency installation, testing, linting, formatting, type checking, and serving.

```bash
cd backend
uv sync                    # install deps
uv run pytest              # run tests (89 tests)
uv run pytest --cov        # with coverage
uv run ruff check .        # lint
uv run ruff format .       # format
uv run mypy obsidianrag    # type check
uv run obsidianrag serve --vault /path/to/vault  # run server
```

--------------------------------

### Verify server is running

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Check if the obsidianrag server is running by sending a health check request.

```bash
curl http://localhost:8000/health
```

--------------------------------

### Check port conflicts

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Check if the default port (8000) is being used by another application.

```bash
# macOS/Linux
lsof -i :8000
```

```bash
# Windows
netstat -ano | findstr :8000
```

--------------------------------

### Pull a smaller/faster model

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TROUBLESHOOTING.md

Command to pull a smaller and faster model like llama3.2 using Ollama.

```bash
ollama pull llama3.2  # 2GB, much faster
```

--------------------------------

### Ask Endpoint Request

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Example JSON request body for the POST /ask API endpoint.

```json
{
  "text": "What notes do I have about Python?",
  "session_id": "optional-session-id"
}
```

--------------------------------

### Ask Endpoint Response

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Example JSON response body for the POST /ask API endpoint.

```json
{
  "question": "What notes do I have about Python?",
  "result": "According to your notes...",
  "sources": [
    {
      "source": "Programming/Python.md",
      "score": 0.92,
      "retrieval_type": "retrieved"
    }
  ],
  "text_blocks": ["..."],
  "process_time": 2.5,
  "session_id": "abc123"
}
```

--------------------------------

### Plugin Commands

Source: https://github.com/vasallo94/obsidianrag/blob/main/CLAUDE.md

Commands for managing the TypeScript Obsidian plugin, including dependency installation, building, development mode, testing, and linting.

```bash
cd plugin
pnpm install               # install deps
pnpm run build             # compile (tsc + esbuild)
pnpm run dev               # watch mode
pnpm test                  # jest tests
pnpm run lint              # eslint
```

--------------------------------

### Check Port Usage on Linux

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to check if a specific port is in use and to kill the process if necessary.

```bash
# Check if port 8000 is in use
lsof -i :8000

# Kill process if needed
lsof -ti:8000 | xargs kill -9
```

--------------------------------

### Check and Kill Port Usage

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/TESTING_GUIDE.md

Commands to check if port 8000 is in use and to kill the process if necessary.

```bash
# Check port usage
lsof -i :8000

# Kill if needed
lsof -ti:8000 | xargs kill -9
```

--------------------------------

### Programmatic Configuration - Manual

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Manually configure settings using the Settings class.

```python
from obsidianrag.config import Settings, configure_from_vault

# Auto-configure from vault
configure_from_vault("/path/to/vault")

# Manual configuration
settings = Settings(
    obsidian_path="/path/to/vault",
    llm_model="qwen2.5",
    use_reranker=True,
    retrieval_k=15
)
```

--------------------------------

### Release Version Bump and Build

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

Commands for version bumping and building the plugin for release.

```bash
# Version bump
npm version patch  # or minor, major

# Build
pnpm run build
```

--------------------------------

### Troubleshooting: Download alternative model

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

If responses are in the wrong language, try downloading and configuring a different Ollama model.

```bash
ollama pull qwen2.5  # Better for Spanish

Then in Settings → ObsidianRAG → LLM Model → select `qwen2.5`
```

--------------------------------

### Ask Question (CLI)

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Ask a question to the RAG system via the command-line interface.

```bash
obsidianrag ask --vault /path/to/vault "What notes do I have about Python?"
```

--------------------------------

### Run tests with coverage

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to run tests with code coverage reporting.

```bash
uv run pytest --cov=obsidianrag --cov-report=html
```

--------------------------------

### Programmatic Configuration - Auto-configure

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Automatically configure settings by pointing to the Obsidian vault path.

```python
from obsidianrag.config import Settings, configure_from_vault

# Auto-configure from vault
configure_from_vault("/path/to/vault")
```

--------------------------------

### Development and Production Builds

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

Commands for building the plugin for development with watch mode and for production.

```bash
pnpm run dev

pnpm run build
```

--------------------------------

### Format code

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to format the project code using Ruff.

```bash
uv run ruff format obsidianrag/ tests/
```

--------------------------------

### Run all tests

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to execute all tests using pytest.

```bash
uv run pytest
```

--------------------------------

### Submitting a Pull Request - Formatting Code

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Commands to format and lint backend code using ruff and plugin code using pnpm.

```bash
# Backend
uv run ruff format obsidianrag/ tests/
uv run ruff check obsidianrag/ tests/ --fix

# Plugin
pnpm run lint

```

--------------------------------

### Troubleshooting: Check Ollama status

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

If encountering 'Ollama not running' errors, ensure Ollama is running and accessible.

```bash
# Make sure Ollama is running
ollama serve

# Verify
curl http://localhost:11434/api/tags

# Download model if needed
ollama pull gemma3
```

--------------------------------

### Docker Command

Source: https://github.com/vasallo94/obsidianrag/blob/main/CLAUDE.md

Command to run the backend and plugin using Docker Compose.

```bash
OBSIDIAN_VAULT_PATH=/path/to/vault docker compose up
```

--------------------------------

### CLI Reference

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Command-line interface options for serving the ObsidianRAG backend.

```bash
obsidianrag serve [OPTIONS]

Options:
  --vault, -v       Path to Obsidian vault (required)
  --host, -h        Host to bind to (default: 127.0.0.1)
  --port, -p        Server port (default: 8000)
  --provider        LLM provider: ollama, lmstudio, custom
  --model, -m       LLM model name (default: gemma3)
  --base-url        Base URL for the selected provider
  --api-format      API format: ollama or chat-completions
  --api-key         API key for providers that require one
  --reranker        Enable reranker (default)
  --no-reranker     Disable reranker
  --reload, -r      Enable auto-reload for development
```

--------------------------------

### Clone repository

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to clone the ObsidianRAG repository.

```bash
git clone https://github.com/Vasallo94/ObsidianRAG.git
```

--------------------------------

### Testing Commands

Source: https://github.com/vasallo94/obsidianrag/blob/main/plugin/README.md

Commands for running unit tests, including watch mode and coverage reports.

```bash
# Run unit tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage
```

--------------------------------

### Testing Commands

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Commands to run tests for both the backend and the plugin components of the project.

```bash
# Backend
cd backend
uv run pytest

# Plugin
cd plugin
pnpm test
```

--------------------------------

### Plugin Tests Execution

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Commands for running plugin tests using pnpm, including running all tests, with coverage, and in watch mode.

```bash
cd plugin

# Run all tests
pnpm test

# Run with coverage
pnpm test -- --coverage

# Watch mode
pnpm test -- --watch

```

--------------------------------

### Lint code

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to lint the project code using Ruff.

```bash
uv run ruff check obsidianrag/ tests/
```

--------------------------------

### System Overview Diagram

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Architecture diagram illustrating the interaction between Obsidian, ObsidianRAG Plugin, and the Backend.

```text
+-------------------------------------------+
|             Obsidian                       |
|  +-------------------------------------+  |
|  |   ObsidianRAG Plugin (TypeScript)   |  |
|  |                                     |  |
|  |  - Chat UI                          |  |
|  |  - Server Manager                   |  |
|  |  - Provider Settings                |  |
|  +----------------+--------------------+  |
+-------------------|------------------------+
                    | HTTP (localhost:8000)
                    v
+-------------------------------------------+
|   Backend (Python / FastAPI)              |
|                                           |
|   LLM Provider Layer                      |
|   (Ollama | LM Studio | Custom)          |
|        |                                  |
|   LangGraph Agent                         |
|   Retrieve -> Rerank -> Generate          |
|        |                                  |
|   ChromaDB (Vector Store)                 |
+-------------------------------------------+
```

--------------------------------

### Core Components Directory Structure

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Directory structure of the ObsidianRAG backend project.

```text
obsidianrag/
├── api/
│   └── server.py         # FastAPI server
├── cli/
│   └── main.py           # CLI commands (Typer)
├── core/
│   ├── qa_agent.py       # LangGraph RAG agent
│   ├── qa_service.py     # Hybrid retriever + reranker
│   ├── db_service.py     # ChromaDB + indexing
│   └── metadata_tracker.py  # Change detection
├── config/
│   └── __init__.py       # Pydantic settings
└── utils/
    └── logger.py         # Logging
```

--------------------------------

### Index Vault - Incremental

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Perform an incremental index of the vault, only processing changed notes.

```bash
obsidianrag index --vault /path/to/vault
```

--------------------------------

### Run unit tests only

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Command to execute only unit tests, excluding integration and slow tests.

```bash
uv run pytest -m "not integration and not slow"
```

--------------------------------

### Backend Tests Execution

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Various commands for running backend tests using pytest, including running all tests, specific files, with coverage, and skipping slow tests.

```bash
cd backend

# Run all tests
uv run pytest

# Run specific file
uv run pytest tests/test_cli.py -v

# Run with coverage
uv run pytest --cov=obsidianrag --cov-report=term-missing

# Skip slow tests
uv run pytest -m "not slow"

```

--------------------------------

### Index Vault - Full rebuild

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Force a full rebuild of the RAG database for the specified vault.

```bash
obsidianrag index --vault /path/to/vault --force
```

--------------------------------

### Repository Structure

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Overview of the directory structure for the ObsidianRAG project, separating backend, plugin, and documentation.

```bash
ObsidianRAG/
├── backend/          # Python backend (PyPI package)
│   ├── obsidianrag/  # Main package
│   └── tests/        # Python tests
├── plugin/           # Obsidian plugin (TypeScript)
│   ├── src/          # Source code
│   └── tests/        # Plugin tests
└── docs/             # Documentation

```

--------------------------------

### Troubleshooting: Ollama Check

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Commands to check if Ollama is running and accessible.

```bash
ollama serve
curl http://localhost:11434/api/tags
```

--------------------------------

### Submitting a Pull Request - Testing

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Commands to run backend and plugin tests as part of the pull request submission process.

```bash
# Backend
cd backend && uv run pytest

# Plugin
cd plugin && pnpm test

```

--------------------------------

### Creating a Feature Branch

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/CONTRIBUTING.md

Commands to create a new feature branch based on the development branch (`v3-plugin`) for making changes.

```bash
# Start from development branch
git checkout v3-plugin
git pull origin v3-plugin

# Create feature branch
git checkout -b feature/my-awesome-feature

```

--------------------------------

### Git Workflow for Contributions

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Standard Git commands for forking the repository, creating a feature branch, committing changes, and pushing for a Pull Request.

```git
git checkout -b feature/your-feature
git commit -m 'feat: add your feature'
git push origin feature/your-feature
```

--------------------------------

### Current langchain_classic Imports

Source: https://github.com/vasallo94/obsidianrag/blob/main/docs/developer-guide/langchain-classic-migration.md

The active imports from langchain_classic in the current implementation.

```python
from langchain_classic.retrievers import ContextualCompressionRetriever, EnsembleRetriever
from langchain_classic.retrievers.document_compressors import CrossEncoderReranker
```

--------------------------------

### Environment Variables

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Key environment variables for configuring ObsidianRAG backend settings.

```bash
OBSIDIANRAG_OBSIDIAN_PATH=/path/to/vault
OBSIDIANRAG_LLM_PROVIDER=ollama
OBSIDIANRAG_LLM_MODEL=gemma3
OBSIDIANRAG_OLLAMA_BASE_URL=http://localhost:11434
```

--------------------------------

### Project Structure

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

The directory structure of the ObsidianRAG project, detailing the backend (Python) and plugin (TypeScript) components, along with configuration and documentation.

```tree
ObsidianRAG/
|-- backend/                  Python backend (PyPI package)
|   |-- obsidianrag/
|   |   |-- api/              FastAPI server
|   |   |-- cli/              CLI commands
|   |   |-- core/             RAG logic
|   |   |   |-- qa_agent.py       LangGraph agent
|   |   |   |-- qa_service.py     Retrieval and reranking
|   |   |   |-- db_service.py     ChromaDB management
|   |   |   |-- llm_provider.py   Multi-provider LLM support
|   |   |   `-- metadata_tracker.py  Incremental indexing
|   |   `-- config.py         Pydantic settings
|   |-- tests/
|   |-- Dockerfile            Multi-stage build
|   `-- pyproject.toml
|
|-- plugin/                   Obsidian plugin (TypeScript)
|   |-- src/main.ts           Plugin entry point
|   |-- tests/                Unit tests
|   `-- styles.css            UI styles
|
|-- docker-compose.yml        Container orchestration
|-- .env.example              Configuration template
`-- docs/                     Documentation

```

--------------------------------

### RAG Pipeline - LangGraph Agent

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Description of the LangGraph Agent component in the RAG pipeline.

```text
LangGraph Agent (`qa_agent.py`):
```

--------------------------------

### RAG Pipeline Diagram

Source: https://github.com/vasallo94/obsidianrag/blob/main/README.md

Mermaid diagram illustrating the Retrieval-Augmented Generation (RAG) pipeline.

```mermaid
flowchart LR
    Q[Question] --> R[Retrieve]
    R --> H[Hybrid Search<br/>Vector + BM25]
    H --> RR[Reranker<br/>CrossEncoder]
    RR --> G[GraphRAG<br/>Link Expansion]
    G --> C[Context]
    C --> L[LLM Generate]
    L --> A[Answer]
```

--------------------------------

### Check Status

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Check the current status of the RAG service for the specified vault.

```bash
obsidianrag status --vault /path/to/vault
```

--------------------------------

### Two-node graph definition

Source: https://github.com/vasallo94/obsidianrag/blob/main/backend/README.md

Defines a simple two-node graph for retrieval and generation using StateGraph.

```python
graph = StateGraph(AgentState)
graph.add_node("retrieve", retrieve_node)
graph.add_node("generate", generate_node)
graph.add_edge("retrieve", "generate")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.