DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
from __future__ import annotations
import asyncio
import importlib.util
import inspect
import json
from pathlib import Path
import sys
import types
import pytest
from deeptutor.multi_user.context import (
get_current_user_or_none,
reset_current_user,
set_current_user,
)
from deeptutor.multi_user.models import CurrentUser, UserScope
from deeptutor.services.embedding.config import EmbeddingConfig
from deeptutor.services.llm.exceptions import LLMAPIError, LLMAuthenticationError
from deeptutor.services.parsing.types import ParsedDocument
from deeptutor.services.rag.factory import get_pipeline, list_pipelines, normalize_provider_name
from deeptutor.services.rag.index_versioning import list_kb_versions
from deeptutor.services.rag.pipelines.lightrag import config, engine, indexing_policy, storage
from deeptutor.services.rag.pipelines.lightrag.ingress import (
IngressError,
bundles_root,
freeze_document,
load_verified_bundle,
pending_root,
)
from deeptutor.services.rag.pipelines.lightrag.pipeline import (
BatchOutcome,
LightRagBatchError,
LightRagNeedsReindexError,
LightRagPipeline,
)
REQUIRES_LIGHTRAG = pytest.mark.skipif(
importlib.util.find_spec("lightrag") is None,
reason="requires the optional rag-lightrag extra",
)
@pytest.fixture(autouse=True)
def _active_embedding(monkeypatch: pytest.MonkeyPatch) -> None:
from deeptutor.services.embedding.config import EmbeddingConfig
cfg = EmbeddingConfig(model="test-embedding", dim=3, api_key="test-key")
monkeypatch.setattr("deeptutor.services.embedding.get_embedding_config", lambda: cfg)
class _Bridge:
def __init__(self) -> None:
self.calls = 0
def raise_if_cancelled(self) -> None:
return None
async def run(self, factory):
self.calls += 1
return await factory()
async def call(self, callback, *args):
self.calls += 1
value = callback(*args)
return await value if inspect.isawaitable(value) else value
@pytest.fixture(autouse=True)
def _isolate_role_revalidation(monkeypatch):
# Lifecycle tests use synthetic policies; real catalog/access revalidation
# is covered by test_lightrag_roles and test_lightrag_indexing_policy.
monkeypatch.setattr(indexing_policy, "revalidate_snapshot", lambda snapshot: snapshot)
def _indexing_snapshot():
return types.SimpleNamespace(
embedding_config=EmbeddingConfig(
model="embed-one", api_key="fake", dim=3, base_url="https://embed.test/v1"
),
vision_available=True,
image_analysis=None,
target_bound=False,
persisted_policy=lambda: {"policy": "pinned", "fingerprint": "a" * 64},
)
def test_factory_routes_without_importing_optional_sdk(tmp_path: Path, monkeypatch) -> None:
sys.modules.pop("lightrag", None)
pipeline = get_pipeline("lightrag", kb_base_dir=str(tmp_path))
assert isinstance(pipeline, LightRagPipeline)
assert "lightrag" not in sys.modules
monkeypatch.setattr(config, "is_lightrag_available", lambda: False)
entry = next(item for item in list_pipelines() if item["id"] == "lightrag")
assert entry["configured"] is False
assert normalize_provider_name("LightRAG") == "lightrag"
@pytest.mark.parametrize(
("value", "expected"),
[("MIX", "mix"), ("local", "local"), (None, "hybrid"), ("invalid", "hybrid")],
)
def test_normalize_mode(value, expected) -> None:
assert config.normalize_mode(value) == expected
def test_availability_checks_native_lightrag_module(monkeypatch) -> None:
seen: list[str] = []
def find_spec(name: str):
seen.append(name)
return None
monkeypatch.setattr(config.importlib.util, "find_spec", find_spec)
assert config.is_lightrag_available() is False
assert seen == ["lightrag"]
@pytest.mark.parametrize(
("settings", "expected"),
[
({}, None),
(
{"llm_profile_id": " profile ", "llm_model_id": " model "},
{"profile_id": "profile", "model_id": "model"},
),
({"llm_profile_id": "profile", "llm_model_id": ""}, None),
],
)
def test_released_lightrag_query_selection_keeps_fallback_contract(
monkeypatch, settings, expected
) -> None:
monkeypatch.setattr("deeptutor.services.config.load_lightrag_settings", lambda: settings)
assert config.lightrag_llm_selection_from_settings() == expected
def test_indexing_selection_rejects_partial_released_setting(monkeypatch) -> None:
monkeypatch.setattr(
"deeptutor.services.config.load_lightrag_settings",
lambda: {"llm_profile_id": "profile", "llm_model_id": ""},
)
with pytest.raises(ValueError, match="incomplete"):
config.lightrag_indexing_selection_from_settings()
def test_query_model_resolver_falls_back_only_when_selected_entry_is_missing(
monkeypatch,
) -> None:
selection = {"profile_id": "profile", "model_id": "model"}
fallback = object()
calls: list[object] = []
monkeypatch.setattr(config, "lightrag_llm_selection_from_settings", lambda: selection)
active = {"profile_id": "active-profile", "model_id": "active-model"}
monkeypatch.setattr(indexing_policy, "_active_catalog_selection", lambda: active)
def resolve(value):
calls.append(value)
if value is selection:
raise ValueError("missing")
return fallback
monkeypatch.setattr(
"deeptutor.services.model_selection.runtime.resolve_llm_config_for_selection",
resolve,
)
assert config.resolve_lightrag_query_llm_config() is fallback
assert calls == [selection, active]
def test_lightrag_llm_adapter_uses_explicit_snapshot_config(monkeypatch) -> None:
captured = {}
def build_model(config, *, allow_multimodal):
assert config is selected_config
assert allow_multimodal is False
async def model_func(_prompt, **kwargs):
captured.update(kwargs)
assert kwargs["max_retries"] == 0
return "ok"
return model_func
selected_config = object()
monkeypatch.setattr("deeptutor.services.llm.client.build_model_func_for_config", build_model)
adapter = config.build_llm_model_func(llm_config=selected_config)
assert (
asyncio.run(
adapter(
"prompt",
response_format={"type": "json_object"},
enable_cot=True,
stream=False,
_priority=3,
hashing_kv=object(),
)
)
== "ok"
)
assert captured["response_format"] == {"type": "json_object"}
assert "enable_cot" not in captured
assert "stream" not in captured
assert "_priority" not in captured
assert "hashing_kv" not in captured
def test_lightrag_vision_adapter_uses_explicit_snapshot_config(monkeypatch) -> None:
captured = {}
def build_model(config, *, allow_multimodal):
assert config is selected_config
assert allow_multimodal is True
async def model_func(_prompt, **kwargs):
captured.update(kwargs)
assert kwargs["allow_image_fallback"] is False
assert kwargs["image_data"] == "sentinel"
return "ok"
return model_func
selected_config = object()
monkeypatch.setattr("deeptutor.services.llm.client.build_model_func_for_config", build_model)
adapter = config.build_vision_model_func(llm_config=selected_config)
assert (
asyncio.run(
adapter(
"prompt",
image_inputs=[{"base64": "sentinel"}],
response_format={"type": "json_object"},
stream=False,
_priority=3,
hashing_kv=object(),
)
)
== "ok"
)
assert captured["response_format"] == {"type": "json_object"}
assert "stream" not in captured
assert "_priority" not in captured
assert "hashing_kv" not in captured
@pytest.mark.parametrize("role", ["user", "admin"])
@pytest.mark.parametrize("fail", [False, True])
def test_explicit_adapter_installs_owner_scope_and_restores_ambient_scope(
monkeypatch, tmp_path: Path, role: str, fail: bool
) -> None:
owner = CurrentUser(
id=f"owner-{role}",
username=f"owner-{role}",
role=role,
scope=UserScope(kind=role, user_id=f"owner-{role}", root=tmp_path / "owner"),
)
ambient = CurrentUser(
id="ambient",
username="ambient",
role="user",
scope=UserScope(kind="user", user_id="ambient", root=tmp_path / "ambient"),
)
def build_model(_config, *, allow_multimodal):
assert allow_multimodal is False
async def model_func(_prompt, **_kwargs):
assert get_current_user_or_none() == owner
if fail:
raise RuntimeError("provider failed")
return "ok"
return model_func
monkeypatch.setattr("deeptutor.services.llm.client.build_model_func_for_config", build_model)
adapter = config.build_llm_model_func(llm_config=object(), owner=owner)
token = set_current_user(ambient)
try:
if fail:
with pytest.raises(RuntimeError, match="provider failed"):
asyncio.run(adapter("prompt"))
else:
assert asyncio.run(adapter("prompt")) == "ok"
assert get_current_user_or_none() == ambient
finally:
reset_current_user(token)
def test_build_rag_keeps_indexing_snapshot_out_of_embedding_kwargs(
monkeypatch, tmp_path: Path
) -> None:
"""The 1.6 native adapter must not pass LLM-only kwargs to embedding."""
class NativeLightRag:
def __init__(self, **kwargs) -> None:
self.kwargs = kwargs
fake_lightrag = types.ModuleType("lightrag")
fake_lightrag.__path__ = [] # type: ignore[attr-defined]
fake_roles = types.ModuleType("lightrag.llm_roles")
class RoleLLMConfig:
def __init__(self, **kwargs) -> None:
self.__dict__.update(kwargs)
fake_roles.RoleLLMConfig = RoleLLMConfig # type: ignore[attr-defined]
monkeypatch.setitem(sys.modules, "lightrag", fake_lightrag)
monkeypatch.setitem(sys.modules, "lightrag.llm_roles", fake_roles)
monkeypatch.setattr(engine, "_require_exact_version", lambda: None)
monkeypatch.setattr(engine, "_register_parser", lambda: None)
monkeypatch.setattr(engine, "_controlled_class", lambda: NativeLightRag)
monkeypatch.setattr(engine, "indexing_kwargs_from_settings", dict)
monkeypatch.setattr(engine, "constructor_kwargs_from_settings", dict)
query_config = types.SimpleNamespace(binding="openai")
from deeptutor.services.rag.pipelines.lightrag import roles
monkeypatch.setattr(
roles,
"resolve_query_roles",
lambda: {role: roles.RoleCall(query_config, None, 4, 240) for role in ("keyword", "query")},
)
monkeypatch.setattr(indexing_policy, "cache_identity_for_config", lambda _config: "query-id")
llm_calls: list[dict[str, object]] = []
embedding_calls: list[object] = []
def build_llm(**kwargs):
llm_calls.append(kwargs)
return "llm"
def build_embedding(*, io_bridge=None):
embedding_calls.append(io_bridge)
return "embedding"
monkeypatch.setattr(engine, "build_llm_model_func", build_llm)
monkeypatch.setattr(engine, "build_embedding_func", build_embedding)
rag = engine.build_rag(tmp_path)
assert llm_calls == [{"llm_config": query_config, "owner": None}] * 3
assert embedding_calls == [None]
assert rag.kwargs["embedding_func"] == "embedding"
@REQUIRES_LIGHTRAG
def test_distribution_identity_is_exact_stable() -> None:
assert engine.installed_version() == "1.5.7"
assert engine.LIGHTRAG_DISTRIBUTION == "lightrag-hku"
def test_preflight_rejects_a_different_installed_lightrag_version(monkeypatch) -> None:
from deeptutor.services.rag import preflight
monkeypatch.setattr(config, "is_lightrag_available", lambda: True)
monkeypatch.setattr(engine, "installed_version", lambda: "1.5.8")
monkeypatch.setattr(preflight, "_active_embedding", lambda: ("embedding", 3))
monkeypatch.setattr(preflight, "_active_chat_model", lambda: ("chat", "openai"))
report = preflight._lightrag_preflight()
package = next(check for check in report["checks"] if check["key"] == "package")
assert package["ok"] is False
assert package["detail"] == "Found 1.5.8; required 1.5.7."
def test_workspace_is_stable_and_version_specific(tmp_path: Path) -> None:
first = engine.workspace_for(tmp_path / "version-1")
assert first == engine.workspace_for(tmp_path / "version-1")
assert first != engine.workspace_for(tmp_path / "version-2")
assert first.startswith("deeptutor_")
def _resolver(tmp_path: Path):
cls = engine._controlled_class()
rag = object.__new__(cls)
rag.working_dir = str(tmp_path)
return rag
@REQUIRES_LIGHTRAG
def test_source_resolver_only_reads_version_ingress(tmp_path: Path, monkeypatch) -> None:
pending = pending_root(tmp_path)
pending.mkdir(parents=True)
expected = pending / "doc.pdf"
expected.write_bytes(b"right")
decoy = tmp_path / "decoy"
decoy.mkdir()
(decoy / "doc.pdf").write_bytes(b"wrong")
monkeypatch.chdir(decoy)
rag = _resolver(tmp_path)
assert rag._resolve_source_file_for_parser("doc.pdf", parser_engine="deeptutor") == str(
expected.resolve()
)
@REQUIRES_LIGHTRAG
@pytest.mark.parametrize("bad", ["../doc.pdf", "/tmp/doc.pdf", "nested/doc.pdf"])
def test_source_resolver_rejects_noncanonical_paths(tmp_path: Path, bad: str) -> None:
rag = _resolver(tmp_path)
with pytest.raises(IngressError):
rag._resolve_source_file_for_parser(bad, parser_engine="deeptutor")
@REQUIRES_LIGHTRAG
def test_source_resolver_rejects_symlink_and_ambiguity(tmp_path: Path) -> None:
pending = pending_root(tmp_path)
archived = pending / "__parsed__"
archived.mkdir(parents=True)
outside = tmp_path / "outside.pdf"
outside.write_bytes(b"outside")
(pending / "doc.pdf").symlink_to(outside)
rag = _resolver(tmp_path)
with pytest.raises(IngressError, match="missing"):
rag._resolve_source_file_for_parser("doc.pdf", parser_engine="deeptutor")
(pending / "doc.pdf").unlink()
(pending / "doc.pdf").write_bytes(b"one")
(archived / "doc.pdf").write_bytes(b"two")
with pytest.raises(IngressError, match="ambiguous"):
rag._resolve_source_file_for_parser("doc.pdf", parser_engine="deeptutor")
@REQUIRES_LIGHTRAG
def test_source_resolver_rejects_other_parser(tmp_path: Path) -> None:
with pytest.raises(IngressError, match="Unsupported parser"):
_resolver(tmp_path)._resolve_source_file_for_parser("doc.pdf", parser_engine="mineru")
def test_vision_adapter_maps_one_base64_unchanged(monkeypatch) -> None:
captured: dict[str, object] = {}
class Client:
def get_vision_model_func(self):
async def call(prompt, **kwargs):
captured["prompt"] = prompt
captured.update(kwargs)
return "seen"
return call
monkeypatch.setattr("deeptutor.services.llm.get_llm_client", lambda: Client())
func = config.build_vision_model_func()
assert asyncio.run(func("describe", image_inputs=[{"base64": "sentinel"}])) == "seen"
assert captured["image_data"] == "sentinel"
assert captured["allow_image_fallback"] is False
@pytest.mark.parametrize(
"value",
[None, [], [{"base64": "a"}, {"base64": "b"}], [{}], ["image"], [{"base64": ""}]],
)
def test_vision_adapter_rejects_invalid_inputs(monkeypatch, value) -> None:
class Client:
def get_vision_model_func(self):
async def call(*_args, **_kwargs):
raise AssertionError("prompt-only fallback must not run")
return call
monkeypatch.setattr("deeptutor.services.llm.get_llm_client", lambda: Client())
with pytest.raises(ValueError):
asyncio.run(config.build_vision_model_func()("describe", image_inputs=value))
@REQUIRES_LIGHTRAG
def test_embedding_adapter_preserves_query_and_document_roles(monkeypatch) -> None:
calls: list[tuple[list[str], str | None]] = []
class EmbeddingConfig:
dim = 3
max_tokens = 99
class Client:
def __init__(self, *, config):
self.config = config
async def embed(self, texts, *, input_type=None):
calls.append((list(texts), input_type))
return [[1, 2, 3] for _ in texts]
monkeypatch.setattr("deeptutor.services.embedding.get_embedding_config", EmbeddingConfig)
monkeypatch.setattr("deeptutor.services.embedding.client.EmbeddingClient", Client)
adapter = config.build_embedding_func()
query = asyncio.run(adapter(["question"], context="query"))
document = asyncio.run(adapter(["passage"], context="document"))
assert query.shape == (1, 3)
assert document.shape == (1, 3)
assert calls == [
(["question"], "search_query"),
(["passage"], "search_document"),
]
def test_llm_adapter_retries_only_transient_failures(monkeypatch) -> None:
attempts = 0
sleeps: list[float] = []
class Client:
def get_model_func(self):
async def call(_prompt, **kwargs):
nonlocal attempts
attempts += 1
assert kwargs["max_retries"] == 0
if attempts < 3:
raise LLMAPIError("temporary", status_code=503)
return "ok"
return call
async def sleep(delay: float) -> None:
sleeps.append(delay)
monkeypatch.setattr("deeptutor.services.llm.get_llm_client", Client)
monkeypatch.setattr(config.asyncio, "sleep", sleep)
assert asyncio.run(config.build_llm_model_func()("prompt")) == "ok"
assert attempts == 3
assert sleeps == [1.0, 2.0]
def test_llm_adapter_does_not_retry_authentication_failure(monkeypatch) -> None:
error = LLMAuthenticationError("unauthorized")
attempts = 0
class Client:
def get_model_func(self):
async def call(_prompt, **_kwargs):
nonlocal attempts
attempts += 1
raise error
return call
monkeypatch.setattr("deeptutor.services.llm.get_llm_client", Client)
with pytest.raises(LLMAuthenticationError) as caught:
asyncio.run(config.build_llm_model_func()("prompt"))
assert caught.value is error
assert attempts == 1
def test_preparse_runs_once_and_bundle_ignores_later_parser_drift(
monkeypatch, tmp_path: Path
) -> None:
source = tmp_path / "source.md"
source.write_text("original source", encoding="utf-8")
calls = 0
class ParseService:
def parse(self, _path):
nonlocal calls
calls += 1
return ParsedDocument(
markdown="frozen markdown",
engine="text_only",
source_hash="source-hash",
parser_signature="parser-v1",
)
monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", ParseService)
monkeypatch.setattr(config, "vision_model_available", lambda: False)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path / "kb"))
staged, failures = pipeline._stage_documents(
tmp_path / "version-1", [str(source)], vision_available=True
)
source.write_text("changed after staging", encoding="utf-8")
manifest, bundle = load_verified_bundle(tmp_path / "version-1", "source.md")
assert calls == 1
assert failures == {}
assert len(staged) == 1
assert (bundle / manifest["markdown"]["path"]).read_text() == "frozen markdown"
assert staged[0].source_path.read_text() == "original source"
class _QueryRag:
def __init__(self, result) -> None:
self.result = result
self.calls = 0
self.param = None
async def aquery_llm(self, _question, *, param):
self.calls += 1
self.param = param
return self.result
def _query_result() -> dict:
return {
"status": "success",
"llm_response": {"is_streaming": False, "content": "answer"},
"data": {
"chunks": [
{
"chunk_id": "c1",
"content": "x" * 500,
"reference_id": "r1",
"page": 2,
}
],
"entities": [
{
"entity_name": "Euler",
"entity_type": "person",
"description": "entity body",
"source_id": "c1",
"reference_id": "r1",
}
],
"relationships": [
{
"src_id": "Euler",
"tgt_id": "Identity",
"description": "relationship body",
"keywords": ["math"],
"weight": 3.5,
"source_id": "c1",
"reference_id": "r1",
}
],
"references": [{"reference_id": "r1", "file_path": "notes.pdf"}],
},
"metadata": {"keywords": {"high_level": ["math"]}, "processing_info": {"chunks": 1}},
}
@REQUIRES_LIGHTRAG
def test_query_uses_one_call_and_preserves_complete_sources(monkeypatch) -> None:
monkeypatch.setattr(engine, "query_kwargs_from_settings", lambda: {})
rag = _QueryRag(_query_result())
answer, sources = asyncio.run(engine.query_with_sources(rag, "q", "hybrid"))
assert rag.calls == 1
assert rag.param.stream is False
assert answer == "answer"
assert sources[0]["content"] == "x" * 500
assert sources[0]["kind"] == "chunk"
assert sources[1]["entity_name"] == "Euler"
assert sources[2]["weight"] == 3.5
assert "score" not in sources[2]
assert sources[3]["kind"] == "reference"
assert sources[3]["reference"] == {"reference_id": "r1", "file_path": "notes.pdf"}
assert sources[-1]["metadata"]["processing_info"] == {"chunks": 1}
@REQUIRES_LIGHTRAG
@pytest.mark.parametrize(
"result",
[
{"status": "failure", "message": "retrieval failed"},
{"status": "success", "llm_response": {}, "data": {}, "metadata": {}},
{
"status": "success",
"llm_response": {"is_streaming": True, "content": "x"},
"data": {},
"metadata": {},
},
"not an object",
],
)
def test_query_rejects_failure_and_malformed_envelopes(result) -> None:
with pytest.raises(engine.LightRagContractError):
asyncio.run(engine.query_with_sources(_QueryRag(result), "q"))
@REQUIRES_LIGHTRAG
def test_storage_publishes_schema_two_metadata(tmp_path: Path, monkeypatch) -> None:
(tmp_path / "kv_store_doc_status.json").write_text(
json.dumps({"id": {"status": "processed", "chunks_list": ["c"]}}), encoding="utf-8"
)
monkeypatch.setattr(
"deeptutor.services.rag.embedding_signature.embedding_meta_fields",
lambda: {"embedding": "e"},
)
storage.write_meta(tmp_path)
meta = json.loads((tmp_path / "meta.json").read_text(encoding="utf-8"))
assert meta["state"] == "published"
assert meta["lightrag_adapter_schema"] == 2
assert meta["lightrag_package_version"] == "1.5.7"
assert meta["parser_inputs"] == []
assert storage.meta_is_native_published(tmp_path) is True
def test_flat_schema_two_candidate_fails_closed_until_published(tmp_path: Path) -> None:
version = tmp_path / "version-1"
version.mkdir()
(version / "kv_store_doc_status.json").write_text(
json.dumps({"id": {"status": "processed", "chunks_list": ["c"]}}), encoding="utf-8"
)
(version / "meta.json").write_text(
json.dumps({"provider": "lightrag", "signature": "lightrag", "lightrag_adapter_schema": 2}),
encoding="utf-8",
)
assert list_kb_versions(tmp_path)[0]["ready"] is False
payload = json.loads((version / "meta.json").read_text())
payload["state"] = "published"
(version / "meta.json").write_text(json.dumps(payload), encoding="utf-8")
assert list_kb_versions(tmp_path)[0]["ready"] is True
def _write_published_version(root: Path, *, indexing_policy_value: dict | None = None) -> None:
from deeptutor.services.rag.embedding_signature import embedding_meta_fields
root.mkdir(parents=True)
(root / "kv_store_doc_status.json").write_text(
json.dumps({"doc": {"status": "processed", "chunks_list": ["chunk"]}}),
encoding="utf-8",
)
(root / "meta.json").write_text(
json.dumps(
{
"provider": "lightrag",
"signature": "lightrag",
"lightrag_adapter_schema": storage.ADAPTER_SCHEMA,
"parser_bridge_schema": 1,
"state": "published",
"indexing_policy": indexing_policy_value or {"policy": "legacy_unpinned"},
**embedding_meta_fields(),
}
),
encoding="utf-8",
)
def test_rebuild_failure_before_index_output_keeps_previous_published_version(
tmp_path: Path, monkeypatch
) -> None:
kb_dir = tmp_path / "kb"
old = kb_dir / "version-1"
_write_published_version(old)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
async def fail_before_output(*_args, **_kwargs):
raise RuntimeError("indexing failed")
monkeypatch.setattr(pipeline, "_run_indexing", fail_before_output)
with pytest.raises(RuntimeError, match="indexing failed"):
asyncio.run(
pipeline.initialize(
"kb",
[str(tmp_path / "doc.md")],
indexing_snapshot=_indexing_snapshot(),
)
)
assert storage.latest_published_root(kb_dir) == old
assert not (kb_dir / "version-2").exists()
def test_atomic_meta_failure_leaves_new_candidate_unpublished(tmp_path: Path, monkeypatch) -> None:
kb_dir = tmp_path / "kb"
old = kb_dir / "version-1"
_write_published_version(old)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
async def finish_index(root: Path, *_args, **_kwargs):
(root / "kv_store_doc_status.json").write_text(
json.dumps({"new": {"status": "processed", "chunks_list": ["chunk"]}}),
encoding="utf-8",
)
return BatchOutcome(
requested=1,
accepted=1,
processed=("doc.md",),
indexing_policy={"policy": "legacy_unpinned"},
)
def fail_meta(*_args, **_kwargs):
raise OSError("atomic publication failed")
monkeypatch.setattr(pipeline, "_run_indexing", finish_index)
monkeypatch.setattr(storage, "write_meta", fail_meta)
with pytest.raises(OSError, match="atomic publication failed"):
asyncio.run(
pipeline.initialize(
"kb",
[str(tmp_path / "doc.md")],
indexing_snapshot=_indexing_snapshot(),
)
)
candidate = kb_dir / "version-2"
assert candidate.is_dir()
assert not (candidate / "meta.json").exists()
assert storage.latest_published_root(kb_dir) == old
def test_append_metadata_refresh_failure_preserves_published_success(
tmp_path: Path, monkeypatch
) -> None:
kb_dir = tmp_path / "kb"
published = kb_dir / "version-1"
_write_published_version(
published,
indexing_policy_value={
"policy": "pinned",
"selection": {"profile_id": "profile", "model_id": "model"},
"fingerprint": "a" * 64,
},
)
original_meta = (published / "meta.json").read_bytes()
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
async def finish_index(*_args, **_kwargs):
return BatchOutcome(
requested=1,
accepted=1,
processed=("doc.md",),
indexing_policy={"policy": "legacy_unpinned"},
)
monkeypatch.setattr(pipeline, "_run_indexing", finish_index)
monkeypatch.setattr(
indexing_policy,
"snapshot_from_persisted",
lambda _policy: _indexing_snapshot(),
)
monkeypatch.setattr(
storage,
"write_meta",
lambda *_args, **_kwargs: (_ for _ in ()).throw(OSError("metadata unavailable")),
)
assert asyncio.run(pipeline.add_documents("kb", [str(tmp_path / "doc.md")])) is True
assert (published / "meta.json").read_bytes() == original_meta
def test_append_rejects_legacy_unpinned_index_before_mutation(tmp_path: Path, monkeypatch) -> None:
published = tmp_path / "kb" / "version-1"
_write_published_version(published)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
async def unexpected(*_args, **_kwargs):
raise AssertionError("legacy append must not reach indexing")
monkeypatch.setattr(pipeline, "_run_indexing", unexpected)
with pytest.raises(indexing_policy.IndexingModelChangedError, match="full re-index"):
asyncio.run(pipeline.add_documents("kb", [str(tmp_path / "doc.md")]))
def test_append_rejects_explicit_indexing_snapshot_before_mutation(
tmp_path: Path, monkeypatch
) -> None:
published = tmp_path / "kb" / "version-1"
_write_published_version(published)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
async def unexpected(*_args, **_kwargs):
raise AssertionError("append must not reach indexing")
monkeypatch.setattr(pipeline, "_run_indexing", unexpected)
with pytest.raises(indexing_policy.IndexingPolicyError, match="full re-index"):
asyncio.run(
pipeline.add_documents(
"kb",
[str(tmp_path / "doc.md")],
indexing_snapshot=_indexing_snapshot(),
)
)
def test_first_index_uses_defaults_instead_of_creation_time_pending_policy(tmp_path, monkeypatch):
kb_dir = tmp_path / "kb"
kb_dir.mkdir()
(tmp_path / "kb_config.json").write_text(
json.dumps(
{
"knowledge_bases": {
"kb": {
"pending_indexing_policy": {
"policy": "pending_pinned",
"fingerprint": "stale",
},
}
}
}
)
)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
snapshot = _indexing_snapshot()
monkeypatch.setattr(
"deeptutor.services.rag.pipelines.lightrag.pipeline.freeze_default_snapshot",
lambda: snapshot,
)
monkeypatch.setattr(
indexing_policy,
"snapshot_from_persisted",
lambda _: pytest.fail("restored old empty policy"),
)
async def check_defaults(_root, _files, _progress, accepted, **_kwargs):
assert accepted is snapshot
raise RuntimeError("checked defaults before provider call")
monkeypatch.setattr(pipeline, "_run_indexing", check_defaults)
with pytest.raises(RuntimeError, match="checked defaults"):
asyncio.run(pipeline.initialize("kb", [str(tmp_path / "doc.md")]))
assert not any(kb_dir.glob("version-*"))
def test_schema_two_metadata_without_processed_workspace_output_is_not_ready(
tmp_path: Path,
) -> None:
version = tmp_path / "version-1"
workspace = version / "workspace"
workspace.mkdir(parents=True)
(version / "meta.json").write_text(
json.dumps(
{
"provider": "lightrag",
"signature": "lightrag",
"lightrag_adapter_schema": 2,
"state": "published",
"workspace": "workspace",
}
),
encoding="utf-8",
)
(workspace / "kv_store_doc_status.json").write_text(
json.dumps({"id": {"status": "failed", "chunks_list": []}}), encoding="utf-8"
)
assert list_kb_versions(tmp_path)[0]["ready"] is False
def test_legacy_flat_metadata_stays_visible_but_requires_reindex(tmp_path: Path) -> None:
version = tmp_path / "version-1"
version.mkdir()
(version / "kv_store_doc_status.json").write_text(
json.dumps({"id": {"status": "processed", "chunks_list": ["c"]}}), encoding="utf-8"
)
(version / "meta.json").write_text(
json.dumps({"provider": "lightrag", "signature": "lightrag"}), encoding="utf-8"
)
assert list_kb_versions(tmp_path)[0]["ready"] is True
assert storage.meta_is_native_published(version) is False
def test_batch_outcome_only_completes_all_processed() -> None:
assert BatchOutcome(requested=1, accepted=1, processed=("a",)).complete is True
assert BatchOutcome(requested=2, accepted=1, processed=("a",), missing=("b",)).complete is False
def test_reconcile_counts_terminal_rows_and_missing(tmp_path: Path) -> None:
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
pipeline._status_no_progress_seconds = 0
staged = [types.SimpleNamespace(canonical_name="a.pdf", audit_ledger=None)]
class Rag:
working_dir = str(tmp_path)
async def aget_docs_by_track_id(self, _track):
return {"doc-a": types.SimpleNamespace(file_path="a.pdf", status="processed")}
outcome = asyncio.run(
pipeline._reconcile(Rag(), staged, {"bad.pdf": "parse failed"}, "track", _Bridge(), None)
)
assert outcome.accepted == 1
assert outcome.processed == ("a.pdf",)
assert outcome.preflight_failed == {"bad.pdf": "parse failed"}
assert outcome.complete is False
def test_indexing_initializes_processes_reconciles_and_finalizes(
tmp_path: Path, monkeypatch
) -> None:
events: list[object] = []
staged = types.SimpleNamespace(canonical_name="doc.pdf", process_options="F", audit_ledger=None)
class Rag:
working_dir = str(tmp_path)
async def apipeline_process_enqueue_documents(self):
events.append("process")
async def aget_docs_by_track_id(self, track_id):
assert track_id == "track-1"
return {"doc-id": types.SimpleNamespace(file_path="doc.pdf", status="processed")}
rag = Rag()
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
snapshot = _indexing_snapshot()
freeze_calls = 0
def freeze_default():
nonlocal freeze_calls
freeze_calls += 1
return snapshot
def stage(*_args, **kwargs):
assert kwargs["vision_available"] is True
return [staged], {}
def build(*_args, **kwargs):
assert kwargs["indexing_snapshot"] is snapshot
return rag
monkeypatch.setattr(
"deeptutor.services.rag.pipelines.lightrag.pipeline.freeze_default_snapshot",
freeze_default,
)
monkeypatch.setattr(pipeline, "_stage_documents", stage)
monkeypatch.setattr(engine, "build_rag", build)
async def initialize(_rag):
events.append("initialize")
async def enqueue(_rag, documents):
assert documents == [staged]
events.append("enqueue")
return "track-1"
async def finalize(_rag, *, cancel_pending):
events.append(("finalize", cancel_pending))
monkeypatch.setattr(engine, "initialize", initialize)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", finalize)
outcome = asyncio.run(pipeline._run_indexing(tmp_path, ["doc.pdf"], None))
assert outcome.complete is True
assert freeze_calls == 1
assert outcome.indexing_policy == {"policy": "pinned", "fingerprint": "a" * 64}
assert events == ["initialize", "enqueue", "process", ("finalize", False)]
def test_partial_failure_is_typed_and_finalizes_with_cancellation(
tmp_path: Path, monkeypatch
) -> None:
events: list[object] = []
staged = types.SimpleNamespace(canonical_name="bad.pdf", process_options="F", audit_ledger=None)
class Rag:
working_dir = str(tmp_path)
async def apipeline_process_enqueue_documents(self):
return None
async def aget_docs_by_track_id(self, _track_id):
return {
"doc-id": types.SimpleNamespace(
file_path="bad.pdf", status="failed", error_msg="parse failed"
)
}
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_stage_documents", lambda *_args, **_kwargs: ([staged], {}))
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: Rag())
async def no_op(*_args, **_kwargs):
return None
async def enqueue(*_args, **_kwargs):
return "track-1"
async def finalize(_rag, *, cancel_pending):
events.append(("finalize", cancel_pending))
monkeypatch.setattr(engine, "initialize", no_op)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", finalize)
with pytest.raises(LightRagBatchError) as caught:
asyncio.run(pipeline._run_indexing(tmp_path, ["bad.pdf"], None, _indexing_snapshot()))
assert caught.value.outcome.failed == {"bad.pdf": "parse failed"}
assert events == [("finalize", True)]
@pytest.mark.parametrize("failure_stage", ["initialize", "enqueue"])
def test_pre_acceptance_failure_removes_ingress_and_allows_same_name_retry(
tmp_path: Path, monkeypatch, failure_stage: str
) -> None:
source = tmp_path / "source" / "doc.md"
source.parent.mkdir()
source.write_text("body", encoding="utf-8")
working = tmp_path / "version-1"
attempt = 0
class Rag:
working_dir = str(working)
class DocStatus:
async def get_docs_by_ids(self, _doc_ids, *, strict):
assert strict is True
return {}
doc_status = DocStatus()
async def apipeline_process_enqueue_documents(self):
return None
async def aget_docs_by_track_id(self, _track_id):
return {"doc-id": types.SimpleNamespace(file_path="doc.md", status="processed")}
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
def stage(_working, paths, **_kwargs):
staged = freeze_document(
working,
Path(paths[0]),
ParsedDocument(markdown="body", engine="text_only"),
)
return [staged], {}
async def initialize(_rag):
if attempt == 0 and failure_stage == "initialize":
raise RuntimeError("initialize rejected")
async def enqueue(_rag, _staged):
if attempt == 0 and failure_stage == "enqueue":
raise RuntimeError("enqueue rejected")
return "track-1"
async def finalize(_rag, *, cancel_pending):
assert cancel_pending is (attempt == 0)
monkeypatch.setattr(pipeline, "_stage_documents", stage)
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: Rag())
monkeypatch.setattr(engine, "_document_id", lambda name: f"doc-{name}")
monkeypatch.setattr(engine, "initialize", initialize)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", finalize)
with pytest.raises(RuntimeError, match=failure_stage):
asyncio.run(pipeline._run_indexing(working, [str(source)], None, _indexing_snapshot()))
assert not (pending_root(working) / "doc.md").exists()
assert not (bundles_root(working) / "doc.md.bundle").exists()
attempt = 1
outcome = asyncio.run(
pipeline._run_indexing(working, [str(source)], None, _indexing_snapshot())
)
assert outcome.complete is True
def test_enqueue_partial_commit_removes_only_confirmed_unaccepted_ingress(
tmp_path: Path, monkeypatch
) -> None:
sources = [tmp_path / "source" / name for name in ("accepted.md", "rejected.md")]
sources[0].parent.mkdir()
for source in sources:
source.write_text(source.stem, encoding="utf-8")
working = tmp_path / "version-1"
status_reads: list[tuple[list[str], bool]] = []
class DocStatus:
async def get_docs_by_ids(self, doc_ids, *, strict):
status_reads.append((doc_ids, strict))
return {doc_ids[0]: types.SimpleNamespace(status="pending")}
class Rag:
working_dir = str(working)
doc_status = DocStatus()
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
def stage(_working, paths, **_kwargs):
return [
freeze_document(
working,
Path(path),
ParsedDocument(markdown=Path(path).stem, engine="text_only"),
)
for path in paths
], {}
async def enqueue(_rag, _staged):
raise RuntimeError("doc_status partially committed")
async def no_op(*_args, **_kwargs):
return None
monkeypatch.setattr(pipeline, "_stage_documents", stage)
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: Rag())
monkeypatch.setattr(engine, "_document_id", lambda name: f"doc-{name}")
monkeypatch.setattr(engine, "initialize", no_op)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", no_op)
with pytest.raises(RuntimeError, match="partially committed"):
asyncio.run(
pipeline._run_indexing(
working,
[str(path) for path in sources],
None,
_indexing_snapshot(),
)
)
assert len(status_reads) == 1
assert status_reads[0][1] is True
assert (pending_root(working) / "accepted.md").is_file()
assert (bundles_root(working) / "accepted.md.bundle").is_dir()
assert not (pending_root(working) / "rejected.md").exists()
assert not (bundles_root(working) / "rejected.md.bundle").exists()
def test_enqueue_status_read_failure_retains_all_ingress(tmp_path: Path, monkeypatch) -> None:
source = tmp_path / "source" / "doc.md"
source.parent.mkdir()
source.write_text("body", encoding="utf-8")
working = tmp_path / "version-1"
class DocStatus:
async def get_docs_by_ids(self, _doc_ids, *, strict):
assert strict is True
raise RuntimeError("status unavailable")
class Rag:
working_dir = str(working)
doc_status = DocStatus()
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
def stage(_working, paths, **_kwargs):
return [
freeze_document(
working,
Path(paths[0]),
ParsedDocument(markdown="body", engine="text_only"),
)
], {}
async def enqueue(_rag, _staged):
raise ValueError("enqueue failed")
async def no_op(*_args, **_kwargs):
return None
monkeypatch.setattr(pipeline, "_stage_documents", stage)
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: Rag())
monkeypatch.setattr(engine, "initialize", no_op)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", no_op)
with pytest.raises(ValueError, match="enqueue failed"):
asyncio.run(pipeline._run_indexing(working, [str(source)], None, _indexing_snapshot()))
assert (pending_root(working) / "doc.md").is_file()
assert (bundles_root(working) / "doc.md.bundle").is_dir()
@pytest.mark.parametrize("operation", ["initialize", "add_documents"])
def test_public_initial_ingestion_retains_uncertain_ingress(
tmp_path: Path, monkeypatch, operation: str
) -> None:
source = tmp_path / "source" / "doc.md"
source.parent.mkdir()
source.write_text("body", encoding="utf-8")
staged_working: Path | None = None
class DocStatus:
async def get_docs_by_ids(self, _doc_ids, *, strict):
assert strict is True
raise RuntimeError("status unavailable")
class Rag:
doc_status = DocStatus()
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path / "knowledge-bases"))
def stage(working, paths, **_kwargs):
nonlocal staged_working
staged_working = working
return [
freeze_document(
working,
Path(paths[0]),
ParsedDocument(markdown="body", engine="text_only"),
)
], {}
async def enqueue(_rag, _staged):
raise ValueError("original enqueue failure")
async def no_op(*_args, **_kwargs):
return None
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
monkeypatch.setattr(pipeline, "_stage_documents", stage)
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: Rag())
monkeypatch.setattr(engine, "initialize", no_op)
monkeypatch.setattr(engine, "enqueue", enqueue)
monkeypatch.setattr(engine, "finalize", no_op)
with pytest.raises(ValueError, match="original enqueue failure"):
asyncio.run(
getattr(pipeline, operation)(
"kb",
[str(source)],
indexing_snapshot=types.SimpleNamespace(
embedding_config=_indexing_snapshot().embedding_config,
vision_available=True,
image_analysis=None,
target_bound=False,
persisted_policy=lambda: {"policy": "legacy_unpinned"},
),
)
)
assert staged_working is not None
assert (pending_root(staged_working) / "doc.md").is_file()
assert (bundles_root(staged_working) / "doc.md.bundle").is_dir()
def test_zero_accepted_candidate_cleanup_removes_empty_version(tmp_path: Path) -> None:
version = tmp_path / "version-1"
pending_root(version).mkdir(parents=True)
bundles_root(version).mkdir(parents=True)
LightRagPipeline(kb_base_dir=str(tmp_path))._remove_zero_accepted_candidate(version)
assert not version.exists()
def test_append_rejects_corrupt_or_unpublished_existing_version(
tmp_path: Path, monkeypatch
) -> None:
version = tmp_path / "kb" / "version-1"
workspace = version / "workspace"
workspace.mkdir(parents=True)
(version / "meta.json").write_text(
json.dumps(
{
"provider": "lightrag",
"signature": "lightrag",
"lightrag_adapter_schema": 2,
"parser_bridge_schema": 1,
"state": "published",
"workspace": "workspace",
}
),
encoding="utf-8",
)
(workspace / "kv_store_doc_status.json").write_text(
json.dumps({"failed": {"status": "failed", "chunks_list": []}}),
encoding="utf-8",
)
before = {
path.relative_to(version): path.read_bytes()
for path in version.rglob("*")
if path.is_file()
}
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
with pytest.raises(LightRagNeedsReindexError, match="unpublished, or corrupt"):
asyncio.run(
pipeline.add_documents(
"kb",
[str(tmp_path / "new.md")],
)
)
assert not (tmp_path / "kb" / "version-2").exists()
assert {
path.relative_to(version): path.read_bytes()
for path in version.rglob("*")
if path.is_file()
} == before
def test_search_failure_is_not_reported_as_empty_success(tmp_path: Path, monkeypatch) -> None:
root = tmp_path / "version-1"
_write_published_version(root)
pipeline = LightRagPipeline(kb_base_dir=str(tmp_path))
monkeypatch.setattr(storage, "latest_published_root", lambda _kb_dir: root)
monkeypatch.setattr(pipeline, "_resolve_mode", lambda *_args: "hybrid")
monkeypatch.setattr(pipeline, "_ensure_available", lambda: None)
monkeypatch.setattr(engine, "build_rag", lambda *_args, **_kwargs: object())
async def no_op(*_args, **_kwargs):
return None
async def fail(*_args, **_kwargs):
raise engine.LightRagContractError("retrieval failed")
monkeypatch.setattr(engine, "initialize", no_op)
monkeypatch.setattr(engine, "query_with_sources", fail)
monkeypatch.setattr(engine, "finalize", no_op)
result = asyncio.run(pipeline.search("question", "kb"))
assert result["content"] == ""
assert result["sources"] == []
assert result["error_type"] == "retrieval_error"
def test_legacy_search_requires_reindex_without_mutating_files(tmp_path: Path) -> None:
kb = tmp_path / "kb"
version = kb / "version-1"
version.mkdir(parents=True)
meta = version / "meta.json"
meta.write_text(json.dumps({"provider": "lightrag", "signature": "lightrag"}), encoding="utf-8")
(version / "kv_store_doc_status.json").write_text(
json.dumps({"id": {"status": "processed", "chunks_list": ["c"]}}),
encoding="utf-8",
)
before = {path.name: path.read_bytes() for path in version.iterdir()}
result = asyncio.run(LightRagPipeline(kb_base_dir=str(tmp_path)).search("q", "kb"))
assert result["needs_reindex"] is True
assert {path.name: path.read_bytes() for path in version.iterdir()} == before