HireSquire

Unified open-source Python package for HireSquire — AI-powered candidate screening, local resume parsing (PDF, DOCX, TXT, MD), personalized outreach emails, compliance/bias audits, credit management, and interview scheduling.

One install gives you three agent-ready interfaces backed by a single Pydantic v2 schema and resilient HTTP client:

Node.js / TypeScript CLI: Prefer npm? Install hiresquire-cli (npx hiresquire-cli).

Installation

pip install hiresquire

Or run zero-install with uvx:

uvx hiresquire whoami --json
uvx --from hiresquire hiresquire-mcp

pypdf and python-docx are core dependencies — PDF and DOCX parsing work out of the box with no extra flags.

Authentication & Configuration

Set your API token (sk_... user token or hs_... spend-limited Agent API key):

export HIRESQUIRE_API_TOKEN="your_token_here"

Or persist it locally (written with mode 0600 to ~/.hiresquire/config.json):

hiresquire init --token YOUR_API_TOKEN

Precedence order: environment variables > ~/.hiresquire/config.json > defaults.

Quick Start

1. MCP Server (Claude Desktop, Cursor, VS Code)

Add to claude_desktop_config.json or .mcp.json using uvx (zero manual install):

{
  "mcpServers": {
    "hiresquire": {
      "command": "uvx",
      "args": ["--from", "hiresquire", "hiresquire-mcp"],
      "env": {
        "HIRESQUIRE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or if installed via pip install hiresquire:

{
  "mcpServers": {
    "hiresquire": {
      "command": "hiresquire-mcp",
      "env": {
        "HIRESQUIRE_API_TOKEN": "your_token_here"
      }
    }
  }
}

2. Python SDK

from hiresquire import HireSquireClient

with HireSquireClient("YOUR_API_TOKEN") as client:
    # Free health check (no credits spent)
    me = client.whoami()
    print(me["credits"]["formatted_balance"])

    # Submit resumes (local PDF/DOCX/TXT/MD paths or pre-parsed dicts)
    job = client.jobs.create(
        title="Senior Python Developer",
        description="Looking for a backend engineer with 5+ years of Python, FastAPI, and PostgreSQL experience.",
        resumes=["./resumes/john_doe.pdf", "./resumes/jane_smith.docx"],
        leniency_level=6,  # 1 (lenient) to 10 (strict), default 5
    )

    # Poll until completed and fetch ranked candidates
    results = client.jobs.wait(job["job_id"])
    for c in results["candidates"]:
        print(f"{c['id']}: {c['name']} — {c['score']}/100 | {c['summary']}")

    # Generate an interview invite for the top candidate
    top = results["candidates"][0]
    email = client.emails.generate(
        job_id=job["job_id"],
        candidate_id=top["id"],
        email_type="invite",
        tone="professional",
    )
    print(email["subject"], email["body"])

3. CLI (--json ready for agents)

# Free token & balance check
hiresquire whoami --json

# Estimate credit cost before screening
hiresquire estimate --candidates 25 --json

# Submit resumes, poll until completion, and output JSON
hiresquire screen \
  --title "Senior Python Developer" \
  --description "Looking for a backend engineer with 5+ years of Python, FastAPI, and PostgreSQL experience." \
  --resumes ./resumes/ \
  --leniency 6 \
  --watch \
  --json

# Filter results by score or top N
hiresquire results --job 123 --min-score 80 --only-top-n 5 --json

# Generate outreach email
hiresquire email --job 123 --candidate 456 --type invite --tone friendly --json

MCP Tools Reference (26 Tools)

All MCP tools run locally over stdio via FastMCP, extract resume text locally (never uploading raw binary files), and return structured JSON dicts (including {"error": "...", "message": "..."} on failure rather than crashing).

Python SDK Namespaces

HireSquireClient organizes the API into seven typed namespaces (all validated with Pydantic v2 models in hiresquire.models):

• client.jobs: create(), create_from_zip(), list(), get_status(), get_results(), wait(), cancel(), compare(), report_outcome()
• client.candidates: get(), update_status()
• client.emails: generate(), bulk_generate(), generate_questions(), generate_icebreaker()
• client.credits: get_balance(), estimate_cost(), list_packs(), get_transactions(), purchase(), create_checkout_session(), create_payment_intent(), enable_auto_reload(), disable_auto_reload()
• client.calendar: list(), connect(), get_slots(), create_interview(), generate_meeting_link()
• client.agent_keys: list(), create(), get(), update(), revoke(), regenerate(), get_usage()
• client.utils: whoami(), get_rate_limit(), test_webhook(), get_api_schema(), audit_screening_job()

Schemas & Contracts (for Agents)

Create Screening Job Request (POST /api/v1/jobs)

{
  "title": "Senior Python Developer",
  "description": "Minimum 50 characters describing role requirements and stack.",
  "resumes": [
    { "filename": "ada_lovelace.pdf", "content": "Extracted resume text..." }
  ],
  "leniency_level": 5,
  "custom_instructions": "Prioritize distributed systems experience",
  "webhook_url": "https://example.com/webhooks/hiresquire"
}

• Idempotency-Key (UUID v4) is auto-generated and sent as an HTTP header on jobs.create, jobs.create_from_zip, and credits.purchase so retries never double-charge.
• leniency_level: integer 1 (most lenient) to 10 (strictest), default 5.
• Resume limits: .txt, .md, .pdf, .docx; max 20 MB per file, max 100 resumes per batch, minimum 50 characters of extracted text.

Screening Results Response (GET /api/v1/jobs/{id}/results)

{
  "job_id": 42,
  "job_title": "Senior Python Developer",
  "status": "completed",
  "total_candidates": 1,
  "candidates": [
    {
      "id": 101,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "score": 94,
      "summary": "Strong distributed systems and Python background.",
      "strengths": ["10+ years Python", "Event-driven architecture"],
      "weaknesses": ["Limited Kubernetes exposure"],
      "skills": ["Python", "PostgreSQL", "FastAPI"],
      "status": "new"
    }
  ],
  "agent_summary": "1 strong match identified..."
}

Error Hierarchy (hiresquire.errors)

CLI Command Reference

Pass --json to any command for clean machine-readable output:

hiresquire init              Save token & defaults to ~/.hiresquire/config.json (0600)
hiresquire configure         Update or --clear saved configuration
hiresquire whoami            Verify token and check credit balance (free)
hiresquire estimate          Estimate cost for N candidates
hiresquire screen            Submit resumes (--resumes or --zip, --watch, --leniency)
hiresquire jobs              List screening jobs (--status, --page, --limit)
hiresquire status            Check or --watch job status
hiresquire results           Fetch ranked candidates (--min-score, --only-top-n)
hiresquire summary           Display AI summary for a completed job
hiresquire compare           Compare candidates side-by-side
hiresquire cancel            Cancel a processing job
hiresquire outcome           Report hiring outcome (hired | rejected | withdrawn)
hiresquire candidate         Get candidate details
hiresquire set-status        Update candidate status
hiresquire email             Generate outreach email (--type, --tone, --message)
hiresquire credits ...       balance | list-packs | checkout | purchase | transactions | auto-reload-enable | auto-reload-disable
hiresquire agent-keys ...    list | create | get | update | revoke | regenerate | usage
hiresquire calendar ...      connect | list (also calendar:connect, calendar:list)
hiresquire interviews ...    schedule | list (also interviews:schedule, interviews:list)
hiresquire meetings link     Generate meeting link (also meetings:link)
hiresquire rate-limit        Check API rate limit status
hiresquire webhook-test      Send a test webhook payload
hiresquire schema            Fetch API schema
hiresquire mcp               Start the stdio MCP server

Backward Compatibility (v1 → v2)

Existing v1 code continues to work without changes:

from hiresquire import HireSquire  # alias for HireSquireClient
from hiresquire import create_screening_job, get_hiresquire_tools  # deprecated v1 wrappers

Deprecated top-level functions emit DeprecationWarning and delegate to HireSquireClient.

Links & Ecosystem

• PyPI: https://pypi.org/project/hiresquire/
• GitHub: https://github.com/bp46/hiresquire
• Node.js CLI (npm): https://www.npmjs.com/package/hiresquire-cli
• MCP Registry: mcp-name: io.github.bp46/hiresquire
• API Docs: https://hiresquireai.com/docs/api
• Agent Docs: https://hiresquireai.com/docs/agents
• Support: info@hiresquireai.com

License

MIT License — see LICENSE.