jofizcd/soul-of-waifu

Purpose and entry points

Soul of Waifu is a Windows-first Python desktop application for persistent AI characters across chat/voice, RPG, desktop companion, Discord, and LAN web access. Startup is main.py; Windows launch/install wrappers are start.bat and installer.bat. Runtime settings and character/provider metadata are persisted under app/configuration/.

Desktop application shell

The GUI is the primary orchestration boundary: it presents chat, settings, character workflows, calls, and feature modes, then routes user actions through signals into service modules. Core UI/system paths are app/gui/sowInterface.py, app/gui/sowSystem.py, and app/gui/interface_signals.py. app/gui/soul_stage_page.py provides the dedicated RPG view.

AI generation abstraction

app/utils/ai_clients/ai_factory.py selects an LLM provider behind the common contract in app/utils/ai_clients/base_provider.py. Provider implementations span local inference and cloud APIs in app/utils/ai_clients/providers/, while app/utils/ai_clients/local_server_manager.py manages the local Llama.cpp-style server lifecycle. Prompt construction is centralized in app/utils/ai_clients/prompt_engine.py, separating character/context assembly from model transport.

Persistent character cognition

Long-lived per-character continuity is handled by app/utils/soul_memory.py: psychology, relationship state, episodic retrieval, diary, emotional decay, and contradiction repair. Character-card import/export and character representation are managed in app/utils/character_cards.py. This memory layer feeds prompts for normal chat and can synchronize context into other modes rather than being owned by any one UI surface.

Structured RPG mode

Soul Stage is a separately modeled AI game-master flow implemented by app/utils/ai_clients/soul_stage_engine.py and displayed through app/gui/soul_stage_page.py. It converts player/party actions into structured campaign state—world facts, NPCs, inventory, status, choices, background and ambient changes—while using the AI client boundary for GM generation. It shares character identity/memory but retains RPG-specific state control.

Companion and external interaction boundary

The desktop-overlay companion is centered on app/utils/soul_companion/soul_companion.py; plugin extension points live in app/utils/soul_companion/plugins/. MCP integrations are isolated in app/utils/ai_clients/mcp_client.py, creating an explicit boundary between model-directed actions and external tool servers. The companion can use local desktop capabilities such as screen/clipboard/web behavior and proactively react through its behavioral simulation.

Multimodal and remote channels

Voice pipeline services are app/utils/speech_to_text.py and app/utils/text_to_speech.py; they bridge microphone/audio playback with local or cloud speech engines. Image-generation adapters reside in app/utils/image_generator.py. Discord is a distinct gateway via app/utils/discord_manager.py. LAN/mobile access is served by app/utils/web_server.py, with a browser client in app/web_client/index.html and app/web_client/script.js, providing WebSocket-style bidirectional interaction against the desktop-hosted runtime.

Runtime assets and infrastructure

The app expects writable/downloaded runtime areas for models, FFmpeg, voices, data, and cache: assets/local_llm/, app/ffmpeg/, app/voices/, app/data/, and app/cache/. Avatar/emotion assets are organized under assets/emotions/, including Live2D and VRM resources. Local-first execution supports GPU-accelerated model serving; optional external services include OpenAI-compatible and named cloud LLM providers, image APIs, ElevenLabs, Discord, Hugging Face model discovery/downloads (app/utils/models_hub.py), and external MCP servers.