Add /api/v2/ayah-claude endpoint using AnsariClaude

waleedkadous · waleedkadous · commit 143674b4a33b · 2025-08-15T23:24:28.000-07:00
- New endpoint with same features as /api/v2/ayah but using AnsariClaude
- Maintains API key authentication with QURAN_DOT_COM_API_KEY
- Uses ayah-specific system prompt for specialized responses
- Implements database caching for responses
- Supports augment_question parameter for enhanced queries
- Includes comprehensive unit tests
diff --git a/src/ansari/app/main_api.py b/src/ansari/app/main_api.py
@@ -1078,3 +1078,93 @@ async def answer_ayah_question(
     except Exception:
         logger.error("Error in answer_ayah_question", exc_info=True)
         raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@app.post("/api/v2/ayah-claude")
+async def answer_ayah_question_claude(
+    req: AyahQuestionRequest,
+    settings: Settings = Depends(get_settings),
+    db: AnsariDB = Depends(lambda: AnsariDB(get_settings())),
+):
+    """Answer questions about specific Quranic verses using AnsariClaude.
+    
+    This endpoint provides similar functionality to /api/v2/ayah but uses AnsariClaude
+    for more advanced reasoning and citation capabilities while maintaining:
+    - API key authentication
+    - Ayah-specific system prompt
+    - Database caching for responses
+    - Tafsir search with ayah filtering
+    """
+    if req.apikey != settings.QURAN_DOT_COM_API_KEY.get_secret_value():
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    
+    try:
+        ayah_id = req.surah * 1000 + req.ayah
+        
+        # Check if the answer is already stored in the database
+        if req.use_cache:
+            stored_answer = db.get_quran_answer(req.surah, req.ayah, req.question)
+            if stored_answer:
+                return {"response": stored_answer}
+        
+        # Create AnsariClaude instance with ayah-specific system prompt
+        logger.debug(f"Creating AnsariClaude instance for {req.surah}:{req.ayah}")
+        
+        # Load the ayah-specific system prompt
+        system_prompt_path = os.path.join(
+            os.path.dirname(__file__), 
+            "..", 
+            "system_prompts",
+            settings.AYAH_SYSTEM_PROMPT_FILE_NAME
+        )
+        
+        with open(system_prompt_path, "r") as f:
+            ayah_system_prompt = f.read()
+        
+        # Initialize AnsariClaude with the ayah-specific system prompt
+        ansari_claude = AnsariClaude(
+            settings,
+            system_prompt=ayah_system_prompt,
+            source_type=SourceType.WEB  # Using WEB for now, could add QURAN_COM if needed
+        )
+        
+        # Prepare the context with ayah information
+        ayah_context = f"Question about Surah {req.surah}, Ayah {req.ayah}"
+        
+        # Build the search query with metadata filter for the specific ayah
+        search_context = {
+            "tool_name": "search_tafsir",
+            "metadata_filter": f"part.from_ayah_int<={ayah_id} AND part.to_ayah_int>={ayah_id}",
+        }
+        
+        # Create a message that includes the context and triggers appropriate searches
+        enhanced_question = f"{ayah_context}\n\n{req.question}"
+        
+        # If augment_question is enabled, add instructions for query enhancement
+        if req.augment_question:
+            enhanced_question += "\n\nPlease search relevant tafsir sources and provide a comprehensive answer."
+        
+        # Prepare messages for AnsariClaude
+        messages = [
+            {
+                "role": "user",
+                "content": enhanced_question
+            }
+        ]
+        
+        # Generate response using AnsariClaude
+        response_generator = ansari_claude.replace_message_history(messages)
+        
+        # Collect the full response (since we need to return JSON, not stream)
+        full_response = ""
+        for chunk in response_generator:
+            full_response += chunk
+        
+        # Store the answer in the database
+        db.store_quran_answer(req.surah, req.ayah, req.question, full_response)
+        
+        return {"response": full_response}
+        
+    except Exception as e:
+        logger.error(f"Error in answer_ayah_question_claude: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail="Internal server error")
diff --git a/tests/unit/test_ayah_claude_endpoint.py b/tests/unit/test_ayah_claude_endpoint.py
@@ -0,0 +1,291 @@
+"""Unit tests for the /api/v2/ayah-claude endpoint."""
+
+import pytest
+from fastapi.testclient import TestClient
+from unittest.mock import MagicMock, patch, mock_open
+import json
+
+
+@pytest.fixture
+def client():
+    """Create a test client for the FastAPI app."""
+    from src.ansari.app.main_api import app
+    return TestClient(app)
+
+
+@pytest.fixture
+def mock_settings():
+    """Mock settings with test API key."""
+    with patch("src.ansari.app.main_api.get_settings") as mock:
+        settings = MagicMock()
+        settings.QURAN_DOT_COM_API_KEY.get_secret_value.return_value = "test-api-key"
+        settings.AYAH_SYSTEM_PROMPT_FILE_NAME = "ayah_system_prompt.md"
+        settings.MONGO_URL = "mongodb://test:27017"
+        settings.MONGO_DB_NAME = "test_db"
+        mock.return_value = settings
+        yield settings
+
+
+@pytest.fixture  
+def mock_db():
+    """Mock database for testing."""
+    with patch("src.ansari.app.main_api.AnsariDB") as mock_class:
+        db_instance = MagicMock()
+        db_instance.get_quran_answer = MagicMock()
+        db_instance.store_quran_answer = MagicMock()
+        mock_class.return_value = db_instance
+        yield db_instance
+
+
+@pytest.fixture
+def mock_ansari_claude():
+    """Mock AnsariClaude for testing."""
+    with patch("src.ansari.app.main_api.AnsariClaude") as mock:
+        instance = MagicMock()
+        # Mock the generator response
+        def mock_generator():
+            yield "This is a test response "
+            yield "about the ayah "
+            yield "with citations."
+        instance.replace_message_history.return_value = mock_generator()
+        mock.return_value = instance
+        yield mock
+
+
+class TestAyahClaudeEndpoint:
+    """Test cases for the /api/v2/ayah-claude endpoint."""
+
+    def test_endpoint_exists(self, client):
+        """Test that the endpoint is registered."""
+        response = client.post(
+            "/api/v2/ayah-claude",
+            json={
+                "surah": 1,
+                "ayah": 1,
+                "question": "What is the meaning?",
+                "apikey": "wrong-key"
+            }
+        )
+        # Should not return 404
+        assert response.status_code != 404
+
+    def test_authentication_required(self, client, mock_settings):
+        """Test that API key authentication is enforced."""
+        # Test with wrong API key
+        response = client.post(
+            "/api/v2/ayah-claude",
+            json={
+                "surah": 1,
+                "ayah": 1,
+                "question": "What is the meaning?",
+                "apikey": "wrong-api-key"
+            }
+        )
+        assert response.status_code == 401
+        assert response.json()["detail"] == "Unauthorized"
+
+    def test_successful_request_with_valid_key(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test successful request with valid API key."""
+        # Mock the file reading for system prompt
+        with patch("builtins.open", mock_open(read_data="Test system prompt")):
+            # Mock that no cached answer exists
+            mock_db.get_quran_answer.return_value = None
+            
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 1,
+                    "ayah": 1,
+                    "question": "What is the meaning?",
+                    "apikey": "test-api-key",
+                    "use_cache": True
+                }
+            )
+            
+            assert response.status_code == 200
+            assert "response" in response.json()
+            assert response.json()["response"] == "This is a test response about the ayah with citations."
+
+    def test_cache_retrieval(self, client, mock_settings, mock_db):
+        """Test that cached answers are returned when available."""
+        # Mock a cached answer
+        cached_answer = "This is a cached response"
+        mock_db.get_quran_answer.return_value = cached_answer
+        
+        response = client.post(
+            "/api/v2/ayah-claude",
+            json={
+                "surah": 1,
+                "ayah": 1,
+                "question": "What is the meaning?",
+                "apikey": "test-api-key",
+                "use_cache": True
+            }
+        )
+        
+        assert response.status_code == 200
+        assert response.json()["response"] == cached_answer
+        # Verify that get_quran_answer was called
+        mock_db.get_quran_answer.assert_called_once_with(1, 1, "What is the meaning?")
+
+    def test_cache_disabled(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test that cache is bypassed when use_cache is False."""
+        with patch("builtins.open", mock_open(read_data="Test system prompt")):
+            # Even if cache has an answer, it shouldn't be used
+            mock_db.get_quran_answer.return_value = "Cached answer"
+            
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 2,
+                    "ayah": 255,
+                    "question": "Explain this verse",
+                    "apikey": "test-api-key",
+                    "use_cache": False
+                }
+            )
+            
+            assert response.status_code == 200
+            # Should not return cached answer
+            assert response.json()["response"] != "Cached answer"
+            # get_quran_answer should not be called when cache is disabled
+            mock_db.get_quran_answer.assert_not_called()
+
+    def test_augment_question_feature(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test that augment_question adds enhancement instructions."""
+        with patch("builtins.open", mock_open(read_data="Test system prompt")):
+            mock_db.get_quran_answer.return_value = None
+            
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 3,
+                    "ayah": 14,
+                    "question": "What does this mean?",
+                    "apikey": "test-api-key",
+                    "augment_question": True,
+                    "use_cache": False
+                }
+            )
+            
+            assert response.status_code == 200
+            # Verify that AnsariClaude was called
+            mock_ansari_claude.assert_called_once()
+            # Verify the message passed included enhancement
+            call_args = mock_ansari_claude.return_value.replace_message_history.call_args
+            messages = call_args[0][0]
+            assert "search relevant tafsir sources" in messages[0]["content"]
+
+    def test_database_storage(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test that responses are stored in the database."""
+        with patch("builtins.open", mock_open(read_data="Test system prompt")):
+            mock_db.get_quran_answer.return_value = None
+            
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 4,
+                    "ayah": 34,
+                    "question": "Explain the context",
+                    "apikey": "test-api-key",
+                    "use_cache": True
+                }
+            )
+            
+            assert response.status_code == 200
+            # Verify that store_quran_answer was called
+            mock_db.store_quran_answer.assert_called_once_with(
+                4, 34, "Explain the context", 
+                "This is a test response about the ayah with citations."
+            )
+
+    def test_ayah_specific_system_prompt(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test that ayah-specific system prompt is loaded."""
+        system_prompt_content = "Special ayah system prompt"
+        
+        with patch("builtins.open", mock_open(read_data=system_prompt_content)):
+            mock_db.get_quran_answer.return_value = None
+            
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 5,
+                    "ayah": 3,
+                    "question": "What is the significance?",
+                    "apikey": "test-api-key"
+                }
+            )
+            
+            assert response.status_code == 200
+            # Verify AnsariClaude was initialized with the system prompt
+            mock_ansari_claude.assert_called_once()
+            call_args = mock_ansari_claude.call_args
+            assert call_args[1]["system_prompt"] == system_prompt_content
+
+    def test_ayah_id_calculation(self, client, mock_settings, mock_db, mock_ansari_claude):
+        """Test that ayah_id is calculated correctly for tafsir filtering."""
+        with patch("builtins.open", mock_open(read_data="Test system prompt")):
+            mock_db.get_quran_answer.return_value = None
+            
+            # Test with Surah 2, Ayah 255 (Ayat al-Kursi)
+            # Expected ayah_id = 2 * 1000 + 255 = 2255
+            response = client.post(
+                "/api/v2/ayah-claude",
+                json={
+                    "surah": 2,
+                    "ayah": 255,
+                    "question": "Explain Ayat al-Kursi",
+                    "apikey": "test-api-key"
+                }
+            )
+            
+            assert response.status_code == 200
+            # The ayah_id should be used in the context
+            call_args = mock_ansari_claude.return_value.replace_message_history.call_args
+            messages = call_args[0][0]
+            assert "Surah 2, Ayah 255" in messages[0]["content"]
+
+    def test_error_handling(self, client, mock_settings, mock_db):
+        """Test that errors are handled gracefully."""
+        with patch("src.ansari.app.main_api.AnsariClaude") as mock_claude:
+            # Make AnsariClaude raise an exception
+            mock_claude.side_effect = Exception("Test error")
+            mock_db.get_quran_answer.return_value = None
+            
+            with patch("builtins.open", mock_open(read_data="Test system prompt")):
+                response = client.post(
+                    "/api/v2/ayah-claude",
+                    json={
+                        "surah": 1,
+                        "ayah": 1,
+                        "question": "Test question",
+                        "apikey": "test-api-key"
+                    }
+                )
+                
+                assert response.status_code == 500
+                assert response.json()["detail"] == "Internal server error"
+
+    def test_request_validation(self, client, mock_settings):
+        """Test that request validation works correctly."""
+        # Missing required fields
+        response = client.post(
+            "/api/v2/ayah-claude",
+            json={
+                "surah": 1,
+                # Missing ayah, question, and apikey
+            }
+        )
+        assert response.status_code == 422  # Unprocessable Entity
+
+        # Invalid data types
+        response = client.post(
+            "/api/v2/ayah-claude",
+            json={
+                "surah": "not-a-number",
+                "ayah": 1,
+                "question": "Test",
+                "apikey": "test-key"
+            }
+        )
+        assert response.status_code == 422
