API Reference

API reference

Every public symbol reveilio exposes.

---

Top-level functions

reveilio.configure

reveilio.configure(
    provider: "gemini" | "openai" | "azure" | "ollama",
    api_key: str | None = None,
    model: str | None = None,
    *,
    azure_endpoint: str | None = None,
    azure_deployment: str | None = None,
    azure_api_version: str = "2024-02-15-preview",
    base_url: str | None = None,
    weights: dict[str, float] | None = None,
) -> ReveilioConfig

Set the process-global LLM configuration. Any argument left as None falls back to the matching environment variable. See Configuration for the full list.

---

reveilio.get_config

reveilio.get_config() -> ReveilioConfig

Return the active configuration. Creates one automatically from environment variables if configure() was never called. Raises RuntimeError if no credentials are available.

---

reveilio.analyze_resume

reveilio.analyze_resume(
    resume: Resume | str | Path | bytes,
    jd: JobDescription | str | Path,
) -> AnalysisResult

Analyze a single resume against a JD. Both resume and jd accept a file path, a free-text string, or a pre-built object.

---

reveilio.analyze_folder

reveilio.analyze_folder(
    folder: str | Path,
    jd: JobDescription | str | Path,
    *,
    extensions: tuple[str, ...] = (".pdf", ".docx", ".doc", ".txt"),
    max_workers: int = 4,
    recursive: bool = False,
) -> list[AnalysisResult]

Walk a folder, analyze every matching file in parallel, and return results sorted by overall_score descending with a 1-based rank set.

---

reveilio.score

reveilio.score(resume: ResumeLike, jd: JDLike) -> AnalysisResult

Lower-level alias for analyze_resume. Use it when you want to be explicit that no file discovery or ranking is happening.

---

reveilio.save_report_pdf

reveilio.save_report_pdf(
    result: AnalysisResult | dict,
    path: str | Path,
) -> Path

Render a detailed per-candidate PDF report and write it to path. Parent directories are created automatically. Returns the written path.

---

reveilio.save_batch_report_pdf

reveilio.save_batch_report_pdf(
    results: list[AnalysisResult | dict],
    path: str | Path,
) -> Path

Render a batch ranking summary PDF (a table of candidates with scores and recommendations). Returns the written path.

---

Classes

JobDescription

Wraps the raw text of a JD plus a lazily-parsed structured dictionary.

Constructor	Accepts
JobDescription.from_text(text)	Free-text JD
JobDescription.from_file(path)	.pdf, .docx, .doc, or .txt on disk
JobDescription.from_bytes(data, filename)	In-memory bytes; filename supplies the extension

Attribute	Type	Description
text	str	Raw extracted text.
source	str | None	File path or "text".
parsed	dict	LLM-parsed structured JD. Computed on first access, then cached.

---

Resume

Wraps the extracted plain text of a candidate's resume. No LLM parse occurs until you hand the resume to analyze_resume or score.

Constructor	Accepts
Resume.from_text(text, filename="resume.txt")	Free text
Resume.from_file(path)	.pdf, .docx, .doc, or .txt
Resume.from_bytes(data, filename)	In-memory bytes

---

ReveilioConfig

Dataclass returned by configure(). You normally do not construct this yourself.

Field	Type	Default
provider	Literal["gemini","openai","azure","ollama"]	"gemini"
api_key	str | None	None
model	str | None	provider-specific default
azure_endpoint	str | None	None
azure_deployment	str | None	None
azure_api_version	str	"2024-02-15-preview"
base_url	str | None	None (Ollama only)
weights	dict[str, float]	see Configuration

---

Result models

AnalysisResult

Pydantic v2 model. All fields are readable. Use .model_dump() to get a plain dictionary.

Field	Type	Meaning
overall_score	float	0 to 100 weighted match.
confidence_level	str	"High", "Medium", or "Low".
recommendation	str	"Shortlist", "Needs Review", or "Not Suitable".
detailed_scores	dict[str, {score, reasoning}]	Per-dimension breakdown.
jd_analysis	dict	Snapshot of the structured JD used.
ai_summary	str	Executive critique (about 120 words).
strengths, weaknesses, career_flags	list[str]	Narrative bullets.
kpis, relevancy_metrics, suggested_roles	various	Additional LLM output.
suggested_questions	list[str]	Populated only for Shortlist recommendations.
candidate_data	ResumeData	Structured extraction of the resume.
rank	int | None	Set by analyze_folder.

---

ResumeData

Field	Type
name, email, phone, linkedin, filename	str | None
skills, certifications, top_keywords	list[str]
experience	list[ExperienceItem]
education	list[EducationItem]
total_experience	float (years)
career_gaps	list[Any]

---

Environment variables

Variable	Used by
GEMINI_API_KEY or GOOGLE_API_KEY	Gemini provider
OPENAI_API_KEY	OpenAI provider
AZURE_OPENAI_API_KEY	Azure provider
AZURE_OPENAI_ENDPOINT	Azure provider
AZURE_OPENAI_DEPLOYMENT	Azure provider
AZURE_OPENAI_API_VERSION	Azure provider
OLLAMA_BASE_URL	Ollama provider

---

Continue to Docker & UI.