Agentic Job Intelligence Pipeline (MCP + LLM)

Model Context Protocol을 사용하여 구조화된 데이터 검색을 위한 외부 도구를 오케스트레이션하는 에이전트 기반 파이프라인으로, LLM 점수화 계층이 후보자 프로필과 비교하여 구조화되지 않은 채용 공고의 순위를 매깁니다. 컨텍스트 창 압력은 단계적 메타데이터 우선 검색 전략(pipeline.py)으로 처리되며, 동일한 도구는 자체 계획 루프가 있는 실제 도구 호출 에이전트(agent.py)와 REST + WebSocket API(api.py)에도 노출됩니다. 전체 문서는 docs/를 참조하세요.

실행하기

pip install -r requirements.txt

python pipeline.py --benchmark     # token comparison, zero API calls
python pipeline.py --dry-run       # real MCP subprocess handshake, no LLM
export OPENAI_API_KEY=sk-...
python pipeline.py --top 8         # fixed 3-stage pipeline
python agent.py --dry-run          # agent tool discovery, no LLM calls
export OPENAI_API_KEY=sk-...
python agent.py --top 8            # tool-calling agent with a planning loop
python eval.py --prefilter-only    # stage-1 recall, deterministic half, no key needed
pytest -q                          # in-process MCP server, no key needed

uvicorn api:app --reload           # REST + WebSocket layer, http://localhost:8000
curl localhost:8000/health
curl -X POST localhost:8000/rank -H 'content-type: application/json' -d '{"use_llm": false}'

측정 결과

150개 채용 공고 코퍼스, 8개 숏리스트. prefilter()는 태그/제목, 시니어 여부(후보자 경력 연차 < 4년이면 senior 제외), 위치(후보자 선호 도시, 별칭 정규화, 또는 원격) 게이트를 적용하여 생존자 수를 150명에서 31명으로 줄입니다:

python pipeline.py --benchmark으로 재현하세요. 이 리포지토리의 data/jobs.json에 있는 실제 수치이며, 플레이스홀더가 아닙니다. 토큰 수는 tiktoken의 o200k_base 인코더(gpt-4o / gpt-4o-mini가 실제로 사용하는 것)를 사용합니다 — 정확한 값이지 추정치가 아닙니다. 기존의 chars ÷ 4 휴리스틱은 이 코퍼스에서 기본 전략 비용을 17.4% 과대평가했습니다. benchmark()의 heuristic_vs_real_tokens 필드가 그 비교를 재현합니다.

아키텍처

   MCP SERVER (stdio subprocess)              MCP CLIENT / pipeline.py
   ---------------------------------          ------------------------------------
   tool  list_jobs        -> metadata  <----  Stage 0  prefilter()   [0 tokens]
   tool  get_job_details  -> full text        Stage 1  shortlist     [~5k tokens]
   tool  get_candidate_profile                Stage 2  score         [~4k tokens]
   tool  corpus_stats
   resource  jobs://schema                    Meter tracks tokens per stage
   prompt    rank_jobs

단계적 검색의 논거

기본 방식: 모든 전체 설명을 모델에 넘기고 순위를 요청합니다. 세 가지 문제가 있습니다.

1. 비용 — 실행당 79k 프롬프트 토큰이 들며, 코퍼스 크기에 따라 선형적으로 증가합니다.

2. 상한 — 게시물이 수백 개를 넘어서면 컨텍스트 창을 완전히 초과합니다. 느린 것이 아니라 불가능합니다.

3. 품질 — 긴 컨텍스트에서 재현율은 큰 프롬프트의 중간 부분에서 저하되므로, 후보를 더 추가할수록 순위가 더 나빠집니다.

단계적 검색, 가장 저렴한 필터 우선:

일반화 가능한 원칙 — 그리고 면접에서 실제로 말해야 할 것 — 은 비용별 캐스케이드 입니다: 필터를 가장 저렴한 것부터 순서대로 배치하고, 각 단계의 임계값은 정밀도가 아닌 재현율 기준으로 설정하세요. 이후 단계가 여전히 거부할 수 있지만, 초기 단계에서 떨어진 것은 무엇으로도 복구할 수 없기 때문입니다.

에이전트 계층 (agent.py)

pipeline.py는 고정된 스크립트입니다: 사전 필터링, 그다음 항상 숏리스트, 그다음 항상 점수화. agent.py는 OpenAI 함수 호출을 통해 모델에 동일한 MCP 도구를 제공하고, 모델이 자신만의 경로를 계획하도록 합니다 — 하드코딩된 순서가 아닌 실제 도구 호출 에이전트입니다:

• 도구 호출로 구조화된 최종 답변. 에이전트는 "JSON으로 답하고 기대"하지 않습니다 — 완료란 파라미터 스키마가 정확히 schemas.RankingResult인 합성 submit_rankings 도구를 호출하는 것을 의미합니다. 잘못된 인수는 모델이 읽고 수정할 수 있는 검증 오류로 돌아오며, 재시도 횟수는 제한되어 있습니다.

• 도구 실패는 저하될 뿐, 크래시되지 않습니다. 모든 MCP 도구 예외는 일반적인 {"error": ...} 도구 결과가 되어 모델로 다시 전달되므로, 실행 전체를 중단시키는 대신 잘못된 호출을 우회할 수 있습니다.

• 수렴하지 못한 모델도 여전히 무언가를 반환합니다. 유효한 출력 없이 단계/재시도 예산을 소진하면 에이전트는 pipeline.py와 동일한 결정적 prefilter → shortlist → score 논