feat: add framework integrations and improve CLI with Session API

- Add LangChain and LlamaIndex compatibility modules with retriever
  implementations
- Introduce high-level Session API as primary interface replacing Engine
- Add comprehensive test suite for configuration, events, and type
  wrappers with shared fixtures
- Implement batch indexing support in CLI with directory traversal
- Add interactive REPL with document targeting, stats tracking,
  and navigation commands
- Update pyproject.toml with new dependencies and optional extras
  for different integration frameworks
- Refactor CLI commands to use Session-based workflow instead of
  low-level Engine operations

Author: zTgx

pyproject.toml

@@ -28,14 +28,38 @@ classifiers = [
 ]
 keywords = ["rag", "document", "retrieval", "llm", "document-intelligence"]
 
-dependencies = []
+dependencies = [
+    "pydantic>=2.0",
+    "click>=8.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
     "mypy>=1.0",
+    "rich>=13.0",
+]
+cli = [
+    "rich>=13.0",
+]
+langchain = [
+    "langchain-core>=0.1.0",
+]
+llamaindex = [
+    "llama-index-core>=0.10.0",
 ]
+jupyter = [
+    "rich>=13.0",
+    "ipywidgets>=8.0",
+]
+all = [
+    "vectorless[cli,langchain,llamaindex,jupyter]",
+]
+
+[project.scripts]
+vectorless = "vectorless.cli.main:app"
 
 [project.urls]
 Homepage = "https://vectorless.dev"

python/tests/__init__.py

@@ -0,0 +1,90 @@
+"""Shared test fixtures."""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.fixture
+def mock_engine():
+    """Mock Rust Engine for testing without LLM."""
+    engine = MagicMock()
+
+    # Mock index result
+    index_result = MagicMock()
+    index_result.doc_id = "test-doc-id"
+    index_item = MagicMock()
+    index_item.doc_id = "test-doc-id"
+    index_item.name = "test.md"
+    index_item.format = "markdown"
+    index_item.description = None
+    index_item.source_path = "/path/to/test.md"
+    index_item.page_count = None
+    index_item.metrics = None
+    index_result.items = [index_item]
+    index_result.failed = []
+    index_result.has_failures.return_value = False
+    index_result.total.return_value = 1
+    index_result.__len__ = lambda self: 1
+
+    engine.index = AsyncMock(return_value=index_result)
+
+    # Mock query result
+    query_item = MagicMock()
+    query_item.doc_id = "test-doc-id"
+    query_item.content = "Test answer content"
+    query_item.score = 0.85
+    query_item.confidence = 0.85
+    query_item.node_ids = ["node-1"]
+    query_item.evidence = []
+    query_item.metrics = None
+
+    query_result = MagicMock()
+    query_result.items = [query_item]
+    query_result.failed = []
+    query_result.single.return_value = query_item
+    query_result.has_failures.return_value = False
+    query_result.__len__ = lambda self: 1
+
+    engine.query = AsyncMock(return_value=query_result)
+
+    # Mock list
+    doc_info = MagicMock()
+    doc_info.id = "test-doc-id"
+    doc_info.name = "test.md"
+    doc_info.format = "markdown"
+    doc_info.description = None
+    doc_info.source_path = "/path/to/test.md"
+    doc_info.page_count = None
+    doc_info.line_count = 42
+    engine.list = AsyncMock(return_value=[doc_info])
+
+    # Mock other operations
+    engine.remove = AsyncMock(return_value=True)
+    engine.clear = AsyncMock(return_value=1)
+    engine.exists = AsyncMock(return_value=True)
+
+    # Mock graph
+    engine.get_graph = AsyncMock(return_value=None)
+
+    # Mock metrics
+    metrics_report = MagicMock()
+    metrics_report.total_cost_usd.return_value = 0.001
+    engine.metrics_report.return_value = metrics_report
+
+    return engine
+
+
+@pytest.fixture
+def sample_config_dict():
+    """Sample configuration dict."""
+    return {
+        "llm": {
+            "model": "gpt-4o",
+            "api_key": "sk-test-key",
+            "endpoint": "https://api.openai.com/v1",
+        },
+        "retrieval": {"top_k": 5},
+        "storage": {"workspace_dir": "/tmp/test-vectorless"},
+    }

python/tests/conftest.py

@@ -0,0 +1,95 @@
+"""Tests for configuration models and loading."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from vectorless.config.models import (
+    EngineConfig,
+    LlmConfig,
+    MetricsConfig,
+    RetrievalConfig,
+    StorageConfig,
+)
+
+
+class TestEngineConfig:
+    def test_defaults(self):
+        config = EngineConfig()
+        assert config.llm.model == ""
+        assert config.llm.api_key is None
+        assert config.retrieval.top_k == 3
+        assert config.storage.workspace_dir == "~/.vectorless"
+        assert config.metrics.enabled is True
+
+    def test_custom_values(self):
+        config = EngineConfig(
+            llm=LlmConfig(model="gpt-4o", api_key="sk-test"),
+            retrieval=RetrievalConfig(top_k=10),
+            storage=StorageConfig(workspace_dir="/data/vl"),
+        )
+        assert config.llm.model == "gpt-4o"
+        assert config.llm.api_key == "sk-test"
+        assert config.retrieval.top_k == 10
+        assert config.storage.workspace_dir == "/data/vl"
+
+    def test_to_rust_config(self):
+        config = EngineConfig(
+            llm=LlmConfig(model="gpt-4o", api_key="sk-test"),
+            retrieval=RetrievalConfig(top_k=5, max_iterations=20),
+            storage=StorageConfig(workspace_dir="/tmp/vl"),
+            metrics=MetricsConfig(enabled=False),
+        )
+        # to_rust_config should not raise
+        rust_config = config.to_rust_config()
+        assert rust_config is not None
+
+    def test_validation_top_k_minimum(self):
+        with pytest.raises(Exception):
+            RetrievalConfig(top_k=0)
+
+    def test_json_roundtrip(self):
+        config = EngineConfig(
+            llm=LlmConfig(model="gpt-4o", api_key="sk-test"),
+        )
+        data = config.model_dump()
+        restored = EngineConfig(**data)
+        assert restored.llm.model == "gpt-4o"
+        assert restored.llm.api_key == "sk-test"
+
+
+class TestConfigLoading:
+    def test_load_from_env(self):
+        os.environ["VECTORLESS_API_KEY"] = "sk-env-test"
+        os.environ["VECTORLESS_MODEL"] = "gpt-4o-mini"
+        os.environ["VECTORLESS_TOP_K"] = "7"
+
+        try:
+            from vectorless.config.loading import load_config_from_env
+
+            config = load_config_from_env()
+            assert config.llm.api_key == "sk-env-test"
+            assert config.llm.model == "gpt-4o-mini"
+            assert config.retrieval.top_k == 7
+        finally:
+            del os.environ["VECTORLESS_API_KEY"]
+            del os.environ["VECTORLESS_MODEL"]
+            del os.environ["VECTORLESS_TOP_K"]
+
+    def test_load_from_file(self):
+        with tempfile.NamedTemporaryFile(mode="wb", suffix=".toml", delete=False) as f:
+            f.write(b'[llm]\nmodel = "gpt-4o"\napi_key = "sk-file"\n')
+            f.flush()
+
+            try:
+                from vectorless.config.loading import load_config_from_file
+
+                config = load_config_from_file(Path(f.name))
+                assert config.llm.model == "gpt-4o"
+                assert config.llm.api_key == "sk-file"
+            finally:
+                os.unlink(f.name)

python/tests/test_cli/__init__.py

@@ -0,0 +1,78 @@
+"""Tests for the event system."""
+
+from __future__ import annotations
+
+from vectorless.events import (
+    EventEmitter,
+    IndexEventData,
+    IndexEventType,
+    QueryEventData,
+    QueryEventType,
+)
+
+
+class TestEventEmitter:
+    def test_index_events(self):
+        received = []
+        emitter = EventEmitter()
+
+        @emitter.on_index
+        def handler(event):
+            received.append(event)
+
+        event = IndexEventData(
+            event_type=IndexEventType.STARTED,
+            path="/test/doc.pdf",
+        )
+        emitter.emit_index(event)
+
+        assert len(received) == 1
+        assert received[0].path == "/test/doc.pdf"
+        assert received[0].event_type == IndexEventType.STARTED
+
+    def test_query_events(self):
+        received = []
+        emitter = EventEmitter()
+
+        @emitter.on_query
+        def handler(event):
+            received.append(event)
+
+        event = QueryEventData(
+            event_type=QueryEventType.COMPLETE,
+            query="What is revenue?",
+            total_results=3,
+        )
+        emitter.emit_query(event)
+
+        assert len(received) == 1
+        assert received[0].query == "What is revenue?"
+        assert received[0].total_results == 3
+
+    def test_multiple_handlers(self):
+        count = [0]
+        emitter = EventEmitter()
+
+        emitter.on_index(lambda e: count.__setitem__(0, count[0] + 1))
+        emitter.on_index(lambda e: count.__setitem__(0, count[0] + 1))
+
+        emitter.emit_index(
+            IndexEventData(event_type=IndexEventType.COMPLETE)
+        )
+
+        assert count[0] == 2
+
+    def test_chaining(self):
+        emitter = EventEmitter()
+        result = emitter.on_index(lambda e: None)
+        assert result is emitter
+
+    def test_no_handlers(self):
+        emitter = EventEmitter()
+        # Should not raise
+        emitter.emit_index(
+            IndexEventData(event_type=IndexEventType.COMPLETE)
+        )
+        emitter.emit_query(
+            QueryEventData(event_type=QueryEventType.COMPLETE)
+        )

python/tests/test_compat/__init__.py

@@ -0,0 +1,55 @@
+"""Tests for Session high-level API."""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+
+class TestSessionConstruction:
+    def test_session_rejects_no_source(self):
+        """Session.index() should reject calls with no source."""
+        # We can't fully test Session without a real Engine,
+        # but we can test validation logic
+        from vectorless.session import Session
+
+        # This will fail because no api_key/model provided
+        # We just verify the source validation in index()
+        pass
+
+
+class TestSessionIndex:
+    @pytest.mark.asyncio
+    async def test_index_requires_exactly_one_source(self):
+        from vectorless.session import Session
+
+        # Patch Engine construction
+        with patch("vectorless.session.Engine") as MockEngine:
+            mock_engine = MagicMock()
+            mock_result = MagicMock()
+            mock_result.doc_id = "doc-1"
+            mock_result.items = []
+            mock_result.failed = []
+            mock_engine.index = AsyncMock(return_value=mock_result)
+            MockEngine.return_value = mock_engine
+
+            from vectorless.config import EngineConfig, LlmConfig
+
+            with patch(
+                "vectorless.session.Session._resolve_config",
+                return_value=EngineConfig(llm=LlmConfig(model="test", api_key="test")),
+            ):
+                session = Session.__new__(Session)
+                session._config = EngineConfig(
+                    llm=LlmConfig(model="test", api_key="test")
+                )
+                session._engine = mock_engine
+                session._events = MagicMock()
+
+                # No source
+                with pytest.raises(ValueError, match="exactly one source"):
+                    await session.index()
+
+                # Multiple sources
+                with pytest.raises(ValueError, match="exactly one source"):
+                    await session.index(path="a.pdf", content="text")