Development Guide

Basics

To get started on development you need to install uv. You can use pip, pipx or conda to do so:

pip install uv

Next install the package and all dependencies with uv sync.

# cd <gerd_project_root>
uv sync

After that, it should be possible to run scripts without further issues:

uv run examples/hello.py

To add a new runtime dependency, just run uv add:

uv add langchain

To add a new development dependency, run uv add with the --dev flag:

uv add mypy --dev

Pre-commit hooks (recommended)

Pre-commit hooks are used to check linting and run tests before commit changes to prevent faulty commits. Thus, it is recommended to use these hooks! Hooks should not include long running actions (such as tests) since committing should be fast. To install pre-commit hooks, execute this once:

uv run pre-commit install

Further tools

Poe Task Runner

Task runner configuration are stored in the pyproject.toml file. You can run most of the tools mentioned above with a (shorter) call to poe.

uv run poe lint  # do some linting (with mypy)

PyTest

Test case are run via pytest. Tests can be found in the /tests folder. Tests will not be run via pre-commit since they might be too complex to be done before commits. To run the standard set of tests use the poe task test:

uv run poe test

More excessive testing can be trigger with test_manual which will NOT mock calls to the used models:

uv run poe test_manual

Ruff

Ruff is used for linting and code formatting. Ruff follows black styling ref. Ruff will be run automatically before commits when pre-commit hooks are installed. To run ruff manually, use uv:

uv run ruff check gerd

There is a VSCode extension that handles formatting and linting.

MyPy

MyPy does static type checking. It will not be run automatically. To run MyPy manually use uv with the folder to be checked:

uv run mypy gerd

Implemented GUIs

Run Frontend

Either run Generate Frontend:

uv run poe gen_dev

or QA Frontend:

uv run poe qa_dev

or the GERD Router:

# add _dev for the gradio live reload version
# omit in 'prod'
uv run router[_dev]

CI/CD and Distribution

GitHub Actions

GitHub Actions can be found under .github/workflows. There is currently one main CI workflow called python-ci.yml:

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

name: Linting/Testing Python

on:
  push:
    branches: [main, dev-gha]
  pull_request:
    branches: [main]

jobs:
  linting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python 3.12
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install uv and development dependencies with extras
        run: |
          pipx install uv 
          uv sync
      - name: Run linting
        run: uv run poe lint
  testing:
    needs: linting
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.12", "3.10"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Cache HuggingFace models and data
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          key: ${{ runner.os }}-hf
      - name: Install uv
        run: pipx install uv
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install development dependencies with extras
        run: uv sync
      - name: Run Tests
        run: uv run poe cov
      - name: Report Coverage
        run: uv run coverage report --skip-covered --omit="tests/*" --format=markdown >> $GITHUB_STEP_SUMMARY

In its current config it will only be executed when a PR for main is created or when a special dev-gha branch is created. It will also trigger actions when commits are pushed to main directly but this should be avoided.

GitHub Issue Templates

This project uses GitHub issue templates. Currently, there are three templates available.

Bug Report

name: Bug
description: File a bug report
title: "[Bug]: "
labels: ["bug"]
# assignees:
#   - aleneum
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  - type: textarea
    id: expected-behavior
    attributes:
      label: Expected Behavior
      description: What should happen
    validations:
      required: true
  - type: textarea
    id: actual-behavior
    attributes:
      label: Actual Behavior
      description: What happened instead
    validations:
      required: true
  - type: textarea
    id: steps-reproduce
    attributes:
      label: Steps to Reproduce the Problem
      value: |
        1.
        2.
        3.

    validations:
      required: true
  - type: input
    id: affected-version
    attributes:
      label: Affected version
      description: Version number or commit hash
      placeholder: "0.1.0"
    validations:
      required: true
  - type: dropdown
    id: affected-components
    attributes:
      label: Affected components
      description: Which components are affected
      multiple: true
      options:
        - Gen Service
        - Qa Service
        - Frontend
        - Backend
    validations:
      required: false
  - type: dropdown
    id: affected-plattforms
    attributes:
      label: Affected plattforms
      description: Which plattforms are affected
      multiple: true
      options:
        - Windows
        - Linux
        - MacOS
    validations:
      required: false
  - type: textarea
    id: further-information
    attributes:
      label: Further contextual information and suggestions
      description: More detailed descriptions or possible solutions
    validations:
      required: false

Feature Request

name: Feature Request
description: Suggest an idea for this project
title: "[FR]: "
labels: ["enhancement"]
# assignees:
#   - aleneum
body:
  - type: markdown
    attributes:
      value: Do you have an idea for a feature that would make this project more helpful or easier to use?
  - type: textarea
    id: problem-description
    attributes:
      label: Problem description
      description: Is your feature request related to a problem? Please describe.
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Solution
      description: A clear and concise description of what you want to happen.
    validations:
      required: true
  - type: textarea
    id: additional-context
    attributes:
      label: Additional context
      description: Add any other context or screenshots about the feature request here.
    validations:
      required: false
  - type: dropdown
    id: affected-components
    attributes:
      label: Affected components
      description: Which components are affected
      multiple: true
      options:
        - Gen Service
        - Qa Service
        - Frontend
        - Backend
    validations:
      required: false

Use Case

name: Use Case
description: A description of a user-centered system requirement
title: "[UC]: "
labels: ["use case"]
# assignees:
#   - aleneum
body:
  - type: textarea
    id: summary
    attributes:
      label: Summary
      description: A concise description of the use case
    validations:
      required: true
  - type: textarea
    id: rationale
    attributes:
      label: Rationale
      description: The motivation and value added by the described use case
    validations:
      required: true
  - type: dropdown
    id: level
    attributes:
      label: Level
      multiple: false
      options:
        - user goal
        - subfunction
  - type: input
    id: actors
    attributes:
      label: Actors
      description: Someone or something with behavior, e.g. a person (identified by role), a computer system, or an organization
    validations:
      required: true
  - type: textarea
    id: preconditions
    attributes:
      label: Preconditions
      description: What needs to be true on start
      placeholder: |
        - Use Cases: #1, #2
        - User is authenticated
    validations:
      required: true
  - type: textarea
    id: postconditions
    attributes:
      label: Postconditions
      description: What must be true on successful completion
      placeholder: "The form "
    validations:
      required: true
  - type: textarea
    id: basic-flow
    attributes:
      label: Basic Flow
      description: A typical, unconditional happy path
      value: |
        1.
        2.
        3.

    validations:
      required: true
  - type: textarea
    id: alternative-paths
    attributes:
      label: Alternative Paths
      description: Alternate scenarios of success or failure
      placeholder: |
        2.1
        2.2
        3.1

    validations:
      required: false
  - type: textarea
    id: visualisation
    attributes:
      label: Visualisation
      description: A mermaid diagram or image depiciting the action flow
      value: |
        ```mermaid
        flowchart LR;
          1-->2
          2-->3
          3-->4
          3-->3.1
          3.1-->3.2
          3.2-->2
          4-->4.1
          4.1-->4
        ```
    validations:
      required: false
  - type: textarea
    id: related-issues
    attributes:
      label: Other related issues, use cases, features
      description: What must be true on successful completion
      placeholder: "#1 #2 #3"
    validations:
      required: false