Aller au contenu

Candidate Analyzer API

Port : 8003 | NodePort : 30003 | Repo : solyntek/djinn/services/djinn-candidate-analyzer

Analyse et classement de candidatures par pertinence pour un poste.

Endpoints

Méthode Route Description
GET /health Health check
POST /v1/analyze Analyser 1 candidat vs 1 poste
POST /v1/analyze/batch Analyser N candidats, retour trié par score
POST /v1/analyze/competency-file Analyser un dossier de compétences (texte brut)

Scoring (5 dimensions)

Dimension Poids Méthode
Skills 0.30 Similarité sémantique (embeddings)
Experience 0.25 Années + pertinence
Education 0.15 Diplômes + certifications
Languages 0.15 Matching langues requises
Location 0.15 Compatibilité remote/onsite

Exemple

curl -X POST http://localhost:30003/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "job": {"title": "Python Developer", "required_skills": ["Python", "FastAPI"]},
    "candidate": {"firstname": "Jean", "skills": ["Python", "FastAPI", "Docker"]}
  }'

curl -X POST https://api.djinn.solyntek.io/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "job": {"title": "Python Developer", "required_skills": ["Python", "FastAPI"]},
    "candidate": {"firstname": "Jean", "skills": ["Python", "FastAPI", "Docker"]}
  }'

Référence interactive

Générée à chaque build depuis la spec versionnée openapi/candidate-analyzer-v1.json (ADR-011) — aucune route documentée à la main.

Djinn Candidate Analyzer 0.1.0

Analyse et classement de candidatures par pertinence pour postes

Endpoints

GET /health

Health

Description

Health check endpoint.

Responses

{
    "status": "string",
    "version": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
        },
        "version": {
            "type": "string",
            "title": "Version",
            "default": "0.1.0"
        }
    },
    "type": "object",
    "title": "HealthResponse",
    "description": "Response for health check."
}

POST /v1/analyze

Analyze

Description

Analyze a single candidate against a job description.

Input parameters

Parameter In Type Default Nullable Description
X-API-Key header No
X-Internal-Service header No
X-Tenant-ID header No

Request body

{
    "job": {
        "title": "string",
        "description": "string",
        "required_skills": [
            "string"
        ],
        "preferred_skills": [
            "string"
        ],
        "min_experience_years": null,
        "required_languages": [
            "string"
        ],
        "required_education": null,
        "location": null,
        "remote_policy": null
    },
    "candidate": {
        "id": null,
        "firstname": null,
        "lastname": null,
        "email": null,
        "skills": [
            "string"
        ],
        "languages": [
            "string"
        ],
        "experiences": [
            {
                "company": "string",
                "title": "string",
                "location": "string",
                "start_date": "string",
                "end_date": "string",
                "description": "string"
            }
        ],
        "diplomas": [
            {
                "school": "string",
                "degree": "string",
                "field_of_study": "string",
                "start_date": "string",
                "end_date": "string"
            }
        ],
        "certifications": [
            {}
        ],
        "location": null,
        "raw_text": null
    },
    "weights": {
        "skills": 10.12,
        "experience": 10.12,
        "education": 10.12,
        "languages": 10.12,
        "location": 10.12
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "properties": {
        "job": {
            "$ref": "#/components/schemas/JobDescription"
        },
        "candidate": {
            "$ref": "#/components/schemas/CandidateProfile"
        },
        "weights": {
            "$ref": "#/components/schemas/ScoringWeights"
        }
    },
    "type": "object",
    "required": [
        "job",
        "candidate"
    ],
    "title": "AnalyzeRequest",
    "description": "Requête d'analyse d'un candidat."
}

Responses

{
    "candidate_id": null,
    "candidate_name": null,
    "overall_score": 10.12,
    "dimension_scores": [
        {
            "dimension": "string",
            "score": 10.12,
            "details": "string"
        }
    ],
    "strengths": [
        "string"
    ],
    "gaps": [
        "string"
    ],
    "summary": "string",
    "fit_level": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "candidate_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Candidate Id"
        },
        "candidate_name": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Candidate Name"
        },
        "overall_score": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Overall Score"
        },
        "dimension_scores": {
            "items": {
                "$ref": "#/components/schemas/DimensionScore"
            },
            "type": "array",
            "title": "Dimension Scores"
        },
        "strengths": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Strengths"
        },
        "gaps": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Gaps"
        },
        "summary": {
            "type": "string",
            "title": "Summary",
            "default": ""
        },
        "fit_level": {
            "type": "string",
            "title": "Fit Level",
            "description": "excellent | good | moderate | weak",
            "default": "moderate"
        }
    },
    "type": "object",
    "required": [
        "overall_score"
    ],
    "title": "CandidateAnalysis",
    "description": "Résultat d'analyse pour un candidat."
}


{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /v1/analyze/batch

Analyze Batch

Description

Analyze multiple candidates and return sorted by score.

Input parameters

Parameter In Type Default Nullable Description
X-API-Key header No
X-Internal-Service header No
X-Tenant-ID header No

Request body

{
    "job": {
        "title": "string",
        "description": "string",
        "required_skills": [
            "string"
        ],
        "preferred_skills": [
            "string"
        ],
        "min_experience_years": null,
        "required_languages": [
            "string"
        ],
        "required_education": null,
        "location": null,
        "remote_policy": null
    },
    "candidates": [
        {
            "id": null,
            "firstname": null,
            "lastname": null,
            "email": null,
            "skills": [
                "string"
            ],
            "languages": [
                "string"
            ],
            "experiences": [
                {
                    "company": "string",
                    "title": "string",
                    "location": "string",
                    "start_date": "string",
                    "end_date": "string",
                    "description": "string"
                }
            ],
            "diplomas": [
                {
                    "school": "string",
                    "degree": "string",
                    "field_of_study": "string",
                    "start_date": "string",
                    "end_date": "string"
                }
            ],
            "certifications": [
                {}
            ],
            "location": null,
            "raw_text": null
        }
    ],
    "weights": {
        "skills": 10.12,
        "experience": 10.12,
        "education": 10.12,
        "languages": 10.12,
        "location": 10.12
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "properties": {
        "job": {
            "$ref": "#/components/schemas/JobDescription"
        },
        "candidates": {
            "items": {
                "$ref": "#/components/schemas/CandidateProfile"
            },
            "type": "array",
            "maxItems": 500,
            "minItems": 1,
            "title": "Candidates"
        },
        "weights": {
            "$ref": "#/components/schemas/ScoringWeights"
        }
    },
    "type": "object",
    "required": [
        "job",
        "candidates"
    ],
    "title": "AnalyzeBatchRequest",
    "description": "Requête d'analyse de plusieurs candidats."
}

Responses

{
    "job_title": "string",
    "candidates": [
        {
            "candidate_id": null,
            "candidate_name": null,
            "overall_score": 10.12,
            "dimension_scores": [
                {
                    "dimension": "string",
                    "score": 10.12,
                    "details": "string"
                }
            ],
            "strengths": [
                "string"
            ],
            "gaps": [
                "string"
            ],
            "summary": "string",
            "fit_level": "string"
        }
    ],
    "total_analyzed": 0
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "job_title": {
            "type": "string",
            "title": "Job Title"
        },
        "candidates": {
            "items": {
                "$ref": "#/components/schemas/CandidateAnalysis"
            },
            "type": "array",
            "title": "Candidates"
        },
        "total_analyzed": {
            "type": "integer",
            "title": "Total Analyzed"
        }
    },
    "type": "object",
    "required": [
        "job_title",
        "candidates",
        "total_analyzed"
    ],
    "title": "AnalyzeBatchResponse",
    "description": "Réponse d'analyse batch (triée par score décroissant)."
}


{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /v1/analyze/competency-file

Analyze Competency File

Description

Analyze a competency file (raw text) against a job description.

Input parameters

Parameter In Type Default Nullable Description
X-API-Key header No
X-Internal-Service header No
X-Tenant-ID header No

Request body

{
    "job": {
        "title": "string",
        "description": "string",
        "required_skills": [
            "string"
        ],
        "preferred_skills": [
            "string"
        ],
        "min_experience_years": null,
        "required_languages": [
            "string"
        ],
        "required_education": null,
        "location": null,
        "remote_policy": null
    },
    "competency_text": "string",
    "weights": {
        "skills": 10.12,
        "experience": 10.12,
        "education": 10.12,
        "languages": 10.12,
        "location": 10.12
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "properties": {
        "job": {
            "$ref": "#/components/schemas/JobDescription"
        },
        "competency_text": {
            "type": "string",
            "maxLength": 500000,
            "minLength": 1,
            "title": "Competency Text"
        },
        "weights": {
            "$ref": "#/components/schemas/ScoringWeights"
        }
    },
    "type": "object",
    "required": [
        "job",
        "competency_text"
    ],
    "title": "CompetencyFileRequest",
    "description": "Requête d'analyse d'un dossier de compétences."
}

Responses

{
    "candidate_id": null,
    "candidate_name": null,
    "overall_score": 10.12,
    "dimension_scores": [
        {
            "dimension": "string",
            "score": 10.12,
            "details": "string"
        }
    ],
    "strengths": [
        "string"
    ],
    "gaps": [
        "string"
    ],
    "summary": "string",
    "fit_level": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "candidate_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Candidate Id"
        },
        "candidate_name": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Candidate Name"
        },
        "overall_score": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Overall Score"
        },
        "dimension_scores": {
            "items": {
                "$ref": "#/components/schemas/DimensionScore"
            },
            "type": "array",
            "title": "Dimension Scores"
        },
        "strengths": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Strengths"
        },
        "gaps": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Gaps"
        },
        "summary": {
            "type": "string",
            "title": "Summary",
            "default": ""
        },
        "fit_level": {
            "type": "string",
            "title": "Fit Level",
            "description": "excellent | good | moderate | weak",
            "default": "moderate"
        }
    },
    "type": "object",
    "required": [
        "overall_score"
    ],
    "title": "CandidateAnalysis",
    "description": "Résultat d'analyse pour un candidat."
}


{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Schemas

AnalyzeBatchRequest

Name Type Description
candidates Array<CandidateProfile>
job JobDescription
weights ScoringWeights

AnalyzeBatchResponse

Name Type Description
candidates Array<CandidateAnalysis>
job_title string
total_analyzed integer

AnalyzeRequest

Name Type Description
candidate CandidateProfile
job JobDescription
weights ScoringWeights

CandidateAnalysis

Name Type Description
candidate_id
candidate_name
dimension_scores Array<DimensionScore>
fit_level string excellent | good | moderate | weak
gaps Array<string>
overall_score number
strengths Array<string>
summary string

CandidateProfile

Name Type Description
certifications Array<>
diplomas Array<Diploma>
email
experiences Array<Experience>
firstname
id
languages Array<string>
lastname
location
raw_text
skills Array<string>

CompetencyFileRequest

Name Type Description
competency_text string
job JobDescription
weights ScoringWeights

DimensionScore

Name Type Description
details string
dimension string
score number

Diploma

Name Type Description
degree string
end_date string
field_of_study string
school string
start_date string

Experience

Name Type Description
company string
description string
end_date string
location string
start_date string
title string

HealthResponse

Name Type Description
status string
version string

HTTPValidationError

Name Type Description
detail Array<ValidationError>

JobDescription

Name Type Description
description string
location
min_experience_years
preferred_skills Array<string>
remote_policy onsite | hybrid | remote
required_education
required_languages Array<string>
required_skills Array<string>
title string

ScoringWeights

Name Type Description
education number
experience number
languages number
location number
skills number

ValidationError

Name Type Description
ctx
input
loc Array<>
msg string
type string