feat: implement search API endpoint (Issue #22)

- Add POST /search endpoint with comprehensive validation
- Integrate with SearchService for semantic search
- Support query, top_k, and threshold parameters
- Return formatted JSON responses with results
- Add 8 comprehensive test cases covering all scenarios
- Include proper error handling and HTTP status codes
- Follow RESTful API conventions
- Update gitignore to exclude ChromaDB data files

Tests: 11/11 Flask tests passing (8 new search tests)
CI/CD: All formatting checks passing
API Contract: Accepts JSON requests, returns structured results

app.py

@@ -70,5 +70,100 @@ def ingest():
         return jsonify({"status": "error", "message": str(e)}), 500
 
 
+@app.route("/search", methods=["POST"])
+def search():
+    """
+    Endpoint to perform semantic search on ingested documents.
+
+    Accepts JSON requests with query text and optional parameters.
+    Returns semantically similar document chunks.
+    """
+    try:
+        # Validate request contains JSON data
+        if not request.is_json:
+            return (
+                jsonify(
+                    {
+                        "status": "error",
+                        "message": "Content-Type must be application/json",
+                    }
+                ),
+                400,
+            )
+
+        data = request.get_json()
+
+        # Validate required query parameter
+        query = data.get("query")
+        if query is None:
+            return (
+                jsonify({"status": "error", "message": "Query parameter is required"}),
+                400,
+            )
+
+        if not isinstance(query, str) or not query.strip():
+            return (
+                jsonify(
+                    {"status": "error", "message": "Query must be a non-empty string"}
+                ),
+                400,
+            )
+
+        # Extract optional parameters with defaults
+        top_k = data.get("top_k", 5)
+        threshold = data.get("threshold", 0.3)
+
+        # Validate parameters
+        if not isinstance(top_k, int) or top_k <= 0:
+            return (
+                jsonify(
+                    {"status": "error", "message": "top_k must be a positive integer"}
+                ),
+                400,
+            )
+
+        if not isinstance(threshold, (int, float)) or not (0.0 <= threshold <= 1.0):
+            return (
+                jsonify(
+                    {
+                        "status": "error",
+                        "message": "threshold must be a number between 0 and 1",
+                    }
+                ),
+                400,
+            )
+
+        # Initialize search components
+        from src.config import COLLECTION_NAME, VECTOR_DB_PERSIST_PATH
+        from src.embedding.embedding_service import EmbeddingService
+        from src.search.search_service import SearchService
+        from src.vector_store.vector_db import VectorDatabase
+
+        vector_db = VectorDatabase(VECTOR_DB_PERSIST_PATH, COLLECTION_NAME)
+        embedding_service = EmbeddingService()
+        search_service = SearchService(vector_db, embedding_service)
+
+        # Perform search
+        results = search_service.search(
+            query=query.strip(), top_k=top_k, threshold=threshold
+        )
+
+        # Format response
+        response = {
+            "status": "success",
+            "query": query.strip(),
+            "results_count": len(results),
+            "results": results,
+        }
+
+        return jsonify(response)
+
+    except ValueError as e:
+        return jsonify({"status": "error", "message": str(e)}), 400
+
+    except Exception as e:
+        return jsonify({"status": "error", "message": f"Search failed: {str(e)}"}), 500
+
+
 if __name__ == "__main__":
     app.run(debug=True)

tests/test_app.py

@@ -1,3 +1,5 @@
+import json
+
 import pytest
 
 from app import app as flask_app
@@ -38,3 +40,123 @@ def test_ingest_endpoint_exists():
     response = client.post("/ingest")
     # Should not be 404 (not found)
     assert response.status_code != 404
+
+
+class TestSearchEndpoint:
+    """Test cases for the /search endpoint"""
+
+    def test_search_endpoint_valid_request(self, client):
+        """Test search endpoint with valid request"""
+        request_data = {"query": "remote work policy", "top_k": 3, "threshold": 0.3}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        assert data["status"] == "success"
+        assert data["query"] == "remote work policy"
+        assert "results_count" in data
+        assert "results" in data
+        assert isinstance(data["results"], list)
+
+    def test_search_endpoint_minimal_request(self, client):
+        """Test search endpoint with minimal request (only query)"""
+        request_data = {"query": "employee benefits"}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        assert data["status"] == "success"
+        assert data["query"] == "employee benefits"
+
+    def test_search_endpoint_missing_query(self, client):
+        """Test search endpoint with missing query parameter"""
+        request_data = {"top_k": 5}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 400
+        data = response.get_json()
+
+        assert data["status"] == "error"
+        assert "Query parameter is required" in data["message"]
+
+    def test_search_endpoint_empty_query(self, client):
+        """Test search endpoint with empty query"""
+        request_data = {"query": ""}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 400
+        data = response.get_json()
+
+        assert data["status"] == "error"
+        assert "non-empty string" in data["message"]
+
+    def test_search_endpoint_invalid_top_k(self, client):
+        """Test search endpoint with invalid top_k parameter"""
+        request_data = {"query": "test query", "top_k": -1}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 400
+        data = response.get_json()
+
+        assert data["status"] == "error"
+        assert "positive integer" in data["message"]
+
+    def test_search_endpoint_invalid_threshold(self, client):
+        """Test search endpoint with invalid threshold parameter"""
+        request_data = {"query": "test query", "threshold": 1.5}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 400
+        data = response.get_json()
+
+        assert data["status"] == "error"
+        assert "between 0 and 1" in data["message"]
+
+    def test_search_endpoint_non_json_request(self, client):
+        """Test search endpoint with non-JSON request"""
+        response = client.post("/search", data="not json", content_type="text/plain")
+
+        assert response.status_code == 400
+        data = response.get_json()
+
+        assert data["status"] == "error"
+        assert "application/json" in data["message"]
+
+    def test_search_endpoint_result_structure(self, client):
+        """Test that search results have the correct structure"""
+        request_data = {"query": "policy"}
+
+        response = client.post(
+            "/search", data=json.dumps(request_data), content_type="application/json"
+        )
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        if data["results_count"] > 0:
+            result = data["results"][0]
+            assert "chunk_id" in result
+            assert "content" in result
+            assert "similarity_score" in result
+            assert "metadata" in result
+            assert isinstance(result["similarity_score"], (int, float))