Open LLM VTuber Development Assistant
You are an AI coding assistant for the **Open-LLM-VTuber** project, a low-latency voice-based LLM interaction tool with Live2D support running locally across platforms.
Project Context
**Language:** Python >= 3.10**Core Stack:** FastAPI, Pydantic v2, Uvicorn, WebSockets (fully async)**Package Manager:** `uv` (~0.8) — always use `uv run`, `uv sync`, `uv add`, `uv remove` instead of `pip`**Primary Goal:** End-to-end latency below 500ms (user speaks → AI voice heard)**Architecture:** Strict frontend-backend separation, offline-ready core functionalityKey Files & Directories
```
doc/ # Deprecated directory
frontend/ # Compiled web frontend (git submodule from Open-LLM-VTuber-Web)
config_templates/
conf.default.yaml # English configuration template
conf.ZH.default.yaml # Chinese configuration template
src/open_llm_vtuber/
config_manager/main.py # Pydantic configuration models
run_server.py # Application entrypoint
conf.yaml # User configuration (generated from template)
```
Core Principles
1. **Offline-Ready:** Core functionality MUST work without internet
2. **Separation of Concerns:** Strict frontend-backend separation
3. **Clean Code:** Modern Python 3.10+ idioms, no deprecated patterns
4. **Performance-Critical:** Avoid blocking operations in async contexts
5. **Cross-Platform:** macOS, Windows, Linux support required
Coding Standards
Formatting & Linting
Format all code with `uv run ruff format`Pass `uv run ruff check` without errorsGroup imports: standard library → third-party → local (PEP 8)Naming Conventions (PEP 8)
`snake_case` for variables, functions, methods, modules`PascalCase` for class namesDescriptive names (avoid single letters except loop counters)Type Hints (CRITICAL)
**DO:**
Use `|` for unions: `str | None`Use built-in generics: `list[int]`, `dict[str, float]`**DON'T:**
Use `Optional[str]` from `typing`Use capitalized types: `List[int]`, `Dict[str, float]`**Requirements:**
All function signatures MUST have accurate type hints (args + return)Target Python 3.10+ syntaxSuppress type checker only when third-party libraries force errorsDocstrings & Comments (CRITICAL)
All public modules, functions, classes, methods MUST have **Google-style** docstrings in EnglishRequired sections: 1. Summary
2. `Args:` (parameter type + purpose)
3. `Returns:` (return type + meaning)
4. `Raises:` (optional but encouraged)
All code comments in EnglishLogging
Use `loguru` for all output (no print statements)Messages in English, clear, informativeUse emoji when appropriateConfiguration Management
Templates in `config_templates/` (both `conf.default.yaml` and `conf.ZH.default.yaml`)When modifying config structure: 1. Update BOTH template files
2. Update Pydantic models in `src/open_llm_vtuber/config_manager/main.py`
Configuration validated on load via PydanticDependency Management
1. First try Python stdlib or existing dependencies in `pyproject.toml`
2. New dependencies must be:
- Compatible license
- Well-maintained
3. Use `uv add` / `uv remove` (never pip directly)
4. After adding dependency, update BOTH:
- `pyproject.toml` (automatic via uv)
- `requirements.txt` (manual)
Cross-Platform Requirements
Core logic MUST run on macOS, Windows, LinuxPlatform-specific features (e.g., CUDA, Windows APIs) MUST be optional with graceful fallbacksApplication should start and run core features even if optional components unavailablePerformance Guidelines
Avoid blocking operations in async contextsUse efficient data structures and algorithmsProfile critical paths (target <500ms end-to-end latency)Prefer async/await over synchronous code in backendDocumentation
When asked to generate documentation, create Markdown files in project root (user migrates to `open-llm-vtuber.github.io` repo)Frontend docs reference: `Open-LLM-VTuber-Web` repository (separate React app)Best Practices
**Simplicity:** Write code that is simple, clear, easy to understand (Zen of Python)**Single Responsibility:** One function/class = one purpose**Performance-Aware:** No premature optimization, but be mindful of async blocking**Testable:** Write code that can be easily unit tested**Maintainable:** Follow FastAPI and Pydantic v2 best practicesWhen writing code for this project:
1. Always check existing patterns in the codebase first
2. Verify cross-platform compatibility
3. Ensure type hints are complete and accurate
4. Write comprehensive docstrings
5. Test that code passes `ruff format` and `ruff check`
6. Confirm async code doesn't block the event loop
7. Use `uv` for all package operations