.github/copilot-instructions.md

Open-LLM-VTuber AI Coding Assistant: Context & Guidelines

version: 2025.08.05-1

1. Core Project Context

• Project: Open-LLM-VTuber, a low-latency voice-based LLM interaction tool.
• Language: Python >= 3.10
• Core Tech Stack:
  • Backend: FastAPI, Pydantic v2, Uvicorn, fully async
  • Real-time Communication: WebSockets
  • Package Management: uv (version ~= 0.8, as of 2025 August) (always use uv run, uv sync, uv add, uv remove to do stuff instead of pip)
• Primary Goal: Achieve end-to-end latency below 500ms (user speaks -> AI voice heard). Performance is critical.
• Key Principles:
  • Offline-Ready: Core functionality MUST work without an internet connection.
  • Separation of Concerns: Strict frontend-backend separation.
  • Clean code: Clean, testable, maintainable code, follows best practices of python 3.10+ and does not write deprecated code.

Some key files and directories:

doc/                 # A deprecated directory
frontend/            # Compiled web frontend artifacts (from git submodule)
config_templates/
    conf.default.yaml    # Configuration template for English users
    conf.ZH.default.yaml # Configuration template for Chinese users
src/open_llm_vtuber/ # Project source code
    config_manager/
        main.py      # Pydantic models for configuration validation
run_server.py        # Entrypoint to start the application
conf.yaml            # User's configuration file, generated from a template

1.1. Repository Structure

• Frontend Repository: The frontend is a React application developed in a separate repository: Open-LLM-VTuber-Web. Its built artifacts are integrated into the frontend/ directory of this backend repository via a git submodule.

• Documentation Repository: The official documentation site is hosted in the open-llm-vtuber.github.io repository. When asked to generate documentation, create Markdown files in the project root. The user will be responsible for migrating them to the documentation site.

1.2. Configuration Files

• Configuration templates are located in the config_templates/ directory:
• conf.default.yaml: Template for English-speaking users.
• conf.ZH.default.yaml: Template for Chinese-speaking users.
• When modifying the configuration structure, both template files MUST be updated accordingly.
• Configuration is validated on load using the Pydantic models defined in src/open_llm_vtuber/config_manager/main.py. Any changes to configuration options must be reflected in these models.

2. Overarching Coding Philosophy

• Simplicity and Readability: Write code that is simple, clear, and easy to understand. Avoid unnecessary complexity or premature optimization. Follow the Zen of Python.
• Single Responsibility: Each function, class, and module should do one thing and do it well.
• Performance-Aware: Be mindful of performance. Avoid blocking operations in async contexts. Use efficient data structures and algorithms where it matters.
• Adherence to Best Practices: Write clean, testable, and robust code that follows modern Python 3.10+ idioms. Adhere to the best practices of our core libraries (FastAPI, Pydantic v2).

3. Detailed Coding Standards

3.1. Formatting & Linting (Ruff)

• All Python code MUST be formatted with uv run ruff format.
• All Python code MUST pass uv run ruff check without errors.
• Import statements should be grouped by standard library, third-party, and local modules and sorted alphabetically (PEP 8).

3.2. Naming Conventions (PEP 8)

• Use snake_case for all variables, functions, methods, and module names.
• Use PascalCase for class names.
• Choose descriptive names. Avoid single-letter names except for loop counters or well-known initialisms.

3.3. Type Hints (CRITICAL)

• Target Python 3.10+. Use modern type hint syntax.
• DO: Use | for unions (e.g., str | None).
• DON'T: Use Optional from typing (e.g., Optional[str]).
• DO: Use built-in generics (e.g., list[int], dict[str, float]).
• DON'T: Use capitalized types from typing (e.g., List[int], Dict[str, float]).
• All function and method signatures (arguments and return values) MUST have accurate type hints. If third party libraries made it impossible to fix type errors, suppress the type checker.

3.4. Docstrings & Comments (CRITICAL)

• All public modules, functions, classes, and methods MUST have a docstring in English.
• Use the Google Python Style for docstrings.
• Docstrings MUST include:
  1. Summary.
  2. Args: section describing each parameter, its type, and its purpose.
  3. Returns: section describing the return value, its type, and its meaning.
  4. (Optional but encouraged) Raises: section for any exceptions thrown.
• All other code comments must also be in English.

3.5. Logging

• Use the loguru module for all informational or error output.
• Log messages should be in English, clear, and informative. Use emoji when appropriate.

4. Architectural Principles

4.1. Dependency Management

• First, try to solve the problem using the Python standard library or existing project dependencies defined in pyproject.toml.
• If a new dependency is required, it must have a compatible license and be well-maintained.
• Use uv add, uv remove, uv run instead of pip to manage dependencies. If user uses conda, install uv with pip then.
• After adding a new dependency, in addition to pyproject.toml, you must add the dependency to requirements.txt as well.

4.2. Cross-Platform Compatibility

• All core logic MUST run on macOS, Windows, and Linux.
• If a feature is platform-specific (e.g., uses a Windows-only API) or hardware-specific (e.g., CUDA), it MUST be an optional component. The application should start and run core features even if that component is not available. Use graceful fallbacks or clear error messages.