CONTRIBUTING.md

Contributing to Quack 🦆

Welcome 🤗 The resources compiled here are meant to help developers contribute to the project. Please check the code of conduct before going further.

If you're looking for ways to contribute, here are some ideas:

• 🐛 Report bugs (open an issue & fill the template)
• 💡 Suggest improvements (open a GitHub discussion or chat with us on Discord)
• 👍👎 Provide feedback about our roadmap (easier to chat on Discord)
• ⌨️ Update the codebase (check our guide for setup & PR submission)

Data model

The back-end core feature is to interact with the metadata tables. For the service to be useful for codebase analysis, multiple tables/object types are introduced and described as follows:

Access-related tables

• Users: stores the hashed credentials and access level for users & devices.

Core worklow tables

• Repository: metadata of installed repositories.
• Guideline: metadata of curated guidelines.

Codebase structure

• src/app - The actual API codebase
• src/tests - The API unit tests
• .github - Configuration for CI (GitHub Workflows)
• docs - Source of our documentation
• scripts - Custom scripts
• demo - Code for the Gradio demo
• apm - Configuration for Application Performance Monitoring

Continuous Integration

This project uses the following integrations to ensure proper codebase maintenance:

• Github Worklow - run jobs for package build and coverage
• Codacy - analyzes commits for code quality
• Codecov - reports back coverage results
• Sentry - automatically reports errors back to us
• PostgreSQL - storing and interacting with the metadata database
• PostHog - product analytics
• Slack - event notifications
• Prometheus - Scraping API metrics
• Grafana - Dashboard for API monitoring (dashboard adapted from https://github.com/Kludex/fastapi-prometheus-grafana)
• Traefik - the reverse proxy and load balancer
• Mintlify - the documentation builder

As a contributor, you will only have to ensure coverage of your code by adding appropriate unit testing of your code.

Feedback

Feature requests & bug report

Whether you encountered a problem, or you have a feature suggestion, your input has value and can be used by contributors to reference it in their developments. For this purpose, we advise you to use Github issues.

First, check whether the topic wasn't already covered in an open / closed issue. If not, feel free to open a new one! When doing so, use issue templates whenever possible and provide enough information for other contributors to jump in.

Questions

If you are wondering how to do something with Companion API, or a more general question, you should consider checking out Github discussions. See it as a Q&A forum, or the project-specific StackOverflow!

Developer setup

Prerequisites

• Git
• Docker
• Docker compose
• NVIDIA Container Toolkit and a GPU (>= 6 Gb VRAM for good performance/latency balance)*
• Poetry
• Make (optional)

*If you don't have a GPU, you can use alternative LLM providers (currently supported: Groq, OpenAI)

Configure your fork

1 - Fork this repository by clicking on the "Fork" button at the top right of the page. This will create a copy of the project under your GitHub account (cf. Fork a repo).

2 - Clone your fork to your local disk and set the upstream to this repo

git clone git@github.com:<YOUR_GITHUB_ACCOUNT>/companion.git
cd companion
git remote add upstream https://github.com/quack-ai/companion.git

Install the dependencies

Let's install the different libraries:

poetry export -f requirements.txt --without-hashes --with quality --output requirements.txt
pip install -r requirements.txt

Pre-commit hooks

Let's make your life easier by formatting & fixing lint on each commit:

pre-commit install

Environment configuration

In order to run the project, you will need to specific some information, which can be done using a .env file. Copy the default environement variables from .env.example:

cp .env.example .env

This file contains all the information to run the project.

Values you have to replace

• SUPERADMIN_GH_PAT: the GitHub personal access token of the initial admin user
• GH_OAUTH_ID: the Client ID of the GitHub Oauth app (Create an OAuth app on GitHub, pointing to your Quack dashboard w/ callback URL)
• GH_OAUTH_SECRET: the secret of the GitHub Oauth app (Generate a new client secret on the created OAuth app)

Values you can edit freely

• POSTGRES_DB: a name for the PostgreSQL database that will be created
• POSTGRES_USER: a login for the PostgreSQL database
• POSTGRES_PASSWORD: a password for the PostgreSQL database
• SUPERADMIN_LOGIN: the login of the initial admin user
• SUPERADMIN_PWD: the password of the initial admin user

Other optional values

• JWT_SECRET: if set, tokens can be reused between sessions. All instances sharing the same secret key can use the same token.
• OLLAMA_MODEL: the model tag in Ollama library that will be used for the API.
• GROQ_API_KEY: your Groq API KEY, required if you select groq as LLM_PROVIDER.
• GROQ_MODEL: the model tag in Groq supported models that will be used for the API.
• OPENAI_API_KEY: your OpenAI API KEY, required if you select openai as LLM_PROVIDER.
• OPENAI_MODEL: the model tag in OpenAI supported models that will be used for the API.
• SENTRY_DSN: the DSN for your Sentry project, which monitors back-end errors and report them back.
• SERVER_NAME: the server tag that will be used to report events to Sentry.
• POSTHOG_HOST: the host for PostHog PostHog.
• POSTHOG_KEY: the project API key for PostHog PostHog.
• SLACK_API_TOKEN: the App key for your Slack bot (Create New App on Slack, go to OAuth & Permissions and generate a bot User OAuth Token).
• SLACK_CHANNEL: the Slack channel where your bot will post events (defaults to #general, you have to invite the App to your channel).
• SUPPORT_EMAIL: the email used for support of your API.
• DEBUG: if set to false, silence debug logs.

Production-only values

• ACME_EMAIL: the email linked to your certificate for HTTPS
• POSTGRES_HOST & POSTGRES_PORT: the host and port of your remote PostgreSQL database service.
• BACKEND_HOST: the subdomain where your users will access your API (e.g "api.mydomain.com")
• GRADIO_HOST: the subdomain where your users will access your chat interface (e.g "chat.mydomain.com")
• GF_HOST: the subdomain where you'll access your Grafana APM dashboard (e.g "apm.mydomain.com")

Submitting a Pull Request

Preparing your local branch

You should not work on the main branch, so let's create a new one

git checkout -b a-short-description

Developing your feature

Commits

• Code: ensure to provide docstrings to your Python code. In doing so, please follow Google-style so it can ease the process of documentation later.
• Commit message: please follow Angular commit format

Tests

In order to run the same tests as the CI workflows, you can run them locally:

make test

Code quality

To run all quality checks together

make quality

The previous command won't modify anything in your codebase. Some fixes (import ordering and code formatting) can be done automatically using the following command:

make style

Submit your modifications

Push your last modifications to your remote branch

git push -u origin a-short-description

Then open a Pull Request from your fork's branch. Follow the instructions of the Pull Request template and then click on "Create a pull request".