docmind-ai-llm

Installation

1. Clone the repository:

   git clone https://github.com/BjornMelin/docmind-ai-llm.git
   cd docmind-ai-llm
   

2. Install dependencies:

   uv sync --frozen
   

   Install the optional observability extra for LlamaIndex OpenTelemetry instrumentation:

   uv sync --frozen --extra observability
   

   Searchable-PDF export is POSIX-only (Linux, macOS, or WSL2; native Windows is unsupported) and requires the OCRmyPDF and Tesseract executables:

   uv sync --frozen --extra searchable-pdf
   

   Prefetch the default retrieval and parser artifacts, then verify the parser manifests:

   uv run python tools/models/pull.py \
     --all \
     --cache_dir ./models_cache \
     --parser-defaults \
     --parser-cache-dir ./cache/models
   uv run python scripts/parser_health.py --check
   

   Regenerate the schema 3 parser benchmark artifact after the code is frozen:

   uv run python scripts/benchmark_parsing.py \
     --generate-minimal-fixtures \
     --repeat 3 \
     --output docs/benchmarks/parser-runtime-validation.json
   

   The checked-in schema 3 artifact is bound to its clean source commit and runtime identity. The validation record, current baseline, and measurement limits live in docs/developers/parser-runtime-validation.md.

   Start loopback-only Qdrant and run the system gate when you need end-to-end validation:

   ./scripts/start_qdrant_local.sh
   DOCMIND_RUN_SYSTEM=1 \
     DOCMIND_QDRANT_SYSTEM_URL=http://127.0.0.1:6333 \
     uv run pytest tests/system/test_e2e_offline.py -q
   

   Key Dependencies Included:

   • LlamaIndex Core (>=0.14.21,<0.15.0): Ingestion, retrieval, selectors, and query engines, with selected LLM, Hugging Face, Qdrant, and DuckDB adapters
   • LangGraph (>=1.0.10,<2.0.0): Four-worker supervisor orchestration (graph-native StateGraph, no external supervisor wrapper)
   • Streamlit (>=1.52.2,<2.0.0): Web interface framework
   • Ollama (0.6.2): Local LLM integration
   • Qdrant Client (>=1.15.1,<2.0.0): Vector database operations
   • Docling (>=2.111,<3): Multi-format document conversion.
   • pypdfium2 (>=5.7,<6): PDF inspection and page rasterization.
   • RapidOCR (>=3.8,<4): CPU-safe local OCR using the locked wheel's hash-verified packaged models.
   • FastEmbed (>=0.5.1): Direct CPU sparse query encoding
   • Loguru (>=0.7.3,<1.0.0): Structured logging
   • Pydantic (2.13.4): Data validation and settings.

3. Install spaCy language model:

   spaCy is bundled for optional NLP enrichment (sentence segmentation + entity extraction during ingestion). Install a language model if you plan to use enrichment:

   # Install the small English model (recommended, ~15MB)
   uv run python -m spacy download en_core_web_sm
   
   # Optional: Install larger models for better accuracy
   # Medium model (~50MB): uv run python -m spacy download en_core_web_md
   # Large model (~560MB): uv run python -m spacy download en_core_web_lg
   

   Note: spaCy models are downloaded and cached locally. The app does not auto-download models; install them explicitly for offline use.

   Optional configuration (defaults shown):

   # Enable/disable enrichment
   DOCMIND_SPACY__ENABLED=true
   # Pipeline name or path (blank fallback when missing)
   DOCMIND_SPACY__MODEL=en_core_web_sm
   # cpu|cuda|apple|auto (auto prefers CUDA, then Apple, else CPU)
   DOCMIND_SPACY__DEVICE=auto
   DOCMIND_SPACY__GPU_ID=0
   

   Cross-platform acceleration:

   • NVIDIA CUDA (validated on Linux x86_64): uv sync --frozen --no-group cpu --extra gpu and set DOCMIND_SPACY__DEVICE=auto|cuda; WSL2 is best effort
   • Apple Silicon (best effort, macOS arm64 with CPython 3.12): uv sync --frozen --extra apple and set DOCMIND_SPACY__DEVICE=auto|apple

   See docs/specs/spec-015-nlp-enrichment-spacy.md and