README.md

---
title: LLM FullTextScreener
emoji: 🔥
colorFrom: gray
colorTo: pink
sdk: gradio
sdk_version: 6.15.1
python_version: '3.11'
app_file: app.py
pinned: false
short_description: An integrated app for LLM aided full-text screening
---

# Scientific Article Screener (Gradio + Azure OpenAI)

## Run locally

1. Create and activate a Python 3.11+ environment.
2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Set environment variables:

```bash
export AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com"
export AZURE_OPENAI_API_KEY="<your-api-key>"
export AZURE_OPENAI_DEPLOYMENT="gpt-4.1-mini"
# optional
export AZURE_OPENAI_API_VERSION="2024-08-01-preview"
```

4. Start the app:

```bash
python app.py
```

## Notes

- Session files are persisted per authenticated user under app storage, so users do not overwrite each other's session state.
- Download the updated Excel file using the UI button.
- OCR fallback is left as a placeholder when a PDF has no extractable text.
- Optional `criteria.yml` upload enables a dedicated LLM eligibility workflow (topic + inclusion/exclusion criteria) that overrides decision/confidence.
- If the Excel contains `RAYYAN_Labels`, a parallel LLM workflow shows current labels, suggested switched labels (same count), and rationale for switched labels.

## Protecting Access With a Password (Hugging Face Spaces)

Set these in your Space settings under `Settings -> Repository secrets`:

- `USER1`, `USER2`, ... (recommended), each with value `(username,password)`  
  Example: `("alice","strongpass")`
- `SPACE_APP_PASSWORD` (required to enable login)
- `SPACE_APP_USERNAME` (optional, default is `admin`)

When at least one `USER#` secret is set, Gradio basic auth uses all provided users.
If no `USER#` is set, it falls back to `SPACE_APP_USERNAME` + `SPACE_APP_PASSWORD`.