test: cover non-DB transformation layer

Author: SGevorg

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.30.2
+- Add unit tests for the rest of the non-DB-touching transformation surface — five files covering `tools.py` (`BaseTool.to_api_schema`, `ToolRegistry`), `agents/llm_client.py` (`resolve_provider`, `_normalize_anthropic_stop`, `_normalize_openai_stop`), `knowledge/__init__.py` (`load`, `load_onboarding_block`, `onboarding_summary` with override and default paths), `records/__init__.py` (`RecordsExpert.ingest` validation paths with mocked storage), and `registry.py` (`schema_fragment` and `_render_deployment_section_seed` with patched `_db_rows` for DB isolation). 47 new tests total; full suite (55 tests) runs in ~0.3s.
+
 ## 1.30.1
 - Wire pytest into CI. New `.github/workflows/test.yml` runs `uv run pytest tests/unit/` on every PR and push to `main`, alongside the existing lint workflow. Test failures now block merges.
 

pearscarf/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.30.1"
+__version__ = "1.30.2"
 
 # Make installed expert packages importable from the experts/ folder.
 # Temporary — replaced by the registry-driven discovery in a follow-up.

tests/unit/test_knowledge.py

@@ -0,0 +1,117 @@
+"""Tests for `pearscarf.knowledge` — prompt loader + onboarding block resolution."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import pearscarf.knowledge as knowledge
+
+
+@pytest.fixture(autouse=True)
+def _reset_onboarding_cache() -> None:
+    """Drop the module-level onboarding cache before each test."""
+    knowledge._onboarding_block = None
+    knowledge._onboarding_source = None
+
+
+# ---- load(name) ----
+
+
+def test_load_named_prompt_reads_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("ONBOARDING_PROMPT_PATH", raising=False)
+    content = knowledge.load("onboarding")
+    assert content  # non-empty default ships with the repo
+
+
+def test_load_with_override_env_var(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    override = tmp_path / "custom_onboarding.md"
+    override.write_text("CUSTOM ONBOARDING TEXT")
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(override))
+
+    assert knowledge.load("onboarding") == "CUSTOM ONBOARDING TEXT"
+
+
+def test_load_with_override_pointing_to_missing_file_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    missing = tmp_path / "nonexistent.md"
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(missing))
+
+    with pytest.raises(FileNotFoundError, match="ONBOARDING_PROMPT_PATH"):
+        knowledge.load("onboarding")
+
+
+def test_load_unknown_name_raises_key_error() -> None:
+    with pytest.raises(KeyError):
+        knowledge.load("does_not_exist")
+
+
+# ---- load_onboarding_block ----
+
+
+def test_load_onboarding_block_frames_default_content(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ONBOARDING_PROMPT_PATH", raising=False)
+    block = knowledge.load_onboarding_block()
+    assert block.startswith("## Onboarding\n\n")
+    assert block.endswith("\n\n---\n\n")
+
+
+def test_load_onboarding_block_uses_override_content(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    override = tmp_path / "custom.md"
+    override.write_text("INNER")
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(override))
+
+    assert knowledge.load_onboarding_block() == "## Onboarding\n\nINNER\n\n---\n\n"
+
+
+def test_load_onboarding_block_returns_empty_when_content_blank(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    override = tmp_path / "blank.md"
+    override.write_text("   \n  \n")
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(override))
+
+    assert knowledge.load_onboarding_block() == ""
+
+
+# ---- onboarding_summary ----
+
+
+def test_onboarding_summary_default_returns_label_and_count(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ONBOARDING_PROMPT_PATH", raising=False)
+    label, count = knowledge.onboarding_summary()
+    assert "default" in label
+    assert count > 0
+
+
+def test_onboarding_summary_with_override_label_includes_override(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    override = tmp_path / "custom.md"
+    override.write_text("HELLO")
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(override))
+
+    label, count = knowledge.onboarding_summary()
+    assert "override" in label
+    assert str(override) in label
+    assert count > 0
+
+
+def test_onboarding_summary_blank_content_marks_empty(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    override = tmp_path / "blank.md"
+    override.write_text("")
+    monkeypatch.setenv("ONBOARDING_PROMPT_PATH", str(override))
+
+    label, count = knowledge.onboarding_summary()
+    assert "(empty)" in label
+    assert count == 0

tests/unit/test_llm_client.py

@@ -0,0 +1,84 @@
+"""Tests for pure helpers in `pearscarf.agents.llm_client`:
+`resolve_provider`, `_normalize_anthropic_stop`, `_normalize_openai_stop`.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from pearscarf.agents.llm_client import (
+    _normalize_anthropic_stop,
+    _normalize_openai_stop,
+    resolve_provider,
+)
+
+# ---- resolve_provider ----
+
+
+def test_resolve_provider_claude_prefix_routes_to_anthropic() -> None:
+    assert resolve_provider("claude-opus-4-7") == "anthropic"
+
+
+def test_resolve_provider_gpt_prefix_routes_to_openai() -> None:
+    assert resolve_provider("gpt-5-turbo") == "openai"
+
+
+def test_resolve_provider_o_series_routes_to_openai() -> None:
+    assert resolve_provider("o1-preview") == "openai"
+    assert resolve_provider("o3-mini") == "openai"
+    assert resolve_provider("o4-mini") == "openai"
+
+
+def test_resolve_provider_explicit_overrides_model_prefix() -> None:
+    assert resolve_provider("claude-opus-4-7", "openai") == "openai"
+    assert resolve_provider("gpt-5", "anthropic") == "anthropic"
+
+
+def test_resolve_provider_unknown_explicit_raises() -> None:
+    with pytest.raises(ValueError, match="not supported"):
+        resolve_provider("claude-opus-4-7", "azure")
+
+
+def test_resolve_provider_unknown_model_prefix_raises() -> None:
+    with pytest.raises(ValueError, match="Cannot infer provider"):
+        resolve_provider("llama-3-70b")
+
+
+# ---- _normalize_anthropic_stop ----
+
+
+def test_normalize_anthropic_passes_through_canonical_values() -> None:
+    assert _normalize_anthropic_stop("end_turn") == "end_turn"
+    assert _normalize_anthropic_stop("tool_use") == "tool_use"
+    assert _normalize_anthropic_stop("max_tokens") == "max_tokens"
+
+
+def test_normalize_anthropic_none_becomes_unknown() -> None:
+    assert _normalize_anthropic_stop(None) == "unknown"
+
+
+def test_normalize_anthropic_passes_through_unrecognized_strings() -> None:
+    assert _normalize_anthropic_stop("weird_stop") == "weird_stop"
+
+
+# ---- _normalize_openai_stop ----
+
+
+def test_normalize_openai_maps_stop_to_end_turn() -> None:
+    assert _normalize_openai_stop("stop") == "end_turn"
+
+
+def test_normalize_openai_maps_tool_calls_to_tool_use() -> None:
+    assert _normalize_openai_stop("tool_calls") == "tool_use"
+
+
+def test_normalize_openai_maps_length_to_max_tokens() -> None:
+    assert _normalize_openai_stop("length") == "max_tokens"
+
+
+def test_normalize_openai_none_becomes_unknown() -> None:
+    assert _normalize_openai_stop(None) == "unknown"
+
+
+def test_normalize_openai_unmapped_passes_through() -> None:
+    assert _normalize_openai_stop("content_filter") == "content_filter"

tests/unit/test_records_validation.py

@@ -0,0 +1,107 @@
+"""Tests for `pearscarf.records.RecordsExpert.ingest` validation paths.
+
+The ingest path validates body/url/op_area then delegates to
+`ctx.storage.save_record`. These tests cover the validation branches with a
+mocked context — no DB involved.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+from unittest.mock import MagicMock
+
+import pytest
+
+from pearscarf.expert_context import ExpertContext
+from pearscarf.records import RecordsExpert, RecordSubmissionError
+
+VALID_BODY = """\
+Title: Test record
+
+Id: test-record-20260510
+Date: 2026-05-10
+
+Anchor.
+
+## For humans
+
+Some prose.
+
+## For agents
+
+```yaml
+facts:
+  - Some fact about something.
+```
+"""
+
+
+def _expert_with_mock_storage() -> tuple[RecordsExpert, MagicMock]:
+    """Return a RecordsExpert wired to a Mock storage."""
+    ctx = MagicMock()
+    ctx.storage.save_record.return_value = "record_test123"
+    return RecordsExpert(cast("ExpertContext", ctx)), ctx.storage.save_record
+
+
+# ---- validation rejections ----
+
+
+def test_empty_body_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    with pytest.raises(RecordSubmissionError, match="body is empty"):
+        expert.ingest("", "https://example.com/x", "reality")
+
+
+def test_whitespace_only_body_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    with pytest.raises(RecordSubmissionError, match="body is empty"):
+        expert.ingest("   \n\n   ", "https://example.com/x", "reality")
+
+
+def test_empty_url_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    with pytest.raises(RecordSubmissionError, match="url is required"):
+        expert.ingest(VALID_BODY, "", "reality")
+
+
+def test_invalid_op_area_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    with pytest.raises(RecordSubmissionError, match="op_area must be one of"):
+        expert.ingest(VALID_BODY, "https://example.com/x", "bogus")
+
+
+def test_body_missing_id_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    body = "Title: x\n\nDate: 2026-05-10\n\nAnchor."
+    with pytest.raises(RecordSubmissionError, match=r"missing required `Id:` line"):
+        expert.ingest(body, "https://example.com/x", "reality")
+
+
+def test_body_missing_date_raises() -> None:
+    expert, _ = _expert_with_mock_storage()
+    body = "Title: x\n\nId: x123\n\nAnchor."
+    with pytest.raises(RecordSubmissionError, match=r"missing required `Date:` line"):
+        expert.ingest(body, "https://example.com/x", "reality")
+
+
+# ---- happy path ----
+
+
+def test_valid_input_calls_storage_with_correct_args() -> None:
+    expert, save_record = _expert_with_mock_storage()
+    result = expert.ingest(VALID_BODY, "https://example.com/x", "reality")
+    assert result == "record_test123"
+
+    save_record.assert_called_once_with(
+        record_type="record",
+        raw=VALID_BODY,
+        content=VALID_BODY,
+        metadata={"op_area": "reality", "source_url": "https://example.com/x"},
+        dedup_key="test-record-20260510",
+    )
+
+
+def test_valid_input_with_intention_op_area() -> None:
+    expert, save_record = _expert_with_mock_storage()
+    expert.ingest(VALID_BODY, "https://example.com/x", "intention")
+    assert save_record.call_args.kwargs["metadata"]["op_area"] == "intention"