from __future__ import annotations
import os
from pathlib import Path
from typing import TYPE_CHECKING, Any
import pytest
if TYPE_CHECKING:
from matra.types import Identity
matra = pytest.importorskip("matra", reason="matra wheel not built")
PARAPHRASE_A = "The cat sat on the mat."
PARAPHRASE_B = "A cat was sitting on the mat."
UNRELATED = "Quarterly revenue exceeded every forecast."
VECTORS = {
"sat": [1.0, 0.0, 0.0],
"sitting": [0.9987, 0.05, 0.0],
"revenue": [0.0, 0.0, 1.0],
}
class FakeEmbedder:
def identity(self) -> Identity:
return {"name": "fake-embedder", "model": "v1", "sha256": None, "license": "MIT"}
def embed(self, texts: list[str]) -> list[list[float]]:
out = []
for text in texts:
lowered = text.lower()
match = next((v for k, v in VECTORS.items() if k in lowered), None)
out.append(match if match is not None else [0.0, 1.0, 0.0])
return out
@pytest.mark.model
def test_a_python_object_is_an_embedder(engine: Any) -> None:
doc = engine.analyze(f"{PARAPHRASE_A} {PARAPHRASE_B} {UNRELATED}")
result = matra.clusters(doc, FakeEmbedder(), 0.9)
assert result["provenance"]["parameters"]["embedder"] == {
"name": "fake-embedder",
"model": "v1",
"sha256": None,
"license": "MIT",
}
assert result["provenance"]["parameters"]["threshold"] == 0.9
assert result["provenance"]["method"] == "cosine"
assert len(result["clusters"]) == 1
assert result["clusters"][0]["members"] == [0, 1]
assert len(result["edges"]) == 1
assert result["edges"][0]["score"] > 0.99
@pytest.mark.model
def test_wrong_vector_count_raises_the_same_message_a_rust_caller_gets(
engine: Any,
) -> None:
seen: list[int] = []
class ShortEmbedder:
def identity(self) -> Identity:
return {"name": "short-embedder", "model": None, "sha256": None, "license": None}
def embed(self, texts: list[str]) -> list[list[float]]:
seen.append(len(texts))
return [[1.0, 0.0, 0.0]] * (len(texts) - 1)
with pytest.raises(ValueError) as excinfo:
matra.clusters(engine.analyze(f"{PARAPHRASE_A} {UNRELATED}"), ShortEmbedder(), 0.9)
assert seen == [2]
assert str(excinfo.value) == (
"invalid input: embedder returned 1 vector for 2 sentences, violating its contract"
)
@pytest.mark.model
def test_an_exception_inside_embed_surfaces_with_its_own_text(engine: Any) -> None:
class BoomEmbedder:
def identity(self) -> Identity:
return {"name": "boom-embedder", "model": None, "sha256": None, "license": None}
def embed(self, texts: list[str]) -> list[list[float]]:
raise KeyError("no vectors cached for this batch")
with pytest.raises(ValueError) as excinfo:
matra.clusters(engine.analyze(PARAPHRASE_A), BoomEmbedder(), 0.9)
message = str(excinfo.value)
assert "no vectors cached for this batch" in message
assert "embed()" in message
@pytest.mark.model
def test_a_shape_violation_names_the_level_that_was_wrong(engine: Any) -> None:
class ScalarEmbedder:
def identity(self) -> Identity:
return {"name": "scalar-embedder", "model": None, "sha256": None, "license": None}
def embed(self, texts: list[str]) -> list[list[float]]:
return 42
with pytest.raises(ValueError) as excinfo:
matra.clusters(engine.analyze(PARAPHRASE_A), ScalarEmbedder(), 0.9)
assert "must return a sequence of vectors" in str(excinfo.value)
@pytest.mark.model
def test_an_embedder_without_identity_is_refused_before_any_work(
engine: Any,
) -> None:
class Nameless:
def embed(self, texts: list[str]) -> list[list[float]]:
raise AssertionError("embed must not be called")
with pytest.raises(ValueError) as excinfo:
matra.clusters(engine.analyze(PARAPHRASE_A), Nameless(), 0.9)
assert "identity()" in str(excinfo.value)
@pytest.mark.model
def test_an_identity_that_is_not_the_parsers_shape_is_refused(engine: Any) -> None:
class Stringly:
def identity(self) -> str:
return "a-bare-string"
def embed(self, texts: list[str]) -> list[list[float]]:
raise AssertionError("embed must not be called")
doc = engine.analyze(PARAPHRASE_A)
with pytest.raises(matra.InvalidInputError) as excinfo:
matra.clusters(doc, Stringly(), 0.9) assert "identity()" in str(excinfo.value)
class NameOnly(FakeEmbedder):
def identity(self) -> Identity:
return {"name": "name-only"}
result = matra.clusters(doc, NameOnly(), 0.9)
assert result["provenance"]["parameters"]["embedder"] == {
"name": "name-only",
"model": None,
"sha256": None,
"license": None,
}
def item_path(item: Any) -> str | None:
if isinstance(item, matra.Document):
path: str | None = item["provenance"]["source"]["path"]
return path
path = item["path"]
return path
@pytest.mark.model
def test_a_directory_yields_one_item_per_file_in_order(engine: Any, tmp_path: Path) -> None:
(tmp_path / "a.txt").write_text("The committee approved the proposal.")
(tmp_path / "b.txt").write_bytes(b"\xff\xfe not valid utf-8")
(tmp_path / "c.txt").write_text("The report was filed without comment.")
items = list(engine.analyze_all(dir=str(tmp_path)))
assert len(items) == 3
assert [Path(item_path(item) or "").name for item in items] == ["a.txt", "b.txt", "c.txt"]
assert isinstance(items[0], matra.Document)
assert items[0]["sections"][0]["paragraphs"][0]["sentences"]
assert not isinstance(items[1], matra.Document)
assert items[1]["kind"] == "unsupported_format"
assert items[1]["message"]
assert items[1]["details"] == {}
assert isinstance(items[2], matra.Document)
assert items[2]["metrics"]["passive_ratio"] is not None
@pytest.mark.model
def test_a_markdown_file_is_read_as_markdown(engine: Any, tmp_path: Path) -> None:
path = tmp_path / "notes.md"
path.write_text("# Field notes\n\nThe river rose overnight.\n")
doc = engine.analyze(file=path)
assert doc["provenance"]["format"] == "markdown"
assert doc["sections"][0]["heading"] == "Field notes"
assert doc["metrics"]["total_sentences"] == 1
@pytest.mark.model
def test_a_file_names_itself_in_its_provenance(engine: Any, tmp_path: Path) -> None:
path = tmp_path / "only.txt"
path.write_text("The committee approved the proposal.")
doc = engine.analyze(file=str(path))
assert Path(item_path(doc) or "") == path
@pytest.mark.model
@pytest.mark.skipif(os.name != "posix", reason="only posix filenames carry raw bytes")
def test_a_file_whose_name_is_not_utf_8_is_analyzed_and_round_trips(
engine: Any, tmp_path: Path
) -> None:
name = b"weird-\xff.txt"
raw = os.path.join(os.fsencode(str(tmp_path)), name)
try:
with open(raw, "wb") as f:
f.write(b"The committee approved the proposal.")
except OSError as exc:
pytest.skip(f"this filesystem refuses a non-UTF-8 filename: {exc}")
items = list(engine.analyze_all(dir=tmp_path))
assert len(items) == 1
assert isinstance(items[0], matra.Document)
assert os.fsencode(item_path(items[0]) or "").endswith(name)
assert items[0]["sections"][0]["paragraphs"][0]["sentences"]
@pytest.mark.model
def test_a_non_ascii_filename_round_trips(engine: Any, tmp_path: Path) -> None:
name = "rapport-financiér-ü.txt"
(tmp_path / name).write_text("The committee approved the proposal.")
items = list(engine.analyze_all(dir=tmp_path))
assert len(items) == 1
path = item_path(items[0]) or ""
assert path.endswith(name)
assert os.fsencode(path) == os.fsencode(str(tmp_path / name))
@pytest.mark.model
def test_a_file_takes_a_pathlib_path(engine: Any, tmp_path: Path) -> None:
(tmp_path / "only.txt").write_text("The committee approved the proposal.")
doc = engine.analyze(file=tmp_path / "only.txt")
assert Path(item_path(doc) or "").name == "only.txt"
def test_model2vec_takes_a_pathlib_path(tmp_path: Path) -> None:
with pytest.raises(matra.ModelNotFoundError):
matra.Model2Vec.from_dir(tmp_path / "no-such-model")
@pytest.mark.model
def test_potion_base_8m_takes_the_models_directory(
tmp_path: Path, capfd: pytest.CaptureFixture[str]
) -> None:
models = os.environ.get("MATRA_MODEL_DIR")
source = Path(models or "") / "potion-base-8M"
if not models or not (source / "model.safetensors").is_file():
pytest.skip("needs MATRA_MODEL_DIR holding potion-base-8M")
target = tmp_path / "models" / "potion-base-8M"
target.mkdir(parents=True)
for name in ("model.safetensors", "tokenizer.json", "config.json"):
(target / name).write_bytes((source / name).read_bytes())
capfd.readouterr()
model = matra.Model2Vec.potion_base_8m(tmp_path / "models")
assert model.model_hash == matra.Model2Vec.from_dir(source).model_hash
assert sorted(p.name for p in (tmp_path / "models").iterdir()) == ["potion-base-8M"]
assert capfd.readouterr().err == ""
def test_only_from_config_reads_the_config_file(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
bad = tmp_path / "config.toml"
bad.write_text("this is = not [ toml\n")
models = tmp_path / "models"
(models / "potion-base-8M").mkdir(parents=True)
(models / "potion-base-8M" / "config.json").write_text("{}")
monkeypatch.setenv("MATRA_CONFIG_FILE", str(bad))
monkeypatch.setenv("MATRA_MODEL_DIR", str(models))
with pytest.raises(matra.InvalidInputError) as configured:
matra.Model2Vec.from_config()
assert configured.value.details["reason"] == "config_malformed"
with pytest.raises(matra.ModelInvalidError) as defaulted:
matra.Model2Vec.potion_base_8m()
assert "partial" in str(defaulted.value) or "part of" in str(defaulted.value)
@pytest.mark.model
def test_a_missing_directory_raises(engine: Any, tmp_path: Path) -> None:
with pytest.raises(FileNotFoundError) as excinfo:
engine.analyze_all(dir=str(tmp_path / "no-such-directory"))
assert isinstance(excinfo.value, matra.IoNotFoundError)
assert excinfo.value.kind == "io"
assert excinfo.value.details["io_kind"] == "not_found"
assert "No such file or directory" in str(excinfo.value)
def test_the_new_shapes_are_importable_from_the_package_root() -> None:
from matra import BlockDict, DocumentDict, DocumentError, Embedder, ErrorInfo, Skipped, Span
assert set(DocumentError.__annotations__) == {"path", "kind", "message", "details"}
assert set(DocumentDict.__annotations__) == {"provenance", "sections", "metrics", "skipped"}
assert set(Span.__annotations__) == {"byte_start", "byte_end"}
assert set(Skipped.__annotations__) == {"kind", "span"}
assert set(ErrorInfo.__annotations__) == {"kind", "message", "details"}
assert callable(Embedder.embed) and callable(Embedder.identity)
assert BlockDict is not None
def test_the_builtin_adapter_satisfies_the_embedder_protocol() -> None:
assert callable(matra.Model2Vec.embed)
assert callable(matra.Model2Vec.identity)