Metadata-Version: 2.4
Name: vita-cv
Version: 2.5.2
Summary: VITA — CV as Code : personal CV management CLI
Author-email: Abdellah HALLOU <abdeallahhallou33@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ABDELLAH-Hallou/vita-cv
Project-URL: Bug Tracker, https://github.com/ABDELLAH-Hallou/vita-cv/issues
Keywords: resume,cv,career,latex,git
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# VITA — CV as Code

> **One base CV. Infinite targeted variants. Zero duplicates.**
>
> `vita-cv` is a CLI tool that treats your resume like source code — versioned with git, branched per company, built from LaTeX, and sharpened with AI assistance.

VITA can generate targeted AI prompts or run an autonomous AI workflow to analyze job descriptions, adapt your CV, and write a matching cover letter. Customize each task with your own Markdown skills.

```sh
uv tool install vita-cv
```

---

## How It Works

VITA manages your CV using git branches:

| Branch | Purpose |
|---|---|
| `master` | Your canonical base — the CV you're always proud of |
| `gen-<role>` | Domain-specific base (e.g. `gen-swe`, `gen-ml`) |
| `etp-<company>-<role>` | Tailored CV for a specific application (e.g. `etp-google-swe`) |

Every time you apply somewhere, you create a branch. VITA tracks that in a registry so you never accidentally send the wrong version or apply twice.

---

## Prerequisites

- **uv** — [install](https://docs.astral.sh/uv/getting-started/installation/) (`pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- **Python 3.10+** — managed automatically by uv
- **Git** (must be in PATH)
- **LaTeX** — [TeX Live](https://tug.org/texlive/) or [MiKTeX](https://miktex.org/), with `latexmk`

---

## Quick Start

```sh
# 1. Install vita from PyPI as a persistent tool
uv tool install vita-cv
# → vita is now available globally in your terminal

# 2. Create your CV project directory
mkdir my-cv && cd my-cv

# 3. Initialize VITA (creates .vita/ and git repo)
vita init

# 4. Edit .vita/config.json — set your name
#    "author": "yourname"

# 5. Create your LaTeX CV (see below)
# ... write main.tex, sections/, etc.

# 6. Commit your base CV
git add .
git commit -m "base: initial CV"

# 7. Apply to a company
vita new etp google "software engineer"
# → creates branch etp-google-swe, updates registry

# 8. Tailor your CV for this job, then build
vita build
```

---

## Your CV Project Structure

After running `vita init`, your project should look like this:

```
my-cv/
├── main.tex              ← LaTeX entry point (you create this)
├── sections/             ← Modular CV sections (you create these)
│   ├── experience.tex
│   ├── education.tex
│   ├── skills.tex
│   └── ...
├── job.md                ← Paste job descriptions here (for AI prompts)
├── cover-letter.tex      ← Cover letter source (generated by vita cover)
├── out/                  ← PDF output (auto-created on build)
│
└── .vita/                ← Auto-created by `vita init`
    ├── config.json       ← Your settings (author, output paths, etc.)
    ├── companies.json    ← Registry of all companies you've applied to
    ├── extensions.json   ← Your custom role aliases, languages, and LLM providers
    ├── .env              ← Local API keys for --auto mode
    ├── .env.example      ← Example API key file
    ├── skills/           ← Custom skills in analyze/, adapt/, review/, cover/
    ├── prompts/          ← Generated prompts for each task
    └── logs/             ← CLI activity log
```

> `.vita/` is gitignored — your registry and config stay local.

---

## Files You Need to Create

VITA manages the `.vita/` directory for you. **You are responsible for the LaTeX files.**

### `main.tex` — Entry Point

Your main LaTeX file. VITA will compile this with `latexmk`. Example minimal structure:

```latex
\documentclass{article}

\begin{document}

\input{sections/experience}
\input{sections/education}
\input{sections/skills}

\end{document}
```

You can use any LaTeX CV class (e.g. `moderncv`, `altacv`, `awesome-cv`).

### `sections/` — Modular Content

Split your CV into files so each branch only touches relevant sections:

```
sections/
├── experience.tex   ← Work history (most frequently changed per company)
├── education.tex    ← Education
├── skills.tex       ← Skills (adjust keywords per role)
├── summary.tex      ← Optional: tailored headline
└── projects.tex     ← Optional
```

### `job.md` — Job Description (for AI prompts)

When you run `vita adapt` or `vita analyze`, VITA looks for `job.md` in your project root. Paste the job posting there:

```markdown
Company: Google
Role: Senior Software Engineer

[Paste full job description here]
```

---

## Configuration Reference

`vita init` creates `.vita/config.json` with these defaults:

```json
{
  "author": "",
  "output_dir": "out",
  "output_filename": "cv-{author}.pdf",
  "tex_entry": "main.tex",
  "cover_tex_entry": "cover-letter.tex",
  "cover_output_filename": "cover-letter-{author}.pdf",
  "build_mode": "auto",
  "default_base_branch": "master",
  "strict_mode": false,
  "allow_multiple_per_company": true,
  "warn_on_duplicate": true,
  "auto_add_codex_provider": false
}
```

| Key | What it does |
|---|---|
| `author` | Your name — used in the PDF filename |
| `output_dir` | Where the compiled PDF goes (`out/` by default) |
| `output_filename` | PDF name template. `{author}` is substituted automatically |
| `tex_entry` | Your LaTeX entry file (default: `main.tex`) |
| `cover_tex_entry` | Cover letter LaTeX source (default: `cover-letter.tex`) |
| `cover_output_filename` | Cover letter PDF name (default: `cover-letter-{author}.pdf`) |
| `build_mode` | Reserved build mode setting (`auto` by default) |
| `default_base_branch` | The branch `vita new` checks out from if no base exists |
| `strict_mode` | Reserved stricter workflow setting (`false` by default) |
| `allow_multiple_per_company` | Reserved duplicate-policy setting |
| `warn_on_duplicate` | If `true`, warns (but doesn't block) on duplicate company |
| `auto_add_codex_provider` | If `true`, automatically adds a missing Codex provider to `extensions.json` without prompting |

---

## CLI Commands

### `vita init`

Initialize VITA in the current directory. Creates `.vita/`, scaffolds config files, and runs `git init`.

```sh
vita init          # first-time setup
vita init --force  # wipe and re-initialize
```

---

### `vita new etp <company> <role>`

Create a new tailored CV branch for a job application.

```sh
vita new etp google "software engineer"
vita new etp openai ml
vita new etp stripe "backend engineer" --commit  # commit pending changes first
```

- Normalizes the role (`software engineer` → `swe`)
- Creates branch `etp-<company>-<role>` off your base branch
- Registers the company in `.vita/companies.json`
- Warns if you've already applied to this company

---

### `vita status`

See all companies, branches, and where you currently are.

```sh
vita status
```

```
VITA Status — yourname
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current branch : etp-google-swe

Companies (2):
  google  [2 CVs]
    ├── etp-google-swe   base: gen-swe   ← you are here
    └── etp-google-ml    base: gen-ml

  meta  [1 CV] [LOCKED]
    └── etp-meta-swe     base: gen-swe

Base branches:
  gen-swe · gen-ml
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

### `vita sync`

Reconcile the `.vita` directory and registry with your actual git branches. Useful if you created or deleted branches manually, or if local `.vita` files such as `config.json`, `extensions.json`, `.env`, or generated artifact directories are missing.

```sh
vita sync              # interactive
vita sync --dry-run    # preview only, no changes written
vita sync --auto       # apply all changes without prompting
```

---

### `vita save`

Stage all changes, commit them, and push to the remote repository.

```sh
vita save
vita save -m "update Google CV"
vita save -r
```

- `-m/--message` sets a custom commit message.
- Without `-m`, VITA uses a generic commit message.
- `-r/--reconcile` saves the current branch, checks out `master`, runs `vita sync --auto`, then saves `master`.

---

### `vita build`

Compile your LaTeX CV, cover letter, or both to PDF using `latexmk`.

```sh
vita build                 # CV only (existing default)
vita build both            # CV and cover letter
vita build -r              # CV only; also --resume
vita build -c              # Cover letter only; also --cover
```

Both PDFs use the same configured `output_dir`: by default `out/cv-<author>.pdf` and `out/cover-letter-<author>.pdf`. Generate the cover letter first with `vita cover --auto` or `vita run --auto`. Building compiles existing sources; it does not call an AI provider. A missing source or compiler failure returns a nonzero exit status. `both` cannot be combined with `--resume` or `--cover`.

---

### `vita diff <company>`

Show what changed in a company branch versus its base.

```sh
vita diff google
```

---

### `vita lock / unlock <company>`

Lock a company to prevent creating new CVs for it (e.g. you've accepted an offer).

```sh
vita lock amazon
vita unlock amazon
```

---

### `vita extract`

Extract structured job metadata without sending the CV to the extraction provider.

```sh
vita extract                           # Generate an extraction prompt
vita extract --auto                    # Refresh job.json and job.toon
vita extract --auto --provider openai
```

Extraction is optional and off by default. Enable it with `ENABLE_JD_EXTRACTION=true` in `.vita/.env` to prepend extraction to `vita run`. Configure a lightweight extraction model independently from the evaluator. See [pipeline configuration and data contracts](PIPELINE.md) for routing, cache behavior, schemas, and score comparisons.

### `vita analyze`

Generate an AI prompt to analyze your CV against the job in `job.md`.

```sh
vita analyze
vita analyze --auto
vita analyze --auto --provider codex
```

Without `--auto`, VITA saves the prompt to `.vita/current_prompt.md`; open it and give it to your AI assistant.

With `--auto`, VITA sends the prompt and local context to your configured LLM provider and saves validated `.vita/results/analysis.json` plus a rendered `analysis.md`. `analyze.md` remains a compatibility alias. Analysis uses validated TOON metadata when available, otherwise raw `job.md`.

`job.md` can contain one role, or multiple roles from the same company using `# Job N` sections:

```md
# Job 1
Software Engineer, Infrastructure

# Job 2
Research Engineer, GenAI
```

When multiple jobs are detected, `vita analyze --auto` and `vita run --auto` produce one unified cross-role analysis with criteria identified by job and an overall documented-fit score. This score describes evidence in the CV, not hiring probability.

---

### `vita adapt [--language <code>]`

Generate an AI prompt to tailor your CV to the job in `job.md`.

```sh
vita adapt               # English (default)
vita adapt --language fr # French
vita adapt --language ar # Arabic
vita adapt --auto --provider gemini
```

VITA adapts the CV title/headline, professional summary, experience, and skills based on the job description. For multi-job `job.md` files, it creates one coherent CV optimized for shared requirements across all listed roles instead of separate CV versions.

The target language applies to the whole CV, even where job tailoring focuses on selected sections. English and other targets explicitly cover education, publications/articles, awards, volunteering, and custom sections as well as the headline, summary, experience, projects, and skills. Translation instructions preserve LaTeX structure, layout, URLs, citation/reference keys, facts, and appropriate proper nouns. The CLI still defaults to English. These instructions guide the provider; review the generated CV to confirm translation quality and completeness.

The CV title uses one role name, such as `Applied AI Engineer`, `Data Engineer`, `Software Engineer`, or `ML Engineer`. Specializations and keywords belong in the summary or skills, without a tagline appended to the title. For multiple jobs, VITA selects the single role that best fits the shared requirements and your experience.

---

### `vita review`

Evaluate the updated CV against `job.md`. Review saves `review.json` and `review.md` using the same schema and scoring rubric as analysis. A matching initial analysis locks the criteria and produces `delta.json` and `delta.md` with before/after score changes. Review recommends improvements without editing the CV.

```sh
vita review
vita review --auto
```

---

### `vita run`

Run the full AI workflow: `(optional extract) → analyze → adapt → review → cover`.

```sh
vita run
vita run --auto
vita run --auto --provider codex
vita run --auto --provider gemini --language fr
```

Without `--auto`, this saves each task to `.vita/prompts/<task>.md` and writes an ordered workflow to `.vita/current_prompt.md` for your assistant to execute. Each prompt includes its bundled and custom skills.

With `--auto`, VITA writes reports into `.vita/results/`, updates the configured CV source during adaptation, and creates the configured cover letter source after review. Each stage supports its own provider/model settings; review inherits analysis settings by default. Existing provider configuration remains the fallback. `--language` applies to both documents. A failed step stops the pipeline. Run `vita build both` to compile the PDFs.

### `vita cover [--language <code>]`

Generate a cover letter (lettre de motivation) from the current CV and `job.md`, using the bundled `cover-letter-generator.md` skill and any `.vita/skills/cover/*.md` customizations.

```sh
vita cover --language fr                         # Generate a prompt
vita cover --auto --provider codex --language fr # Write cover-letter.tex
vita build --cover                              # Compile its PDF
```

The letter uses supported CV facts, optional `.vita/cv.yaml` knowledge, and the job's requirements. It uses the same model settings as the CV commands in `.vita/extensions.json`. The CV and a nonempty `job.md` must exist. Multiple jobs from one company produce one coherent letter. The generated letter is standalone LaTeX; it does not require the CV's custom class or assets.

---

### `vita keys`

Manage API keys for LLM providers.

```sh
vita keys list
vita keys set gemini <your-key>
vita keys remove gemini
```

Keys are stored locally in `.vita/.env`. Codex CLI support uses your local Codex login instead of an API key.

---

## Typical Workflow

```sh
# Day 1 — Set up your CV project
uv tool install vita-cv
mkdir my-cv && cd my-cv
vita init
# → edit .vita/config.json (set author)
# → write main.tex and sections/

git add .
git commit -m "base: initial CV"

# Applying to a company
git checkout -b gen-swe         # create your domain baseline
# → tailor the CV for SWE roles generally
git add . && git commit -m "gen-swe: baseline"

vita new etp google "software engineer"
# → now on branch etp-google-swe

# Paste job description
echo "..." > job.md
vita analyze    # get analysis prompt
vita adapt      # get tailoring prompt
# → run prompts with AI, apply suggestions to sections/

# Or run the autonomous pipeline with a configured provider
vita run --auto --provider codex

vita build      # compile to PDF
# → out/cv-yourname.pdf

vita status     # review all companies
```

---

## Building the PDF

VITA uses `latexmk` automatically. If you need to build manually:

```sh
# Standard
latexmk -pdf -outdir=out main.tex

# With bibliography (BibTeX/Biber)
pdflatex -output-directory=out main.tex
biber --input-directory=out --output-directory=out main
pdflatex -output-directory=out main.tex
pdflatex -output-directory=out main.tex
```

---

## Extensibility

VITA ships with built-in role aliases, language codes, and LLM provider support. You can add your own in `.vita/extensions.json` (created by `vita init`):

```json
{
  "llm_providers": {
    "codex": {
      "model": ""
    },
    "gemini": {
      "model": "gemini-2.0-flash"
    }
  },
  "role_aliases": {
    "research engineer": "re",
    "applied scientist": "as",
    "solutions architect": "sa"
  },
  "language_map": {
    "zh": "Chinese (Simplified)",
    "ja": "Japanese"
  }
}
```

Your entries are merged on top of the built-ins — your values win on conflict. Use `--provider` with `--auto` commands to choose a configured LLM provider.

See [EXTENSIONS.md](EXTENSIONS.md) for the full list of built-in aliases and all format details.

---

## CI/CD and automated releases

GitHub Actions runs linting, dependency auditing, package validation, CodeQL, regression tests on Python 3.10 through 3.14, and an isolated installed-package smoke test. The full pipeline also runs every Monday at 05:23 UTC. Dependabot checks Python and GitHub Actions dependencies every Monday.

Releases require **two separate PR merges**. Release Please maintains a **TestPyPI release PR**, including `vita.__version__` and `CHANGELOG.md`. Merging it creates the version tag and a draft GitHub release, runs the release checks, builds once, and publishes to TestPyPI only. After verifying the uploaded package, automation publishes the GitHub prerelease and opens a **PyPI promotion PR** with the exact file hashes and testing instructions. Test the package yourself, then merge that second PR when ready. Only that merge publishes the same files to PyPI and marks the GitHub release stable.

Use these pull request title prefixes to select the next version automatically:

- `fix: ...` creates a patch release, such as `2.3.0` to `2.3.1`.
- `feat: ...` creates a minor release, such as `2.3.0` to `2.4.0`.
- `feat!: ...`, `fix!: ...`, or a `BREAKING CHANGE:` footer creates a major release.
- `chore: ...`, `ci: ...`, and `test: ...` normally do not create a release.

Use a scope when useful, for example `fix(cli): handle a missing config file`. CI rejects pull request titles that are not Conventional Commits. To select an exact exceptional version, add `Release-As: X.Y.Z` to the squash commit body.

### Add the publishing tokens to GitHub

Never commit either token to this repository. Store each token as a GitHub environment secret:

1. Open the GitHub repository and go to **Settings → Environments**.
2. Create an environment named **`testpypi`**. Under **Environment secrets**, add **`TEST_PYPI_API_TOKEN`** with a project-scoped token created at [TestPyPI account settings](https://test.pypi.org/manage/account/token/).
3. Create an environment named **`pypi`**. Under **Environment secrets**, add **`PYPI_API_TOKEN`** with a project-scoped token created at [PyPI account settings](https://pypi.org/manage/account/token/).
4. Restrict both environments to tags matching `v*`. Merging the promotion PR dispatches PyPI publication on its tested version tag, preserving existing environment restrictions. Environment reviewers are optional extra protection; merging the promotion PR is already the explicit production approval.

The token value includes the `pypi-` prefix. The workflow supplies the required `__token__` username automatically.

### Add the release automation token to GitHub

Release Please needs a fine-grained GitHub personal access token so that its pull requests run the required CI checks and its version tags start the publishing workflow. The same token creates the separate promotion PR. In GitHub, open **Settings → Secrets and variables → Actions**, create a repository secret named **`RELEASE_PLEASE_TOKEN`**, and paste a fine-grained token with access only to this repository. Grant it **Contents: Read and write**, **Pull requests: Read and write**, and **Issues: Read and write**. Keep the token owner authorized to create branches, tags, and pull requests in this repository.

After the three secrets are configured, normal development and releases use this flow:

1. Merge a pull request with a Conventional Commit title into `master`.
2. Release Please creates or updates `chore(testpypi): release X.Y.Z` with the calculated version and release notes.
3. Review and merge that PR after its checks pass. The `vX.Y.Z` tag triggers TestPyPI publication and verification.
4. Automation opens `chore(pypi): release X.Y.Z`, adding only `.github/releases/pypi/vX.Y.Z.json`. Its body includes a TestPyPI install command and SHA-256 hashes for the wheel and source distribution.
5. Install from TestPyPI in a separate environment and test your workflow. Leave the promotion PR open while testing; closing it without merging does not publish anything to PyPI.
6. Merge the promotion PR when satisfied. Automation dispatches publication on the tested version tag, verifies the merged approval, successful TestPyPI run, tag/commit provenance, and hashes, downloads the exact tested files, smoke-tests them, and uploads them to PyPI without rebuilding. It verifies PyPI's files before marking the GitHub release stable. Manually dispatching this workflow also requires a valid, already-merged promotion PR; selecting an unapproved PR or a different tag fails validation.

Promotion uses TestPyPI as the durable source of the files, so it does not depend on an expiring Actions artifact. A newer `master` commit or a newer pending release cannot alter an older promotion's package. Keep these promotion PRs limited to their generated JSON record; adding other changes makes the production check fail.

If publication fails, rerun the failed jobs in the original workflow. Already uploaded files are accepted only when their hashes match. Retrying the TestPyPI workflow reuses its existing promotion PR and refreshes the run provenance only when the package bytes are unchanged. Closed promotion PRs are not automatically reopened. If testing finds a package problem, close the promotion PR, merge a fix, and release a new version: an uploaded version's files must not be replaced. A full rebuild can produce different bytes and will be rejected for an already uploaded version.

---

## AI Skills

Add project-specific Markdown skills under the folder for their task:

```text
.vita/skills/
├── extract/                 # Optional JD extraction guidance
├── analyze/                 # Job analysis
├── adapt/                   # CV adaptation
│   ├── writing-style.md     # Additional guidance
│   └── resume-tailor.md     # Replaces the bundled skill with this filename
├── review/                  # CV review
└── cover/                   # Cover letter construction
    └── tone.md
```

`vita init` creates these folders; existing projects can use `vita sync --auto`. Nonempty `.md` files directly inside a task folder apply only to that task, in both manual and automatic modes. A file matching a bundled skill's filename replaces that skill for the task. Other files are appended in filename order, with project writing/style guidance taking precedence over bundled guidance. Empty files are ignored. No frontmatter is required. See [custom task skills](EXTENSIONS.md#custom-task-skills) for the default skill mapping and an example.

VITA includes a library of AI agent skills for specialized tasks. Reference them when prompting your AI assistant:

| Category | Skills |
|---|---|
| **Writing** | `resume-writer`, `resume-bullet-writer`, `resume-quantifier` |
| **Reviewing** | `resume-reviewer`, `resume-ats-optimizer` |
| **Targeting** | `resume-tailor`, `job-description-analyzer`, `resume-section-builder` |
| **Documents** | `cover-letter-generator`, `linkedin-profile-optimizer` |
| **Prep** | `interview-prep-generator`, `salary-negotiation-prep`, `offer-comparison-analyzer` |
| **Specialized** | `tech-resume-optimizer`, `executive-resume-writer`, `academic-cv-builder` |
| **Transitions** | `career-changer-translator`, `creative-portfolio-resume` |

**Example usage:**

> "Use the `resume-tailor` skill to update `sections/experience.tex` based on the job description I pasted in `job.md`."

> "Run `interview-prep-generator` on my CV and generate 5 STAR stories for a Google interview."

---

## Design Philosophy

- **Warn, don't block** — duplicate CVs trigger a warning, not a hard stop (`--force` overrides, `locked: true` blocks permanently)
- **CLI enforces naming** — roles are normalized automatically (`data engineer` → `de`, `machine learning engineer` → `ml`)
- **Registry is the truth** — `.vita/companies.json` is the authoritative record; use `vita sync` if it drifts from git
- **User-extensible** — role aliases and language codes are fully overridable via `.vita/extensions.json`
- **Local-first** — prompt generation, git workflows, and LaTeX builds are local. `--auto` sends CV/job context to the LLM provider you configure.
