assistance-engine/.github/copilot-instructions.md

applyTo
**

Project General Coding Standards (Python - PEP 8)

Naming Conventions

• Follow PEP 8 naming conventions strictly
• Use snake_case for variables, functions, and methods
• Use PascalCase for class names
• Use UPPER_CASE for constants
• Prefix internal/private attributes with a single underscore (_)
• Avoid single-letter variable names unless in very small scopes (e.g., loops)

---

Code Style & Formatting

• Follow PEP 8 guidelines for formatting
• Use 4 spaces for indentation (never tabs)
• Limit lines to 79 characters when possible (max 88 if using Black)
• Add a blank line between logical sections of code
• Keep imports organized:
  1. Standard library
  2. Third-party packages
  3. Local imports
• Avoid wildcard imports (from module import *)
• Remove unused imports and variables

---

Clean Code Principles

• Write small, focused functions that do one thing only
• Prefer functions over long procedural blocks
• Keep functions under ~30 lines when possible
• Use descriptive and meaningful names
• Avoid code duplication (DRY principle)
• Prefer explicit code over implicit behavior
• Avoid deeply nested logic (max 2–3 levels)
• Use early returns to reduce nesting
• Keep classes focused and cohesive
• Write code that is easy to read and maintain

---

Function Design

• Always use functions when logic can be reused or isolated
• Add type hints to all function signatures
• Keep functions pure when possible (avoid side effects)
• Document functions using docstrings (PEP 257 style)

Example:

def calculate_average(values: list[float]) -> float:
    """
    Calculate the average of a list of numbers.

    Args:
        values: A list of float numbers.

    Returns:
        The arithmetic mean of the values.
    """
    if not values:
        raise ValueError("The values list cannot be empty.")

    return sum(values) / len(values)