# Contributing to PaperQA

Thank you for your interest in contributing to PaperQA! Here are some guidelines to help you get started.

## Setting up the development environment

We use [`uv`](https://github.com/astral-sh/uv) for our local development.

1. Install `uv` by following the instructions on the [uv website](https://astral.sh/uv/).
2. Run the following command to install all dependencies and set up the development environment:

   ```bash
   uv sync
   ```

## Installing the package for development

If you prefer to use `pip` for installing the package in development mode, you can do so by running:

```bash
pip install -e ".[dev]"
```

Where the `dev` extra includes development dependencies such as `pytest`.

## Running tests and other tooling

Use the following commands:

* Run tests (requires an OpenAI key in your environment)

  ```bash
  pytest
  # or for multiprocessing based parallelism
  pytest -n auto
  ```
* Run `pre-commit` for formatting and type checking

  ```bash
  pre-commit run --all-files
  ```
* Run `mypy`, `refurb`, or `pylint` directly:

  ```bash
  mypy paperqa
  # or
  refurb paperqa
  # or
  pylint paperqa
  ```

See our GitHub Actions [`tests.yml`](https://github.com/Future-House/paper-qa/blob/main/.github/workflows/tests.yml) for further reference.

## Using `pytest-recording` and VCR cassettes

We use the [`pytest-recording`](https://github.com/kiwicom/pytest-recording) plugin to create VCR cassettes to cache HTTP requests, making our unit tests more deterministic.

To record a new VCR cassette:

```bash
uv run pytest --record-mode=once tests/desired_test_module.py
```

And the new cassette(s) should appear in [`tests/cassettes`](https://github.com/Future-House/paper-qa/blob/main/tests/cassettes/README.md).

Our configuration for `pytest-recording` can be found in [`tests/conftest.py`](https://github.com/Future-House/paper-qa/blob/main/tests/conftest.py). This includes header removals (e.g. OpenAI `authorization` key) from responses to ensure sensitive information is excluded from the cassettes.

Please ensure cassettes are less than 1 MB to keep tests loading quickly.

Happy coding!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edisonscientific.com/paperqa/contributing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.