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:

Unlike the HTML-scraping adapters, bamboohr and workday are structured-JSON
sources: BambooHR and Workday careers pages are client-rendered apps, so those
adapters read the tenant's public JSON listing endpoints directly (stable titles,
locations, and ids) instead of parsing rendered markup. Workday uses the public
CXS POST API — see docs/guides/WORKDAY_SOURCE_GUIDE.md.

The jsonld adapter is vendor-neutral: modern ATS platforms publish
<script type="application/ld+json"> JobPosting payloads so their roles appear
in Google Jobs, so a single adapter covers boards that would otherwise each need
a bespoke scraper. It understands bare objects, arrays, @graph/ItemList
containers, TELECOMMUTE remote roles, and PropertyValue identifiers, and it
skips malformed blocks instead of failing the whole page.

# Register a JSON-LD source
curl -X POST localhost:8000/source-configs \
  -H 'content-type: application/json' \
  -d '{"name":"acme-careers","source_type":"jsonld","base_url":"https://acme.example.com/careers"}'

Quick start

git clone https://github.com/Francis1998/agentic-career-search.git
cd agentic-career-search
uv venv
source .venv/bin/activate
uv sync --extra dev --frozen
cp .env.example .env
uv run uvicorn autoapply_agent.main:app --reload

Documentation

Regenerate demos

./scripts/generate_demo_gif.sh

License

MIT © Francis1998