Talent Match Insight¶

Talent Match Insight explains one existing user/opportunity pair in short, evidence-based prose. It is not a second matching algorithm: persisted JOM scores calibrate the conclusion, while concrete user and opportunity data supplies every claim.

End-to-end flow¶

user_id + offer_id + tenant context
  -> load user, opportunity and persisted JOM score concurrently
  -> normalize and bound evidence
  -> select general / skills / motivation prompt
  -> configured LLM task
  -> strip wrappers, normalize whitespace and enforce 300 characters

POST /api/v1/jom/rationale uses standard API-key authentication. POST /jom/admin/talent_match_insights_by_id retains the historical public-environment contract. Both invoke the same service and return a JSON string. All inputs are query parameters, even though the method is POST; there is no JSON request body.

For example, with the standard API key header and real entity IDs:

POST /api/v1/jom/rationale?user_id=user-123&offer_id=opportunity-456&client_id=72&lang=en&insight_type=skills

Example response (application/json):

"Your SQL skills align with this data analysis opportunity. Confirm the expected reporting experience before applying."

Data loading¶

The service resolves the tenant matching context and AI configuration first. MongoDB concurrently loads the user document, opportunity document and the user/opportunity score row. PostgreSQL concurrently reads aihub_user_v1, aihub_opportunity_v1 and user-side JOM scores, then selects the row whose jobOfferId matches offer_id.

An unknown tenant database returns 404. A missing user or opportunity also returns 404; a missing score is allowed and simply removes score calibration from the prompt.

Evidence construction¶

The requested lang is normalized as a BCP-47-like value (_ becomes -). Invalid or empty values fall back to English. Localized fields prefer the full locale, then its base language, English and finally the first available value. Supported HTML tags are stripped, entities are decoded and every text field and list is bounded before it reaches the model.

Profile evidence¶

• current role from the first available job-title field;
• job family;
• up to 40 deduplicated named skills from skillsInformation, skills and topSkills.

Opportunity evidence¶

• title, attached job, job family and seniority/classification;
• up to 40 deduplicated required skills.

Skill alignment¶

direct_matches contains normalized exact-title intersections. Remaining opportunity skills are placed in opportunity_skills_without_direct_match. The persisted semantic skillScore can calibrate the overall strength, but it does not authorize the model to invent a semantic connection that is absent from the supplied named evidence.

Motivation evidence¶

Only user skills with a positive declared motivation value are retained, up to 20. They are split between skills whose normalized titles occur in the opportunity and other motivated skills (the latter are supplied only when no direct motivated skill matches). Up to five bookmarked and five interested opportunity titles provide additional preference signals.

Score calibration¶

Only finite persisted skill/motivation values in [0, 1] are included. The prompt treats values from 0.70 as strong, values from 0.40 to below 0.70 as partial and lower values as weak. The generated answer must never quote the numeric score, band or internal scoring mechanism.

Insight types¶

Other values fail request validation. The structured evidence is serialized as one JSON user message and explicitly marked as untrusted data so text contained in entity fields cannot override the system instructions.

Generation contract¶

The provider/model is selected by the talent_match_insights semantic task. Model and reasoning settings come from the configured profile. The call allows a maximum of 2,048 output tokens, but the business contract is much narrower:

• one or two short sentences in the requested language;
• one compact plain-text paragraph, no title, Markdown, JSON or quotation;
• a practical assessment supported by named evidence;
• a second sentence only when a supplied requirement to verify or a concrete motivation signal adds useful information;
• no unsupported expertise, missing-skill claim, decision recommendation or outcome prediction;
• no more than 300 characters including spaces.

The general, skills and motivation variants share this rule. When the profile and opportunity both list Python and no other relevant factor is supplied, one sentence explaining that direct match is sufficient. Missing profile evidence for a supplied requirement can justify a point to verify, but the model must not invent broader job expectations to fill a second sentence.

For example, the complete response can be: "This opportunity is relevant: your Python skill matches a listed requirement for the Software Developer role." Stop there when no distinct relevant evidence remains; do not append a reservation about undocumented broader software-development experience.

When only the opportunity lists Python, its presence in the person's profile is unknown. The explanation must leave the capability itself open, for example: "This opportunity may be worth exploring if you meet its Python requirement." This is the complete response when no distinct relevant evidence remains. Do not append a clause or sentence about a match not being documented, including after a comma or semicolon: the condition already identifies what needs verification. Phrases such as "verify whether your Python skill matches" still assume that the person has that skill and are unsupported in this case.

A listed skill establishes its presence in the profile, not practical or professional experience, proficiency, mastery or expertise. Those claims require explicit supporting evidence and cannot be inferred from a direct skill match or a matching score. For example, a shared Python skill can justify "your Python skill matches a requirement of this opportunity", but not "your Python experience" or "your mastery of Python".

Code fences, surrounding emphasis/quotes and excess whitespace are removed. Long output is cut at the last sentence boundary in the useful half of the limit when possible, otherwise at a word boundary with an ellipsis.

If the provider returns empty content, the service retries once with the same evidence. Two empty results become 502 with a stable public error; provider, model and request diagnostics remain in logs.

This workflow is distinct from the legacy PwC prose-based endpoint documented under PwC JOM Compatibility.

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