Skip to content
AI Agent Campfire

Job Scout: Detailed Architecture

🛠️ JobScout — Tech Stack & Architecture

Section titled “🛠️ JobScout — Tech Stack & Architecture”

Overview

Section titled “Overview”

JobScout is an agentic AI job-search assistant that automates searching, scoring, and tailoring resumes/CVs for job postings with human-in-the-loop approval. It orchestrates multiple LLM-powered modules — resume parsing, tailored content generation, cover-letter writing, semantic matching, and persistent storage — in a repeatable scouting cycle.

📐 Architecture at a Glance

Section titled “📐 Architecture at a Glance”
Layer Role
CLI / Harness Entry point (run_scouting_cycle) that orchestrates the end-to-end pipeline: parse → search → score → tailor → write → store
Matching Engine Scoring module (semantic + keyword overlap) against a local Chroma vector database
Tools Modular LLM callables — resume_parser, resume_tailor, cover_letter_writer
Storage ChromaDB for persistent job embeddings + seen-URL deduplication; CSV / Excel exports; SQLite metadata cache (via Langfuse telemetry)
External Services OpenAI-compatible LLM API, Ollama (local nomic-embed-text), Langfuse (telemetry), custom Parse API (PARSE_API_KEY)

Architecture Diagrams

Section titled “Architecture Diagrams”

View High-Level Design

🧱 Core Dependencies (Python ≥ 3.11)

Section titled “🧱 Core Dependencies (Python ≥ 3.11)”
Category Package Purpose
Async HTTP aiohttp Async job-search HTTP requests, API calls
LLM SDK claude-agent-sdk Claude / Anthropic model client
Vector Store chromadb Local persistent embeddings & deduplication
PDF Handling pypdf Parse .pdf resumes
Docx Handling python-docx Parse .docx resumes & generated documents
Spreadsheet Output openpyxl Export results to .xlsx / .csv
Data Validation pydantic Typed schemas for CycleResult, TailoredResume, CoverLetter, etc.
Environment Config python-dotenv .env variable injection
Config / YAML pyyaml YAML configuration loading
Telemetry & Tracing langfuse Embedding traces, latency tracking, LLM call monitoring

Optional / Dev Dependencies

Section titled “Optional / Dev Dependencies”
Package Purpose
pytest ≥ 7.0 Test runner
pytest-asyncio ≥ 0.21 Async test support
pytest-timeout ≥ 2.3 Guard against hanging tests
ruff Fast Python linter / formatter

🌐 External Services & APIs

Section titled “🌐 External Services & APIs”
Service Role Config Key(s)
OpenAI-compatible LLM API Claude, GPT-4-style model calls for parsing, tailoring, cover-letter generation PARSE_API_KEY, OPENAI_API_KEY (or equivalent env vars)
Ollama Local embedding model (nomic-embed-text) for vector similarity scoring Installed locally; no remote API key
Langfuse Cloud / Self-hosted Traces, metrics & cost monitoring for every LLM call LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY (optional)
Custom Parse API Proprietary resume parsing endpoint (fallback to local OCR when offline) PARSE_API_KEY

🧪 Testing Strategy

Section titled “🧪 Testing Strategy”
Tool Coverage Mode
pytest + pytest-asyncio Unit, integration, and harness-level tests (~165+ tests) Auto mode for async fixtures
Timeout guard Prevents hung tests (> 60 s each) pytest-timeout enforced globally
Markers Categorisation: integration, ollama, harness Granular test selection via -m flag

📦 Project Layout

Section titled “📦 Project Layout”
JobScout/
├── src/                      # Core source code (Python package)
│   ├── matching/             # Scorer, cosine-similarity, semantic match logic
│   ├── tools/                # resume_parser, resume_tailor, cover_letter_writer
│   ├── harness/              # run_cycle.py — pipeline orchestration
│   ├── local_models/         # OllamaClient wrapper (nomic-embed-text)
│   ├── data/                 # vector_store.py — ChromaDB persistence layer
│   └── config/               # YAML / env-driven configuration loaders
├── applications/             # CLI entry points, dashboard consumers
├── tests/                    # Full test suite (unit + integration)
├── data/                     # Sample resumes, generated job sheets (XLSX/CSV)
├── help/                     # Onboarding docs and helper scripts
├── pyproject.toml            # Build config, deps, ruff & pytest settings
├── .env.example              # Template for required environment variables
├── run_jobscout.sh           # Bash bootstrap entry point
└── cleanup.sh                # Sanitization & temporary-file removal

🔐 Security & Data Privacy

Section titled “🔐 Security & Data Privacy”
  • Local-first vector storage — ChromaDB data lives on-disk; no cloud vector endpoint required.
  • Embeddings stored locally via Ollama (nomic-embed-text) — sensitive resume content never leaves the machine for retrieval.
  • LLM calls may transmit text to third-party APIs; PARSE_API_KEY / OPENAI_API_KEY are managed through .env.
  • Exported spreadsheets (data/*.xlsx, data/*.csv) should be reviewed before sharing externally.

⚙️ Configuration

Section titled “⚙️ Configuration”
Source Format Usage
.env / .env.example Key-value pairs API keys, model names, ChromaDB path
config/*.yaml (if present) YAML Thresholds, scoring weights, job-search parameters

🚀 Running the Project

Section titled “🚀 Running the Project”
Terminal window
# 1. Install dependencies
pip install -e ".[dev]"


# 2. Set up environment variables
cp .env.example .env
# Edit .env with your API keys


# 3. Run the scouting cycle (CLI or harness)
./run_jobscout.sh           # Bash bootstrap entry point
python -m src.harness.run_cycle   # Direct Python entry


# 4. Run tests
pytest -v
pytest -m "integration"          # Tests requiring real API keys
pytest -m "ollama"               # Tests requiring local Ollama

📊 Observability & Telemetry

Section titled “📊 Observability & Telemetry”
Metric Instrumented Via Notes
LLM token usage & cost Langfuse spans Per-parse, per-tailor, per-cover-letter
Embedding latency Langfuse + custom logging Vector-store fetch time tracked separately
Match scores (semantic vs overlap) CycleResult payload Exported to Excel for review

Last updated: August 2026 · Project Version 0.1.0