API reference

Every public symbol reveilio exposes.

Top-level functions

reveilio.configure

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

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 Architecture.