feat: implement SearchService for semantic document search

- Add SearchService class with comprehensive search functionality
- Support for semantic search using embeddings and vector similarity
- Configurable top_k results and similarity threshold filtering
- Integration with existing VectorDatabase and EmbeddingService
- Comprehensive test suite with 12 test cases (100% passing)
- Full error handling and parameter validation
- TDD approach with unit and integration tests
- Code formatting compliance (black, isort, flake8)

Addresses GitHub Issue #14
Phase 2B implementation ready for Flask API integration

src/search/__init__.py

@@ -0,0 +1 @@
+"""Search module for semantic document retrieval."""

src/search/search_service.py

@@ -0,0 +1,145 @@
+"""
+SearchService - Semantic document search functionality.
+
+This module provides semantic search capabilities for the document corpus
+using embeddings and vector similarity search through ChromaDB integration.
+
+Classes:
+    SearchService: Main class for performing semantic search operations
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from src.embedding.embedding_service import EmbeddingService
+from src.vector_store.vector_db import VectorDatabase
+
+logger = logging.getLogger(__name__)
+
+
+class SearchService:
+    """
+    Semantic search service for finding relevant documents using embeddings.
+
+    This service combines text embedding generation with vector similarity search
+    to provide relevant document retrieval based on semantic similarity rather
+    than keyword matching.
+
+    Attributes:
+        vector_db: VectorDatabase instance for similarity search
+        embedding_service: EmbeddingService instance for query embedding
+    """
+
+    def __init__(
+        self,
+        vector_db: Optional[VectorDatabase],
+        embedding_service: Optional[EmbeddingService],
+    ):
+        """
+        Initialize SearchService with required dependencies.
+
+        Args:
+            vector_db: VectorDatabase instance for storing and searching embeddings
+            embedding_service: EmbeddingService instance for generating embeddings
+
+        Raises:
+            ValueError: If either vector_db or embedding_service is None
+        """
+        if vector_db is None:
+            raise ValueError("vector_db cannot be None")
+        if embedding_service is None:
+            raise ValueError("embedding_service cannot be None")
+
+        self.vector_db = vector_db
+        self.embedding_service = embedding_service
+        logger.info("SearchService initialized successfully")
+
+    def search(
+        self, query: str, top_k: int = 5, threshold: float = 0.0
+    ) -> List[Dict[str, Any]]:
+        """
+        Perform semantic search for relevant documents.
+
+        Args:
+            query: Text query to search for
+            top_k: Maximum number of results to return (must be positive)
+            threshold: Minimum similarity score threshold (0.0 to 1.0)
+
+        Returns:
+            List of search results, each containing:
+                - chunk_id: Unique identifier for the document chunk
+                - content: Text content of the document chunk
+                - similarity_score: Similarity score (0.0 to 1.0, higher is better)
+                - metadata: Additional metadata (filename, chunk_index, etc.)
+
+        Raises:
+            ValueError: If query is empty, top_k is not positive, or threshold
+                is invalid
+            RuntimeError: If embedding generation or vector search fails
+        """
+        # Validate input parameters
+        if not query or not query.strip():
+            raise ValueError("Query cannot be empty")
+
+        if top_k <= 0:
+            raise ValueError("top_k must be positive")
+
+        if not (0.0 <= threshold <= 1.0):
+            raise ValueError("threshold must be between 0 and 1")
+
+        try:
+            # Generate embedding for the query
+            logger.debug(f"Generating embedding for query: '{query[:50]}...'")
+            query_embedding = self.embedding_service.embed_text(query.strip())
+
+            # Perform vector similarity search
+            logger.debug(f"Searching vector database with top_k={top_k}")
+            raw_results = self.vector_db.search(
+                query_embedding=query_embedding, top_k=top_k
+            )
+
+            # Format and filter results
+            formatted_results = self._format_search_results(raw_results, threshold)
+
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+            return formatted_results
+
+        except Exception as e:
+            logger.error(f"Search failed for query '{query}': {str(e)}")
+            raise
+
+    def _format_search_results(
+        self, raw_results: List[Dict[str, Any]], threshold: float
+    ) -> List[Dict[str, Any]]:
+        """
+        Format VectorDatabase results into standardized search result format.
+
+        Args:
+            raw_results: Results from VectorDatabase.search()
+            threshold: Minimum similarity score threshold
+
+        Returns:
+            List of formatted search results
+        """
+        formatted_results = []
+
+        # Process each result from VectorDatabase format
+        for result in raw_results:
+            # Convert distance to similarity score (higher is better)
+            distance = result.get("distance", 1.0)
+            similarity_score = 1.0 - distance
+
+            # Apply threshold filtering
+            if similarity_score >= threshold:
+                formatted_result = {
+                    "chunk_id": result.get("id", ""),
+                    "content": result.get("document", ""),
+                    "similarity_score": similarity_score,
+                    "metadata": result.get("metadata", {}),
+                }
+                formatted_results.append(formatted_result)
+
+        logger.debug(
+            f"Formatted {len(formatted_results)} results above threshold {threshold}"
+        )
+        return formatted_results

tests/test_search/__init__.py

@@ -0,0 +1 @@
+"""Tests for search module."""

tests/test_search/test_search_service.py

@@ -0,0 +1,333 @@
+"""
+Tests for SearchService - Semantic document search functionality.
+
+This test suite covers:
+- SearchService initialization and configuration
+- Query embedding generation
+- Similarity search with ChromaDB integration
+- Result formatting and metadata handling
+- Error handling and edge cases
+- Performance and parameter validation
+"""
+
+import shutil
+import tempfile
+from unittest.mock import Mock
+
+import pytest
+
+from src.embedding.embedding_service import EmbeddingService
+from src.search.search_service import SearchService
+from src.vector_store.vector_db import VectorDatabase
+
+
+class TestSearchServiceInitialization:
+    """Test SearchService initialization and configuration."""
+
+    def test_search_service_initialization(self):
+        """Test that SearchService initializes correctly with required dependencies."""
+        mock_vector_db = Mock(spec=VectorDatabase)
+        mock_embedding_service = Mock(spec=EmbeddingService)
+
+        search_service = SearchService(
+            vector_db=mock_vector_db, embedding_service=mock_embedding_service
+        )
+
+        assert search_service.vector_db == mock_vector_db
+        assert search_service.embedding_service == mock_embedding_service
+
+    def test_search_service_with_none_dependencies(self):
+        """Test that SearchService raises appropriate error with None dependencies."""
+        with pytest.raises(ValueError, match="vector_db cannot be None"):
+            SearchService(vector_db=None, embedding_service=Mock())
+
+        with pytest.raises(ValueError, match="embedding_service cannot be None"):
+            SearchService(vector_db=Mock(), embedding_service=None)
+
+
+class TestSearchFunctionality:
+    """Test core search functionality."""
+
+    def setup_method(self):
+        """Set up test fixtures for search functionality tests."""
+        self.mock_vector_db = Mock(spec=VectorDatabase)
+        self.mock_embedding_service = Mock(spec=EmbeddingService)
+        self.search_service = SearchService(
+            vector_db=self.mock_vector_db, embedding_service=self.mock_embedding_service
+        )
+
+    def test_search_with_valid_query(self):
+        """Test search functionality with a valid text query."""
+        # Mock embedding generation
+        mock_embedding = [0.1, 0.2, 0.3, 0.4]
+        self.mock_embedding_service.embed_text.return_value = mock_embedding
+
+        # Mock vector database search results (VectorDatabase format)
+        mock_raw_results = [
+            {
+                "id": "doc_1",
+                "document": "Remote work policy content...",
+                "distance": 0.15,
+                "metadata": {"filename": "remote_work_policy.md", "chunk_index": 2},
+            },
+            {
+                "id": "doc_2",
+                "document": "PTO policy content...",
+                "distance": 0.25,
+                "metadata": {"filename": "pto_policy.md", "chunk_index": 1},
+            },
+        ]
+        self.mock_vector_db.search.return_value = mock_raw_results
+
+        # Perform search
+        results = self.search_service.search("remote work policy", top_k=2)
+
+        # Verify embedding service was called
+        self.mock_embedding_service.embed_text.assert_called_once_with(
+            "remote work policy"
+        )
+
+        # Verify vector database search was called
+        self.mock_vector_db.search.assert_called_once_with(
+            query_embedding=mock_embedding, top_k=2
+        )
+
+        # Verify results structure
+        assert len(results) == 2
+        assert results[0]["chunk_id"] == "doc_1"
+        assert results[0]["content"] == "Remote work policy content..."
+        assert results[0]["similarity_score"] == pytest.approx(
+            0.85, abs=0.01
+        )  # 1 - 0.15
+        assert results[0]["metadata"]["filename"] == "remote_work_policy.md"
+
+    def test_search_with_empty_query(self):
+        """Test search behavior with empty query string."""
+        with pytest.raises(ValueError, match="Query cannot be empty"):
+            self.search_service.search("")
+
+        with pytest.raises(ValueError, match="Query cannot be empty"):
+            self.search_service.search("   ")  # whitespace only
+
+    def test_search_with_no_results(self):
+        """Test search behavior when no results are found."""
+        # Mock embedding generation
+        mock_embedding = [0.1, 0.2, 0.3, 0.4]
+        self.mock_embedding_service.embed_text.return_value = mock_embedding
+
+        # Mock empty search results (VectorDatabase format)
+        mock_raw_results = []
+        self.mock_vector_db.search.return_value = mock_raw_results
+
+        # Perform search
+        results = self.search_service.search("non-existent topic")
+
+        # Verify empty results
+        assert results == []
+
+    def test_search_with_top_k_parameter(self):
+        """Test search with different top_k values."""
+        mock_embedding = [0.1, 0.2, 0.3, 0.4]
+        self.mock_embedding_service.embed_text.return_value = mock_embedding
+
+        # Mock results for top_k=1 (VectorDatabase format)
+        mock_raw_results = [
+            {
+                "id": "doc_1",
+                "document": "Content 1",
+                "distance": 0.15,
+                "metadata": {"filename": "file1.md", "chunk_index": 0},
+            }
+        ]
+        self.mock_vector_db.search.return_value = mock_raw_results
+
+        # Test with top_k=1
+        results = self.search_service.search("test query", top_k=1)
+        self.mock_vector_db.search.assert_called_with(
+            query_embedding=mock_embedding, top_k=1
+        )
+        assert len(results) == 1
+
+        # Test with top_k=10
+        self.search_service.search("test query", top_k=10)
+        self.mock_vector_db.search.assert_called_with(
+            query_embedding=mock_embedding, top_k=10
+        )
+
+    def test_search_with_threshold_filtering(self):
+        """Test search with similarity threshold filtering."""
+        # Mock embedding generation
+        mock_embedding = [0.1, 0.2, 0.3, 0.4]
+        self.mock_embedding_service.embed_text.return_value = mock_embedding
+
+        # Mock results with varying distances (VectorDatabase format)
+        mock_raw_results = [
+            {
+                "id": "doc_1",
+                "document": "High match",
+                "distance": 0.1,  # similarity: 0.9
+                "metadata": {"filename": "file1.md", "chunk_index": 0},
+            },
+            {
+                "id": "doc_2",
+                "document": "Medium match",
+                "distance": 0.5,  # similarity: 0.5
+                "metadata": {"filename": "file2.md", "chunk_index": 0},
+            },
+            {
+                "id": "doc_3",
+                "document": "Low match",
+                "distance": 0.8,  # similarity: 0.2
+                "metadata": {"filename": "file3.md", "chunk_index": 0},
+            },
+        ]
+        self.mock_vector_db.search.return_value = mock_raw_results
+
+        # Search with threshold=0.4 (should return only first two results)
+        results = self.search_service.search("test query", top_k=5, threshold=0.4)
+
+        # Verify only results above threshold are returned
+        assert len(results) == 2
+        assert results[0]["similarity_score"] == pytest.approx(0.9, abs=0.01)
+        assert results[1]["similarity_score"] == pytest.approx(0.5, abs=0.01)
+
+
+class TestErrorHandling:
+    """Test error handling and edge cases."""
+
+    def setup_method(self):
+        """Set up test fixtures for error handling tests."""
+        self.mock_vector_db = Mock(spec=VectorDatabase)
+        self.mock_embedding_service = Mock(spec=EmbeddingService)
+        self.search_service = SearchService(
+            vector_db=self.mock_vector_db, embedding_service=self.mock_embedding_service
+        )
+
+    def test_search_with_embedding_service_error(self):
+        """Test search behavior when embedding service fails."""
+        # Mock embedding service to raise an exception
+        self.mock_embedding_service.embed_text.side_effect = RuntimeError(
+            "Embedding model failed"
+        )
+
+        with pytest.raises(RuntimeError, match="Embedding model failed"):
+            self.search_service.search("test query")
+
+    def test_search_with_vector_db_error(self):
+        """Test search behavior when vector database fails."""
+        # Mock successful embedding but failed vector search
+        self.mock_embedding_service.embed_text.return_value = [0.1, 0.2, 0.3]
+        self.mock_vector_db.search.side_effect = RuntimeError(
+            "Vector DB connection failed"
+        )
+
+        with pytest.raises(RuntimeError, match="Vector DB connection failed"):
+            self.search_service.search("test query")
+
+    def test_search_with_invalid_parameters(self):
+        """Test search with invalid parameter values."""
+        with pytest.raises(ValueError, match="top_k must be positive"):
+            self.search_service.search("query", top_k=0)
+
+        with pytest.raises(ValueError, match="top_k must be positive"):
+            self.search_service.search("query", top_k=-1)
+
+        with pytest.raises(ValueError, match="threshold must be between 0 and 1"):
+            self.search_service.search("query", threshold=-0.1)
+
+        with pytest.raises(ValueError, match="threshold must be between 0 and 1"):
+            self.search_service.search("query", threshold=1.1)
+
+
+class TestIntegrationWithRealComponents:
+    """Test SearchService integration with real VectorDatabase and EmbeddingService."""
+
+    def setup_method(self):
+        """Set up real components for integration testing."""
+        # Create temporary directory for ChromaDB
+        self.temp_dir = tempfile.mkdtemp()
+
+        # Initialize real components
+        self.embedding_service = EmbeddingService()
+        self.vector_db = VectorDatabase(
+            persist_path=self.temp_dir, collection_name="test_collection"
+        )
+        self.search_service = SearchService(
+            vector_db=self.vector_db, embedding_service=self.embedding_service
+        )
+
+    def teardown_method(self):
+        """Clean up temporary directory."""
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def test_search_integration_with_real_data(self):
+        """Test search functionality with real embedding and vector storage."""
+        # Add some test documents to the vector database
+        test_texts = [
+            "Remote work policy allows employees to work from home",
+            "Employee benefits include health insurance and vacation time",
+            "Code of conduct requires professional behavior at all times",
+        ]
+        test_metadatas = [
+            {"filename": "remote_work.md", "chunk_index": 0},
+            {"filename": "benefits.md", "chunk_index": 0},
+            {"filename": "conduct.md", "chunk_index": 0},
+        ]
+
+        # Generate embeddings and store in vector database
+        embeddings = []
+        for text in test_texts:
+            embedding = self.embedding_service.embed_text(text)
+            embeddings.append(embedding)
+
+        # Add to vector database using the bulk add_embeddings method
+        chunk_ids = [f"doc_{i}" for i in range(len(test_texts))]
+        self.vector_db.add_embeddings(
+            embeddings=embeddings,
+            chunk_ids=chunk_ids,
+            documents=test_texts,
+            metadatas=test_metadatas,
+        )
+
+        # Test search functionality
+        results = self.search_service.search("work from home", top_k=2)
+
+        # Verify results
+        assert len(results) > 0
+        assert "chunk_id" in results[0]
+        assert "content" in results[0]
+        assert "similarity_score" in results[0]
+        assert "metadata" in results[0]
+
+        # Verify similarity scores are reasonable
+        for result in results:
+            assert 0.0 <= result["similarity_score"] <= 1.0
+
+        # Verify results are ordered by similarity (highest first)
+        if len(results) > 1:
+            assert results[0]["similarity_score"] >= results[1]["similarity_score"]
+
+    def test_search_quality_validation(self):
+        """Test that search returns relevant results for policy queries."""
+        # This is a simplified test to verify basic search functionality
+        # More complex relevance testing can be done in manual/integration testing
+
+        # Add a simple test document
+        test_text = "Remote work policy allows employees to work from home"
+        embedding = self.embedding_service.embed_text(test_text)
+
+        # Store document in vector database
+        self.vector_db.add_embeddings(
+            embeddings=[embedding],
+            chunk_ids=["test_doc"],
+            documents=[test_text],
+            metadatas=[{"filename": "test.md", "chunk_index": 0}],
+        )
+
+        # Verify we can search and get results
+        results = self.search_service.search("remote work", top_k=1)
+
+        # Basic validation
+        assert len(results) > 0
+        assert results[0]["chunk_id"] == "test_doc"
+        assert 0.0 <= results[0]["similarity_score"] <= 1.0