API Reference.md - himent12/FlashGenie GitHub Wiki

📚 FlashGenie API Reference

Complete technical documentation for FlashGenie's classes, methods, and interfaces. This reference provides comprehensive coverage of the public API for developers building integrations, extensions, or contributing to the core codebase.

🎯 API Overview

FlashGenie's API is organized into several key modules:

Core Classes: Fundamental flashcard and deck management
Smart Features: Intelligent learning algorithms
Data Management: Storage and persistence
User Interface: CLI and interaction components
Utilities: Helper functions and tools

🧠 Core Classes

Flashcard

The fundamental unit of learning in FlashGenie.

from flashgenie.core.flashcard import Flashcard

Constructor

Flashcard(
    question: str,
    answer: str,
    tags: Optional[List[str]] = None,
    difficulty: float = 1.0,
    metadata: Optional[Dict[str, Any]] = None
)

Parameters:

question (str): The question text
answer (str): The answer text
tags (List[str], optional): List of tags for categorization
difficulty (float, optional): Difficulty level (0.1-5.0), defaults to 1.0
metadata (Dict[str, Any], optional): Additional metadata

Properties

Property	Type	Description
`id`	str	Unique identifier
`question`	str	Question text
`answer`	str	Answer text
`tags`	List[str]	Associated tags
`difficulty`	float	Current difficulty level
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp
`review_count`	int	Number of times reviewed
`correct_count`	int	Number of correct answers
`last_reviewed`	datetime	Last review timestamp

Methods

`add_tag(tag: str) -> None`

Add a tag to the flashcard.

`remove_tag(tag: str) -> bool`

Remove a tag from the flashcard. Returns True if tag was found and removed.

`update_difficulty(new_difficulty: float) -> None`

Update the difficulty level (clamped between 0.1 and 5.0).

`record_review(correct: bool) -> None`

Record a review attempt and update statistics.

`get_success_rate() -> float`

Calculate the success rate as a percentage.

`to_dict() -> Dict[str, Any]`

Convert flashcard to dictionary representation.

`from_dict(data: Dict[str, Any]) -> Flashcard`

Create flashcard from dictionary (class method).

Deck

Container for managing collections of flashcards.

from flashgenie.core.deck import Deck

Constructor

Deck(
    name: str,
    description: str = "",
    flashcards: Optional[List[Flashcard]] = None,
    metadata: Optional[Dict[str, Any]] = None
)

Properties

Property	Type	Description
`id`	str	Unique identifier
`name`	str	Deck name
`description`	str	Deck description
`flashcards`	List[Flashcard]	List of flashcards
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp
`total_cards`	int	Total number of cards
`tags`	Set[str]	All unique tags in deck

Methods

`add_card(flashcard: Flashcard) -> None`

Add a flashcard to the deck.

`remove_card(card_id: str) -> bool`

Remove a flashcard by ID. Returns True if found and removed.

`get_card(card_id: str) -> Optional[Flashcard]`

Retrieve a flashcard by ID.

`get_cards_by_tag(tag: str) -> List[Flashcard]`

Get all cards with a specific tag.

`get_cards_by_difficulty(min_diff: float, max_diff: float) -> List[Flashcard]`

Get cards within a difficulty range.

`shuffle_cards() -> None`

Randomly shuffle the order of flashcards.

`get_statistics() -> Dict[str, Any]`

Get comprehensive deck statistics.

🤖 Smart Features

QuizEngine

Manages quiz sessions and intelligent question selection.

from flashgenie.core.quiz_engine import QuizEngine, QuizSession

Constructor

QuizEngine(
    difficulty_analyzer: Optional[DifficultyAnalyzer] = None,
    spaced_repetition: Optional[SpacedRepetitionAlgorithm] = None
)

Methods

`start_session(deck: Deck, config: Optional[QuizConfig] = None) -> QuizSession`

Start a new quiz session.

`resume_session(session_id: str) -> QuizSession`

Resume a previously saved session.

QuizSession

Represents an active quiz session.

Properties

Property	Type	Description
`session_id`	str	Unique session identifier
`deck`	Deck	Associated deck
`current_card`	Optional[Flashcard]	Current flashcard
`score`	int	Current score
`total_questions`	int	Total questions answered
`correct_answers`	int	Number of correct answers
`start_time`	datetime	Session start time

Methods

`get_next_card() -> Optional[Flashcard]`

Get the next card based on intelligent selection.

`submit_answer(answer: str, confidence: float = 1.0) -> bool`

Submit an answer and get correctness feedback.

`skip_card() -> None`

Skip the current card.

`end_session() -> Dict[str, Any]`

End the session and return summary statistics.

DifficultyAnalyzer

Analyzes performance and adjusts card difficulty intelligently.

from flashgenie.core.difficulty_analyzer import DifficultyAnalyzer

Methods

`analyze_performance(card: Flashcard, responses: List[Dict]) -> Dict[str, float]`

Analyze performance metrics for a card.

`suggest_difficulty_adjustment(performance: Dict[str, float]) -> float`

Suggest difficulty adjustment based on performance.

`update_card_difficulty(card: Flashcard, performance: Dict[str, float]) -> None`

Update card difficulty based on analysis.

SpacedRepetitionAlgorithm

Implements the SM-2 spaced repetition algorithm.

from flashgenie.core.spaced_repetition import SpacedRepetitionAlgorithm

Methods

`calculate_next_review(card: Flashcard, quality: int) -> datetime`

Calculate when a card should next be reviewed.

`update_card_schedule(card: Flashcard, quality: int) -> None`

Update the card's review schedule.

💾 Data Management

DataStorage

Handles persistence and data management.

from flashgenie.data.storage import DataStorage

Methods

`save_deck(deck: Deck) -> bool`

Save a deck to persistent storage.

`load_deck(deck_id: str) -> Optional[Deck]`

Load a deck from storage.

`list_decks() -> List[Dict[str, str]]`

List all available decks.

`delete_deck(deck_id: str) -> bool`

Delete a deck from storage.

`backup_data(backup_path: str) -> bool`

Create a backup of all data.

`restore_data(backup_path: str) -> bool`

Restore data from a backup.

Importers

CSVImporter

from flashgenie.data.importers.csv_importer import CSVImporter

`import_from_file(file_path: str, config: Optional[Dict] = None) -> List[Flashcard]`

Import flashcards from CSV file.

TXTImporter

from flashgenie.data.importers.txt_importer import TXTImporter

`import_from_file(file_path: str, config: Optional[Dict] = None) -> List[Flashcard]`

Import flashcards from text file.

Exporters

CSVExporter

from flashgenie.data.exporters.csv_exporter import CSVExporter

`export_deck(deck: Deck, file_path: str) -> bool`

Export deck to CSV format.

JSONExporter

from flashgenie.data.exporters.json_exporter import JSONExporter

`export_deck(deck: Deck, file_path: str) -> bool`

Export deck to JSON format.

🎯 Usage Examples

Basic Usage

from flashgenie import Flashcard, Deck, QuizEngine, DifficultyAnalyzer

# Create flashcards
card1 = Flashcard("What is Python?", "A programming language")
card2 = Flashcard("What is ML?", "Machine Learning")

# Create deck
deck = Deck("Programming Basics", flashcards=[card1, card2])

# Initialize quiz engine
analyzer = DifficultyAnalyzer()
quiz_engine = QuizEngine(analyzer)

# Start quiz session
session = quiz_engine.start_session(deck)

# Quiz loop
while session.has_more_cards():
    card = session.get_next_card()
    print(f"Question: {card.question}")
    
    user_answer = input("Your answer: ")
    is_correct = session.submit_answer(user_answer)
    
    print("Correct!" if is_correct else f"Wrong. Answer: {card.answer}")

# Get session results
results = session.end_session()
print(f"Score: {results['score']}/{results['total']}")

Advanced Usage with Smart Features

from flashgenie import (
    Deck, QuizEngine, DifficultyAnalyzer,
    TagManager, SmartCollectionManager
)

# Create deck with tagged cards
deck = Deck("Advanced Topics")
deck.add_card(Flashcard("Define polymorphism", "...", tags=["OOP", "concepts"]))
deck.add_card(Flashcard("Explain inheritance", "...", tags=["OOP", "basics"]))

# Initialize smart features
tag_manager = TagManager()
collection_manager = SmartCollectionManager()
analyzer = DifficultyAnalyzer()

# Auto-categorize cards
tag_manager.auto_tag_deck(deck)

# Create smart collections
collection_manager.create_collection("Struggling Cards", {
    "difficulty_min": 3.0,
    "success_rate_max": 0.6
})

# Use smart collections
struggling_cards = collection_manager.get_collection("Struggling Cards")
cards = collection_manager.get_collection_cards(struggling_cards, deck)
print(f"Found {len(cards)} struggling cards")

Data Management

from flashgenie.data.storage import DataStorage
from flashgenie.data.importers.csv_importer import CSVImporter

# Initialize storage
storage = DataStorage()

# Import from CSV
importer = CSVImporter()
cards = importer.import_from_file("my_cards.csv")

# Create and save deck
deck = Deck("Imported Deck", flashcards=cards)
storage.save_deck(deck)

# List all decks
decks = storage.list_decks()
for deck_info in decks:
    print(f"Deck: {deck_info['name']} ({deck_info['card_count']} cards)")

🔧 Configuration

Environment Variables

Variable	Description	Default
`FLASHGENIE_DATA_DIR`	Data directory path	`./data`
`FLASHGENIE_LOG_LEVEL`	Logging level	`INFO`
`FLASHGENIE_CONFIG_FILE`	Config file path	`./config.json`

Configuration File

{
  "spaced_repetition": {
    "initial_interval": 1,
    "easy_factor": 2.5,
    "minimum_factor": 1.3
  },
  "quiz": {
    "max_questions_per_session": 50,
    "case_sensitive": false
  },
  "ui": {
    "use_colors": true,
    "clear_screen": true
  }
}

🚨 Error Handling

Custom Exceptions

from flashgenie.utils.exceptions import (
    FlashGenieError,
    DeckNotFoundError,
    CardNotFoundError,
    ImportError,
    ExportError
)

FlashGenieError

Base exception for all FlashGenie errors.

DeckNotFoundError

Raised when a requested deck cannot be found.

CardNotFoundError

Raised when a requested card cannot be found.

ImportError

Raised when import operations fail.

ExportError

Raised when export operations fail.

🔌 Extension Points

FlashGenie is designed for extensibility. Key extension points include:

Custom Algorithms

from flashgenie.core.difficulty_analyzer import DifficultyAnalyzer

class MyCustomAnalyzer(DifficultyAnalyzer):
    def analyze_performance(self, card, responses):
        # Your custom analysis logic
        return performance_metrics

    def suggest_difficulty_adjustment(self, performance):
        # Your custom adjustment logic
        return difficulty_change

Custom Importers

from flashgenie.data.importers.base_importer import BaseImporter

class MyCustomImporter(BaseImporter):
    def import_from_file(self, file_path, config=None):
        # Your custom import logic
        return flashcards

Custom Exporters

from flashgenie.data.exporters.base_exporter import BaseExporter

class MyCustomExporter(BaseExporter):
    def export_deck(self, deck, file_path):
        # Your custom export logic
        return success

📊 Performance Considerations

Memory Usage

Decks are loaded entirely into memory
Large decks (>10,000 cards) may impact performance
Consider pagination for very large datasets

Storage

Data is stored in JSON format by default
File I/O operations are synchronous
Consider async operations for large datasets

Optimization Tips

Use smart collections to filter large decks
Implement custom algorithms for specific use cases
Cache frequently accessed data

This API reference is automatically updated with each release. For the latest version, see the GitHub repository.