test: add Ollama markers and improve test documentation

- Add @pytest.mark.ollama to tests requiring Ollama backend
- Update test/README.md with comprehensive marker documentation
- Update .gitignore for logs/ and pytest output files

Author: planetf1

.gitignore

@@ -8,6 +8,13 @@ scratchpad/
 *.egg-info
 .vscode/
 
+# HPC job logs directory (synced from remote)
+logs/
+
+# Test output files
+pytest_*.stdout
+pytest_*.stderr
+
 # IDE
 .idea
 

docs/examples/aLora/101_example.py

@@ -1,4 +1,5 @@
-# pytest: huggingface, requires_heavy_ram, llm
+# pytest: skip, huggingface, requires_heavy_ram, llm
+# SKIP REASON: Example broken since intrinsics refactor - see issue #385
 
 import time
 

docs/examples/mify/rich_document_advanced.py

@@ -1,4 +1,5 @@
-# pytest: huggingface, requires_heavy_ram, llm
+# pytest: skip, huggingface, requires_heavy_ram, llm
+# SKIP REASON: CXXABI_1.3.15 not found - conda environment issue on HPC systems with old glibc
 
 # ruff: noqa E402
 # Example: Rich Documents and Templating

docs/examples/safety/guardian.py

@@ -1,4 +1,4 @@
-# pytest: huggingface, requires_heavy_ram, llm
+# pytest: ollama, llm
 
 """Example of using the Enhanced Guardian Requirement with Granite Guardian 3.3 8B"""
 

docs/examples/safety/guardian_huggingface.py

@@ -1,4 +1,4 @@
-# pytest: huggingface, requires_heavy_ram, llm
+# pytest: ollama, huggingface, requires_heavy_ram, llm
 
 """Example of using GuardianCheck with HuggingFace backend for direct model inference
 

docs/examples/safety/repair_with_guardian.py

@@ -1,4 +1,4 @@
-# pytest: huggingface, requires_heavy_ram, llm
+# pytest: ollama, huggingface, requires_heavy_ram, llm
 
 """RepairTemplateStrategy Example with Actual Function Call Validation
 Demonstrates how RepairTemplateStrategy repairs responses using actual function calls.

test/README.md

@@ -1,3 +1,80 @@
+# Mellea Test Suite
 
+Test files must be named as `test_*.py` so that pydocstyle ignores them.
 
-Test files must be named as "test_*.py" so that pydocstyle ignores them
+## Running Tests
+
+```bash
+# Fast tests only (~2 min) - skips qualitative and slow tests
+uv run pytest -m "not qualitative"
+
+# Default - includes qualitative tests, skips slow tests
+uv run pytest
+
+# All tests including slow tests (>5 min)
+uv run pytest -m slow
+uv run pytest  # without pytest.ini config
+```
+
+## GPU Testing on CUDA Systems
+
+### The Problem: CUDA EXCLUSIVE_PROCESS Mode
+
+When running GPU tests on systems with `EXCLUSIVE_PROCESS` mode (common on HPC clusters), you may encounter "CUDA device busy" errors. This happens because:
+
+1. **Parent Process Context**: The pytest parent process creates a CUDA context when running regular tests
+2. **Subprocess Blocking**: Example tests run in subprocesses (via `docs/examples/conftest.py`)
+3. **Exclusive Access**: In `EXCLUSIVE_PROCESS` mode, only one process can hold a CUDA context per GPU
+4. **Result**: Subprocesses fail with "CUDA device busy" when the parent still holds the context
+
+### Solution 1: NVIDIA MPS (Recommended)
+
+**NVIDIA Multi-Process Service (MPS)** allows multiple processes to share a GPU in `EXCLUSIVE_PROCESS` mode:
+
+```bash
+# Enable MPS in your job scheduler configuration
+# Consult your HPC documentation for specific syntax
+```
+
+### Why This Matters
+
+The test infrastructure runs examples in subprocesses (see `docs/examples/conftest.py`) to:
+- Isolate example execution environments
+- Capture stdout/stderr cleanly
+- Prevent cross-contamination between examples
+
+However, this creates the "Parent Trap": the parent pytest process holds a CUDA context from running regular tests, blocking subprocesses from accessing the GPU.
+
+### Technical Details
+
+**CUDA Context Lifecycle**:
+- Created on first CUDA operation (e.g., `torch.cuda.is_available()`)
+- Persists until process exit or explicit `cudaDeviceReset()`
+- In `EXCLUSIVE_PROCESS` mode, blocks other processes from GPU access
+
+**MPS Architecture**:
+- Runs as a proxy service between applications and GPU driver
+- Multiplexes CUDA contexts from multiple processes onto single GPU
+- Transparent to applications - no code changes needed
+- Requires explicit enablement via job scheduler flags
+
+**Alternative Approaches Tried** (documented in `GPU_PARENT_TRAP_SOLUTION.md`):
+- ❌ `torch.cuda.empty_cache()` - Only affects PyTorch allocator, not driver context
+- ❌ `cudaDeviceReset()` in subprocesses - Parent still holds context
+- ❌ Inter-example delays - Doesn't release parent context
+- ❌ pynvml polling - Can't force parent to release context
+- ✅ MPS - Allows GPU sharing without code changes
+
+## Test Markers
+
+See [`MARKERS_GUIDE.md`](MARKERS_GUIDE.md) for complete marker documentation.
+
+Key markers for GPU testing:
+- `@pytest.mark.huggingface` - Requires HuggingFace backend (local, GPU-heavy)
+- `@pytest.mark.requires_gpu` - Requires GPU hardware
+- `@pytest.mark.requires_heavy_ram` - Requires 48GB+ RAM
+- `@pytest.mark.slow` - Tests taking >5 minutes
+
+## Coverage
+
+Coverage reports are generated in `htmlcov/` and `coverage.json`.

test/stdlib/sampling/test_majority_voting.py

@@ -9,6 +9,9 @@
     MBRDRougeLStrategy,
 )
 
+# Mark all tests as requiring Ollama (start_session defaults to Ollama)
+pytestmark = [pytest.mark.ollama, pytest.mark.llm, pytest.mark.qualitative]
+
 
 @pytest.fixture(scope="module")
 def m_session(gh_run):

test/stdlib/sampling/test_sampling_ctx.py

@@ -7,11 +7,18 @@
 from mellea.stdlib.sampling import MultiTurnStrategy, RejectionSamplingStrategy
 
 
-class TestSamplingCtxCase:
-    m = start_session(
+@pytest.fixture(scope="class")
+def m_session():
+    """Shared session for sampling context tests."""
+    return start_session(
         model_options={ModelOption.MAX_NEW_TOKENS: 100}, ctx=ChatContext()
     )
 
+
+@pytest.mark.ollama
+@pytest.mark.llm
+@pytest.mark.qualitative
+class TestSamplingCtxCase:
     def _run_asserts_for_ctx_testing(self, res):
         assert isinstance(res, SamplingResult), "res should be a SamplingResult."
 
@@ -27,9 +34,9 @@ def _run_asserts_for_ctx_testing(self, res):
             "there should be 3 validation results."
         )
 
-    def test_ctx_for_rejection_sampling(self):
-        self.m.reset()
-        res = self.m.instruct(
+    def test_ctx_for_rejection_sampling(self, m_session):
+        m_session.reset()
+        res = m_session.instruct(
             "Write a sentence.",
             requirements=[
                 "be funny",
@@ -40,10 +47,10 @@ def test_ctx_for_rejection_sampling(self):
             return_sampling_results=True,
         )
         self._run_asserts_for_ctx_testing(res)
-        assert len(self.m.ctx.as_list()) == 2, (
+        assert len(m_session.ctx.as_list()) == 2, (
             "there should only be a message and a response in the ctx."
         )
-        assert len(self.m.last_prompt()) == 1, (  # type: ignore
+        assert len(m_session.last_prompt()) == 1, (  # type: ignore
             "Last prompt should only have only one instruction inside - independent of sampling iterations."
         )
 
@@ -55,9 +62,9 @@ def test_ctx_for_rejection_sampling(self):
         assert isinstance(val_res.context.previous_node.node_data, Requirement)  # type: ignore
         assert val_res.context.node_data is val_res.thunk
 
-    def test_ctx_for_multiturn(self):
-        self.m.reset()
-        res = self.m.instruct(
+    def test_ctx_for_multiturn(self, m_session):
+        m_session.reset()
+        res = m_session.instruct(
             "Write a sentence.",
             requirements=[
                 "be funny",
@@ -69,10 +76,10 @@ def test_ctx_for_multiturn(self):
         )
 
         self._run_asserts_for_ctx_testing(res)
-        assert len(self.m.ctx.as_list()) >= 2, (
+        assert len(m_session.ctx.as_list()) >= 2, (
             "there should be at least a message and a response in the ctx; more if the first result failed validation"
         )
-        assert len(self.m.last_prompt()) == len(res.sample_generations) * 2 - 1, (  # type: ignore
+        assert len(m_session.last_prompt()) == len(res.sample_generations) * 2 - 1, (  # type: ignore
             "For n sampling iterations there should be 2n-1 prompt conversation elements in the last prompt."
         )
 

test/stdlib/test_chat_view.py

@@ -4,6 +4,9 @@
 from mellea.stdlib.context import ChatContext
 from mellea.stdlib.session import start_session
 
+# Mark all tests as requiring Ollama (start_session defaults to Ollama)
+pytestmark = [pytest.mark.ollama, pytest.mark.llm]
+
 
 @pytest.fixture(scope="function")
 def linear_session():