A structured Python pipeline for collecting, normalizing, and filtering software engineering listings.
Built to cut through noisy job boards, AI Job Search queries the Adzuna REST API, transforms raw, fragmented JSON payloads into strongly-typed dataclass models, and filters opportunities against custom preferences using role aliases and regex-based work arrangement detection.
Independent Python project verified locally with automated pytest test suites covering API fault tolerance, regex pattern extraction, role expansions, and preference filtering.
Searching for software engineering positions across generalist job boards means sifting through hundreds of irrelevant postings, inaccurate location tags, and buried requirements.
General-purpose search algorithms on large job aggregators frequently return senior managerial roles, sales positions, or unrelated technical stacks when searching for entry-level or specialized developer roles. Furthermore, external job APIs return unpredictable payload structures: some omit salary fields, others nest location data three levels deep, and most bury remote/hybrid policies inside large blocks of unstructured text.
Without a disciplined collection and normalization pipeline, developers either miss opportunities due to minor title differences (e.g., "Python Developer" vs. "Backend Engineer") or waste hours manually parsing listings that don't match their work arrangement preferences.
AI Job Search solves this by establishing a deterministic four-stage data pipeline: querying external job boards via REST endpoints, mapping raw payloads to standardized Job dataclass models, expanding roles with semantic aliases, and filtering opportunities purely on clean, validated properties.
The application follows a linear, decoupled architecture where each stage has a single, well-defined responsibility. Network communication is isolated at the edge, data is normalized into structured domain models, and filtering operates purely on clean domain instances.
Modular architecture of AI Job Search V1.0.0. All collection, normalization, and filtering operates locally via Python.
Open-source repository: Source code, pipeline modules, and tests are public on GitHub (JoseLM03/ai-job-search) .
V1 was architected with clean separation of concerns, ensuring that modifying data sources, expanding filter rules, or altering output formats does not require rewrites across the application.
Raw API payloads are never passed directly to filter functions. A dedicated normalizer transforms vendor-specific keys into a standardized Job dataclass. This guarantees that adding future job boards (such as Greenhouse, Lever, or LinkedIn) only requires a new normalizer function rather than alterations to downstream filtering logic.
Job titles vary widely across companies. The role_aliases.py module maps broad target titles (e.g., "software engineer") to ten related industry titles, including "backend engineer", "full stack engineer", "python developer", and "site reliability engineer", significantly improving recall without requiring multiple manual queries.
Because job boards rarely enforce structured remote/hybrid tags, extract_work_arrangement evaluates description text using targeted regular expressions (such as hybrid|remote \d+ days (per|a) week) to reliably categorize listings as remote, hybrid, or onsite.
Domain models are declared using Python's @dataclass with explicit type hints and defensive field factories (e.g., employment_types: list[str] = field(default_factory=list)). This ensures strict schema validation and eliminates runtime AttributeError or mutable default bugs.
Because reliability is paramount when automating job searches, the codebase is backed by an automated pytest suite covering network failure resilience, regex extraction accuracy, role alias lookups, and preference permutations.
Verifies src/collectors/adzuna.py under network failures. Using monkeypatch to simulate an httpx.RequestError, the test confirms that get_jobs gracefully catches the exception, logs an error, and returns an empty list ([]) without crashing the pipeline.
Verifies src/normalizers/adzuna.py field mapping and evaluates 9 distinct regex pattern test cases, confirming accurate classification of complex hybrid strings (e.g., "Remote 3 days per week", "2 days remote per week"), pure remote, onsite, and employment contract types.
Validates src/filters/job_filter.py across 14 scenarios: case-insensitive matching ("SOFTWARE DEVELOPER"), role alias lookup, remote/hybrid/onsite constraints, multiple employment types, and location matching versus rejection.
Tests src/pipeline.py end-to-end using mock API fixtures, verifying that get_relevant_jobs handles zero-result API responses and filters populated job batches down to exact matching listings.
V1 established the data collection, normalization, and filtering baseline. Future exploration may investigate potential enhancements as non-committed research directions.
Explore integrating Google Gemini API or local Ollama models with structured JSON schemas to evaluate candidate résumés against job descriptions and compute an objective alignment score with rationale.
Investigate connecting Google Maps Platform or OpenStreetMap distance matrix APIs to calculate real transit and driving times, activating the max_commute_minutes preference filter.
Explore adding ingestion modules for Greenhouse, Lever, and USAJOBS API feeds, routing raw listings through dedicated normalizers into the unified Job pipeline.
Consider storing collected listings in a local SQLite database, tracking application stages (Saved, Applied, Interviewing, Offer), and prototyping a lightweight React web UI.
Reliable software begins with disciplined data modeling and clean separation of concerns before adding complex features.
The most important design decision in AI Job Search was isolating external API payloads behind dedicated normalizer functions. By transforming messy, vendor-specific JSON dictionaries into immutable, strongly-typed Job dataclasses immediately upon ingestion, the filtering logic remained pure, testable, and completely independent of Adzuna's specific API schema.
Equally valuable was the discipline of incremental scoping: rather than attempting to build an all-in-one AI auto-apply tool, V1 focused strictly on building a reliable, fault-tolerant collection and filtering engine with 100% automated test coverage. This created a solid foundation that makes future integrations—like LLM scoring or database persistence—straightforward and clean.