refactor: improve session state management and enhance card interpretation logic

- Added session state checks to initialize cards, deck, and interpreter only once.
- Updated the CardInterpreter to use a global pipeline for efficiency.
- Introduced a new rules module for better content management in interpretations.
- Enhanced the get_cards function with clearer comments and removed unnecessary print statements.
- Updated requirements to include the 'watchdog' package.

app.py

@@ -13,13 +13,19 @@ base_dir = os.path.dirname(os.path.abspath(__file__))
 data_dir = os.path.join(base_dir, "data")
 json_file = os.path.join(data_dir, "tarot-images.json")
 
-
-get_cards()
+if 'initialized' not in st.session_state:
+    get_cards()
+    st.session_state.initialized = True
 
 # Initialize deck and interpreter
-deck = TarotDeck()
-deck.get_cards()
-interpreter = CardInterpreter()
+if 'deck' not in st.session_state:
+    deck = TarotDeck()
+    deck.get_cards()
+    st.session_state.deck = deck
+
+if 'interpreter' not in st.session_state:
+    interpreter = CardInterpreter()
+    st.session_state.interpreter = interpreter
 
 st.set_page_config(page_title="Tarot Reading", page_icon="🔮", layout="centered")
 
@@ -43,8 +49,6 @@ with st.sidebar:
         #     index=0
         # )
 
-reversed_prob -= 1
-
 # User interface texts
 welcome_text = "### Welcome to your Tarot Reading"
 instructions_text = (
@@ -84,10 +88,10 @@ context = st.text_area(context_text, placeholder=context_placeholder)
 if st.button(draw_button):
     # Shuffle and draw cards
     with st.spinner(spinner_texts["shuffle"]):
-        deck.shuffle(reversed_prob)
+        st.session_state.deck.shuffle(reversed_prob)
 
     with st.spinner(spinner_texts["channel"]):
-        cards = deck.draw(CardReadingMethod(method))
+        cards = st.session_state.deck.draw(CardReadingMethod(method))
 
     # Display cards
     st.markdown(spinner_texts["cards"])
@@ -111,11 +115,11 @@ if st.button(draw_button):
     # Generate and display interpretation
     with st.spinner(spinner_texts["consult"]):
         if context:
-            interpretation = interpreter.generate_interpretation(
+            interpretation = st.session_state.interpreter.generate_interpretation(
                 cards, context, CardReadingMethod(method)
             )
         else:
-            interpretation = interpreter.generate_interpretation(
+            interpretation = st.session_state.interpreter.generate_interpretation(
                 cards, None, CardReadingMethod(method)
             )
 

modules/llm/card_interpreter.py

@@ -1,54 +1,42 @@
 import os
 from typing import Dict, List, Optional
 
-from huggingface_hub import login
+from huggingface_hub import HfFolder, login
 from transformers import pipeline
 
 from modules.utils.commom import Card, CardReadingMethod
 
 from ..interfaces.llm_interface import CardInterpreterInterface
+from .rules import content
 
+PIPELINE = None
 
-class CardInterpreter(CardInterpreterInterface):
-    def __init__(self) -> None:
-        # Login to Hugging Face
-        hf_token = os.getenv("HF_TOKEN")
-        login(token=hf_token)
-        # Initialize pipeline with smaller model and CPU
-        self.pipeline = pipeline(
+
+def get_pipeline():
+    global PIPELINE
+    if PIPELINE is None:
+        PIPELINE = pipeline(
             "text-generation",
-            model="TinyLlama/TinyLlama-1.1B-Chat-v1.0",
-            device_map="cpu", # Force CPU for HF Spaces compatibility
+            model="meta-llama/Llama-3.2-1B-Instruct",
+            device_map="auto",
             pad_token_id=2,
-            model_kwargs={
-                "low_cpu_mem_usage": False,
-                "use_cache": False 
-            }
+            model_kwargs={"low_cpu_mem_usage": True, "use_cache": False},
         )
-        # Base prompt template
-        self._base_content = """
-        You are a powerful occultist and exceptional tarot reader. Provide a concise reading based on the given cards.
+    return PIPELINE
 
-        Focus on Rider Waite Tarot symbolism and card imagery.
 
-        The possible methods are:
-            - PAST_PRESENT_FUTURE: Three cards, past, present and future;
-            - CELTIC_CROSS: Ten cards, the situation, challenges, what to focus on, your past, your strengths, near future, suggested approach, what you need to know, your hopes and fears, and outcomes;
-            - HAND_OF_ERIS: Five cards, about your question, what may help you, what may hinder you, possible outcome number 1, and possible outcome number 2;
+class CardInterpreter(CardInterpreterInterface):
+    def __init__(self) -> None:
+        # Login to Hugging Face
+        hf_token = os.getenv("HF_TOKEN")
+        if not HfFolder.get_token():
+            login(token=hf_token)
 
-        Reading Guidelines:
-            - Keep answers brief and focused;
-            - Provide a summary overview;
-            - Only interpret reversed cards when specified;
-            - With context: Focus on context-specific interpretation;
-            - Without context: Give practical daily guidance;
+        # Initialize pipeline
+        self.pipeline = get_pipeline()
 
-        If other context is provided:
-            - Focus on the context provided;
-            - Provide a reading related to the context;
-            - Focus primarily on interpreting within the given context
-            - Keep the symbolism of the cards first, but make sure to use the context to interpret the cards.
-        """
+        # Base prompt template
+        self._base_content = content
 
     def _format_card(self, card: Card) -> str:
         # Format card name with reversed state
@@ -63,7 +51,6 @@ class CardInterpreter(CardInterpreterInterface):
                 Present: {self._format_card(cards[1])}
                 Future: {self._format_card(cards[2])}
             """,
-            
             CardReadingMethod.CELTIC_CROSS: lambda: f"""The provided cards are:
                 The situation: {self._format_card(cards[0])}
                 Challenges: {self._format_card(cards[1])}
@@ -76,22 +63,23 @@ class CardInterpreter(CardInterpreterInterface):
                 Your hopes and fears: {self._format_card(cards[8])}
                 Outcomes: {self._format_card(cards[9])}
             """,
-            
             CardReadingMethod.HAND_OF_ERIS: lambda: f"""The provided cards are:
                 About your question: {self._format_card(cards[0])}
                 What may help you: {self._format_card(cards[1])}
                 What may hinder you: {self._format_card(cards[2])}
                 Possible outcome number 1: {self._format_card(cards[3])}
                 Possible outcome number 2: {self._format_card(cards[4])}
-            """
+            """,
         }
 
         question = method_templates[method]()
-        question += f"\nIn the context of: {context}\nDrawn with the method: {method.value}"
+        question += (
+            f"\nIn the context of: {context}\nDrawn with the method: {method.value}"
+        )
 
         return [
             {"role": "system", "content": self._base_content},
-            {"role": "user", "content": question}
+            {"role": "user", "content": question},
         ]
 
     def generate_interpretation(
@@ -99,8 +87,8 @@ class CardInterpreter(CardInterpreterInterface):
     ) -> str:
         prompt = self.generate_prompt(cards, context or "General reading", method)
         result = self.pipeline(
-            prompt, 
-            max_new_tokens=256,  # Reduced token limit for faster inference
+            prompt,
+            max_new_tokens=512,
             num_return_sequences=1,
             do_sample=False,
         )

modules/llm/rules.py

@@ -0,0 +1,23 @@
+content = """
+        You are a masterful tarot reader with deep esoteric knowledge. Provide an insightful and focused reading based on the drawn cards.
+
+        Reading Guidelines:
+            - Keep answers brief and focused;
+            - Provide a summary overview at the end;
+            - Only interpret reversed cards when specified;
+            - With context: Focus on context-specific interpretation;
+            - Without context: Give practical daily guidance;
+            - Do not mention the method name in the reading overview;
+            - Be direct and concise.
+
+        If other context is provided:
+            - Focus on the context provided;
+            - Provide a reading related to the context;
+            - Focus primarily on interpreting within the given context
+            - Keep the symbolism of the cards first, but make sure to use the context to interpret the cards.
+
+        Focus on Rider Waite Tarot symbolism and card imagery.
+        Format example:
+            1. Cards meaning;
+            2. If the context is provided, give a practical and short guidance;
+            3. Reading overview."""

requirements.txt

@@ -57,3 +57,4 @@ transformers==4.47.1
 typing_extensions==4.12.2
 tzdata==2024.2
 urllib3==2.3.0
+watchdog==2.3.1

scripts/get_cards.py

@@ -27,41 +27,28 @@ def get_cards():
         with open(zip_file, "wb") as f:
             f.write(response.content)
 
-        # Extrair e renomear se necessário
+        # Extract and rename if necessary
         with zipfile.ZipFile(zip_file, "r") as zip_ref:
-            # Listar conteúdo do ZIP
+            # List all files in the ZIP
             files = zip_ref.namelist()
             json_files = [f for f in files if f.endswith(".json")]
 
-            print(f"Arquivos encontrados no ZIP: {files}")
-            print(f"Arquivos JSON encontrados: {json_files}")
-
             if json_files:
-                # Extrair todos os arquivos
+                # Extract all files
                 zip_ref.extractall(data_dir)
 
-                # Renomear o primeiro arquivo JSON encontrado para tarot-images.json
                 old_path = os.path.join(data_dir, json_files[0])
                 new_path = os.path.join(data_dir, "tarot-images.json")
-                print(f"Renomeando de {old_path} para {new_path}")
 
                 if old_path != new_path:
                     if os.path.exists(old_path):
                         os.rename(old_path, new_path)
-                    else:
-                        print(f"ERRO: Arquivo original {old_path} não encontrado!")
+
             else:
                 raise Exception("No JSON file found in the ZIP archive")
 
         os.remove(zip_file)
 
-        # Verificar se o arquivo final existe
-        if os.path.exists(new_path):
-            print(f"Arquivo final encontrado em: {new_path}")
-        else:
-            print(f"ERRO: Arquivo final não encontrado em: {new_path}")
-
-        print("Files downloaded and extracted successfully!")
 
     except Exception as e:
         print(f"Error downloading/extracting files: {e}")