Metadata-Version: 2.4
Name: obsidianrag
Version: 4.0.1
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 License
        
        Copyright (c) [2024] [Enrique Vasallo Fernández]
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
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.1
# or
uv tool install obsidianrag==4.0.1
```

LanceDB is a standard dependency in 4.0.1; 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.
