pyr0ball 8cb636dabe docs: mkdocs wiki — installation, user guide, developer guide, reference

Adds a full MkDocs documentation site under docs/ with Material theme.

Getting Started: installation walkthrough, 7-step first-run wizard guide,
Docker Compose profile reference with GPU memory guidance and preflight.py
description.

User Guide: job discovery (search profiles, custom boards, enrichment),
job review (sorting, match scores, batch actions), apply workspace (cover
letter gen, PDF export, mark applied), interviews (kanban stages, company
research auto-trigger, survey assistant), email sync (IMAP, Gmail App
Password, classification labels, stage auto-updates), integrations (all 13
drivers with tier requirements), settings (every tab documented).

Developer Guide: contributing (dev env setup, code style, branch naming, PR
checklist), architecture (ASCII layer diagram, design decisions), adding
scrapers (full scrape() interface, registration, search profile config,
test patterns), adding integrations (IntegrationBase full interface, auto-
discovery, tier gating, test patterns), testing (patterns, fixtures, what
not to test).

Reference: tier system (full FEATURES table, can_use/tier_label API, dev
override, adding gates), LLM router (backend types, complete() signature,
fallback chains, vision routing, __auto__ resolution, adding backends),
config files (every file with field-level docs and gitignore status).

Also adds CONTRIBUTING.md at repo root pointing to the docs site.

2026-02-25 12:05:49 -08:00

4 KiB

Raw Blame History

Contributing

Thank you for your interest in contributing to Peregrine. This guide covers the development environment, code standards, test requirements, and pull request process.

!!! note "License" Peregrine uses a dual licence. The discovery pipeline (scripts/discover.py, scripts/match.py, scripts/db.py, scripts/custom_boards/) is MIT. All AI features, the UI, and everything else is BSL 1.1. Do not add Co-Authored-By: trailers or AI-attribution notices to commits — this is a commercial repository.

Fork and Clone

git clone https://git.circuitforge.io/circuitforge/peregrine
cd peregrine

Create a feature branch from main:

git checkout -b feat/my-feature

Dev Environment Setup

Peregrine's Python dependencies are managed with conda. The same job-seeker environment is used for both the legacy personal app and Peregrine.

# Create the environment from the lockfile
conda env create -f environment.yml

# Activate
conda activate job-seeker

Alternatively, install from requirements.txt into an existing Python 3.12 environment:

pip install -r requirements.txt

!!! warning "Keep the env lightweight" Do not add torch, sentence-transformers, bitsandbytes, transformers, or any other CUDA/GPU package to the main environment. These live in separate conda environments (job-seeker-vision for the vision service, ogma for fine-tuning). Adding them to the main env causes out-of-memory failures during test runs.

Running Tests

conda run -n job-seeker python -m pytest tests/ -v

Or with the direct binary (avoids runaway process spawning):

/path/to/miniconda3/envs/job-seeker/bin/pytest tests/ -v

The pytest.ini file scopes collection to the tests/ directory only — do not widen this.

All tests must pass before submitting a PR. See Testing for patterns and conventions.

Code Style

PEP 8 for all Python code — use flake8 or ruff to check
Type hints preferred on function signatures — not required but strongly encouraged
Docstrings on all public functions and classes
No print statements in library code (scripts/); use Python's logging module or return status in the return value. print is acceptable in one-off scripts and discover.py-style entry points.

Branch Naming

Prefix	Use for
`feat/`	New features
`fix/`	Bug fixes
`docs/`	Documentation only
`refactor/`	Code reorganisation without behaviour change
`test/`	Test additions or corrections
`chore/`	Dependency updates, CI, tooling

Example: feat/add-greenhouse-scraper, fix/email-imap-timeout, docs/add-integration-guide

PR Checklist

Before opening a pull request:

All tests pass: conda run -n job-seeker python -m pytest tests/ -v
New behaviour is covered by at least one test
No new dependencies added to environment.yml or requirements.txt without a clear justification in the PR description
Documentation updated if the PR changes user-visible behaviour (update the relevant page in docs/)
Config file changes are reflected in the .example file
No secrets, tokens, or personal data in any committed file
Gitignored files (config/*.yaml, staging.db, aihawk/, .env) are not committed

What NOT to Do

Do not commit config/user.yaml, config/notion.yaml, config/email.yaml, config/adzuna.yaml, or any config/integrations/*.yaml — all are gitignored
Do not commit staging.db
Do not add torch, bitsandbytes, transformers, or sentence-transformers to the main environment
Do not add Co-Authored-By: or AI-attribution lines to commit messages
Do not force-push to main

Getting Help

Open an issue on the repository with the question label. Include:

Your OS and Docker version
The inference_profile from your config/user.yaml
Relevant log output from make logs

4 KiB Raw Blame History