akinator

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #go #rust #docker #nodejs #vue #awesome-list #security #mcp #openai

(★ 10)

An high-performance, open source Akinator like Engine and probabilistic guessing engine written in Go.

akinator Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Sensei Knows: The Akinator Engine</h1>

---

**Sensei Knows** is an Akinator engine that powers our official [Anime Akinator](https://anime-akinator.vercel.app/). If you've ever wondered how Akinator works or wanted to build your own 20 Questions character guessing game, this repository is for you.

<div align="center">
  <img src="assets/gifs/koro yeah i did it.gif" alt="Koro Yeah I did it" width="60%" />
  <br/>
  <i>Believe me I can do this!</i>
</div>

---

<div align="center">
  <img src="assets/gifs/after banner.gif" alt="Funny mind reading gif" width="60%" />
  <br/>
  <i>When you try to pick a totally obscure character, but the engine still reads your mind...</i>
</div>

---

## Table of Contents

- [Why we Built It ?](#why-we-built-it-)
- [Current Implementation](#-current-implementation)
- [The Architecture](#the-architecture)
  - [4.1 Core Philosophy: A Statistical Approach](#41-core-philosophy-a-statistical-approach)
  - [4.2 The Math & Prediction Logic](#42-the-math--prediction-logic)
  - [4.3 Reinforcement Learning (Self-Correction)](#43-reinforcement-learning-self-correction)
  - [4.4 Anti-Troll & Adversarial Defense](#44-anti-troll--adversarial-defense)
- [Dataset Mathematical Blueprint](#-dataset-mathematical-blueprint)
- [Usage & Installation](#-usage--installation)
- [License](#️-license)

<h2 align="center">Why we Built It ?</h2>

<div align="center">
  <img src="assets/gifs/why we built.gif" alt="Looking at C++ Frameworks" width="60%" />
  <br/>
  <i>Us looking at C++ backend web frameworks...</i>
</div>

---

It all started with a specific goal in mind: we wanted to build an **Anime Akinator**.

At first, we engineered the core guessing logic using **C++** because of its performance. However, when the time came to hook this engine up to a live website as a backend service, that's when we faced many problems. Building a C++ web server was turning into an absolute nightmare as we had no experience it and could not find any framework which provided all what we needed.

<div align="center">
  <img src="assets/gifs/koro reading book.gif" alt="Learning Go" width="60%" />
  <br/>
  <i>So we sat down, explored Go, and made the decision to make a switch.</i>
</div>

---

We decided to ditch the C++ backend and switch entirely to **Golang**. Go's built-in concurrency, simple HTTP standard library, and ease of deployment made it the absolute perfect choice for us.

<h2 align="center">Current Implementation</h2>

<div align="center">
  <img src="assets/gifs/koro secn3.gif" alt="Showing off the implementation" width="60%" />
  <br/>
  <i>I am already live to read your minds!</i>
</div>

---

Right now, we're have a live instance of this exact engine for our original project running: Sensei Knows. You can play around with it and try to beat the engine here:
👉 **[anime-akinator.vercel.app](https://anime-akinator.vercel.app/)**

Here's a sneak peek of the frontend we hooked up to our Go engine:

<br/>

But here is the best part: **this engine is completely dataset-agnostic.**

You can literally just swap out the dataset to make it guess Hollywood actors, cars, programming languages, or even your own friends.

If you end up using this engine for a different dataset or project, _please_ let us know! (_Do share your project link with us :)_ ) We'd absolutely love to see what kind of crazy things you build with it.

<h2 align="center">The Architecture</h2>

### 4.1 Core Philosophy: A Statistical Approach

<div align="center">
  <img src="assets/gifs/after header.gif" alt="Koro Sensei philosopher" width="60%" />
  <br/>
  <i>"I knew I am a philosopher nururufuhuhu"</i>
</div>

---

While decision trees and binary search algorithms are foundational to computer science for exact matching, building a robust guessing engine requires dealing with human uncertainty. Standard binary trees fail gracefully; a single incorrect answer or a "Don't Know" response can lead to an unrecoverable collapse of the search space.

Drawing inspiration from existing literature on probabilistic classifiers (such as Naive Bayes), our engine is built as a **dynamic statistical classification system**. This allows the engine to:

1. Operate on a continuous probability space (`Yes` = 1.0, `Probably` = 0.75, `Don't Know` = 0.50, `Probably Not` = 0.25, `No` = 0.0).
2. Handle noise and human error. A contradictory answer does not eliminate a candidate; it merely applies a mathematical penalty to their posterior probability.
3. Dynamically compute the optimal sequence of questions based on the active state of the knowledge base, rather than relying on a static, pre-computed graph.

### 4.2 The Math & Prediction Logic

<div align="center">
  <img src="assets/gifs/koro sweating.gif" alt="Koro Sensei Sweating over math" width="60%" />
  <br/>
  <i>The engine sweating over probabilities to figure out who you are thinking of...</i>
</div>

---

The engine's predictions are powered by several core mathematical concepts:

**1. Probabilistic State Representation**
Instead of boolean values, the knowledge base stores two parameters for every question associated with a character: a continuous weight $w \in [0, 1]$ and a sample size $n$.

**2. Posterior Probability & Beta-Prior Smoothing**
When a user provides an answer $a$, the posterior probability $P(C_k)$ for every character $C_k$ is updated. The baseline match score is the absolute distance: $1 - |a - w|$.
However, to prevent total probability collapse (the zero-frequency problem where one bad answer reduces a character's probability to exactly 0), we apply a **Beta-prior smoothing calibration**:
```math
\alpha = w \cdot n + 1.0
```
```math
\beta = (1 - w) \cdot n + 1.0
```
We compute a dynamic lower bound (epsilon) based on these Beta parameters. The final match score is bounded by this epsilon, ensuring the engine can always recover from anomalies.

**3. Shannon Entropy & Information Gain**
To determine which question to ask next, the engine does not look at a tree. It computes the current **Shannon Entropy** ($H_0$) of the entire character distribution:
```math
H_0 = -\sum P(C_k) \log_2 P(C_k)
```
For every eligible question, the engine simulates the expected entropy $E[H]$ across all 5 possible answer buckets, weighted by their marginal probabilities. The question that yields the highest **Expected Information Gain (EIG)** ($H_0 - E[H]$) is mathematically guaranteed to split the remaining candidates most efficiently.

**4. UCB (Upper Confidence Bound) Exploration**
To balance exploiting known good questions and exploring new ones, the engine applies a UCB bonus. Questions that have a low selection count receive a slight mathematical boost, ensuring the engine tests new pathways and doesn't get stuck in local optima.

**Output Format**
When the engine has exhausted its question cap or hit its guess threshold, it calculates and outputs the final **Top Candidates List** along with their exact computed percentage confidence scores directly in the terminal.

<div align="center">
  <img src="assets/gifs/architecture.gif" alt="Koro calculating probabilities" width="60%" />
  <br/>
  <i>Koro calculating the probabilities for each of your responses...</i>
</div>

### 4.3 Reinforcement Learning (Self-Correction)

<div align="center">
  <img src="assets/gifs/koro self learning system.gif" alt="Koro Sensei learning" width="60%" />
  <br/>
  <i>Koro having troubles seeing so much to learn from...</i>
</div>

---

A static database quickly becomes outdated. To solve this, the engine employs a continuous reinforcement learning mechanism. Every time a game concludes, whether the engine guessed correctly or was corrected by the user, the system learns from the session.

For the correct character, the engine updates its stored weights ($w$) and sample sizes ($n$) for every question answered during the session. It calculates a consistency score between the user's answer and the stored weight, then applies an observation weight scaled by the existing data mass (to prevent a single user from drastically altering well-established facts). The character's parameters are thus incrementally refined, allowing the engine to adapt to community consensus over time.

### 4.4 Anti-Troll & Adversarial Defense

<div align="center">
  <img src="assets/gifs/koro concurrency.gif" alt="Koro Sensei dodging bullets" width="60%" />
  <br/>
  <i>Sensei dodging all the bullets bad players send...</i>
</div>

---

One of the biggest challenges in crowdsourced learning is malicious data poisoning (trolls). If users intentionally give wrong answers, they could corrupt the dataset. We built two layers of defense to prevent this:

**1. Adversarial Flagging (Z-Collapse Detection)**
During a session, the engine monitors the sum of probabilities ($Z$). If a user's answers are statistically inconsistent with the knowledge base, $Z$ collapses. If the collapse fraction exceeds a certain threshold, the session is flagged as "adversarial," and its answers are completely ignored for live training.

**2. Staging & Review System**
When a user adds a new character or corrects the engine, the change does not go live immediately. Instead, it is pushed to a `PendingCorrections` queue. A correction must gather a minimum number of community consensus votes (`MinVotesToPromote`) from independent sessions before it is mathematically averaged and officially promoted into the live dataset.

<h2 align="center">Dataset Mathematical Blueprint</h2>

<div align="center">
  <img src="assets/gifs/koro dataset.gif" alt="Koro loves a good dataset" width="60%" />
  <br/>
  <i>Koro loves a dataset of his favorite taste, it makes his guessing so much easier!</i>
</div>

---

To make the engine guess accurately in under 20 questions, your custom dataset needs a highly efficient structure. Based on our experience, here is what we followed our own dataset:

**1. The "Golden Ratio" (Questions to Characters)**
For optimal convergence, you should aim for a **1:2** or **1:3** question-to-character ratio. For example, if your dataset has 100 characters, aiming for about 45-50 well-framed questions is the sweet spot.

**2. Semantic vs. Specific Questions**
The secret to a fast guessing engine is maximizing the Expected Information Gain (EIG) early on.

- **Broad/Semantic Questions:** Roughly **40-50%** of your dataset should be broad semantic questions designed to split the candidate pool by at least 20%. These are mathematically vital for early-game variance.
- **Specific/Niche Questions:** Keep highly specific questions to under **10%** of your dataset. Reserve these exclusively for distinguishing between extremely similar characters deep in the search tree. The rest questions should be category based.
- **Avoid Too Many Niche Questions:** Keeping a niche question for each/most character(s) will make it eventually impossible to guess the character within 20 questions.

<h2 align="center">Usage & Installation</h2>

<div align="center">
  <img src="assets/gifs/koro ready to run.gif" alt="Koro ready to run" width="60%" />
  <br/>
  <i>Are we ready to go?</i>
</div>

---

If you want to run the engine locally in your terminal, the process is incredibly simple. Make sure you have **Go (1.21+)** installed.

### Build the Engine

To compile the `akinator-go` binary, simply run:

```bash
make build
```

### Play the Game

To run a standard game session where the engine tries to guess your character based on your custom `knowledge.json`, pass the file path as an argument to the binary:

```bash
./akinator-go path/to/your/knowledge.json
```

### Review Pending Corrections

Remember our Anti-Troll system from Section 4.4? As people play, their corrections get stored in the queue. If you want to review the pending queue and manually promote corrections to the live database, pass the `--review` flag:

```bash
./akinator-go --review path/to/your/knowledge.json
```

<h2 align="center">⚖️ License</h2>

This project is completely open-sourced under the **AGPL 3.0** License.

<div align="center">
  <img src="assets/gifs/end readme.gif" alt="Koro Sensei goodbye" width="60%" />
  <br/>
  <i>Koro will meet you soon in any of his other forms! Don't forget to try and beat him at: <a href="https://anime-akinator.vercel.app/">https://anime-akinator.vercel.app/</a></i>
</div>

akinator

akinator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

akinator

akinator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README