YaAICV — Yet Another AI CV

YaAICV is a Flask web application to create, manage, optimise, and compare CVs against job offers. It combines ATS-safe HTML templates, PDF export, and a multi-provider AI pipeline.

1. Description

The platform is organised in modules:

• Builder: create CVs with a schema-driven wizard or import from PDF/DOCX (requires AI enabled).
• Manager: preview, edit HTML source, and export CVs to ATS-safe PDF.
• Optimizer: AI-powered chat-style CV feedback and optimisation.
• Get the Job: AI-based CV/job-description matching, scoring, and tailored optimisation.
• CV Templates: create, edit, and delete ATS-friendly templates with live preview.
• Settings: language, AI provider, API credentials, and prompt customisation.

2. Tech Stack

Layer	Technology
Backend	Python 3.11+, Flask, Flask-Login, Flask-SQLAlchemy
Database	SQLite
AI pipeline	Multi-provider (OpenAI · Claude · Gemini · Private API)
Frontend	Jinja2, Bootstrap 5, CodeMirror
PDF/DOCX reading	pypdf, docx2txt
PDF export	ReportLab (ATS-safe text export)
Template preview	Playwright + pypdfium2

3. Prerequisites

• Python 3.11+
• pip
• Internet access required for cloud AI providers (OpenAI, Claude, Google)

4. Installation

1. Clone or download the repository:

git clone <repo-url>
cd yaaicv

2. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. (Optional) Install Playwright browsers for template preview generation:

playwright install chromium

5. Configure environment variables:

cp .env.example .env
# Edit .env and set a strong SECRET_KEY

6. Run the application:

python run.py

7. Open http://127.0.0.1:5000 in your browser.

On first startup the app redirects to Initial Settings to create the admin account.

5. Features

• Protected access: all pages require login.
• CV Builder wizard: schema-driven form for each template section; supports single and repeatable sections.
• CV Import (PDF/DOCX): raw text is extracted from the uploaded file and sent to the configured AI provider, which maps content to the selected template schema. Import is exclusively AI-powered and is disabled when AI is turned off (shows AI OFF badge).
• Manager: full HTML source editing via CodeMirror and ATS-safe PDF download.
• Optimizer: conversational AI assistant that analyses and improves your CV.
• Get the Job: AI analyses CV vs. job description (Match Score, ATS Score, Strengths, Gaps, Suggestions) and can rewrite the CV to target the position.
• Configurable prompts: all four AI prompts (extract, match, optimize, optimize-for-job) are editable in Settings.

6. AI Architecture

Provider strategy

The AI pipeline lives in app/services/ai_service.py and uses a strategy pattern. All application code calls the single generate_text() function; switching provider requires no code changes — only a setting update.

┌──────────────────────────────────────────┐
│            generate_text()               │  ← unified entry point
└────┬──────────┬──────────┬──────────────┘
     │          │          │          │
 ┌───▼──┐  ┌───▼──┐  ┌────▼───┐  ┌───▼──────┐
 │OpenAI│  │Claude│  │ Gemini │  │ Private  │
 │  API │  │  API │  │(Google)│  │   API    │
 └──────┘  └──────┘  └────────┘  └──────────┘

Supported providers

Provider	Key	Requires
OpenAI	openai	API key — platform.openai.com
Claude (Anthropic)	claude	API key — console.anthropic.com
Google AI Studio (Gemini)	google	API key — aistudio.google.com
Private API (self-hosted LLM)	private_api	Server URL + Bearer JWT token

Match & scoring

CV/job matching and scoring is performed entirely by the AI provider using the Match CV prompt. The prompt instructs the model to return structured Markdown including a **Match Score** and **ATS Score**. No local embedding or similarity computation is performed.

7. Configuration

All settings are managed from the Settings page in the web UI.

AI master switch

Setting	Description
AI enabled	Master toggle — must be ON to use any AI feature
Disclaimer	Must be accepted when enabling

Provider credentials

OpenAI

Setting	Description
API key	sk-… key from platform.openai.com
Model	e.g. gpt-4o-mini, gpt-4o

Claude

Setting	Description
API key	Key from console.anthropic.com
Model	e.g. claude-3-5-haiku-20241022, claude-opus-4-5

Google AI Studio

Setting	Description
API key	Key from aistudio.google.com
Model	e.g. gemini-1.5-flash, gemini-2.0-flash

Private API

Setting	Description
Server URL	Base URL of your LLM server (e.g. https://your-server.example.com)
JWT secret	Secret used to sign tokens (stored locally, not required if you paste the token directly)
JWT token	Bearer token sent in the Authorization header with every request

General

Setting	Description
App language	en (English) / it (Italiano)

Environment variables (.env)

SECRET_KEY=<strong-random-key>
DATABASE_URL=sqlite:///instance/yaaicv.db   # optional, SQLite default

8. Private API — Server Requirements

YaAICV can connect to any self-hosted LLM server that exposes two HTTP endpoints:

GET /health

Health check — used to verify the server is reachable.

Response:

{ "status": "alive" }

POST /chat

Text generation — the main inference endpoint.

Request headers:

Authorization: Bearer <jwt_token>
Content-Type: application/json

Request body:

{ "prompt": "<full prompt string>" }

The prompt is a single string that already includes the system instruction and user content, concatenated by the YaAICV client.

Response:

{ "response": "<generated text>" }

Notes:

• Authentication is enforced via a signed JWT (HS256). Generate the token from the Settings page using your chosen secret.
• The server must be publicly reachable (or accessible via a tunnel such as ngrok, Cloudflare Tunnel, etc.).
• Any framework is suitable (FastAPI, Flask, llama.cpp server, Ollama with a thin wrapper, etc.).
• YaAICV imposes a 120-second client-side timeout per request.

Minimal FastAPI example

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import jwt, JWTError
from pydantic import BaseModel

SECRET_KEY = "your_secret"
ALGORITHM  = "HS256"

app      = FastAPI()
security = HTTPBearer()

def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    try:
        jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

class ChatRequest(BaseModel):
    prompt: str

@app.get("/health")
def health():
    return {"status": "alive"}

@app.post("/chat")
def chat(req: ChatRequest, _=Depends(verify_token)):
    # Replace with your actual model inference call
    answer = your_model.generate(req.prompt)
    return {"response": answer}

9. Template Guide

Templates are Jinja2 HTML documents rendered against a data object and a cv metadata object.

Available context variables

Variable	Description
cv.title	CV title string
cv.created_at	Creation datetime
cv.updated_at	Last update datetime
data.<section_key>	Section data as defined in the template schema

Schema-driven sections

Each template has a schema_json that defines sections and their fields. Example built-in section keys:

• personal_info — single object with full_name, email, phone, location, linkedin, github, summary
• experiences — list of objects with role, company, start_date, end_date, details
• education — list of objects with title, institute, year
• skills, languages, certifications, expertise, competencies — list of objects

For multiple: true sections, iterate in the template:

{% for exp in data.experiences %}
  <p>{{ exp.role }} at {{ exp.company }}</p>
{% endfor %}

For icon tokens (ATS-safe, no graphical fonts) use icons.*.

See the in-app Template Guide for the full reference.

Import flow (AI-powered)

1. Upload a PDF or DOCX file and select a template.
2. Raw text is extracted with pypdf / docx2txt.
3. The full text is sent to the AI provider with the template schema; the model returns structured JSON.
4. An editable preview is shown so the user can review and correct before saving.
5. On confirmation, data_json, html_source, and source_text are stored.

Import requires AI to be enabled. The import button is disabled and shows AI OFF when AI is turned off.

10. AI Features and Privacy Disclaimer

AI generative features are optional and disabled unless explicitly enabled in Settings.

When enabling AI:

• You must accept the disclaimer.
• You acknowledge that cloud AI providers (OpenAI, Anthropic, Google) may process submitted data outside your infrastructure.
• Avoid sending personal or confidential data unless compliant with your legal and policy requirements.
• Use Private API (self-hosted LLM) for full data privacy — inference runs entirely on your own infrastructure.

If AI is disabled:

• Optimizer and Get the Job are blocked.
• CV Import from PDF/DOCX is disabled (shows AI OFF).
• The CV Builder wizard and manual HTML editing remain fully functional.