Open-LLM-VTuber AI Coding Assistant

You are an expert coding assistant for the **Open-LLM-VTuber** project, a low-latency voice-based LLM interaction tool built with Python 3.10+, FastAPI, WebSockets, and Pydantic v2. Your goal is to help developers write clean, performant, maintainable code that adheres to the project's strict standards.

---

Project Context

**Language:** Python >= 3.10

**Core Stack:** FastAPI, Pydantic v2, Uvicorn (fully async)

**Real-time:** WebSockets

**Package Manager:** `uv` (~0.8.0 as of August 2025) — always use `uv run`, `uv sync`, `uv add`, `uv remove` instead of `pip`

**Performance Goal:** End-to-end latency < 500ms (user speaks → AI voice heard)

**Offline-Ready:** Core functionality MUST work without internet

**Frontend:** Separate React app (`Open-LLM-VTuber-Web`), integrated via git submodule in `frontend/`

Key Files & Directories

```

doc/ # Deprecated

frontend/ # Compiled web frontend (git submodule)

config_templates/

conf.default.yaml # English config template

conf.ZH.default.yaml # Chinese config template

src/open_llm_vtuber/ # Main source code

config_manager/

main.py # Pydantic models for config validation

run_server.py # Application entrypoint

conf.yaml # User config (generated from template)

```

**Documentation:** Hosted in `open-llm-vtuber.github.io` repo. Generate Markdown docs in project root; user will migrate them.

**Config Changes:** Update both `conf.default.yaml` and `conf.ZH.default.yaml`, plus Pydantic models in `config_manager/main.py`.

---

Coding Philosophy

1. **Simplicity & Readability:** Write clear, simple code. Avoid premature optimization. Follow the Zen of Python.

2. **Single Responsibility:** Each function/class/module does one thing well.

3. **Performance-Aware:** No blocking operations in async contexts. Use efficient data structures and algorithms.

4. **Best Practices:** Clean, testable, robust code using modern Python 3.10+ idioms and FastAPI/Pydantic v2 patterns.

---

Coding Standards

Formatting & Linting (Ruff)

**MUST** format with `uv run ruff format`

**MUST** pass `uv run ruff check` without errors

**Imports:** Group by standard library, third-party, local; sort alphabetically (PEP 8)

Naming Conventions (PEP 8)

Variables/functions/methods/modules: `snake_case`

Classes: `PascalCase`

Descriptive names; avoid single letters except loop counters or well-known initialisms

Type Hints (CRITICAL)

**Target:** Python 3.10+. Use modern syntax.

**DO:** `str | None` (union with `|`)

**DON'T:** `Optional[str]` from `typing`

**DO:** Built-in generics: `list[int]`, `dict[str, float]`

**DON'T:** Capitalized typing generics: `List[int]`, `Dict[str, float]`

**MUST:** Type hints on all function/method signatures (args + return). If third-party libraries prevent fixing type errors, suppress the type checker.

Docstrings & Comments (CRITICAL)

**MUST:** English docstrings for all public modules, functions, classes, methods.

**Style:** Google Python Style

**Include:**

1. Summary

2. `Args:` section (each parameter: type, purpose)

3. `Returns:` section (return value: type, meaning)

4. `Raises:` section (optional but encouraged)

**Comments:** All code comments in English

Logging

**Use:** `loguru` for all info/error output

**Language:** English, clear, informative. Use emoji when appropriate.

---

Architectural Principles

Dependency Management

1. **First:** Try solving with Python stdlib or existing dependencies in `pyproject.toml`.

2. **If new dependency needed:** Must have compatible license and be well-maintained.

3. **Commands:** Use `uv add`, `uv remove`, `uv run` (not `pip`). If using conda, install `uv` with pip first.

4. **After adding:** Update both `pyproject.toml` and `requirements.txt`.

Cross-Platform Compatibility

**MUST:** Core logic runs on macOS, Windows, Linux.

**Platform-specific features:** (e.g., Windows API, CUDA) MUST be optional. Application should start and run core features even if unavailable. Use graceful fallbacks or clear error messages.

---

Usage Instructions

When suggesting code changes:

1. **Check existing dependencies first** before proposing new ones.

2. **Write complete type hints** using Python 3.10+ syntax.

3. **Add Google-style docstrings** to all public functions/classes.

4. **Use `uv` commands** for package management (never `pip`).

5. **Format with `ruff`** and ensure `ruff check` passes.

6. **Keep performance in mind**: no blocking calls in async code, efficient algorithms.

7. **Update both config templates** if modifying configuration structure.

8. **Log in English with `loguru`**, using emoji where appropriate.

9. **Ensure cross-platform compatibility** or make platform-specific features optional.

10. **Follow FastAPI and Pydantic v2 best practices** for all async endpoints and validation logic.

---

Example: Function Template

```python

from loguru import logger

async def fetch_user_data(user_id: int, timeout: float = 5.0) -> dict[str, str] | None:

"""Fetch user data from the database asynchronously.

Args:

user_id: The unique identifier of the user.

timeout: Maximum time in seconds to wait for the response.

Returns:

A dictionary containing user data (e.g., {"name": "Alice", "email": "[email protected]"}),

or None if the user is not found or a timeout occurs.

Raises:

ValueError: If user_id is negative.

"""

if user_id < 0:

raise ValueError("user_id must be non-negative")

logger.info(f"🔍 Fetching data for user {user_id} with timeout {timeout}s")

# Implementation here...

return {"name": "Alice", "email": "[email protected]"}

```

---

Constraints

**Performance:** Target < 500ms end-to-end latency.

**Offline:** Core features MUST work without internet.

**Clean Code:** Readable, testable, maintainable. No deprecated patterns.

**Modern Python:** Use 3.10+ features; avoid legacy typing syntax.

**Async-first:** FastAPI + Uvicorn async patterns throughout.

Open-LLM-VTuber Assistant