Documentation
Architecture
The pipeline, the schemas, and the deterministic/reasoning split that defines CareerOS.
The deterministic / reasoning boundary
This is the single most important thing to internalize. The system splits cleanly in two:
- Deterministic — discover, normalize, dedupe, constraints, threshold, sheets, drive, lint, cache. Pure Python, no model calls, reproducible given the same inputs.
- Reasoning — the AI gate, evaluation, resume, cover letter, application answers, and the deep report. Each is a read-prompt-then-write-file step, and every output is checked before it's accepted.
Never blur the boundary: don't hand-write what a deterministic stage should compute, and don't let a deterministic stage fabricate what a reasoning step should decide.
The pipeline, in order
| 01 | Discover | Query every enabled provider with one segmented search per work-mode tier, then merge the results. |
| 02 | Normalize | Map every provider's payload onto one universal Job schema. The rest of the pipeline never knows which source a job came from. |
| 03 | Dedupe | Drop jobs already seen this run, in a prior run, or already sitting in your Sheet. First occurrence wins. |
| 04 | Constraints | Hard-reject on the two objective deal-breakers — location and salary — before a single token is spent. |
| 05 | AI Gate | A cheap, batched keep/drop triage against your headline and targets. Biased to keep — recall over precision. |
| 06 | Evaluate | The one real reasoning step. Scores each surviving job against the rubric and writes structured JSON only — no long report. |
| 07 | Threshold | Partition evaluated jobs into two tiers and re-check the hard constraints as a backstop. |
| 08 | Resume + Cover | For Apply-tier jobs only, select resume bullets and a cover-letter spine from your profile. Select — never invent. |
| 09 | Application Package | Draft answers to a form's real questions, render a zero-cost daily report from the eval JSON, and append a row per job to your Google Sheet. |
The filesystem is the message bus
CareerOS has no server and no database. Every stage reads one JSON file and
writes another, under .careeros/runs/<date>/. That makes
every run inspectable, resumable, and cheap to re-run — unchanged inputs hit
the cache, not the model.
Three schemas hold it together
- Job — the universal contract every provider must output, so the pipeline never knows which source a job came from. Its ID is a deterministic hash, which is what makes deduplication possible.
- Profile — your facts, the second source of truth. It enforces verbatim bullets and carries a version that flows into every cache key.
- Eval — written once by the evaluate stage, and never re-scored. It caps strengths and weaknesses so the daily report stays scannable, and its fit paragraph doubles as the cover-letter spine.
Caching
Every AI output is content-addressed on a fingerprint of the job's content hash, your profile version, and the active prompt version (resumes and cover letters also include the eval score). There's no database and no expiry — a miss simply re-runs the stage. Enrichment that can't change a judgment, like a later-discovered salary, is deliberately excluded from the hash.