Quickstart

From installation to a ranked shortlist in a few minutes.

Step 1. Configure once

Choose a provider and set an API key. configure() stores a process-global configuration that every other reveilio call reads from. It only needs to be called once.

import reveilio

reveilio.configure(
    provider="gemini",
    api_key="AIza...",
)

If you prefer environment variables, set GEMINI_API_KEY, OPENAI_API_KEY, or the equivalent for your provider. Reveilio will pick them up automatically.

Step 2. Build a JobDescription

A JobDescription is a lightweight wrapper around the raw JD text plus a lazily-computed structured parse. You can create one from a file, from free text, or from in-memory bytes.

# From a file (.pdf, .docx, .doc, or .txt)
jd = reveilio.JobDescription.from_file("jd.pdf")

# From free text, for pasted JDs or database rows
jd = reveilio.JobDescription.from_text("""
Senior Python Engineer, 5+ years, FastAPI, AWS, Postgres.
Must be comfortable with async code and production on-call.
""")

# From in-memory bytes, e.g. an uploaded file in a web handler
jd = reveilio.JobDescription.from_bytes(uploaded.read(), filename=uploaded.name)

Step 3a. Analyze a single resume

result = reveilio.analyze_resume("resumes/alice.pdf", jd)

print(result.overall_score)        # 82.0
print(result.recommendation)       # 'Shortlist'
print(result.candidate_data.name) # 'Alice Example'
print(result.detailed_scores["skills"])
# {'score': 90, 'reasoning': 'strong match on Python, FastAPI...'}

You can pass a Resume object, a path, or free text:

reveilio.analyze_resume(reveilio.Resume.from_text(text), jd)
reveilio.analyze_resume("resumes/bob.docx", jd)
reveilio.analyze_resume("Bob, 8 years Java", jd)  # treated as free text

Step 3b. Analyze a folder

Point reveilio at a folder. It will pick up every supported resume, score them in parallel, sort by overall_score, and assign a 1-based rank.

results = reveilio.analyze_folder("./resumes", jd, max_workers=4)

for r in results[:5]:
    print(f"#{r.rank} {r.candidate_data.name:<25} {r.overall_score:>5.1f}  {r.recommendation}")

To include subfolders, pass recursive=True.

Step 4. Export a PDF report

The same PDF exporter used in the original HR application ships with the package. Two formats are available:

# A detailed report for a single candidate
reveilio.save_report_pdf(result, "reports/alice.pdf")

# A ranking summary table for an entire batch
reveilio.save_batch_report_pdf(results, "reports/ranking.pdf")

Putting it all together

import reveilio

reveilio.configure(provider="openai", api_key="sk-...", model="gpt-4o-mini")

jd = reveilio.JobDescription.from_file("roles/senior_python.pdf")
results = reveilio.analyze_folder("applicants/2026-Q2/", jd)

shortlist = [r for r in results if r.recommendation == "Shortlist"]
print(f"{len(shortlist)} of {len(results)} candidates made the shortlist")

reveilio.save_batch_report_pdf(results, "reports/senior_python_ranking.pdf")
for r in shortlist:
    reveilio.save_report_pdf(r, f"reports/{r.candidate_data.name}.pdf")

Continue to Configuration & providers.