Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
"""
Tests for all CLI commands added in issue #568.
Strategy:
- Module-level imports (ingest, kg, etc.) are mocked via monkeypatch so tests
run without optional backends installed.
- Help surfaces: every command/group --help must exit 0 and mention key flags.
- --dry-run: write commands must exit 0 and emit a dry-run message.
- --json: write commands must emit parseable JSON.
- ImportError paths: modules that raise ImportError must produce a clean
ClickException (non-zero exit, no traceback).
- Argument validation: missing required args must exit non-zero cleanly.
- Service commands: subprocess.Popen is mocked so nothing actually launches.
"""
import json
import os
import time
import re
import stat
import sys
import tarfile
import types
from typing import Any
from unittest.mock import MagicMock, patch
import pytest
from click.testing import CliRunner
import semantica.cli as cli_module
# ─── fixtures ─────────────────────────────────────────────────────────────────
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
@pytest.fixture(autouse=True)
def silence_logging(monkeypatch):
monkeypatch.setattr(cli_module, "setup_logging", lambda *a, **kw: None)
def _fake_module(**attrs: Any) -> types.ModuleType:
"""Build a minimal fake module with the given attributes."""
m = types.ModuleType("_fake")
for k, v in attrs.items():
setattr(m, k, v)
return m
def _import_side_effect(name: str, **_):
raise ImportError(f"No module named '{name}'")
# ─── helpers ──────────────────────────────────────────────────────────────────
def _ok(result, expected_exit: int = 0, *, substr: str = "") -> None:
"""Assert exit code and optional substring."""
assert result.exit_code == expected_exit, (
f"exit={result.exit_code}, output={result.output!r}"
)
if substr:
assert substr in result.output, f"{substr!r} not in {result.output!r}"
def _json_output(result) -> Any:
"""Parse JSON from command output; raises on bad JSON."""
assert result.exit_code == 0, f"exit={result.exit_code}: {result.output}"
return json.loads(result.output.strip())
def _flatten(output: str) -> str:
"""Undo Rich panel wrapping for substring assertions on error text.
Rich wraps long messages across multiple bordered lines (each with its
own leading/trailing "│"), so a naive whitespace join still leaves those
border characters between words that were split across lines. Strip the
box-drawing characters first, then collapse whitespace.
"""
for ch in "┌┐└┘│─":
output = output.replace(ch, " ")
return " ".join(output.split())
# ─── Global flags ─────────────────────────────────────────────────────────────
class TestGlobalFlags:
def test_json_flag_stored_in_context(self, runner, monkeypatch):
captured = {}
def fake_run_build(ctx, sources):
captured["json"] = ctx.json_output
monkeypatch.setattr(cli_module, "_run_build", fake_run_build)
result = runner.invoke(cli_module.main, ["--json", "kg", "build", "-s", "x.txt"])
assert result.exit_code == 0
assert captured["json"] is True
def test_quiet_flag_stored_in_context(self, runner, monkeypatch):
captured = {}
def fake_run_build(ctx, sources):
captured["quiet"] = ctx.quiet
monkeypatch.setattr(cli_module, "_run_build", fake_run_build)
result = runner.invoke(cli_module.main, ["--quiet", "kg", "build", "-s", "x.txt"])
assert result.exit_code == 0
assert captured["quiet"] is True
def test_dry_run_global_stored_in_context(self, runner, monkeypatch):
captured = {}
def fake_run_build(ctx, sources):
captured["dry_run"] = ctx.dry_run_global
monkeypatch.setattr(cli_module, "_run_build", fake_run_build)
result = runner.invoke(cli_module.main, ["--dry-run", "kg", "build", "-s", "x.txt"])
assert result.exit_code == 0
assert captured["dry_run"] is True
def test_store_override_stored_in_context(self, runner, monkeypatch):
captured = {}
def fake_run_build(ctx, sources):
captured["store"] = ctx.store_backend
monkeypatch.setattr(cli_module, "_run_build", fake_run_build)
result = runner.invoke(cli_module.main, ["--store", "neo4j", "kg", "build", "-s", "x.txt"])
assert result.exit_code == 0
assert captured["store"] == "neo4j"
def test_vector_store_override_stored_in_context(self, runner, monkeypatch):
captured = {}
def fake_run_build(ctx, sources):
captured["vs"] = ctx.vector_store_backend
monkeypatch.setattr(cli_module, "_run_build", fake_run_build)
result = runner.invoke(cli_module.main, ["--vector-store", "qdrant", "kg", "build", "-s", "x.txt"])
assert result.exit_code == 0
assert captured["vs"] == "qdrant"
def test_root_help_shows_all_global_flags(self, runner):
result = runner.invoke(cli_module.main, ["--help"])
assert result.exit_code == 0
for flag in ["--json", "--quiet", "--dry-run", "--store", "--vector-store",
"--profile", "--no-color"]:
assert flag in result.output, f"{flag} missing from root help"
def test_root_help_shows_all_command_groups(self, runner):
result = runner.invoke(cli_module.main, ["--help"])
assert result.exit_code == 0
for cmd in ["ingest", "parse", "split", "normalize", "extract", "embed",
"deduplicate", "reason", "decision", "temporal", "provenance",
"validate", "ontology", "export", "visualize", "pipeline",
"store", "backup", "server", "explorer", "mcp", "completion"]:
assert cmd in result.output, f"{cmd!r} missing from root help"
def test_default_log_file_failure_falls_back_without_polluting_json(
self,
runner,
monkeypatch,
):
calls = []
def fake_setup_logging(*, config=None, **_kwargs):
calls.append(dict(config or {}))
if len(calls) == 1:
raise PermissionError("readonly semantica.log")
monkeypatch.setattr(cli_module, "setup_logging", fake_setup_logging)
result = runner.invoke(
cli_module.main,
["--json", "backup", "schedule", "--dest", "x", "--freq", "daily"],
)
payload = _json_output(result)
assert payload["cron"].startswith("0 2 * * *")
assert len(calls) == 2
assert calls[1].get("file") is None
assert "readonly semantica.log" not in result.output
# ─── kg subcommands ───────────────────────────────────────────────────────────
class TestKgSubcommands:
@pytest.mark.parametrize("sub", ["query", "stats", "analyze", "find-path",
"resolve", "predict", "validate"])
def test_help_exits_0(self, runner, sub):
result = runner.invoke(cli_module.main, ["kg", sub, "--help"])
_ok(result, substr=sub.replace("-", " ") if sub != "find-path" else "")
assert result.exit_code == 0
def test_kg_query_json_with_mock(self, runner, monkeypatch):
fake_gs = _fake_module(
execute_query=lambda q, **kw: {"query": q, "lang": "cypher", "rows": []},
)
monkeypatch.setitem(__import__("sys").modules, "semantica.graph_store", fake_gs)
result = runner.invoke(cli_module.main, ["kg", "query", "MATCH (n) RETURN n", "--json"])
_ok(result)
data = _json_output(result)
assert "query" in data
def test_kg_query_fails_cleanly_without_backend(self, runner):
result = runner.invoke(cli_module.main, ["kg", "query", "MATCH (n) RETURN n"])
# Either exits 0 (fallback) or non-0 (clean error) — never traceback
assert "Traceback" not in result.output
def test_kg_stats_json_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
GraphAnalyzer=lambda **kw: MagicMock(
compute_metrics=lambda: {"nodes": 10, "edges": 25, "density": 0.5}
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "stats", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, dict)
assert "nodes" in data
def test_kg_analyze_json_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
GraphAnalyzer=lambda **kw: MagicMock(
analyze=lambda mode: {"mode": mode, "communities": 3}
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "analyze", "--mode", "community", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, dict)
def test_kg_find_path_requires_from_and_to(self, runner):
result = runner.invoke(cli_module.main, ["kg", "find-path"])
assert result.exit_code != 0
def test_kg_find_path_json_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
PathFinder=lambda **kw: MagicMock(
find_path=lambda f, t, path_type: {"from": f, "to": t, "path": [f, t]}
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "find-path",
"--from", "Alice", "--to", "Acme", "--json"])
_ok(result)
data = _json_output(result)
assert "from" in data
def test_kg_resolve_exits_0_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
EntityResolver=lambda **kw: MagicMock(resolve=lambda: {"resolved": 5}),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "resolve"])
assert result.exit_code == 0
def test_kg_predict_exits_0_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
LinkPredictor=lambda **kw: MagicMock(predict=lambda: {"predictions": []}),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "predict"])
assert result.exit_code == 0
def test_kg_validate_exits_0_with_mock(self, runner, monkeypatch):
fake_kg = _fake_module(
GraphValidator=lambda **kw: MagicMock(
validate=lambda: {"valid": True},
integrity_check=lambda: {"valid": True},
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["kg", "validate"])
assert result.exit_code == 0
# ─── ingest ───────────────────────────────────────────────────────────────────
class TestIngest:
def test_help_shows_flags(self, runner):
result = runner.invoke(cli_module.main, ["ingest", "--help"])
_ok(result)
for flag in ["--type", "--format", "--recursive", "--watch",
"--batch-size", "--store", "--output", "--dry-run"]:
assert flag in result.output, f"{flag} missing"
def test_dry_run_json_exits_0(self, runner):
# Per-command --json with --dry-run should emit JSON (fixed via json_out param)
result = runner.invoke(cli_module.main, ["ingest", "data.pdf", "--dry-run", "--json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
assert data["action"] == "ingest"
def test_dry_run_global_json_exits_0(self, runner):
# Global --json with per-command --dry-run
result = runner.invoke(cli_module.main, ["--json", "ingest", "data.pdf", "--dry-run"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_dry_run_text_exits_0(self, runner):
result = runner.invoke(cli_module.main, ["ingest", "data.pdf", "--dry-run"])
_ok(result, substr="Dry run")
def test_runtime_path_passes_source_positionally(self, runner, monkeypatch):
captured = {}
def fake_ingest_file(sources, **kwargs):
captured["sources"] = sources
captured["kwargs"] = kwargs
return [{"path": sources}]
monkeypatch.setattr("semantica.ingest.methods.ingest_file", fake_ingest_file)
result = runner.invoke(
cli_module.main,
["ingest", "README.md", "--type", "file", "--format", "csv", "--json"],
)
_ok(result)
data = _json_output(result)
assert data["files"] == [{"path": "README.md"}]
assert captured["sources"] == "README.md"
assert captured["kwargs"]["method"] == "file"
assert captured["kwargs"]["batch_size"] == 500
assert captured["kwargs"]["format"] == "csv"
@pytest.mark.parametrize("fmt", ["ndjson", "jsonl"])
def test_ingest_format_line_delimited_json(self, runner, monkeypatch, fmt):
captured = {}
def fake_ingest_file(sources, **kwargs):
captured["sources"] = sources
captured["kwargs"] = kwargs
return [{"path": sources}]
monkeypatch.setattr("semantica.ingest.methods.ingest_file", fake_ingest_file)
result = runner.invoke(
cli_module.main,
["ingest", f"data.{fmt}", "--type", "file", "--format", fmt, "--json"],
)
_ok(result)
data = _json_output(result)
assert data["files"] == [{"path": f"data.{fmt}"}]
assert captured["sources"] == f"data.{fmt}"
assert captured["kwargs"]["method"] == "file"
assert captured["kwargs"]["format"] == fmt
def test_watch_help_shows_line_delimited_json_patterns(self, runner):
result = runner.invoke(cli_module.main, ["watch", "--help"])
_ok(result)
assert "*.jsonl" in result.output
assert "*.ndjson" in result.output
def test_runtime_path_passes_source_positionally_with_auto_detection(self, runner, monkeypatch):
captured = {}
def fake_ingest_file(sources, **kwargs):
captured["sources"] = sources
captured["kwargs"] = kwargs
return [{"path": sources}]
monkeypatch.setattr("semantica.ingest.methods.ingest_file", fake_ingest_file)
result = runner.invoke(cli_module.main, ["ingest", "README.md", "--json"])
_ok(result)
data = _json_output(result)
assert data["files"] == [{"path": "README.md"}]
assert captured["sources"] == "README.md"
assert captured["kwargs"]["method"] == "file"
def test_configured_graph_backend_does_not_report_false_success(
self, runner, monkeypatch
):
monkeypatch.setenv("GRAPH_STORE_DEFAULT_BACKEND", "neo4j")
monkeypatch.setattr(
"semantica.ingest.methods.ingest_file",
lambda sources, **kwargs: [{"path": sources}],
)
result = runner.invoke(cli_module.main, ["ingest", "README.md"])
output = _flatten(result.output)
assert result.exit_code != 0
assert "does not write to graph stores" in output
assert "Ingested:" not in output
def test_configured_graph_backend_error_does_not_recommend_broken_kg_build(
self, runner, monkeypatch
):
# kg build also does not persist to a configured graph store
# (tracked separately as #1352), so the error must not send users to
# a command that will silently no-op the same way.
monkeypatch.setenv("GRAPH_STORE_DEFAULT_BACKEND", "neo4j")
monkeypatch.setattr(
"semantica.ingest.methods.ingest_file",
lambda sources, **kwargs: [{"path": sources}],
)
result = runner.invoke(cli_module.main, ["ingest", "README.md"])
output = _flatten(result.output)
assert result.exit_code != 0
assert "kg build" not in output
def test_output_flag_writes_real_content_and_bypasses_graph_error(
self, runner, monkeypatch, tmp_path
):
monkeypatch.setenv("GRAPH_STORE_DEFAULT_BACKEND", "neo4j")
monkeypatch.setattr(
"semantica.ingest.methods.ingest_file",
lambda sources, **kwargs: [{"path": sources}],
)
out_path = tmp_path / "out.json"
result = runner.invoke(
cli_module.main, ["ingest", "README.md", "--output", str(out_path)]
)
_ok(result, substr="Wrote")
written = json.loads(out_path.read_text(encoding="utf-8"))
assert written == {"files": [{"path": "README.md"}]}
def test_store_and_output_are_not_forwarded_to_ingest_backend(
self, runner, monkeypatch, tmp_path
):
captured = {}
def fake_ingest_file(sources, **kwargs):
captured["kwargs"] = kwargs
return [{"path": sources}]
monkeypatch.setattr("semantica.ingest.methods.ingest_file", fake_ingest_file)
out_path = tmp_path / "out.json"
result = runner.invoke(
cli_module.main,
["ingest", "README.md", "--store", "neo4j", "--output", str(out_path)],
)
_ok(result)
assert "store" not in captured["kwargs"]
assert "output" not in captured["kwargs"]
def test_import_error_is_clean(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "__import__", _import_side_effect, raising=False)
original_import = __import__
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.ingest") else original_import(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["ingest", "data.pdf"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_type_choice_validation(self, runner):
result = runner.invoke(cli_module.main, ["ingest", "x.pdf", "--type", "invalid_type"])
assert result.exit_code != 0
def test_recursive_flag_accepted(self, runner):
result = runner.invoke(cli_module.main, ["ingest", "./data", "--recursive", "--dry-run"])
_ok(result)
def test_global_dry_run_triggers_ingest_dry(self, runner):
# Both global --dry-run and global --json
result = runner.invoke(cli_module.main, ["--dry-run", "--json", "ingest", "data.pdf"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
# ─── parse ────────────────────────────────────────────────────────────────────
class TestParse:
def test_help_shows_flags(self, runner):
result = runner.invoke(cli_module.main, ["parse", "--help"])
_ok(result)
for flag in ["--parser", "--format"]:
assert flag in result.output
def test_missing_file_arg_fails(self, runner):
result = runner.invoke(cli_module.main, ["parse"])
assert result.exit_code != 0
def test_nonexistent_file_fails(self, runner):
result = runner.invoke(cli_module.main, ["parse", "no_such_file.pdf"])
assert result.exit_code != 0
def test_parse_real_file(self, runner):
with runner.isolated_filesystem():
with open("doc.txt", "w") as f:
f.write("Hello world")
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.parse") else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["parse", "doc.txt"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_format_choices(self, runner):
result = runner.invoke(cli_module.main, ["parse", "--help"])
assert "json" in result.output
assert "yaml" in result.output
assert "table" in result.output
# ─── split ────────────────────────────────────────────────────────────────────
class TestSplit:
def test_help_shows_strategy_choices(self, runner):
result = runner.invoke(cli_module.main, ["split", "--help"])
_ok(result)
for strategy in ["recursive", "semantic", "entity-aware", "table"]:
assert strategy in result.output
def test_missing_input_fails(self, runner):
result = runner.invoke(cli_module.main, ["split"])
assert result.exit_code != 0
def test_split_with_import_error(self, runner):
with runner.isolated_filesystem():
with open("doc.txt", "w") as f:
f.write("content")
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.split") else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["split", "doc.txt"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_split_writes_output_file(self, runner, monkeypatch):
mock_chunks = [{"text": "chunk1"}, {"text": "chunk2"}]
fake_split = _fake_module(
split_recursive=lambda *a, **kw: mock_chunks,
get_split_method=lambda s: lambda *a, **kw: mock_chunks,
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.split", fake_split
)
with runner.isolated_filesystem():
with open("doc.txt", "w") as f:
f.write("line1\nline2")
result = runner.invoke(
cli_module.main, ["split", "doc.txt", "--output", "out.json"]
)
if result.exit_code == 0:
assert os.path.exists("out.json")
# ─── normalize ────────────────────────────────────────────────────────────────
class TestNormalize:
def test_help_shows_mode_and_domain(self, runner):
result = runner.invoke(cli_module.main, ["normalize", "--help"])
_ok(result)
assert "--mode" in result.output
assert "--domain" in result.output
def test_normalize_text_inline(self, runner, monkeypatch):
fake_norm = _fake_module(
normalize_text=lambda t: t.upper(),
normalize_date=lambda t, **kw: t,
normalize_entity=lambda t, **kw: t,
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.normalize", fake_norm
)
result = runner.invoke(cli_module.main, ["normalize", "hello world", "--mode", "text"])
assert result.exit_code == 0
assert "HELLO WORLD" in result.output
def test_normalize_json(self, runner, monkeypatch):
fake_norm = _fake_module(
normalize_text=lambda t: "normalized",
normalize_date=lambda t, **kw: "normalized",
normalize_entity=lambda t, **kw: "normalized",
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.normalize", fake_norm
)
result = runner.invoke(cli_module.main, ["normalize", "text", "--json"])
_ok(result)
data = _json_output(result)
assert "result" in data
def test_domain_choices(self, runner):
result = runner.invoke(cli_module.main, ["normalize", "--help"])
for d in ["healthcare", "legal", "finance", "general"]:
assert d in result.output
# ─── extract ──────────────────────────────────────────────────────────────────
class TestExtract:
def test_help_shows_mode_method_flags(self, runner):
result = runner.invoke(cli_module.main, ["extract", "--help"])
_ok(result)
for flag in ["--mode", "--method", "--model", "--confidence",
"--temporal", "--format", "--output"]:
assert flag in result.output
def test_dry_run_not_needed_extract_is_read_only(self, runner, monkeypatch):
_ner_result = [MagicMock(text="Alice", label="PER", confidence=0.9,
start_char=0, end_char=5, metadata={})]
fake_ext = _fake_module(
NERExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: _ner_result),
RelationExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
TripletExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
result = runner.invoke(
cli_module.main, ["extract", "Alice works at Acme.", "--mode", "ner", "--json"]
)
_ok(result)
data = _json_output(result)
assert isinstance(data, (dict, list))
def test_stdin_input(self, runner, monkeypatch):
_ner_result = [MagicMock(text="Alice", label="PER", confidence=0.9,
start_char=0, end_char=5, metadata={})]
fake_ext = _fake_module(
NERExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: _ner_result),
RelationExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
TripletExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
result = runner.invoke(
cli_module.main, ["extract", "-", "--mode", "ner", "--json"], input="Alice\n"
)
_ok(result)
def test_default_mode_runs_every_extractor(self, runner, monkeypatch):
"""#1789 — the default --mode all must dispatch, not raise."""
_ner_result = [MagicMock(text="Alice", label="PER", confidence=0.9,
start_char=0, end_char=5, metadata={})]
fake_ext = _fake_module(
NERExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: _ner_result),
RelationExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
TripletExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
# No --mode: fall back to the command default.
result = runner.invoke(
cli_module.main, ["extract", "Alice works at Acme.", "--json"]
)
_ok(result)
data = _json_output(result)
assert set(data) == {"ner", "relations", "triplets", "events"}
def test_mode_choices_include_all_and_coreference(self):
"""#1850 — every advertised mode must be a real `--mode` choice.
`all` is the *default* mode, yet the smoke loop in
``tests/verify_rich_cli.py`` used to hardcode a list that silently
omitted it — which is why #1789 shipped unnoticed. Pin the full
``choices`` set (and the default) so that loop stays aligned with the
command contract.
"""
mode_param = next(
p for p in cli_module.extract.params if p.name == "mode"
)
choices = list(mode_param.type.choices)
assert mode_param.default == "all"
assert "all" in choices, f"'all' missing from choices: {choices}"
assert set(choices) == {
"ner", "relations", "triplets", "events", "coreference", "all",
}
def test_explicit_all_mode_returns_every_stage(self, runner, monkeypatch):
"""#1850 — an explicit `--mode all` (not just the default) runs all stages."""
_ner_result = [MagicMock(text="Alice", label="PER", confidence=0.9,
start_char=0, end_char=5, metadata={})]
fake_ext = _fake_module(
NERExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: _ner_result),
RelationExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
TripletExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
result = runner.invoke(
cli_module.main,
["extract", "Alice works at Acme.", "--mode", "all", "--json"],
)
_ok(result)
assert set(_json_output(result)) == {"ner", "relations", "triplets", "events"}
def test_coreference_mode_is_a_clean_placeholder_error(self, runner, monkeypatch):
"""#1850 — `coreference` is a listed choice but has no extractor yet.
Until it is wired it must fail with a clean "not yet wired" error (and
no traceback), rather than silently succeeding or crashing.
"""
fake_ext = _fake_module(
NERExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
RelationExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
TripletExtractor=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
result = runner.invoke(
cli_module.main,
["extract", "Alice works at Acme.", "--mode", "coreference"],
)
assert result.exit_code != 0
assert "Traceback" not in result.output
assert "not yet wired" in _flatten(result.output)
def test_all_mode_reuses_ner_and_relations(self, runner, monkeypatch):
"""#1789 (Qodo) — 'all' must not recompute NER/relations per stage."""
calls = {"ner": 0, "relations": 0, "triplets": 0}
seen = {}
ner_result = [MagicMock(text="Alice", label="PER", confidence=0.9,
start_char=0, end_char=5, metadata={})]
relation_result = [MagicMock(subject="Alice", predicate="works_at",
object="Acme", confidence=0.9, metadata={})]
def _triplet_extract(text, entities=None, relations=None, **kw):
seen["entities"] = entities
seen["relations"] = relations
return []
fake_ext = _fake_module(
NERExtractor=lambda **kw: (
calls.__setitem__("ner", calls["ner"] + 1)
or MagicMock(extract=lambda text, **kw2: ner_result)
),
RelationExtractor=lambda **kw: (
calls.__setitem__("relations", calls["relations"] + 1)
or MagicMock(extract=lambda text, entities=None, **kw2: relation_result)
),
TripletExtractor=lambda **kw: (
calls.__setitem__("triplets", calls["triplets"] + 1)
or MagicMock(extract=_triplet_extract)
),
EventDetector=lambda **kw: MagicMock(extract=lambda text, **kw2: []),
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.semantic_extract", fake_ext
)
result = runner.invoke(
cli_module.main, ["extract", "Alice works at Acme.", "--json"]
)
_ok(result)
# NER (for the ner stage) and relations run once each; the triplet
# stage reuses their output instead of building a second NER/relation
# extractor of its own.
assert calls["ner"] == 1
assert calls["relations"] == 1
assert calls["triplets"] == 1
# ...and the triplet stage actually received that shared output.
assert seen["entities"] is ner_result
assert seen["relations"] is relation_result
def test_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.semantic_extract") else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["extract", "text"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_invalid_method_choice(self, runner):
result = runner.invoke(cli_module.main, ["extract", "text", "--method", "magic"])
assert result.exit_code != 0
# ─── embed ────────────────────────────────────────────────────────────────────
class TestEmbed:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["embed", "--help"])
_ok(result)
for sub in ["generate", "search", "index"]:
assert sub in result.output
def test_generate_help(self, runner):
result = runner.invoke(cli_module.main, ["embed", "generate", "--help"])
_ok(result)
assert "--model" in result.output
def test_search_help(self, runner):
result = runner.invoke(cli_module.main, ["embed", "search", "--help"])
_ok(result)
assert "--top-k" in result.output
assert "--hybrid" in result.output
def test_index_help(self, runner):
result = runner.invoke(cli_module.main, ["embed", "index", "--help"])
_ok(result)
assert "--store" in result.output
def test_generate_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "embeddings" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["embed", "generate", "entities.json"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_search_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "vector_store" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["embed", "search", "CEO query"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_index_requires_existing_file(self, runner):
result = runner.invoke(cli_module.main, ["embed", "index", "nonexistent.parquet"])
assert result.exit_code != 0
def test_index_loads_vectors_from_json(self, runner, monkeypatch, tmp_path):
"""Vectors are loaded from the file; create_index receives List[np.ndarray]."""
import json as _json, numpy as np
records = [{"id": "a", "embedding": [0.1, 0.2, 0.3]},
{"id": "b", "embedding": [0.4, 0.5, 0.6]}]
json_file = tmp_path / "test.json"
json_file.write_text(_json.dumps(records), encoding="utf-8")
captured = {}
def fake_create_index(vectors, ids=None, **kw):
captured["vectors"] = vectors
captured["ids"] = ids
return {"status": "ok"}
fake_vs = _fake_module(create_index=fake_create_index)
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["embed", "index", str(json_file), "--json"])
_ok(result)
assert len(captured["vectors"]) == 2
assert isinstance(captured["vectors"][0], np.ndarray)
def test_index_rejects_unsupported_format(self, runner, monkeypatch, tmp_path):
txt_file = tmp_path / "embeddings.txt"
txt_file.write_text("not a supported format")
fake_vs = _fake_module(create_index=MagicMock(return_value={}))
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["embed", "index", str(txt_file)])
assert result.exit_code != 0
# ─── deduplicate ──────────────────────────────────────────────────────────────
class TestDeduplicate:
def test_help_shows_flags(self, runner):
result = runner.invoke(cli_module.main, ["deduplicate", "--help"])
_ok(result)
for flag in ["--strategy", "--min-similarity", "--action", "--dry-run"]:
assert flag in result.output
def test_dry_run_exits_0(self, runner):
result = runner.invoke(cli_module.main, ["deduplicate", "--dry-run"])
_ok(result)
def test_dry_run_json(self, runner):
result = runner.invoke(cli_module.main, ["deduplicate", "--dry-run", "--json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_detect_runtime_path(self, runner, monkeypatch):
entities = [
{"id": "e1", "name": "Alice", "type": "Person"},
{"id": "e2", "name": "Alice", "type": "Person"},
{"id": "e3", "name": "Bob", "type": "Person"},
]
class FakeStore:
def get_nodes(self, labels=None, properties=None, limit=100, **options):
return entities
monkeypatch.setattr("semantica.graph_store.methods._get_store", lambda: FakeStore())
monkeypatch.setattr("semantica.graph_store.methods.get_nodes", lambda **kwargs: entities)
result = runner.invoke(
cli_module.main,
["deduplicate", "--action", "detect", "--min-similarity", "0.1", "--json"],
)
_ok(result)
assert "Alice" in result.output
assert "Bob" not in result.output or "entities" in result.output
def test_merge_runtime_path(self, runner, monkeypatch):
entities = [
{"id": "e1", "name": "Alice", "type": "Person"},
{"id": "e2", "name": "Alice", "type": "Person"},
]
captured = {}
class FakeStore:
def get_nodes(self, labels=None, properties=None, limit=100, **options):
return entities
monkeypatch.setattr("semantica.graph_store.methods._get_store", lambda: FakeStore())
monkeypatch.setattr("semantica.graph_store.methods.get_nodes", lambda **kwargs: entities)
def fake_merge(self, loaded_entities, **kwargs):
captured["entities"] = loaded_entities
captured["kwargs"] = kwargs
return [{"merged": True, "count": len(loaded_entities)}]
monkeypatch.setattr(
"semantica.deduplication.entity_merger.EntityMerger.merge_duplicates",
fake_merge,
)
result = runner.invoke(
cli_module.main,
["deduplicate", "--action", "merge", "--json"],
)
_ok(result)
data = _json_output(result)
assert data == [{"merged": True, "count": 2}]
assert captured["entities"] == entities
assert captured["kwargs"]["threshold"] == pytest.approx(0.7)
assert captured["kwargs"]["candidate_strategy"] == "hybrid_v2"
assert captured["kwargs"]["sort_by"] == "similarity_score"
def test_global_dry_run_triggers_dry(self, runner):
result = runner.invoke(cli_module.main, ["--dry-run", "--json", "deduplicate"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "deduplication" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["deduplicate"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_invalid_strategy_choice(self, runner):
result = runner.invoke(cli_module.main, ["deduplicate", "--strategy", "magic"])
assert result.exit_code != 0
@pytest.mark.parametrize("action", ["detect", "merge", "report"])
def test_action_choices_accepted(self, runner, action):
result = runner.invoke(cli_module.main, ["deduplicate", "--action", action, "--dry-run"])
_ok(result)
# ─── reason ───────────────────────────────────────────────────────────────────
class TestReason:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["reason", "--help"])
_ok(result)
for sub in ["run", "explain", "query", "list"]:
assert sub in result.output
def test_list_shows_engines(self, runner):
result = runner.invoke(cli_module.main, ["reason", "list"])
_ok(result)
assert "rete" in result.output
def test_list_json(self, runner):
# list command has no --json flag, output via cli_ctx.json_output
result2 = runner.invoke(cli_module.main, ["--json", "reason", "list"])
_ok(result2)
data = json.loads(result2.output.strip())
assert "engines" in data
assert "rete" in data["engines"]
def test_run_help(self, runner):
result = runner.invoke(cli_module.main, ["reason", "run", "--help"])
_ok(result)
assert "--engine" in result.output
def test_run_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "reasoning" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["reason", "run"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_run_infers_from_graph_store_facts(self, runner, monkeypatch, tmp_path):
# reason run used to call Reasoner.run(), which does not exist
# (#1354); it must feed graph store facts + --rules into
# Reasoner.infer_facts().
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text(
'- IF Person(?x) THEN Human(?x)\n'
'- IF MANAGES(?x, ?y) THEN Manager(?x)\n'
'- IF Employee(?x) THEN Staff(?x)\n',
encoding="utf-8")
class _FakeStore:
# Same dict schema as the real backends: nodes carry
# labels/properties, relationships carry start_node_id/end_node_id.
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"],
"properties": {"name": "Alice"}},
{"id": 2, "labels": ["Person", "Employee"],
"properties": {"name": "Bob"}}]
def get_relationships(self, limit=None):
return [{"id": 9, "type": "MANAGES",
"start_node_id": 1, "end_node_id": 2}]
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--rules", str(rules_file)],
)
_ok(result)
data = json.loads(result.output.strip())
# Person(Alice), Person(Bob), Employee(Bob), MANAGES(Alice, Bob)
assert data["facts"] == 4
assert "Human(Alice)" in data["inferred_facts"]
# Relationship endpoints resolve node ids to names.
assert "Manager(Alice)" in data["inferred_facts"]
# Secondary labels also become facts.
assert "Staff(Bob)" in data["inferred_facts"]
assert data["inferred_count"] == len(data["inferred_facts"])
def test_run_rejects_unwired_engine(self, runner):
result = runner.invoke(cli_module.main,
["reason", "run", "--engine", "sparql"])
assert result.exit_code != 0
# _flatten() undoes the Rich panel's line-wrap borders, which would
# otherwise split "reason query" mid-word and break a raw substring
# check.
normalized = _flatten(result.output)
assert "not wired" in normalized
assert "reason query" in normalized
assert "Traceback" not in result.output
def test_run_reasoning_local_json_flag_suppresses_spinner(self, runner, monkeypatch):
"""`reason run --json` (the command's own flag, not the global one)
must not enter the Rich status spinner. console.status() writes to
stdout; entering it under the local-only flag would put status text
ahead of the JSON payload in the same stream."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
status_calls = []
real_status = cli_module.console.status
def _spy_status(*a, **kw):
status_calls.append((a, kw))
return real_status(*a, **kw)
monkeypatch.setattr(cli_module.console, "status", _spy_status)
result = runner.invoke(cli_module.main, ["reason", "run", "--json"])
_ok(result)
assert status_calls == []
def test_run_deductive_falls_back_to_graph_store_facts(self, runner, monkeypatch, tmp_path):
"""--engine deductive without --premises should build Premises from
the graph store, matching the rete/datalog fallback convention."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text(
"- IF Person(?x) THEN Human(?x)\n"
"- IF MANAGES(?x, ?y) THEN Manager(?x)\n",
encoding="utf-8")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"], "properties": {"name": "Alice"}},
{"id": 2, "labels": ["Person", "Employee"], "properties": {"name": "Bob"}}]
def get_relationships(self, limit=None):
return [{"id": 9, "type": "MANAGES", "start_node_id": 1, "end_node_id": 2}]
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "deductive", "--rules", str(rules_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["engine"] == "deductive"
assert data["facts"] == 4
assert "Human(Alice)" in data["inferred_facts"]
assert "Human(Bob)" in data["inferred_facts"]
assert "Manager(Alice)" in data["inferred_facts"]
assert data["inferred_count"] == len(data["inferred_facts"])
def test_run_deductive_uses_premises_file(self, runner, monkeypatch, tmp_path):
"""--premises should be used instead of the graph store when given,
and accept both plain strings and {statement, confidence} entries."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text("- IF Person(?x) THEN Human(?x)\n", encoding="utf-8")
premises_file = tmp_path / "premises.yaml"
premises_file.write_text(
"- Person(Alice)\n"
"- {statement: 'Person(Bob)', confidence: 0.7}\n",
encoding="utf-8")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "deductive",
"--rules", str(rules_file), "--premises", str(premises_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["facts"] == 2
assert "Human(Alice)" in data["inferred_facts"]
assert "Human(Bob)" in data["inferred_facts"]
def test_run_deductive_reaches_fixpoint_across_rule_order(self, runner, monkeypatch, tmp_path):
"""DeductiveReasoner.apply_logic() scans its rules once, not to a
fixpoint -- a single call would miss Human(Bob) here since the rule
deriving it needs Employee(Bob), which is itself only derived by a
*later* rule in this same call. reason run must loop apply_logic()
until no new conclusions appear so rule order doesn't silently drop
valid transitive conclusions."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text(
"- IF Employee(?x) THEN Human(?x)\n"
"- IF Manager(?x) THEN Employee(?x)\n",
encoding="utf-8")
premises_file = tmp_path / "premises.yaml"
premises_file.write_text("- Manager(Bob)\n", encoding="utf-8")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "deductive",
"--rules", str(rules_file), "--premises", str(premises_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert "Employee(Bob)" in data["inferred_facts"]
assert "Human(Bob)" in data["inferred_facts"]
def test_run_abductive_requires_observations(self, runner, monkeypatch):
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(cli_module.main, ["reason", "run", "--engine", "abductive"])
assert result.exit_code != 0
assert "--observations" in result.output
assert "Traceback" not in result.output
def test_run_abductive_finds_explanations(self, runner, monkeypatch, tmp_path):
"""--engine abductive should find rules whose conclusion explains
each observation, not force everything through infer_facts()."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text("- IF Person(?x) THEN Human(?x)\n", encoding="utf-8")
obs_file = tmp_path / "observations.yaml"
obs_file.write_text("- Human(Alice)\n", encoding="utf-8")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"], "properties": {"name": "Alice"}}]
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "abductive",
"--rules", str(rules_file), "--observations", str(obs_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["engine"] == "abductive"
assert data["observations"] == 1
assert len(data["explanations"]) == 1
exp = data["explanations"][0]
assert exp["observation"] == "Human(Alice)"
assert exp["best_hypothesis"] is not None
assert exp["hypotheses_considered"] == 1
def test_run_abductive_no_matching_rule_returns_empty_explanation(
self, runner, monkeypatch, tmp_path
):
"""An observation no loaded rule can explain must report cleanly
(no hypotheses), not crash or fabricate an explanation."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text("- IF Person(?x) THEN Human(?x)\n", encoding="utf-8")
obs_file = tmp_path / "observations.yaml"
obs_file.write_text("- Unicorn(Alice)\n", encoding="utf-8")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "abductive",
"--rules", str(rules_file), "--observations", str(obs_file)],
)
_ok(result)
data = json.loads(result.output.strip())
exp = data["explanations"][0]
assert exp["best_hypothesis"] is None
assert exp["hypotheses_considered"] == 0
def test_run_abductive_does_not_require_graph_store(self, runner, monkeypatch, tmp_path):
"""A fully self-contained abductive run (--rules + --observations)
must not depend on the configured graph store being reachable.
AbductiveReasoner doesn't currently consume knowledge_base at all,
so calling _graph_store_facts() here would only add a failure mode
with no corresponding benefit."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text("- IF Person(?x) THEN Human(?x)\n", encoding="utf-8")
obs_file = tmp_path / "observations.yaml"
obs_file.write_text("- Human(Alice)\n", encoding="utf-8")
def _unreachable_store(ctx):
raise RuntimeError("graph store should not be contacted")
monkeypatch.setattr(cli_module, "_get_graph_store", _unreachable_store)
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "abductive",
"--rules", str(rules_file), "--observations", str(obs_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["explanations"][0]["best_hypothesis"] is not None
def test_run_datalog_derives_facts_from_graph_store(self, runner, monkeypatch, tmp_path):
"""--engine datalog should run DatalogReasoner.derive_all(), not infer_facts()."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
# Predicate case matches the graph's own label/relationship-type
# spelling (title-case "Person", upper-case "MANAGES") -- only
# arguments get lowercased into Datalog constants, not predicates.
rules_file = tmp_path / "rules.dl"
rules_file.write_text(
"Human(X) :- Person(X).\n"
"Manager(X) :- MANAGES(X, Y).\n",
encoding="utf-8")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"], "properties": {"name": "Alice"}},
{"id": 2, "labels": ["Person", "Employee"], "properties": {"name": "Bob"}}]
def get_relationships(self, limit=None):
return [{"id": 9, "type": "MANAGES", "start_node_id": 1, "end_node_id": 2}]
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "datalog", "--rules", str(rules_file)],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["engine"] == "datalog"
# Person(alice), Person(bob), Employee(bob), MANAGES(alice, bob)
assert data["facts"] == 4
assert "Human(alice)" in data["inferred_facts"]
assert "Human(bob)" in data["inferred_facts"]
assert "Manager(alice)" in data["inferred_facts"]
# Base facts must not be reported back as "inferred".
assert "Person(alice)" not in data["inferred_facts"]
assert data["inferred_count"] == len(data["inferred_facts"])
def test_run_datalog_lowercases_args_only_not_predicate(self):
"""Regression for a case-mismatch bug: lowercasing the whole fact
string (not just its arguments) made facts like "person(alice)"
unmatchable by rules written against the graph's real label
spelling, e.g. "Human(X) :- Person(X)."."""
assert cli_module._lowercase_datalog_args("Person(Alice)") == "Person(alice)"
assert cli_module._lowercase_datalog_args(
"MANAGES(Alice, Bob)") == "MANAGES(alice, bob)"
def test_run_datalog_rejects_ifthen_rules_cleanly(self, runner, monkeypatch, tmp_path):
"""A rete-style '--rules' file (IF/THEN) is not valid Datalog syntax;
it must surface as a clean error, not a Traceback."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
rules_file = tmp_path / "rules.yaml"
rules_file.write_text("- IF Person(?x) THEN Human(?x)\n", encoding="utf-8")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(
cli_module.main,
["reason", "run", "--engine", "datalog", "--rules", str(rules_file)],
)
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_run_datalog_no_rules_uses_empty_ruleset(self, runner, monkeypatch):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"], "properties": {"name": "Alice"}}]
def get_relationships(self, limit=None):
return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(
cli_module.main, ["--json", "reason", "run", "--engine", "datalog"])
_ok(result)
data = json.loads(result.output.strip())
assert data["facts"] == 1
assert data["inferred_count"] == 0
assert data["inferred_facts"] == []
def test_run_graph_requires_query(self, runner, monkeypatch):
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(cli_module.main, ["reason", "run", "--engine", "graph"])
assert result.exit_code != 0
assert "--query" in result.output
assert "Traceback" not in result.output
def test_run_graph_dispatches_to_graph_reasoner(self, runner, monkeypatch, tmp_path):
"""--engine graph should call GraphReasoner.reason(graph, query) and
surface its natural-language answer, not the facts-count shape.
Also regression-guards three context-building gaps: a node with
multiple labels must keep all of them (not just labels[0]), a
relationship's properties must reach GraphReasoner (not just its
source/target/type), and start_node_id/end_node_id must resolve to
the actual node names rather than leaking raw internal ids into the
graph context sent to the LLM.
"""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person", "Manager"], "properties": {"name": "Alice"}},
{"id": 2, "labels": ["Person"], "properties": {"name": "Bob"}}]
def get_relationships(self, limit=None):
return [{"id": 9, "type": "MANAGES", "start_node_id": 1, "end_node_id": 2,
"properties": {"since": "2020"}}]
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
class _FakeGraphReasoner:
def __init__(self, config=None, **kwargs):
pass
def reason(self, graph, query, **options):
assert graph["entities"][0]["name"] == "Alice"
assert graph["entities"][0]["type"] == "Person/Manager"
assert graph["relationships"][0]["type"] == "MANAGES"
assert graph["relationships"][0]["properties"] == {"since": "2020"}
# start_node_id/end_node_id (1, 2) must resolve to node
# names, not leak raw internal ids into the LLM's context.
assert graph["relationships"][0]["source"] == "Alice"
assert graph["relationships"][0]["target"] == "Bob"
assert query == "Who manages Bob?"
return "Alice manages Bob."
monkeypatch.setattr(
"semantica.reasoning.GraphReasoner", _FakeGraphReasoner, raising=False)
result = runner.invoke(
cli_module.main,
["--json", "reason", "run", "--engine", "graph",
"--query", "Who manages Bob?"],
)
_ok(result)
data = json.loads(result.output.strip())
assert data["engine"] == "graph"
assert data["query"] == "Who manages Bob?"
assert data["answer"] == "Alice manages Bob."
assert data["facts"] == 3
def test_run_graph_surfaces_reasoner_failure_as_error(self, runner, monkeypatch):
"""GraphReasoner.reason() never raises on an LLM-side failure -- it
returns a string starting with "Error" instead. reason run must
surface that as a real command failure, not exit 0 with a fake
"answer"."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
class _FailingGraphReasoner:
def __init__(self, config=None, **kwargs):
pass
def reason(self, graph, query, **options):
return "Error: LLM provider not initialized for GraphReasoner. Check your configuration."
monkeypatch.setattr(
"semantica.reasoning.GraphReasoner", _FailingGraphReasoner, raising=False)
result = runner.invoke(
cli_module.main, ["reason", "run", "--engine", "graph", "--query", "anything?"])
assert result.exit_code != 0
assert "LLM provider not initialized" in result.output
assert "Traceback" not in result.output
def test_run_graph_surfaces_generation_failure_as_error(self, runner, monkeypatch):
"""The second GraphReasoner error path -- a generation-time failure
(e.g. provider initialized but the call itself fails) returns
"Error during reasoning: ..." rather than the "not initialized"
string. reason run must surface this as a real command failure too,
not just the first error string."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
class _FailingGraphReasoner:
def __init__(self, config=None, **kwargs):
pass
def reason(self, graph, query, **options):
return "Error during reasoning: connection timed out"
monkeypatch.setattr(
"semantica.reasoning.GraphReasoner", _FailingGraphReasoner, raising=False)
result = runner.invoke(
cli_module.main, ["reason", "run", "--engine", "graph", "--query", "anything?"])
assert result.exit_code != 0
assert "Error during reasoning" in result.output
assert "Traceback" not in result.output
def test_load_rule_definitions_formats(self, tmp_path):
yaml_list = tmp_path / "list.yaml"
yaml_list.write_text('- IF A(?x) THEN B(?x)\n- IF B(?x) THEN C(?x)\n',
encoding="utf-8")
assert cli_module._load_rule_definitions(str(yaml_list)) == [
"IF A(?x) THEN B(?x)", "IF B(?x) THEN C(?x)"]
yaml_map = tmp_path / "map.yaml"
yaml_map.write_text('rules:\n - IF A(?x) THEN B(?x)\n', encoding="utf-8")
assert cli_module._load_rule_definitions(str(yaml_map)) == [
"IF A(?x) THEN B(?x)"]
plain = tmp_path / "rules.dl"
plain.write_text('# comment\nIF A(?x) THEN B(?x)\n\n', encoding="utf-8")
assert cli_module._load_rule_definitions(str(plain)) == [
"IF A(?x) THEN B(?x)"]
def test_run_empty_graph_returns_zero_facts(self, runner, monkeypatch):
"""reason run with an empty graph store should not crash and report 0 facts."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(cli_module.main, ["--json", "reason", "run"])
_ok(result)
data = json.loads(result.output.strip())
assert data["facts"] == 0
assert data["inferred_count"] == 0
assert data["inferred_facts"] == []
def test_run_graph_store_error_surfaces_cleanly(self, runner, monkeypatch):
"""A graph-store connectivity error must surface as a clean error, not a Traceback."""
def _bad_store(ctx):
raise RuntimeError("connection refused")
monkeypatch.setattr(cli_module, "_get_graph_store", _bad_store)
result = runner.invoke(cli_module.main, ["reason", "run"])
assert result.exit_code != 0
assert "Traceback" not in result.output
assert "connection refused" in result.output
def test_run_no_rules_uses_empty_ruleset(self, runner, monkeypatch):
"""reason run without --rules should still succeed (zero rules -> zero inferences)."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _FakeStore:
def get_nodes(self, limit=None):
return [{"id": 1, "labels": ["Person"], "properties": {"name": "Alice"}}]
def get_relationships(self, limit=None):
return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _FakeStore())
result = runner.invoke(cli_module.main, ["--json", "reason", "run"])
_ok(result)
data = json.loads(result.output.strip())
assert data["facts"] == 1
assert data["inferred_count"] == 0
def test_load_rule_definitions_yaml_mapping_without_rules_key_raises(self, tmp_path):
"""A YAML mapping with no 'rules' key must raise ClickException, not silently
pass the raw YAML lines as rules."""
bad = tmp_path / "bad.yaml"
bad.write_text("some_key: some_value\nother_key: other_value\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="no 'rules' key"):
cli_module._load_rule_definitions(str(bad))
def test_load_rule_definitions_empty_file_returns_empty_list(self, tmp_path):
empty = tmp_path / "empty.yaml"
empty.write_text("", encoding="utf-8")
assert cli_module._load_rule_definitions(str(empty)) == []
def test_load_rule_definitions_yaml_rules_null_falls_to_plaintext(self, tmp_path):
"""rules: null is valid YAML with the key present; the null value is
not a list, so the function falls through to plain-text parsing and
returns the literal line (one no-op rule). This documents the edge
case rather than asserting a specific useful behaviour."""
f = tmp_path / "null_rules.yaml"
f.write_text("rules: null\n", encoding="utf-8")
result = cli_module._load_rule_definitions(str(f))
# Plain-text fallback: the non-comment, non-blank line becomes a rule.
assert result == ["rules: null"]
def test_load_premises_formats(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
plain = tmp_path / "plain.yaml"
plain.write_text("- Person(Alice)\n- Person(Bob)\n", encoding="utf-8")
premises = cli_module._load_premises(str(plain))
assert [p.statement for p in premises] == ["Person(Alice)", "Person(Bob)"]
assert [p.confidence for p in premises] == [1.0, 1.0]
with_confidence = tmp_path / "confidence.yaml"
with_confidence.write_text(
"- {statement: 'Person(Alice)', confidence: 0.5}\n", encoding="utf-8")
premises = cli_module._load_premises(str(with_confidence))
assert premises[0].statement == "Person(Alice)"
assert premises[0].confidence == 0.5
mapping = tmp_path / "mapping.yaml"
mapping.write_text("premises:\n - Person(Alice)\n", encoding="utf-8")
premises = cli_module._load_premises(str(mapping))
assert [p.statement for p in premises] == ["Person(Alice)"]
def test_load_premises_missing_statement_raises(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
bad = tmp_path / "bad.yaml"
bad.write_text("- {confidence: 0.5}\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="missing 'statement'"):
cli_module._load_premises(str(bad))
def test_load_premises_null_key_value_raises(self, tmp_path):
"""A 'premises' key present but not a list (e.g. YAML null) must be
a clear error, not silently reinterpreted as one raw-text line
("premises: null" itself becoming a bogus premise)."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
bad = tmp_path / "bad.yaml"
bad.write_text("premises: null\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="not a list"):
cli_module._load_premises(str(bad))
def test_load_premises_empty_list_raises(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
empty = tmp_path / "empty.yaml"
empty.write_text("premises: []\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="no premises"):
cli_module._load_premises(str(empty))
def test_load_observations_formats(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
plain = tmp_path / "plain.yaml"
plain.write_text("- Human(Alice)\n", encoding="utf-8")
observations = cli_module._load_observations(str(plain))
assert [o.description for o in observations] == ["Human(Alice)"]
with_facts = tmp_path / "with_facts.yaml"
with_facts.write_text(
"- {description: 'Human(Alice)', facts: ['Person(Alice)']}\n", encoding="utf-8")
observations = cli_module._load_observations(str(with_facts))
assert observations[0].description == "Human(Alice)"
assert observations[0].facts == ["Person(Alice)"]
mapping = tmp_path / "mapping.yaml"
mapping.write_text("observations:\n - Human(Alice)\n", encoding="utf-8")
observations = cli_module._load_observations(str(mapping))
assert [o.description for o in observations] == ["Human(Alice)"]
def test_load_observations_missing_description_raises(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
bad = tmp_path / "bad.yaml"
bad.write_text("- {facts: []}\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="missing 'description'"):
cli_module._load_observations(str(bad))
def test_load_observations_null_key_value_raises(self, tmp_path):
"""A 'observations' key present but not a list (e.g. YAML null)
must be a clear error. Previously this fell through to
reinterpreting the raw file text as plain lines, turning
"observations: null" itself into one bogus Observation and letting
`reason run --engine abductive` report a misleading success."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
bad = tmp_path / "bad.yaml"
bad.write_text("observations: null\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="not a list"):
cli_module._load_observations(str(bad))
def test_load_observations_empty_list_raises(self, tmp_path):
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
empty = tmp_path / "empty.yaml"
empty.write_text("observations: []\n", encoding="utf-8")
import click as _click
with pytest.raises(_click.ClickException, match="no observations"):
cli_module._load_observations(str(empty))
def test_run_deductive_no_rules_uses_empty_ruleset(self, runner, monkeypatch):
"""--engine deductive is wired to DeductiveReasoner.apply_logic() (#1478);
it must no longer be rejected -- zero rules just means zero conclusions,
matching the rete/datalog no-op-ruleset convention."""
pytest.importorskip("numpy", reason="semantica.reasoning needs numpy")
class _EmptyStore:
def get_nodes(self, limit=None): return []
def get_relationships(self, limit=None): return []
monkeypatch.setattr(cli_module, "_get_graph_store", lambda ctx: _EmptyStore())
result = runner.invoke(
cli_module.main, ["--json", "reason", "run", "--engine", "deductive"])
_ok(result)
data = json.loads(result.output.strip())
assert data["engine"] == "deductive"
assert data["facts"] == 0
assert data["inferred_count"] == 0
assert data["inferred_facts"] == []
def test_explain_requires_conclusion(self, runner):
result = runner.invoke(cli_module.main, ["reason", "explain"])
assert result.exit_code != 0
def test_explain_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "reasoning" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["reason", "explain", "Alice is-manager-of Eng"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_query_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "reasoning" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["reason", "query", "SELECT ?x WHERE {}"])
assert result.exit_code != 0
assert "Traceback" not in result.output
# ─── decision ─────────────────────────────────────────────────────────────────
class TestDecision:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["decision", "--help"])
_ok(result)
for sub in ["record", "list", "query", "trace", "similar", "impact", "check"]:
assert sub in result.output
def test_record_requires_title(self, runner):
result = runner.invoke(cli_module.main, ["decision", "record"])
assert result.exit_code != 0
def test_record_dry_run_json(self, runner):
result = runner.invoke(cli_module.main, ["decision", "record",
"--title", "Approve X", "--dry-run", "--json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_record_global_dry_run_json(self, runner):
result = runner.invoke(cli_module.main, ["--json", "--dry-run", "decision", "record",
"--title", "Approve X"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_record_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "semantica.context" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["decision", "record", "--title", "X"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_list_json(self, runner, monkeypatch):
import datetime
fake_dq = MagicMock()
d = MagicMock()
d.decision_id = "d1"
d.scenario = "T"
d.category = "general"
d.outcome = "ok"
d.confidence = 1.0
fake_dq.find_by_time_range.return_value = [d]
fake_decision_query = _fake_module(DecisionQuery=lambda *a, **kw: fake_dq)
fake_graph_store = _fake_module(GraphStore=MagicMock(return_value=MagicMock()))
monkeypatch.setitem(__import__("sys").modules,
"semantica.context.decision_query", fake_decision_query)
monkeypatch.setitem(__import__("sys").modules,
"semantica.graph_store", fake_graph_store)
result = runner.invoke(
cli_module.main, ["decision", "list", "--format", "json"]
)
_ok(result)
# (filter, matching category, decoy category the mangled filter also hits)
# lstrip("tag:") strips leading t/a/g/: characters, so "tag:auth" became
# "uth" — which still substring-matches "auth", but ALSO matches "south".
@pytest.mark.parametrize("tag,decoy", [
("auth", "south"),
("git", "editor"),
("testing", "nesting"),
("tag", "anything-at-all"),
])
def test_query_tag_filter_does_not_match_on_mangled_prefix(
self, runner, monkeypatch, tag, decoy
):
"""--filter tag:<value> must strip the prefix, not leading characters."""
fake_dq = MagicMock()
def _decision(did, category):
d = MagicMock()
d.decision_id, d.scenario, d.category = did, "T", category
d.outcome, d.confidence = "ok", 1.0
return d
fake_dq.find_by_time_range.return_value = [
_decision("d1", tag), _decision("d2", decoy),
]
monkeypatch.setitem(__import__("sys").modules,
"semantica.context.decision_query",
_fake_module(DecisionQuery=lambda *a, **kw: fake_dq))
monkeypatch.setitem(__import__("sys").modules, "semantica.graph_store",
_fake_module(GraphStore=MagicMock(return_value=MagicMock())))
# --store neo4j: these mock DecisionQuery/GraphStore, so they must name
# the database path explicitly rather than inherit the default backend,
# which is memory and would read an empty ContextGraph.
result = runner.invoke(
cli_module.main,
["--store", "neo4j", "decision", "query", "--filter", f"tag:{tag}",
"--format", "json"],
)
_ok(result)
ids = [d["id"] for d in json.loads(result.output)]
assert ids == ["d1"], (
f"tag:{tag} matched {decoy!r} too — the prefix was stripped as "
f"characters, leaving a shorter filter"
)
def test_query_tag_filter_value_strips_prefix_only(self):
assert cli_module._tag_filter_value("tag:auth") == "auth"
assert cli_module._tag_filter_value("tag:git") == "git"
assert cli_module._tag_filter_value("tag:tag") == "tag"
assert cli_module._tag_filter_value("plain") == "plain"
@pytest.mark.parametrize("filter_str", ["tag:", ""])
def test_query_empty_tag_filter_is_rejected(self, runner, monkeypatch, filter_str):
"""An empty tag value matched every decision; it must be a usage error."""
fake_dq = MagicMock()
monkeypatch.setitem(
__import__("sys").modules,
"semantica.context.decision_query",
_fake_module(DecisionQuery=lambda *a, **kw: fake_dq),
)
monkeypatch.setitem(
__import__("sys").modules,
"semantica.graph_store",
_fake_module(GraphStore=MagicMock(return_value=MagicMock())),
)
result = runner.invoke(
cli_module.main,
["decision", "query", "--filter", filter_str, "--format", "json"],
)
assert result.exit_code != 0
fake_dq.find_by_time_range.assert_not_called()
def test_trace_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "semantica.context" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["decision", "trace", "dec_123"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_check_requires_id(self, runner):
result = runner.invoke(cli_module.main, ["decision", "check"])
assert result.exit_code != 0
@pytest.mark.parametrize("sub", ["similar", "impact"])
def test_sub_requires_id(self, runner, sub):
result = runner.invoke(cli_module.main, ["decision", sub])
assert result.exit_code != 0
class TestMemoryGraphBackend:
"""The `memory` backend routes through ContextGraph instead of GraphStore.
GraphStore has no `memory` backend, so before #1481 every one of these
commands died with `ValidationError: Unknown backend: memory` — which is
what `semantica init` writes by default.
"""
@pytest.fixture
def memory_cfg(self, tmp_path):
cfg = tmp_path / "cfg.yaml"
cfg.write_text(
"graph_db:\n"
" backend: memory\n"
f" path: {tmp_path / 'graph.json'}\n"
)
return str(cfg)
def _record(self, runner, memory_cfg, title, tags, rationale=None):
args = ["--config", memory_cfg, "decision", "record", "--title", title,
"--tags", tags]
if rationale:
args += ["--rationale", rationale]
result = runner.invoke(cli_module.main, args)
_ok(result)
return result
def test_record_then_list_persists_across_invocations(self, runner, memory_cfg):
"""A CLI is one process per command, so the graph must be written back."""
self._record(runner, memory_cfg, "Adopt Postgres", "database", "cheaper")
result = runner.invoke(
cli_module.main,
["--config", memory_cfg, "decision", "list", "--format", "json"],
)
_ok(result)
rows = json.loads(result.output)
assert [r["title"] for r in rows] == ["Adopt Postgres"]
assert rows[0]["tags"] == ["database"]
def test_record_without_rationale_succeeds(self, runner, memory_cfg):
"""--rationale is optional; ContextGraph rejects empty reasoning."""
self._record(runner, memory_cfg, "Use OAuth", "auth")
result = runner.invoke(
cli_module.main,
["--config", memory_cfg, "decision", "list", "--format", "json"],
)
_ok(result)
assert [r["title"] for r in json.loads(result.output)] == ["Use OAuth"]
def test_query_filters_by_tag(self, runner, memory_cfg):
self._record(runner, memory_cfg, "Adopt Postgres", "database", "cheaper")
self._record(runner, memory_cfg, "Use OAuth", "auth", "standard")
result = runner.invoke(
cli_module.main,
["--config", memory_cfg, "decision", "query", "--filter", "tag:database",
"--format", "json"],
)
_ok(result)
rows = json.loads(result.output)
assert [r["scenario"] for r in rows] == ["Adopt Postgres"]
def test_export_reads_the_context_graph(self, runner, memory_cfg):
self._record(runner, memory_cfg, "Adopt Postgres", "database", "cheaper")
result = runner.invoke(
cli_module.main, ["--config", memory_cfg, "export", "--format", "json"]
)
_ok(result)
payload = json.loads(result.output)
titles = [e.get("text") or e.get("name") for e in payload["entities"]]
assert "Adopt Postgres" in titles
def test_list_is_empty_before_anything_is_recorded(self, runner, memory_cfg):
"""A missing graph file is an empty graph, not an error."""
result = runner.invoke(
cli_module.main,
["--config", memory_cfg, "decision", "list", "--format", "json"],
)
_ok(result)
assert json.loads(result.output) == []
def test_check_names_the_decision_when_absent(self, runner, memory_cfg):
result = runner.invoke(
cli_module.main, ["--config", memory_cfg, "decision", "check", "nope"]
)
assert result.exit_code != 0
assert "nope" in result.output
assert "Traceback" not in result.output
def test_doctor_reports_memory_without_probing_a_server(self, runner, memory_cfg):
result = runner.invoke(cli_module.main, ["--config", memory_cfg, "doctor"])
graph_rows = [
line for line in result.output.splitlines() if "Graph store" in line
]
assert graph_rows, result.output
assert "memory" in graph_rows[0]
assert "Neo4j" not in graph_rows[0]
def _ctx(self, memory_cfg, store_backend=None):
cfg = cli_module._build_runtime_config(memory_cfg, None)
return cli_module.CLIContext(
config_path=memory_cfg, config=cfg, log_level="INFO",
store_backend=store_backend,
)
def test_resolve_backend_reads_the_config(self, memory_cfg):
ctx = self._ctx(memory_cfg)
assert cli_module._resolve_graph_backend(ctx) == "memory"
assert cli_module._uses_memory_graph(ctx) is True
def test_resolve_backend_prefers_the_store_flag(self, memory_cfg):
"""--store must win over the config file, as it does for every command."""
ctx = self._ctx(memory_cfg, store_backend="neo4j")
assert cli_module._resolve_graph_backend(ctx) == "neo4j"
assert cli_module._uses_memory_graph(ctx) is False
def test_graph_path_is_configurable(self, memory_cfg, tmp_path):
ctx = self._ctx(memory_cfg)
assert cli_module._memory_graph_path(ctx) == tmp_path / "graph.json"
def test_validity_flags_reach_the_graph_not_just_metadata(
self, runner, memory_cfg, tmp_path
):
"""ContextGraph tracks node validity itself (Qodo #2 on PR #1765).
Passing --valid-from/--valid-until only inside metadata left the
decision active outside its window.
"""
result = runner.invoke(cli_module.main, [
"--config", memory_cfg, "decision", "record", "--title", "Trial run",
"--tags", "pilot", "--rationale", "time-boxed",
"--valid-from", "2026-01-01T00:00:00",
"--valid-until", "2026-02-01T00:00:00",
])
_ok(result)
saved = json.loads((tmp_path / "graph.json").read_text())
blob = json.dumps(saved)
assert "2026-01-01" in blob and "2026-02-01" in blob
def test_check_sees_the_stored_reasoning_and_decision_maker(
self, runner, memory_cfg
):
"""check_decision_rules indexes decision["reasoning"] (Qodo #4).
The display mapping used by list/query omits it, so policy checks were
evaluating a decision that looked emptier than what was stored.
"""
self._record(runner, memory_cfg, "Adopt Postgres", "database",
"cheaper to operate")
ctx = self._ctx(memory_cfg)
stored = cli_module._memory_decisions(ctx)
assert stored, "nothing recorded"
assert stored[0]["reasoning"] == "cheaper to operate"
assert "decision_maker" in stored[0]
def test_concurrent_records_do_not_lose_each_other(self, memory_cfg, tmp_path):
"""Two processes recording at once must not drop a decision (Qodo #1).
record is a load-modify-save of the whole graph, so without a lock the
later save replaces the earlier decision, silently.
"""
import subprocess
import sys as _sys
procs = [
subprocess.Popen(
[_sys.executable, "-m", "semantica.cli", "--config", memory_cfg,
"decision", "record", "--title", f"Decision {i}",
"--tags", f"tag{i}", "--rationale", "concurrent"],
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
)
for i in range(4)
]
assert all(p.wait(timeout=120) == 0 for p in procs)
ctx = self._ctx(memory_cfg)
titles = {d["scenario"] for d in cli_module._memory_decisions(ctx)}
assert titles == {f"Decision {i}" for i in range(4)}, titles
def test_an_old_lock_held_by_a_live_writer_is_not_stolen(self, memory_cfg):
"""Age must never grant entry while the holder is alive.
An mtime-based "reclaim a lock older than N" rule lets a second writer
into the critical section whenever the first is merely slow or
suspended. The second saves, the first then saves its older snapshot,
and the second decision disappears with no error anywhere.
"""
import subprocess
import sys as _sys
ctx = self._ctx(memory_cfg)
lock = cli_module._memory_graph_path(ctx).with_suffix(".lock")
with cli_module._memory_graph_lock(ctx):
graph = cli_module._load_context_graph(ctx)
graph.record_decision(category="a", scenario="A", reasoning="r",
outcome="recorded", confidence=1.0)
# Make the lock look ancient while this writer still holds it.
lock.touch()
old = time.time() - 86_400
os.utime(lock, (old, old))
other = subprocess.run(
[_sys.executable, "-m", "semantica.cli", "--config", memory_cfg,
"decision", "record", "--title", "B", "--tags", "b",
"--rationale", "r"],
capture_output=True, text=True, timeout=120,
)
# B must be kept out, not allowed in to have its write erased.
assert other.returncode != 0, other.stdout + other.stderr
assert cli_module._memory_decisions(ctx) == [] or all(
d["scenario"] != "B" for d in cli_module._memory_decisions(ctx)
)
cli_module._save_context_graph(ctx, graph)
assert [d["scenario"] for d in cli_module._memory_decisions(ctx)] == ["A"]
def test_lock_is_released_when_the_holder_exits(self, memory_cfg):
"""The OS drops an advisory lock on process death, so no timeout guess."""
ctx = self._ctx(memory_cfg)
with cli_module._memory_graph_lock(ctx):
pass
with cli_module._memory_graph_lock(ctx): # immediately re-acquirable
pass
def test_init_then_plain_commands_need_no_config_flag(
self, runner, monkeypatch, tmp_path
):
"""The workflow #1481 is actually about: init, then plain commands.
`semantica init` writes ~/.semantica/config.yaml, but nothing read it,
so accepting its `memory` default still left every command on the
built-in fallback. Supplying --config in tests hid this entirely.
"""
home = tmp_path / "home"
home.mkdir()
monkeypatch.setattr(cli_module.Path, "home", staticmethod(lambda: home))
init = runner.invoke(cli_module.main, ["init"], input="memory\nfaiss\nnone\n")
_ok(init)
assert "backend: memory" in (home / ".semantica" / "config.yaml").read_text()
# No --config from here on.
rec = runner.invoke(cli_module.main, [
"decision", "record", "--title", "First", "--tags", "pilot",
"--rationale", "trying it out",
])
_ok(rec)
listed = runner.invoke(
cli_module.main, ["decision", "list", "--format", "json"]
)
_ok(listed)
assert [d["title"] for d in json.loads(listed.output)] == ["First"]
exported = runner.invoke(cli_module.main, ["export", "--format", "json"])
_ok(exported)
assert "First" in exported.output
def test_default_backend_is_memory_with_no_config_at_all(
self, runner, monkeypatch, tmp_path
):
"""A user who never ran init gets a working local graph, not a Neo4j error."""
home = tmp_path / "empty-home"
home.mkdir()
monkeypatch.setattr(cli_module.Path, "home", staticmethod(lambda: home))
result = runner.invoke(
cli_module.main, ["decision", "list", "--format", "json"]
)
_ok(result)
assert json.loads(result.output) == []
def test_explicit_config_still_wins_over_the_default_file(
self, runner, monkeypatch, tmp_path
):
home = tmp_path / "home2"
(home / ".semantica").mkdir(parents=True)
(home / ".semantica" / "config.yaml").write_text(
"graph_db:\n backend: memory\n"
)
monkeypatch.setattr(cli_module.Path, "home", staticmethod(lambda: home))
explicit = tmp_path / "explicit.yaml"
explicit.write_text("graph_db:\n backend: falkordb\n")
ctx_cfg = cli_module._build_runtime_config(str(explicit), None)
ctx = cli_module.CLIContext(
config_path=str(explicit), config=ctx_cfg, log_level="INFO"
)
assert cli_module._resolve_graph_backend(ctx) == "falkordb"
@staticmethod
def _init_home(monkeypatch, tmp_path, name):
"""A HOME whose ~/.semantica/config.yaml selects the memory backend."""
home = tmp_path / name
(home / ".semantica").mkdir(parents=True)
(home / ".semantica" / "config.yaml").write_text(
"graph_db:\n backend: memory\nvector_store:\n backend: faiss\n"
)
monkeypatch.setattr(cli_module.Path, "home", staticmethod(lambda: home))
return home
def test_store_override_constructs_the_real_backend(self, monkeypatch, tmp_path):
"""--store must reach GraphStore, not die assembling its arguments.
`store_backend or graph_db.pop("backend", ...)` short-circuits, so an
override left the configured backend in the kwargs and GraphStore got
`backend` twice. Auto-loading ~/.semantica/config.yaml made plain
`init` + `--store` hit it, so this asserts on construction rather than
on _resolve_graph_backend().
"""
self._init_home(monkeypatch, tmp_path, "home-override")
seen = {}
class FakeGraphStore:
def __init__(self, backend=None, **kwargs):
seen["backend"] = backend
seen["kwargs"] = kwargs
monkeypatch.setitem(
__import__("sys").modules, "semantica.graph_store",
_fake_module(GraphStore=FakeGraphStore),
)
cfg = cli_module._build_runtime_config(None, None)
ctx = cli_module.CLIContext(
config_path=None, config=cfg, log_level="INFO", store_backend="neo4j",
)
store = cli_module._get_graph_store(ctx)
assert isinstance(store, FakeGraphStore)
assert seen["backend"] == "neo4j"
assert "backend" not in seen["kwargs"], seen["kwargs"]
@pytest.mark.parametrize("args", [
["decision", "list", "--format", "json"],
["export", "--format", "json"],
])
def test_store_override_after_init_does_not_fail_on_arguments(
self, runner, monkeypatch, tmp_path, args
):
"""init then `--store neo4j <cmd>` must not raise a TypeError."""
self._init_home(monkeypatch, tmp_path, f"home-{args[0]}")
result = runner.invoke(cli_module.main, ["--store", "neo4j"] + args)
# Rich wraps the error inside a box, so collapse whitespace before
# matching: the literal phrase is split across lines in result.output.
flat = " ".join(result.output.split())
assert "multiple values for keyword argument" not in flat, flat[:300]
assert "TypeError" not in flat, flat[:300]
assert "Traceback" not in result.output
def test_get_graph_store_refuses_memory_with_a_clear_message(self, memory_cfg):
"""Safety net: a future caller that forgets to route memory gets told."""
import click as _click
with pytest.raises(_click.ClickException) as exc:
cli_module._get_graph_store(self._ctx(memory_cfg))
assert "ContextGraph" in str(exc.value)
# ─── temporal ─────────────────────────────────────────────────────────────────
class TestTemporal:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["temporal", "--help"])
_ok(result)
for sub in ["snapshot", "query", "history", "distance", "allen"]:
assert sub in result.output
def test_snapshot_requires_at(self, runner):
result = runner.invoke(cli_module.main, ["temporal", "snapshot"])
assert result.exit_code != 0
def test_snapshot_json(self, runner, monkeypatch):
fake_kg = _fake_module(
TemporalGraphQuery=lambda **kw: MagicMock(
snapshot=lambda at: {"at": at, "nodes": 5}
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.kg", fake_kg)
result = runner.invoke(cli_module.main, ["temporal", "snapshot",
"--at", "2026-01-01T00:00:00Z", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, dict)
def test_distance_requires_both_events(self, runner):
result = runner.invoke(cli_module.main, ["temporal", "distance", "--event1", "ev1"])
assert result.exit_code != 0
def test_allen_requires_both_intervals(self, runner):
result = runner.invoke(cli_module.main, ["temporal", "allen",
"--interval1", "int1", "--interval2", "int2"])
assert result.exit_code != 0 or result.exit_code == 0 # depends on import
def test_history_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.kg") else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["temporal", "history", "entity_alice"])
assert result.exit_code != 0
assert "Traceback" not in result.output
# ─── provenance ───────────────────────────────────────────────────────────────
class TestProvenance:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["provenance", "--help"])
_ok(result)
for sub in ["lineage", "audit", "export", "check"]:
assert sub in result.output
def test_lineage_requires_entity(self, runner):
result = runner.invoke(cli_module.main, ["provenance", "lineage"])
assert result.exit_code != 0
def test_lineage_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "provenance" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["provenance", "lineage", "entity_alice"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_export_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["provenance", "export", "--dry-run"])
_ok(result)
def test_audit_writes_output(self, runner, monkeypatch):
fake_prov = _fake_module(
ProvenanceManager=lambda **kw: MagicMock(
audit_log=lambda **kw2: [{"actor": "user", "action": "ingest"}]
),
)
monkeypatch.setitem(__import__("sys").modules, "semantica.provenance", fake_prov)
with runner.isolated_filesystem():
result = runner.invoke(cli_module.main, ["provenance", "audit", "--output", "audit.json"])
if result.exit_code == 0:
assert os.path.exists("audit.json")
def test_check_exits_0_when_import_error(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "provenance" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["provenance", "check"])
assert result.exit_code != 0
assert "Traceback" not in result.output
# ─── validate ─────────────────────────────────────────────────────────────────
class TestValidate:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["validate", "--help"])
_ok(result)
for sub in ["shacl", "conflicts", "integrity"]:
assert sub in result.output
def test_shacl_help(self, runner):
result = runner.invoke(cli_module.main, ["validate", "shacl", "--help"])
_ok(result)
assert "--strictness" in result.output
def test_shacl_import_error_is_clean(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "ontology" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["validate", "shacl"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_conflicts_json(self, runner, monkeypatch):
fake_conf = _fake_module(
detect_conflicts=lambda **kw: {"conflicts": [], "count": 0},
)
monkeypatch.setitem(__import__("sys").modules, "semantica.conflicts", fake_conf)
result = runner.invoke(cli_module.main, ["validate", "conflicts", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, dict)
def test_integrity_exits_0_with_import_error(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if n.startswith("semantica.kg") else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["validate", "integrity"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_strictness_choices(self, runner):
result = runner.invoke(cli_module.main, ["validate", "shacl", "--help"])
for s in ["strict", "moderate", "lenient"]:
assert s in result.output
# ─── ontology ─────────────────────────────────────────────────────────────────
class TestOntology:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "--help"])
_ok(result)
for sub in ["generate", "import", "validate", "shacl", "skos",
"align", "health", "version"]:
assert sub in result.output
def test_generate_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "generate", "--dry-run"])
_ok(result)
def test_generate_json_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "generate", "--dry-run", "--json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_generate_global_json_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["--json", "--dry-run", "ontology", "generate"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_import_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "import", "schema.ttl", "--dry-run"])
_ok(result)
def test_import_requires_source(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "import"])
assert result.exit_code != 0
def test_skos_group_help(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "skos", "--help"])
_ok(result)
for sub in ["search", "hierarchy"]:
assert sub in result.output
def test_skos_search_requires_term(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "skos", "search"])
assert result.exit_code != 0
def test_skos_hierarchy_requires_uri(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "skos", "hierarchy"])
assert result.exit_code != 0
def test_align_requires_source_and_target(self, runner):
result = runner.invoke(cli_module.main, ["ontology", "align"])
assert result.exit_code != 0
def test_align_import_error_is_clean(self, runner):
with runner.isolated_filesystem():
with open("s.ttl", "w") as f:
f.write("")
with open("t.ttl", "w") as f:
f.write("")
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "ontology" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["ontology", "align",
"--source", "s.ttl", "--target", "t.ttl"])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_health_exits_0_with_import_error(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "ontology" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["ontology", "health"])
assert result.exit_code != 0
assert "Traceback" not in result.output
# ─── export ───────────────────────────────────────────────────────────────────
# The record shape the Neo4j and FalkorDB backends return: endpoints named
# start_node_id/end_node_id, and get_nodes() nesting its fields under
# "properties". The local store uses source_id/target_id, so a fixture written
# against it hid the fact that the command fed the exporters a shape they could
# not read (#1712).
STORE_NODES = [
{"id": "n1", "type": "Person", "name": "Alice", "properties": {"name": "Alice"}}
]
STORE_RELATIONSHIP = {
"id": "r1",
"start_node_id": "n1",
"end_node_id": "n1",
"type": "KNOWS",
"properties": {},
}
# The extension each multi-file format is written under, checked against the
# list the command refuses a single destination for.
MULTI_FILE_EXTENSIONS = {"arrow": ".arrow", "csv": ".csv", "parquet": ".parquet"}
def _patch_graph_store(monkeypatch, relationships, nodes=None) -> dict:
"""Point the export command at a fake store, and count how often it reads."""
node_records = STORE_NODES if nodes is None else nodes
reads = {"nodes": 0}
def get_nodes(**kwargs):
reads["nodes"] += 1
return [dict(n) for n in node_records]
def get_relationships(**kwargs):
return [dict(r) for r in relationships]
class FakeGraphStore:
def get_nodes(self, **kwargs):
return get_nodes(**kwargs)
def get_relationships(self, **kwargs):
return get_relationships(**kwargs)
monkeypatch.setattr(
"semantica.graph_store.methods._get_store", lambda: FakeGraphStore()
)
for target in (
"semantica.graph_store.get_nodes",
"semantica.graph_store.methods.get_nodes",
):
monkeypatch.setattr(target, get_nodes)
for target in (
"semantica.graph_store.get_relationships",
"semantica.graph_store.methods.get_relationships",
):
monkeypatch.setattr(target, get_relationships)
return reads
def test_multi_file_extensions_cover_what_the_command_lists():
from semantica.export import MULTI_FILE_FORMATS
assert set(MULTI_FILE_EXTENSIONS) == set(
MULTI_FILE_FORMATS
), "a multi-file format was added or removed without updating these tests"
class TestExport:
def test_help_shows_the_offered_formats(self, runner):
result = runner.invoke(cli_module.main, ["export", "--help"])
_ok(result)
for fmt in cli_module._EXPORT_FORMATS:
assert fmt in result.output
# These three need an ontology or an Explorer session, not a graph
# dump, so they are no longer offered (#1712).
for fmt in ["owl", "shacl", "distance-enriched"]:
assert fmt not in result.output
for flag in ["--with-provenance", "--filter", "--compress", "--dry-run"]:
assert flag in result.output
def test_dry_run_json(self, runner):
result = runner.invoke(cli_module.main, ["export", "--format", "turtle",
"--dry-run", "--json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_dry_run_text(self, runner):
result = runner.invoke(cli_module.main, ["export", "--format", "csv", "--dry-run"])
_ok(result, substr="Dry run")
def test_global_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["--dry-run", "--json", "export", "--format", "json"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_real_export_runtime_path(self, runner, tmp_path, monkeypatch):
_patch_graph_store(monkeypatch, [STORE_RELATIONSHIP])
output_path = tmp_path / "export.json"
result = runner.invoke(cli_module.main, [
"--store", "neo4j", "export", "--format", "json",
"--output", str(output_path),
])
_ok(result)
exported = output_path.read_text(encoding="utf-8")
assert "Alice" in exported
assert "KNOWS" in exported
def test_invalid_format_fails(self, runner):
result = runner.invoke(cli_module.main, ["export", "--format", "magic"])
assert result.exit_code != 0
def test_import_error_is_clean(self, runner):
original_import = __import__
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "semantica.export" in n else original_import(n, *a, **k)
)):
result = runner.invoke(
cli_module.main, ["--store", "neo4j", "export", "--format", "json"]
)
assert result.exit_code != 0
assert "Traceback" not in result.output
class TestExportMultiFileFormats:
"""Formats that write one file per collection, driven through the command.
``arrow``, ``csv`` and ``parquet`` take ``--output`` as a base name and
write ``graph_entities.*``/``graph_relationships.*`` next to it, so the
path the command was given is never created. It used to report that path as
written anyway, hand stdout an empty file, and compress a base file that
did not exist.
"""
@pytest.mark.parametrize("fmt,ext", sorted(MULTI_FILE_EXTENSIONS.items()))
def test_reports_the_files_it_wrote(self, runner, tmp_path, monkeypatch, fmt, ext):
_patch_graph_store(monkeypatch, [STORE_RELATIONSHIP])
target = tmp_path / f"graph{ext}"
result = runner.invoke(
cli_module.main,
["--store", "neo4j", "export", "--format", fmt, "--output", str(target)]
)
_ok(result)
names = sorted(p.name for p in tmp_path.iterdir())
assert names == [f"graph_entities{ext}", f"graph_relationships{ext}"], names
for name in names:
assert name in result.output, f"{name} not reported: {result.output!r}"
assert not target.exists(), (
"the command was asked for a base name; it must not be reported as "
"the artifact"
)
@pytest.mark.parametrize("fmt,ext", sorted(MULTI_FILE_EXTENSIONS.items()))
@pytest.mark.parametrize(
"flags,mention",
[([], "--output"), (["--compress"], "--compress")],
)
def test_a_single_destination_is_refused(
self, runner, tmp_path, monkeypatch, fmt, ext, flags, mention
):
reads = _patch_graph_store(monkeypatch, [STORE_RELATIONSHIP])
result = runner.invoke(cli_module.main, ["export", "--format", fmt] + flags)
assert result.exit_code != 0, f"{flags} exited 0: {result.output!r}"
assert mention in result.output, f"{result.output!r} does not mention {mention}"
assert reads["nodes"] == 0, "the store was read before the format was refused"
def test_arrow_without_relationships_still_exports(
self, runner, tmp_path, monkeypatch
):
"""A graph whose nodes have no edges between them is not an error."""
_patch_graph_store(monkeypatch, [])
target = tmp_path / "graph.arrow"
result = runner.invoke(
cli_module.main,
["--store", "neo4j", "export", "--format", "arrow", "--output", str(target)]
)
_ok(result)
assert (tmp_path / "graph_entities.arrow").exists()
assert not (tmp_path / "graph_relationships.arrow").exists()
@pytest.mark.parametrize("fmt,ext", sorted(MULTI_FILE_EXTENSIONS.items()))
def test_an_empty_store_writes_nothing_and_says_so(
self, runner, tmp_path, monkeypatch, fmt, ext
):
_patch_graph_store(monkeypatch, [], nodes=[])
target = tmp_path / f"graph{ext}"
result = runner.invoke(
cli_module.main,
["--store", "neo4j", "export", "--format", fmt, "--output", str(target)]
)
_ok(result)
assert "Nothing written" in result.output, result.output
assert not list(tmp_path.iterdir())
# ─── visualize ────────────────────────────────────────────────────────────────
class TestVisualize:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["visualize", "--help"])
_ok(result)
for sub in ["kg", "ontology", "embeddings", "temporal", "analytics"]:
assert sub in result.output
@pytest.mark.parametrize("sub", ["kg", "ontology", "embeddings", "temporal", "analytics"])
def test_subcommand_help(self, runner, sub):
result = runner.invoke(cli_module.main, ["visualize", sub, "--help"])
_ok(result)
for flag in ["--layout", "--format", "--output"]:
assert flag in result.output
@pytest.mark.parametrize("sub", ["kg", "ontology", "embeddings", "temporal", "analytics"])
def test_import_error_is_clean(self, runner, sub):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "visualization" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["visualize", sub])
assert result.exit_code != 0
assert "Traceback" not in result.output
def test_format_choices(self, runner):
result = runner.invoke(cli_module.main, ["visualize", "kg", "--help"])
for fmt in ["html", "svg", "png", "pdf"]:
assert fmt in result.output
def test_layout_choices(self, runner):
result = runner.invoke(cli_module.main, ["visualize", "kg", "--help"])
for layout in ["forceatlas2", "spring", "hierarchical"]:
assert layout in result.output
# ─── pipeline ─────────────────────────────────────────────────────────────────
class TestPipeline:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "--help"])
_ok(result)
for sub in ["init", "validate", "run", "status", "stop"]:
assert sub in result.output
def test_init_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "init", "--dry-run"])
_ok(result)
def test_init_templates_match_the_manager(self, runner):
# The CLI hardcoded five template names the manager has never registered,
# so every `pipeline init` would have reached "Template not found" once the
# wrapper called the real API. Keep the two lists in step.
from semantica.pipeline import PipelineTemplateManager
manager = PipelineTemplateManager()
assert cli_module._PIPELINE_TEMPLATES == manager.list_templates()
def test_init_creates_a_loadable_pipeline(self, runner):
with runner.isolated_filesystem():
result = runner.invoke(
cli_module.main,
["pipeline", "init", "--template", "rag_pipeline",
"--output", "pl.yaml"],
)
_ok(result)
pipeline = cli_module._load_pipeline_file("pl.yaml")
assert [s.name for s in pipeline.steps] == [
"ingest", "chunk", "embed", "store_vectors",
]
def test_init_writes_the_pipeline_not_a_placeholder(self, runner):
# The old ImportError path silently wrote "# Pipeline template: X\nsteps: []".
with runner.isolated_filesystem():
result = runner.invoke(
cli_module.main,
["pipeline", "init", "--output", "pl.yaml"],
)
_ok(result)
text = open("pl.yaml").read()
assert "steps: []" not in text
assert "type: ingest" in text
def test_init_help_offers_only_real_templates(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "init", "--help"])
_ok(result)
for gone in ["ingest-extract-kg", "decision-track", "ontology-build"]:
assert gone not in result.output
for real in ["document_processing", "rag_pipeline"]:
assert real in result.output
def test_validate_requires_file(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "validate"])
assert result.exit_code != 0
def test_validate_nonexistent_file_fails(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "validate", "no_such.yaml"])
assert result.exit_code != 0
def test_validate_reads_the_file_instead_of_the_path(self, runner):
# Regression: validate() was handed the *path string*. A str has no steps,
# so it type-checked nothing and reported valid for any input.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps:\n - name: a\n type: ingest\n")
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml", "--json"],
)
_ok(result)
payload = json.loads([
line for line in result.output.splitlines() if line.startswith("{")
][-1])
assert payload["valid"] is True
assert payload["pipeline"] == "pl.yaml"
# The loader leaves handlers off, and the validator says so.
assert any("no handler" in w for w in payload["warnings"])
def test_validate_reports_a_missing_dependency(self, runner):
# Before the fix this exact file was reported valid, because it was never
# loaded.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write(
"steps:\n"
" - name: a\n"
" type: ingest\n"
" dependencies: [nope]\n"
)
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml"],
)
assert result.exit_code != 0
assert "Missing dependency 'nope'" in _flatten(result.output)
def test_validate_rejects_a_file_that_is_not_a_pipeline(self, runner):
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("just a string\n")
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml"],
)
assert result.exit_code != 0
assert "not a pipeline definition" in _flatten(result.output)
def test_validate_rejects_a_step_the_builder_would_drop(self, runner):
# build_pipeline() keeps a step only when both name and type are truthy,
# so a half-written step vanished before the validator ran and the file
# was reported valid (#2026).
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write(
"steps:\n"
" - name: ingest\n"
" type: ingest\n"
" - name: broken\n"
" config: {}\n"
)
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "steps[1]" in flat
assert "broken" in flat
assert "non-empty 'type'" in flat
def test_validate_json_reports_a_dropped_step_in_its_own_shape(self, runner):
# The structured object has to survive the loader rejecting the file,
# otherwise --json callers only see the generic error envelope.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write(
"steps:\n"
" - name: ingest\n"
" type: ingest\n"
" - name: broken\n"
" config: {}\n"
)
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml", "--json"],
)
assert result.exit_code != 0
payload = json.loads([
line for line in result.output.splitlines() if line.startswith("{")
][-1])
assert payload["valid"] is False
assert payload["pipeline"] == "pl.yaml"
assert payload["errors"] == ["steps[1] ('broken') is missing a non-empty 'type'"]
assert payload["warnings"] == []
def test_validate_rejects_a_step_that_is_not_a_mapping(self, runner):
# Used to reach dict() inside deserialize_pipeline and surface as
# "dictionary update sequence element #0 has length 1; 2 is required".
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps:\n - just-a-string\n")
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "steps[0] is not a mapping (got str)" in flat
assert "dictionary update sequence" not in flat
def test_validate_json_reports_a_builder_rejection_in_its_own_shape(self, runner):
# deserialize_pipeline() runs builder validation, which raises on a
# missing dependency. --json used to fall through to the error envelope
# on stderr instead of printing {valid, errors, warnings, pipeline}.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write(
"steps:\n"
" - name: orphan\n"
" type: export\n"
" dependencies: [does_not_exist]\n"
)
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml", "--json"],
)
assert result.exit_code != 0
payload = json.loads([
line for line in result.output.splitlines() if line.startswith("{")
][-1])
assert payload["valid"] is False
assert payload["errors"] == [
"Missing dependency 'does_not_exist' for step 'orphan'"
]
assert payload["warnings"] == []
assert payload["pipeline"] == "pl.yaml"
def test_validate_json_keeps_the_object_for_a_non_pipeline_file(self, runner):
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("just a string\n")
result = runner.invoke(
cli_module.main,
["pipeline", "validate", "pl.yaml", "--json"],
)
assert result.exit_code != 0
payload = json.loads([
line for line in result.output.splitlines() if line.startswith("{")
][-1])
assert payload["valid"] is False
assert "not a pipeline definition" in payload["errors"][0]
def test_run_rejects_a_step_the_builder_would_drop(self, runner):
# run loads through the same helper, so it must not silently execute a
# pipeline that is missing a step.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write(
"steps:\n"
" - name: ingest\n"
" type: ingest\n"
" - name: broken\n"
" config: {}\n"
)
result = runner.invoke(
cli_module.main,
["pipeline", "run", "pl.yaml"],
)
assert result.exit_code != 0
assert "steps[1]" in _flatten(result.output)
def test_run_dry_run(self, runner):
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps: []\n")
result = runner.invoke(cli_module.main, ["pipeline", "run", "pl.yaml", "--dry-run"])
_ok(result)
def test_run_requires_file(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "run"])
assert result.exit_code != 0
def test_run_refuses_steps_that_have_no_handler(self, runner):
# A pipeline loaded from a file can never carry handlers, and
# _execute_step() returns its input untouched when handler is None, so
# executing would report success having done nothing.
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps:\n - name: ingest\n type: ingest\n")
result = runner.invoke(
cli_module.main,
["pipeline", "run", "pl.yaml"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "no handler" in flat
assert "ingest" in flat
def test_run_executes_a_pipeline_with_handlers(self, runner, monkeypatch):
# The wiring itself: execute_pipeline() has to receive the loaded Pipeline,
# and --parallel has to land on pipeline.config, the only place the engine
# reads parallelism from.
from semantica.pipeline import PipelineBuilder
builder = PipelineBuilder()
builder.register_step_handler("ingest", lambda data, **kw: data)
builder.add_step("ingest", "ingest")
handled = builder.build()
seen = {}
class _Engine:
def __init__(self, config=None):
seen["config"] = config
def execute_pipeline(self, pipeline, **options):
seen["pipeline"] = pipeline
return _fake_module(
success=True,
errors=[],
metadata={"pipeline_id": pipeline.name, "execution_time": 0.5},
)
monkeypatch.setattr(cli_module, "_load_pipeline_file", lambda path: handled)
monkeypatch.setitem(__import__("sys").modules, "semantica.pipeline",
_fake_module(ExecutionEngine=_Engine))
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps: []\n")
result = runner.invoke(
cli_module.main,
["pipeline", "run", "pl.yaml", "--parallel", "7"],
)
_ok(result)
assert seen["pipeline"] is handled
assert seen["pipeline"].config["parallelism"] == 7
assert "Pipeline completed" in _flatten(result.output)
def test_run_reports_a_failed_pipeline(self, runner, monkeypatch):
from semantica.pipeline import PipelineBuilder
builder = PipelineBuilder()
builder.register_step_handler("ingest", lambda data, **kw: data)
builder.add_step("ingest", "ingest")
handled = builder.build()
class _Engine:
def __init__(self, config=None):
pass
def execute_pipeline(self, pipeline, **options):
return _fake_module(success=False, errors=["boom"], metadata={})
monkeypatch.setattr(cli_module, "_load_pipeline_file", lambda path: handled)
monkeypatch.setitem(__import__("sys").modules, "semantica.pipeline",
_fake_module(ExecutionEngine=_Engine))
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps: []\n")
result = runner.invoke(cli_module.main, ["pipeline", "run", "pl.yaml"])
assert result.exit_code != 0
assert "boom" in _flatten(result.output)
def test_run_rejects_watch(self, runner):
with runner.isolated_filesystem():
with open("pl.yaml", "w") as f:
f.write("steps:\n - name: ingest\n type: ingest\n")
result = runner.invoke(
cli_module.main,
["pipeline", "run", "pl.yaml", "--watch"],
)
assert result.exit_code != 0
assert "--watch" in _flatten(result.output)
def test_status_reports_it_cannot_observe_another_process(self, runner):
# The engine keeps pipeline status in memory, so a separate `pipeline run`
# process is not observable from here.
result = runner.invoke(cli_module.main, ["pipeline", "status"])
assert result.exit_code != 0
assert "no source of truth" in _flatten(result.output)
assert "Traceback" not in result.output
def test_stop_reports_it_cannot_reach_another_process(self, runner):
result = runner.invoke(cli_module.main, ["pipeline", "stop"])
assert result.exit_code != 0
assert "nothing to stop" in _flatten(result.output)
assert "Traceback" not in result.output
# ─── store ────────────────────────────────────────────────────────────────────
class TestStore:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["store", "--help"])
_ok(result)
for sub in ["list", "connect", "stats", "migrate", "flush"]:
assert sub in result.output
def test_list_json_empty_config(self, runner):
result = runner.invoke(cli_module.main, ["store", "list", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, dict)
def test_list_table(self, runner):
result = runner.invoke(cli_module.main, ["store", "list"])
_ok(result)
def test_connect_requires_backend(self, runner):
result = runner.invoke(cli_module.main, ["store", "connect"])
assert result.exit_code != 0
def test_connect_reports_status(self, runner):
result = runner.invoke(cli_module.main, ["store", "connect", "--backend", "neo4j"])
_ok(result)
def test_connect_dispatches_through_graph_store(self, runner, monkeypatch):
# store connect used to call get_graph_store_method(backend) — the
# method registry, which needs (task, method_name) — so it raised a
# TypeError before any connection attempt (#1354).
calls = {}
class _FakeGraphStore:
def __init__(self, backend=None, **cfg):
calls["backend"] = backend
calls["cfg"] = cfg
def connect(self):
calls["connected"] = True
return True
import semantica.graph_store as gs_mod
monkeypatch.setattr(gs_mod, "GraphStore", _FakeGraphStore)
result = runner.invoke(cli_module.main, [
"store", "connect", "--backend", "neo4j",
"--uri", "bolt://example:7687", "--json"])
_ok(result)
data = _json_output(result)
assert data == {"backend": "neo4j", "connected": True}
assert calls["backend"] == "neo4j"
assert calls["cfg"].get("uri") == "bolt://example:7687"
assert calls.get("connected") is True
def test_connect_invalid_backend_reports_error_not_dispatch_error(self, runner):
"""An unknown backend name must produce a meaningful backend error, not a
Python TypeError from the old get_graph_store_method() dispatch (#1354)."""
result = runner.invoke(cli_module.main,
["store", "connect", "--backend", "does-not-exist"])
# Exit 0 because store_connect always catches and reports errors gracefully.
_ok(result)
# The output must mention the backend, not a Python internal error.
assert "does-not-exist" in result.output
assert "TypeError" not in result.output
assert "Traceback" not in result.output
def test_connect_backend_error_surfaces_in_json(self, runner, monkeypatch):
"""A connect() failure must appear in JSON output as connected=False with an error field."""
class _FailingStore:
def __init__(self, backend=None, **cfg):
pass
def connect(self):
raise RuntimeError("auth failed")
import semantica.graph_store as gs_mod
monkeypatch.setattr(gs_mod, "GraphStore", _FailingStore)
result = runner.invoke(cli_module.main, [
"store", "connect", "--backend", "neo4j", "--json"])
_ok(result)
data = _json_output(result)
assert data["connected"] is False
assert "auth failed" in data.get("error", "")
assert data["backend"] == "neo4j"
def test_migrate_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "faiss", "--to", "qdrant", "--dry-run"])
_ok(result)
def test_migrate_requires_from_and_to(self, runner):
result = runner.invoke(cli_module.main, ["store", "migrate", "--from", "faiss"])
assert result.exit_code != 0
def test_migrate_refuses_unsupported_backend_pair(self, runner):
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "faiss", "--to", "qdrant"])
assert result.exit_code != 0
# Rich may wrap the error message across lines; check for each backend
# name individually rather than the exact comma-joined string.
output = result.output
assert "faiss" in output
assert "pgvector" in output
assert "sqlite" in output
def _fake_migrate_store_module(self, source_items, stored, dest_configs=None):
class _FakeBackendStore:
def __init__(self, dimension=None):
self.dimension = dimension
class _FakeStore:
def __init__(self, backend, config=None, **kw):
self.backend = backend
self._config = config or {}
dim = self._config.get("dimension")
self._backend_store = _FakeBackendStore(dimension=dim)
if dest_configs is not None:
dest_configs[backend] = dict(self._config)
def iter_vectors(self, batch_size=500):
if self.backend == "sqlite":
yield from source_items
return
return
yield # pragma: no cover - makes this a generator for other backends
def store_vectors(self, vectors, metadata, ids=None):
for vec_id, meta in zip(ids, metadata):
stored[vec_id] = meta
return _fake_module(VectorStore=_FakeStore)
def test_migrate_runs_between_supported_backends(self, runner, monkeypatch):
source_items = [
{"id": "a", "vector": [0.1, 0.2], "metadata": {"tag": "x"}},
{"id": "b", "vector": [0.3, 0.4], "metadata": {}},
]
stored = {}
fake_vs = self._fake_migrate_store_module(source_items, stored)
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "sqlite", "--to", "pgvector",
"--namespace", "prod", "--json"])
_ok(result)
data = _json_output(result)
assert data == {"from": "sqlite", "to": "pgvector", "migrated": 2}
assert stored == {"a": {"tag": "x", "namespace": "prod"}, "b": {"namespace": "prod"}}
def test_migrate_reports_zero_for_empty_source(self, runner, monkeypatch):
stored = {}
fake_vs = self._fake_migrate_store_module([], stored)
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "sqlite", "--to", "pgvector", "--json"])
_ok(result)
assert _json_output(result)["migrated"] == 0
assert stored == {}
def test_migrate_inherits_source_dimension_into_dest(self, runner, monkeypatch):
source_items = [{"id": "a", "vector": [0.1, 0.2, 0.3], "metadata": {}}]
stored = {}
dest_configs: dict = {}
fake_vs = self._fake_migrate_store_module(source_items, stored, dest_configs)
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
monkeypatch.setattr(
cli_module.Config, "to_dict",
lambda self: {"vector_store": {"sqlite": {"dimension": 3}, "pgvector": {}}},
)
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "sqlite", "--to", "pgvector", "--json"])
_ok(result)
assert dest_configs["pgvector"].get("dimension") == 3
def test_migrate_retry_reloads_persisted_faiss_state(
self, runner, monkeypatch, tmp_path
):
pytest.importorskip("faiss")
import numpy as np
from semantica.vector_store.faiss_store import FAISSStore
index_path = tmp_path / "migrated.faiss"
source_items = [
{"id": "a", "vector": [0.1, 0.2, 0.3], "metadata": {"tag": "x"}},
{"id": "b", "vector": [0.4, 0.5, 0.6], "metadata": {"tag": "y"}},
]
class _SourceBackend:
dimension = 3
class _MigrationStore:
def __init__(self, backend, config=None, **kw):
self.backend = backend
if backend == "sqlite":
self._backend_store = _SourceBackend()
else:
self._backend_store = FAISSStore(dimension=3)
self._backend_store.create_index(index_type="flat")
def iter_vectors(self, batch_size=500):
if self.backend == "sqlite":
yield from source_items
def store_vectors(self, vectors, metadata, ids=None):
self._backend_store.add_vectors(
np.asarray(vectors, dtype=np.float32),
ids=ids,
metadata=metadata,
)
fake_vs = _fake_module(VectorStore=_MigrationStore)
monkeypatch.setitem(
__import__("sys").modules, "semantica.vector_store", fake_vs
)
monkeypatch.setattr(
cli_module.Config,
"to_dict",
lambda self: {
"vector_store": {
"sqlite": {"dimension": 3},
"faiss": {"dimension": 3, "index_path": str(index_path)},
}
},
)
command = [
"store",
"migrate",
"--from",
"sqlite",
"--to",
"faiss",
"--json",
]
first_result = runner.invoke(cli_module.main, command)
_ok(first_result)
first_load = FAISSStore(dimension=3)
first_load.load_index(index_path, index_type="flat")
assert first_load.index.vector_ids == ["a", "b"]
assert first_load.index.index.ntotal == 2
retry_result = runner.invoke(cli_module.main, command)
_ok(retry_result)
retry_load = FAISSStore(dimension=3)
retry_load.load_index(index_path, index_type="flat")
assert retry_load.index.vector_ids == ["a", "b"]
assert retry_load.index.index.ntotal == 2
def test_migrate_faiss_source_requires_index_path(self, runner, monkeypatch):
fake_vs = _fake_module(VectorStore=lambda **kw: MagicMock())
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "faiss", "--to", "sqlite"])
assert result.exit_code != 0
assert "index_path" in result.output
def test_migrate_faiss_dest_requires_index_path(self, runner, monkeypatch):
fake_vs = _fake_module(VectorStore=lambda **kw: MagicMock())
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["store", "migrate",
"--from", "sqlite", "--to", "faiss"])
assert result.exit_code != 0
assert "index_path" in result.output
def test_flush_requires_confirm(self, runner):
result = runner.invoke(cli_module.main, ["store", "flush"])
assert result.exit_code != 0
assert "confirm" in result.output.lower() or result.exit_code == 2
def test_flush_with_confirm(self, runner, monkeypatch):
fake_vs = _fake_module(delete_vectors=lambda **kw: None)
monkeypatch.setitem(__import__("sys").modules, "semantica.vector_store", fake_vs)
result = runner.invoke(cli_module.main, ["store", "flush", "--confirm"])
_ok(result)
def test_stats_requires_backend(self, runner):
result = runner.invoke(cli_module.main, ["store", "stats"])
assert result.exit_code != 0
# ─── backup ───────────────────────────────────────────────────────────────────
class TestBackup:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["backup", "--help"])
_ok(result)
for sub in ["info", "create", "sync", "restore", "schedule"]:
assert sub in result.output
def test_info_json_empty_config(self, runner):
result = runner.invoke(cli_module.main, ["backup", "info", "--json"])
_ok(result)
data = _json_output(result)
assert isinstance(data, list)
def test_info_redacts_credentials(self, runner):
# Config normalizes store.graph → graph_db
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: neo4j\n"
" uri: bolt://user:secret123@host:7687\n"
)
result = runner.invoke(cli_module.main, ["--config", "cfg.yaml", "backup", "info"])
_ok(result)
assert "secret123" not in result.output
def test_info_shows_redacted_uri_in_output(self, runner):
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: neo4j\n"
" uri: bolt://user:secret123@host:7687\n"
)
result = runner.invoke(cli_module.main, ["--config", "cfg.yaml", "backup", "info"])
_ok(result)
assert "neo4j" in result.output
assert "graph" in result.output
def test_info_flags_cloud_backends_as_export(self, runner):
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
# vector_store is the correct key in Config
f.write("vector_store:\n backend: pinecone\n host: x\n")
result = runner.invoke(cli_module.main, ["--config", "cfg.yaml", "backup", "info"])
_ok(result)
assert "export" in result.output
def test_create_dry_run(self, runner):
with runner.isolated_filesystem():
os.makedirs("kg")
with open("kg/graph.db", "w") as f:
f.write("data")
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: sqlite\n path: kg\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "backup.tar.gz", "--dry-run"],
)
_ok(result)
assert "Dry run: would backup create" in _flatten(result.output)
def test_create_unencrypted_with_config_requires_confirm(self, runner):
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: neo4j\n uri: bolt://localhost\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz"],
input="n\n",
)
assert result.exit_code != 0
def test_create_strip_config_skips_confirm(self, runner):
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: neo4j\n uri: bolt://localhost\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--quiet"],
)
assert "Traceback" not in result.output
@pytest.mark.parametrize("extra", [["--strip-config"], [], ["--encrypt"]])
def test_create_without_stores_fails(self, runner, monkeypatch, tmp_path, extra):
# Regression for #1820: no store paths used to write an archive
# with "files": [] and exit 0. It must also fail before asking for
# a passphrase or confirmation.
monkeypatch.setattr(cli_module.Path, "home", staticmethod(lambda: tmp_path))
with runner.isolated_filesystem():
result = runner.invoke(
cli_module.main,
["backup", "create", "out.tar.gz", "--quiet", *extra],
)
assert result.exit_code != 0
assert "No store data to back up" in result.output
assert "passphrase" not in result.output
assert "Continue without encryption" not in result.output
assert not os.path.exists("out.tar.gz")
def test_create_with_local_store_writes_its_files(self, runner):
with runner.isolated_filesystem():
os.makedirs("kg")
with open("kg/graph.db", "w") as f:
f.write("data")
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: sqlite\n path: kg\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--quiet"],
)
_ok(result)
with tarfile.open("out.tar.gz") as tar:
names = tar.getnames()
assert "semantica-backup/graph/graph.db" in names
def test_create_reports_a_store_whose_path_is_missing(self, runner):
# Regression for #2009: a configured store whose path does not exist was
# dropped without a word, so the archive was partial and still reported
# success. The skip must be named, and recorded in the manifest.
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: missing_graph.json\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config"],
)
_ok(result)
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "missing_graph.json" in flat
with tarfile.open("out.tar.gz") as tar:
names = tar.getnames()
manifest = json.loads(
tar.extractfile("semantica-backup/backup_manifest.json").read()
)
assert "semantica-backup/vector/index.json" in names
assert not any(n.startswith("semantica-backup/graph/") for n in names)
assert manifest["skipped"] == [
{"store": "graph", "backend": "local", "path": "missing_graph.json"}
]
def test_create_fail_on_skip_exits_nonzero_without_writing(self, runner):
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: missing_graph.json\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--fail-on-skip"],
)
assert result.exit_code != 0
assert "Configured store path does not exist" in _flatten(result.output)
assert not os.path.exists("out.tar.gz")
def test_create_records_no_skipped_entries_when_paths_exist(self, runner):
# A store the caller simply has not configured is not a skip, and a
# backend with no local path key (cloud) must not be reported either.
with runner.isolated_filesystem():
os.makedirs("kg")
with open("kg/graph.db", "w") as f:
f.write("data")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: sqlite\n"
" path: kg\n"
"vector_store:\n"
" backend: pinecone\n"
" index: demo\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config"],
)
_ok(result)
assert "Skipping" not in _flatten(result.output)
with tarfile.open("out.tar.gz") as tar:
manifest = json.loads(
tar.extractfile("semantica-backup/backup_manifest.json").read()
)
assert manifest["skipped"] == []
def test_collect_backup_sources_separates_missing_paths(self, runner):
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
cfg = {
"graph_db": {"backend": "local", "path": "gone.json"},
"vector_store": {"backend": "local", "path": "vecs"},
"triplet_store": {"backend": "pinecone", "index": "demo"},
}
sources, skipped = cli_module._collect_backup_sources(
cfg, None, "all", strip_config=True,
)
assert [arcname for arcname, _ in sources] == ["vector/index.json"]
assert skipped == [
{"store": "graph", "backend": "local", "path": "gone.json"}
]
def test_create_reports_a_store_whose_directory_is_empty(self, runner):
# Regression for #2014: a configured store whose path exists but holds
# no files took the is_dir() branch, contributed nothing, and never
# reached `skipped`, so the manifest reported "skipped": [] and the
# command exited 0.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config"],
)
_ok(result)
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
with tarfile.open("out.tar.gz") as tar:
manifest = json.loads(
tar.extractfile("semantica-backup/backup_manifest.json").read()
)
assert manifest["skipped"] == [
{"store": "graph", "backend": "local", "path": "empty_graph"}
]
def test_create_empty_dir_fail_on_skip_exits_nonzero(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--fail-on-skip"],
)
assert result.exit_code != 0
assert "Configured store path does not exist" in _flatten(result.output)
assert not os.path.exists("out.tar.gz")
def test_create_dry_run_fail_on_skip_exits_nonzero(self, runner):
# #2109: a dry run has to match the real command.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--dry-run", "--fail-on-skip"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert "Configured store path does not exist" in flat
assert not os.path.exists("out.tar.gz")
@pytest.mark.parametrize("extra_args", [[], ["--fail-on-skip"]])
def test_create_dry_run_fails_when_no_store_has_data(self, runner, extra_args):
# #2122: --dry-run previewed a backup the real command refuses to
# write, so it exited 0 on a config where nothing would be archived.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: missing_vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--dry-run", *extra_args],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert "Skipping vector store" in flat
assert "missing_vecs" in flat
assert "No store data to back up" in flat
assert "Dry run: would backup create" not in flat
assert not os.path.exists("out.tar.gz")
def test_create_dry_run_without_store_config_fails(self, runner):
# Same #2122 case as above with no store configured at all: the real
# command refuses it (#1820), so the preview must too.
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write("processing:\n batch_size: 8\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--dry-run"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "No store data to back up" in flat
assert "Skipping" not in flat
def test_create_dry_run_json_fails_when_no_store_has_data(self, runner):
# --json must not print a payload for a preview that cannot happen.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: local\n path: empty_graph\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "--json", "backup", "create",
"out.tar.gz", "--strip-config", "--dry-run"],
)
assert result.exit_code != 0
assert result.stdout.strip() == ""
assert "No store data to back up" in _flatten(result.stderr)
def test_create_dry_run_reports_a_skipped_store(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--dry-run"],
)
_ok(result)
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert not os.path.exists("out.tar.gz")
def test_create_dry_run_json_stays_parseable_when_a_store_is_skipped(self, runner):
# #2110 review: the skip warning used to land on stdout ahead of the
# payload, so --json could not be parsed in exactly the case this PR
# fixes.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "--json", "backup", "create",
"out.tar.gz", "--strip-config", "--dry-run"],
)
_ok(result)
payload = json.loads(result.stdout)
assert payload["skipped"] == [
{"store": "graph", "backend": "local", "path": "empty_graph"}
]
assert "Skipping graph store" in result.stderr
assert not os.path.exists("out.tar.gz")
def test_sync_dry_run_json_stays_parseable_when_a_store_is_skipped(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "--json", "backup", "sync",
"sync_dest", "--dry-run"],
)
_ok(result)
payload = json.loads(result.stdout)
assert payload["skipped"] == [
{"store": "graph", "backend": "local", "path": "empty_graph"}
]
assert "Skipping graph store" in result.stderr
assert not os.path.exists("sync_dest")
def test_no_color_strips_colour_from_the_json_warning_on_stderr(
self, runner, monkeypatch
):
# Under --json the warning goes to err_console, not console. Give that
# console a forced terminal first, so a rebind that misses it would
# leave escape codes in the captured stderr.
monkeypatch.setenv("TERM", "xterm-256color")
original = cli_module.err_console
cli_module.err_console = cli_module.Console(stderr=True, force_terminal=True)
try:
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
[
"--config",
"cfg.yaml",
"--json",
"--no-color",
"backup",
"sync",
"sync_dest",
"--dry-run",
],
)
_ok(result)
assert "Skipping graph store" in result.stderr
assert "\x1b[" not in result.stderr
finally:
cli_module.err_console = original
def test_dry_run_json_reports_no_skips_when_every_store_is_present(self, runner):
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "--json", "backup", "create",
"out.tar.gz", "--strip-config", "--dry-run"],
)
_ok(result)
assert json.loads(result.stdout)["skipped"] == []
def test_collect_backup_sources_marks_empty_directories_as_skipped(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
cfg = {
"graph_db": {"backend": "local", "path": "empty_graph"},
"vector_store": {"backend": "local", "path": "vecs"},
}
sources, skipped = cli_module._collect_backup_sources(
cfg, None, "all", strip_config=True,
)
assert [arcname for arcname, _ in sources] == ["vector/index.json"]
assert skipped == [
{"store": "graph", "backend": "local", "path": "empty_graph"}
]
def test_collect_backup_sources_reports_empty_ontology_directory(self, runner):
# #2014 also flagged the ontology branch: an existing-but-empty (or
# absent) ontology path produced no sources and no skip entry.
with runner.isolated_filesystem():
os.makedirs("empty_onto")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
cfg = {
"ontology_path": "empty_onto",
"vector_store": {"backend": "local", "path": "vecs"},
}
sources, skipped = cli_module._collect_backup_sources(
cfg, None, "all", strip_config=True,
)
assert [arcname for arcname, _ in sources] == ["vector/index.json"]
assert skipped == [
{"store": "ontology", "backend": "file", "path": "empty_onto"}
]
def test_sync_names_a_skipped_store(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "sync", "sync_dest"],
)
_ok(result)
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert os.path.isfile(os.path.join("sync_dest", "vector", "index.json"))
def test_sync_fail_on_skip_exits_nonzero(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "sync", "sync_dest",
"--fail-on-skip"],
)
assert result.exit_code != 0
assert "Configured store path does not exist" in _flatten(result.output)
assert not os.path.exists("sync_dest")
def test_sync_dry_run_fail_on_skip_exits_nonzero(self, runner):
# #2109: the dry-run branch used to return before the skip handling.
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "sync", "sync_dest",
"--dry-run", "--fail-on-skip"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert "Configured store path does not exist" in flat
assert not os.path.exists("sync_dest")
def test_sync_dry_run_reports_a_skipped_store(self, runner):
with runner.isolated_filesystem():
os.makedirs("empty_graph")
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: empty_graph\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "sync", "sync_dest",
"--dry-run"],
)
_ok(result)
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "empty_graph" in flat
assert not os.path.exists("sync_dest")
def test_sync_without_skips_does_not_warn(self, runner):
with runner.isolated_filesystem():
os.makedirs("kg")
with open("kg/graph.db", "w") as f:
f.write("data")
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: sqlite\n path: kg\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "sync", "sync_dest"],
)
_ok(result)
assert "Skipping" not in _flatten(result.output)
@pytest.mark.parametrize("extra_args", [[], ["--fail-on-skip"]])
def test_create_names_every_missing_store_when_none_exist(self, runner, extra_args):
# When every configured store path is missing, the empty-archive error
# (#1820) still fires, but each missing path must be named first.
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: local\n"
" path: missing_graph.json\n"
"vector_store:\n"
" backend: local\n"
" path: missing_vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", *extra_args],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "Skipping graph store" in flat
assert "missing_graph.json" in flat
assert "Skipping vector store" in flat
assert "missing_vecs" in flat
assert "No store data to back up" in flat
assert not os.path.exists("out.tar.gz")
def test_create_without_store_config_reports_no_skip(self, runner):
# No store configured at all is the #1820 case, not a skip.
with runner.isolated_filesystem():
with open("cfg.yaml", "w") as f:
f.write("processing:\n batch_size: 8\n")
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config"],
)
assert result.exit_code != 0
flat = _flatten(result.output)
assert "No store data to back up" in flat
assert "Skipping" not in flat
def test_create_redacts_credentials_in_skipped_path(self, runner):
# A credential-bearing path must not reach the warning or the
# manifest, even with --strip-config.
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: sqlite\n"
" path: 'postgresql://user:[email protected]/kg'\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config"],
)
_ok(result)
assert "s3cretpw" not in result.output
assert "Skipping graph store" in _flatten(result.output)
with tarfile.open("out.tar.gz") as tar:
raw = tar.extractfile(
"semantica-backup/backup_manifest.json"
).read().decode("utf-8")
assert "s3cretpw" not in raw
manifest = json.loads(raw)
assert len(manifest["skipped"]) == 1
assert manifest["skipped"][0]["path"].startswith("postgresql://user:")
assert manifest["skipped"][0]["path"].endswith("@db.example/kg")
def test_create_fail_on_skip_redacts_credentials(self, runner):
with runner.isolated_filesystem():
os.makedirs("vecs")
with open("vecs/index.json", "w") as f:
f.write("{}")
with open("cfg.yaml", "w") as f:
f.write(
"graph_db:\n"
" backend: sqlite\n"
" path: 'postgresql://user:[email protected]/kg'\n"
"vector_store:\n"
" backend: local\n"
" path: vecs\n"
)
result = runner.invoke(
cli_module.main,
["--config", "cfg.yaml", "backup", "create", "out.tar.gz",
"--strip-config", "--fail-on-skip"],
)
assert result.exit_code != 0
assert "Configured store path does not exist" in _flatten(result.output)
assert "s3cretpw" not in result.output
assert not os.path.exists("out.tar.gz")
def test_collect_backup_sources_redacts_but_checks_the_real_path(self, runner):
# The redacted form is only for reporting; an existing path containing
# ":...@" must still be found and archived under its real name.
with runner.isolated_filesystem():
os.makedirs("a:b@c")
with open("a:b@c/index.json", "w") as f:
f.write("{}")
cfg = {
"graph_db": {"backend": "sqlite",
"path": "postgresql://user:[email protected]/kg"},
"vector_store": {"backend": "local", "path": "a:b@c"},
}
sources, skipped = cli_module._collect_backup_sources(
cfg, None, "all", strip_config=True,
)
assert [arcname for arcname, _ in sources] == ["vector/index.json"]
assert [str(p) for _, p in sources] == [os.path.join("a:b@c", "index.json")]
assert len(skipped) == 1
assert "s3cretpw" not in skipped[0]["path"]
def test_create_dry_run_json(self, runner):
# backup create has no per-command --json; use global --json
with runner.isolated_filesystem():
os.makedirs("kg")
with open("kg/graph.db", "w") as f:
f.write("data")
with open("cfg.yaml", "w") as f:
f.write("graph_db:\n backend: sqlite\n path: kg\n")
result = runner.invoke(cli_module.main, ["--config", "cfg.yaml", "--json",
"backup", "create", "backup.tar.gz", "--dry-run"])
_ok(result)
data = _json_output(result)
assert data["dry_run"] is True
def test_create_keyfile_world_readable_rejected(self, runner):
with runner.isolated_filesystem():
with open("keyfile.txt", "w") as f:
f.write("secret")
try:
os.chmod("keyfile.txt", stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH)
result = runner.invoke(
cli_module.main,
["backup", "create", "out.tar.gz",
"--keyfile", "keyfile.txt", "--encrypt"],
)
assert result.exit_code != 0
assert "readable" in result.output # covers both "world-readable" and group-readable
except OSError:
pytest.skip("Cannot set file permissions on this OS")
def test_create_keyfile_nonexistent_rejected(self, runner):
result = runner.invoke(
cli_module.main,
["backup", "create", "out.tar.gz",
"--keyfile", "no_such_keyfile.txt", "--encrypt"],
)
assert result.exit_code != 0
def test_sync_dry_run(self, runner):
result = runner.invoke(cli_module.main, ["backup", "sync", "/tmp/bk", "--dry-run"])
_ok(result)
def test_sync_creates_directory(self, runner):
with runner.isolated_filesystem():
result = runner.invoke(cli_module.main, ["backup", "sync", "sync_dest"])
_ok(result)
assert os.path.isdir("sync_dest")
def test_restore_dry_run(self, runner):
with runner.isolated_filesystem():
with open("backup.tar.gz", "w") as f:
f.write("")
result = runner.invoke(cli_module.main, ["backup", "restore", "backup.tar.gz", "--dry-run"])
_ok(result)
def test_restore_requires_source(self, runner):
result = runner.invoke(cli_module.main, ["backup", "restore"])
assert result.exit_code != 0
def test_restore_nonexistent_source_fails(self, runner):
result = runner.invoke(cli_module.main, ["backup", "restore", "no_such_file.tar.gz"])
assert result.exit_code != 0
def test_schedule_prints_cron(self, runner):
result = runner.invoke(cli_module.main, ["backup", "schedule",
"--dest", "/mnt/bk", "--freq", "daily"])
_ok(result)
assert "0 2 * * *" in result.output
assert "/mnt/bk" in result.output
def test_schedule_weekly(self, runner):
result = runner.invoke(cli_module.main, ["backup", "schedule",
"--dest", "/mnt/bk", "--freq", "weekly"])
_ok(result)
assert "0 2 * * 0" in result.output
def test_schedule_with_encrypt(self, runner):
result = runner.invoke(cli_module.main, ["backup", "schedule",
"--dest", "/mnt/bk", "--encrypt"])
_ok(result)
assert "--encrypt" in result.output
def test_schedule_json(self, runner):
result = runner.invoke(cli_module.main, ["--json", "backup", "schedule",
"--dest", "/mnt/bk"])
_ok(result)
data = json.loads(result.output.strip())
assert "cron" in data
# ─── server ───────────────────────────────────────────────────────────────────
class TestServer:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["server", "--help"])
_ok(result)
for sub in ["start", "stop", "status"]:
assert sub in result.output
def test_start_help(self, runner):
result = runner.invoke(cli_module.main, ["server", "start", "--help"])
_ok(result)
for flag in ["--port", "--workers", "--reload", "--host"]:
assert flag in result.output
def test_start_launches_process(self, runner):
mock_proc = MagicMock()
mock_proc.pid = 12345
with patch("subprocess.Popen", return_value=mock_proc) as mock_popen:
result = runner.invoke(cli_module.main, ["server", "start", "--port", "9000"])
_ok(result)
mock_popen.assert_called_once()
call_args = mock_popen.call_args[0][0]
assert "9000" in call_args
def test_start_with_reload(self, runner):
mock_proc = MagicMock()
mock_proc.pid = 12346
with patch("subprocess.Popen", return_value=mock_proc) as mock_popen:
result = runner.invoke(cli_module.main, ["server", "start", "--reload"])
_ok(result)
call_args = mock_popen.call_args[0][0]
assert "--reload" in call_args
def test_stop_when_not_running(self, runner, tmp_path, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["server", "stop"])
_ok(result)
assert "not running" in result.output.lower()
def test_stop_sends_sigterm(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: 99999)
monkeypatch.setattr(cli_module, "_pid_file", lambda n: MagicMock(
exists=lambda: True, unlink=lambda missing_ok=False: None
))
with patch("os.kill") as mock_kill:
result = runner.invoke(cli_module.main, ["server", "stop"])
_ok(result)
mock_kill.assert_called_once()
def test_status_when_stopped(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["server", "status"])
_ok(result)
assert "stopped" in result.output
def test_status_json(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["server", "status", "--json"])
_ok(result)
data = _json_output(result)
assert data["service"] == "server"
assert "status" in data
# ─── explorer ─────────────────────────────────────────────────────────────────
class TestExplorer:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["explorer", "--help"])
_ok(result)
for sub in ["start", "stop", "status", "open"]:
assert sub in result.output
def test_start_launches_process(self, runner, monkeypatch):
mock_proc = MagicMock()
mock_proc.pid = 22222
monkeypatch.setattr(cli_module, "_write_pid", lambda *_args: None)
with patch("subprocess.Popen", return_value=mock_proc):
result = runner.invoke(cli_module.main, ["explorer", "start", "--port", "5173"])
_ok(result)
def test_start_forwards_api_url_to_child_environment(self, runner, monkeypatch):
mock_proc = MagicMock()
mock_proc.pid = 22223
monkeypatch.setattr(cli_module, "_write_pid", lambda *_args: None)
with patch("subprocess.Popen", return_value=mock_proc) as mock_popen:
result = runner.invoke(
cli_module.main,
["explorer", "start", "--api-url", "http://localhost:9000"],
)
_ok(result)
assert mock_popen.call_args.kwargs["env"]["SEMANTICA_API_URL"] == (
"http://localhost:9000"
)
def test_stop_when_not_running(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["explorer", "stop"])
_ok(result)
assert "not running" in result.output.lower()
def test_status_json(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["explorer", "status", "--json"])
_ok(result)
data = _json_output(result)
assert data["service"] == "explorer"
def test_open_calls_webbrowser(self, runner):
with patch("webbrowser.open") as mock_wb:
result = runner.invoke(cli_module.main, ["explorer", "open", "--port", "5173"])
_ok(result)
mock_wb.assert_called_once_with("http://localhost:5173")
# ─── mcp ──────────────────────────────────────────────────────────────────────
class TestMCP:
def test_group_help(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "--help"])
_ok(result)
for sub in ["start", "stop", "status", "list-tools", "call"]:
assert sub in result.output
def test_start_launches_process(self, runner):
mock_proc = MagicMock()
mock_proc.pid = 33333
with patch("subprocess.Popen", return_value=mock_proc):
result = runner.invoke(cli_module.main, ["mcp", "start"])
_ok(result)
def test_start_http_is_rejected(self, runner):
mock_proc = MagicMock()
mock_proc.pid = 33334
with patch("subprocess.Popen", return_value=mock_proc) as mock_popen:
result = runner.invoke(cli_module.main, ["mcp", "start", "--transport", "http",
"--port", "4000"])
assert result.exit_code != 0
assert not mock_popen.called
def test_stop_when_not_running(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["mcp", "stop"])
_ok(result)
def test_status_json(self, runner, monkeypatch):
monkeypatch.setattr(cli_module, "_read_pid", lambda n: None)
result = runner.invoke(cli_module.main, ["mcp", "status", "--json"])
_ok(result)
data = _json_output(result)
assert data["service"] == "mcp"
def test_list_tools_shows_tools(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "list-tools"])
_ok(result)
# Table renders correctly — at minimum the column header is present
assert "Tool" in result.output or "tool" in result.output.lower()
def test_list_tools_reads_server_catalog(self, runner, monkeypatch):
"""list-tools must read TOOL_DEFINITIONS (what the server serves via
tools/list), not the module's ``__all__`` (issue #1355)."""
import semantica_mcp.mcp.tools as tools_mod
fake = [{"name": "fake_tool_from_catalog", "description": "", "inputSchema": {},
"_handler": lambda a: {}}]
monkeypatch.setattr(tools_mod, "TOOL_DEFINITIONS", fake)
result = runner.invoke(cli_module.main, ["mcp", "list-tools"])
_ok(result)
assert "fake_tool_from_catalog" in result.output
def test_list_tools_json(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "list-tools", "--json"])
_ok(result)
data = _json_output(result)
assert "tools" in data
assert isinstance(data["tools"], list)
def test_call_requires_tool_name(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "call"])
assert result.exit_code != 0
def test_call_invalid_json_args_fails_cleanly(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "call", "some_tool", "--args", "{bad json}"])
assert result.exit_code != 0
assert "Traceback" not in result.output
assert "Invalid JSON" in result.output
def test_call_failure_global_json_mode_keeps_stdout_clean(self, runner):
"""Under global --json, stdout must stay machine-readable: failures are
emitted as structured JSON on stderr, never as a Rich panel on stdout."""
result = runner.invoke(
cli_module.main,
["--json", "mcp", "call", "some_tool", "--args", "{bad json}"],
)
assert result.exit_code != 0
assert result.stdout == ""
err = json.loads(result.stderr)
assert err["error"].startswith("Invalid JSON in --args")
assert err["type"] == "ClickException"
def test_call_failure_local_json_mode_keeps_stdout_clean(self, runner):
"""The subcommand's own --json flag promises the same stream contract."""
result = runner.invoke(
cli_module.main,
["mcp", "call", "some_tool", "--args", "{bad json}", "--json"],
)
assert result.exit_code != 0
assert result.stdout == ""
err = json.loads(result.stderr)
assert err["error"].startswith("Invalid JSON in --args")
def test_call_dispatches_through_packaged_server(self, runner):
"""Regression for issue #1355: ``mcp call`` dispatches in-process through
``semantica_mcp.mcp.server`` (the server ``mcp start`` spawns) instead
of importing the nonexistent ``MCPSession``."""
result = runner.invoke(
cli_module.main, ["--json", "mcp", "call", "extract_entities"]
)
_ok(result)
# Empty args short-circuit before heavy imports; reaching the
# handler's own validation proves the dispatch path works.
assert "text is required" in result.output
def test_call_unknown_tool_fails_cleanly(self, runner):
result = runner.invoke(cli_module.main, ["mcp", "call", "no_such_tool"])
assert result.exit_code != 0
assert "Traceback" not in result.output
assert "Unknown tool" in result.output
def test_call_non_object_args_rejected(self, runner):
result = runner.invoke(
cli_module.main, ["mcp", "call", "extract_entities", "--args", "[1, 2]"]
)
assert result.exit_code != 0
assert "Traceback" not in result.output
assert "--args must be a JSON object" in result.output
def test_list_tools_json_matches_server_catalog(self, runner):
"""The CLI catalog and the MCP server catalog must be the same list."""
from semantica_mcp.mcp.tools import TOOL_DEFINITIONS
result = runner.invoke(cli_module.main, ["mcp", "list-tools", "--json"])
_ok(result)
data = _json_output(result)
assert data["tools"] == [t["name"] for t in TOOL_DEFINITIONS]
# ─── services group (backward-compat wrapper) ─────────────────────────────────
class TestServicesGroup:
def test_services_group_help_shows_subgroups(self, runner):
result = runner.invoke(cli_module.main, ["services", "--help"])
_ok(result)
for sub in ["server", "explorer", "mcp"]:
assert sub in result.output
def test_services_server_help(self, runner):
result = runner.invoke(cli_module.main, ["services", "server", "--help"])
_ok(result)
for sub in ["start", "stop", "status"]:
assert sub in result.output
def test_services_explorer_help(self, runner):
result = runner.invoke(cli_module.main, ["services", "explorer", "--help"])
_ok(result)
def test_services_mcp_help(self, runner):
result = runner.invoke(cli_module.main, ["services", "mcp", "--help"])
_ok(result)
# ─── completion ───────────────────────────────────────────────────────────────
class TestCompletion:
@pytest.mark.parametrize("shell", ["bash", "zsh", "fish", "powershell"])
def test_completion_exits_0(self, runner, shell):
result = runner.invoke(cli_module.main, ["completion", shell])
assert result.exit_code == 0
@pytest.mark.parametrize("shell", ["bash", "zsh", "fish", "powershell"])
def test_completion_output_not_empty(self, runner, shell):
result = runner.invoke(cli_module.main, ["completion", shell])
assert result.exit_code == 0
assert len(result.output.strip()) > 0
@pytest.mark.parametrize("shell,install_path", [
("bash", "~/.bashrc"),
("zsh", "~/.zshrc"),
("fish", "~/.config/fish"),
("powershell", "$PROFILE"),
])
def test_completion_mentions_install_path(self, runner, shell, install_path):
result = runner.invoke(cli_module.main, ["completion", shell])
assert result.exit_code == 0
assert install_path in result.output
def test_invalid_shell_fails(self, runner):
result = runner.invoke(cli_module.main, ["completion", "csh"])
assert result.exit_code != 0
# ─── cross-cutting: --json propagated from global flag ────────────────────────
class TestGlobalJsonPropagation:
"""--json set at root should trigger JSON output in all subcommands."""
def test_global_json_on_backup_schedule(self, runner):
result = runner.invoke(cli_module.main, ["--json", "backup", "schedule", "--dest", "/d"])
_ok(result)
data = json.loads(result.output.strip())
assert "cron" in data
def test_global_json_on_store_list(self, runner):
result = runner.invoke(cli_module.main, ["--json", "store", "list"])
_ok(result)
assert json.loads(result.output.strip()) is not None
def test_global_json_on_mcp_list_tools(self, runner):
result = runner.invoke(cli_module.main, ["--json", "mcp", "list-tools"])
_ok(result)
data = json.loads(result.output.strip())
assert "tools" in data
# ─── exit codes ───────────────────────────────────────────────────────────────
class TestExitCodes:
"""Exit codes must match the spec: 0 success, 1 general, 2 validation."""
def test_success_is_0(self, runner):
result = runner.invoke(cli_module.main, ["info"])
assert result.exit_code == 0
def test_missing_required_arg_is_2(self, runner):
result = runner.invoke(cli_module.main, ["kg", "build"])
assert result.exit_code == 2
def test_missing_required_arg_for_find_path_is_nonzero(self, runner):
result = runner.invoke(cli_module.main, ["kg", "find-path"])
assert result.exit_code != 0
def test_import_error_is_nonzero(self, runner):
with patch("builtins.__import__", side_effect=lambda n, *a, **k: (
(_ for _ in ()).throw(ImportError(n))
if "deduplication" in n else __import__(n, *a, **k)
)):
result = runner.invoke(cli_module.main, ["deduplicate"])
assert result.exit_code != 0
def test_no_traceback_on_any_error(self, runner):
for argv in [
["kg", "build"],
["deduplicate", "--strategy", "bad"],
["export", "--format", "bad"],
["mcp", "call", "tool", "--args", "{invalid}"],
]:
result = runner.invoke(cli_module.main, argv)
assert "Traceback" not in result.output, (
f"Traceback found for {argv}: {result.output}"
)
class TestDoctorEmbeddings:
"""#994: doctor must surface non-functional embedding backends instead of
reporting all green. Default = import-level check; --deep-embeddings (or
SEMANTICA_DOCTOR_DEEP_EMBEDDINGS=1) instantiates via TextEmbedder."""
def _doctor_checks(self, runner, *extra):
result = runner.invoke(cli_module.main, ["doctor", "--json", *extra])
_ok(result)
import json as _json
return {c["check"]: c for c in _json.loads(result.output)}
def _with_fake_st(self, monkeypatch, **embedder_attrs):
fake_st = _fake_module(
__version__="9.9.9",
SentenceTransformer=object,
)
monkeypatch.setitem(__import__("sys").modules, "sentence_transformers", fake_st)
def test_doctor_reports_embedding_checks(self, runner):
checks = self._doctor_checks(runner)
assert "Embeddings (sentence-transformers)" in checks
assert "Embeddings (fastembed)" in checks
def test_import_failure_is_fail_status_with_hint(self, runner, monkeypatch):
# Force the 'import sentence_transformers' inside _embedding_backend to
# raise ImportError regardless of whether the package is installed on
# this machine. Setting a module entry to None is the standard Python
# mechanism: any subsequent 'import <name>' raises
# "import of <name> halted; None in sys.modules".
monkeypatch.setitem(
__import__("sys").modules, "sentence_transformers", None
)
checks = self._doctor_checks(runner)
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "fail"
assert st["hint"] == "pip install 'semantica[embeddings-local]'"
def test_deep_probe_detects_fallback_active(self, runner, monkeypatch):
self._with_fake_st(monkeypatch)
fake_embedder = types.SimpleNamespace(model=None, fastembed_model=None)
fake_emb_mod = _fake_module(TextEmbedder=lambda **k: fake_embedder)
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb_mod)
checks = self._doctor_checks(runner, "--deep-embeddings")
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "fail"
assert "hash fallback" in st["note"]
def test_deep_probe_ok_when_model_loads(self, runner, monkeypatch):
self._with_fake_st(monkeypatch)
import numpy as np
fake_embedder = types.SimpleNamespace(
model=object(),
fastembed_model=None,
embed_text=lambda text: np.zeros(384, dtype=np.float32),
)
fake_emb_mod = _fake_module(TextEmbedder=lambda **k: fake_embedder)
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb_mod)
checks = self._doctor_checks(runner, "--deep-embeddings")
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "ok"
assert "384-dim" in st["note"]
def test_env_var_enables_deep_mode(self, runner, monkeypatch):
monkeypatch.setenv("SEMANTICA_DOCTOR_DEEP_EMBEDDINGS", "1")
self._with_fake_st(monkeypatch)
fake_embedder = types.SimpleNamespace(model=None, fastembed_model=None)
fake_emb_mod = _fake_module(TextEmbedder=lambda **k: fake_embedder)
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb_mod)
checks = self._doctor_checks(runner)
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "fail"
assert "hash fallback" in st["note"]
class TestDoctorEmbeddingHintsAndEnv:
"""Review follow-ups: deep failures must not carry the pip-install hint,
and the env toggle tolerates case/whitespace variants."""
def _doctor_checks(self, runner, *extra):
result = runner.invoke(cli_module.main, ["doctor", "--json", *extra])
_ok(result)
import json as _json
return {c["check"]: c for c in _json.loads(result.output)}
def _with_fake_st(self, monkeypatch):
fake_st = _fake_module(
__version__="9.9.9",
SentenceTransformer=object,
)
monkeypatch.setitem(__import__("sys").modules, "sentence_transformers", fake_st)
def test_deep_failure_hint_is_not_pip_install(self, runner, monkeypatch):
self._with_fake_st(monkeypatch)
fake_embedder = types.SimpleNamespace(model=None, fastembed_model=None)
fake_emb_mod = _fake_module(TextEmbedder=lambda **k: fake_embedder)
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb_mod)
checks = self._doctor_checks(runner, "--deep-embeddings")
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "fail"
assert "pip install" not in (st["hint"] or ""), (
"a deep probe failure means the package imported fine — pointing "
"users at pip sends them to reinstall for a runtime/model problem"
)
assert "runtime/model-load" in st["hint"]
def test_env_var_tolerates_case_and_whitespace(self, runner, monkeypatch):
monkeypatch.setenv("SEMANTICA_DOCTOR_DEEP_EMBEDDINGS", " TRUE ")
self._with_fake_st(monkeypatch)
fake_embedder = types.SimpleNamespace(model=None, fastembed_model=None)
fake_emb_mod = _fake_module(TextEmbedder=lambda **k: fake_embedder)
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb_mod)
checks = self._doctor_checks(runner)
st = checks["Embeddings (sentence-transformers)"]
assert st["status"] == "fail"
assert "hash fallback" in st["note"], "padded/caps env value must enable deep mode"
class TestDoctorBackendEnvResolution:
"""#1818: doctor must report the MCP server's stores, which are configured
only through ``SEMANTICA_VECTOR_*`` / ``SEMANTICA_KG_PATH``.
Those variables never change what CLI commands build, so they get their own
rows resolved by the server's session helpers instead of being folded into
the CLI's vector and graph checks.
"""
_MCP_ENV = (
"SEMANTICA_VECTOR_BACKEND",
"SEMANTICA_VECTOR_DB_PATH",
"SEMANTICA_VECTOR_PATH",
"SEMANTICA_KG_PATH",
)
@pytest.fixture(autouse=True)
def _clean_env(self, monkeypatch):
for var in self._MCP_ENV:
monkeypatch.delenv(var, raising=False)
@pytest.fixture
def cfg(self, tmp_path):
# graph_db.path keeps the CLI graph row off the real ~/.semantica.
def _write(extra=""):
path = tmp_path / "cfg.yaml"
path.write_text(
"graph_db:\n backend: memory\n"
f" path: {tmp_path / 'cli_graph.json'}\n" + extra
)
return str(path)
return _write
def _checks(self, runner, config):
args = ["--config", config, "doctor", "--json"]
result = runner.invoke(cli_module.main, args)
_ok(result)
return {c["check"]: c for c in json.loads(result.output)}
@staticmethod
def _without_faiss(monkeypatch):
monkeypatch.setitem(sys.modules, "faiss", None)
@staticmethod
def _with_faiss(monkeypatch):
monkeypatch.setitem(sys.modules, "faiss", types.ModuleType("faiss"))
@staticmethod
def _sqlite_vec_loads(monkeypatch):
monkeypatch.setattr(cli_module, "_probe_sqlite_vec", lambda: None)
@staticmethod
def _save_graph_with_one_decision(path):
from semantica.context import ContextGraph
graph = ContextGraph()
graph.record_decision(
category="vendor_selection",
scenario="Pick a vector backend",
reasoning="sqlite-vec needs no server",
outcome="selected_sqlite",
confidence=0.9,
)
graph.save_to_file(path)
def test_no_mcp_rows_without_mcp_env(self, runner, cfg):
checks = self._checks(runner, cfg())
assert "MCP vector store" not in checks
assert "MCP graph" not in checks
def test_reports_the_mcp_sqlite_store(self, runner, cfg, tmp_path, monkeypatch):
self._sqlite_vec_loads(monkeypatch)
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", " SQLite ")
monkeypatch.setenv("SEMANTICA_VECTOR_DB_PATH", str(tmp_path / "v.db"))
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "ok"
assert row["note"] == "sqlite-vec loaded"
def test_mcp_env_is_read_even_when_init_wrote_a_cli_backend(
self, runner, cfg, tmp_path, monkeypatch
):
# `semantica init` writes vector_store.backend: faiss by default; that
# must neither hide the MCP store nor be replaced by it.
self._with_faiss(monkeypatch)
self._sqlite_vec_loads(monkeypatch)
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "sqlite")
monkeypatch.setenv("SEMANTICA_VECTOR_DB_PATH", str(tmp_path / "v.db"))
checks = self._checks(runner, cfg("vector_store:\n backend: faiss\n"))
assert checks["MCP vector store"]["note"] == "sqlite-vec loaded"
assert checks["Vector store"]["note"] == "faiss importable"
def test_mcp_vector_defaults_to_inmemory(self, runner, cfg, tmp_path, monkeypatch):
monkeypatch.setenv("SEMANTICA_KG_PATH", str(tmp_path / "kg.json"))
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "ok"
assert row["note"] == "inmemory"
def test_flags_sqlite_without_a_db_path(self, runner, cfg, monkeypatch):
# The server refuses to start this way, so doctor must not pass it.
self._sqlite_vec_loads(monkeypatch)
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "sqlite")
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "fail"
assert "SEMANTICA_VECTOR_DB_PATH" in row["note"]
def test_flags_an_unsupported_mcp_backend(self, runner, cfg, monkeypatch):
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "faiss")
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "fail"
assert "supported backends: inmemory, sqlite" in row["note"]
def test_flags_a_missing_sqlite_vec(self, runner, cfg, tmp_path, monkeypatch):
import semantica.vector_store.sqlite_vec_store as sqlite_store
monkeypatch.setattr(sqlite_store, "SQLITE_VEC_AVAILABLE", False)
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "sqlite")
monkeypatch.setenv("SEMANTICA_VECTOR_DB_PATH", str(tmp_path / "v.db"))
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "fail"
assert "not installed" in row["note"]
assert "vectorstore-sqlite" in row["hint"]
def test_flags_a_sqlite_vec_that_fails_to_load(
self, runner, cfg, tmp_path, monkeypatch
):
# Discoverable but unloadable must fail: the probe runs the store's
# real load path rather than trusting find_spec.
import semantica.vector_store.sqlite_vec_store as sqlite_store
from semantica.utils.exceptions import ProcessingError
def _boom(**_):
raise ProcessingError("Failed to load sqlite-vec extension: boom")
monkeypatch.setattr(sqlite_store, "SQLITE_VEC_AVAILABLE", True)
monkeypatch.setattr(sqlite_store, "SQLiteVecStore", _boom)
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "sqlite")
monkeypatch.setenv("SEMANTICA_VECTOR_DB_PATH", str(tmp_path / "v.db"))
row = self._checks(runner, cfg())["MCP vector store"]
assert row["status"] == "fail"
assert "Failed to load sqlite-vec extension" in row["note"]
def test_unconfigured_faiss_is_a_warning_for_an_mcp_deployment(
self, runner, cfg, tmp_path, monkeypatch
):
self._without_faiss(monkeypatch)
monkeypatch.setenv("SEMANTICA_KG_PATH", str(tmp_path / "kg.json"))
row = self._checks(runner, cfg())["Vector store"]
assert row["status"] == "warn"
assert "CLI default" in row["note"]
def test_unconfigured_faiss_still_fails_without_mcp_env(
self, runner, cfg, monkeypatch
):
self._without_faiss(monkeypatch)
assert self._checks(runner, cfg())["Vector store"]["status"] == "fail"
def test_configured_faiss_still_fails_for_an_mcp_deployment(
self, runner, cfg, tmp_path, monkeypatch
):
self._without_faiss(monkeypatch)
monkeypatch.setenv("SEMANTICA_KG_PATH", str(tmp_path / "kg.json"))
config = cfg("vector_store:\n backend: faiss\n")
assert self._checks(runner, config)["Vector store"]["status"] == "fail"
def test_mcp_graph_counts_decisions_from_kg_path(
self, runner, cfg, tmp_path, monkeypatch
):
kg = tmp_path / "mcp_graph.json"
self._save_graph_with_one_decision(kg)
monkeypatch.setenv("SEMANTICA_KG_PATH", str(kg))
checks = self._checks(runner, cfg())
assert checks["MCP graph"]["status"] == "ok"
assert checks["MCP graph"]["note"] == "1 decision(s)"
# The CLI graph is a different file; it must not report the MCP one.
assert checks["Graph store"]["note"] == "memory, 0 decision(s)"
def test_mcp_graph_accepts_an_empty_or_missing_file(
self, runner, cfg, tmp_path, monkeypatch
):
# The server starts empty from both, so neither is a failure.
empty = tmp_path / "empty.json"
empty.write_text("")
for path in (empty, tmp_path / "missing.json"):
monkeypatch.setenv("SEMANTICA_KG_PATH", str(path))
row = self._checks(runner, cfg())["MCP graph"]
assert row["status"] == "ok"
assert row["note"] == "new graph, created on first save"
def test_mcp_graph_flags_an_unreadable_file(
self, runner, cfg, tmp_path, monkeypatch
):
kg = tmp_path / "corrupt.json"
kg.write_text("{not json")
monkeypatch.setenv("SEMANTICA_KG_PATH", str(kg))
row = self._checks(runner, cfg())["MCP graph"]
assert row["status"] == "fail"
assert "persistence would be disabled" in row["note"]
def test_mcp_graph_without_kg_path_is_in_memory(self, runner, cfg, monkeypatch):
monkeypatch.setenv("SEMANTICA_VECTOR_BACKEND", "inmemory")
row = self._checks(runner, cfg())["MCP graph"]
assert row["status"] == "ok"
assert "not persisted" in row["note"]
class TestDoctorTableLayout:
"""#1428 + Qodo review: doctor table must keep Check labels and Hint text
readable at a normal 80-column terminal.
These tests render the *human-readable* (non-JSON) doctor table into a
captured 80-column Rich console so they cover the actual column-width
arithmetic, not just the JSON data.
Two regressions are protected:
A. #1428 — Hint (and Note) columns must not collapse into unreadable
single-character fragments or be silently truncated with a layout '…'.
overflow="fold" on both columns ensures content wraps across lines while
remaining fully present.
B. Qodo — Long Check labels such as "Embeddings (sentence-transformers)"
must not be truncated/ellipsized. Assigning ratio=1 to the Check column
(as the original PR did) caused Rich to squeeze it below its min_width
at narrow terminals, so the fix removes ratio from the fixed-size columns.
"""
def _render_doctor_at_80(self, runner, monkeypatch):
"""Return the plain-text (ANSI-stripped) doctor table rendered at 80 cols."""
import io
import re
from rich.console import Console
# Unset LLM-provider env vars so the warn rows (with hints) are always present.
for var in ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GROQ_API_KEY"):
monkeypatch.delenv(var, raising=False)
buf = io.StringIO()
narrow_console = Console(
file=buf, width=80, highlight=False, force_terminal=True, no_color=True
)
monkeypatch.setattr(cli_module, "console", narrow_console)
result = runner.invoke(cli_module.main, ["doctor"])
assert result.exit_code == 0, f"doctor exited non-zero: {result.output!r}"
return re.sub(r"\x1b\[[0-9;]*m", "", buf.getvalue())
def _hint_column_parts(self, output: str) -> "list[str]":
"""Extract non-blank Hint-column segments from each rendered line.
Locates the Hint column start from the header row and slices that
suffix from every subsequent line, so the test is insensitive to the
exact widths of the other columns.
"""
lines = output.splitlines()
# Line 0 is blank (console.print() blank line before table).
hdr = next((l for l in lines if "Hint" in l and "Check" in l), None)
assert hdr is not None, "Could not find table header in doctor output"
hint_start = hdr.index("Hint")
parts = []
for line in lines:
if len(line) > hint_start:
seg = line[hint_start:].rstrip()
if seg and seg != "Hint" and not set(seg).issubset({"─", " "}):
parts.append(seg)
return parts
# ── B: Qodo regression ────────────────────────────────────────────────────
def test_long_check_label_not_truncated_at_80_cols(self, runner, monkeypatch):
"""'Embeddings (sentence-transformers)' must appear verbatim at 80 cols.
Before the fix, ratio=1 on the Check column let Rich squeeze it below
its min_width, turning the label into 'Embedd…' or similar.
"""
output = self._render_doctor_at_80(runner, monkeypatch)
assert "Embeddings (sentence-transformers)" in output, (
"Check label 'Embeddings (sentence-transformers)' was truncated in "
"the 80-column doctor table — the ratio= constraint on the Check "
"column must be removed so min_width=34 is always honoured."
)
def test_all_check_labels_not_truncated_at_80_cols(self, runner, monkeypatch):
"""Every standard Check label must appear verbatim at 80 cols."""
output = self._render_doctor_at_80(runner, monkeypatch)
for label in (
"Python",
"semantica",
"rich",
"Graph store",
"Vector store",
"Embeddings (sentence-transformers)",
"Embeddings (fastembed)",
"OpenAI",
"Anthropic",
"Groq",
"Config file",
"Log directory",
):
assert label in output, (
f"Check label {label!r} was truncated or missing in the "
"80-column doctor table."
)
# ── A: #1428 regression ───────────────────────────────────────────────────
def test_hint_content_fully_present_at_80_cols(self, runner, monkeypatch):
"""The LLM-provider hints must be fully present (folded, not ellipsized).
With overflow='fold' the full hint text wraps across lines; no
characters are discarded. Joining the Hint-column segments (stripping
whitespace) must reconstruct each complete hint string.
"""
import re
output = self._render_doctor_at_80(runner, monkeypatch)
parts = self._hint_column_parts(output)
hint_joined = re.sub(r"\s+", "", "".join(parts))
# Each LLM-provider hint must be fully recoverable from the folded lines.
for expected in (
"exportOPENAI_API_KEY=\u2026", # export OPENAI_API_KEY=…
"exportANTHROPIC_API_KEY=\u2026", # export ANTHROPIC_API_KEY=…
"exportGROQ_API_KEY=\u2026", # export GROQ_API_KEY=…
):
assert expected in hint_joined, (
f"Hint content {expected!r} is missing from the 80-column "
"doctor table — overflow='fold' must be set on the Hint column "
"so no content is silently discarded."
)
def test_hint_column_has_no_single_char_fragments_at_80_cols(
self, runner, monkeypatch
):
"""No Hint-column line must be a single alphabetic character.
The original #1428 bug produced outputs like:
export
O
P
E
N
A
I
...
because Rich allocated the Hint column only 1–2 characters of content
width. overflow='fold' on a properly-wide column eliminates this.
"""
output = self._render_doctor_at_80(runner, monkeypatch)
parts = self._hint_column_parts(output)
single_char_alpha = [p for p in parts if len(p.strip()) == 1 and p.strip().isalpha()]
assert not single_char_alpha, (
f"Hint column contains single-character lines {single_char_alpha!r} "
"at 80 columns — the Hint column is too narrow; check min_width and "
"ratio settings."
)
class TestEmbedGenerateOutput:
"""#994: `embed generate --output` must write files `embed index` can read."""
def _patch_generate(self, monkeypatch, retval):
import numpy as np
fake_emb = _fake_module(generate_embeddings=lambda *a, **k: np.asarray(retval))
monkeypatch.setitem(__import__("sys").modules, "semantica.embeddings", fake_emb)
def test_writes_valid_parquet(self, runner, monkeypatch, tmp_path):
pytest.importorskip("pyarrow", reason="parquet writer regression needs pyarrow")
import numpy as np
import pandas as pd
self._patch_generate(monkeypatch, [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])
out = tmp_path / "embeddings.parquet"
result = runner.invoke(cli_module.main, ["embed", "generate", "in.json", "--output", str(out)])
_ok(result)
df = pd.read_parquet(out)
assert "embedding" in df.columns
assert len(df) == 2
# Use allclose: the writer may store float32 or float64 depending on
# the model backend; exact == fails for float32-precision values.
assert np.allclose(df["embedding"].iloc[0], [0.1, 0.2, 0.3], atol=1e-6)
def test_writes_1d_result_as_single_row_parquet(self, runner, monkeypatch, tmp_path):
pytest.importorskip("pyarrow", reason="parquet writer regression needs pyarrow")
import numpy as np
import pandas as pd
self._patch_generate(monkeypatch, [0.1, 0.2, 0.3])
out = tmp_path / "embeddings.parquet"
result = runner.invoke(cli_module.main, ["embed", "generate", "in.json", "--output", str(out)])
_ok(result)
df = pd.read_parquet(out)
assert len(df) == 1
assert np.allclose(df["embedding"].iloc[0], [0.1, 0.2, 0.3], atol=1e-6)
def test_writes_json_records_not_repr_strings(self, runner, monkeypatch, tmp_path):
import json as _json
import numpy as np
import pandas as pd
self._patch_generate(monkeypatch, [[0.1, 0.2], [0.3, 0.4]])
out = tmp_path / "embeddings.json"
result = runner.invoke(cli_module.main, ["embed", "generate", "in.json", "--output", str(out)])
_ok(result)
records = _json.loads(out.read_text(encoding="utf-8"))
assert records == [{"embedding": [0.1, 0.2]}, {"embedding": [0.3, 0.4]}]
# Verify embed index can read the file back (round-trip contract).
df = pd.read_json(out, orient="records")
vector_col = next(
(c for c in df.columns if isinstance(df[c].iloc[0], (list, np.ndarray))),
None,
)
assert vector_col == "embedding", (
f"embed index would not find a vector column; got columns {list(df.columns)}"
)
def test_rejects_unsupported_output_format(self, runner, monkeypatch, tmp_path):
self._patch_generate(monkeypatch, [[0.1, 0.2]])
out = tmp_path / "embeddings.txt"
result = runner.invoke(cli_module.main, ["embed", "generate", "in.json", "--output", str(out)])
assert result.exit_code != 0
assert "Unsupported output format" in result.output
assert not out.exists()
class TestWriteResultOutput:
"""Unit-level regression tests for _write_result_output().
Covers every branch: JSON, JSONL, CSV, unsupported extension, no-extension,
dict+JSONL, empty list, NumPy scalar/array values, and round-trip readback.
"""
# ── helpers ───────────────────────────────────────────────────────────────
def _write(self, tmp_path, filename, result):
"""Call _write_result_output and return the output Path."""
from semantica.cli import _write_result_output
out = tmp_path / filename
_write_result_output(out, result)
return out
# ── JSON ─────────────────────────────────────────────────────────────────
def test_json_dict_produces_valid_json(self, tmp_path):
import json
out = self._write(tmp_path, "r.json", {"pairs": 3, "score": 0.9})
data = json.loads(out.read_text(encoding="utf-8"))
assert data == {"pairs": 3, "score": 0.9}
def test_json_list_produces_valid_json(self, tmp_path):
import json
out = self._write(tmp_path, "r.json", [{"a": 1}, {"a": 2}])
data = json.loads(out.read_text(encoding="utf-8"))
assert data == [{"a": 1}, {"a": 2}]
def test_json_numpy_scalar_serialises_as_number_not_repr(self, tmp_path):
"""np.float32 values must round-trip as JSON numbers, not repr strings."""
import json
import numpy as np
out = self._write(tmp_path, "r.json", {"score": np.float32(0.95)})
data = json.loads(out.read_text(encoding="utf-8"))
assert isinstance(data["score"], float), (
f"expected float, got {type(data['score'])}: {data['score']!r}"
)
assert abs(data["score"] - 0.95) < 1e-4
def test_json_numpy_array_serialises_as_list_not_repr(self, tmp_path):
"""np.ndarray values must round-trip as JSON arrays, not '[0.1 0.2]' repr."""
import json
import numpy as np
out = self._write(tmp_path, "r.json", {"vec": np.array([0.1, 0.2, 0.3])})
data = json.loads(out.read_text(encoding="utf-8"))
assert isinstance(data["vec"], list), (
f"expected list, got {type(data['vec'])}: {data['vec']!r}"
)
assert len(data["vec"]) == 3
# ── JSONL ────────────────────────────────────────────────────────────────
def test_jsonl_list_writes_one_object_per_line(self, tmp_path):
"""Each item in a list result must occupy exactly one JSONL line."""
import json
records = [{"id": "a", "score": 0.9}, {"id": "b", "score": 0.7}]
out = self._write(tmp_path, "r.jsonl", records)
lines = [l for l in out.read_text(encoding="utf-8").splitlines() if l.strip()]
assert len(lines) == 2
assert json.loads(lines[0]) == {"id": "a", "score": 0.9}
assert json.loads(lines[1]) == {"id": "b", "score": 0.7}
def test_jsonl_dict_writes_exactly_one_line(self, tmp_path):
"""A dict result (e.g. ontology_align) must write one JSON object on one line,
not a pretty-printed multi-line block that pd.read_json(lines=True) cannot parse."""
import json
import pandas as pd
result = {"total_entities": 10, "duplicate_pairs": 3}
out = self._write(tmp_path, "r.jsonl", result)
raw = out.read_text(encoding="utf-8")
lines = [l for l in raw.splitlines() if l.strip()]
# Exactly one line
assert len(lines) == 1, (
f"Expected 1 JSONL line for dict result, got {len(lines)}:\n{raw!r}"
)
# That line parses as valid JSON
parsed = json.loads(lines[0])
assert parsed == result
# pd.read_json(lines=True) can read it back
df = pd.read_json(out, lines=True)
assert list(df.columns) == ["total_entities", "duplicate_pairs"]
def test_jsonl_numpy_values_are_not_repr_strings(self, tmp_path):
"""NumPy values inside JSONL lines must be proper JSON, not repr()."""
import json
import numpy as np
records = [{"score": np.float32(0.8), "tag": "x"}]
out = self._write(tmp_path, "r.jsonl", records)
line = out.read_text(encoding="utf-8").strip()
parsed = json.loads(line)
assert isinstance(parsed["score"], float)
# ── CSV ──────────────────────────────────────────────────────────────────
def test_csv_list_of_dicts_produces_readable_csv(self, tmp_path):
import pandas as pd
rows = [{"entity_1": "Alice", "entity_2": "Bob", "similarity": 0.87},
{"entity_1": "Carol", "entity_2": "Dave", "similarity": 0.72}]
out = self._write(tmp_path, "r.csv", rows)
df = pd.read_csv(out)
assert list(df.columns) == ["entity_1", "entity_2", "similarity"]
assert len(df) == 2
assert abs(df["similarity"].iloc[0] - 0.87) < 1e-6
def test_csv_numpy_scalar_becomes_number_not_repr(self, tmp_path):
"""np.float32 in a result row must not become a repr string in the CSV."""
import numpy as np
import pandas as pd
rows = [{"label": "x", "score": np.float32(0.95)}]
out = self._write(tmp_path, "r.csv", rows)
df = pd.read_csv(out)
# The cell must be a numeric type, not a string like 'np.float32(0.95)'
assert df["score"].dtype.kind in ("f", "i"), (
f"Expected numeric dtype, got {df['score'].dtype}: {df['score'].iloc[0]!r}"
)
def test_csv_empty_list_raises_clickexception(self, tmp_path):
"""An empty result list must raise rather than create a headerless newline."""
import click
from semantica.cli import _write_result_output
out = tmp_path / "empty.csv"
with pytest.raises(click.ClickException, match="No results to write"):
_write_result_output(out, [])
assert not out.exists()
def test_csv_single_dict_written_as_one_row(self, tmp_path):
import pandas as pd
out = self._write(tmp_path, "r.csv", {"total": 5, "merged": 2})
df = pd.read_csv(out)
assert len(df) == 1
assert df["total"].iloc[0] == 5
# ── unsupported / no-extension ────────────────────────────────────────────
def test_unsupported_extension_raises_clickexception(self, tmp_path):
import click
from semantica.cli import _write_result_output
out = tmp_path / "report.txt"
with pytest.raises(click.ClickException, match="Unsupported output format"):
_write_result_output(out, {"k": "v"})
assert not out.exists()
def test_no_extension_raises_clickexception(self, tmp_path):
"""No-extension paths must be rejected — not silently renamed to .json —
so the path reported to the user always matches the file created."""
import click
from semantica.cli import _write_result_output
out = tmp_path / "report"
with pytest.raises(click.ClickException, match="Unsupported output format"):
_write_result_output(out, {"k": "v"})
assert not out.exists()
assert not (tmp_path / "report.json").exists()
def test_txt_extension_raises_clickexception(self, tmp_path):
""".txt is not a documented format and must be rejected, consistent with
_write_embeddings_output which also rejects it."""
import click
from semantica.cli import _write_result_output
out = tmp_path / "r.txt"
with pytest.raises(click.ClickException, match="Unsupported output format"):
_write_result_output(out, {"k": "v"})
assert not out.exists()
def test_uppercase_extension_accepted(self, tmp_path):
"""Extension matching must be case-insensitive (.CSV == .csv)."""
import pandas as pd
out = self._write(tmp_path, "r.CSV", [{"a": 1}])
df = pd.read_csv(out)
assert len(df) == 1
class TestDeduplicateOutput:
"""CLI-level regression tests for deduplicate --output integration.
Uses the same monkeypatching pattern as TestDeduplicate.test_detect_runtime_path:
patch _get_store and get_nodes at the graph_store.methods level, then patch
the deduplication module so no real model or DB is needed.
"""
_ENTITIES = [
{"id": "e1", "name": "Alice", "type": "Person"},
{"id": "e2", "name": "Alice", "type": "Person"},
]
_DETECT_RESULT = [
{"entity_1": "e1", "entity_2": "e2", "similarity": 0.9}
]
def _patch_dedup(self, monkeypatch):
"""Wire graph store + deduplication mocks for the detect action."""
entities = self._ENTITIES
detect_result = self._DETECT_RESULT
class FakeStore:
def get_nodes(self, labels=None, properties=None, limit=100, **opts):
return entities
monkeypatch.setattr(
"semantica.graph_store.methods._get_store", lambda: FakeStore()
)
monkeypatch.setattr(
"semantica.graph_store.methods.get_nodes", lambda **kw: entities
)
monkeypatch.setattr(
"semantica.deduplication.methods.detect_duplicates",
lambda *a, **k: detect_result,
raising=False,
)
# The CLI imports from .deduplication directly; patch that too.
import types
fake_dedup = _fake_module(detect_duplicates=lambda *a, **k: detect_result)
fake_merger_inst = types.SimpleNamespace(
merge_duplicates=lambda *a, **k: detect_result
)
fake_dedup.entity_merger = types.SimpleNamespace(
EntityMerger=lambda: fake_merger_inst
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.deduplication", fake_dedup
)
monkeypatch.setitem(
__import__("sys").modules,
"semantica.deduplication.entity_merger",
fake_dedup.entity_merger,
)
def test_deduplicate_output_json_is_valid(self, runner, monkeypatch, tmp_path):
"""deduplicate --output report.json must produce parseable JSON, not a repr."""
import json
self._patch_dedup(monkeypatch)
out = tmp_path / "report.json"
result = runner.invoke(
cli_module.main,
["deduplicate", "--action", "detect", "--output", str(out)],
)
_ok(result)
assert out.exists(), f"output file not created; output: {result.output!r}"
data = json.loads(out.read_text(encoding="utf-8"))
assert isinstance(data, (list, dict))
def test_deduplicate_output_csv_is_readable(self, runner, monkeypatch, tmp_path):
"""deduplicate --output report.csv (documented format) must produce valid CSV."""
import pandas as pd
self._patch_dedup(monkeypatch)
out = tmp_path / "report.csv"
result = runner.invoke(
cli_module.main,
["deduplicate", "--action", "detect", "--output", str(out)],
)
_ok(result)
assert out.exists(), f"CSV file not created; output: {result.output!r}"
df = pd.read_csv(out)
assert len(df) >= 1
class TestOntologyAlignOutput:
"""CLI-level regression tests for ontology align --output integration.
Uses runner.isolated_filesystem() so Click's exists=True source/target
validation passes, then patches semantica.ontology at the sys.modules level
before the import inside _action() fires — same pattern as
TestOntology.test_align_import_error_is_clean.
"""
_ALIGN_RESULT = {
"alignments": [{"source": "A", "target": "B", "score": 0.8}],
"total": 1,
}
def _patch_align(self, monkeypatch, align_result=None):
result = align_result if align_result is not None else self._ALIGN_RESULT
import types
fake_gen = types.SimpleNamespace(align=lambda *a, **k: result)
fake_ontology = _fake_module(
OntologyGenerator=lambda **k: fake_gen,
)
monkeypatch.setitem(
__import__("sys").modules, "semantica.ontology", fake_ontology
)
def test_ontology_align_output_json_is_valid(self, runner, monkeypatch, tmp_path):
"""ontology align --output alignments.json must produce parseable JSON."""
import json
self._patch_align(monkeypatch)
out = tmp_path / "alignments.json"
with runner.isolated_filesystem():
open("s.ttl", "w").close()
open("t.ttl", "w").close()
result = runner.invoke(
cli_module.main,
["ontology", "align",
"--source", "s.ttl", "--target", "t.ttl",
"--output", str(out)],
)
_ok(result)
assert out.exists(), f"output file not created; output: {result.output!r}"
data = json.loads(out.read_text(encoding="utf-8"))
assert isinstance(data, dict)
assert "alignments" in data
def test_ontology_align_output_jsonl_is_readable_by_pandas(
self, runner, monkeypatch, tmp_path
):
"""ontology align --output alignments.jsonl must produce valid JSONL:
exactly one JSON object per line, readable by pd.read_json(lines=True).
Regression for F2: dict result must NOT be pretty-printed across multiple
lines into a .jsonl file."""
import pandas as pd
self._patch_align(monkeypatch)
out = tmp_path / "alignments.jsonl"
with runner.isolated_filesystem():
open("s.ttl", "w").close()
open("t.ttl", "w").close()
result = runner.invoke(
cli_module.main,
["ontology", "align",
"--source", "s.ttl", "--target", "t.ttl",
"--output", str(out)],
)
_ok(result)
assert out.exists(), f"JSONL file not created; output: {result.output!r}"
raw = out.read_text(encoding="utf-8")
lines = [ln for ln in raw.splitlines() if ln.strip()]
assert len(lines) == 1, (
f"Expected exactly 1 JSONL line for a dict result, got {len(lines)}:\n{raw!r}"
)
# pd.read_json(lines=True) must succeed — this is what the F2 bug broke.
df = pd.read_json(out, lines=True)
assert "alignments" in df.columns
class _FakeUrlopenResponse:
"""Minimal context-manager response for a stubbed urllib.request.urlopen."""
def __init__(self, payload: bytes):
self._payload = payload
def __enter__(self) -> "_FakeUrlopenResponse":
return self
def __exit__(self, *exc: Any) -> bool:
return False
def read(self) -> bytes:
return self._payload
def _stub_release(monkeypatch, tag_name: str) -> None:
"""Make the changelog's GitHub release lookup return *tag_name*."""
import urllib.request
payload = json.dumps({"tag_name": tag_name, "body": "", "html_url": ""}).encode()
monkeypatch.setattr(
urllib.request,
"urlopen",
lambda *a, **kw: _FakeUrlopenResponse(payload),
)
class TestChangelogVersionTag:
"""changelog must strip the "v" prefix, not a run of leading characters.
Regression for #1845: ``tag.lstrip("v")`` treats "v" as a character set, so
a tag like ``vv1.2.3`` lost both leading v's. ``removeprefix("v")`` strips
exactly one, which is the documented intent.
"""
@pytest.mark.parametrize(
"tag_name,expected",
[
("v1.2.3", "1.2.3"),
("vv1.2.3", "v1.2.3"),
("1.2.3", "1.2.3"),
],
)
def test_changelog_json_latest_strips_one_v(
self, runner, monkeypatch, tag_name, expected
):
_stub_release(monkeypatch, tag_name)
result = runner.invoke(cli_module.main, ["changelog", "--json"])
_ok(result)
assert json.loads(result.output)["latest"] == expected
class TestChangelogUpdateCheck:
"""changelog must order versions, not compare them as strings.
A build ahead of the latest release (e.g. 0.8.0 against a v0.7.0 tag) used
to be told "Update available: 0.8.0 → 0.7.0", recommending a downgrade.
"""
@pytest.mark.parametrize(
"current,tag_name,expected",
[
("0.7.0", "v0.8.0", True),
("0.8.0", "v0.8.0", False),
("0.8", "v0.8.0", False),
("0.8.0", "v0.7.0", False),
("0.8.0.dev1", "v0.7.0", False),
("0.8.0rc1", "v0.8.0", True),
("0.8.0", "unknown", None),
],
)
def test_changelog_json_update_available(
self, runner, monkeypatch, current, tag_name, expected
):
_stub_release(monkeypatch, tag_name)
monkeypatch.setattr(cli_module, "__version__", current)
result = runner.invoke(cli_module.main, ["changelog", "--json"])
_ok(result)
assert json.loads(result.output)["update_available"] is expected
@pytest.mark.parametrize(
"current,tag_name,shown,hidden",
[
("0.7.0", "v0.8.0", "Update available", "ahead of the latest"),
("0.8.0", "v0.8.0", "on the latest version", "Update available"),
("0.8.0", "v0.7.0", "ahead of the latest", "Update available"),
("0.8.0", "unknown", "Could not compare", "Update available"),
],
)
def test_changelog_status_line(
self, runner, monkeypatch, current, tag_name, shown, hidden
):
_stub_release(monkeypatch, tag_name)
monkeypatch.setattr(cli_module, "__version__", current)
result = runner.invoke(cli_module.main, ["changelog"])
_ok(result)
assert shown in result.output
assert hidden not in result.output
class TestChangelogWithoutPackaging:
"""packaging is not a core dependency (#1513), so a slim install may lack it.
The fallback must still order plain X.Y.Z releases and must never report
an update it cannot establish.
"""
@pytest.mark.parametrize(
"current,tag_name,expected",
[
("0.7.0", "v0.8.0", True),
("0.8.0", "v0.7.0", False),
("0.8", "v0.8.0", False),
("0.10.0", "v0.9.0", False),
("0.8.0.dev1", "v0.8.0.dev1", False),
("0.8.0.dev1", "v0.7.0", None),
("0.8.0", "unknown", None),
],
)
def test_changelog_json_update_available_without_packaging(
self, runner, monkeypatch, current, tag_name, expected
):
import sys
# A None entry makes ``from packaging.version import ...`` raise ImportError.
monkeypatch.setitem(sys.modules, "packaging.version", None)
_stub_release(monkeypatch, tag_name)
monkeypatch.setattr(cli_module, "__version__", current)
result = runner.invoke(cli_module.main, ["changelog", "--json"])
_ok(result)
assert json.loads(result.output)["update_available"] is expected