groundworkers 0.7.0__tar.gz → 0.7.1__tar.gz

{groundworkers-0.7.0 → groundworkers-0.7.1}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           --password postgres \
           --database-name test_db \
           --test-only false
-        uv run omop-config databases add cdm test_cdm_db --connection pg_test --cdm-schema public
+        uv run omop-config databases add cdm test_cdm_db --connection pg_test --cdm-schema gw_primary --vocab-schema gw_vocab
         uv run omop-config databases add generic test_vector_db --connection pg_test --schema-name embeddings
         uv run omop-config vector-stores add test_embeddings \
           --backend-type pgvector \
@@ -44,3 +44,49 @@ jobs:
           --cdm-db test_cdm_db \
           --vector-store-name test_embeddings
         uv run python -m tests.support.seed_postgres_fixture
+  test-evidence:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - name: Run hermetic suite with coverage and skip reasons
+        run: |
+          uv sync --frozen --all-extras --dev
+          export GROUNDWORKERS_REQUIRE_FORMAT_TESTS=1
+          echo "GROUNDWORKERS_REQUIRE_FORMAT_TESTS=1" >> "$GITHUB_ENV"
+          COVERAGE_FILE="$RUNNER_TEMP/groundworkers.coverage" uv run pytest -q -ra \
+            --cov=groundworkers --cov-branch \
+            --cov-report=xml:"$RUNNER_TEMP/coverage.xml" \
+            --junitxml="$RUNNER_TEMP/pytest.xml"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: groundworkers-test-evidence
+          path: |
+            ${{ runner.temp }}/coverage.xml
+            ${{ runner.temp }}/pytest.xml
+          if-no-files-found: warn
+  wheel-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - name: Build and smoke-test base and optional wheel installs
+        run: |
+          uv build --wheel
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          wheel="$(pwd)/$wheel"
+          uv venv "$RUNNER_TEMP/gw-wheel-base" --python 3.12
+          uv pip install --python "$RUNNER_TEMP/gw-wheel-base/bin/python" "$wheel"
+          mkdir -p "$RUNNER_TEMP/gw-wheel-run"
+          cd "$RUNNER_TEMP/gw-wheel-run"
+          "$RUNNER_TEMP/gw-wheel-base/bin/python" "$GITHUB_WORKSPACE/tests/support/wheel_smoke.py" base
+          uv venv "$RUNNER_TEMP/gw-wheel-extras" --python 3.12
+          uv pip install --python "$RUNNER_TEMP/gw-wheel-extras/bin/python" "$wheel[all_source,tui]" httpx
+          "$RUNNER_TEMP/gw-wheel-extras/bin/python" "$GITHUB_WORKSPACE/tests/support/wheel_smoke.py" extras

{groundworkers-0.7.0 → groundworkers-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: groundworkers
-Version: 0.7.0
+Version: 0.7.1
 Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
 Requires-Python: >=3.12
 Requires-Dist: fastapi<1.0,>=0.110

groundworkers-0.7.1/docs/usage/testing.md

@@ -0,0 +1,45 @@
+# Testing
+
+## Test lanes
+
+Groundworkers uses distinct lanes because an isolated unit run cannot prove the database, optional parser, plugin-entry-point, or built-wheel contracts.
+
+| Lane | What it proves | CI behavior |
+|---|---|---|
+| Unit and service | Deterministic policy, adapter boundaries, source planning, transport behavior, and controlled provider responses | Runs without a live database or model service |
+| Optional dependency | Real XLSX, DOCX, and PDF parsing plus missing-extra guidance | Required format tests must pass in the all-extras CI lane; missing-extra behavior is simulated |
+| PostgreSQL integration | Seeded graph retrieval, real pgvector storage and reader behavior, model selection, filters, and embedding-tier grounding | Required: every required_integration case must be collected and pass |
+| Wheel smoke | Base and optional-extra installations, package entry-point discovery, CLI startup, and successful MCP/REST planning operations | Builds once and runs outside the checkout |
+| Optional live provider | Real configured model-provider connectivity | Opt-in developer smoke only; never substitutes for seeded embedding tests |
+
+## Running tests
+
+~~~bash
+# Hermetic suite, including real optional-format parsers
+uv run pytest -q -ra
+
+# Unit tests only
+uv run pytest tests/unit/
+
+# Required PostgreSQL cases; provide a seeded test stack first
+GROUNDWORKERS_CONFIG_PATH=/path/to/stack.toml \
+GROUNDWORKERS_REQUIRE_INTEGRATION=1 \
+GROUNDWORKERS_TEST_DATABASE_URL=postgresql+psycopg://... \
+uv run pytest -m required_integration -q -ra
+
+# Coverage for local review
+COVERAGE_FILE=/tmp/groundworkers.coverage uv run pytest -q -ra \
+  --cov=groundworkers --cov-branch --cov-report=term-missing
+~~~
+
+The required integration gate derives its cases from the `required_integration` marker, so every marked case is checked for collection and a passing result. Missing configuration, unavailable adapters, and absent seeded rows fail in that lane. The all-extras CI job applies the same execution check to `required_format` cases, so a missing parser cannot silently turn the format contract into a skip. Without the corresponding `GROUNDWORKERS_REQUIRE_*` flag, PostgreSQL and optional-format fixtures remain opt-in and skip with a reason.
+
+## Configuration and optional provider smoke
+
+Set GROUNDWORKERS_CONFIG_PATH (or GROUNDWORKERS_CONFIG) to the explicit Groundworkers stack file for integration tests. OA_CONFIG_PATH selects the oa-configurator default stack, but does not by itself opt the graph integration tests into a required run. PostgreSQL CI sets both paths and seeds a compact fixture before pytest starts.
+
+The external-provider smoke tests are separate from seeded deterministic embedding tests. To run them locally, set GROUNDWORKERS_RUN_EMBEDDING_INTEGRATION=1, GROUNDWORKERS_CONFIG_PATH, and GROUNDWORKERS_TEST_CONCEPT_ID; they require a configured provider and a concept with stored vectors.
+
+## Coverage and skip evidence
+
+CI publishes coverage.xml and pytest.xml from the hermetic all-extras run. The JUnit report carries named skip reasons. PostgreSQL CI separately enforces the required test list, so optional local skips cannot satisfy that gate. Coverage percentages are review evidence, not a global pass threshold. Prioritize unexecuted behavior at database, provider, transport, and packaging boundaries.

{groundworkers-0.7.0 → groundworkers-0.7.1}/pyproject.toml

@@ -112,5 +112,8 @@ include = ["src"]
 testpaths = ["tests"]
 markers = [
   "integration: requires a live backend or database",
+  "required_integration: deterministic integration contract required by CI",
+  "required_format: optional document-format contract required in all-extras CI",
+  "optional_integration: environment-dependent integration smoke test",
   "requires_client: requires an embedding API client",
 ]

{groundworkers-0.7.0 → groundworkers-0.7.1}/src/groundworkers/plugins.py

@@ -20,7 +20,6 @@ from enum import StrEnum
 from importlib.metadata import entry_points
 from typing import TYPE_CHECKING, Any, ClassVar, Protocol, runtime_checkable
 
-from groundskeeping.contracts import CommandPlan
 from oa_configurator import (  # type: ignore[import-untyped]
     PackageConfigBase,
     ResolvedDatabase,
@@ -36,6 +35,7 @@ if TYPE_CHECKING:
         ConfigWorkflowSpec,
         MutationOperation,
     )
+    from groundskeeping.contracts import CommandPlan
 
     from groundworkers.services.grounding import ConceptGroundingService
     from groundworkers.services.mapping import MappingService

{groundworkers-0.7.0 → groundworkers-0.7.1}/src/groundworkers/services/source_planning/assisted.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from dataclasses import replace
 
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
 from groundworkers.adapters.llm import LLMAdapter
 from groundworkers.base.errors import GroundworkersError
@@ -31,6 +31,8 @@ Respond with raw JSON only.
 
 
 class AssistedColumnDecision(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
     header: str
     role: str | None = None
     confidence: float = Field(ge=0.0, le=1.0)
@@ -40,6 +42,8 @@ class AssistedColumnDecision(BaseModel):
 
 
 class AssistedClassificationResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
     decisions: list[AssistedColumnDecision] = Field(default_factory=list)
 
 

groundworkers-0.7.1/tests/conftest.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+_REQUIRED_TEST_MARKERS = {
+    "GROUNDWORKERS_REQUIRE_INTEGRATION": "required_integration",
+    "GROUNDWORKERS_REQUIRE_FORMAT_TESTS": "required_format",
+}
+_required_test_ids: dict[str, set[str]] = {}
+_required_test_outcomes: dict[str, dict[str, str]] = {}
+
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+
+@pytest.fixture(autouse=True)
+def _isolated_env_file(tmp_path_factory, monkeypatch):
+    """Keep the recorded config location out of the developer's home directory.
+
+    `groundworkers._env.ENV_FILE` is a real path under ~/.config/omop, and the
+    location wizard writes it. Autouse rather than opt-in: a test that records a
+    location and forgets to redirect it repoints the machine Groundworkers reads
+    from, which is not a failure any assertion would catch.
+    """
+    from groundworkers import _env
+
+    monkeypatch.setattr(
+        _env, "ENV_FILE", tmp_path_factory.mktemp("env") / "groundworkers.env"
+    )
+    monkeypatch.delenv(_env.ENV_CONFIG_PATH, raising=False)
+    # `load_environment` writes this module global directly, so a test that calls
+    # it leaves every later test looking like it was launched with a broken
+    # OA_CONFIG_PATH -- which makes the setup page open the location wizard.
+    monkeypatch.setattr(_env, "_rejected", None)
+
+
+def _missing_required_tests(expected: set[str], selected: set[str]) -> list[str]:
+    return sorted(expected - selected)
+
+
+def _required_test_failures(
+    expected: set[str], outcomes: dict[str, str]
+) -> list[str]:
+    return sorted(nodeid for nodeid in expected if outcomes.get(nodeid) != "passed")
+
+
+@pytest.hookimpl(hookwrapper=True, tryfirst=True)
+def pytest_collection_modifyitems(session: pytest.Session, items: list[pytest.Item]):
+    enabled = {
+        marker
+        for variable, marker in _REQUIRED_TEST_MARKERS.items()
+        if os.getenv(variable) == "1"
+    }
+    expected = {
+        marker: {item.nodeid for item in items if item.get_closest_marker(marker)}
+        for marker in enabled
+    }
+    yield
+    selected_items = {item.nodeid for item in session.items}
+    _required_test_ids.clear()
+    _required_test_ids.update(expected)
+    for marker in enabled:
+        _required_test_outcomes[marker] = {}
+    session.config._required_test_ids = expected
+    session.config._required_test_collection_errors = {
+        marker: _missing_required_tests(ids, selected_items)
+        for marker, ids in expected.items()
+    }
+    session.config._required_test_outcomes = {
+        marker: _required_test_outcomes.setdefault(marker, {}) for marker in enabled
+    }
+
+
+def pytest_runtest_logreport(report: pytest.TestReport) -> None:
+    if report.when not in {"setup", "call", "teardown"}:
+        return
+    for marker, outcomes in _required_test_outcomes.items():
+        if report.when == "call" or report.outcome != "passed":
+            if report.nodeid in _required_test_ids.get(marker, set()):
+                outcomes[report.nodeid] = report.outcome
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    required = getattr(session.config, "_required_test_ids", {})
+    collection_errors = getattr(session.config, "_required_test_collection_errors", {})
+    outcomes = getattr(session.config, "_required_test_outcomes", {})
+    problems = {
+        marker: sorted(
+            set(collection_errors.get(marker, []))
+            | set(_required_test_failures(ids, outcomes.get(marker, {})))
+        )
+        for marker, ids in required.items()
+    }
+    for marker, ids in required.items():
+        if not ids:
+            problems[marker].append(f"no tests collected with {marker} marker")
+    failures = {marker: entries for marker, entries in problems.items() if entries}
+    if not failures:
+        return
+    reporter = session.config.pluginmanager.get_plugin("terminalreporter")
+    if reporter is not None:
+        for marker, entries in failures.items():
+            reporter.write_sep("!", f"required {marker} execution gate failed")
+            for nodeid in entries:
+                outcome = outcomes.get(marker, {}).get(nodeid, "not executed or deselected")
+                reporter.write_line(f"{nodeid}: {outcome}")
+    session.exitstatus = pytest.ExitCode.TESTS_FAILED

{groundworkers-0.7.0 → groundworkers-0.7.1}/tests/integration/test_omop_emb_adapter.py

@@ -42,7 +42,7 @@ def _load_integration_adapter():
     return adapter
 
 
-@pytest.mark.integration
+@pytest.mark.optional_integration
 def test_index_status_returns_at_least_one_model():
     adapter = _load_integration_adapter()
 
@@ -59,7 +59,7 @@ def _get_test_concept_id() -> int:
     return int(value)
 
 
-@pytest.mark.integration
+@pytest.mark.optional_integration
 def test_get_neighbours_returns_sorted_results():
     adapter = _load_integration_adapter()
     status = adapter.index_status()
@@ -71,11 +71,12 @@ def test_get_neighbours_returns_sorted_results():
         model_name=status["models"][0]["model_name"],
     )
 
+    assert result["results"], "configured embedding smoke test returned no neighbours"
     similarities = [item["similarity"] for item in result["results"]]
     assert similarities == sorted(similarities, reverse=True)
 
 
-@pytest.mark.integration
+@pytest.mark.optional_integration
 def test_get_neighbours_excludes_query_concept():
     adapter = _load_integration_adapter()
     status = adapter.index_status()
@@ -87,10 +88,11 @@ def test_get_neighbours_excludes_query_concept():
         model_name=status["models"][0]["model_name"],
     )
 
+    assert result["results"], "configured embedding smoke test returned no neighbours"
     assert all(item["concept_id"] != concept_id for item in result["results"])
 
 
-@pytest.mark.integration
+@pytest.mark.optional_integration
 def test_get_neighbours_unknown_concept_raises_not_found():
     adapter = _load_integration_adapter()
     status = adapter.index_status()

groundworkers-0.7.1/tests/integration/test_omop_emb_contract.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+from oa_configurator import ResolvedModel, ResolvedProvider
+from omop_emb.backends import open_vector_store_reader
+from omop_emb.config import MetricType
+from omop_emb.interface import EmbeddingReaderInterface
+
+from groundworkers.adapters.omop_emb import OmopEmbAdapter
+from groundworkers.adapters.omop_graph import OmopGraphAdapter
+from groundworkers.base.errors import GroundworkersError
+from groundworkers.bootstrap import build_app_config
+from groundworkers.services.graph import GraphService
+from groundworkers.services.grounding import ConceptGroundingService
+from tests.support.embedding_contract_fixture import (
+    MODEL_NAME,
+    seed_embedding_contract,
+)
+
+
+class FixedEncoder:
+    provider = "ollama"
+    model = MODEL_NAME
+
+    def embed_texts(self, texts, *, role, batch_size=None):
+        return [[1.0, 0.0, 0.0] if text != "orthogonal query" else [0.0, 1.0, 0.0] for text in texts]
+
+    async def async_embed_texts(self, texts, *, role, batch_size=None):
+        return self.embed_texts(texts, role=role, batch_size=batch_size)
+
+
+@pytest.fixture(scope="module")
+def embedding_contract():
+    if os.getenv("GROUNDWORKERS_REQUIRE_INTEGRATION") != "1":
+        pytest.skip("deterministic pgvector embedding contract runs in required PostgreSQL CI")
+    config_path = os.getenv("GROUNDWORKERS_CONFIG_PATH") or os.getenv("GROUNDWORKERS_CONFIG")
+    if not config_path:
+        raise RuntimeError("required embedding contract needs GROUNDWORKERS_CONFIG_PATH")
+    config = build_app_config(config_path=config_path)
+    if config.vector_store is None:
+        raise AssertionError("required embedding contract has no configured vector store")
+    seed_embedding_contract(config)
+    adapter = OmopEmbAdapter(
+        backend_factory=lambda: open_vector_store_reader(config.vector_store),
+        backend_type=config.vector_store.backend_type,
+        cdm_session_factory=config.cdm_session_factory,
+    )
+    adapter._model_backend_factory = lambda: FixedEncoder()
+    try:
+        yield config, adapter
+    finally:
+        adapter.close()
+
+
+@pytest.mark.required_integration
+def test_real_reader_returns_seeded_neighbours_and_keeps_batch_alignment(embedding_contract):
+    _config, adapter = embedding_contract
+    neighbours = adapter.get_neighbours(201826, limit=5, model_name=MODEL_NAME)
+    assert [item["concept_id"] for item in neighbours["results"]][:2] == [201827, 201830]
+    assert 201826 not in {item["concept_id"] for item in neighbours["results"]}
+
+    record = adapter._resolve_model_record(MODEL_NAME)
+    reader = EmbeddingReaderInterface(
+        model=record.model_name,
+        backend=adapter._get_backend(),
+        metric_type=record.metric_type or MetricType.COSINE,
+        provider_type=record.provider_type,
+    )
+    batch = reader.get_nearest_concepts_from_query_texts(
+        ["nearest to diabetes", "orthogonal query"],
+        model_backend=FixedEncoder(),
+        k=1,
+        faiss_index_config=record.index_config,
+    )
+    assert [[match.concept_id for match in row] for row in batch] == [[201826], [201828]]
+
+
+@pytest.mark.required_integration
+def test_real_model_registry_handles_missing_and_ambiguous_selection(embedding_contract):
+    _, adapter = embedding_contract
+    assert adapter.resolve_model_name(MODEL_NAME) == MODEL_NAME
+    with pytest.raises(GroundworkersError) as missing:
+        adapter.resolve_model_name("not-registered:v1")
+    assert missing.value.code == "NOT_FOUND"
+    with pytest.raises(GroundworkersError) as ambiguous:
+        adapter.resolve_model_name(None)
+    assert ambiguous.value.code == "BACKEND_UNAVAIL"
+
+
+@pytest.mark.required_integration
+def test_real_text_search_applies_domain_vocabulary_standard_and_active_filters(embedding_contract):
+    _, adapter = embedding_contract
+    result = adapter.search(
+        "a deterministic unrelated phrase",
+        limit=10,
+        domain="Condition",
+        vocabulary="SNOMED",
+        standard_only=True,
+        active_only=True,
+        model_name=MODEL_NAME,
+    )
+    assert {item["concept_id"] for item in result["results"]} == {201826, 201827, 201828}
+
+
+@pytest.mark.required_integration
+def test_graph_grounding_executes_real_embedding_tier_with_seeded_reader(embedding_contract):
+    config, _adapter = embedding_contract
+    assert config.vector_store is not None
+    resolved_model = ResolvedModel(
+        name="groundworkers_fixture",
+        provider=ResolvedProvider(
+            name="fixture_provider", provider="ollama", base_url=None, api_key=None
+        ),
+        model=MODEL_NAME,
+        embedding_dim=3,
+        document_prefix=None,
+        query_prefix=None,
+        embeddings=True,
+        tool_use=False,
+        structured_output=False,
+        extended_thinking=False,
+        configuration={},
+    )
+    graph_adapter = OmopGraphAdapter(
+        engine=config.cdm_engine,
+        cdm_session_factory=config.cdm_session_factory,
+        embedding_backend_factory=lambda: open_vector_store_reader(config.vector_store),
+        resolved_embedding_model=resolved_model,
+        model_backend_factory=FixedEncoder,
+    )
+    assert graph_adapter.is_available() is True
+    graph = GraphService(graph_adapter)
+    assert graph.embedding_resolver_active is True
+
+    result = ConceptGroundingService(graph).ground(
+        "a deterministic unrelated phrase",
+        limit=5,
+        domain="Condition",
+        vocabulary_id=None,
+    )
+
+    assert result["grounding_explanation"]["matched_tier"] == "EMBEDDING_NEAREST"
+    assert result["grounding_explanation"]["used_embedding"] is True
+    assert [hit["concept_id"] for hit in result["results"]]
+    assert result["results"][0]["concept_id"] == 201826