Skip to content
View 2096955's full-sized avatar
💭
I may be slow to respond, not bc I’m smart, but bc I’m slow.
💭
I may be slow to respond, not bc I’m smart, but bc I’m slow.

Block or report 2096955

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Maximum 250 characters. Please don't include any personal information such as legal names or email addresses. Markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
2096955/README.md

Multi‑Agent Job Application Assistant (Streamlit + Gradio/Hugging Face)

A production‑ready system to discover jobs, generate ATS‑optimized resumes and cover letters, and export documents to Word/PowerPoint/Excel. Includes secure LinkedIn OAuth (optional), multi‑source job aggregation, Gemini‑powered generation, and advanced agent capabilities (parallelism, temporal tracking, observability, context engineering).

What you get

  • Two UIs: Streamlit (app.py) and Gradio/HF (hf_app.py)
  • LinkedIn OAuth 2.0 (optional; CSRF‑safe state validation)
  • Job aggregation: Adzuna (5k/month) plus resilient fallbacks
  • ATS‑optimized drafting: resumes + cover letters (Gemini)
  • Office exports:
    • Word resumes and cover letters (5 templates)
    • PowerPoint CV (4 templates)
    • Excel application tracker (5 analytical sheets)
  • Advanced agents: parallel execution, temporal memory, observability/tracing, and context engineering/flywheel
  • LangExtract integration: structured extraction with Gemini key; robust regex fallback in constrained environments

Quickstart

1) Environment (.env)

Create a UTF‑8 .env (values optional if you want mock mode):

# Behavior
MOCK_MODE=true
PORT=7860

# LinkedIn OAuth (optional)
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=
LINKEDIN_REDIRECT_URI=http://localhost:8501

# LLM / Research
LLM_PROVIDER=gemini
GEMINI_API_KEY=YOUR_KEY
TAVILY_API_KEY=

# Job APIs
ADZUNA_APP_ID=
ADZUNA_APP_KEY=

# Office MCP (optional)
POWERPOINT_MCP_URL=http://localhost:3000
WORD_MCP_URL=http://localhost:3001
EXCEL_MCP_URL=http://localhost:3002

# LangExtract uses GEMINI key by default
LANGEXTRACT_API_KEY=

2) Install

  • Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
  • Linux/macOS
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3) Run the apps

  • Streamlit (PATH‑safe)
python -m streamlit run app.py --server.port 8501
  • Gradio / Hugging Face (avoid port conflicts)
$env:PORT=7861; python hf_app.py
PORT=7861 python hf_app.py

The HF app binds on 0.0.0.0:$PORT.

LinkedIn OAuth (optional)

  1. Create a LinkedIn Developer App, then add redirect URLs:
http://localhost:8501
http://localhost:8501/callback
  1. Products: enable “Sign In with LinkedIn using OpenID Connect”.
  2. Update .env and set MOCK_MODE=false.
  3. In the UI, use the “LinkedIn Authentication” section to kick off the flow.

Notes:

  • LinkedIn Jobs API is enterprise‑only. The system uses Adzuna + other sources for job data.

Job sources

  • Adzuna: global coverage, 5,000 free jobs/month
  • Resilient aggregator and optional JobSpy MCP for broader search
  • Custom jobs: add your own postings in the UI
  • Corporate SSL environments: Adzuna calls auto‑retries with verify=False fallback

Advanced agents (built‑in)

  • Parallel processing: 3–5× faster multi‑job drafting
  • Temporal tracking: time‑stamped history and pattern analysis
  • Observability: tracing, metrics, timeline visualization
  • Context engineering: flywheel learning, L1/L2/L3 memory, scalable context

Toggle these in the HF app under “🚀 Advanced AI Features”.

LangExtract + Gemini

  • Uses the same GEMINI_API_KEY (auto‑applied to LANGEXTRACT_API_KEY when empty)
  • Official langextract.extract(...) requires examples; the UI also exposes a robust regex‑based fallback (services/langextract_service.py) so features work even when cloud extraction is constrained
  • In HF app (“🔍 Enhanced Job Analysis”), you can:
    • Analyze job postings (structured fields + skills)
    • Optimize resume for ATS (score + missing keywords)
    • Bulk analyze multiple jobs

Office exports

  • Word (services/word_cv.py): resumes + cover letters (5 templates; python‑docx fallback)
  • PowerPoint (services/powerpoint_cv.py): visual CV (4 templates; python‑pptx fallback)
  • Excel (services/excel_tracker.py): tracker with 5 analytical sheets (openpyxl fallback)
  • MCP servers supported when available; local libraries are used otherwise

In HF app, after generation, expand:

  • “📊 Export to PowerPoint CV”
  • “📝 Export to Word Documents”
  • “📈 Export Excel Tracker”

Troubleshooting

  • PowerShell ampersand: don’t append &. Run the command directly.
  • Streamlit not found: use python -m streamlit run app.py (PATH‑safe).
  • Port already in use: set a free port, e.g. PORT=7861.
  • Corporate SSL issues: Adzuna auto‑retries with verify=False.
  • Kill HF app bound on a port (PowerShell):
Get-Process python | Where-Object { $_.CommandLine -like "*hf_app.py*" } | Stop-Process -Force

Directory layout (high‑level)

agents/                # Orchestrator and agent logic (incl. advanced features)
models/                # Pydantic schemas
services/              # LinkedIn client, job aggregator, Office, LangExtract svc
utils/                 # Text, security, caching, langextract wrappers
memory/                # File‑based persistence (atomic writes)
app.py                 # Streamlit UI
hf_app.py              # Gradio / HF UI (standalone‑capable)
requirements.txt       # Dependencies
README.md              # This consolidated guide

Tests & scripts

  • Run test suites in tests/
  • Useful scripts: test_* files in project root (integration checks)

Security

  • OAuth state validation, input/path/url sanitization
  • Sensitive data via environment variables; avoid committing secrets
  • Atomic writes in memory store

Run summary

  • Streamlit: python -m streamlit run app.py --server.port 8501
  • Gradio/HF: PORT=7861 python hf_app.py

Your system is fully documented here in one place and ready for local or HF deployment.

@2096955's activity is private