kestrel-agent 0.1.0__tar.gz

kestrel_agent-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# Kestrel Environment Configuration
+# Copy to ~/.kestrel/.env and fill in your values.
+
+# LLM Provider (pick one)
+GEMINI_API_KEY=           # Gemini 2.0 Flash (recommended, cheapest)
+# OPENAI_API_KEY=         # OpenAI (GPT-4o-mini)
+# LLM_URL=http://127.0.0.1:8080/v1  # Local LLM (llama.cpp, Ollama)
+# LLM_MODEL=              # Override model name
+
+# Auto-Apply (optional)
+CAPSOLVER_API_KEY=        # For CAPTCHA solving during auto-apply
+
+# Auto-Apply engine (optional; default: claude)
+# AUTOAPPLY_ENGINE=droid  # claude | droid
+# FACTORY_API_KEY=        # Required when the engine is droid (child env only)
+
+# Proxy (optional, for scraping)
+# PROXY=host:port:user:pass

kestrel_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Install Playwright Chromium
+        run: playwright install --with-deps chromium
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -v

kestrel_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+# Publish kestrel-agent to PyPI on version tags (v*), via OIDC trusted publishing.
+#
+# MANUAL SETUP REQUIRED BEFORE THE FIRST TAG (release runbook):
+#
+# 1. The PyPI project `kestrel-agent` must be registered before the first
+#    publication. Registration happens on first upload — but with trusted
+#    publishing, the project must instead be pre-created on PyPI with the
+#    pending publisher configured (PyPI -> Publishing -> add a pending
+#    trusted publisher), because a tag-triggered workflow cannot claim an
+#    unregistered project name without a human in the loop.
+# 2. Configure the trusted-publisher entry on PyPI for
+#    `Vontarius-Ventures/kestrel`:
+#      - owner: Vontarius-Ventures
+#      - repository: kestrel
+#      - workflow name: publish.yml
+#      - environment: pypi
+#    (Note the repository name is `kestrel`, while this file lives in the
+#    private repo `VontariusF/ApplyPilot` until the public cut; the entry
+#    must point at the public repo.)
+# 3. The `pypi` GitHub environment must exist on the target repo with the
+#    OIDC id-token permission (granted here via `permissions.id-token`).
+#
+# Kestrel is an AGPL-3.0 fork of Pickle-Pixel/ApplyPilot; see NOTICE and
+# README for upstream attribution.
+
+name: Publish kestrel-agent to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build kestrel-agent distribution
+        run: python -m build
+
+      - name: Publish kestrel-agent to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kestrel_agent-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# User data (NEVER commit)
+profile.json
+resume.txt
+resume.pdf
+*.env
+.env.*
+!.env.example
+
+# Runtime artifacts
+*.db
+tailored_resumes/
+cover_letters/
+chrome-workers/
+apply-workers/
+apply_logs/
+logs/
+
+# MCP configs (per-machine)
+.mcp*.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Owner secrets (never ship or commit)
+*.local
+.env*.local
+
+# Local SQLite databases (never commit)
+*.sqlite3
+*.sqlite3-journal
+
+# Claude Code
+.claude/

kestrel_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to Kestrel will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-09
+
+First public release of Kestrel, the open-source job-search and application
+assistant.
+
+### About
+
+Kestrel helps candidates discover and evaluate jobs, prepare tailored
+application materials, and manage applications through a human-supervised,
+localhost-first workflow. This release is cut from a fresh versioning start:
+`0.1.0` restarts the version lineage and this changelog begins anew.
+
+### Lineage
+
+Kestrel is a fork of [ApplyPilot](https://github.com/Pickle-Pixel/ApplyPilot)
+by Pickle-Pixel, released under the GNU Affero General Public License
+v3.0. Upstream copyright is retained; Kestrel's changes continue to be
+distributed under AGPL-3.0. See `LICENSE` and `NOTICE` for attribution
+details.
+
+### Added (carried from the fork)
+
+- 6-stage pipeline: discover, enrich, score, tailor, cover letter, apply
+- Multi-source job discovery: Indeed, LinkedIn, Glassdoor, ZipRecruiter, Google Jobs
+- Workday employer portal support with a preconfigured employer registry
+- Direct career site scraping with a 3-tier extraction cascade
+  (JSON-LD, CSS selectors, AI fallback)
+- AI-powered job scoring (1-10 fit scale with rationale) and composable
+  filters with reranking and score history
+- Resume tailoring with factual preservation (no fabrication) and
+  per-job cover letter generation
+- Autonomous browser-based application submission via Playwright, with
+  plan-then-confirm controls, attempt limits, and human-gated submissions
+- Typer-based CLI (`kestrel`), machine-readable `status --json` and
+  `doctor --json` output, and an agent-driven onboarding flow
+- Optional single-user FastAPI portal (localhost, auth by default)
+- Multi-provider LLM support (Gemini, OpenAI, local models via
+  OpenAI-compatible endpoints)
+- Local SQLite storage under `~/.kestrel`
+
+### Changed from upstream
+
+- Package distribution and PyPI name: `kestrel-agent` (CLI: `kestrel`)
+- Default data directory: `~/.kestrel` (migrates from `~/.applypilot`
+  on first run; `KESTREL_DIR` replaces `APPLYPILOT_DIR` with the legacy
+  variable still honored as a fallback)
+- Environment namespace: `KESTREL_*` replaces `APPLYPILOT_*`, with legacy
+  fallbacks for compatibility
+- Privacy: removed personal fixtures, machine-specific paths, and
+  internal transcripts; rebalanced the example employer registry toward a
+  geographically neutral sample

kestrel_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contributing to Kestrel
+
+Thank you for your interest in contributing to Kestrel — an AGPL-3.0 fork of
+[Pickle-Pixel/ApplyPilot](https://github.com/Pickle-Pixel/ApplyPilot). This
+guide covers development setup, the gates every change must pass, and the
+ground rules for what never enters the repository.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher
+- Git
+
+### Clone and Install
+
+```bash
+git clone https://github.com/Vontarius-Ventures/kestrel.git
+cd kestrel
+pip install -e ".[dev]"
+playwright install chromium
+```
+
+This installs Kestrel in editable mode with the development dependencies
+(pytest, ruff, and the portal stack) and downloads the Chromium browser
+binary for Playwright.
+
+### Verify the installation
+
+```bash
+kestrel --version
+kestrel doctor --json
+```
+
+## Must-pass gates
+
+These must pass before you open a PR — CI runs them, and a red gate blocks
+the merge:
+
+```bash
+ruff check .                 # lint (src + tests)
+pytest tests -m "not e2e"    # unit suite (non-e2e)
+```
+
+For portal or onboarding changes, also run the browser e2e suite
+(`pytest tests/e2e`); Chromium must be installed once per machine
+(`playwright install chromium`) — without it the e2e tests silently SKIP,
+and a skipped gate is no gate.
+
+## How to contribute
+
+1. Check existing [issues](https://github.com/Vontarius-Ventures/kestrel/issues)
+   to avoid duplicating work; for new features, open an issue first to
+   discuss the approach.
+2. Fork the repo and create a feature branch from `main`.
+3. Write code with type hints and docstrings, and add tests for new
+   functionality — bug fixes need a regression test.
+4. Run the must-pass gates above.
+5. Submit a PR with a clear description of what changed and why.
+
+### Adding Workday employers and career sites
+
+Workday employer portals live in `src/kestrel/config/employers.yaml`; direct
+career sites in `src/kestrel/config/sites.yaml`. Find the portal URL and
+Workday instance/tenant (or the site's CSS selectors for job listings), add
+an entry following the existing format, and verify with
+`kestrel run --stage discover` against that employer or site before
+submitting.
+
+## Code style
+
+- **Type hints** on all function signatures.
+- **Docstrings** (Google style) on all public functions and classes.
+- **snake_case** for functions and variables, **PascalCase** for classes.
+- **Imports** sorted by Ruff (isort-compatible); **line length** 120
+  characters.
+- Auto-fix what Ruff can fix: `ruff check src/ --fix`.
+
+## Ground rules — never commit
+
+These are hard rules, enforced by review; violations are removed on sight:
+
+- **Keys, tokens, or credentials of any kind** — API keys, OAuth tokens,
+  session cookies, password files.
+- **`.env*.local` and `*.local` files** — local-only configuration and
+  secrets stay on your machine. `.env.example` (placeholders only) is the
+  template that ships.
+- **Personal machine details** — home-directory paths, hostnames, IPs,
+  usernames, deployed-service configs (e.g., launchd plists).
+- **Local databases** — SQLite files and their journals.
+- **Live resume/profile data** — `profile.json` and `resume.txt` are
+  git-ignored; commit only the `profile.example.json` / example fixtures.
+
+## Project structure
+
+```
+kestrel/
+├── src/kestrel/          # Main package
+│   ├── cli.py            # CLI entry points
+│   ├── pipeline.py       # Stage orchestration (tailor, cover letters, PDF)
+│   ├── discovery/        # Stage 1: job discovery scrapers
+│   ├── enrichment/       # Stage 2: description extraction
+│   ├── scoring/          # Stage 3: AI scoring
+│   ├── apply/            # Stage 6: browser automation (Claude/Droid engines)
+│   ├── portal/           # Localhost web portal
+│   ├── wizard/           # Onboarding wizard
+│   ├── agent_protocol.py # Host-driven agent protocol (JSON verbs)
+│   ├── database.py       # SQLite store
+│   └── config/           # Bundled YAML configs (employers, sites, searches)
+├── tests/                # Test suite (unit + e2e)
+└── pyproject.toml        # Package configuration
+```
+
+## License
+
+By contributing to Kestrel, you agree that your contributions will be
+licensed under the [GNU Affero General Public License v3.0](LICENSE).
+Kestrel retains upstream ApplyPilot attribution per [NOTICE](NOTICE).