Metadata-Version: 2.4
Name: obsidianrag
Version: 4.0.0
Summary: RAG system for querying Obsidian notes with SQLite FTS5 and LanceDB
Project-URL: Homepage, https://github.com/Vasallo94/ObsidianRAG
Project-URL: Repository, https://github.com/Vasallo94/ObsidianRAG
Project-URL: Documentation, https://github.com/Vasallo94/ObsidianRAG#readme
Project-URL: Issues, https://github.com/Vasallo94/ObsidianRAG/issues
Author: Enrique Vasallo
License: MIT
Keywords: lancedb,langchain,obsidian,ollama,plugin,rag,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.4
Requires-Dist: httpx>=0.27.2
Requires-Dist: lancedb<0.37.0,>=0.36.0
Requires-Dist: langchain-core>=0.3.15
Requires-Dist: langchain-huggingface>=0.1.0
Requires-Dist: langchain-ollama>=0.2.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.9.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: typer>=0.12.5
Requires-Dist: uvicorn>=0.32.0
Description-Content-Type: text/markdown

# ObsidianRAG Backend 4

Python 3.11+ backend for the ObsidianRAG API, CLI, revisioned SQLite FTS5 catalog, and embedded LanceDB vector index.

## Install

```bash
pip install obsidianrag==4.0.0
# or
uv tool install obsidianrag==4.0.0
```

LanceDB is a standard dependency in 4.0.0; no extra is required.

## Commands

```bash
obsidianrag serve --vault /path/to/vault
obsidianrag index --vault /path/to/vault
obsidianrag index --vault /path/to/vault --full-rebuild
obsidianrag status --vault /path/to/vault
obsidianrag prune --vault /path/to/vault
obsidianrag search "deployment rollback" --vault /path/to/vault
obsidianrag search "deployment rollback" --vault /path/to/vault --lexical-only
obsidianrag ask "How do I roll back a deployment?" --vault /path/to/vault
```

`index` is incremental by default. Use `--full-rebuild` only when status reports incompatible schema, embedding, or chunk settings, or when recovering a malformed active manifest.

## API 4

Start the server:

```bash
obsidianrag serve --vault /path/to/vault --host 127.0.0.1 --port 8000
```

Endpoints:

- `GET /capabilities`
- `GET /health`
- `GET /models`
- `POST /ask`
- `POST /ask/stream`
- `GET /index/status`
- `POST /index/build`
- `POST /index/prune`

A fresh server is healthy but not query-ready. It does not build automatically. `GET /health` reports `query_ready`, `active_revision`, and `serving_revision` so clients can present the correct lifecycle action.

Build request:

```json
{
  "full_rebuild": false
}
```

Status states:

- `missing`: build the first index.
- `current`: active content and configuration match the vault.
- `stale`: refresh incrementally; an older revision may remain available to current readers.
- `rebuild_required`: perform an explicit full rebuild.

## Storage and safety

Indexes live under `.obsidianrag/v4`. Builds:

- scan regular Markdown without following symlinks or junctions;
- create isolated copy-on-write revisions;
- copy unchanged vectors in bounded batches;
- fingerprint actual synthetic embedding outputs;
- validate SQLite integrity, foreign keys, FTS semantics, deterministic IDs, paths, dimensions, and finite vectors;
- fsync the candidate before atomically replacing `active.json`;
- keep the previous serving revision available until all checked-out readers finish.

`prune` removes inactive revisions only when no reader lease exists.

Legacy `.obsidianrag/db` data from 3.x is ignored and never removed automatically.

## Providers

Generation supports Ollama, LM Studio, and custom Ollama/chat-completions-compatible endpoints. Embeddings support Ollama and HuggingFace.

```bash
obsidianrag serve --vault /path/to/vault --provider ollama --model gemma3

obsidianrag serve --vault /path/to/vault \
  --provider lmstudio --model local-model \
  --base-url http://localhost:1234/v1
```

Environment variables use the `OBSIDIANRAG_` prefix.

## Evaluation

```bash
obsidianrag evaluate evaluation.json --vault /path/to/vault --k 10
obsidianrag evaluate evaluation.json --vault /path/to/vault --lexical-only
obsidianrag compare-evaluations baseline.json candidate.json
```

External-agent evaluation requires explicit private-data consent:

```bash
obsidianrag evaluate-agent private.json \
  --vault /path/to/vault \
  --generator-command "python -m obsidianrag.pi_agent_adapter" \
  --judge-command "python -m obsidianrag.pi_agent_adapter" \
  --allow-private-data
```

## Development

```bash
uv sync --locked --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv build
```

Normal tests use temporary/sample vaults and mocked providers.
