agentic-career-search

AI-agent backend for autonomous job discovery, explainable decisions, and production-style operations.

Demo Gallery

Why this exists

Most job-search automation demos fail in real usage because they:

• cannot explain why a role is ranked highly,
• cannot recover cleanly when providers fail,
• have no durable event trace for debugging,
• become hard to maintain once features grow.

This project solves those issues with explicit agent engineering primitives:

• deterministic decision engine with rationale traces,
• state-machine run lifecycle and durable event log,
• tool/adapters abstraction for external integrations,
• safety controls (timeouts, bounded scope, cancellation),
• optional LLM enrichment via multiple providers.

Real use cases (problem -> solution)

LLM API integration (consumes model outputs)

Provider integration is built into the code path:

• Gemini API
• Kimi (Moonshot, OpenAI-compatible)
• Claude (Anthropic Messages API)
• GPT-compatible APIs through OpenAI-style endpoint patterns

Enable provider enrichment:

LLM_ENABLE_ENRICHMENT=true
LLM_PROVIDER=gemini   # or kimi / claude / gpt

Then set matching API keys in .env (see CONFIGURATION.md).

Engineering standards covered

This repository follows the requested standards:

1. standalone repo architecture (not coupled to source repo internals),
2. AI-agent-first design with deterministic decision traces,
3. LLM output consumption from Claude/Gemini/Kimi and GPT-style integrations,
4. production-minded layout (src, tests, scripts, CI, env config, migrations),
5. high-quality docs (README, QUICKSTART, CONFIGURATION, SAFETY, ARCHITECTURE),
6. branch-based merge workflow for controlled integration (no direct unsafe merges),
7. lint/type/test validation before finalization,
8. no Docker requirement for standard local verification,
9. phase branches for development roadmap (phase/01 to phase/10),
10. commit-forward workflow with frequent incremental pushes.

API snapshot

• POST /source-configs create source adapter configs
• GET /source-configs list enabled sources
• POST /runs enqueue autonomous run
• GET /runs/{run_id} inspect run state
• GET /runs/{run_id}/events inspect event timeline
• POST /runs/{run_id}/cancel request cancellation
• GET /jobs inspect normalized, scored, and enriched outputs
• GET /health/live and GET /health/ready

Supported job sources

Each SourceConfig selects a source adapter by source_type:

| catsone | CatsoneAdapter | Recognises CATS careers posting anchors by /jobs/{id}, /job/{id}, /careers/{id}, /careers/job/{id}, or /postings/{id} URL shapes | CATS (*.catsone.com) careers boards | | adp | AdpAdapter | Recognises ADP Recruiting posting anchors by /jobs/{id}, /job/{id}, /careers/{id}, /careers/job/{id}, or /requisitions/{id} URL shapes | ADP (*.adp.com) recruiting boards | | jibe | JibeAdapter | Recognises Jibe posting anchors by /jobs/{id}, /job/{id}, /position/{id}, /positions/{id}, or /requisition/{id} URL shapes | Jibe (*.jibe.com) recruiting boards | | hirevue | HireVueAdapter | Recognises HireVue posting anchors by /jobs/{id}, /job/{id}, /careers/{id}, /careers/job/{id}, or /requisition/{id} URL shapes | HireVue public careers boards | | paycom | PaycomAdapter | Recognises Paycom posting anchors by /jobs/{id}, /job/{id}, /posting/{id}, /postings/{id}, or /opportunity/{id} URL shapes | Paycom public careers boards | | yello | YelloAdapter | Recognises Yello posting anchors by /jobs/{id}, /job/{id}, /position/{id}, /positions/{id}, or /opening/{id} URL shapes | Yello public careers boards | | wellfound | WellfoundAdapter | Recognises Wellfound posting anchors by /jobs/{id}, /job/{id}, /role/{id}, /roles/{id}, /startup-jobs/{id} URL shapes | Wellfound (wellfound.com / angel.co) careers boards | | otta | OttaAdapter | Recognises Otta posting anchors by /jobs/{id}, /job/{id}, /roles/{id}, /role/{id}, /openings/{id} URL shapes | Otta (otta.com) careers boards | | builtin | BuiltinAdapter | Recognises Built In posting anchors by /job/{id}, /jobs/{id}, /company-jobs/{id}, /careers/job/{id}, /role/{id} URL shapes | Built In (builtin.com / builtinnyc.com / builtinchicago.com) careers boards | | remoteok | RemoteokAdapter | Recognises RemoteOK posting anchors by /remote-jobs/{id}, /remote-job/{id}, /jobs/{id}, /job/{id} URL shapes | RemoteOK (remoteok.com) careers boards | | weworkremotely | WeworkremotelyAdapter | Recognises WeWorkRemotely posting anchors by /remote-jobs/{id}, /jobs/{id}, /job/{id}, /listings/{id}, /listing/{id} URL shapes | WeWorkRemotely (weworkremotely.com) careers boards | | welcometothejungle | WelcometothejungleAdapter | Recognises Welcome to the Jungle posting anchors by /jobs/{id}, /job/{id}, /companies/{slug}/jobs/{id}, /offers/{id}, /offer/{id} URL shapes | Welcome to the Jungle (welcometothejungle.com) careers boards | | remotive | RemotiveAdapter | Recognises Remotive posting anchors by /remote-jobs/{id}, /remote-job/{id}, /jobs/{id}, /job/{id}, /positions/{id} URL shapes | Remotive (remotive.com) careers boards | | himalayas | HimalayasAdapter | Recognises Himalayas posting anchors by /jobs/{id}, /job/{id}, /companies/{slug}/jobs/{id}, /remote-jobs/{id}, /roles/{id} URL shapes | Himalayas (himalayas.app) careers boards | | workingnomads | WorkingnomadsAdapter | Recognises Working Nomads posting anchors by /jobs/{id}, /job/{id}, /remote-jobs/{id}, /positions/{id}, /position/{id} URL shapes | Working Nomads careers boards | | justremote | JustremoteAdapter | Recognises JustRemote posting anchors by /remote-jobs/{id}, /jobs/{id}, /job/{id}, /listings/{id}, /listing/{id} URL shapes | JustRemote (justremote.co) careers boards | | nodesk | NodeskAdapter | Recognises NoDesk posting anchors by /jobs/{id}, /job/{id}, /remote/{id}, /positions/{id}, /careers/{id} URL shapes | NoDesk (nodesk.co) careers boards | | jobspresso | JobspressoAdapter | Recognises Jobspresso posting anchors by /jobs/{id}, /job/{id}, /remote-jobs/{id}, /postings/{id}, /openings/{id} URL shapes | Jobspresso (jobspresso.co) careers boards | | remoteco | RemotecoAdapter | Recognises Remote.co posting anchors by /remote-jobs/{id}, /jobs/{id}, /job/{id}, /positions/{id}, /careers/{id} URL shapes | Remote.co (remote.co) careers boards | | dynamitejobs | DynamitejobsAdapter | Recognises Dynamite Jobs posting anchors by /jobs/{id}, /job/{id}, /remote-jobs/{id}, /positions/{id}, /listings/{id} URL shapes | Dynamite Jobs (dynamitejobs.com) careers boards | | arcdev | ArcdevAdapter | Recognises Arc.dev posting anchors by /jobs/{id}, /job/{id}, /roles/{id}, /positions/{id}, /openings/{id} URL shapes | Arc.dev (arc.dev) careers boards | | flexjobs | FlexjobsAdapter | Recognises FlexJobs posting anchors by /search/{id}, /flex-jobs/{id}, /remote-job/{id}, /jobs/{id}, /job/{id} URL shapes | FlexJobs (flexjobs.com) careers boards | | radancy | RadancyAdapter | Recognises Radancy posting anchors by /jobs/{id}, /job/{id}, /search/job/{id}, /careers/{id}, or /careers/job/{id} URL shapes | Radancy (*.radancy.com, *.jobs.net) recruiting boards | | silkroad | SilkRoadAdapter | Recognises SilkRoad posting anchors by /jobs/{id}, /job/{id}, /posting/{id}, /postings/{id}, or /opportunity/{id} URL shapes | SilkRoad (*.silkroad.com) recruiting boards | | paradox | ParadoxAdapter | Recognises Paradox careers posting anchors by /jobs/{id}, /job/{id}, /careers/{id}, /careers/job/{id}, or /opportunities/{id} URL shapes | Paradox Olivia (*.paradox.ai) careers boards | | applicantpro | ApplicantProAdapter | Recognises ApplicantPro careers posting anchors by /jobs/{id}, /job/{id}, /careers/{id}, /careers/job/{id}, or /openings/{id} URL shapes | ApplicantPro (*.applicantpro.com) careers boards | | brassring | BrassringAdapter | Recognises BrassRing careers posting anchors by /jobs/{id}, /job/{id}, /jobdetail/{id}, /FgJobDetail/{id}, or /careers/{id} URL shapes | IBM Kenexa BrassRing (*.brassring.com) careers boards |