feat: add AI-powered flashcard and collection generation

feat: add AI-powered flashcard and collection generation

---------

Co-authored-by: Sebastian <[email protected]>
Co-authored-by: Miguel Cobo <[email protected]>
Co-authored-by: ZorroGuardaPavos <[email protected]>

Author: 4 people

backend/.env.example

@@ -23,3 +23,4 @@ AI_MODEL=
 AI_API_KEY=
 
 COLLECTION_GENERATION_PROMPT="I want to generate flashcards on a specific topic for efficient studying. Please create a set of flashcards covering key concepts, definitions, important details, and examples, with a focus on progressively building understanding of the topic. The flashcards should aim to provide a helpful learning experience by using structured explanations, real-world examples and formatting. Each flashcard should follow this format: Front (Question/Prompt): A clear and concise question or term to test recall, starting with introductory concepts and moving toward more complex details. Back (Answer): If the front is a concept or topic, provide a detailed explanation, broken down into clear paragraphs with easy-to-understand language. If possible, include a real-world example, analogy or illustrative diagrams to make the concept more memorable and relatable. If the front is a vocabulary word (for language learning), provide a direct translation in the target language. Optional Hint: A short clue to aid recall, especially for more complex concepts. Important: Use valid Markdown format for the back of the flashcard."
+CARD_GENERATION_PROMPT="I want to generate a flashcard on a specific topic. The contents of the flashcard should provide helpful information that aim to help the learner retain the concepts given. The flashcard must follow this format: Front (Question/Prompt): A clear and concise question or term to test recall. Back (Answer): If the front is a concept or topic, provide a detailed explanation, broken down into clear paragraphs with easy-to-understand language. If possible, include a real-world example, analogy or illustrative diagrams to make the concept more memorable and relatable. If the front is a vocabulary word (for language learning), provide a direct translation in the target language. Important: Use valid Markdown format for the back of the flashcard."

backend/src/core/config.py

@@ -66,6 +66,7 @@ def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn:
     AI_MODEL: str | None = None
 
     COLLECTION_GENERATION_PROMPT: str | None = None
+    CARD_GENERATION_PROMPT: str | None = None
 
     @computed_field  # type: ignore[prop-decorator]
     @property

backend/src/flashcards/ai_config.py

@@ -4,6 +4,21 @@
 from src.core.config import settings
 
 
+def card_response_schema(schema_type):
+    return schema_type.Schema(
+        type=schema_type.Type.OBJECT,
+        required=["front", "back"],
+        properties={
+            "front": schema_type.Schema(
+                type=schema_type.Type.STRING,
+            ),
+            "back": schema_type.Schema(
+                type=schema_type.Type.STRING,
+            ),
+        },
+    )
+
+
 def collection_response_schema(schema_type):
     return schema_type.Schema(
         type=schema_type.Type.OBJECT,
@@ -18,18 +33,7 @@ def collection_response_schema(schema_type):
                     ),
                     "cards": schema_type.Schema(
                         type=schema_type.Type.ARRAY,
-                        items=schema_type.Schema(
-                            type=schema_type.Type.OBJECT,
-                            required=["front", "back"],
-                            properties={
-                                "front": schema_type.Schema(
-                                    type=schema_type.Type.STRING,
-                                ),
-                                "back": schema_type.Schema(
-                                    type=schema_type.Type.STRING,
-                                ),
-                            },
-                        ),
+                        items=card_response_schema(schema_type),
                     ),
                 },
             ),
@@ -42,3 +46,10 @@ def get_flashcard_config(schema_type) -> types.GenerateContentConfig:
         response_schema=collection_response_schema(schema_type),
         system_instruction=settings.COLLECTION_GENERATION_PROMPT,
     )
+
+
+def get_card_config(schema_type) -> types.GenerateContentConfig:
+    return create_content_config(
+        response_schema=card_response_schema(schema_type),
+        system_instruction=settings.CARD_GENERATION_PROMPT,
+    )

backend/src/flashcards/api.py

@@ -1,3 +1,4 @@
+import asyncio
 import uuid
 from typing import Any, Literal
 
@@ -46,25 +47,28 @@ async def create_collection(
     collection_in: CollectionCreate,
     provider: GeminiProviderDep,
 ) -> Any:
+    name = collection_in.name
+    cards = None
+
     if collection_in.prompt:
         try:
-            collection = await services.generate_ai_collection(
-                session=session,
-                user_id=current_user.id,
-                prompt=collection_in.prompt,
-                provider=provider,
+            flashcard_collection = await services.generate_ai_collection(
+                provider, collection_in.prompt
             )
-            return collection
+            name = flashcard_collection.name
+            cards = flashcard_collection.cards
         except EmptyCollectionError:
             raise HTTPException(
                 status_code=400, detail="Failed to generate flashcards from the prompt"
             )
         except AIGenerationError as e:
             raise HTTPException(status_code=500, detail=str(e))
-    else:
-        return services.create_collection(
-            session=session, collection_in=collection_in, user_id=current_user.id
+
+    return await asyncio.to_thread(
+        lambda: services.create_collection(
+            session=session, user_id=current_user.id, name=name, cards=cards
         )
+    )
 
 
 @router.get("/collections/{collection_id}", response_model=Collection)
@@ -126,16 +130,28 @@ def read_cards(
 
 
 @router.post("/collections/{collection_id}/cards/", response_model=Card)
-def create_card(
+async def create_card(
     session: SessionDep,
     current_user: CurrentUser,
     collection_id: uuid.UUID,
     card_in: CardCreate,
+    provider: GeminiProviderDep,
 ) -> Any:
-    if not services.check_collection_access(session, collection_id, current_user.id):
+    access_checked = await asyncio.to_thread(
+        lambda: services.check_collection_access(
+            session, collection_id, current_user.id
+        )
+    )
+    if not access_checked:
         raise HTTPException(status_code=404, detail="Collection not found")
-    return services.create_card(
-        session=session, collection_id=collection_id, card_in=card_in
+    if card_in.prompt:
+        card_base = await services.generate_ai_flashcard(card_in.prompt, provider)
+        card_in.front = card_base.front
+        card_in.back = card_base.back
+    return await asyncio.to_thread(
+        lambda: services.create_card(
+            session=session, collection_id=collection_id, card_in=card_in
+        )
     )
 
 

backend/src/flashcards/schemas.py

@@ -1,17 +1,16 @@
 import uuid
 from datetime import datetime
 
-from pydantic import BaseModel
-from pydantic import Field as PydanticField
-from sqlmodel import Field, SQLModel
+from pydantic import BaseModel, Field
+from sqlmodel import SQLModel
 
 
 class CollectionBase(SQLModel):
     name: str
 
 
 class CollectionCreate(CollectionBase):
-    prompt: str | None = None
+    prompt: str | None = Field(default=None, max_length=100)
 
 
 class CollectionUpdate(SQLModel):
@@ -24,7 +23,7 @@ class CardBase(SQLModel):
 
 
 class CardCreate(CardBase):
-    pass
+    prompt: str | None = Field(default=None, max_length=100)
 
 
 class CardUpdate(CardBase):
@@ -110,17 +109,13 @@ class PracticeCardResponse(SQLModel):
     is_correct: bool | None
 
 
-class AIFlashcardsRequest(SQLModel):
-    prompt: str = Field(max_length=100)
-
-
 class AIFlashcard(BaseModel):
     front: str
     back: str
 
 
 class AIFlashcardCollection(BaseModel):
-    name: str = PydanticField(description="the simple name of the topic")
+    name: str
     cards: list[AIFlashcard]
 
 

backend/src/flashcards/services.py

@@ -10,14 +10,14 @@
 
 from src.ai_models.gemini.exceptions import AIGenerationError
 
-from .ai_config import get_flashcard_config
+from .ai_config import get_card_config, get_flashcard_config
 from .exceptions import EmptyCollectionError
 from .models import Card, Collection, PracticeCard, PracticeSession
 from .schemas import (
     AIFlashcardCollection,
+    CardBase,
     CardCreate,
     CardUpdate,
-    CollectionCreate,
     CollectionUpdate,
 )
 
@@ -48,11 +48,22 @@ def get_collection(
 
 
 def create_collection(
-    session: Session, collection_in: CollectionCreate, user_id: uuid.UUID
+    session: Session, user_id: uuid.UUID, name: str, cards: list[CardBase] | None = None
 ) -> Collection:
-    collection = Collection.model_validate(collection_in, update={"user_id": user_id})
-    collection.user_id = user_id
+    collection = Collection(name=name, user_id=user_id)
     session.add(collection)
+    session.flush()
+
+    if cards:
+        card_objs = [
+            Card(
+                front=card.front,
+                back=card.back,
+                collection_id=collection.id,
+            )
+            for card in cards
+        ]
+        session.add_all(card_objs)
     session.commit()
     session.refresh(collection)
     return collection
@@ -361,7 +372,7 @@ def get_card_by_id(session: Session, card_id: uuid.UUID) -> Card | None:
     return session.exec(statement).first()
 
 
-async def _generate_ai_flashcards(provider, prompt: str) -> AIFlashcardCollection:
+async def generate_ai_collection(provider, prompt: str) -> AIFlashcardCollection:
     content_config = get_flashcard_config(genai.types)
     raw_response = await provider.run_model(content_config, prompt)
 
@@ -382,33 +393,18 @@ async def _generate_ai_flashcards(provider, prompt: str) -> AIFlashcardCollectio
         raise AIGenerationError(f"Error processing AI response: {str(e)}")
 
 
-def _save_ai_collection(
-    session: Session, user_id: uuid.UUID, flashcard_collection: AIFlashcardCollection
-) -> Collection:
-    collection = Collection(
-        name=flashcard_collection.name,
-        user_id=user_id,
-    )
-    session.add(collection)
-    session.commit()
-    session.refresh(collection)
-
-    for card_data in flashcard_collection.cards:
-        card = Card(
-            front=card_data.front,
-            back=card_data.back,
-            collection_id=collection.id,
-        )
-        session.add(card)
-
-    session.commit()
-    session.refresh(collection)
-    return collection
-
-
-async def generate_ai_collection(
-    session: Session, user_id: uuid.UUID, prompt: str, provider
-) -> Collection:
-    """Generate a collection of flashcards using AI and save it to the database."""
-    flashcard_collection = await _generate_ai_flashcards(provider, prompt)
-    return _save_ai_collection(session, user_id, flashcard_collection)
+async def generate_ai_flashcard(prompt: str, provider) -> CardBase:
+    content_config = get_card_config(genai.types)
+    raw_response = await provider.run_model(content_config, prompt)
+    try:
+        json_data = json.loads(raw_response)
+        if "front" not in json_data or "back" not in json_data:
+            raise AIGenerationError("AI response missing 'front' or 'back' field")
+        card = CardBase(front=json_data["front"], back=json_data["back"])
+        return card
+    except json.JSONDecodeError:
+        raise AIGenerationError("Failed to parse AI response as JSON")
+    except ValidationError as e:
+        raise AIGenerationError(f"Invalid AI response format: {str(e)}")
+    except Exception as e:
+        raise AIGenerationError(f"Error processing AI response: {str(e)}")

backend/tests/flashcards/card/test_api.py

@@ -1,5 +1,6 @@
 import uuid
 from typing import Any
+from unittest.mock import ANY, AsyncMock, patch
 
 import pytest
 from fastapi.testclient import TestClient
@@ -380,3 +381,46 @@ def test_deleted_card_not_in_list(
     list_after = rsp.json()
     assert list_after["count"] == len(test_multiple_cards) - 1
     assert delete_card["id"] not in [card["id"] for card in list_after["data"]]
+
+
+def test_create_card_with_prompt_ai(
+    client: TestClient,
+    normal_user_token_headers: dict[str, str],
+    test_collection: dict[str, Any],
+):
+    collection_id = test_collection["id"]
+    prompt = "What is a closure in Python?"
+    ai_card = {"front": "What is a closure?", "back": "A closure is..."}
+    with patch(
+        "src.flashcards.services.generate_ai_flashcard", new_callable=AsyncMock
+    ) as mock_ai:
+        mock_ai.return_value = type("Card", (), ai_card)()
+        card_data = {"prompt": prompt, "front": "", "back": ""}
+        rsp = client.post(
+            f"{settings.API_V1_STR}/collections/{collection_id}/cards/",
+            json=card_data,
+            headers=normal_user_token_headers,
+        )
+        assert rsp.status_code == 200
+        content = rsp.json()
+        assert content["front"] == ai_card["front"]
+        assert content["back"] == ai_card["back"]
+        mock_ai.assert_called_once_with(prompt, ANY)
+
+
+def test_create_card_with_prompt_too_long(
+    client: TestClient,
+    normal_user_token_headers: dict[str, str],
+    test_collection: dict[str, Any],
+):
+    collection_id = test_collection["id"]
+    prompt = "x" * 101
+    card_data = {"prompt": prompt, "front": "", "back": ""}
+    rsp = client.post(
+        f"{settings.API_V1_STR}/collections/{collection_id}/cards/",
+        json=card_data,
+        headers=normal_user_token_headers,
+    )
+    assert rsp.status_code == 422
+    content = rsp.json()
+    assert "prompt" in str(content)

backend/tests/flashcards/collection/test_api.py

@@ -94,7 +94,12 @@ def test_create_collection_with_prompt(
         assert rsp.status_code == 200
         content = rsp.json()
         assert content["name"] == collection_data.name
-        assert content["id"] == str(mock_collection.id)
+        assert "id" in content
+        assert isinstance(content["id"], str)
+        assert len(content["cards"]) == len(mock_collection.cards)
+        for i, card in enumerate(mock_collection.cards):
+            assert content["cards"][i]["front"] == card.front
+            assert content["cards"][i]["back"] == card.back
 
         mock_ai_generate.assert_called_once()
 

backend/tests/flashcards/collection/test_services.py

@@ -4,7 +4,7 @@
 from sqlmodel import Session
 
 from src.flashcards.models import Collection
-from src.flashcards.schemas import CollectionCreate, CollectionUpdate
+from src.flashcards.schemas import CollectionUpdate
 from src.flashcards.services import (
     check_collection_access,
     create_collection,
@@ -16,15 +16,11 @@
 
 
 def test_create_collection(db: Session, test_user: dict[str, Any]):
-    collection_in = CollectionCreate(name="Test Collection")
     collection = create_collection(
-        session=db,
-        collection_in=collection_in,
-        user_id=test_user["id"],
+        session=db, user_id=test_user["id"], name="Test Collection"
     )
-
     assert collection.id is not None
-    assert collection.name == collection_in.name
+    assert collection.name == "Test Collection"
     assert collection.user_id == test_user["id"]
     assert collection.created_at is not None
     assert collection.updated_at is not None