How kseto06/otakunet works
1. Overall shape
OtakuNet is split into two clear boundaries: an offline model-training subsystem and an online desktop GUI inference subsystem. The training side produces serialized model artifacts; the GUI side loads those artifacts and turns user genre ratings into anime recommendations.
2. Training and experimentation layer
The notebooks/ directory is the model development area. ContentBasedAnime.ipynb appears to contain the data preparation, feature engineering, training, and evaluation workflow for the recommender. This is where the content-based logic is built and the learned parameters are exported.
3. Custom neural-network framework
The framework/ package is the core ML engine. framework.py, model.py, and Sequential.py indicate a from-scratch neural network abstraction built on top of NumPy rather than a full ML library. This suggests a lightweight training/inference runtime with custom layers, sequential composition, and model orchestration.
4. Dual-network recommendation model
The README describes a dual neural network architecture: one path learns user-related features and another learns anime-related features, then the learned representations are combined for the final prediction. Architecturally, this means the model has two parallel input branches and a merge/scoring stage rather than a single monolithic classifier.
5. Feature engineering and preprocessing
The model relies on data preparation steps such as Bayesian rating, weighted average, and z-score normalization. The presence of item_prepared.pkl, item_original.pkl, y_original.pkl, and user_constants.pkl shows that preprocessing outputs are persisted separately from raw/normalized targets and constants used at inference time.
6. Persisted model artifacts
The notebooks/pickle/ directory is the handoff point from training to application. item_model.pkl, user_model.pkl, and the related pickle files indicate the GUI does not retrain the model; it consumes precomputed parameters and prepared data structures for prediction.
7. GUI application boundary
The gui/ directory is a standalone desktop application. gui/app.py is the entry point, and gui/views/ contains the screens: Home.py, Prompt.py, and Recommend.py. This is a multi-screen local UI rather than a browser app.
8. User interaction flow
The GUI flow is: start on the home screen, move to the prompt screen to collect genre ratings, then navigate to the recommend screen to display results. This makes the user input a compact vector of preferences that feeds the inference pipeline.
9. Prediction and ranking pipeline
gui/functions/predictions.py is the bridge between UI and model artifacts. It likely loads the serialized models, converts prompt inputs into model-ready form, computes candidate anime scores, sorts them, and returns the top recommendations with metadata for display.
10. Presentation layer for recommendations
The recommend screen is responsible for rendering the final ranked output: anime names, genres, and images. The gui/views/images/ folder and demo/ animation indicate the app has a presentation-focused layer separate from the prediction logic.
11. Technology stack
The ML side is centered on NumPy and Pandas, with pickle-based serialization for model persistence. The UI side uses customtkinter per the README and has its own environment requirements in gui/requirements.txt. The repo is therefore a mix of Python ML tooling and a native desktop interface.
12. Key architecture diagram emphasis
If you draw this repo, the most important arrows are:
- raw anime/user data → notebook preprocessing/training
- preprocessing/training → custom NumPy framework
- trained parameters → pickle artifacts
- GUI prompt inputs → prediction function
- prediction function + pickles → ranked recommendations → UI display
The main architectural boundary is between model generation and model consumption.
Main entry points: ContentBasedAnime.ipynb ContentBasedAnime · predictions.py Predictions · framework.py Framework core · Home.py Home
Components 16
Offline training
Notebook-driven model development, preprocessing, and serialized artifact generation.
- ContentBasedAnime · Main experimentation and training workflow for the content-based recommender.
notebooks/ContentBasedAnime.ipynb
ML framework
Custom NumPy-based neural-network runtime used by the recommender model.
- Framework core · Top-level custom ML framework abstractions built around NumPy.
framework/framework.py - Model base · Model lifecycle and shared training/inference behavior.
framework/model.py - Sequential · Sequential composition helper for stacking network components.
framework/Sequential.py
Desktop app
Local multi-screen GUI that collects ratings and shows ranked anime recommendations.
- App entry · Starts the customtkinter application and screen flow.
gui/app.py - Home · Initial screen that begins the user journey.
gui/views/Home.py - Prompt · Collects genre ratings and prepares user preferences.
gui/views/Prompt.py - Recommend · Displays ranked anime recommendations with metadata and images.
gui/views/Recommend.py - Predictions · Loads serialized models, transforms prompt input, scores candidates, and ranks results.
gui/functions/predictions.py
Model artifacts
Persisted pickle files consumed by the GUI at inference time.
- Item model · Serialized anime-side model parameters used during inference.
notebooks/pickle/item_model.pkl - User model · Serialized user-side model parameters used during inference.
notebooks/pickle/user_model.pkl - Prepared items · Anime feature data prepared for training and inference.
notebooks/pickle/item_prepared.pkl - Raw items · Original anime item data preserved alongside prepared features.
notebooks/pickle/item_original.pkl - User constants · Normalization and scoring constants reused at inference time.
notebooks/pickle/user_constants.pkl - Original targets · Stored target values or labels associated with the training workflow.
notebooks/pickle/y_original.pkl
Other components
- README · Describes the dual-network recommender, training flow, and GUI usage.
README.md
Connections 19
- README → ContentBasedAnime: describes · The README documents the training workflow and model design.
- ContentBasedAnime → Framework core: uses · Notebook training relies on the custom NumPy framework.
- Framework core → Model base: includes · Core framework builds on model lifecycle abstractions.
- Framework core → Sequential: includes · Core framework includes sequential composition support.
- ContentBasedAnime → Prepared items: writes · Training produces prepared item features for reuse.
- ContentBasedAnime → Item model: writes · Training exports the anime-side learned parameters.
- ContentBasedAnime → User model: writes · Training exports the user-side learned parameters.
- ContentBasedAnime → User constants: writes · Training persists normalization and scoring constants.
- ContentBasedAnime → Raw items: reads · Training consumes original anime data.
- ContentBasedAnime → Original targets: reads · Training consumes original target values.
- App entry → Home: opens · The application starts on the home screen.
- Home → Prompt: navigates · Users move from the home screen to the prompt screen.
- Prompt → Predictions: submits · User ratings are handed off to the prediction bridge.
- Predictions → Item model: loads · Inference loads the item-side serialized model.
- Predictions → User model: loads · Inference loads the user-side serialized model.
- Predictions → Prepared items: loads · Inference uses prepared anime features and metadata.
- Predictions → User constants: loads · Inference reuses stored constants for feature shaping.
- Predictions → Recommend: returns · Prediction results are sent to the recommendation screen.
- Recommend → Home: restart · The UI can return to the start of the flow.