Merge pull request lightspeed-core#946 from tisnik/updated-docstrings-in-models-responses

LCORE-1092: Updated docstrings in models/responses

Author: tisnik

tests/unit/models/responses/test_authorized_response.py

@@ -21,7 +21,16 @@ def test_constructor(self) -> None:
         assert ar.skip_userid_check is True
 
     def test_constructor_fields_required(self) -> None:
-        """Test the AuthorizedResponse constructor."""
+        """Test the AuthorizedResponse constructor.
+
+        Verify that constructing AuthorizedResponse without required fields
+        raises ValidationError.
+
+        Checks three cases where a ValidationError is expected:
+        - no parameters provided
+        - missing `user_id`
+        - missing `username`
+        """
         with pytest.raises(ValidationError):
             # missing all parameters
             _ = AuthorizedResponse()  # pyright: ignore

tests/unit/models/responses/test_error_responses.py

@@ -61,7 +61,14 @@ def test_different_resource_types(self) -> None:
         )
 
     def test_openapi_response(self) -> None:
-        """Test BadRequestResponse.openapi_response() method."""
+        """Test BadRequestResponse.openapi_response() method.
+
+        Verify that BadRequestResponse.openapi_response() produces an OpenAPI
+        entry with the correct description, model reference, and JSON examples,
+        and that the examples list matches the model schema's examples and
+        contains a `conversation_id` example whose detail.response equals
+        "Invalid conversation ID format".
+        """
         schema = BadRequestResponse.model_json_schema()
         model_examples = schema.get("examples", [])
         expected_count = len(model_examples)
@@ -86,7 +93,16 @@ def test_openapi_response(self) -> None:
         )
 
     def test_openapi_response_with_explicit_examples(self) -> None:
-        """Test BadRequestResponse.openapi_response() with explicit examples."""
+        """Test BadRequestResponse.openapi_response() with explicit examples.
+
+        Verify BadRequestResponse.openapi_response returns only the specified
+        example when explicit example labels are provided.
+
+        Asserts that calling
+        BadRequestResponse.openapi_response(examples=["conversation_id"])
+        produces application/json examples containing exactly one entry with
+        the key "conversation_id".
+        """
         result = BadRequestResponse.openapi_response(examples=["conversation_id"])
         examples = result["content"]["application/json"]["examples"]
 
@@ -204,7 +220,11 @@ def test_factory_endpoint(self) -> None:
         )
 
     def test_factory_feedback_disabled(self) -> None:
-        """Test ForbiddenResponse.feedback_disabled() factory method."""
+        """Test ForbiddenResponse.feedback_disabled() factory method.
+
+        Verifies that ForbiddenResponse.feedback_disabled() produces a 403
+        AbstractErrorResponse with the expected detail message and cause.
+        """
         response = ForbiddenResponse.feedback_disabled()
         assert isinstance(response, AbstractErrorResponse)
         assert response.status_code == status.HTTP_403_FORBIDDEN

tests/unit/models/responses/test_rag_chunk.py

@@ -14,7 +14,14 @@ def test_constructor_with_content_only(self) -> None:
         assert chunk.score is None
 
     def test_constructor_with_all_fields(self) -> None:
-        """Test RAGChunk constructor with all fields."""
+        """Test RAGChunk constructor with all fields.
+
+        Verify that providing content, source, and score assigns those values
+        to the RAGChunk instance.
+
+        Asserts that the chunk's `content`, `source`, and `score` fields equal
+        the values passed to the constructor.
+        """
         chunk = RAGChunk(
             content="Kubernetes is an open-source container orchestration system",
             source="kubernetes-docs/overview.md",
@@ -66,7 +73,14 @@ def test_empty_content(self) -> None:
         assert chunk.score is None
 
     def test_multiline_content(self) -> None:
-        """Test RAGChunk with multiline content."""
+        """Test RAGChunk with multiline content.
+
+        Verify that a RAGChunk preserves multiline content and stores the
+        provided source and score.
+
+        Asserts that the chunk's `content` equals the original multiline
+        string, `source` equals "docs/multiline.md", and `score` equals 0.88.
+        """
         multiline_content = """This is a multiline content
         that spans multiple lines
         and contains various information."""