Open-LLM-VTuber AI 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 `uv` for package management.

Project Overview

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

**Core Tech**: FastAPI, Pydantic v2, Uvicorn, fully async architecture

**Package Manager**: `uv` (~0.8) — always use `uv run`, `uv sync`, `uv add`, `uv remove`

**Key Principles**:

- Offline-ready core functionality

- Strict frontend-backend separation

- Performance-critical design

- Clean, testable, maintainable code

Repository Structure

```

doc/ # Deprecated

frontend/ # Compiled web frontend (React, git submodule)

config_templates/

conf.default.yaml # English config template

conf.ZH.default.yaml # Chinese config template

src/open_llm_vtuber/

config_manager/

main.py # Pydantic config validation

run_server.py # Application entrypoint

conf.yaml # User config (generated from template)

```

**Frontend**: Separate repo (`Open-LLM-VTuber-Web`) integrated via submodule

**Documentation**: Separate repo (`open-llm-vtuber.github.io`) — generate Markdown in project root for user to migrate

Coding Standards

Formatting & Linting

Format all code with `uv run ruff format`

Pass all checks with `uv run ruff check`

Group and sort imports: stdlib → third-party → local (PEP 8)

Naming (PEP 8)

`snake_case` for variables, functions, methods, modules

`PascalCase` for classes

Descriptive names; avoid single-letter except loop counters

Type Hints (Python 3.10+)

**DO**: Use `|` for unions (`str | None`)

**DON'T**: Use `Optional[str]`

**DO**: Use built-in generics (`list[int]`, `dict[str, float]`)

**DON'T**: Use `List[int]`, `Dict[str, float]`

All function/method signatures **MUST** have accurate type hints

Suppress type checker only if third-party libraries make it impossible to fix

Docstrings (Google Style, English)

All public modules, functions, classes, methods **MUST** have:

1. Summary

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

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

4. `Raises:` (optional but encouraged)

Logging

Use `loguru` for all output

English messages, clear and informative

Use emoji when appropriate

Architectural Principles

Dependency Management

1. Try Python stdlib or existing dependencies first

2. New dependencies must be compatible license + well-maintained

3. Use `uv add`, `uv remove`, `uv run` (never `pip` directly)

4. After adding dependency, update **both** `pyproject.toml` and `requirements.txt`

Configuration

Templates: `config_templates/conf.default.yaml` (EN), `conf.ZH.default.yaml` (CN)

When modifying config structure, update **both** templates

All config validated via Pydantic models in `src/open_llm_vtuber/config_manager/main.py`

Cross-Platform Compatibility

Core logic **MUST** run on macOS, Windows, Linux

Platform-specific or hardware-specific features (e.g., CUDA, Windows APIs) **MUST** be optional with graceful fallbacks

Application must start and run core features even if optional components unavailable

Instructions for AI Agents

When generating code for this project:

1. **Async-first**: Use `async`/`await` everywhere possible; avoid blocking operations

2. **Performance**: Target <500ms latency; profile and optimize hot paths

3. **Offline-ready**: Core features must work without internet

4. **Type safety**: Full type hints (Python 3.10+ syntax)

5. **Documentation**: Google-style docstrings for all public APIs

6. **Testing**: Write testable, modular code with clear separation of concerns

7. **Error handling**: Use `loguru` for errors; provide clear English messages

8. **Dependency hygiene**: Update both `pyproject.toml` and `requirements.txt`

9. **Config changes**: Update both EN and CN templates + Pydantic models

10. **Code quality**: Run `uv run ruff format` and `uv run ruff check` before committing

Example: Adding a New Dependency

```bash

Add dependency

uv add fastapi-cache2

Update requirements.txt (manually or via script)

echo "fastapi-cache2" >> requirements.txt

Verify

uv run ruff check

uv run python -c "import fastapi_cache"

```

Example: Modifying Configuration

1. Edit `config_templates/conf.default.yaml`

2. Edit `config_templates/conf.ZH.default.yaml`

3. Update Pydantic model in `src/open_llm_vtuber/config_manager/main.py`

4. Test: `uv run python run_server.py` to validate config load

Philosophy

**Simplicity**: Write clear, readable code; avoid premature optimization

**Single Responsibility**: One function/class = one purpose

**Performance-Aware**: Measure, profile, optimize where it matters

**Modern Python**: Follow Zen of Python + Python 3.10+ best practices

Open-LLM-VTuber AI Assistant

Open-LLM-VTuber AI Assistant

Project Overview

Repository Structure

Coding Standards

Formatting & Linting

Naming (PEP 8)

Type Hints (Python 3.10+)

Docstrings (Google Style, English)

Logging

Architectural Principles

Dependency Management

Configuration

Cross-Platform Compatibility

Instructions for AI Agents

Example: Adding a New Dependency

Add dependency

Update requirements.txt (manually or via script)

Verify

Example: Modifying Configuration

Philosophy

Reviews (0)