Upload 31 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+akinator.py/banner.png filter=lfs diff=lfs merge=lfs -text

akinator.py/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,66 @@
+name: Bug Report
+description: Report broken or incorrect behaviour
+labels: bug
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking the time to fill out a bug.
+
+        Please note that this form is for bugs only!
+  - type: input
+    attributes:
+      label: Summary
+      description: A simple summary of your bug report.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction Steps
+      description: >
+         What you did to make it happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Code
+      description: >
+        A short snippet of code that showcases the bug.
+      render: python
+  - type: textarea
+    attributes:
+      label: Expected Results
+      description: >
+        What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Actual Results
+      description: >
+        What actually happened?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: System Information
+      description: >
+        Provide some information about your system.
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Checklist
+      description: >
+        Let's make sure you've properly done due diligence when reporting this issue!
+      options:
+        - label: I have searched open issues for duplicates.
+          required: true
+        - label: I have shown the entire traceback, if possible.
+          required: true
+        - label: I have made sure that this issue is valid.
+          required: true
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If you have anything else to say, please do so here.

akinator.py/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a Question
+    about: Ask questions and have discussions with other users.
+    url: https://github.com/Ombucha/brawlstars.py/discussions

akinator.py/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature Request
+description: Suggest a feature for this library
+labels: enhancement
+body:
+  - type: input
+    attributes:
+      label: Summary
+      description: >
+        A short summary of what your feature request is.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Problem
+      description: >
+        What problem is your feature trying to solve?
+        What becomes easier or possible when this feature is implemented?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Ideal Solution
+      description: >
+        What is your ideal solution to the problem?
+        What would you like this feature to do?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Current Solution
+      description: >
+        What is the current solution to the problem, if any?
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If there is anything else to say, please do so here.

akinator.py/.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '22 21 * * 4'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v3
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

akinator.py/.github/workflows/pylint.yml

@@ -0,0 +1,23 @@
+name: Pylint
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+    - name: Analysing the code with pylint
+      run: |
+        pylint $(git ls-files '*.py')

akinator.py/.github/workflows/python-publish.yml

@@ -0,0 +1,31 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

akinator.py/.github/workflows/unittest.yml

@@ -0,0 +1,27 @@
+name: Run Unit Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+    - name: Run unittests
+      run: |
+        python -m unittest discover -s tests

akinator.py/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

akinator.py/.pylintrc

@@ -0,0 +1,2 @@
+[MASTER]
+disable = W0718, C0301, R0902, R1710, R0903, R0801, E0401

akinator.py/.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: docs/conf.py
+
+python:
+   install:
+   - requirements: requirements.txt

akinator.py/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

akinator.py/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to akinator.py
+
+Thank you for your interest in contributing! Your help is appreciated.
+
+## How to Contribute
+
+1. **Fork the repository** and clone your fork.
+2. **Create a new branch** for your feature or bugfix:
+   ```sh
+   git checkout -b my-feature
+   ```
+3. **Make your changes** and add tests if possible.
+4. **Lint your code** using [pylint](https://pylint.pycqa.org/).
+5. **Commit your changes** with a clear message.
+6. **Push to your fork** and open a Pull Request (PR) against the `main` branch.
+
+## Code Style
+
+- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidelines.
+- Use type hints where possible.
+- Document your functions and classes.
+
+## Pull Request Checklist
+
+- [ ] Code is linted with `pylint`
+- [ ] Documentation is updated if needed
+- [ ] PR description explains the change
+
+## Reporting Issues
+
+If you find a bug or have a feature request, please [open an issue](https://github.com/Ombucha/akinator.py/issues) and provide as much detail as possible.
+
+## Community
+
+- Be respectful and constructive.
+- Ask questions or discuss ideas in issues or PRs.
+
+Thank you for helping improve **akinator.py**!

akinator.py/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

akinator.py/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

akinator.py/README.rst

@@ -0,0 +1,160 @@
+.. image:: https://raw.githubusercontent.com/Ombucha/akinator.py/main/banner.png
+
+.. image:: https://img.shields.io/pypi/v/akinator
+    :target: https://pypi.python.org/pypi/akinator
+    :alt: PyPI version
+.. image:: https://static.pepy.tech/personalized-badge/akinator?period=total&left_text=downloads&left_color=grey&right_color=red
+    :target: https://pypi.python.org/pypi/akinator
+    :alt: PyPI downloads
+.. image:: https://sloc.xyz/github/Ombucha/akinator.py?lower=True
+    :target: https://github.com/Ombucha/akinator.py/graphs/contributors
+    :alt: Lines of code
+.. image:: https://img.shields.io/github/repo-size/Ombucha/akinator.py?color=yellow
+    :target: https://github.com/Ombucha/akinator.py
+    :alt: Repository size
+
+A modern, easy-to-use Python wrapper for the Akinator web game, supporting both synchronous and asynchronous usage.
+
+Background
+----------
+
+Originally, there was a popular Python library called ``akinator.py``, which provided a simple interface to interact with the Akinator API. However, this library suddenly disappeared from public repositories without notice. In response, a mirror was created here to preserve its functionality. Unfortunately, it too stopped working after Akinator made changes to their backend API. Later, another library called ``akipy`` emerged to fill the gap, but it also became non-functional when Cloudflare protection was introduced on Akinator's endpoints. This library revives Akinator interaction by replacing the standard ``requests`` library with ``cloudscraper``, allowing it to bypass Cloudflare's anti-bot measures and restoring full functionality.
+
+Features
+--------
+
+- Play Akinator in Python (sync and async)
+- Supports all official Akinator languages and themes
+- Simple, Pythonic interface
+- Type hints for better editor support
+- Custom exceptions for robust error handling
+- Well-tested and documented
+- Actively maintained and open source
+
+Requirements
+------------
+
+- **Python 3.9 or higher**
+- `cloudscraper <https://pypi.org/project/cloudscraper/>`_
+
+Installation
+------------
+
+To install the latest stable version:
+
+.. code-block:: sh
+
+    python3 -m pip install akinator
+
+To install the development version:
+
+.. code-block:: sh
+
+    git clone https://github.com/Ombucha/akinator.py
+    cd akinator.py
+    python3 -m pip install -e .
+
+Getting Started
+---------------
+
+Synchronous Example
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import akinator
+
+    aki = akinator.Akinator()
+    aki.start_game()
+
+    while not aki.finished:
+        print(f"\nQuestion: {str(aki)}")
+        user_input = input(
+            "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
+        ).strip().lower()
+        if user_input == "b":
+            try:
+                aki.back()
+            except akinator.CantGoBackAnyFurther:
+                print("You can't go back any further!")
+        else:
+            try:
+                aki.answer(user_input)
+            except akinator.InvalidChoiceError:
+                print("Invalid answer. Please try again.")
+
+    print("\n--- Game Over ---")
+    print(f"Proposition: {aki.name_proposition}")
+    print(f"Description: {aki.description_proposition}")
+    print(f"Pseudo: {aki.pseudo}")
+    print(f"Photo: {aki.photo}")
+    print(f"Final Message: {aki.question}")
+
+
+Asynchronous Example
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import asyncio
+    import akinator
+
+    aki = akinator.Akinator()
+
+    async def play():
+        await aki.start_game()
+
+        while not aki.finished:
+            print(f"\nQuestion: {str(aki)}")
+            user_input = input(
+                "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
+            ).strip().lower()
+            if user_input == "b":
+                try:
+                    await aki.back()
+                except akinator.CantGoBackAnyFurther:
+                    print("You can't go back any further!")
+            else:
+                try:
+                    await aki.answer(user_input)
+                except akinator.InvalidChoiceError:
+                    print("Invalid answer. Please try again.")
+
+        print("\n--- Game Over ---")
+        print(f"Proposition: {aki.name_proposition}")
+        print(f"Description: {aki.description_proposition}")
+        print(f"Pseudo: {aki.pseudo}")
+        print(f"Photo: {aki.photo}")
+        print(f"Final Message: {aki.question}")
+
+    asyncio.run(play())
+
+
+Advanced Usage
+--------------
+
+- **Languages:** All official Akinator languages are supported (see `LANG_MAP` in the code).
+- **Themes:** Use "c" for characters, "a" for animals, "o" for objects (not all themes are available in all languages).
+- **Error Handling:** All errors raise custom exceptions like `CantGoBackAnyFurther`, `InvalidLanguageError`, `InvalidChoiceError`, and `InvalidThemeError`.
+- **Custom Session:** You can pass your own `cloudscraper.CloudScraper` session for advanced usage.
+- **Async and Sync:** Both sync and async clients are available for all use cases.
+- **Testing:** Comprehensive test suite for both sync and async clients.
+- **Examples:** See the `examples/` directory for CLI and bot scripts.
+
+Links
+-----
+
+- `Akinator <https://akinator.com/>`_
+- `Documentation <https://akinator.readthedocs.io>`_
+- `Examples <https://github.com/Ombucha/akinator.py/tree/main/examples>`_
+- `PyPI <https://pypi.org/project/akinator.py/>`_
+
+Contributing
+------------
+
+Contributions are welcome! Please see the `CONTRIBUTING.md` file for details.
+
+License
+-------
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

akinator.py/akinator/__init__.py

@@ -0,0 +1,21 @@
+"""
+Akinator API Wrapper
+~~~~~~~~~~~~~~~~~~~
+
+A basic API wrapper for Akinator.
+
+:copyright: (c) 2025 Omkaar
+:license: MIT, see LICENSE for more details.
+"""
+
+
+__title__ = "akinator"
+__author__ = "Omkaar"
+__license__ = "MIT"
+__copyright__ = "Copyright 2025 Omkaar"
+__version__ = "2.0.1"
+
+
+from .client import *
+from .exceptions import *
+from .async_client import *

akinator.py/akinator/async_client.py

@@ -0,0 +1,469 @@
+"""
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from typing import Literal, Optional
+from re import search
+from html import unescape
+from asyncio import to_thread
+from cloudscraper import CloudScraper, create_scraper
+
+from .exceptions import CantGoBackAnyFurther, InvalidLanguageError, InvalidThemeError, InvalidChoiceError
+
+
+LANG_MAP = {
+    "english": "en",
+    "arabic": "ar",
+    "chinese": "cn",
+    "german": "de",
+    "spanish": "es",
+    "french": "fr",
+    "hebrew": "il",
+    "italian": "it",
+    "japanese": "jp",
+    "korean": "kr",
+    "dutch": "nl",
+    "polish": "pl",
+    "portuguese": "pt",
+    "russian": "ru",
+    "turkish": "tr",
+    "indonesian": "id",
+}
+
+THEME_IDS = {"c": 1, "a": 14, "o": 2}
+
+# c - characters
+# a - animals
+# o - objects
+
+THEME_MAP = {
+    "en": ["c", "a", "o"],
+    "ar": ["c"],
+    "cn": ["c"],
+    "de": ["c", "a"],
+    "es": ["c", "a"],
+    "fr": ["c", "a", "o"],
+    "il": ["c"],
+    "it": ["c", "a"],
+    "jp": ["c", "a"],
+    "kr": ["c"],
+    "nl": ["c"],
+    "pl": ["c"],
+    "pt": ["c"],
+    "ru": ["c"],
+    "tr": ["c"],
+    "id": ["c"],
+}
+
+ANSWER_IDS = {
+    0: ["yes", "y", "0"],
+    1: ["no", "n", "1"],
+    2: ["i", "idk", "i dont know", "i don't know", "2"],
+    3: ["p", "probably", "3"],
+    4: ["pn", "probably not", "4"],
+}
+
+ANSWER_MAP = {item: key for key, values in ANSWER_IDS.items() for item in values}
+
+class AsyncCloudScraper:
+    """
+    An asynchronous wrapper around `CloudScraper` to handle HTTP requests.
+    """
+    def __init__(self, **kwargs):
+        self.scraper = create_scraper(**kwargs)
+
+    async def post(self, url, data=None, json=None, **kwargs):
+        """
+        An asynchronous method to perform a POST request using the `cloudscraper` library.
+        """
+        return await to_thread(self.scraper.post, url, data=data, json=json, **kwargs)
+
+class AsyncClient:
+
+    """
+    A class representing an asynchronous client for the Akinator game.
+
+    :param session: An optional `CloudScraper` object to use for making HTTP requests. If not provided, a new session will be created.
+    :type session: Optional[CloudScraper]
+    
+    :ivar flag_photo: The URL of the flag photo associated with the current game session.
+    :ivar photo: The URL of the character photo associated with the current game session.
+    :ivar pseudo: The pseudo name of the player in the current game session.
+    :ivar theme: The theme of the game session, which can be "c" (characters), "a" (animals), or "o" (objects).
+    :ivar session_id: The unique identifier for the current game session.
+    :ivar signature: The signature for the current game session.
+    :ivar identifiant: The unique identifier for the player in the current game session.
+    :ivar child_mode: A boolean indicating whether child mode is enabled for the game session.
+    :ivar language: The language used for the game session, represented as a string (e.g., "en" for English).
+    :ivar question: The current question being asked in the game session.
+    :ivar progression: The progression percentage of the game session, represented as a float.
+    :ivar step: The current step number in the game session.
+    :ivar akitude: The current akitude image associated with the game session.
+    :ivar step_last_proposition: The last proposition made in the current step.
+    :ivar finished: A boolean indicating whether the game session has finished.
+    :ivar win: A boolean indicating whether the player has won the game session.
+    :ivar id_proposition: The unique identifier for the current proposition in the game session.
+    :ivar name_proposition: The name of the current proposition in the game session.
+    :ivar description_proposition: The description of the current proposition in the game session.
+    :ivar proposition: The current proposition being made in the game session.
+    :ivar completion: The completion status of the game session, which can be "OK, "KO - TIMEOUT", "SOUNDLIKE", or other values.
+    :ivar confidence: The confidence level of the current question, represented as a float between 0 and 1.
+    :ivar theme_id: The ID of the current theme, represented as an integer.
+    :ivar theme_name: The name of the current theme, represented as a string.
+    :ivar akitude_url: The URL of the current akitude image associated with the game session.
+    """
+
+    def __init__(self, session: Optional[CloudScraper] = None):
+        self.session = session if session else AsyncCloudScraper()
+
+        self.flag_photo = None
+        self.photo = None
+        self.pseudo = None
+        self.theme = None
+        self.session_id = None
+        self.signature = None
+        self.identifiant = None
+        self.child_mode = False
+        self.language = None
+        self.theme = None
+
+        self.question = None
+        self.progression = None
+        self.step = None
+        self.akitude = None
+        self.step_last_proposition = ""
+        self.finished = False
+
+        self.win = False
+        self.id_proposition = None
+        self.name_proposition = None
+        self.description_proposition = None
+        self.proposition = ""
+        self.completion = None
+
+    async def __handler(self, response):
+        response.raise_for_status()
+        try:
+            data = response.json()
+        except Exception as e:
+            if "A technical problem has ocurred." in response.text:
+                raise RuntimeError("A technical problem has occurred. Please try again later.") from e
+            raise RuntimeError("Failed to parse the response as JSON.") from e
+
+        if "completion" not in data:
+            data["completion"] = self.completion
+        if data["completion"] == "KO - TIMEOUT":
+            raise RuntimeError("The session has timed out. Please start a new game.")
+        if data["completion"] == "SOUNDLIKE":
+            self.finished = True
+            self.win = True
+            if not self.id_proposition:
+                self.defeat()
+        elif "id_proposition" in data:
+            self.win = True
+            self.id_proposition = data["id_proposition"]
+            self.name_proposition = data["name_proposition"]
+            self.description_proposition = data["description_proposition"]
+            self.step_last_proposition = self.step
+            self.pseudo = data["pseudo"]
+            self.flag_photo = data["flag_photo"]
+            self.photo = data["photo"]
+        else:
+            self.akitude = data["akitude"]
+            self.step = int(data["step"])
+            self.progression = float(data["progression"])
+            self.question = data["question"]
+        self.completion = data["completion"]
+
+    async def start_game(self, *, language: str = "en", child_mode: bool = False, theme: Literal["c", "a", "o"] = "c"):
+        """
+        Starts a new game session with the specified language, child mode, and theme.
+
+        :param language: The language to use for the game. Defaults to "en" (English).
+        :type language: str
+        :param child_mode: Whether to enable child mode. Defaults to False.
+        :type child_mode: bool
+        :param theme: The theme to use for the game. Can be "c" (characters), "a" (animals), or "o" (objects). Defaults to "c".
+        :type theme: Literal["c", "a", "o"]
+        """
+        if language not in LANG_MAP and language not in LANG_MAP.values():
+            raise InvalidLanguageError(f"Unsupported language: {language}. Supported languages: {', '.join(LANG_MAP.keys())}")
+
+        if theme not in THEME_IDS and theme not in THEME_IDS.values():
+            raise InvalidThemeError(f"Unsupported theme: {theme}. Supported themes: {', '.join(THEME_IDS.keys())}")
+
+        if theme not in THEME_MAP[LANG_MAP.get(language.lower(), language.lower())]:
+            raise InvalidThemeError(f"Theme '{theme}' is not available for language '{language}'.")
+
+        try:
+            self.theme = theme
+            self.language = LANG_MAP.get(language.lower(), language.lower())
+            self.child_mode = child_mode
+
+            response = await self.session.post(f"https://{self.language}.akinator.com/game", data={"sid": THEME_IDS[theme], "cm": str(child_mode).lower()})
+            response.raise_for_status()
+            text = response.text
+
+            self.session_id = search(r"#session'\).val\('(.+?)'\)", text).group(1)
+            self.signature = search(r"#signature'\).val\('(.+?)'\)", text).group(1)
+            self.identifiant = search(r"#identifiant'\).val\('(.+?)'\)", text).group(1)
+
+            if not all([self.session_id, self.signature, self.identifiant]):
+                raise ValueError("Failed to extract session information from the response.")
+
+            question = search(r'<div class="bubble-body"><p class="question-text" id="question-label">(.+)</p></div>', text)
+
+            if not question:
+                raise ValueError("Failed to extract the initial question from the response.")
+
+            self.question = unescape(question.group(1))
+
+            proposition = search(r'<div class="sub-bubble-propose"><p id="p-sub-bubble">([\w\s]+)</p></div>', text)
+
+            if not proposition:
+                raise ValueError("Failed to extract the proposition from the response.")
+
+            self.proposition = unescape(proposition.group(1))
+            self.progression = 0
+            self.step = 0
+            self.akitude = "defi.png"
+        except Exception as e:
+            raise RuntimeError("Failed to start the game.") from e
+
+        return self.session
+
+    async def answer(self, answer: str):
+        """
+        Submits an answer to the current question.
+    
+        :param answer: The answer to submit. Can be "yes", "no", "i don't know", "probably", or "probably not".
+        :type answer: str
+        """
+        if not answer.lower() in ANSWER_MAP:
+            raise InvalidChoiceError(f"Invalid answer: {answer}. Valid answers are: {', '.join(ANSWER_MAP.keys())}")
+        answer_id = ANSWER_MAP[answer.lower()]
+
+        if self.win:
+            if answer_id == 0:
+                return await self.choose()
+            if answer_id == 1:
+                return await self.exclude()
+            raise InvalidChoiceError("Invalid answer after Akinator has proposed a win. Only 'yes' or 'no' are valid answers at this point.")
+
+        url = f"https://{self.language}.akinator.com/answer"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "answer": answer_id,
+            "step_last_proposition": self.step_last_proposition,
+            "session": self.session_id,
+            "signature": self.signature
+        }
+
+        try:
+            response = await self.session.post(url, data=data)
+            await self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to submit the answer.") from e
+
+    async def back(self):
+        """
+        Goes back to the previous question in the game.
+
+        .. note::
+
+            This method can only be called if the current step is greater than 0. If the step is 0, it raises a `CantGoBackAnyFurther` exception.        
+        """
+        if self.step == 0:
+            raise CantGoBackAnyFurther()
+
+        url = f"https://{self.language}.akinator.com/cancel_answer"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "session": self.session_id,
+            "signature": self.signature
+        }
+        self.win = False
+
+        try:
+            response = await self.session.post(url, data=data)
+            await self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to go back to the previous question.") from e
+
+    async def exclude(self):
+        """
+        Excludes the current proposition from the game.
+
+        .. note::
+
+            This method can only be called after Akinator has proposed a win. If the game is already finished, it will call the `defeat` method.
+        """
+        if not self.win:
+            raise RuntimeError("You can only exclude a proposition after Akinator has proposed a win.")
+
+        if self.finished:
+            return await self.defeat()
+
+        url = f"https://{self.language}.akinator.com/exclude"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "session": self.session_id,
+            "signature": self.signature
+        }
+        self.win = False
+        self.id_proposition = ""
+
+        try:
+            response = await self.session.post(url, data=data)
+            await self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to exclude the proposition.") from e
+
+    async def choose(self):
+        """
+        Chooses the current proposition as the answer to the game.
+
+        .. note::
+
+            This method can only be called after Akinator has proposed a win. If the game is already finished, it will raise a `RuntimeError`.
+        """
+        if not self.win:
+            raise RuntimeError("You can only choose a proposition after Akinator has proposed a win.")
+
+        url = f"https://{self.language}.akinator.com/choice"
+        data = {
+            "step": self.step,
+            "sid": THEME_IDS[self.theme],
+            "session": self.session_id,
+            "signature": self.signature,
+            "identifiant": self.identifiant,
+            "pid": self.id_proposition,
+            "charac_name": self.name_proposition,
+            "charac_description": self.description_proposition,
+            "pflag_photo": self.flag_photo
+        }
+
+        try:
+            response = await self.session.post(url, data=data, allow_redirects=True)
+            if response.status_code not in range(200, 400):
+                response.raise_for_status()
+
+            self.finished = True
+            self.win = True
+            self.akitude = "triomphe.png"
+            self.id_proposition = ""
+        except Exception as e:
+            raise RuntimeError("Failed to choose the proposition.") from e
+
+        try:
+            text = response.text
+            win_message = unescape(search(r'<span class="win-sentence">(.+?)<\/span>', text).group(1))
+            already_played = unescape(search(r'let tokenDejaJoue = "([\w\s]+)";', text).group(1))
+            times_selected = search(r'let timesSelected = "(\d+)";', text).group(1)
+            times = unescape(search(r'<span id="timesselected"><\/span>\s+([\w\s]+)<\/span>', text).group(1))
+            self.question = f"{win_message}\n{already_played} {times_selected} {times}"
+        except Exception:
+            pass
+
+        self.progression = 100
+
+    async def defeat(self):
+        """
+        Handles the defeat scenario in the game.
+        """
+        self.finished = True
+        self.win = False
+        self.akitude = "deception.png"
+        self.id_proposition = ""
+
+        questions = {
+            "en": "Bravo, you have defeated me !\nShare your feat with your friends.",
+            "ar": "أحسنت، لقد هزمتني !\nشارك إنجازك مع أصدقائك.",
+            "cn": "太棒了，你打败了我！\n与朋友分享你的成就吧。",
+            "de": "Bravo, du hast mich besiegt !\nTeile deinen Erfolg mit deinen Freunden.",
+            "es": "¡Bravo, me has derrotado !\nComparte tu hazaña con tus amigos.",
+            "fr": "Bravo, tu m'as vaincu  !\nPartage ton exploit avec tes amis.",
+            "il": "כל הכבוד, הצלחת להביס אותי !\nשתף את ההישג שלך עם חברים.",
+            "it": "Bravo, mi hai sconfitto !\nCondividi la tua impresa con i tuoi amici.",
+            "jp": "すごい、あなたは私を倒しました！\nこの偉業を友達と共有しましょう。",
+            "kr": "브라보, 당신이 저를 이겼습니다 !\n당신의 업적을 친구들과 공유하세요.",
+            "nl": "Bravo, je hebt me verslagen !\nDeel je prestatie met je vrienden.",
+            "pl": "Brawo, pokonałeś mnie !\nPodziel się swoim wyczynem ze znajomymi.",
+            "pt": "Bravo, você me derrotou !\nCompartilhe sua conquista com seus amigos.",
+            "ru": "Браво, ты победил меня !\nПоделись своим достижением с друзьями.",
+            "tr": "Bravo, beni yendin !\nBu başarını arkadaşlarınla paylaş.",
+            "id": "Hebat, kamu mengalahkanku !\nBagikan pencapaianmu kepada teman-temanmu.",
+        }
+
+        self.question = questions[self.language]
+        self.progression = 100
+
+    @property
+    def confidence(self) -> float:
+        """
+        Returns the confidence level of the current question.
+        """
+        return self.progression / 100
+
+    @property
+    def theme_id(self) -> int:
+        """
+        Returns the ID of the current theme.
+        """
+        return THEME_IDS[self.theme]
+
+    @property
+    def theme_name(self) -> str:
+        """
+        Returns the name of the current theme.
+        """
+        return "Characters" if self.theme == "c" else "Animals" if self.theme == "a" else "Objects"
+
+    @property
+    def akitude_url(self) -> str:
+        """
+        Returns the URL of the current akitude image.
+        """
+        return f"https://{self.language}.akinator.com/assets/img/akitudes_670x1096/{self.akitude}"
+
+    def __str__(self):
+        if self.win and not self.finished:
+            return f"{self.proposition} {self.name_proposition} ({self.description_proposition})"
+        return self.question
+
+    def __repr__(self):
+        return f"<Akinator Client (Language: {self.language}, Theme: {self.theme_name}, Step: {self.step}, Progression: {self.progression}%)>"
+
+class AsyncAkinator(AsyncClient):
+    """
+    A class identical to `AsyncClient`, but created for compatibility with the previous version of the library.
+    """

akinator.py/akinator/client.py

@@ -0,0 +1,454 @@
+"""
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from typing import Literal, Optional
+from re import search
+from html import unescape
+from cloudscraper import CloudScraper, create_scraper
+
+from .exceptions import CantGoBackAnyFurther, InvalidLanguageError, InvalidChoiceError, InvalidThemeError
+
+LANG_MAP = {
+    "english": "en",
+    "arabic": "ar",
+    "chinese": "cn",
+    "german": "de",
+    "spanish": "es",
+    "french": "fr",
+    "hebrew": "il",
+    "italian": "it",
+    "japanese": "jp",
+    "korean": "kr",
+    "dutch": "nl",
+    "polish": "pl",
+    "portuguese": "pt",
+    "russian": "ru",
+    "turkish": "tr",
+    "indonesian": "id",
+}
+
+THEME_IDS = {"c": 1, "a": 14, "o": 2}
+
+# c - characters
+# a - animals
+# o - objects
+
+THEME_MAP = {
+    "en": ["c", "a", "o"],
+    "ar": ["c"],
+    "cn": ["c"],
+    "de": ["c", "a"],
+    "es": ["c", "a"],
+    "fr": ["c", "a", "o"],
+    "il": ["c"],
+    "it": ["c", "a"],
+    "jp": ["c", "a"],
+    "kr": ["c"],
+    "nl": ["c"],
+    "pl": ["c"],
+    "pt": ["c"],
+    "ru": ["c"],
+    "tr": ["c"],
+    "id": ["c"],
+}
+
+ANSWER_IDS = {
+    0: ["yes", "y", "0"],
+    1: ["no", "n", "1"],
+    2: ["i", "idk", "i dont know", "i don't know", "2"],
+    3: ["p", "probably", "3"],
+    4: ["pn", "probably not", "4"],
+}
+
+ANSWER_MAP = {item: key for key, values in ANSWER_IDS.items() for item in values}
+
+class Client:
+
+    """
+    A class representing a client for the Akinator game.
+
+    :param session: An optional `CloudScraper` object to use for making HTTP requests. If not provided, a new session will be created.
+    :type session: Optional[CloudScraper]
+
+    :ivar flag_photo: The URL of the flag photo associated with the current game session.
+    :ivar photo: The URL of the character photo associated with the current game session.
+    :ivar pseudo: The pseudo name of the player in the current game session.
+    :ivar theme: The theme of the game session, which can be "c" (characters), "a" (animals), or "o" (objects).
+    :ivar session_id: The unique identifier for the current game session.
+    :ivar signature: The signature for the current game session.
+    :ivar identifiant: The unique identifier for the player in the current game session.
+    :ivar child_mode: A boolean indicating whether child mode is enabled for the game session.
+    :ivar language: The language used for the game session, represented as a string (e.g., "en" for English).
+    :ivar question: The current question being asked in the game session.
+    :ivar progression: The progression percentage of the game session, represented as a float.
+    :ivar step: The current step number in the game session.
+    :ivar akitude: The current akitude image associated with the game session.
+    :ivar step_last_proposition: The last proposition made in the current step.
+    :ivar finished: A boolean indicating whether the game session has finished.
+    :ivar win: A boolean indicating whether the player has won the game session.
+    :ivar id_proposition: The unique identifier for the current proposition in the game session.
+    :ivar name_proposition: The name of the current proposition in the game session.
+    :ivar description_proposition: The description of the current proposition in the game session.
+    :ivar proposition: The current proposition being made in the game session.
+    :ivar completion: The completion status of the game session, which can be "OK, "KO - TIMEOUT", "SOUNDLIKE", or other values.
+    :ivar confidence: The confidence level of the current question, represented as a float between 0 and 1.
+    :ivar theme_id: The ID of the current theme, represented as an integer.
+    :ivar theme_name: The name of the current theme, represented as a string.
+    :ivar akitude_url: The URL of the current akitude image associated with the game session.
+    """
+
+    def __init__(self, session: Optional[CloudScraper] = None):
+        self.session = session if session else create_scraper()
+
+        self.flag_photo = None
+        self.photo = None
+        self.pseudo = None
+        self.theme = None
+        self.session_id = None
+        self.signature = None
+        self.identifiant = None
+        self.child_mode = False
+        self.language = None
+        self.theme = None
+
+        self.question = None
+        self.progression = None
+        self.step = None
+        self.akitude = None
+        self.step_last_proposition = ""
+        self.finished = False
+
+        self.win = False
+        self.id_proposition = None
+        self.name_proposition = None
+        self.description_proposition = None
+        self.proposition = ""
+        self.completion = None
+
+    def __handler(self, response):
+        response.raise_for_status()
+        try:
+            data = response.json()
+        except Exception as e:
+            if "A technical problem has ocurred." in response.text:
+                raise RuntimeError("A technical problem has occurred. Please try again later.") from e
+            raise RuntimeError("Failed to parse the response as JSON.") from e
+
+        if "completion" not in data:
+            data["completion"] = self.completion
+        if data["completion"] == "KO - TIMEOUT":
+            raise RuntimeError("The session has timed out. Please start a new game.")
+        if data["completion"] == "SOUNDLIKE":
+            self.finished = True
+            self.win = True
+            if not self.id_proposition:
+                self.defeat()
+        elif "id_proposition" in data:
+            self.win = True
+            self.id_proposition = data["id_proposition"]
+            self.name_proposition = data["name_proposition"]
+            self.description_proposition = data["description_proposition"]
+            self.step_last_proposition = self.step
+            self.pseudo = data["pseudo"]
+            self.flag_photo = data["flag_photo"]
+            self.photo = data["photo"]
+        else:
+            self.akitude = data["akitude"]
+            self.step = int(data["step"])
+            self.progression = float(data["progression"])
+            self.question = data["question"]
+        self.completion = data["completion"]
+
+    def start_game(self, *, language: str = "en", child_mode: bool = False, theme: Literal["c", "a", "o"] = "c"):
+        """
+        Starts a new game session with the specified language, child mode, and theme.
+
+        :param language: The language to use for the game. Defaults to "en" (English).
+        :type language: str
+        :param child_mode: Whether to enable child mode. Defaults to False.
+        :type child_mode: bool
+        :param theme: The theme to use for the game. Can be "c" (characters), "a" (animals), or "o" (objects). Defaults to "c".
+        :type theme: Literal["c", "a", "o"]
+        """
+        if language not in LANG_MAP and language not in LANG_MAP.values():
+            raise InvalidLanguageError(f"Unsupported language: {language}. Supported languages: {', '.join(LANG_MAP.keys())}")
+
+        if theme not in THEME_IDS and theme not in THEME_IDS.values():
+            raise InvalidThemeError(f"Unsupported theme: {theme}. Supported themes: {', '.join(THEME_IDS.keys())}")
+
+        if theme not in THEME_MAP[LANG_MAP.get(language.lower(), language.lower())]:
+            raise InvalidThemeError(f"Theme '{theme}' is not available for language '{language}'.")
+
+        try:
+            self.theme = theme
+            self.language = LANG_MAP.get(language.lower(), language.lower())
+            self.child_mode = child_mode
+
+            response = self.session.post(f"https://{self.language}.akinator.com/game", data={"sid": THEME_IDS[theme], "cm": str(child_mode).lower()})
+            response.raise_for_status()
+            text = response.text
+
+            self.session_id = search(r"#session'\).val\('(.+?)'\)", text).group(1)
+            self.signature = search(r"#signature'\).val\('(.+?)'\)", text).group(1)
+            self.identifiant = search(r"#identifiant'\).val\('(.+?)'\)", text).group(1)
+
+            if not all([self.session_id, self.signature, self.identifiant]):
+                raise ValueError("Failed to extract session information from the response.")
+
+            question = search(r'<div class="bubble-body"><p class="question-text" id="question-label">(.+)</p></div>', text)
+
+            if not question:
+                raise ValueError("Failed to extract the initial question from the response.")
+
+            self.question = unescape(question.group(1))
+
+            proposition = search(r'<div class="sub-bubble-propose"><p id="p-sub-bubble">([\w\s]+)</p></div>', text)
+
+            if not proposition:
+                raise ValueError("Failed to extract the proposition from the response.")
+
+            self.proposition = unescape(proposition.group(1))
+            self.progression = 0
+            self.step = 0
+            self.akitude = "defi.png"
+        except Exception as e:
+            raise RuntimeError("Failed to start the game.") from e
+
+        return self.session
+
+    def answer(self, answer: str):
+        """
+        Submits an answer to the current question.
+    
+        :param answer: The answer to submit. Can be "yes", "no", "i don't know", "probably", or "probably not".
+        :type answer: str
+        """
+        if not answer.lower() in ANSWER_MAP:
+            raise InvalidChoiceError(f"Invalid answer: {answer}. Valid answers are: {', '.join(ANSWER_MAP.keys())}")
+        answer_id = ANSWER_MAP[answer.lower()]
+
+        if self.win:
+            if answer_id == 0:
+                return self.choose()
+            if answer_id == 1:
+                return self.exclude()
+            raise InvalidChoiceError("Invalid answer after Akinator has proposed a win. Only 'yes' or 'no' are valid answers at this point.")
+
+        url = f"https://{self.language}.akinator.com/answer"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "answer": answer_id,
+            "step_last_proposition": self.step_last_proposition,
+            "session": self.session_id,
+            "signature": self.signature
+        }
+
+        try:
+            response = self.session.post(url, data=data)
+            self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to submit the answer.") from e
+
+    def back(self):
+        """
+        Goes back to the previous question in the game.
+
+        .. note::
+
+            This method can only be called if the current step is greater than 0. If the step is 0, it raises a `CantGoBackAnyFurther` exception.        
+        """
+        if self.step == 0:
+            raise CantGoBackAnyFurther()
+
+        url = f"https://{self.language}.akinator.com/cancel_answer"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "session": self.session_id,
+            "signature": self.signature
+        }
+        self.win = False
+
+        try:
+            response = self.session.post(url, data=data)
+            self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to go back to the previous question.") from e
+
+    def exclude(self):
+        """
+        Excludes the current proposition from the game.
+
+        .. note::
+
+            This method can only be called after Akinator has proposed a win. If the game is already finished, it will call the `defeat` method.
+        """
+        if not self.win:
+            raise RuntimeError("You can only exclude a proposition after Akinator has proposed a win.")
+
+        if self.finished:
+            return self.defeat()
+
+        url = f"https://{self.language}.akinator.com/exclude"
+        data = {
+            "step": self.step,
+            "progression": self.progression,
+            "sid": THEME_IDS[self.theme],
+            "cm": str(self.child_mode).lower(),
+            "session": self.session_id,
+            "signature": self.signature
+        }
+        self.win = False
+        self.id_proposition = ""
+
+        try:
+            response = self.session.post(url, data=data)
+            self.__handler(response)
+        except Exception as e:
+            raise RuntimeError("Failed to exclude the proposition.") from e
+
+    def choose(self):
+        """
+        Chooses the current proposition as the answer to the game.
+
+        .. note::
+
+            This method can only be called after Akinator has proposed a win. If the game is already finished, it will raise a `RuntimeError`.
+        """
+        if not self.win:
+            raise RuntimeError("You can only choose a proposition after Akinator has proposed a win.")
+
+        url = f"https://{self.language}.akinator.com/choice"
+        data = {
+            "step": self.step,
+            "sid": THEME_IDS[self.theme],
+            "session": self.session_id,
+            "signature": self.signature,
+            "identifiant": self.identifiant,
+            "pid": self.id_proposition,
+            "charac_name": self.name_proposition,
+            "charac_description": self.description_proposition,
+            "pflag_photo": self.flag_photo
+        }
+
+        try:
+            response = self.session.post(url, data=data, allow_redirects=True)
+            if response.status_code not in range(200, 400):
+                response.raise_for_status()
+
+            self.finished = True
+            self.win = True
+            self.akitude = "triomphe.png"
+            self.id_proposition = ""
+        except Exception as e:
+            raise RuntimeError("Failed to choose the proposition.") from e
+
+        try:
+            text = response.text
+            win_message = unescape(search(r'<span class="win-sentence">(.+?)<\/span>', text).group(1))
+            already_played = unescape(search(r'let tokenDejaJoue = "([\w\s]+)";', text).group(1))
+            times_selected = search(r'let timesSelected = "(\d+)";', text).group(1)
+            times = unescape(search(r'<span id="timesselected"><\/span>\s+([\w\s]+)<\/span>', text).group(1))
+            self.question = f"{win_message}\n{already_played} {times_selected} {times}"
+        except Exception:
+            pass
+
+        self.progression = 100
+
+    def defeat(self):
+        """
+        Handles the defeat scenario in the game.
+        """
+        self.finished = True
+        self.win = False
+        self.akitude = "deception.png"
+        self.id_proposition = ""
+
+        questions = {
+            "en": "Bravo, you have defeated me !\nShare your feat with your friends.",
+            "ar": "أحسنت، لقد هزمتني !\nشارك إنجازك مع أصدقائك.",
+            "cn": "太棒了，你打败了我！\n与朋友分享你的成就吧。",
+            "de": "Bravo, du hast mich besiegt !\nTeile deinen Erfolg mit deinen Freunden.",
+            "es": "¡Bravo, me has derrotado !\nComparte tu hazaña con tus amigos.",
+            "fr": "Bravo, tu m'as vaincu  !\nPartage ton exploit avec tes amis.",
+            "il": "כל הכבוד, הצלחת להביס אותי !\nשתף את ההישג שלך עם חברים.",
+            "it": "Bravo, mi hai sconfitto !\nCondividi la tua impresa con i tuoi amici.",
+            "jp": "すごい、あなたは私を倒しました！\nこの偉業を友達と共有しましょう。",
+            "kr": "브라보, 당신이 저를 이겼습니다 !\n당신의 업적을 친구들과 공유하세요.",
+            "nl": "Bravo, je hebt me verslagen !\nDeel je prestatie met je vrienden.",
+            "pl": "Brawo, pokonałeś mnie !\nPodziel się swoim wyczynem ze znajomymi.",
+            "pt": "Bravo, você me derrotou !\nCompartilhe sua conquista com seus amigos.",
+            "ru": "Браво, ты победил меня !\nПоделись своим достижением с друзьями.",
+            "tr": "Bravo, beni yendin !\nBu başarını arkadaşlarınla paylaş.",
+            "id": "Hebat, kamu mengalahkanku !\nBagikan pencapaianmu kepada teman-temanmu.",
+        }
+
+        self.question = questions[self.language]
+        self.progression = 100
+
+    @property
+    def confidence(self) -> float:
+        """
+        Returns the confidence level of the current question.
+        """
+        return self.progression / 100
+
+    @property
+    def theme_id(self) -> int:
+        """
+        Returns the ID of the current theme.
+        """
+        return THEME_IDS[self.theme]
+
+    @property
+    def theme_name(self) -> str:
+        """
+        Returns the name of the current theme.
+        """
+        return "Characters" if self.theme == "c" else "Animals" if self.theme == "a" else "Objects"
+
+    @property
+    def akitude_url(self) -> str:
+        """
+        Returns the URL of the current akitude image.
+        """
+        return f"https://{self.language}.akinator.com/assets/img/akitudes_670x1096/{self.akitude}"
+
+    def __str__(self):
+        if self.win and not self.finished:
+            return f"{self.proposition} {self.name_proposition} ({self.description_proposition})"
+        return self.question
+
+    def __repr__(self):
+        return f"<Akinator Client (Language: {self.language}, Theme: {self.theme_name}, Step: {self.step}, Progression: {self.progression}%)>"
+
+class Akinator(Client):
+    """
+    A class identical to `Client`, but created for compatibility with the previous version of the library.
+    """

akinator.py/akinator/exceptions.py

@@ -0,0 +1,47 @@
+"""
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+
+class AkinatorException(Exception):
+    """Base exception for Akinator-related errors."""
+
+class CantGoBackAnyFurther(AkinatorException):
+    """Raised when the user tries to go back but cannot."""
+    def __init__(self, message: str = "You are already at the first question."):
+        super().__init__(message)
+
+class InvalidLanguageError(AkinatorException):
+    """Raised when an invalid language is specified."""
+    def __init__(self, message: str = "Invalid language specified."):
+        super().__init__(message)
+
+class InvalidChoiceError(AkinatorException):
+    """Raised when an invalid choice is made."""
+    def __init__(self, message: str = "Invalid choice. Please choose a valid option."):
+        super().__init__(message)
+
+class InvalidThemeError(AkinatorException):
+    """Raised when an invalid theme is specified."""
+    def __init__(self, message: str = "Invalid theme specified."):
+        super().__init__(message)

akinator.py/docs/conf.py

@@ -0,0 +1,15 @@
+# pylint: skip-file
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath(".."))
+
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+project = "akinator.py"
+copyright = "2025, Omkaar"
+author = "Ombucha"
+release = "2.0.1"
+
+extensions = ["sphinx.ext.autodoc"]

akinator.py/docs/index.rst

@@ -0,0 +1,62 @@
+akinator.py
+==========
+
+Installation
+------------
+
+**Python 3.3 or higher is required.**
+
+To install the stable version, do the following:
+
+.. code-block:: sh
+
+    # Unix / macOS
+    python3 -m pip install "akinator"
+
+    # Windows
+    py -m pip install "akinator"
+
+
+To install the development version, do the following:
+
+.. code-block:: sh
+
+    $ git clone https://github.com/Ombucha/akinator.py
+
+Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.9 or greater.
+
+If you have have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as possible. Include the output in your terminal, your OS details and Python version.
+
+
+Client
+-----
+
+.. autoclass:: akinator.Client
+    :members:
+
+.. autoclass:: akinator.Akinator
+    :members:
+
+.. autoclass:: akinator.AsyncClient
+    :members:
+
+.. autoclass:: akinator.AsyncAkinator
+    :members:
+
+Exceptions
+---------------
+
+.. autoclass:: akinator.AkinatorException
+    :members:
+
+.. autoclass:: akinator.CantGoBackAnyFurther
+    :members:
+
+.. autoclass:: akinator.InvalidChoiceError
+    :members:
+
+.. autoclass:: akinator.InvalidThemeError
+    :members:
+
+.. autoclass:: akinator.InvalidLanguageError
+    :members:

akinator.py/docs/requirements.txt

@@ -0,0 +1 @@
+sphinx

akinator.py/examples/basic.py

@@ -0,0 +1,29 @@
+# pylint: skip-file
+
+import akinator
+
+aki = akinator.Akinator()
+aki.start_game()
+
+while not aki.finished:
+    print(f"\nQuestion: {str(aki)}")
+    user_input = input(
+        "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
+    ).strip().lower()
+    if user_input == "b":
+        try:
+            aki.back()
+        except akinator.CantGoBackAnyFurther:
+            print("You can't go back any further!")
+    else:
+        try:
+            aki.answer(user_input)
+        except akinator.InvalidChoiceError:
+            print("Invalid answer. Please try again.")
+
+print("\n--- Game Over ---")
+print(f"Proposition: {aki.name_proposition}")
+print(f"Description: {aki.description_proposition}")
+print(f"Pseudo: {aki.pseudo}")
+print(f"Photo: {aki.photo}")
+print(f"Final Message: {aki.question}")

akinator.py/examples/basic_async.py

@@ -0,0 +1,34 @@
+# pylint: skip-file
+
+import asyncio
+import akinator
+
+aki = akinator.Akinator()
+
+async def play():
+    await aki.start_game()
+
+    while not aki.finished:
+        print(f"\nQuestion: {str(aki)}")
+        user_input = input(
+            "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
+        ).strip().lower()
+        if user_input == "b":
+            try:
+                await aki.back()
+            except akinator.CantGoBackAnyFurther:
+                print("You can't go back any further!")
+        else:
+            try:
+                await aki.answer(user_input)
+            except akinator.InvalidChoiceError:
+                print("Invalid answer. Please try again.")
+
+    print("\n--- Game Over ---")
+    print(f"Proposition: {aki.name_proposition}")
+    print(f"Description: {aki.description_proposition}")
+    print(f"Pseudo: {aki.pseudo}")
+    print(f"Photo: {aki.photo}")
+    print(f"Final Message: {aki.question}")
+
+asyncio.run(play())

akinator.py/examples/discord_bot.py

@@ -0,0 +1,125 @@
+# pylint: skip-file
+
+import discord
+import akinator
+
+from discord.ext import commands
+
+intents = discord.Intents.default()
+bot = commands.Bot(command_prefix="!", intents=intents)
+
+class AkiView(discord.ui.View):
+    def __init__(self, aki, user):
+        super().__init__(timeout=120)
+        self.aki = aki
+        self.user = user
+        self.value = None
+
+    async def interaction_check(self, interaction: discord.Interaction) -> bool:
+        return interaction.user == self.user
+
+    @discord.ui.button(label="Yes", style=discord.ButtonStyle.green, row=0)
+    async def yes(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "yes"
+        self.stop()
+
+    @discord.ui.button(label="No", style=discord.ButtonStyle.red, row=0)
+    async def no(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "no"
+        self.stop()
+
+    @discord.ui.button(label="Probably", style=discord.ButtonStyle.blurple, row=1)
+    async def probably(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "p"
+        self.stop()
+
+    @discord.ui.button(label="Probably Not", style=discord.ButtonStyle.blurple, row=1)
+    async def probably_not(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "pn"
+        self.stop()
+
+    @discord.ui.button(label="I don't know", style=discord.ButtonStyle.gray, row=1)
+    async def idk(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "i"
+        self.stop()
+
+    @discord.ui.button(label="Back", style=discord.ButtonStyle.secondary, row=2)
+    async def back(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "back"
+        self.stop()
+
+class GuessView(discord.ui.View):
+    def __init__(self, user):
+        super().__init__(timeout=60)
+        self.user = user
+        self.value = None
+
+    async def interaction_check(self, interaction: discord.Interaction) -> bool:
+        return interaction.user == self.user
+
+    @discord.ui.button(label="Yes", style=discord.ButtonStyle.green, row=0)
+    async def yes(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "yes"
+        self.stop()
+
+    @discord.ui.button(label="No", style=discord.ButtonStyle.red, row=0)
+    async def no(self, interaction: discord.Interaction, button: discord.ui.Button):
+        await interaction.response.defer()
+        self.value = "no"
+        self.stop()
+
+@bot.tree.command(name="akinator", description="Play Akinator in Discord!")
+async def akinator_slash(interaction: discord.Interaction):
+    await interaction.response.defer()
+    aki = akinator.AsyncAkinator()
+    await aki.start_game()
+    embed = discord.Embed(title="Akinator", description=aki.question, color=discord.Color.blurple())
+    embed.set_image(url=aki.akitude_url)
+    view = AkiView(aki, interaction.user)
+    message = await interaction.edit_original_response(embed=embed, view=view)
+    while not aki.finished:
+        await view.wait()
+        if view.value == "back":
+            try:
+                await aki.back()
+            except akinator.CantGoBackAnyFurther:
+                await message.edit(content="You can't go back any further!", embed=None, view=None)
+                return
+        elif view.value in ["yes", "no", "i", "p", "pn"]:
+            try:
+                await aki.answer(view.value)
+            except akinator.InvalidChoiceError:
+                await message.edit(content="Invalid answer. Please try again.", embed=None, view=None)
+                return
+        else:
+            await message.edit(content="Game timed out or cancelled.", embed=None, view=None)
+            return
+        desc = str(aki)
+        embed = discord.Embed(title="Akinator", description=desc, color=discord.Color.blurple())
+        embed.set_image(url=aki.akitude_url)
+        if desc.strip().lower().startswith("i think of"):
+            view = GuessView(interaction.user)
+        else:
+            view = AkiView(aki, interaction.user)
+        await message.edit(embed=embed, view=view)
+    result = discord.Embed(title="Akinator's Guess!", color=discord.Color.gold())
+    result.add_field(name="Proposition", value=aki.name_proposition or "?", inline=False)
+    result.add_field(name="Description", value=aki.description_proposition or "?", inline=False)
+    if aki.photo:
+        result.set_image(url=aki.photo)
+    result.set_footer(text=aki.question)
+    await message.edit(embed=result, view=None)
+
+@bot.event
+async def on_ready():
+    await bot.tree.sync()
+    print(f"Logged in as {bot.user}")
+
+bot.run('TOKEN')

akinator.py/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "akinator.py"
+version = "2.0.1"
+description = "A basic API wrapper for Akinator."
+authors = ["Ombucha <omkaar.nerurkar@gmail.com>"]
+license = "MIT"
+readme = "README.rst"
+repository = "https://github.com/Ombucha/akinator.py/"
+documentation = "https://akinator.readthedocs.io/"
+keywords = ["python", "akinator"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+packages = ["akinator"]
+
+[tool.poetry.dependencies]
+cloudscraper = "*"
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/Ombucha/akinator.py/issues"

akinator.py/requirements.txt

@@ -0,0 +1 @@
+cloudscraper

akinator.py/setup.py

@@ -0,0 +1,30 @@
+# pylint: skip-file
+
+from pathlib import Path
+
+from setuptools import setup
+
+HERE = Path(__file__).resolve().parent
+README = (HERE / "README.rst").read_text()
+
+setup(
+    name = "akinator",
+    version = "2.0.1",
+    description = "A basic API wrapper for Akinator.",
+    long_description = README,
+    long_description_content_type = "text/x-rst",
+    url = "https://github.com/Ombucha/akinator.py",
+    author = "Omkaar",
+    author_email = "omkaar.nerurkar@gmail.com",
+    license = "MIT",
+    classifiers = [
+        "License :: OSI Approved :: MIT License",
+        "Natural Language :: English",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    python_requires='>= 3.9.0',
+    packages = ["akinator"],
+    include_package_data = True,
+    install_requires = ["cloudscraper"]
+)

akinator.py/tests/test_async_client.py

@@ -0,0 +1,172 @@
+"""
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+
+# pylint: skip-file
+
+import unittest
+
+from akinator import AsyncClient, CantGoBackAnyFurther, InvalidLanguageError, InvalidChoiceError, InvalidThemeError
+
+
+class TestAkinatorAsyncClient(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.client = AsyncClient()
+
+    async def test_init_defaults(self):
+        c = AsyncClient()
+        self.assertIsNotNone(c.session)
+        self.assertIsNone(c.language)
+        self.assertIsNone(c.theme)
+        self.assertFalse(c.child_mode)
+        self.assertFalse(c.finished)
+        self.assertFalse(c.win)
+
+    async def test_language_validation(self):
+        with self.assertRaises(InvalidLanguageError):
+            await self.client.start_game(language="notalanguage")
+        await self.client.start_game(language="en")
+        await self.client.start_game(language="english")
+
+    async def test_theme_validation(self):
+        with self.assertRaises(InvalidThemeError):
+            await self.client.start_game(theme="z")
+        with self.assertRaises(InvalidThemeError):
+            await self.client.start_game(language="ar", theme="a")
+        await self.client.start_game(theme="c")
+
+    async def test_answer_validation(self):
+        await self.client.start_game()
+        with self.assertRaises(InvalidChoiceError):
+            await self.client.answer("notananswer")
+
+    async def test_full_game_flow(self):
+        await self.client.start_game(language="en", theme="c")
+        steps = 0
+        while not self.client.finished and steps < 10:
+            try:
+                await self.client.answer("yes")
+            except InvalidChoiceError:
+                await self.client.answer("no")
+            steps += 1
+        self.assertTrue(self.client.finished or steps == 10)
+
+    async def test_back_and_exclude(self):
+        await self.client.start_game(language="en", theme="c")
+        with self.assertRaises(CantGoBackAnyFurther):
+            await self.client.back()
+        await self.client.answer("yes")
+        try:
+            await self.client.back()
+        except Exception:
+            self.fail("back() raised unexpectedly after moving forward")
+        self.client.win = False
+        with self.assertRaises(RuntimeError):
+            await self.client.exclude()
+
+    async def test_properties_and_str(self):
+        self.client.theme = "c"
+        self.client.progression = 50
+        self.assertEqual(self.client.confidence, 0.5)
+        self.assertEqual(self.client.theme_id, 1)
+        self.assertEqual(self.client.theme_name, "Characters")
+        self.client.language = "en"
+        self.client.akitude = "defi.png"
+        self.assertIn("defi.png", self.client.akitude_url)
+        self.client.win = True
+        self.client.finished = False
+        self.client.proposition = "prop"
+        self.client.name_proposition = "name"
+        self.client.description_proposition = "desc"
+        self.assertIn("name", str(self.client))
+        self.client.finished = True
+        self.client.question = "Q?"
+        self.assertEqual(str(self.client), "Q?")
+        self.client.theme = "a"
+        self.assertEqual(self.client.theme_name, "Animals")
+        self.client.theme = "o"
+        self.assertEqual(self.client.theme_name, "Objects")
+
+    async def test_repr(self):
+        self.client.language = "en"
+        self.client.theme = "c"
+        self.client.step = 5
+        self.client.progression = 80
+        rep = repr(self.client)
+        self.assertIn("Akinator Client", rep)
+        self.assertIn("Language: en", rep)
+        self.assertIn("Theme: Characters", rep)
+        self.assertIn("Step: 5", rep)
+        self.assertIn("Progression: 80", rep)
+
+    async def test_defeat_sets_state(self):
+        self.client.language = "en"
+        await self.client.defeat()
+        self.assertTrue(self.client.finished)
+        self.assertFalse(self.client.win)
+        self.assertEqual(self.client.akitude, "deception.png")
+        self.assertEqual(self.client.question, "Bravo, you have defeated me !\nShare your feat with your friends.")
+        self.assertEqual(self.client.progression, 100)
+
+    async def test_choose_without_win(self):
+        await self.client.start_game(language="en", theme="c")
+        self.client.win = False
+        with self.assertRaises(RuntimeError):
+            await self.client.choose()
+
+    async def test_exclude_after_win_and_finished(self):
+        await self.client.start_game(language="en", theme="c")
+        self.client.win = True
+        self.client.finished = True
+        self.client.language = "en"
+        await self.client.defeat()
+        self.assertTrue(self.client.finished)
+        self.assertFalse(self.client.win)
+        self.assertEqual(self.client.akitude, "deception.png")
+
+    async def test_theme_ids_and_names(self):
+        self.client.theme = "c"
+        self.assertEqual(self.client.theme_id, 1)
+        self.assertEqual(self.client.theme_name, "Characters")
+        self.client.theme = "a"
+        self.assertEqual(self.client.theme_id, 14)
+        self.assertEqual(self.client.theme_name, "Animals")
+        self.client.theme = "o"
+        self.assertEqual(self.client.theme_id, 2)
+        self.assertEqual(self.client.theme_name, "Objects")
+
+    async def test_repr_and_str_edge_cases(self):
+        self.client.language = None
+        self.client.theme = None
+        self.client.step = None
+        self.client.progression = None
+        rep = repr(self.client)
+        self.assertIn("Akinator Client", rep)
+        self.client.win = False
+        self.client.finished = False
+        self.client.question = "TestQ"
+        self.assertEqual(str(self.client), "TestQ")
+
+if __name__ == "__main__":
+    unittest.main()

akinator.py/tests/test_client.py

@@ -0,0 +1,178 @@
+"""
+MIT License
+
+Copyright (c) 2025 Omkaar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+
+# pylint: skip-file
+
+import unittest
+
+from akinator import Client, CantGoBackAnyFurther, InvalidLanguageError, InvalidChoiceError, InvalidThemeError
+
+
+class TestAkinatorClient(unittest.TestCase):
+    def setUp(self):
+        self.client = Client()
+
+    def test_init_defaults(self):
+        c = Client()
+        self.assertIsNotNone(c.session)
+        self.assertIsNone(c.language)
+        self.assertIsNone(c.theme)
+        self.assertFalse(c.child_mode)
+        self.assertFalse(c.finished)
+        self.assertFalse(c.win)
+
+    def test_language_validation(self):
+        with self.assertRaises(InvalidLanguageError):
+            self.client.start_game(language="notalanguage")
+        # Should not raise
+        self.client.start_game(language="en")
+        self.client.start_game(language="english")
+
+    def test_theme_validation(self):
+        with self.assertRaises(InvalidThemeError):
+            self.client.start_game(theme="z")
+        with self.assertRaises(InvalidThemeError):
+            self.client.start_game(language="ar", theme="a")  # 'a' not in ar
+        # Should not raise
+        self.client.start_game(theme="c")
+
+    def test_answer_validation(self):
+        self.client.start_game()
+        with self.assertRaises(InvalidChoiceError):
+            self.client.answer("notananswer")
+
+    def test_full_game_flow(self):
+        self.client.start_game(language="en", theme="c")
+        steps = 0
+        while not self.client.finished and steps < 10:
+            # Always answer 'yes' for simplicity
+            try:
+                self.client.answer("yes")
+            except InvalidChoiceError:
+                self.client.answer("no")
+            steps += 1
+        self.assertTrue(self.client.finished or steps == 10)
+
+    def test_back_and_exclude(self):
+        self.client.start_game(language="en", theme="c")
+        with self.assertRaises(CantGoBackAnyFurther):
+            self.client.back()
+        # Move forward one step
+        self.client.answer("yes")
+        try:
+            self.client.back()
+        except Exception:
+            self.fail("back() raised unexpectedly after moving forward")
+        # Exclude only after win
+        self.client.win = False
+        with self.assertRaises(RuntimeError):
+            self.client.exclude()
+
+    def test_properties_and_str(self):
+        self.client.theme = "c"
+        self.client.progression = 50
+        self.assertEqual(self.client.confidence, 0.5)
+        self.assertEqual(self.client.theme_id, 1)
+        self.assertEqual(self.client.theme_name, "Characters")
+        self.client.language = "en"
+        self.client.akitude = "defi.png"
+        self.assertIn("defi.png", self.client.akitude_url)
+        self.client.win = True
+        self.client.finished = False
+        self.client.proposition = "prop"
+        self.client.name_proposition = "name"
+        self.client.description_proposition = "desc"
+        self.assertIn("name", str(self.client))
+        self.client.finished = True
+        self.client.question = "Q?"
+        self.assertEqual(str(self.client), "Q?")
+        self.client.theme = "a"
+        self.assertEqual(self.client.theme_name, "Animals")
+        self.client.theme = "o"
+        self.assertEqual(self.client.theme_name, "Objects")
+
+    def test_repr(self):
+        self.client.language = "en"
+        self.client.theme = "c"
+        self.client.step = 5
+        self.client.progression = 80
+        rep = repr(self.client)
+        self.assertIn("Akinator Client", rep)
+        self.assertIn("Language: en", rep)
+        self.assertIn("Theme: Characters", rep)
+        self.assertIn("Step: 5", rep)
+        self.assertIn("Progression: 80", rep)
+
+    def test_defeat_sets_state(self):
+        self.client.language = "en"
+        self.client.defeat()
+        self.assertTrue(self.client.finished)
+        self.assertFalse(self.client.win)
+        self.assertEqual(self.client.akitude, "deception.png")
+        self.assertEqual(self.client.question, "Bravo, you have defeated me !\nShare your feat with your friends.")
+        self.assertEqual(self.client.progression, 100)
+
+    def test_choose_without_win(self):
+        self.client.start_game(language="en", theme="c")
+        self.client.win = False
+        with self.assertRaises(RuntimeError):
+            self.client.choose()
+
+    def test_exclude_after_win_and_finished(self):
+        self.client.start_game(language="en", theme="c")
+        self.client.win = True
+        self.client.finished = True
+        # Should call defeat and set finished/win
+        self.client.language = "en"
+        self.client.defeat()
+        self.assertTrue(self.client.finished)
+        self.assertFalse(self.client.win)
+        self.assertEqual(self.client.akitude, "deception.png")
+
+    def test_theme_ids_and_names(self):
+        self.client.theme = "c"
+        self.assertEqual(self.client.theme_id, 1)
+        self.assertEqual(self.client.theme_name, "Characters")
+        self.client.theme = "a"
+        self.assertEqual(self.client.theme_id, 14)
+        self.assertEqual(self.client.theme_name, "Animals")
+        self.client.theme = "o"
+        self.assertEqual(self.client.theme_id, 2)
+        self.assertEqual(self.client.theme_name, "Objects")
+
+    def test_repr_and_str_edge_cases(self):
+        self.client.language = None
+        self.client.theme = None
+        self.client.step = None
+        self.client.progression = None
+        rep = repr(self.client)
+        self.assertIn("Akinator Client", rep)
+        self.client.win = False
+        self.client.finished = False
+        self.client.question = "TestQ"
+        self.assertEqual(str(self.client), "TestQ")
+
+if __name__ == "__main__":
+    unittest.main()