reveilio

AI-powered resume and job-description matching and scoring.

Reveilio takes a job description (file or free text) and one or many resumes (PDF, DOCX, DOC, TXT, or free text) and returns a detailed, weighted match score together with structured candidate data. It supports Gemini, OpenAI, Azure OpenAI, and a local Ollama model.

Install

pip install reveilio

Quickstart

import reveilio

# 1. Configure your LLM provider once
reveilio.configure(provider="gemini", api_key="AIza...")
# or: provider="openai", api_key="sk-..."
# or: provider="azure", api_key="...", azure_endpoint="https://...", azure_deployment="gpt-4o"
# or: provider="ollama", base_url="http://localhost:11434", model="llama3.2"

# 2. Build a JD from a file or free text
jd = reveilio.JobDescription.from_file("jd.pdf")
# jd = reveilio.JobDescription.from_text("We're hiring a Senior Python engineer...")

# 3a. Analyze a single resume
result = reveilio.analyze_resume("resumes/alice.pdf", jd)
print(result.overall_score, result.recommendation)

# 3b. Or an entire folder of resumes, sorted and ranked by score
results = reveilio.analyze_folder("resumes/", jd)
for r in results:
    print(r.rank, r.candidate_data.name, r.overall_score)

# 4. Export a PDF report
reveilio.save_report_pdf(result, "alice_report.pdf")
reveilio.save_batch_report_pdf(results, "batch_ranking.pdf")

Supported inputs

• JD: .pdf, .docx, .doc, .txt, or a plain Python string.
• Resume: .pdf, .docx, .doc, .txt, or a plain Python string.

You can manage multiple JDs simultaneously by keeping multiple JobDescription instances around. Each instance is independent.

Supported LLM providers

Environment variable fallbacks: GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT, and OLLAMA_BASE_URL.

Documentation

Full documentation lives in the docs/ directory. Open docs/index.html in a browser for the complete guide, including configuration, API reference, guides, architecture, and contributing instructions.

Contributing

Contributions are welcome. The full contributing guide is in docs/contributing.html. The short version:

1. Fork and clone

git clone https://github.com/roosterhr/reveilio.git
cd reveilio

2. Create a virtual environment and install dev dependencies

python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install -e ".[dev]"

3. Create a feature branch

Use a descriptive prefix: fix/, feat/, docs/, or refactor/.

git checkout -b feat/my-change

4. Make your change

• Keep pull requests focused. One PR should address one concern.
• Match the existing code style. Reveilio avoids over-abstraction.
• Add or update tests for every bug fix and feature. Tests must not make real LLM calls; mock json_completion as the existing suite does.
• Update the relevant docs pages under docs/ when public behavior changes.
• Do not add new runtime dependencies without prior discussion.

5. Lint and test locally

Reveilio uses ruff for linting and formatting, and pytest for tests. Both must be green before you open a pull request.

ruff check src tests
ruff format --check src tests
pytest -q

To auto-fix lint issues and format the code:

ruff check src tests --fix
ruff format src tests

6. Commit

Write imperative, present-tense commit subjects at 72 characters or fewer, and explain the why in the body. Reference related issues with Fixes #123 or Refs #123.

7. Open a pull request

Push your branch to your fork and open a pull request against main. Fill out the PR template with a summary, motivation, and notes on any manual testing. Respond to review feedback promptly, and rebase (do not merge) onto main if it advances while your PR is open:

git fetch origin
git rebase origin/main
git push --force-with-lease

Reporting security issues

Please do not report security vulnerabilities through public GitHub issues. Email the maintainers privately with a detailed description.

License

MIT