# INSTALLATION.md

# Installation Guide

## Overview

The OpenAlex Publication Discovery and Repository Enrichment Toolkit is written in Python and has been developed and tested using Windows.

The toolkit has no dependency on a live EPrints repository connection. Instead, it compares OpenAlex metadata with a periodically exported repository snapshot.

---

# Requirements

The toolkit requires:

* Python 3.11 or later (Python 3.12 recommended)
* Internet access for OpenAlex API queries
* A current export of the institutional repository in CSV format

---

# Python packages

The toolkit requires the following Python packages:

* requests

Additional packages may be required in future versions as functionality develops.

Packages can be installed using:

```bash
pip install requests
```

---

# Folder structure

Place the toolkit and supporting files together in a single folder.

Example:

```
OpenAlex_Publication_Discovery_and_Repository_Enrichment_Toolkit/

    openalex_repository_toolkit.py

    kar_export.csv

    WEEKLY_WORKFLOW.md
    PROJECT_HISTORY.md
    INSTALLATION.md
    CHANGELOG.md
    KNOWN_LIMITATIONS.md
    ARCHITECTURE.pdf
```

---

# Repository export

Before running the toolkit, export the institutional repository as:

**Multiline CSV (Staff)**

Rename the exported file:

```
kar_export.csv
```

Place this file in the same folder as the toolkit.

---

# Configuration

Institution-specific settings are defined in the `CONFIG` section near the beginning of the Python script.

Before running the toolkit, review and amend the following settings as appropriate:

* OpenAlex API key
* OpenAlex contact email
* Institution ROR identifier(s)
* Repository export filename
* Output folders
* Query lookback period

Obtain a free OpenAlex API key from OpenAlex and enter it into the openalex_api_key setting in the CONFIG section of openalex_repository_toolkit.py. Also enter the email address associated with your OpenAlex account into openalex_email. If no API key is supplied, the toolkit will continue to operate using the OpenAlex Polite Pool, but an API key is recommended.

Do not distribute your personal API key when sharing the toolkit or publishing modified versions.

---

# Running the toolkit

From a command prompt:

```bash
python openalex_repository_toolkit.py
```

Alternatively, the script may be run by double-clicking it where the operating system has been configured to execute Python scripts.

---

# Outputs

Successful execution creates:

* RIS files for new publications
* metadata enrichment reports
* duplicate reports
* manual review reports
* log files
* raw OpenAlex JSON

Further information is provided in **WEEKLY_WORKFLOW.md**.

---

# Updating the toolkit

Future releases may include additional publication types, metadata mappings and reporting improvements.

Before updating:

* archive the previous version
* retain the associated repository export
* retain the log files and reports

This provides a complete audit trail and allows previous runs to be reproduced if required.