doclex-cli 0.1.1__tar.gz

doclex_cli-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.doclex/
+*.db
+dist/
+*.egg-info/
+.env
+ANDE Files/
+.claude/
+.agents/
+skills-lock.json
+benchmarks/data/
+benchmarks/results/

doclex_cli-0.1.1/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-08-02
+
+### Fixed
+
+- Search result snippets now anchor on the window with the highest density of query-term matches instead of the first occurrence of the first term, so the snippet favors where the query actually clusters rather than an early, isolated mention.
+
+## [0.1.0] - 2026-08-02
+
+First release — CLI MVP (Fase 1): local, embeddings-free document search over PDF, DOCX, XLSX, CSV, Markdown and TXT files.
+
+### Added
+
+- Local document search CLI (`doclex`) — BM25 lexical search, no embeddings, no vector DB, no cloud.
+- Ingestion pipeline: folder scanning with hash-based change detection, Kreuzberg-based text extraction, structural segmentation per file type (pages, sheets, sections, blocks), BM25X indexing, SQLite metadata store, and a local extraction cache.
+- Real-time incremental updates via Watchdog file monitoring, plus full reconciliation on startup.
+- `doclex add`/`projects`/`remove` — named project registry mapping folder paths to project names, rejecting overlapping/nested folders.
+- `doclex index --project <name> [--file ...] [--force]` — incremental or forced full reindexing, with per-file targeting.
+- `doclex search <query> --project <name> [--top] [--full]` — top-k BM25 search with citations (file, location, score, snippet).
+- `doclex status --project <name> [--file ...] [--all] [--filter]` — corpus/index status, file listing, and per-file inspection.
+- OCR support (`--ocr`) for scanned PDFs, and layout-aware segmentation via Kreuzberg.
+- Recursive character-based splitter keeping segments within a 1024-character limit while preserving semantic boundaries.
+
+### Changed
+
+- CLI output migrated to Rich (progress bars, tables) instead of plain text.
+- Segmentation cache replaced with a unified page-index-style tree; split sub-segments now nest under their extracted heading parent.
+- `list`/`reindex` merged into `index`/`status` flags; cache directory renamed from `.cache` to `.doclex`.
+- Layout-aware PDF segmentation made the default (removed the `--precise` flag).
+
+### Fixed
+
+- Ghost BM25 index entries left behind after a forced reindex (index and SQLite are now rebuilt fully in sync).
+- `status`/`search` no longer create the index directory before a project has actually been indexed.
+- Search result snippets now tokenize the query the same way BM25X tokenizes documents (splitting on punctuation, not just whitespace) and snap to word boundaries instead of cutting words mid-way.

doclex_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,346 @@
+Antes de escribir cualquier código, genera un plan de implementación completo con estructura de carpetas, módulos, schema SQLite y tools MCP. Espera confirmación antes de proceder.
+
+---
+
+# Doclex MCP
+
+Servidor MCP para búsqueda local dentro de documentos usando **extracción de texto + segmentación estructural + BM25**.
+
+El objetivo es permitir que un agente de IA pueda consultar una carpeta local con documentos heterogéneos y recuperar fragmentos relevantes con citas precisas.
+
+---
+
+## Objetivo
+
+Construir un servidor MCP que permita buscar información dentro de archivos locales sin usar embeddings, sin base de datos vectorial y sin depender de servicios externos.
+
+Debe funcionar sobre una carpeta local configurable y mantener un índice actualizado automáticamente cuando los archivos cambian.
+
+---
+
+## Alcance
+
+El sistema debe:
+
+* escanear una carpeta local
+* detectar archivos compatibles
+* extraer su contenido a texto
+* segmentar el contenido en unidades buscables
+* indexar esos segmentos con BM25
+* actualizar el índice cuando los archivos cambien
+* exponer herramientas MCP para búsqueda y recuperación de resultados
+
+---
+
+## Tipos de archivo soportados
+
+El sistema debe estar diseñado para soportar al menos:
+
+* PDF
+* TXT
+* Markdown
+* DOCX
+* XLSX
+* CSV
+
+La extracción debe delegarse a Kreuzberg.
+
+---
+
+## Arquitectura general
+
+El sistema se compone de cinco partes principales:
+
+### 1. Ingestion Layer
+
+Responsable de descubrir archivos dentro de una carpeta y decidir cuándo un archivo debe procesarse o reprocesarse.
+
+Debe detectar:
+
+* archivos nuevos
+* archivos modificados
+* archivos eliminados
+
+Debe ignorar carpetas internas del sistema como `.cache` o equivalentes.
+
+---
+
+### 2. Extraction Layer
+
+Responsable de convertir archivos a texto utilizable.
+
+Debe usar Kreuzberg como backend de extracción.
+
+La salida de esta capa no debe depender directamente del formato original del extractor, sino normalizarse a una estructura interna propia.
+
+---
+
+### 3. Segmentation Layer
+
+Responsable de dividir el contenido en unidades buscables.
+
+No se debe indexar el archivo completo como una sola unidad, ni usar chunking ciego por tamaño fijo.
+
+La segmentación debe seguir la estructura natural del documento según el tipo de archivo:
+
+* PDF → página o bloque
+* XLSX → hoja o tabla
+* DOCX → sección o heading
+* TXT / MD → bloque o heading
+* CSV → tabla o fragmento tabular
+
+Cada segmento debe conservar referencia clara a su archivo de origen y su ubicación exacta.
+
+---
+
+### 4. Index Layer
+
+Responsable de indexar y consultar segmentos usando BM25.
+
+Debe usar BM25X como motor principal.
+
+La unidad de indexación debe ser el segmento, no el archivo completo.
+
+Debe soportar:
+
+* agregar segmentos nuevos
+* actualizar segmentos de un archivo modificado
+* eliminar segmentos de un archivo borrado
+* buscar top-k resultados
+
+---
+
+### 5. Metadata Layer
+
+Responsable de mantener el estado del corpus y del índice.
+
+Debe usar SQLite.
+
+Debe almacenar al menos:
+
+* ruta del archivo
+* hash del archivo
+* fecha de modificación
+* tamaño
+* tipo MIME
+* estado de indexación
+* relación entre archivo y segmentos indexados
+
+Esto se usa para saber qué archivos deben reprocesarse y para mantener consistencia entre disco, caché e índice.
+
+---
+
+## Caché local
+
+El sistema debe mantener una caché local derivada del contenido procesado.
+
+La caché debe permitir evitar reprocesar archivos sin cambios y facilitar depuración.
+
+Debe almacenar por archivo:
+
+* texto completo extraído
+* metadatos
+* segmentos generados
+
+La caché no debe ser la fuente principal de búsqueda, pero sí la fuente intermedia entre extracción e indexación.
+
+---
+
+## Actualización automática
+
+El sistema debe monitorear la carpeta configurada en tiempo real usando Watchdog.
+
+Cuando un archivo se crea, modifica o elimina, el sistema debe:
+
+1. detectar el cambio
+2. aplicar debounce
+3. revalidar el estado real del archivo
+4. reprocesar solo lo necesario
+5. actualizar caché, SQLite e índice BM25
+
+Además del monitoreo por eventos, el sistema debe poder ejecutar reconciliación completa al iniciar.
+
+---
+
+## Flujo de indexación
+
+### Al iniciar
+
+* escanear la carpeta objetivo
+* comparar archivos actuales con el estado en SQLite
+* detectar nuevos, modificados y eliminados
+* procesar cada cambio
+* construir o actualizar índice
+* activar el monitor de archivos
+
+### Cuando cambia un archivo
+
+* recalcular hash y metadatos
+* reextraer contenido
+* regenerar segmentos
+* reemplazar en índice solo los segmentos de ese archivo
+* actualizar caché y manifiesto
+
+---
+
+## Flujo de búsqueda
+
+Cuando un agente realiza una consulta:
+
+1. recibir query de texto
+2. aplicar normalización básica
+3. ejecutar búsqueda BM25 sobre segmentos
+4. recuperar top-k resultados
+5. devolver resultados enriquecidos con metadatos y contexto
+
+---
+
+## Resultado esperado de una búsqueda
+
+Cada resultado debe incluir:
+
+* texto del segmento encontrado
+* score de relevancia
+* archivo de origen
+* tipo de archivo
+* ubicación interna:
+
+  * página
+  * hoja
+  * sección
+  * bloque
+* snippet o texto resumido del match
+* identificador estable del segmento
+
+---
+
+## Requisitos de diseño
+
+El sistema debe ser:
+
+* local-first
+* incremental
+* explicable
+* determinista
+* barato en recursos
+* fácil de depurar
+
+Debe priorizar:
+
+* precisión léxica
+* trazabilidad
+* simplicidad operacional
+
+sobre:
+
+* semántica profunda
+* recuperación por embeddings
+* razonamiento generativo durante búsqueda
+
+---
+
+## Lo que no debe hacer
+
+El sistema no debe:
+
+* usar embeddings
+* usar base de datos vectorial
+* subir archivos a la nube
+* depender de servicios externos para búsqueda
+* hacer OCR por defecto
+* generar respuestas directamente dentro del índice
+
+La responsabilidad del sistema es **recuperar evidencia**, no responder preguntas por sí mismo.
+
+---
+
+## Integración MCP
+
+El servidor debe exponer herramientas MCP para que un agente pueda al menos:
+
+* buscar dentro del corpus
+* listar archivos indexados
+* consultar detalles de un archivo
+* forzar reindexación si es necesario
+
+La interfaz MCP debe estar pensada para que un agente pueda hacer workflows tipo:
+
+1. buscar
+2. leer evidencia
+3. refinar búsqueda
+4. responder usando citas
+
+---
+
+## Stack esperado
+
+* Python
+* MCP SDK
+* Kreuzberg
+* BM25X
+* Watchdog
+* SQLite
+
+---
+
+## Prioridad de implementación
+
+### Fase 1 — CLI (MVP)
+
+El pipeline debe implementarse y verificarse primero como CLI, antes de exponer cualquier interfaz MCP.
+
+Primera versión funcional con:
+
+* escaneo de carpeta
+* extracción (Kreuzberg)
+* segmentación estructural por tipo de archivo
+* indexación BM25 (BM25X)
+* búsqueda top-k desde línea de comandos
+* actualización incremental (Watchdog)
+* caché local y estado en SQLite
+
+La CLI se organiza alrededor de **proyectos**: un proyecto es un nombre registrado que apunta a una carpeta. Toda resolución de carpeta pasa por un proyecto registrado — no existe un flag `--folder` suelto. Esto evita ambigüedad sobre contra qué carpeta se opera y permite detectar carpetas solapadas entre proyectos (rechazadas al registrar).
+
+La CLI debe permitir al menos:
+
+* `doclex add <nombre> <carpeta>` — registra una carpeta bajo un nombre de proyecto (rechaza nombres duplicados, carpetas inexistentes y carpetas que se solapen con un proyecto ya registrado)
+* `doclex list` — lista los proyectos registrados
+* `doclex remove <nombre>` — elimina un proyecto y purga siempre su caché e índice asociados
+* `doclex index --project <nombre> [--file <archivo> ...] [--force]` — indexa el proyecto de forma incremental, o reindexa archivos puntuales con `--file` (repetible), o fuerza reextracción total con `--force`
+* `doclex search <query> --project <nombre> [--top N] [--full]` — busca y muestra resultados con citas; `<query>` es un argumento posicional
+* `doclex status --project <nombre> [--file <archivo> ...] [--all] [--filter indexed|error|pending]` — muestra estado del corpus, lista archivos indexados (`--all`) o inspecciona archivos específicos
+
+`add`/`list`/`remove` son comandos planos, no un subgrupo `project`, ya que `--project` ya se usa como flag en `index`/`search`/`status`. `doclex list` lista **proyectos**, no archivos — para listar archivos de un proyecto se usa `status --all`. No existe un comando `doclex reindex` independiente: queda cubierto por `index --file`.
+
+El resultado de `doclex search` debe mostrar por cada resultado: archivo de origen, ubicación (página / hoja / sección), score de relevancia y snippet del texto encontrado.
+
+### Fase 2 — Servidor MCP
+
+La capa MCP se agrega únicamente después de que el pipeline de extracción, segmentación e indexación esté verificado y funcionando correctamente vía CLI.
+
+Las herramientas MCP son un wrapper sobre el mismo pipeline ya validado.
+
+### Fase 3 — Futuro opcional
+
+Posibles mejoras fuera del alcance actual:
+
+* OCR opcional
+* filtros avanzados
+* query expansion
+* query rewriting
+* búsqueda multi-paso
+* integración con agentes más complejos
+
+---
+
+## Resumen funcional
+
+Doclex MCP debe convertir una carpeta local de documentos en un corpus buscable para agentes, con actualización automática, recuperación precisa y resultados citables.
+
+---
+
+## Notas para Claude Code
+
+- Instalar dependencias con uv, no con pip
+- Usar pyproject.toml para gestión del proyecto
+- No crear archivos de código sin antes mostrar el plan completo y recibir confirmación

doclex_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnPaiva_93
+
+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.

doclex_cli-0.1.1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: doclex-cli
+Version: 0.1.1
+Summary: Local document search — BM25 lexical search over PDFs, DOCX, XLSX, CSV, Markdown and TXT files. No embeddings, no vector DB, no cloud.
+Project-URL: Repository, https://github.com/EnPaiva93/doclex-cli
+Author-email: EnPaiva_93 <enpaiva93@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite
+Requires-Dist: bm25x
+Requires-Dist: kreuzberg==4.8.2
+Requires-Dist: typer
+Requires-Dist: watchdog
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ranx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">Doclex</h1>
+
+<p align="center"><em>English · <a href="README.es.md">Español</a></em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+">
+</p>
+
+<p align="center">A CLI that turns a local folder of documents into a searchable, citable corpus. Point it at a folder; extraction, segmentation, indexing, and change tracking happen automatically.</p>
+
+## Features
+
+Doclex is the orchestration layer that ties them together so you never have to think about the pipeline yourself:
+
+- **Plug and play** — point it at a folder. Extraction, structural segmentation, indexing, and change tracking all happen automatically; there's no pipeline to wire up.
+- **SQLite is the source of truth** — every file's hash, mtime, and indexing status live in one place, so Doclex always knows exactly what changed and reprocesses only that.
+- **Local-first** — everything runs on your machine, nothing leaves it. No embeddings, no vector database, no cloud.
+- **Deterministic** — BM25 lexical scoring, no black-box similarity.
+- **Traceable** — every result cites its file, page/sheet/section, and score.
+- **Incremental** — only reprocesses files that actually changed.
+
+## Install
+
+Requires Python ≥3.12 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/EnPaiva93/doclex-cli.git
+cd doclex-cli
+uv sync
+```
+
+## Quickstart
+
+```bash
+# register a folder as a project
+uv run doclex add mydocs ./path/to/documents
+
+# build the index
+uv run doclex index --project mydocs
+
+# search it
+uv run doclex search "quarterly budget" --project mydocs
+```
+
+```
+[1] budget_2024.pdf — page 3  (score: 4.812)
+    "...the quarterly budget was approved with a 12% increase in..."
+
+[2] notes.md — Planning  (score: 2.107)
+    "...need to revisit the budget assumptions before..."
+```
+
+## Walkthrough
+
+A typical day-to-day flow, from an empty project to keeping it in sync:
+
+```bash
+# 1. register the folder you want to search
+doclex add contracts ~/Documents/legal/contracts
+
+# 2. build the index — extracts, segments, and indexes every supported file
+doclex index --project contracts
+```
+```
+Processing: 42 new, 0 modified, 0 deleted
+✓ Done.
+```
+```bash
+# 3. search it
+doclex search "termination clause" --project contracts
+```
+```
+[1] MSA_2023_AcmeCorp.pdf — Section 9.2  (score: 6.104)
+    "...either party may terminate this Agreement upon 30 days written notice..."
+
+[2] vendor_agreement_v3.docx — Termination  (score: 5.887)
+    "...termination for convenience requires 60 days advance notice to..."
+```
+```bash
+# 4. check what's indexed
+doclex status --project contracts
+```
+```
+Folder       ~/Documents/legal/contracts
+Indexed      42 files
+Segments     318
+BM25 index   318 docs
+Disk state   up to date
+```
+```bash
+# 5. a new contract shows up on disk — reindexing picks it up automatically
+doclex index --project contracts
+```
+```
+Processing: 1 new, 0 modified, 0 deleted
+✓ Done.
+```
+```bash
+# 6. see every registered project
+doclex list
+```
+```
+Name        Folder
+contracts   /home/you/Documents/legal/contracts
+```
+```bash
+# 7. done with it — deregister and purge its cache/index
+doclex remove contracts
+```
+
+Each project is independent — register as many non-overlapping folders as you need, each with its own cache and index:
+
+```bash
+doclex add hr-policies ~/Documents/hr
+doclex index --project hr-policies
+doclex search "vacation days" --project hr-policies --top 5
+```
+
+## Projects
+
+Every command operates on a **registered project** — a name bound to a folder — instead of a raw `--folder` flag. This keeps folder resolution unambiguous and lets Doclex reject overlapping folders (a subfolder registered as its own project would silently duplicate indexing and caching):
+
+```bash
+doclex add mydocs ./path/to/documents
+doclex add mydocs ./other       # error: name already exists
+doclex add sub ./path/to/documents/subdir   # error: overlaps with 'mydocs'
+doclex remove mydocs            # deregisters and purges its cache/index
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `doclex add <name> <folder>` | Register a folder under a project name |
+| `doclex list` | List registered projects |
+| `doclex remove <name>` | Remove a project and purge its cache/index |
+| `doclex index --project <name>` | Scan and index (incremental by default) |
+| `doclex search <query> --project <name>` | Search and print results with citations |
+| `doclex status --project <name>` | Show corpus/index status |
+
+Run `doclex <command> --help` for all flags and examples.
+
+### Flags in practice
+
+```bash
+# force a full re-extraction
+doclex index --project mydocs --force
+
+# reindex specific files after editing them
+doclex index --project mydocs --file report.pdf --file notes.docx
+
+# more results, full segment text instead of a snippet
+doclex search "risk assessment" --project mydocs --top 20 --full
+
+# list every indexed file and its status
+doclex status --project mydocs --all --filter error
+```
+
+## Architecture
+
+```
+folder → scan/watch → extract (Kreuzberg) → segment → BM25X index
+                                                  ↕
+                                          SQLite (files, segments)
+```
+
+| Layer | Responsibility |
+|---|---|
+| **Ingestion** | Scans a project's folder, hashes files to detect new/modified/deleted ones, skips its own cache directory |
+| **Extraction** | Delegates to [Kreuzberg](https://github.com/Goldziher/kreuzberg) to turn each file into plain text, normalized to an internal format |
+| **Segmentation** | Splits text along the file's natural structure — never blind fixed-size chunking (PDF → page, XLSX → sheet, DOCX → section, TXT/MD → block) |
+| **Index** | Indexes segments (not whole files) with BM25X; supports incremental add/update/delete |
+| **Metadata** | SQLite tracks each file's hash, mtime, size, MIME type, and indexing status, plus which segments belong to it |
+
+A local cache stores extracted text and generated segments per file, so unchanged files are never reprocessed.
+
+## Supported file types
+
+PDF · TXT · Markdown · DOCX · XLSX · CSV
+
+## Design principles
+
+Doclex is built to be local-first, incremental, explainable, deterministic, and cheap to run. It deliberately does **not**:
+
+- use embeddings or a vector database
+- upload files anywhere
+- depend on external services to search
+- run OCR by default
+- generate answers — it retrieves evidence, it doesn't interpret it
+
+## Stack
+
+Python · [Typer](https://typer.tiangolo.com/) · [Kreuzberg](https://github.com/Goldziher/kreuzberg) · BM25X · Watchdog · SQLite
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```