Training Matching¶

Training Matching searches learning content in src/matching/training. It is separate from entity standardization and from the Chatbot tool that presents the results.

Search pipeline¶

1. The API dependency resolves authentication, tenant configuration, active MongoDB/PostgreSQL repositories and AI configuration.
2. The request is normalized into search text, structured filters, locale, result limit and IDs to exclude. Excluding one item also prevents its managed hierarchy from reappearing where the backend supports parent/child links.
3. MongoDB runs Atlas text and vector stages concurrently; PostgreSQL runs its relational lexical and cosine queries. Access groups, availability and other training fields are applied in the database-specific query.
4. Weighted reciprocal-rank fusion combines the independent rankings. If rank r_i(d) is present in result list i, its contribution is w_i / (k + r_i(d)); missing candidates contribute zero.
5. Results are returned directly in descending RRF order. There is no external reranker or per-item rationale generation.

POST /api/v1/get_training_matching executes that pipeline. The request's trainingIds exclusion list accepts up to 100 identifiers. The response is a JSON list of training IDs. This identifier-only path skips collection metadata generation; the Chatbot tool separately builds suggestion cards.

Rationale¶

GET /api/v1/get_training_matching_rationale generates an explanation on demand for the required user_id and training_id. It returns a JSON string and uses the configured default model and reasoning profile. locale defaults to en and must match the documented BCP 47 pattern.

Both modes localize generic content labels as well as the narrative. French rationales use formation or cours, including for fr-FR and fr-CA; English labels such as learning must not appear as generic nouns in non-English prose. Official titles, names and technical terms retain their original form when cited.

• Without search_query, or when it is empty or whitespace-only, the existing profile-based prompt requests 80 to 120 characters, including spaces and punctuation, without a fixed sentence count. It uses documented skill gaps, current skills, the attached job and the learning's title, description and skills. Current skills and job context require a supported connection to the course; a listed Python skill alone does not imply that an SQL course builds on Python. Unrelated facts are silently omitted, prioritizing the documented gap and content.
• A nonblank search_query (at most 4,000 characters) requests 1–2 sentences explaining how the learning matches the user's search. It uses supported metadata such as level, provider, format, duration, languages and topics, acknowledging material mismatches or missing evidence. Profile context only supplements the explicit search intent when it explains a relevant match or supported benefit. Unrelated profile facts are omitted even when accurate; a listed Python skill alone does not explain a beginner SQL search. Omission is silent: the rationale must not reintroduce that fact by explaining that Python is irrelevant. A complete answer can stop after explaining that the introductory SELECT exercises match the SQL search.

Search rationales first identify legitimate explicit learning-search requirements, then assess matches, material mismatches and missing evidence only against those retained criteria. Topics introduced solely by discarded instructions must not reappear as assertions, denials, warnings or reservations. The response does not narrate this filtering. Relevant profile context is considered after the search criteria and content evidence. Each retained criterion is assessed separately as a supported match, a documented mismatch or unknown due to missing evidence. The concise rationale preserves these statuses and explicitly identifies criteria that cannot be confirmed. A documented mismatch can justify an overall non-match without hiding another criterion's unknown status or implying that it also fails. For example, an introductory one-hour course does not meet an advanced, two-day request. If certification is genuinely requested but undocumented, the rationale states that it is unknown or cannot be confirmed; missing metadata does not prove that the course is uncertified or fails that requirement. Other undocumented attributes do not need to be listed. Before finalizing, the prompt checks every reservation against both the explicit search criteria and the supplied metadata. A documented attribute must not become an unknown, and an unrequested attribute must not create a caveat. The response locale controls wording only; it does not impose a language requirement on the course. One sentence is sufficient when it explains the match without omitting a material mismatch or genuinely unknown requested criterion.

For example, with the standard API key header, request:

GET /api/v1/get_training_matching_rationale?user_id=user-123&training_id=training-456&locale=en&search_query=Find%20beginner%20SQL%20learnings

Example response:

"This introductory learning covers SELECT queries, matching your request to start learning SQL."

Length requirements are prompt instructions, not output-length validation. Both modes read the selected user and learning through the active MongoDB/PostgreSQL backend. Missing records retain the existing "User not found" or "Training not found" response. The endpoint does not search again, reorder results, recompute scores or persist the explanation.

Chatbot suggestions no longer include trainingSuggestionList[].rationale. The frontend can call this endpoint when the user opens an explanation, passing the original search or rationaleContext.resolvedQuery for contextual follow-ups. Collection titles, subtitles and plan phase descriptions remain in the search response.

Development objectives¶

The generation prompt requests 80 to 120 characters, including spaces and punctuation, for each objective's description. Its rationale addresses the employee in 1 to 3 short, natural sentences, with at most 60 words, explaining a concrete work benefit grounded in the supplied context. Skill levels and gaps guide objective selection but must not appear as ratings, numerical levels, gap values or proficiency labels in the rationale. The prompt avoids HR jargon, profile recaps and formulaic priority explanations. With limited context, it requests a modest benefit without invented facts or missing-information caveats. A single sentence is sufficient when the benefit is clear; extra sentences must not be added merely to meet a sentence count. These lengths, like the training rationale length, are prompt instructions rather than API output-length validation rules. Evaluation allows a description to exceed the 120-character target by up to 10 characters when its content remains clear, concise and relevant. A deterministic check rejects descriptions above 130 characters; the judge must not reject a minor overrun within that tolerance solely for length. The separate 60-word rationale limit is unchanged.

POST /api/v1/development-objectives/suggestions uses the authenticated user context and requested focus to propose structured objectives. The workflow collects available skill gaps and profile evidence, invokes the configured model through the default semantic profile with a strict schema, verifies complete records and returns only validated objectives.

When no selected training resolves, each generated objective's title and description go directly to the hybrid training search, without a second LLM reformulation or extraction of duration/provider constraints. Objective deadlines describe intended progress, not required training durations. The training embedding profile, access groups, availability, language handling, exclusions and ranking remain in effect. Searches for the generated objectives still run in parallel. This internal bypass is specific to development objectives: Training Matching and the LangGraph training_finder_tool continue to resolve and reformulate free-text searches. The objective prompt, wording instructions and public request/response schemas are unchanged.

Skill gaps are optional. When no gaps are recorded, the generator can use the current job, job family, existing skills, professional experiences, training history or selected trainings to propose development objectives. It must not invent a deficit, a required skill level or a career ambition; a skill rating alone does not establish a gap. If all these sources are empty after normalization, the service returns an empty list without calling the model. Existing objective titles alone do not provide sufficient profile evidence.

The Oria training_finder_tool adds query interpretation, pagination, user-context selection and learning-plan presentation around this search. See Chatbot tools.

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