# thiswillbeyourgithub/ankiaiutils architecture

> Architecture diagram of the GitHub repository thiswillbeyourgithub/ankiaiutils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiswillbeyourgithub/ankiaiutils
- Repository: https://github.com/thiswillbeyourgithub/ankiaiutils

## Overview

##### High-Level Architecture Overview

a. Core Components Layer:
- Input Processing (Anki cards via AnkiConnect)
- AI Services Integration (LLMs via LiteLLM)
- Storage & Persistence (SQLite/JSON for history)
- Output Processing (Card modifications)

b. Tool Modules Layer:
- Illustrator
- Reformulator
- Mnemonics Creator
- Explainer
- Mnemonics Helper

##### Key Relationships to Highlight

a. Data Flow:
- How cards are selected using Anki queries
- Parallel processing capabilities
- Demonstrate how results are written back to Anki

b. Shared Components:
- Utils package usage across tools
- Dataset handling
- LLM integration
- Logging system

##### Specific Implementation Details

- Blue rectangles: Core tools (Illustrator, Reformulator, etc.)
- Green ovals: External services (OpenAI, Anthropic, etc.)
- Yellow diamonds: Decision points (card selection, processing rules)
- Gray rectangles: Utility modules

##### Component Details

a. Utils Package (Bottom Layer):
- utils/
- anki.py (AnkiConnect interface)
- cloze_utils.py (Cloze handling)
- datasets.py (Training data management)
- llm.py (LLM integration)
- logger.py (Logging system)
- misc.py (Utilities)
- shared.py (Shared functions)

b. Tool Modules (Middle Layer):
- illustrator.py
- reformulator.py
- mnemonics_creator.py
- explainer.py
- mnemonics_helper.py

c. Examples & Configuration (Top Layer):
- Dataset files
- Configuration files
- Example outputs

##### Key Workflows to Illustrate

a. Card Processing Pipeline:
1. Query Selection → Card Retrieval
2. Content Analysis → Dataset Matching
3. LLM Processing → Result Generation
4. Card Update → Sync

b. Error Handling:
- Failed processing paths
- Rollback mechanisms
- Logging points

##### Integration Points

Connections with:
- Anki (via AnkiConnect)
- LLM providers (via LiteLLM)
- Local storage
- Notification systems (ntfy.sh)

##### Deployment View

A small section showing:
- Local execution environment
- Required external services
- Synchronization with Anki clients

Remember to maintain a balance between showing enough detail to understand the system's complexity while keeping it clear and readable. The focus should be on how the components work together to enhance Anki cards through various AI-powered improvements.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Core Components Layer"
        direction TB
        Input["Input Processing"]:::core
        AIServices["AI Services Integration"]:::core
        Storage["Storage & Persistence"]:::core
        Output["Output Processing"]:::core
    end

    subgraph "Tool Modules Layer"
        direction TB
        Illustrator["Illustrator"]:::tool
        Reformulator["Reformulator"]:::tool
        MnemonicsCreator["Mnemonics Creator"]:::tool
        Explainer["Explainer"]:::tool
        MnemonicsHelper["Mnemonics Helper"]:::tool
    end

    subgraph "External Services"
        direction TB
        Anki["Anki via AnkiConnect"]:::external
        LLMs["LLM Providers via LiteLLM"]:::external
        Notify["Notification System\n(ntfy.sh)"]:::external
    end

    subgraph "Utils Package"
        direction TB
        AnkiUtils["AnkiConnect Interface"]:::util
        LLMUtils["LLM Integration"]:::util
        DatasetUtils["Dataset Management"]:::util
        ClozeUtils["Cloze Processing"]:::util
        Logger["Logging System"]:::util
        SharedUtils["Shared Functions"]:::util
        MiscUtils["Miscellaneous Utils"]:::util
    end

    subgraph "Storage & Examples"
        direction TB
        Datasets["Training Datasets"]:::storage
        Config["Configuration Files"]:::storage
        Examples["Example Outputs"]:::storage
    end

    %% Core Layer Relationships
    Input --> AIServices
    AIServices --> Storage
    Storage --> Output
    Output --> Input

    %% Tool Module Relationships
    Input --> Illustrator & Reformulator & MnemonicsCreator & Explainer & MnemonicsHelper
    Illustrator & Reformulator & MnemonicsCreator & Explainer & MnemonicsHelper --> Output

    %% External Service Connections
    Anki <--> Input
    Anki <--> Output
    AIServices <--> LLMs
    Output --> Notify

    %% Utils Package Usage
    AnkiUtils --> Input
    AnkiUtils --> Output
    LLMUtils --> AIServices
    DatasetUtils --> Storage
    ClozeUtils --> Input
    ClozeUtils --> Output
    Logger --> AIServices
    SharedUtils --> Input & Output & AIServices & Storage
    MiscUtils --> Input & Output & AIServices & Storage

    %% Storage Connections
    Datasets --> DatasetUtils
    Config --> SharedUtils
    Examples --> DatasetUtils

    %% Click Events
    click AnkiUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/anki.py"
    click LLMUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/llm.py"
    click DatasetUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/datasets.py"
    click ClozeUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/cloze_utils.py"
    click Logger "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/logger.py"
    click SharedUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/shared.py"
    click MiscUtils "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/utils/misc.py"
    click Illustrator "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/illustrator.py"
    click Reformulator "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/reformulator.py"
    click MnemonicsCreator "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/mnemonics_creator.py"
    click Explainer "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/explainer.py"
    click MnemonicsHelper "https://github.com/thiswillbeyourgithub/AnkiAIUtils/blob/public/mnemonics_helper.py"
    click Datasets "https://github.com/thiswillbeyourgithub/AnkiAIUtils/tree/public/examples/"
    click Examples "https://github.com/thiswillbeyourgithub/AnkiAIUtils/tree/public/examples/"

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef tool fill:#90EE90,stroke:#333,stroke-width:2px
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef storage fill:#FFD700,stroke:#333,stroke-width:2px
```
