Entities¶

AI Hub Main API on this instance: Swagger · ReDoc · Live OpenAPI JSON

Main HTTP reference

src/entity owns ingestion-independent business representations of users, opportunities, jobs, trainings and skills. Query routes can use MongoDB documents or live PostgreSQL projections. Standardization routes are MongoDB only: they load one raw entity, normalize fields, translations, inferred skills and embeddings according to the tenant configuration, then persist the standardized document.

For a single PwC user, bookmark/interest enrichment reads only opportunities referenced by enabled isBookmarked / isInterested entries. IDs are deduplicated for the query without changing their types or the order/duplicates in the resulting user fields. The lookup retains the existing status=true and skillsInformation != [] criteria, and projects only the ID, title, dates and departments. An empty reference list performs no database query. Bulk imports retain their shared opportunity context. The targeted $in query uses the existing unique JobOffers.jobOfferId index and requires no new provisioning step.

When translation is enabled, every entity type uses the same best-effort boundary. It collects and deduplicates the selected non-English texts, resolves all cached values with one MongoDB query, then sends every cache miss in one grouped DeepL request within provider limits. The group's first network, HTTP or response-validation failure immediately triggers one structured grouped call through the tenant provider's tiny LLM profile. Successful DeepL or LLM results are saved together. If both providers fail for an item, standardization keeps its source text and continues; cancellation still propagates normally.

This cache-backed path exists only for MongoDB standardization. PostgreSQL live projections never access Translations. The complete cross-application rules are described in Language detection and translation.

Skill inference embeds the generated skill names once per inference operation and reuses those vectors across the configured reference catalogs. Catalog searches run in groups of at most four while preserving configured reference priority and result ordering. MongoDB searches also retain the shared vector search concurrency limit; PostgreSQL searches use separate repository sessions.

MongoDB skill inference stores a skillInferenceState alongside its successful result. It fingerprints the cleaned source before translation: ordered experience titles/descriptions for users, or title/description for jobs, opportunities and trainings. Leading/trailing whitespace and line endings are normalized; case, accents, punctuation and experience order are preserved. The same normalized text is used for inference. Unused fields such as email or import timestamps do not invalidate this state.

Reuse also requires identical ordered reference catalogs, priority, threshold, maximum skill count, effective default LLM profile/model/reasoning controls, embedding settings and inference revision. Model and reasoning continue to come from the shared provider configuration, including capability-based omission. Changing catalog contents under the same catalog IDs requires an explicit forced refresh; these fingerprints do not track catalog contents.

Cached candidates are kept before merging them with declared skills. Each import reapplies that merge, so a declared skill can be removed without losing an equivalent inferred candidate. Reuse verifies the applied inferred IDs are still present in the stored entity. Source text and credentials are not copied into cache metadata. Technical state alone does not count as a user business change for matching timestamp preservation.

Existing entities regenerate once on their next eligible standardization. There is no startup backfill or extra database lookup/index. Only successful results establish reusable state; invalidation and the entity are saved in the same ordinary upsert. Maintenance operating on already-standardized documents uses a distinct standardized provenance and cannot establish a reusable source-import fingerprint. Deleting inferred skills also clears this state. PostgreSQL workers retain their existing inference lifecycle and do not use this MongoDB cache.

When changing skill-inference prompts, source normalization or selection semantics, bump SKILL_INFERENCE_REVISION in src/common/infer_skills/inference_cache.py and maintain its evaluation cases.

Within one standardization, independent I/O overlaps without changing the inference-before-translation dependency:

Each branch reads finalized source fields; only the owning branch writes its enriched fields. The standardized document is saved after its required enrichments finish. Optional enrichment failures remain logged and do not cancel independent branches. Cancellation stops and awaits owned tasks and prevents the final save when requested during enrichment. Completed external writes are not rolled back. Existing batch concurrency limits remain unchanged.

All paths below belong to the Main API. Routes using the current /api/v1 contract require the standard API key. Historical /jom/admin routes retain their existing public-environment contract; their schemas in /main/docs are authoritative.

Users¶

GET /api/v1/admin/get_user¶

Loads either one user selected by user_id or the tenant's user collection. The service resolves MongoDB versus the aihub_user_v1 PostgreSQL projection, normalizes documents to the same external shape and returns a list even for a single identifier.

GET /jom/admin/get_user¶

Provides the historical JOM view of the same user query workflow. It preserves the older environment dependency and parameter names but reads through the same backend-aware user service.

GET /jom/admin/get_number_of_active_users¶

Counts users eligible as active entities for the selected tenant and data source. PostgreSQL reads the live projection; MongoDB applies the entity status rules in the tenant database.

GET /api/v1/user/standardize¶

Standardizes one user by ID in MongoDB mode. The workflow loads the source record, applies user transformation and translation settings, infers skills when enabled, writes the standardized user and returns the resulting document. PostgreSQL mode rejects this operation because its user projection is built directly from relational source tables.

Before persistence, user cleaning discards bookmark entries that do not carry a usable entityId, including missing, null, NaN, empty and whitespace-only values. Duplicate identifiers keep their first occurrence and source order. Valid identifiers remain unchanged so values with leading zeroes keep their source representation.

Opportunities¶

The background job deactivate_expired_opportunities_all_clients is scheduled daily at 00:15 in the scheduler's timezone in MongoDB mode. When DATABASE_URL enables PostgreSQL mode, startup skips this MongoDB scheduler entirely: the job is neither registered nor started. The expected startup log is Main MongoDB scheduler not started in PostgreSQL mode.

GET /api/v1/admin/get_opportunity¶

Returns one opportunity selected by opportunity_id, or all available opportunities when the identifier is omitted. It selects the MongoDB collection or the live aihub_opportunity_v1 PostgreSQL projection without changing the response contract.

GET /jom/admin/get_number_of_active_opportunities¶

Counts active JOM opportunities for the tenant. It uses the same status and tenant eligibility rules as the opportunity query and matching candidate source.

GET /api/v1/opportunity/standardize¶

Runs the MongoDB opportunity standardization workflow for one ID. It normalizes source fields, applies configured transformation/translation and skill inference, produces the opportunity embedding used by semantic workflows and persists the standardized document.

The original-title and inferred-title vectors are reused together when both stored vectors are present and their request fingerprint matches the current titles, embedding provider, model and input-token limit. Changing any of these inputs regenerates the pair. Existing documents without a fingerprint regenerate once before they can benefit from reuse. An incomplete or failed generation does not establish a reusable fingerprint. This does not change the separate JOM posting-embedding refresh rules.

Jobs¶

GET /api/v1/admin/get_job¶

Returns one job selected by job_id, or the tenant's jobs when it is omitted. MongoDB reads standardized job documents; PostgreSQL reconstructs the same shape from the live aihub_job_v1 projection.

GET /api/v1/job/standardize¶

Standardizes one MongoDB job. It resolves the tenant configuration, normalizes the source job and skills, generates configured translations or inference and updates the text embedding consumed by JPM. PostgreSQL rejects this route because job data is projected and embedded by its own queue workflow.

Trainings¶

GET /api/v1/training/standardize¶

Standardizes one MongoDB training by training_id. The entity flow creates the searchable text and optional inferred skills/translations, refreshes its embedding and stores the result used by Training Matching.

Skills¶

GET /api/v1/skill/standardize¶

Applies an action_type such as update to one skill identified by integer ID. The MongoDB-only workflow retrieves its tenant context, normalizes the skill representation and updates the skill asset used by matching and Skills Library search.

Bulk imports and relational backfills are operational concerns and therefore live under Administration. Semantic skill search is documented under Skills Library.