How omi-kalix/ai-powered-candidate-screening works
1. Overall shape
- This repository is a batch-processing LLM workflow for screening candidates from a CSV file.
- The architecture is centered on a LangGraph state machine: each candidate flows through a fixed sequence of evaluation nodes, then results are persisted and the next candidate begins.
2. Entry point and orchestration
- app.py is the runtime entry point.
- It likely wires together the graph, loads configuration/data, starts execution, and triggers final export.
- The orchestration boundary is important: application startup is separate from the per-candidate workflow.
3. Workflow engine boundary
- graph/graph.py is the likely place where the LangGraph graph topology is assembled.
- This is where linear steps, conditional edges, and batch looping behavior are defined:
- load batch once
- process each candidate through the evaluation chain
- branch to either the next candidate or CSV export
- In an architecture diagram, treat this as the control plane of the system.
4. Node-level processing
- nodes/nodes.py contains the discrete workflow steps described in the README:
- load batch
- initialize candidate
- preprocess
- feature extraction
- technical match
- seniority match
- culture match
- aggregate score
- recruiter summary
- self review
- save result
- next candidate
- export CSV
- These are the functional units where candidate data is transformed and enriched.
5. LLM chain layer
- chains/chains.py likely encapsulates the LLM calls and prompt execution logic used by the nodes.
- This is the boundary between orchestration and model interaction: nodes decide *when* to call the model, chains define *how* to call it.
- If drawing the architecture, place this layer between node logic and the model provider.
6. Model provider integration
- model/model.py is the abstraction for the LLM backend.
- The README indicates the system uses Ollama locally and a Qwen2.5 model, so the model layer is effectively an adapter to a local LLM runtime rather than a hosted API.
- This is a key external dependency: the app expects Ollama to be running and a model to be pulled.
7. Prompting and evaluation policy
- prompts/prompts.py contains the actual prompt templates for extraction, scoring, summary generation, and self-review.
- The prompt layer is where candidate evaluation criteria are encoded, so it materially affects output quality and consistency.
- In a diagram, it sits beside the chain/model path as a configuration-like dependency.
8. Typed state and schema boundaries
- state/state.py defines the workflow state carried through the graph from node to node.
- schemas/schema.py likely defines Pydantic models for structured outputs such as extracted candidate features, scores, feedback, and final result records.
- This is an important boundary: raw resume text becomes structured state, then structured output becomes persisted results.
9. Data flow: batch input to per-candidate evaluation
- Input starts from candidates.csv, which is read as a batch dataset.
- Each row becomes one candidate instance in the graph.
- The candidate is normalized, parsed into structured features, scored across multiple dimensions, summarized, reviewed, and stored.
10. Data flow: self-review before persistence
- The self-review stage acts as a quality gate before saving.
- It checks summary consistency against scores and flags hallucinations, contradictions, or formatting issues.
- If validation fails, the summary is regenerated before the result is committed.
- This is a notable reliability boundary in the pipeline.
11. Output and persistence
- Evaluated candidates are accumulated and written to candidate_results.csv.
- The system appears file-based rather than database-backed, so persistence is an export step at the end of the batch rather than incremental storage.
- assets/tmp suggests transient artifacts or working files may be created during execution.
12. Supporting assets and packaging
- assets/ contains screenshots used in the README, not core runtime logic.
- requirements.txt captures the Python dependency set, including LangGraph, LangChain, Pandas, Pydantic, and Ollama-related tooling.
- Docker is supported as a deployment wrapper, but the architecture still depends on an externally running Ollama service on the host.
13. How to draw the main boundaries
- A clean diagram would show:
- CSV input on the left
- LangGraph orchestration in the center
- node sequence as the candidate processing pipeline
- LLM/model interaction as an external service boundary
- final CSV export on the right
- The most important internal separation is between workflow control, node logic, LLM prompting/model access, and typed state/output.
Main entry points: nodes.py Nodes · graph.py Graph · chains.py Chains · app.py App
Components 18
Workflow
LangGraph control plane and candidate steps
- Graph · Assembles the state machine and routing
graph/graph.py - Nodes · Candidate processing stages
nodes/nodes.py - Load Batch · Reads the candidate set
nodes/nodes.py - Prep · Initializes and preprocesses a candidate
nodes/nodes.py - Extract · Derives candidate features
nodes/nodes.py - Score · Evaluates technical, seniority, and culture fit
nodes/nodes.py - Review · Checks summary quality before save
nodes/nodes.py - Save · Persists the evaluated candidate
nodes/nodes.py - Export · Writes the final CSV output
nodes/nodes.py
LLM Layer
Prompting and model integration
Contracts
Typed state and structured outputs
Data
Batch inputs, outputs, and working files
- Candidates · Source CSV of candidates
candidates.csv - Results · Final screened candidate export
candidate_results.csv - Tmp · Transient artifacts during execution
assets/tmp
Connections 29
- App → Graph: bootstraps · Application starts the workflow assembly
- App → Candidates: loads · Runtime consumes the candidate batch
- Graph → Load Batch: routes to · Graph begins with batch loading
- Load Batch → State: seeds · Batch and candidate state are initialized
- Load Batch → Prep: next · Loaded rows enter per-candidate processing
- Prep → Extract: feeds · Normalized candidate data is ready for feature extraction
- Extract → Chains: invokes · Extraction step delegates to LLM chains
- Chains → Prompts: uses · Chains render prompt templates
- Chains → Model: calls · Model requests go through the Ollama adapter
- Extract → Schema: produces · Structured features are validated against schemas
- Extract → Score: feeds · Extracted features move into scoring
- Score → Chains: invokes · Scoring and summary generation use the LLM layer
- Score → State: updates · Scores and summaries are stored in workflow state
- Score → Review: next · Self-review gate follows scoring
- Review → Schema: checks · Review compares output against typed records
- Review → Save: passes · Validated results proceed to persistence
- Save → Results: accumulates · Accepted candidates are written to the results export
- Save → Export: loops or ends · Graph advances to the next candidate or finishes batch export
- Export → Results: writes · Final batch output is emitted as CSV
- Nodes → Load Batch: implements · Workflow steps live in the nodes module
- Nodes → Prep: implements · Workflow steps live in the nodes module
- Nodes → Extract: implements · Workflow steps live in the nodes module
- Nodes → Score: implements · Workflow steps live in the nodes module
- Nodes → Review: implements · Workflow steps live in the nodes module
- Nodes → Save: implements · Workflow steps live in the nodes module
- Nodes → Export: implements · Workflow steps live in the nodes module
- Graph → State: depends on · Topology is driven by shared workflow state
- Graph → Nodes: wires · Graph connects the node functions
- App → Tmp: uses · Execution may create temporary artifacts