Limo Local Search

A small local-first tool for reproducible KU Leuven Limo / Primo literature searches, normalized records, run manifests, and optional AI-assisted screening.

In plain terms: it opens Limo in a real browser so you can log in manually, runs saved searches through the local browser session, saves records into predictable folders, normalizes them, and creates reviewable screening artifacts.

This project does not provide KU Leuven, Limo, LIBIS, Ex Libris Primo, or OpenAI access. It requires your own authorized access. It does not store your KU Leuven password. It is not affiliated with KU Leuven, LIBIS, Ex Libris, or Primo.

Why This Exists

Manual literature-search work is possible, but it is easy to lose track of details:

• searches get rerun with slightly different filters;
• exported records end up in random folders;
• downstream review work starts from ad hoc files;
• it is hard to prove which records came from which query and run.

This app keeps that workflow local, repeatable, and inspectable without adding a database, server deployment, queue, or hosted platform.

What It Helps With

• saving a reusable authenticated Chromium profile locally;
• running one Limo query or 100+ saved queries in a batch;
• applying consistent Limo filters such as availability, resource type, and year range;
• handling large downloads with year-split pagination;
• saving raw snapshots, normalized records, manifests, and review tables;
• optionally running OpenAI-assisted title and abstract screening;
• creating pending-review CSV/JSON files when no OpenAI key is configured.

What It Does Not Do

• it does not provide institutional access;
• it does not bypass access controls, rate limits, subscription limits, or provider terms;
• it does not store or print your password;
• it is not a hosted multi-user system;
• it is not a replacement for careful human review;
• it is not an official KU Leuven, LIBIS, Ex Libris, or Primo tool.

Who Might Find This Useful

• PhD students running large literature searches;
• researchers preparing systematic or scoping reviews;
• research librarians and evidence-synthesis support teams;
• research software engineers building local-first review tooling;
• anyone who wants file-based, reproducible Limo search artifacts.

Quick Start

Windows PowerShell

git clone https://github.com/01452/limo-search.git
cd limo-search

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m playwright install chromium

Copy-Item .env.example .env
Copy-Item data\queries.example.json data\queries.json
Copy-Item data\prompt_profiles.example.json data\prompt_profiles.json

python run.py

Open:

http://127.0.0.1:5057

If PowerShell blocks activation, run this once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then activate again:

.\.venv\Scripts\Activate.ps1

macOS / Linux

git clone https://github.com/01452/limo-search.git
cd limo-search

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m playwright install chromium

cp .env.example .env
cp data/queries.example.json data/queries.json
cp data/prompt_profiles.example.json data/prompt_profiles.json

python run.py

First Login

1. Open the local UI.
2. Go to Manual login.
3. Click Open login browser.
4. Log in to KU Leuven / Limo manually.
5. Close the browser after login.

The app stores only a local Chromium browser profile:

auth/limo_chromium_profile/

Do not commit or share that folder.

Saved Queries

Edit:

data/queries.json

Example:

[
  {
    "id": "query-001",
    "label": "My first review query",
    "field": "any",
    "precision": "contains",
    "query": "sustainability AND governance",
    "scope": "All_Content",
    "tab": "all_content_tab",
    "sort": "rank",
    "limit": 50,
    "max_records": 600,
    "available_online": true,
    "resource_types": ["articles", "book_chapters", "reports", "conference_proceedings", "dissertations"],
    "date_from": 2015,
    "date_to": 2026
  }
]

For 100+ searches, put every query in this same file and run a batch from the UI or CLI.

Default Limo Filters

The default review-oriented filters are:

• Available online;
• Resource types:
  • Articles;
  • Book Chapters;
  • Reports;
  • Conference Proceedings;
  • Dissertations/Theses;
• Date range: 2015 to 2026.

The UI shows these filters in Run search and Batch run. For batch runs, the selected filters apply to every selected query.

Important: limit is only the requested per-request page size. Primo caps it at 50, but some sessions or endpoints may still return only 10 records per page. The downloader follows the actual returned page size and keeps paging until it reaches max_records, for example 600.

For large date ranges, the downloader automatically splits the request by year. This avoids common Primo deep-offset limits while keeping the same selected filters.

If analysis_input_record_count is lower than expected, rerun with Fetch + review and Force rerun. Review existing analyzes the current local records.json only; it does not fetch more Limo records.

Typical UI Workflow

1. Run Manual login once.
2. Add queries to data/queries.json.
3. Open Batch run.
4. Choose All queries or select specific rows.
5. Choose Fetch + review.
6. Adjust filters, max records, and prompt profile if needed.
7. Start the batch and inspect result folders when it finishes.

The batch runner is single-threaded and resume-friendly. Completed query folders are skipped unless you enable Force rerun.

CLI Commands

Start the local UI:

python run.py

Run all saved queries:

python run.py batch --all

Run selected queries:

python run.py batch --query-id query-001 --query-id query-002

Force rerun everything:

python run.py batch --all --force

Rebuild review artifacts from existing records.json files:

python run.py analyze-existing --all

Use a prompt profile:

python run.py batch --all --prompt-profile-id generic_lima_screening_strict

Use a custom prompt file:

python run.py batch --all --system-prompt-file ./my_prompt.txt

Override filters:

python run.py batch --all --max-records 600 --date-from 2015 --date-to 2026 --available-online --resource-type articles --resource-type book_chapters --resource-type reports --resource-type conference_proceedings --resource-type dissertations

Optional OpenAI Setup

Open .env and set:

OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-5-mini
AI_MAX_RECORDS=1000

Leave OPENAI_API_KEY empty if you only want local pending-review tables. The app should not fail just because no API key is configured.

Prompt Profiles

Default examples are in:

data/prompt_profiles.example.json

To customize them:

cp data/prompt_profiles.example.json data/prompt_profiles.json

On Windows PowerShell:

Copy-Item data\prompt_profiles.example.json data\prompt_profiles.json
notepad data\prompt_profiles.json

Each profile has:

• id
• label
• system_prompt

The UI can also override the selected profile with a one-off custom prompt.

Outputs

Per query:

data/results/<query-id>/

Important files:

• records.json
• records.csv
• limo_raw_pages.json
• combined_raw.txt
• normalized_records.json
• analysis_config.json
• run_manifest.json
• summary.md
• removed_duplicates.csv / removed_duplicates.json
• title_screening.csv / title_screening.json
• abstract_screening.csv / abstract_screening.json
• included_papers.csv / included_papers.json
• excluded_papers.csv / excluded_papers.json

Batch summaries:

data/results/batch_runs/<timestamp>/

Do Not Commit

These paths are intentionally ignored:

• .env
• .venv/
• auth/limo_chromium_profile/
• data/queries.json
• data/prompt_profiles.json
• data/results/
• logs/

They may contain credentials, cookies, local prompts, private queries, downloaded records, or review outputs.

Local Tests

python -m pip install -r requirements.txt -r requirements-dev.txt
python -m pytest -q

Contributing

See CONTRIBUTING.md. Keep changes local-first, file-based, and easy to inspect.

Security

See SECURITY.md. Do not post .env, cookies, tokens, browser profile files, or downloaded private records in public issues.

License

MIT. See LICENSE.