Job Proximity Matching (JPM)¶

JPM compares a user's current job with jobs in the tenant referential. It runs in user-to-jobs and job-to-users directions and produces skill, text and overall scores.

entity and tenant context
  -> active candidates and hard filters
  -> skill score + job-text score (concurrent)
  -> neutralized excluded pairs
  -> overall score
  -> persistence and optional publication

JPM has no JOM-style pool rules or motivation score.

Galaxy career paths consume stored JPM results to generate a validated career path and a separate, concise explanation of an existing path.

1. Candidate eligibility and hard filters¶

The workflow loads standardized MongoDB documents or live PostgreSQL user/job projections. User-to-jobs always removes hidden jobs; job-to-users returns an Empty job code result when the source job has no code and otherwise processes only non-hidden jobs.

Configured filters under hard_filters.jpm.user or hard_filters.jpm.job use the same definitions as JOM for job classification, access group, contract type, external-user exclusion and location. Active tenant/status predicates are always applied by the repository.

JPM also queries the active entities excluded by these filters. Those pairs are retained as neutralized results with all scores set to zero, rather than simply disappearing. This lets downstream consumers distinguish an ineligible pair from a missing calculation.

2. Skill score¶

The shared algorithm treats job skills as requirements and user skills as acquired skills. It performs semantic skill matching, applies the same exact-ID shortcut, threshold, level ratio and type-weighted average described in JOM skill scoring.

jpm_scores.skill_score.active=false disables this component. An optional min_non_zero_weighted_skills excludes a job from skill scoring unless it has at least that many skills whose configured type weight is strictly positive. The pair remains eligible for text scoring, and an absent skill component is represented as 0.

3. Job-text score¶

The text component compares the embedding of the user's attached current job with the candidate job embedding. In the reverse direction, one source job embedding is compared with the attached-job codes of the candidate users. Missing attached job codes or vectors produce zero rather than a model call.

For a cosine similarity c, the implemented normalization is:

textScore = abs(min(1, (c - 0.7) / 0.3))

Thus c = 0.7 maps to 0, c = 1 maps to 1, and the function is capped only on the upper expression before the absolute value. jpm_scores.text_score.active=false disables this component and supplies zero scores.

4. Final score and neutralization¶

For every eligible pair:

overallScore = max(skillScore, textScore)
neutralized = false

The maximum intentionally lets either demonstrated skill coverage or proximity between job descriptions establish the match. Every active-but-filtered pair is emitted with neutralized=true and skill, text and overall scores equal to 0. All rows receive a timezone-aware UTC scoreDate.

5. Persistence and publication¶

MongoDB stores both directions in the job matching score collection and can publish formatted user/job messages through RabbitMQ. PostgreSQL writes directly to user_job_matching, deletes obsolete pairs for the processed entity and suppresses RabbitMQ publishing. Public responses expose skillScore, textScore, overallScore, neutralized and updatedAt, with scores rounded to three decimals.

See Matching endpoints for processing, score retrieval, statistics and administrator batch operations.

6. Job relevance rationale¶

POST /api/v1/jpm/rationale explains a target job's relevance using the same entity sources as JPM: acquired user skills, required job skills, and the titles, families and descriptions of the user's attached job and the target job. Job text uses the same builder as JPM embeddings. Skills pass through the shared scoring normalizer, preserving types and levels; unknown levels are not evidence of proficiency. This is a qualitative explanation of the available evidence, not a reconstruction of a historical numerical score.

Send a JSON body with the four required fields below. data_source is optional and defaults to smartmobility. Identifiers must belong to the authenticated tenant; replace these illustrative values with your own.

{
  "client_id": "42",
  "user_id": "101",
  "job_id": "503",
  "locale": "en-US",
  "data_source": "smartmobility"
}

{
  "rationale": "Your Python and data analysis skills support a move into business analytics. Experience presenting insights to stakeholders is a useful point to substantiate."
}

The service makes one asynchronous LLM_PROFILE_MINI call using the tenant's provider configuration and the task name jpm.rationale. It requests exactly two short sentences in the required BCP 47 locale. The response is capped at 300 characters including spaces, aligning with the compact JOM format and the two-to-three-sentence Training Matching rationale. Empty or overlong responses are rejected rather than truncated or replaced with generic advice.

The rationale addresses the employee directly. Its first sentence explains evidenced shared skills or responsibilities, or invites the employee to explore the target role when no overlap is evidenced. Its second sentence suggests a practical next step grounded in a target requirement. Unknown proficiency calls for assessment and development if needed, rather than an assumed skill gap. Uncertainty is expressed through cautious recommendations without commenting on missing profile data. For example, with no employee skills or attached job and SQL required for a Data Analyst role:

You could explore a move into a Data Analyst role. To prepare, assess your SQL proficiency and develop it if needed, as SQL is required for this role.

The same approach applies when the profile lists only an unrelated skill such as Python. Omit that skill and reservations such as "no shared skill is evidenced"; invite exploration of the role and assess the actual SQL requirement conditionally.

The endpoint reads existing MongoDB documents or PostgreSQL projections. It does not import entities, recalculate or publish JPM scores, create a career path, or cache the generated response. A missing attached job is represented as absent context; the employee's available skills remain usable. The employee must be active and the target job must be active and visible.

Errors use explicit HTTP statuses: 403 for a client mismatch, 404 for an unknown tenant, employee or available target job, 422 for invalid input, malformed stored evidence or context exceeding 120,000 characters, 502 for an invalid model rationale, and 504 for the 60-second model timeout. Unexpected failures return a sanitized 500 error. No retry or result fallback is added by this workflow.

For NB-9002, the caller can use this rationale to explain a direct transition. The jpm_rationale log event records the client, deployment environment, data source, outcome and duration, without the prompt or generated text. A rationale request does not establish that a forced path was created. Creation flags and monitoring of forced paths for La Poste platform 703 belong to the component that creates/persists those paths and its BI dashboard integration.

The generated main HTTP reference is the authoritative source for parameters, schemas, responses and examples.