How stefperf/ayto works
Project Type and Purpose
• This is a standalone Python CLI/library tool whose purpose is to solve the “Are You the One?” combinatorial puzzle.
• It is not a web or multi-tier service; rather, it’s an algorithmic solver with a small CLI front end, core computation modules, and simple I/O for test runs and reporting.
File Structure
• Top-level modules:
• main.py – command-line entry point
• game_oracle.py – encapsulates the puzzle’s oracle behavior (generating and evaluating guesses)
• game_solver.py – core solver logic (permutation management, test selection, pruning)
• test_*.txt – static test datasets for performance stats
• setup.py, requirements.txt – packaging and dependencies
• Patterns: single-process, CPU-bound algorithmic workflow. No external services, no database.
Extract Key Components
Break the system into these main components:
a. CLI / User Interface
• main.py parses arguments, loads test cases, invokes solver
b. Solver Core
• PermutationManager: tracks and prunes admissible pair permutations
• EntropyCalculator: computes information gain for candidate tests
• TestSelector: picks next M-test or N-test based on ranking strategy
c. Oracle Interface
• GameOracle: simulates or queries the hidden “perfect matches” and scores guesses
d. Data I/O and Reporting
• Input Loader: reads test_*.txt files
• Output Reporter: writes summary statistics and optional charts
e. Packaging & Configuration
• setup.py and requirements.txt define installable package and dependencies
Relationships and Data Flows
• User → CLI
→ (parses) → Input Loader
→ (initializes) → GameOracle + Solver Core
→ Solver Core ↔ GameOracle (test → score feedback)
→ Solver Core → Output Reporter
→ CLI → (exit)
• Within Solver Core:
• PermutationManager ← filtered by oracle feedback
• EntropyCalculator ← reads current permutation set
• TestSelector ← queries EntropyCalculator, picks best candidate
• Loop repeats until solution converges
Architectural Patterns & Design Principles
• Modular separation of concerns (CLI vs. solver vs. oracle vs. I/O)
• Greedy, information-theoretic selection algorithm
• Single-threaded, CPU-bound workflow, but easily parallelizable at the TestSelector phase
Technologies and Frameworks
• Python 3.x
• Standard library (argparse, itertools)
• No external databases or web frameworks
• Packaging: setuptools (setup.py)
Final Checklist
• All modules are present and named exactly as in the file tree.
• Key data structures (permutation set) and processes (entropy calculation) are highlighted.