feat: add base arcana functions

app.py

@@ -0,0 +1,103 @@
+import streamlit as st
+import yaml
+
+from modules.llm.card_interpreter import CardInterpreter
+from modules.tarot.card import TarotDeck
+from modules.utils.commom import CardReadingMethod, label4method
+
+# Initialize deck and interpreter
+deck = TarotDeck()
+deck.get_cards()
+interpreter = CardInterpreter()
+
+st.set_page_config(
+    page_title="Tarot Reading",
+    page_icon="🔮",
+    layout="centered"
+)
+
+st.title("🔮 Tarot Reading")
+
+# Secret configurations
+with st.sidebar:
+    with st.expander("⚙️ Settings", expanded=False):
+        reversed_prob = st.slider(
+            "Probability of reversed cards",
+            min_value=0.0,
+            max_value=1.0,
+            value=yaml.safe_load(open("config.yaml"))["reverse_probability"],
+            step=0.1,
+            help="Probability of a card appearing reversed (0.0 to 1.0)"
+        )
+        # TODO: Add Portuguese language support and translation
+        # language = st.selectbox(
+        #     "Language",
+        #     ["English", "Portuguese"],
+        #     index=0
+        # )
+
+reversed_prob -= 1
+
+# User interface texts
+welcome_text = "### Welcome to your Tarot Reading"
+instructions_text = "Please select a reading method and provide a context for your consultation."
+method_text = "Choose your reading method:"
+context_text = "What would you like to know about? (Optional)"
+context_placeholder = "Ex: I need guidance about finding my life purpose..."
+draw_button = "Draw Cards"
+spinner_texts = {
+    "shuffle": "🔮 Shuffling the cards with mystical energy...",
+    "channel": "✨ Channeling the energies of the universe...",
+    "reveal": "🌟 Revealing the secrets of destiny...",
+    "consult": "🧙‍♂️ Consulting ancient wisdom...",
+    "cards": "### Your Cards:",
+    "reading": "### Your Reading:",
+    "default_context": "General daily reading"
+}
+
+# Display welcome message and instructions
+st.markdown(welcome_text)
+st.markdown(instructions_text)
+
+# Reading method selection
+method = st.selectbox(
+    method_text,
+    [
+        CardReadingMethod.PAST_PRESENT_FUTURE.value,
+        CardReadingMethod.CELTIC_CROSS.value,
+        CardReadingMethod.HAND_OF_ERIS.value
+    ]
+)
+
+# Reading context input
+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)
+        
+    with st.spinner(spinner_texts["channel"]):
+        cards = deck.draw(CardReadingMethod(method))
+    
+    # Display cards
+    st.markdown(spinner_texts["cards"])
+    
+    cols = st.columns(len(cards))
+    for idx, (card, col) in enumerate(zip(cards, cols)):
+        with col:
+            with st.spinner(spinner_texts["reveal"]):
+                st.image(card.image_pth, caption=f"{label4method[CardReadingMethod(method)][idx]}: {card.name}")
+    
+    # Generate and display interpretation
+    with st.spinner(spinner_texts["consult"]):
+        if context:
+            interpretation = interpreter.generate_interpretation(cards, context, CardReadingMethod(method))
+        else:
+            interpretation = interpreter.generate_interpretation(cards, None, CardReadingMethod(method))
+    
+    st.markdown(spinner_texts["reading"])
+    st.write(interpretation)

config.yaml

@@ -0,0 +1,3 @@
+# Probability of reversed cards (0.0 to 1.0)
+reverse_probability: 0.3
+

modules/interfaces/llm_interface.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from modules.utils.commom import Card, CardReadingMethod
+
+
+class CardInterpreterInterface(ABC):
+    @abstractmethod
+    def generate_interpretation(self, cards: List[Card], context: Optional[str], method: CardReadingMethod) -> str:
+        ...
+
+    @abstractmethod
+    def generate_prompt(self, cards: List[Card], context: str, method: CardReadingMethod) -> List[Dict[str, str]]:
+        ...

modules/llm/card_interpreter.py

@@ -0,0 +1,103 @@
+from typing import Dict, List, Optional
+
+from transformers import pipeline
+
+from modules.utils.commom import Card, CardReadingMethod
+
+from ..interfaces.llm_interface import CardInterpreterInterface
+
+
+class CardInterpreter(CardInterpreterInterface):
+    def __init__(self) -> None:
+        # Initialize pipeline once and cache it
+        self.pipeline = pipeline(
+            "text-generation",
+            model="meta-llama/Llama-3.2-1B-Instruct",
+            device_map="auto", 
+            pad_token_id=128001,
+        )
+        
+        # Cache base prompt content that doesn't change
+        self._base_content = """
+        You are a powerful occultist and exceptional tarot reader. Provide a concise reading based on the given cards.
+
+        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;
+
+        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;
+
+        If the context is General reading:
+            - Provide a general daily life reading;
+            - Focus on practical matters;
+
+        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.
+        """
+
+    def _format_card(self, card: Card) -> str:
+        # Helper to format card name
+        return f"{card.name} (Reversed)" if card.reversed else card.name
+
+    def generate_prompt(
+        self, cards: List[Card], context: str, method: CardReadingMethod
+    ) -> List[Dict[str, str]]:
+        method_templates = {
+            CardReadingMethod.PAST_PRESENT_FUTURE: lambda: f"""The provided cards are:
+                Past: {self._format_card(cards[0])}
+                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])}
+                What to focus on: {self._format_card(cards[2])}
+                Your past: {self._format_card(cards[3])}
+                Your strengths: {self._format_card(cards[4])}
+                Near future: {self._format_card(cards[5])}
+                Suggested approach: {self._format_card(cards[6])}
+                What you need to know: {self._format_card(cards[7])}
+                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}"
+
+        return [
+            {"role": "system", "content": self._base_content},
+            {"role": "user", "content": question}
+        ]
+
+    def generate_interpretation(
+        self, cards: List[Card], context: Optional[str], method: CardReadingMethod
+    ) -> str:
+        prompt = self.generate_prompt(cards, context or "General reading", method)
+        result = self.pipeline(
+            prompt, 
+            max_new_tokens=512,  # Limit token generation
+            num_return_sequences=1,  # Only generate one response
+            do_sample=False  # Deterministic output
+        )
+        return result[0]["generated_text"][-1]["content"]

modules/tarot/card.py

@@ -0,0 +1,45 @@
+import json
+import random
+
+from ..utils.commom import Card, CardReadingMethod
+
+
+class TarotDeck:
+    def __init__(self):
+        with open("./data/tarot-images.json") as f:
+            self.cards_json = json.load(f)
+
+    def get_cards(self):
+        cards = []
+        for card_data in self.cards_json["cards"]:
+            name = card_data["name"]
+            number = int(card_data["number"])
+            is_major_arcana = card_data["arcana"]
+            image_pth = f"./data/cards/{card_data['img']}"
+
+            card = Card(
+                name=name,
+                number=number,
+                is_major_arcana=is_major_arcana,
+                image_pth=image_pth,
+            )
+            cards.append(card)
+
+        self.cards = cards
+
+    def shuffle(self, reversal_prob: float):
+        random.shuffle(self.cards)
+        for card in self.cards:
+            card.reversed = random.random() < reversal_prob
+
+        return self.cards
+
+    def draw(self, method: CardReadingMethod = CardReadingMethod.PAST_PRESENT_FUTURE):
+        if method == CardReadingMethod.PAST_PRESENT_FUTURE:
+            return self.cards[0:3]
+        elif method == CardReadingMethod.CELTIC_CROSS:
+            return self.cards[0:10]
+        elif method == CardReadingMethod.HAND_OF_ERIS:
+            return self.cards[0:5]
+        else:
+            raise ValueError(f"Invalid method: {method}")

modules/utils/commom.py

@@ -0,0 +1,50 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ArcanaType(str, Enum):
+    MAJOR = "Major Arcana"
+    MINOR = "Minor Arcana"
+
+
+class CardReadingMethod(str, Enum):
+    PAST_PRESENT_FUTURE = "past_present_future"
+    CELTIC_CROSS = "celtic_cross"
+    HAND_OF_ERIS = "hand_of_eris"
+
+
+label4method = {
+    CardReadingMethod.PAST_PRESENT_FUTURE: ["Past", "Present", "Future"],
+    CardReadingMethod.CELTIC_CROSS: [
+        "Situation",
+        "Potential/Challenges",
+        "Focus",
+        "Past",
+        "Possibilities",
+        "Near Future",
+        "Power",
+        "Environment",
+        "Hopes/Fears",
+        "Outcomes",
+    ],
+    CardReadingMethod.HAND_OF_ERIS: [
+        "About your question",
+        "What may help you",
+        "What may hinder you",
+        "Possible outcome number 1",
+        "Possible outcome number 2",
+    ],
+}
+
+
+class Card(BaseModel):
+    name: str
+    number: int
+    is_major_arcana: ArcanaType
+    reversed: bool = False
+    image_pth: str
+
+    @property
+    def is_major(self) -> bool:
+        return self.is_major_arcana == ArcanaType.MAJOR

scripts/get_cards.py

@@ -0,0 +1,28 @@
+import os
+import shutil
+import zipfile
+
+import requests
+
+
+def get_cards():
+    # Create data directory
+    os.makedirs('./data', exist_ok=True)
+    
+    # Download zip file
+    url = 'https://www.kaggle.com/api/v1/datasets/download/lsind18/tarot-json'
+    zip_file = './tarot-json.zip'
+    
+    response = requests.get(url)
+    with open(zip_file, 'wb') as f:
+        f.write(response.content)
+    
+    # Extract contents
+    with zipfile.ZipFile(zip_file, 'r') as zip_ref:
+        zip_ref.extractall('./data')
+    
+    # Remove zip file
+    os.remove(zip_file)
+
+if __name__ == '__main__':
+    get_cards()

test/test_inference.py

@@ -0,0 +1,12 @@
+from modules.llm.card_interpreter import CardInterpreter
+from utils.commom import Card
+
+cards = [
+    Card(name="The Fool", number=0, is_major_arcana=True, image_pth="", reversed=True),
+    Card(name="Five of Cups", number=5, is_major_arcana=False, image_pth="", reversed=False),
+    Card(name="The Lovers", number=6, is_major_arcana=False, image_pth="", reversed=False),
+    ]
+
+interpreter = CardInterpreter()
+response = interpreter.generate_interpretation(cards, "I'm feeling sad and lost")
+print(response)