Update

README.md

@@ -11,7 +11,7 @@ pinned: True
 
 # Welcome to Chessli2 🏰
 
-Chessli2 is your **always free** and **open-source** chess trainer 🛡️, designed to elevate your game by allowing you to analyze games, identify mistakes, and sharpen your tactics, all sourced directly from [lichess.org](https://lichess.org/).
+[Chessli2](https://github.com/pwenker/chessli2) is your **always free** and **open-source** chess trainer 🛡️, designed to elevate your game by allowing you to analyze games, identify mistakes, and sharpen your tactics, all sourced directly from [lichess.org](https://lichess.org/).
 
 ## Why a second version?
 
@@ -27,10 +27,50 @@ This overwhelming support has inspired me to develop a sleek new version of Ches
 
 Chessli2 is here to support your journey to becoming a chess master. Dive in and start enhancing your skills today! 🚀
 
-## Quickstart
+## Quickstart 🚀
 
-Try it directly out at [Huggingface Spaces](https://pwenker-chessli2.hf.space/).
+### 👉 Click here to try out the app directly:
+[**Chessli2**](https://pwenker-chessli2.hf.space/)
 
+### 🔍 Inspect code at:
+- **GitHub:** [pwenker/chessli2](https://github.com/pwenker/chessli2)
+- **Hugging Face Spaces:** [pwenker/chessli2](https://huggingface.co/spaces/pwenker/chessli2)
+
+
+## Local Deployment 🏠
+
+### Prerequisites 📋
+
+#### Rye 🌾
+[Install `Rye`](https://rye-up.com/guide/installation/#installing-rye)
+> Rye is a comprehensive tool designed for Python developers. It simplifies your workflow by managing Python installations and dependencies. Simply install Rye, and it takes care of the rest.
+
+### Set-Up 🛠️
+
+Clone the repository, e.g. with:
+```
+git clone https://github.com/pwenker/chessli2.git
+```
+Navigate to the directory:
+```
+cd chessli2
+```
+And execute:
+```
+rye sync
+```
+This creates a virtual environment in `.venv` and synchronizes the repo.
+
+For more details, visit: [Basics - Rye](https://rye-up.com/guide/basics/)
+
+### Start the App 🌟
+
+Launch the app using:
+```
+rye run python src/chessli2/app.py
+```
+
+Finally, open your browser and visit [http://localhost:7860](http://localhost:7860/) to start practicing!
 
 ## FAQ
 

app.py

@@ -1,5 +0,0 @@
-from src.chessli2.gui import demo
-
-
-if __name__ == "__main__":
-    demo.launch(show_error=True)

docs/puzzle_themes.md

@@ -0,0 +1,65 @@
+| Name                    | Description                                                                                                         |
+|-------------------------|---------------------------------------------------------------------------------------------------------------------|
+| Advanced pawn           | One of your pawns is deep into the opponent position, maybe threatening to promote.                                 |
+| Advantage               | Seize your chance to get a decisive advantage. (200cp ≤ eval ≤ 600cp)                                               |
+| Anastasia's mate        | A knight and rook or queen team up to trap the opposing king between the side of the board and a friendly piece.    |
+| Arabian mate            | A knight and a rook team up to trap the opposing king on a corner of the board.                                     |
+| Attacking f2 or f7      | An attack focusing on the f2 or f7 pawn, such as in the fried liver opening.                                        |
+| Attraction              | An exchange or sacrifice encouraging or forcing an opponent piece to a square that allows a follow-up tactic.       |
+| Back rank mate          | Checkmate the king on the home rank, when it is trapped there by its own pieces.                                    |
+| Bishop endgame          | An endgame with only bishops and pawns.                                                                             |
+| Boden's mate            | Two attacking bishops on criss-crossing diagonals deliver mate to a king obstructed by friendly pieces.             |
+| Castling                | Bring the king to safety, and deploy the rook for attack.                                                           |
+| Capture the defender    | Removing a piece that is critical to defence of another piece, allowing the now undefended piece to be captured on a following move. |
+| Crushing                | Spot the opponent blunder to obtain a crushing advantage. (eval ≥ 600cp)                                            |
+| Double bishop mate      | Two attacking bishops on adjacent diagonals deliver mate to a king obstructed by friendly pieces.                   |
+| Dovetail mate           | A queen delivers mate to an adjacent king, whose only two escape squares are obstructed by friendly pieces.         |
+| Equality                | Come back from a losing position, and secure a draw or a balanced position. (eval ≤ 200cp)                         |
+| Kingside attack         | An attack of the opponent's king, after they castled on the king side.                                             |
+| Clearance               | A move, often with tempo, that clears a square, file or diagonal for a follow-up tactical idea.                    |
+| Defensive move          | A precise move or sequence of moves that is needed to avoid losing material or another advantage.                  |
+| Deflection              | A move that distracts an opponent piece from another duty that it performs, such as guarding a key square. Sometimes also called "overloading". |
+| Discovered attack       | Moving a piece (such as a knight), that previously blocked an attack by a long range piece (such as a rook), out of the way of that piece. |
+| Double check            | Checking with two pieces at once, as a result of a discovered attack where both the moving piece and the unveiled piece attack the opponent's king. |
+| Endgame                 | A tactic during the last phase of the game.                                                                        |
+| En passant              | A tactic involving the en passant rule, where a pawn can capture an opponent pawn that has bypassed it using its initial two-square move. |
+| Exposed king            | A tactic involving a king with few defenders around it, often leading to checkmate.                                |
+| Fork                    | A move where the moved piece attacks two opponent pieces at once.                                                   |
+| Hanging piece           | A tactic involving an opponent piece being undefended or insufficiently defended and free to capture.               |
+| Hook mate               | Checkmate with a rook, knight, and pawn along with one enemy pawn to limit the enemy king's escape.                |
+| Interference            | Moving a piece between two opponent pieces to leave one or both opponent pieces undefended, such as a knight on a defended square between two rooks. |
+| Intermezzo              | Instead of playing the expected move, first interpose another move posing an immediate threat that the opponent must answer. Also known as "Zwischenzug" or "In between". |
+| Knight endgame          | An endgame with only knights and pawns.                                                                            |
+| Long                    | Three moves to win.                                                                                                |
+| Master games            | Puzzles from games played by titled players.                                                                       |
+| Master vs Master games  | Puzzles from games between two titled players.                                                                     |
+| Checkmate               | Win the game with style.                                                                                           |
+| Mate in 1               | Deliver checkmate in one move.                                                                                     |
+| Mate in 2               | Deliver checkmate in two moves.                                                                                    |
+| Mate in 3               | Deliver checkmate in three moves.                                                                                  |
+| Mate in 4               | Deliver checkmate in four moves.                                                                                   |
+| Mate in 5 or more       | Figure out a long mating sequence.                                                                                 |
+| Middlegame              | A tactic during the second phase of the game.                                                                      |
+| One-move puzzle         | A puzzle that is only one move long.                                                                               |
+| Opening                 | A tactic during the first phase of the game.                                                                       |
+| Pawn endgame            | An endgame with only pawns.                                                                                        |
+| Pin                     | A tactic involving pins, where a piece is unable to move without revealing an attack on a higher value piece.      |
+| Promotion               | Promote one of your pawn to a queen or minor piece.                                                                |
+| Queen endgame           | An endgame with only queens and pawns.                                                                             |
+| Queen and Rook          | An endgame with only queens, rooks and pawns.                                                                      |
+| Queenside attack        | An attack of the opponent's king, after they castled on the queen side.                                            |
+| Quiet move              | A move that does neither make a check or capture, nor an immediate threat to capture, but does prepare a more hidden unavoidable threat for a later move. |
+| Rook endgame            | An endgame with only rooks and pawns.                                                                              |
+| Sacrifice               | A tactic involving giving up material in the short-term, to gain an advantage again after a forced sequence of moves. |
+| Short                   | Two moves to win.                                                                                                  |
+| Skewer                  | A motif involving a high value piece being attacked, moving out the way, and allowing a lower value piece behind it to be captured or attacked, the inverse of a pin. |
+| Smothered mate          | A checkmate delivered by a knight in which the mated king is unable to move because it is surrounded (or smothered) by its own pieces. |
+| Super GM games          | Puzzles from games played by the best players in the world.                                                        |
+| Trapped piece           | A piece is unable to escape capture as it has limited moves.                                                       |
+| Underpromotion          | Promotion to a knight, bishop, or rook.                                                                            |
+| Very long               | Four moves or more to win.                                                                                         |
+| X-Ray attack            | A piece attacks or defends a square, through an enemy piece.                                                       |
+| Zugzwang                | The opponent is limited in the moves they can make, and all moves worsen their position.                           |
+| Healthy mix             | A bit of everything. You don't know what to expect, so you remain ready for anything! Just like in real games.    |
+| Player games            | Lookup puzzles generated from your games, or from another player's games.                                          |
+| Puzzle download information | These puzzles are in the public domain, and can be downloaded from %s.                                           |

pyproject.toml

@@ -13,12 +13,13 @@ dependencies = [
     "gradio_calendar>=0.0.4",
     "gradio>=4.29.0",
     "tabulate>=0.9.0",
+    "typer>=0.12.3",
 ]
 readme = "README.md"
-requires-python = ">= 3.10"
+requires-python = ">= 3.11"
 
 [project.scripts]
-chessli2 = "chessli2.main:app"
+chessli2 = "chessli2.cli:app"
 
 [build-system]
 requires = ["hatchling"]
@@ -26,7 +27,10 @@ build-backend = "hatchling.build"
 
 [tool.rye]
 managed = true
-dev-dependencies = []
+dev-dependencies = [
+    "pytest>=8.2.0",
+    "pytest-sugar>=1.0.0",
+]
 
 [tool.hatch.metadata]
 allow-direct-references = true

requirements-dev.lock

@@ -5,78 +5,233 @@
 #   pre: false
 #   features: []
 #   all-features: false
+#   with-sources: false
 
 -e file:.
 aiofiles==23.2.1
-altair==5.2.0
+    # via gradio
+altair==5.3.0
+    # via gradio
 annotated-types==0.6.0
-anyio==4.2.0
+    # via pydantic
+anyio==4.3.0
+    # via httpx
+    # via starlette
+    # via watchfiles
 attrs==23.2.0
+    # via jsonschema
+    # via referencing
 berserk==0.13.2
-certifi==2023.11.17
+    # via chessli2
+certifi==2024.2.2
+    # via httpcore
+    # via httpx
+    # via requests
 charset-normalizer==3.3.2
+    # via requests
 chess==1.10.0
+    # via chessli2
 click==8.1.7
+    # via typer
+    # via uvicorn
+contourpy==1.2.1
+    # via matplotlib
 cycler==0.12.1
+    # via matplotlib
 deprecated==1.2.14
-exceptiongroup==1.2.1
-fastapi==0.109.0
-ffmpy==0.3.1
-filelock==3.13.1
-fonttools==4.47.2
-fsspec==2023.12.2
-gradio==4.29.0
+    # via berserk
+dnspython==2.6.1
+    # via email-validator
+email-validator==2.1.1
+    # via fastapi
+fastapi==0.111.0
+    # via fastapi-cli
+    # via gradio
+fastapi-cli==0.0.3
+    # via fastapi
+ffmpy==0.3.2
+    # via gradio
+filelock==3.14.0
+    # via huggingface-hub
+fonttools==4.51.0
+    # via matplotlib
+fsspec==2024.3.1
+    # via gradio-client
+    # via huggingface-hub
+gradio==4.31.0
+    # via chessli2
+    # via gradio-calendar
 gradio-calendar==0.0.4
-gradio-client==0.16.1
+    # via chessli2
+gradio-client==0.16.2
+    # via gradio
 h11==0.14.0
-httpcore==1.0.2
-httpx==0.26.0
-huggingface-hub==0.20.2
-idna==3.6
-importlib-resources==6.1.1
-jinja2==3.1.3
-jsonschema==4.20.0
+    # via httpcore
+    # via uvicorn
+httpcore==1.0.5
+    # via httpx
+httptools==0.6.1
+    # via uvicorn
+httpx==0.27.0
+    # via fastapi
+    # via gradio
+    # via gradio-client
+huggingface-hub==0.23.0
+    # via gradio
+    # via gradio-client
+idna==3.7
+    # via anyio
+    # via email-validator
+    # via httpx
+    # via requests
+importlib-resources==6.4.0
+    # via gradio
+iniconfig==2.0.0
+    # via pytest
+jinja2==3.1.4
+    # via altair
+    # via fastapi
+    # via gradio
+jsonschema==4.22.0
+    # via altair
 jsonschema-specifications==2023.12.1
+    # via jsonschema
 kiwisolver==1.4.5
+    # via matplotlib
 markdown-it-py==3.0.0
-markupsafe==2.1.3
-matplotlib==3.5.3
+    # via rich
+markupsafe==2.1.5
+    # via gradio
+    # via jinja2
+matplotlib==3.8.4
+    # via gradio
 mdurl==0.1.2
+    # via markdown-it-py
 ndjson==0.3.1
-numpy==1.24.4
-orjson==3.9.10
-packaging==23.2
-pandas==2.0.3
-pillow==10.2.0
-pydantic==2.5.3
-pydantic-core==2.14.6
-pydantic-settings==2.1.0
+    # via berserk
+numpy==1.26.4
+    # via altair
+    # via contourpy
+    # via gradio
+    # via matplotlib
+    # via pandas
+orjson==3.10.3
+    # via fastapi
+    # via gradio
+packaging==24.0
+    # via altair
+    # via gradio
+    # via gradio-client
+    # via huggingface-hub
+    # via matplotlib
+    # via pytest
+    # via pytest-sugar
+pandas==2.2.2
+    # via altair
+    # via gradio
+pillow==10.3.0
+    # via gradio
+    # via matplotlib
+pluggy==1.5.0
+    # via pytest
+pydantic==2.7.1
+    # via chessli2
+    # via fastapi
+    # via gradio
+    # via pydantic-settings
+pydantic-core==2.18.2
+    # via pydantic
+pydantic-settings==2.2.1
+    # via chessli2
 pydub==0.25.1
-pygments==2.17.2
-pyparsing==3.1.1
-python-dateutil==2.8.2
-python-dotenv==1.0.0
+    # via gradio
+pygments==2.18.0
+    # via rich
+pyparsing==3.1.2
+    # via matplotlib
+pytest==8.2.0
+    # via pytest-sugar
+pytest-sugar==1.0.0
+python-dateutil==2.9.0.post0
+    # via berserk
+    # via matplotlib
+    # via pandas
+python-dotenv==1.0.1
+    # via pydantic-settings
+    # via uvicorn
 python-multipart==0.0.9
-pytz==2023.3.post1
+    # via fastapi
+    # via gradio
+pytz==2024.1
+    # via pandas
 pyyaml==6.0.1
-referencing==0.32.1
+    # via gradio
+    # via huggingface-hub
+    # via uvicorn
+referencing==0.35.1
+    # via jsonschema
+    # via jsonschema-specifications
 requests==2.31.0
-rich==13.7.0
-rpds-py==0.17.1
-ruff==0.4.3
+    # via berserk
+    # via huggingface-hub
+rich==13.7.1
+    # via typer
+rpds-py==0.18.1
+    # via jsonschema
+    # via referencing
+ruff==0.4.4
+    # via gradio
 semantic-version==2.10.0
+    # via gradio
 shellingham==1.5.4
+    # via typer
 six==1.16.0
-sniffio==1.3.0
-starlette==0.35.1
+    # via python-dateutil
+sniffio==1.3.1
+    # via anyio
+    # via httpx
+starlette==0.37.2
+    # via fastapi
 tabulate==0.9.0
+    # via chessli2
+termcolor==2.4.0
+    # via pytest-sugar
 tomlkit==0.12.0
-toolz==0.12.0
-tqdm==4.66.1
+    # via gradio
+toolz==0.12.1
+    # via altair
+tqdm==4.66.4
+    # via huggingface-hub
 typer==0.12.3
-typing-extensions==4.9.0
-tzdata==2023.4
-urllib3==2.1.0
-uvicorn==0.25.0
+    # via chessli2
+    # via fastapi-cli
+    # via gradio
+typing-extensions==4.11.0
+    # via berserk
+    # via fastapi
+    # via gradio
+    # via gradio-client
+    # via huggingface-hub
+    # via pydantic
+    # via pydantic-core
+    # via typer
+tzdata==2024.1
+    # via pandas
+ujson==5.9.0
+    # via fastapi
+urllib3==2.2.1
+    # via gradio
+    # via requests
+uvicorn==0.29.0
+    # via fastapi
+    # via fastapi-cli
+    # via gradio
+uvloop==0.19.0
+    # via uvicorn
+watchfiles==0.21.0
+    # via uvicorn
 websockets==11.0.3
+    # via gradio-client
+    # via uvicorn
 wrapt==1.16.0
+    # via deprecated

requirements.lock

@@ -5,78 +5,222 @@
 #   pre: false
 #   features: []
 #   all-features: false
+#   with-sources: false
 
 -e file:.
 aiofiles==23.2.1
-altair==5.2.0
+    # via gradio
+altair==5.3.0
+    # via gradio
 annotated-types==0.6.0
-anyio==4.2.0
+    # via pydantic
+anyio==4.3.0
+    # via httpx
+    # via starlette
+    # via watchfiles
 attrs==23.2.0
+    # via jsonschema
+    # via referencing
 berserk==0.13.2
-certifi==2023.11.17
+    # via chessli2
+certifi==2024.2.2
+    # via httpcore
+    # via httpx
+    # via requests
 charset-normalizer==3.3.2
+    # via requests
 chess==1.10.0
+    # via chessli2
 click==8.1.7
+    # via typer
+    # via uvicorn
+contourpy==1.2.1
+    # via matplotlib
 cycler==0.12.1
+    # via matplotlib
 deprecated==1.2.14
-exceptiongroup==1.2.1
-fastapi==0.109.0
-ffmpy==0.3.1
-filelock==3.13.1
-fonttools==4.47.2
-fsspec==2023.12.2
-gradio==4.29.0
+    # via berserk
+dnspython==2.6.1
+    # via email-validator
+email-validator==2.1.1
+    # via fastapi
+fastapi==0.111.0
+    # via fastapi-cli
+    # via gradio
+fastapi-cli==0.0.3
+    # via fastapi
+ffmpy==0.3.2
+    # via gradio
+filelock==3.14.0
+    # via huggingface-hub
+fonttools==4.51.0
+    # via matplotlib
+fsspec==2024.3.1
+    # via gradio-client
+    # via huggingface-hub
+gradio==4.31.0
+    # via chessli2
+    # via gradio-calendar
 gradio-calendar==0.0.4
-gradio-client==0.16.1
+    # via chessli2
+gradio-client==0.16.2
+    # via gradio
 h11==0.14.0
-httpcore==1.0.2
-httpx==0.26.0
-huggingface-hub==0.20.2
-idna==3.6
-importlib-resources==6.1.1
-jinja2==3.1.3
-jsonschema==4.20.0
+    # via httpcore
+    # via uvicorn
+httpcore==1.0.5
+    # via httpx
+httptools==0.6.1
+    # via uvicorn
+httpx==0.27.0
+    # via fastapi
+    # via gradio
+    # via gradio-client
+huggingface-hub==0.23.0
+    # via gradio
+    # via gradio-client
+idna==3.7
+    # via anyio
+    # via email-validator
+    # via httpx
+    # via requests
+importlib-resources==6.4.0
+    # via gradio
+jinja2==3.1.4
+    # via altair
+    # via fastapi
+    # via gradio
+jsonschema==4.22.0
+    # via altair
 jsonschema-specifications==2023.12.1
+    # via jsonschema
 kiwisolver==1.4.5
+    # via matplotlib
 markdown-it-py==3.0.0
-markupsafe==2.1.3
-matplotlib==3.5.3
+    # via rich
+markupsafe==2.1.5
+    # via gradio
+    # via jinja2
+matplotlib==3.8.4
+    # via gradio
 mdurl==0.1.2
+    # via markdown-it-py
 ndjson==0.3.1
-numpy==1.24.4
-orjson==3.9.10
-packaging==23.2
-pandas==2.0.3
-pillow==10.2.0
-pydantic==2.5.3
-pydantic-core==2.14.6
-pydantic-settings==2.1.0
+    # via berserk
+numpy==1.26.4
+    # via altair
+    # via contourpy
+    # via gradio
+    # via matplotlib
+    # via pandas
+orjson==3.10.3
+    # via fastapi
+    # via gradio
+packaging==24.0
+    # via altair
+    # via gradio
+    # via gradio-client
+    # via huggingface-hub
+    # via matplotlib
+pandas==2.2.2
+    # via altair
+    # via gradio
+pillow==10.3.0
+    # via gradio
+    # via matplotlib
+pydantic==2.7.1
+    # via chessli2
+    # via fastapi
+    # via gradio
+    # via pydantic-settings
+pydantic-core==2.18.2
+    # via pydantic
+pydantic-settings==2.2.1
+    # via chessli2
 pydub==0.25.1
-pygments==2.17.2
-pyparsing==3.1.1
-python-dateutil==2.8.2
-python-dotenv==1.0.0
+    # via gradio
+pygments==2.18.0
+    # via rich
+pyparsing==3.1.2
+    # via matplotlib
+python-dateutil==2.9.0.post0
+    # via berserk
+    # via matplotlib
+    # via pandas
+python-dotenv==1.0.1
+    # via pydantic-settings
+    # via uvicorn
 python-multipart==0.0.9
-pytz==2023.3.post1
+    # via fastapi
+    # via gradio
+pytz==2024.1
+    # via pandas
 pyyaml==6.0.1
-referencing==0.32.1
+    # via gradio
+    # via huggingface-hub
+    # via uvicorn
+referencing==0.35.1
+    # via jsonschema
+    # via jsonschema-specifications
 requests==2.31.0
-rich==13.7.0
-rpds-py==0.17.1
-ruff==0.4.3
+    # via berserk
+    # via huggingface-hub
+rich==13.7.1
+    # via typer
+rpds-py==0.18.1
+    # via jsonschema
+    # via referencing
+ruff==0.4.4
+    # via gradio
 semantic-version==2.10.0
+    # via gradio
 shellingham==1.5.4
+    # via typer
 six==1.16.0
-sniffio==1.3.0
-starlette==0.35.1
+    # via python-dateutil
+sniffio==1.3.1
+    # via anyio
+    # via httpx
+starlette==0.37.2
+    # via fastapi
 tabulate==0.9.0
+    # via chessli2
 tomlkit==0.12.0
-toolz==0.12.0
-tqdm==4.66.1
+    # via gradio
+toolz==0.12.1
+    # via altair
+tqdm==4.66.4
+    # via huggingface-hub
 typer==0.12.3
-typing-extensions==4.9.0
-tzdata==2023.4
-urllib3==2.1.0
-uvicorn==0.25.0
+    # via chessli2
+    # via fastapi-cli
+    # via gradio
+typing-extensions==4.11.0
+    # via berserk
+    # via fastapi
+    # via gradio
+    # via gradio-client
+    # via huggingface-hub
+    # via pydantic
+    # via pydantic-core
+    # via typer
+tzdata==2024.1
+    # via pandas
+ujson==5.9.0
+    # via fastapi
+urllib3==2.2.1
+    # via gradio
+    # via requests
+uvicorn==0.29.0
+    # via fastapi
+    # via fastapi-cli
+    # via gradio
+uvloop==0.19.0
+    # via uvicorn
+watchfiles==0.21.0
+    # via uvicorn
 websockets==11.0.3
+    # via gradio-client
+    # via uvicorn
 wrapt==1.16.0
+    # via deprecated

requirements.txt

@@ -1,75 +1 @@
-aiofiles==23.2.1
-altair==5.2.0
-annotated-types==0.6.0
-anyio==4.2.0
-attrs==23.2.0
-berserk==0.13.2
-certifi==2023.11.17
-charset-normalizer==3.3.2
-chess==1.10.0
-click==8.1.7
-cycler==0.12.1
-deprecated==1.2.14
-exceptiongroup==1.2.1
-fastapi==0.109.0
-ffmpy==0.3.1
-filelock==3.13.1
-fonttools==4.47.2
-fsspec==2023.12.2
-gradio==4.29.0
-gradio-calendar==0.0.4
-gradio-client==0.16.1
-h11==0.14.0
-httpcore==1.0.2
-httpx==0.26.0
-huggingface-hub==0.20.2
-idna==3.6
-importlib-resources==6.1.1
-jinja2==3.1.3
-jsonschema==4.20.0
-jsonschema-specifications==2023.12.1
-kiwisolver==1.4.5
-markdown-it-py==3.0.0
-markupsafe==2.1.3
-matplotlib==3.5.3
-mdurl==0.1.2
-ndjson==0.3.1
-numpy==1.24.4
-orjson==3.9.10
-packaging==23.2
-pandas==2.0.3
-pillow==10.2.0
-pkgutil-resolve-name==1.3.10
-pydantic==2.5.3
-pydantic-core==2.14.6
-pydantic-settings==2.1.0
-pydub==0.25.1
-pygments==2.17.2
-pyparsing==3.1.1
-python-dateutil==2.8.2
-python-dotenv==1.0.0
-python-multipart==0.0.9
-pytz==2023.3.post1
-pyyaml==6.0.1
-referencing==0.32.1
-requests==2.31.0
-rich==13.7.0
-rpds-py==0.17.1
-ruff==0.4.3
-semantic-version==2.10.0
-shellingham==1.5.4
-six==1.16.0
-sniffio==1.3.0
-starlette==0.35.1
-tabulate==0.9.0
-tomlkit==0.12.0
-toolz==0.12.0
-tqdm==4.66.1
-typer==0.12.3
-typing-extensions==4.9.0
-tzdata==2023.4
-urllib3==2.1.0
-uvicorn==0.25.0
-websockets==11.0.3
-wrapt==1.16.0
-zipp==3.18.1
+chessli2 @ git+https://github.com/pwenker/chessli2

src/chessli2/app.py

@@ -0,0 +1,3 @@
+if __name__ == "__main__":
+    from chessli2.gui import chessli2_gradio_app
+    chessli2_gradio_app.launch()

src/chessli2/choices.py

@@ -0,0 +1,92 @@
+from enum import Enum
+
+
+class Output(str, Enum):
+    file = "file"
+    info = "info"
+    pgn = "pgn"
+
+
+class Color(Enum):
+    white = 1
+    black = 0
+
+
+class MistakeNag(Enum):
+    mistake = 2
+    blunder = 4
+    speculative = 5
+    dubious = 6
+
+
+class TimeControl(str, Enum):
+    bullet = "Bullet"
+    blitz = "Blitz"
+    rapid = "Rapid"
+    classical = "Classical"
+    ultraBullet = "UltraBullet"
+    all = "All Time Controls"
+
+
+class PuzzleTheme(str, Enum):
+    advancedPawn = "Advanced pawn"
+    advantage = "Advantage"
+    anastasiaMate = "Anastasia's mate"
+    arabianMate = "Arabian mate"
+    attackingF2F7 = "Attacking f2 or f7"
+    attraction = "Attraction"
+    backRankMate = "Back rank mate"
+    bishopEndgame = "Bishop endgame"
+    bodenMate = "Boden's mate"
+    castling = "Castling"
+    capturingDefender = "Capture the defender"
+    crushing = "Crushing"
+    doubleBishopMate = "Double bishop mate"
+    dovetailMate = "Dovetail mate"
+    equality = "Equality"
+    kingsideAttack = "Kingside attack"
+    clearance = "Clearance"
+    defensiveMove = "Defensive move"
+    deflection = "Deflection"
+    discoveredAttack = "Discovered attack"
+    doubleCheck = "Double check"
+    endgame = "Endgame"
+    exposedKing = "Exposed king"
+    fork = "Fork"
+    hangingPiece = "Hanging piece"
+    hookMate = "Hook mate"
+    interference = "Interference"
+    intermezzo = "Intermezzo"
+    knightEndgame = "Knight endgame"
+    long = "Long puzzle"
+    master = "Master games"
+    masterVsMaster = "Master vs Master games"
+    mate = "Checkmate"
+    mateIn1 = "Mate in 1"
+    mateIn2 = "Mate in 2"
+    mateIn3 = "Mate in 3"
+    mateIn4 = "Mate in 4"
+    mateIn5 = "Mate in 5 or more"
+    middlegame = "Middlegame"
+    oneMove = "One-move puzzle"
+    opening = "Opening"
+    pawnEndgame = "Pawn endgame"
+    pin = "Pin"
+    promotion = "Promotion"
+    queenEndgame = "Queen endgame"
+    queenRookEndgame = "Queen and Rook"
+    queensideAttack = "Queenside attack"
+    quietMove = "Quiet move"
+    rookEndgame = "Rook endgame"
+    sacrifice = "Sacrifice"
+    short = "Short puzzle"
+    skewer = "Skewer"
+    smotheredMate = "Smothered mate"
+    superGM = "Super GM games"
+    trappedPiece = "Trapped piece"
+    underPromotion = "Underpromotion"
+    veryLong = "Very long puzzle"
+    xRayAttack = "X-Ray attack"
+    zugzwang = "Zugzwang"
+    healthyMix = "Healthy mix"
+    playerGames = "Player games"

src/chessli2/cli.py

@@ -0,0 +1,122 @@
+import logging
+
+import typer
+from gradio_client import Client
+from rich import print
+
+from chessli2.choices import MistakeNag, Output, PuzzleTheme, TimeControl
+from chessli2.settings import settings
+
+app = typer.Typer()
+
+
+@app.command()
+def serve(
+    server_name: str = typer.Option(
+        "127.0.0.1",
+        help="To make app accessible on local network, set this to '0.0.0.0'. Can be set by environment variable GRADIO_SERVER_NAME. If None, will use '127.0.0.1",
+    ),
+    server_port: int = typer.Option(
+        7860,
+        help="Will start gradio app on this port (if available). Can be set by environment variable GRADIO_SERVER_PORT. If None, will search for an available port starting at 7860.",
+    ),
+):
+    """
+    Starts the app and serves it given specified `server_name` and `server_port`.
+    """
+    from chessli2.gui import chessli2_gradio_app
+
+    chessli2_gradio_app.launch(server_port=server_port, server_name=server_name)
+
+
+@app.command()
+def mistakes(
+    src: str = typer.Option(
+        "pwenker/chessli2",
+        help='Select either the name of the Hugging Face Space to load, (e.g. "pwenker/chessli2") or the full URL (including "http" or "https") of the hosted Gradio app to load (e.g. "http://localhost:7860/" or "https://bec81a83-5b5c-471e.gradio.live/',
+    ),
+    lichess_api_token: str = typer.Option(
+        settings.lichess_api_token, help="Select lichess API token"
+    ),
+    user_name: str = typer.Option("pwenker", help="Select user name"),
+    start_date: str = typer.Option("2017-05-14", help="Select start date (YYYY-MM-DD)"),
+    end_date: str = typer.Option("2024-05-14", help="Select end date (YYYY-MM-DD)"),
+    nags: list[int] = typer.Option(
+        [MistakeNag.blunder.value, MistakeNag.mistake.value],
+        help="Filter by mistake nag type (blunder=4, mistake=2, speculative=5, dubious=6)",
+    ),
+    time_control: TimeControl = typer.Option(
+        TimeControl.all, help="Filter by time control"
+    ),
+    output: Output = typer.Option(
+        Output.file,
+        help="""Select whether to output mistakes as markdown table, as PGN string, or file path of CSV file containing PGNS""",
+    ),
+):
+    """
+    Fetches mistakes from the API based on the specified parameters.
+    """
+    client = Client(src)
+    mistake_pgns, mistake_md, mistake_csv = client.predict(
+        lichess_api_token=lichess_api_token,
+        user_name=user_name,
+        start_date=start_date,
+        end_date=end_date,
+        nags=nags,
+        time_control=time_control,
+        api_name="/get_mistakes",
+    )
+
+    if output == Output.info:
+        print(mistake_md)
+    elif output == Output.pgn:
+        print(mistake_pgns)
+    elif output == Output.file:
+        print(mistake_csv["value"])
+
+
+@app.command()
+def puzzles(
+    src: str = typer.Option(
+        "http://pwenker.github.io/chessli2/",
+        help="Select either the name of the Hugging Face Space to load, (e.g. 'pwenker/chessli2') or the full URL (including 'http' or 'https') of the hosted Gradio app to load (e.g. 'http://localhost:7860/' or 'https://bec81a83-5b5c-471e.gradio.live/')",
+    ),
+    lichess_api_token: str = typer.Option(
+        settings.lichess_api_token, help="Select lichess API token"
+    ),
+    before: str = typer.Option(
+        "2024-05-15",
+        help="Only get puzzle activity before this date (format YYYY-MM-DD)",
+    ),
+    max: int = typer.Option(100, help="Select maxmimum number of puzzles"),
+    themes: list[PuzzleTheme] = typer.Option(
+        [pt for pt in PuzzleTheme],
+        help="Filter by puzzle themes",
+    ),
+    output: Output = typer.Option(
+        Output.file,
+        help="Select whether to output info about mistakes, mistakes as PGN string, or a file path of CSV file containing PGNs",
+    ),
+):
+    """
+    Fetches puzzles from the API based on the specified parameters.
+    """
+    logging.disable(logging.CRITICAL)
+    client = Client(src)
+    puzzle_pgns, puzzle_theme_counter, puzzle_csv = client.predict(
+        before=before,
+        max=max,
+        themes_selection=themes,
+        api_name="/get_puzzles",
+    )
+
+    if output == Output.info:
+        print(puzzle_theme_counter)
+    elif output == Output.pgn:
+        print(puzzle_pgns)
+    elif output == Output.file:
+        print(puzzle_csv["value"])
+
+
+if __name__ == "__main__":
+    app()

src/chessli2/games.py

@@ -1,68 +0,0 @@
-import io
-
-import berserk
-import chess.pgn
-import gradio as gr
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class Settings(BaseSettings):
-    model_config = SettingsConfigDict(env_file=".env")
-    lichess_api_token: str = ''
-
-
-settings = Settings()
-
-def generate_grid_html(games_list, row_length=2):
-    game_ids = [
-        chess.pgn.read_headers(io.StringIO(game_pgn))["Site"].rpartition("/")[-1]
-        for game_pgn in games_list
-    ]
-    if row_length == 1:
-        return "\n".join(
-            [
-                f'<iframe src="https://lichess.org/embed/game/{game_id}?theme=auto&bg=auto" width=600 height=397 frameborder=0></iframe>'
-                for game_id in game_ids
-            ]
-        )
-    else:
-        html_rows = []
-        for i in range(0, len(game_ids), row_length):
-            row_html = "".join(
-                [
-                    f'<iframe src="https://lichess.org/embed/game/{id}?theme=auto&bg=auto" width="600" height="397" frameborder="0"></iframe>'
-                    for id in game_ids[i : i + row_length]
-                ]
-            )
-            # Wrap each row in a div for grid formatting
-            html_rows.append(
-                f'<div style="display: flex; justify-content: space-around;">{row_html}</div>'
-            )
-        return "\n".join(html_rows)
-
-def fetch_games(
-    user_name, start_date, end_date, lichess_api_token=settings.lichess_api_token
-):
-    gr.Info("Fetching chess games 🔄♟️")
-
-    start = berserk.utils.to_millis(start_date)
-    end = berserk.utils.to_millis(end_date)
-    session = berserk.TokenSession(lichess_api_token)
-    client = berserk.Client(session=session)
-    games = client.games.export_by_player(
-        user_name,
-        as_pgn=True,
-        color="black",
-        evals=True,
-        analysed=True,
-        literate=True,
-        since=start,
-        until=end,
-        opening=True,
-    )
-    games_list = list(games)
-
-
-    game_ids_html = generate_grid_html(games_list)
-
-    return games_list, gr.HTML(game_ids_html)

src/chessli2/gui.py

@@ -1,42 +1,44 @@
 from datetime import datetime
-from io import StringIO
 from pathlib import Path
 
-import chess.pgn
 import gradio as gr
-import pandas as pd
 from gradio_calendar import Calendar
 
-from src.chessli2.mistakes import validated_get_mistakes
+from chessli2 import choices as ch
+from chessli2.mistakes import validated_get_mistakes
+from chessli2.tactics import get_puzzles
 
 readme_file = Path("README.md")
+puzzle_themes_file = Path("docs/puzzle_themes.md")
 
-nags = {
-    "Mistake (?)": 2,
-    "Blunder (??)": 4,
-    "Speculative Move (!?)": 5,
-    "Dubious Move (?!)": 6,
-}
 
-with gr.Blocks() as demo:
+with gr.Blocks() as chessli2_gradio_app:
     with gr.Tab("Welcome"):
         readme = readme_file.read_text()
-        gr_readme = readme.split('---')[2].strip()
+        gr_readme = readme.split("---")[2].strip()
         gr.Markdown(gr_readme)
-    with gr.Tab("Games & Mistakes"):
-        gr.Markdown("Fetch your games and download a CSV with your mistakes")
 
-        lichess_api_token = gr.Textbox(
-            placeholder="Paste your Lichess API key",
-            label="Lichess API Token",
-            lines=1,
-            type="password",
+    with gr.Tab("Games & Mistakes"):
+        gr.Markdown(
+            """
+            ### Games & Mistakes
+            
+            Here you can fetch your games and mistakes from your **game history** 🎮. You can filter by time control, type of mistakes, and date range.
+            
+            When you are happy, you can download a CSV file with the selected mistakes' PGNs to practice them with Anki 📥."""
         )
+
         user_name = gr.Textbox(
             label="User Name",
             placeholder="Enter your user name",
             info="Type in your lichess user name",
         )
+        lichess_api_token_mistakes = gr.Textbox(
+            placeholder="Paste your Lichess API key",
+            label="Lichess API Token",
+            lines=1,
+            type="password",
+        )
         with gr.Row():
             start_date = Calendar(
                 type="datetime",
@@ -52,76 +54,94 @@ with gr.Blocks() as demo:
             )
         nags_checkbox = gr.CheckboxGroup(
             label="Mistake Types",
-            value=[2, 4],  # Mistakes and Blundes per default
+            value=[ch.MistakeNag.mistake.value, ch.MistakeNag.blunder.value],
             info="Select which types of mistakes should be detected",
-            choices=[(k, v) for k, v in nags.items()],
+            choices=[
+                ("Mistake (?)", ch.MistakeNag.mistake.value),
+                ("Blunder (??)", ch.MistakeNag.blunder.value),
+                ("Speculative Move (!?)", ch.MistakeNag.speculative.value),
+                ("Dubious Move (?!)", ch.MistakeNag.dubious.value),
+            ],
+        )
+        time_control = gr.Dropdown(
+            label="Filter by Time Control",
+            value="All Time Controls",
+            allow_custom_value=True,
+            choices=[(tc.value, tc.name) for tc in ch.TimeControl],
         )
         get_mistakes_btn = gr.Button("Get Mistakes", variant="primary")
 
-        gr.Markdown("### Mistakes")
-        mistakes_df = gr.Dataframe(
-            headers=["PGN"],
-            visible=False,
-            interactive=False,
-        )
-        mistakes_md = gr.Markdown()
+        mistake_pgns = gr.Textbox(visible=False)
+        mistakes_md = gr.Markdown(label="Mistakes")
 
-        def export_csv(df, user_name):
-            gr.Info("Preparing downloadable CSV file 💾")
-            file_name = f"mistakes_{user_name}.csv"
-            df.to_csv(
-                file_name,
-                index=False,
-                header=False,
-            )
-            return gr.DownloadButton(value=file_name, visible=True)
-
-        download_button = gr.DownloadButton(
+        mistakes_download_button = gr.DownloadButton(
             "Download CSV", variant="primary", visible=False
         )
 
-        def df_to_md(df):
-            gr.Info("Visualizing mistakes as markdown table 📉📝")
-
-            def parse_pgn(pgn_text):
-                pgn_io = StringIO(pgn_text)
-                game = chess.pgn.read_game(pgn_io)
-                headers = game.headers
-                moves = pgn_text.split("\n\n")[1]
-                mistake, *correct_variation = moves.split("\n")
-                result_emoji = (
-                    "✅"
-                    if headers["Result"] == "1-0"
-                    else "❌"
-                    if headers["Result"] == "0-1"
-                    else "➖"
-                )
-                return {
-                    "White": headers["White"],
-                    "Black": headers["Black"],
-                    "Result": result_emoji,
-                    "White Elo": headers["WhiteElo"],
-                    "Black Elo": headers["BlackElo"],
-                    "Opening": headers["Opening"],
-                    "Mistake ❌": mistake,
-                    "Correct Variation ✅": correct_variation,
-                }
-
-            df_info = df["PGN"].apply(parse_pgn).apply(pd.Series)
+    with gr.Tab("Tactics"):
+        gr.Markdown(
+            """
+            ### Tactics & Puzzles
+            
+            Here you can fetch your puzzles from your [puzzle history](https://lichess.org/training/history) 🧩.
+            
+            You can filter by [puzzle themes](https://lichess.org/training/themes) 🎯 and also select a maximum number of puzzles.
+            When you are happy, you can download a CSV file with the selected puzzles' PGNs to practice them with Anki 📥."""
+        )
 
-            return df_info.to_markdown(index=False)
+        lichess_api_token_tactics = gr.Textbox(
+            placeholder="Paste your Lichess API key",
+            label="Lichess API Token",
+            lines=1,
+            type="password",
+        )
+        with gr.Accordion("Info about puzzle themes 🧩", open=False):
+            gr.Markdown(puzzle_themes_file.read_text())
 
-        get_mistakes_btn.click(
-            fn=validated_get_mistakes,
-            inputs=[lichess_api_token, user_name, start_date, end_date, nags_checkbox],
-            outputs=mistakes_df,
-            api_name="get_mistakes",
-        ).success(
-            fn=export_csv,
-            inputs=[mistakes_df, user_name],
-            outputs=download_button,
-        ).success(
-            fn=df_to_md,
-            inputs=mistakes_df,
-            outputs=mistakes_md,
+        puzzle_themes = gr.Dropdown(
+            label="Puzzle Themes",
+            info="Filter puzzles by selecting themes. Per default, all available themes are selected",
+            multiselect=True,
+            value=[th.name for th in ch.PuzzleTheme],
+            choices=[(th.value, th.name) for th in ch.PuzzleTheme],
+        )
+        max_puzzles = gr.Slider(
+            label="Maximum number of puzzles",
+            info="Since Puzzle activity is sorted by reverse chronological order (most recent first), this selects the last n puzzles",
+            minimum=1,
+            value=100,
+            maximum=100000,
+        )
+        until_date = Calendar(
+            type="datetime",
+            value=datetime.now(),
+            label="Only get puzzle activity before this time",
+            info="Click the calendar icon to bring up the calendar.",
         )
+        tactics_btn = gr.Button("Get tactics", variant="primary")
+        puzzle_pgns = gr.Textbox(visible=False)
+        puzzle_info = gr.JSON(label="Number of puzzles found organized by themes")
+        puzzle_md_table = gr.Markdown()
+        puzzle_download_button = gr.DownloadButton(
+            "Download CSV", variant="primary", visible=False
+        )
+
+    # Event Handler
+    get_mistakes_btn.click(
+        fn=validated_get_mistakes,
+        inputs=[
+            lichess_api_token_mistakes,
+            user_name,
+            start_date,
+            end_date,
+            nags_checkbox,
+            time_control,
+        ],
+        outputs=[mistake_pgns, mistakes_md, mistakes_download_button],
+        api_name="get_mistakes",
+    )
+    tactics_btn.click(
+        fn=get_puzzles,
+        inputs=[until_date, max_puzzles, puzzle_themes, lichess_api_token_tactics],
+        outputs=[puzzle_pgns, puzzle_info, puzzle_download_button],
+    )

src/chessli2/main.py

@@ -1,5 +0,0 @@
-from src.chessli2.gui import demo
-
-
-if __name__ == "__main__":
-    demo.launch(show_error=True)

src/chessli2/mistakes.py

@@ -1,16 +1,13 @@
 import io
-from enum import Enum
 
+import berserk
 import chess
 import chess.pgn
 import gradio as gr
 
-from src.chessli2.games import fetch_games
-
-
-class Color(Enum):
-    white = 1
-    black = 0
+from chessli2.choices import Color
+from chessli2.settings import get_client
+from chessli2.writer import mistake_pgns_to_md, write_pgn_to_csv
 
 
 def create_mistake_pgn(game_node):
@@ -38,35 +35,80 @@ def create_mistake_pgn(game_node):
     return pgn_string
 
 
-def get_mistakes(lichess_api_token, user_name, start_date, end_date, nags):
-    games, _ = fetch_games(user_name, start_date, end_date, lichess_api_token)
+def get_mistakes(
+    lichess_api_token, user_name, start_date, end_date, nags, time_control
+):
+    client, lichess_api_token = get_client(lichess_api_token=lichess_api_token)
 
-    gr.Info("Finding mistakes 🔍❌")
-    mistake_pgns = []
-    for game_pgn in games:
-        game_pgn = io.StringIO(game_pgn)
-        game_node = chess.pgn.read_game(game_pgn)
-
-        player: Color = (
-            Color.white if game_node.headers["White"] == user_name else Color.black
+    if not lichess_api_token:
+        gr.Info(
+            "If you authenticate with your lichess API token you can increase requests limit from 20 to 60 games per second!"
         )
 
-        def was_players_move(game_node):
-            return player.value != game_node.turn()
-
-        def relevant_mistakes_were_made(game_node, nags):
-            return game_node.nags and game_node.nags.issubset(set(nags))
-
-        while game_node is not None:
-            if was_players_move(game_node) and relevant_mistakes_were_made(
-                game_node, nags
-            ):
-                mistake_pgn = create_mistake_pgn(game_node)
+    games = client.games.export_by_player(
+        user_name,
+        as_pgn=True,
+        evals=True,
+        analysed=True,
+        literate=True,
+        since=berserk.utils.to_millis(start_date),
+        perf_type=None if time_control == "all" else time_control,
+        until=berserk.utils.to_millis(end_date),
+        opening=True,
+    )
 
-                mistake_pgns.append(mistake_pgn)
-            game_node = game_node.next()
-            
-    return [[mp] for mp in mistake_pgns]
+    mistake_pgns = []
+    n_games = 0
+    try:
+        for n, game_pgn in enumerate(games):
+            game_pgn = io.StringIO(game_pgn)
+            game_node = chess.pgn.read_game(game_pgn)
+
+            player: Color = (
+                Color.white if game_node.headers["White"] == user_name else Color.black
+            )
+
+            def was_players_move(game_node):
+                return player.value != game_node.turn()
+
+            def relevant_mistakes_were_made(game_node, nags):
+                return game_node.nags and game_node.nags.issubset(set(nags))
+
+            while game_node is not None:
+                if was_players_move(game_node) and relevant_mistakes_were_made(
+                    game_node, nags
+                ):
+                    mistake_pgn = create_mistake_pgn(game_node)
+
+                    mistake_pgns.append(mistake_pgn)
+                game_node = game_node.next()
+
+            n_games = n
+            info = f"Fetched {n} games(s) with {len(mistake_pgns)} mistakes..."
+            yield mistake_pgns, "", gr.DownloadButton(
+                label=info, variant="secondary", visible=True
+            )
+
+        if mistake_pgns:
+            filename = f"{user_name}_mistakes.csv"
+            write_pgn_to_csv(mistake_pgns, filename=filename)
+            mistakes_md = mistake_pgns_to_md(mistake_pgns=mistake_pgns)
+            info = f"Download CSV file with PGNs of {len(mistake_pgns)} mistakes in {n_games} games"
+            yield mistake_pgns, mistakes_md, gr.DownloadButton(
+                value=filename, label=info, variant="primary"
+            )
+        else:
+            mistakes_md = ""
+            yield mistake_pgns, mistakes_md, gr.DownloadButton(
+                label="No mistakes found", variant="secondary"
+            )
+    except berserk.exceptions.ResponseError:
+        gr.Warning("Your lichess API token is invalid. Did you misspell it?")
+        yield "", "", gr.DownloadButton(
+            label="Please insert a correct lichess API token into the textbox at the top of the interface or leave it empty",
+            visible=True,
+            variant="stop",
+        )
 
 
 def validate_user_input(user_name, start_date, end_date):
@@ -77,8 +119,12 @@ def validate_user_input(user_name, start_date, end_date):
     return user_name, start_date, end_date
 
 
-def validated_get_mistakes(lichess_api_token, user_name, start_date, end_date, nags):
+def validated_get_mistakes(
+    lichess_api_token, user_name, start_date, end_date, nags, time_control
+):
     user_name, start_date, end_date = validate_user_input(
         user_name, start_date, end_date
     )
-    return get_mistakes(lichess_api_token, user_name, start_date, end_date, nags)
+    yield from get_mistakes(
+        lichess_api_token, user_name, start_date, end_date, nags, time_control
+    )

src/chessli2/rich_logging.py

@@ -0,0 +1,33 @@
+"""
+This file contains the logging configuration for the project.
+"""
+
+import logging
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+FORMAT = "%(message)s"
+logging.basicConfig(
+    level="INFO",
+    format=FORMAT,
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+
+console = Console()
+log = logging.getLogger("rich")
+
+
+def set_log_level(verbosity: int):
+    if verbosity == 0:
+        log.setLevel(logging.CRITICAL)
+    elif verbosity == 1:
+        log.setLevel(logging.ERROR)
+    if verbosity == 2:
+        log.setLevel(logging.WARNING)
+    elif verbosity == 3:
+        log.setLevel(logging.INFO)
+    elif verbosity == 4:
+        log.setLevel(logging.DEBUG)
+    return log

src/chessli2/settings.py

@@ -0,0 +1,18 @@
+import berserk
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+    lichess_api_token: str = ""
+
+
+settings = Settings()
+
+
+def get_client(lichess_api_token):
+    if not lichess_api_token:
+        lichess_api_token = settings.lichess_api_token
+    session = berserk.TokenSession(lichess_api_token)
+    client = berserk.Client(session=session)
+    return client, lichess_api_token

src/chessli2/tactics.py

@@ -0,0 +1,136 @@
+import datetime
+from collections import Counter
+
+import berserk
+import chess
+import gradio as gr
+
+from chessli2.settings import get_client
+from chessli2.writer import write_pgn_to_csv
+
+
+def puzzle_pgn(puzzle_activity):
+    game = puzzle_activity["game"]
+    puzzle = puzzle_activity["puzzle"]
+    themes = puzzle["themes"]
+
+    board = chess.Board()
+    moves = game["pgn"].split()
+
+    for move in moves[:-1]:
+        board.push_san(move)
+    last_move = board.parse_san(moves[-1])
+
+    pgn = chess.pgn.Game(
+        headers={
+            "Event": "Puzzle",
+            "Site": f"https://www.lichess.org/training/{puzzle['id']}",
+            "Themes": " ".join(themes),
+        }
+    )
+    pgn.setup(board)
+    puzzle_moves = [chess.Move.from_uci(m) for m in puzzle["solution"]]
+
+    pgn.add_line(
+        moves=[last_move] + puzzle_moves,
+        starting_comment=f"Puzzle {puzzle['id']} with themes: {' '.join(puzzle['themes'])}",
+    )
+
+    exporter = chess.pgn.StringExporter(headers=True, variations=True, comments=True)
+    pgn_string = pgn.accept(exporter)
+    return pgn_string, themes
+
+
+def get_puzzles(before, max, themes_selection, lichess_api_token):
+    client, lichess_api_token = get_client(lichess_api_token=lichess_api_token)
+
+    puzzle_activity = client.puzzles.get_puzzle_activity(
+        before=berserk.utils.to_millis(before), max=max
+    )
+    n_puzzles = 0
+    skipped_puzzles = 0
+    puzzle_pgns = []
+    # Create a counter object that tracks the number of puzzles per theme
+    theme_counter = Counter()
+
+    try:
+        for pa in puzzle_activity:
+            ppgn, themes = puzzle_pgn(client.puzzles.get(pa["puzzle"]["id"]))
+            # check if any of the selected themes are in the puzzle themes
+            if not set(themes_selection).isdisjoint(themes):
+                n_puzzles += 1
+                theme_counter.update(themes)
+                puzzle_pgns.append(ppgn)
+            else:
+                skipped_puzzles += 1
+            download_info = (
+                f"Fetched {n_puzzles}, skipped {skipped_puzzles} puzzle(s)..."
+            )
+            yield puzzle_pgns, theme_counter, gr.DownloadButton(
+                label=download_info, variant="secondary", visible=True
+            )
+
+        if n_puzzles > 0:
+            filename = "puzzles.csv"
+            write_pgn_to_csv(puzzle_pgns, filename=filename)
+            download_info = f"Download CSV file with PGNs of {n_puzzles} puzzles"
+            yield puzzle_pgns, theme_counter, gr.DownloadButton(
+                value=filename, label=download_info, variant="primary"
+            )
+        else:
+            yield puzzle_pgns, {"Puzzles": 0}, gr.DownloadButton(
+                label="No puzzles found", variant="secondary"
+            )
+    except berserk.exceptions.ResponseError as e:
+        if "No such token" in e.message:
+            gr.Warning("Your lichess API token is invalid. Did you misspell it?")
+            warning = "Please insert a correct lichess API token into the textbox at the top of the interface"
+        else:
+            gr.Warning(
+                "To fetch your puzzle activity, you need to authenticate with your lichess API token!"
+            )
+            warning = "Please paste your lichess API token into the corresponding textbox at the top of the interface to fetch your puzzles"
+        yield "", {}, gr.DownloadButton(
+            label=warning,
+            visible=True,
+            variant="stop",
+        )
+
+
+def create_markdown_table(entries):
+    if not entries:
+        return "No data provided"
+
+    if not isinstance(entries, list) or not all(
+        isinstance(item, dict) for item in entries
+    ):
+        return "Invalid input format. Please provide a list of dictionaries."
+
+    # Extract headers from the first dictionary
+    headers = entries[0].keys()
+
+    # Create the header row
+    header_row = "| " + " | ".join(headers) + " |"
+
+    # Create the separator row
+    separator_row = "| " + " | ".join(["---"] * len(headers)) + " |"
+
+    # Initialize the table with the header and separator
+    table = [header_row, separator_row]
+
+    # Fill in the data rows
+    for entry in entries:
+        row = []
+        for header in headers:
+            if header in entry:
+                value = entry[header]
+                if isinstance(value, datetime.datetime):
+                    value = value.strftime("%Y-%m-%d %H:%M:%S %Z")
+                elif isinstance(value, list):
+                    value = ", ".join(map(str, value))
+                row.append(str(value))
+            else:
+                row.append("N/A")
+        table.append("| " + " | ".join(row) + " |")
+
+    return "\n".join(table)

src/chessli2/writer.py

@@ -0,0 +1,58 @@
+import csv
+from io import StringIO
+
+import chess
+import gradio as gr
+import pandas as pd
+
+
+def write_pgn_to_csv(pgns, filename="pgns.csv"):
+    """
+    Writes a list of PGN strings to a CSV file with a single header 'PGN'.
+
+    Args:
+    pgns (list of str): List containing PGN strings.
+    filename (str): Name of the CSV file to be created.
+    """
+    # Open the file in write mode
+    with open(filename, mode="w", newline="", encoding="utf-8") as file:
+        # Create a CSV writer object
+        writer = csv.writer(file)
+
+        # Write each PGN as a new row
+        for pgn in pgns:
+            writer.writerow([pgn])
+
+
+def mistake_pgns_to_md(mistake_pgns):
+    gr.Info("Visualizing mistakes as markdown table 📉📝")
+
+    def parse_pgn(pgn_text):
+        pgn_io = StringIO(pgn_text)
+        game = chess.pgn.read_game(pgn_io)
+        headers = game.headers
+        moves = pgn_text.split("\n\n")[1]
+        mistake, *correct_variation = moves.split("\n")
+        result_emoji = (
+            "✅"
+            if headers["Result"] == "1-0"
+            else "❌"
+            if headers["Result"] == "0-1"
+            else "➖"
+        )
+        return {
+            "White": headers["White"],
+            "Black": headers["Black"],
+            "Result": result_emoji,
+            "White Elo": headers["WhiteElo"],
+            "Black Elo": headers["BlackElo"],
+            "Opening": headers["Opening"],
+            "Time Control": headers["TimeControl"],
+            "Mistake ❌": mistake,
+            "Correct Variation ✅": correct_variation,
+        }
+
+    df = pd.DataFrame(data=mistake_pgns, columns=["PGN"])
+    df_info = df["PGN"].apply(parse_pgn).apply(pd.Series)
+
+    return df_info.to_markdown(index=False)

tests/test_cli.py

@@ -0,0 +1,63 @@
+import pytest
+from typer.testing import CliRunner
+
+from chessli2.cli import app
+from chessli2.settings import settings
+
+runner = CliRunner()
+
+sources = ["pwenker/chessli2", "http://localhost:7860"]
+
+
+@pytest.mark.parametrize("src", ["http://localhost:7860"])
+def test_mistakes_with_options(src):
+    result = runner.invoke(
+        app,
+        [
+            "mistakes",
+            "--src",
+            src,
+            "--lichess-api-token",
+            settings.lichess_api_token,
+            "--user-name",
+            "pwenker",
+            "--start-date",
+            "2017-05-14",
+            "--end-date",
+            "2024-05-14",
+            "--nags",
+            "4",
+            "--nags",
+            "2",
+            "--time-control",
+            "All Time Controls",
+            "--output",
+            "file",
+        ],
+    )
+    assert result.exit_code == 0
+
+
+@pytest.mark.parametrize("src", ["http://localhost:7860"])
+def test_puzzles_with_options(src):
+    """
+    chessli puzzles --src http://localhost:7860  --user-name pwenker --before 2024-05-14 --max 100 --output file
+    """
+    result = runner.invoke(
+        app,
+        [
+            "puzzles",
+            "--src",
+            src,
+            "--lichess-api-token",
+            settings.lichess_api_token,
+            "--before",
+            "2024-05-14",
+            "--max",
+            '10',
+            "--output",
+            "file",
+        ],
+    )
+    __import__('pdb').set_trace()
+    assert result.exit_code == 0