Skip to main content

opengrasp

License MIT PyPI Python Local First HITL

Autonomous job search agent. Runs 100% locally. Your CV never leaves your machine.

opengrasp is an open-source, privacy-first, terminal-first job application assistant. It helps you discover roles, score fit, tailor ATS-safe CVs, and draft applications with Human In The Loop controls.

Why

career-ops showed the world this is possible. opengrasp makes it accessible to everyone:

  • No paid cloud AI subscription requirement
  • No cloud API key requirement
  • No vendor lock-in
  • Full local control over data and models

What It Does

opengrasp is designed as an end-to-end local pipeline:

  1. Job discovery across configured portals
  • scans active portals and discovers new listings
  • deduplicates against existing DB records and scan history
  1. 10-dimension fit evaluation
  • scores each role from 1.0 to 5.0 across role, skills, seniority, compensation, geo, stage, PMF, growth, interview likelihood, and timeline
  • computes weighted score + grade (A/B/C/D/F)
  • writes a markdown report to reports/
  1. Tailored ATS CV generation
  • extracts high-value JD keywords
  • reorders bullets by relevance (without deleting user content)
  • renders ATS-safe HTML to PDF via Playwright
  • saves artifacts to output/ and metadata to DB
  1. Human-reviewed application drafting
  • opens and drafts common form fields
  • never auto-submits
  • requires explicit human review before marking as applied
  1. Parallel batch processing
  • processes queued URLs concurrently
  • fault tolerant: one failure does not block the queue
  • resumable behavior for previously processed jobs
  1. Outcome learning loop
  • logs interview/rejection/offer/ghosted outcomes
  • adjusts scoring weights in DB based on feedback patterns

Quick Start

pip install opengrasp
opengrasp setup

Then:

opengrasp scan

Required: enable at least 1 portal

scan requires at least one active portal in portals.yml (setup creates it for you, but everything is disabled by default).

  1. Open portals.yml
  2. Set at least one entry to active: true
  3. Run:
opengrasp doctor
opengrasp scan --limit 5 --link-limit 30

1) Developer install (this repo)

python -m venv .venv
.venv\Scripts\activate
pip install -e .
python -m playwright install chromium

Run quick health checks:

opengrasp doctor

Run unit tests:

python -m unittest discover -s tests -v

2) User install (PyPI / TestPyPI)

Once you publish (see “Publish To PyPI” below), verify in a clean environment:

python -m venv .venv
.venv\Scripts\activate
pip install opengrasp
opengrasp setup
opengrasp doctor

3) End-to-end CLI smoke test

  • Ensure portals.yml exists (setup creates it) and set at least one portal to active: true.
  • Scan:
opengrasp scan --limit 5 --link-limit 30
  • Run auto-pipeline for a known job URL:
opengrasp pipeline <job-url>
  • Open tracker TUI:
opengrasp tracker

Philosophy

AI analyzes. You decide. HITL always.

opengrasp intentionally avoids full autonomy on final submission actions. The system can evaluate, draft, and prefill, but a human must review before applying.

Core Commands

opengrasp setup
opengrasp doctor
opengrasp scan
opengrasp scan --auto
opengrasp batch --min-score B --limit 20
opengrasp pipeline <url-or-jd-text>
opengrasp apply <url-or-jd-text>
opengrasp tracker
opengrasp learn <job-id> <outcome>

Models

opengrasp uses local Ollama models. A practical starting setup:

  • llama3.1:8b for evaluation

    • Pros: fast, low hardware footprint, good for scoring and routing
    • Tradeoff: less nuanced generation quality for long-form text
  • qwen2.5:14b for generation

    • Pros: stronger CV/cover-letter drafting quality
    • Tradeoff: slower and heavier resource usage

General guidance:

  • Use smaller models for high-volume scan/eval loops.
  • Use larger models for final artifact generation quality.
  • Keep all inference local through Ollama.

Local-First Privacy

  • CV, config, reports, and generated files are stored locally.
  • SQLite DB runs locally (data/opengrasp.db).
  • Prompt and model execution are local-first by design.

Project Status

opengrasp is in active development (0.1.3) and currently optimized for terminal workflows. Web UI support is planned as secondary priority.

Documentation

  • docs/README.md (documentation index)
  • docs/SETUP.md
  • docs/ARCHITECTURE.md
  • docs/PUBLISH.md (maintainers: publish to PyPI)
  • CONTRIBUTING.md
  • SECURITY.md
  • CODE_OF_CONDUCT.md

Community

To help keep the project healthy and maintainable:

  • Read CONTRIBUTING.md before opening pull requests.
  • Review SECURITY.md for vulnerability reporting guidance.
  • Follow CODE_OF_CONDUCT.md in all project spaces.

Publish To PyPI

Use this flow to publish releases so users can run:

pip install opengrasp
opengrasp setup

Build and validate:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Test install from TestPyPI in a clean environment:

python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple opengrasp

Upload to PyPI:

python -m twine upload dist/*

PowerShell helper:

./scripts/publish.ps1
./scripts/publish.ps1 -TestPyPI
./scripts/publish.ps1 -PyPI

Inspiration

Inspired by the ideas popularized in career-ops (MIT). opengrasp is implemented from scratch as a standalone Python product.

License

MIT

Metadata

Release files for opengrasp 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opengrasp 0.1.3
File Size Uploaded Provenance Actions
opengrasp-0.1.3.tar.gz 67.3 kB Without provenance Details for opengrasp-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opengrasp 0.1.3
File Interpreter ABI Platform Actions
opengrasp-0.1.3-py3-none-any.whl Python 3 none any Details for opengrasp-0.1.3-py3-none-any.whl

Total release size: 151.0 kB

Release files / opengrasp-0.1.3.tar.gz

Download URL opengrasp-0.1.3.tar.gz
Size 67.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0b7915fcf8514e8b298caf37b01407913c709479722d788bd80e8165203d981d
BLAKE2b-256 checksum
How to use checksums
ac612ad0d211868c0cf0252c5024972f9e9180bf23fa616d481832e154c06ab1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.4

Release files / opengrasp-0.1.3-py3-none-any.whl

Download URL opengrasp-0.1.3-py3-none-any.whl
Size 83.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c3af43b31083b29a973cd7f3684ca3a466ae3f0fa37e49a467deb4e947f63588
BLAKE2b-256 checksum
How to use checksums
5a7f5b7fb3ea006565f6591f117a08d30b798a2d3609be38a350c842dceda7a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.4

Security for opengrasp 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page