TITLECONVERT¶
GET /api/titleconvert · DSL TITLECONVERT · MCP aoi_dsl_query
Interfaces¶
| Topic | Contract |
|---|---|
| REST | GET /api/titleconvert?title=… (single title). Optional: company, sector, industry, location, expand=cluster, group=onet. POST /api/titleconvert records the user's pick. |
| DSL | TITLECONVERT "…" [EXPAND CLUSTER] [WHERE COMPANY IS "…"]. Batch: TITLECONVERT ["a","b",…] (≤200; DSL/MCP only). SUBMIT TITLECONVERT records a pick. |
| MCP | aoi_dsl_query with the TITLECONVERT / SUBMIT TITLECONVERT command. |
| Cluster twin | GET /api/clusters/convert and CLUSTERCONVERT return clusters for a title (same underlying match, cluster grain). |
| Join after match | Read cluster_id from expand=cluster / EXPAND CLUSTER, then query company_occupation_summary, wages, and badges. |
Response fields¶
Envelope + data[] for GET / TITLECONVERT / aoi_dsl_query.
| Field | Type | Where | Description |
|---|---|---|---|
onet_code |
string | data[] | O*NET-SOC of the match, format XX-XXXX.XX. |
onet_title |
string | data[] | O*NET title for that code. |
cluster_id |
int | data[] when expand=cluster | Occupation cluster. De-duplication grain. Join key into COS / wages / badges. |
cluster_name |
string | data[] when expand=cluster | Canonical cluster name (same as GET CLUSTER). |
match_score |
number 0–1 | data[] | Relevance. Best row in the response is 1.0; others are relative to it. |
confidence |
high | low | data[] | Catalog corroboration: high = catalog recognised the matched name; low = it did not. Independent of match_score. |
match_source |
string | data[] | Retriever(s) that found the row, '+'-joined if more than one agreed. See Values. |
recommended |
bool | data[] | True on the disambiguation winner. |
recommendation_reason |
string | data[] | historical_pattern | llm_inference | survey_prior | llm_skipped. |
matched_name |
string | data[] | Display name that matched (catalog representative or hint display_title). |
vector_similarity |
number 0–1 | data[] when match_source includes vector | Cosine similarity on a vector-recall row. |
owner_class |
bool | data[] when applicable | True only for self-employment-ambiguous titles (e.g. owner). Omitted otherwise. |
hint_applied |
object | query_info / command | {variant, onet_code, action, source}. Omitted when no hint fires. |
disambiguation.status |
string | envelope | resolved | ambiguous | no_match. |
unmatched_tokens |
string[] | envelope | Tokens the matcher could not use. Read with disambiguation.status=no_match. |
title_conversion¶
Employer title blobs → O*NET. Company-scoped TITLECONVERT reads this. top_10_titles is semicolon-separated.
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
title_id |
SERIAL | PRIMARY | Surrogate key. | Not a client field. |
company_uid |
VARCHAR(50) | INDEX | Company UID. | TITLECONVERT company-scoped path. |
company_name |
VARCHAR(255) | INDEX | Company name. | REST: ?company= DSL: WHERE COMPANY IS. |
onet_code |
VARCHAR(20) | INDEX | O*NET code this title blob maps to. | TITLECONVERT data[].onet_code. |
consolidated_title |
VARCHAR(255) | INDEX | O*NET title. | TITLECONVERT data[].onet_title. |
top_10_titles |
TEXT | GIN / FTS | Packed list of job titles used at this company for this O*NET (semicolon-separated). | Match input; not returned as the blob. |
created_at |
TIMESTAMP | Record creation time. | Not served. | |
updated_at |
TIMESTAMP | Last update time. | Not served. |
title_probability¶
Survey P(title|occupation) and occupation mix. No-company typeahead (match_source=name_corpus) and fusion scoring.
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
id |
BIGSERIAL | PRIMARY | Surrogate key. | Not a client field. |
onet_code |
VARCHAR(20) | INDEX | O*NET code. | TITLECONVERT data[].onet_code when match_source includes name_corpus. |
onet_name |
VARCHAR(150) | O*NET occupation name. | TITLECONVERT data[].onet_title. | |
occupation_share |
DOUBLE | P(occupation) in the survey mix (not BLS employment). Sums to 1.0 across occupations. | Used in scoring; not a standalone endpoint. | |
title_rank |
SMALLINT | Rank of this title within the occupation. | Used in scoring; not a standalone endpoint. | |
title |
VARCHAR(160) | INDEX / GIN | Survey title, stored lowercase. | Match input to GET /api/titleconvert, TITLECONVERT. |
probability |
DOUBLE | P(title | occupation). | Used in scoring; not a standalone endpoint. |
occupation_name_catalog¶
PK (name_norm, cluster_id). TITLECONVERT match surface at cluster grain. A name may map to more than one cluster.
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
name_norm |
TEXT | PRIMARY (composite) | Exact-match key (case/punctuation folded). | Match input after TITLECONVERT normalization. Not a client field. |
cluster_id |
INT | PRIMARY (composite) | Cluster this name refers to. TITLECONVERT de-duplicates at this grain. | ?expand=cluster / EXPAND CLUSTER. |
name |
TEXT | Representative display form. | TITLECONVERT data[].matched_name. | |
canonical_key |
TEXT | INDEX (partial) | Fallback key: stopwords and seniority dropped, tokens sorted. NULL if nothing survived. Scored below name_norm. | match_source catalog_canonical. |
onet_code |
VARCHAR(32) | Representative O*NET for interop. Cluster is the grain. | TITLECONVERT data[].onet_code. | |
name_type |
VARCHAR(32) | Strongest contributing source. See Values sheet. | Not a required client field. | |
weight |
NUMERIC(4,3) | Authority 0–1. Rows below the authority threshold retrieve but cannot override on provenance alone. | Feeds confidence (high vs low). | |
employer_n |
INT | Distinct employers using this name. | Not a client field. | |
source_count |
SMALLINT | Independent sources that agreed on this (name, cluster). | Not a client field. | |
created_at |
TIMESTAMPTZ | Row created. | Not served. | |
updated_at |
TIMESTAMPTZ | Row updated. | Not served. |
name_company_evidence¶
PK (name_norm, cluster_id, company_name). Company boost applied after a catalog match. Passing company boosts a hit; it does not hide unmatched names.
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
name_norm |
TEXT | PRIMARY (composite) | Same normaliser as the catalog. | TITLECONVERT ?company= / WHERE COMPANY IS. |
cluster_id |
INT | PRIMARY (composite) | Cluster the name maps to. | TITLECONVERT result grain. |
company_name |
TEXT | PRIMARY (composite) | Canonical employer that used this name. | TITLECONVERT company context. |
titleconvert_picks¶
PK id (UUID). Client pick intake. Does not change ranking.
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
id |
UUID | PRIMARY | Client-supplied or server-generated GUID. Resubmitting the same id is idempotent. | POST /api/titleconvert, SUBMIT TITLECONVERT. Returned as data.id. |
title |
TEXT | INDEX | Searched string (query_info.title). | Required on the pick body. |
onet_code |
VARCHAR(32) | INDEX | Picked O*NET. | Required. Body picked.onet_code or CHOICE "…". |
onet_title |
TEXT | Picked O*NET title. | Optional on the pick body. | |
picked |
JSONB | The chosen data[] element, as received from GET. | POST body. Copy from GET; do not invent a row. | |
query_info |
JSONB | GET envelope query_info echo. | Optional on the pick body. | |
shown |
JSONB | Full data[] if posted back (shown-set context). | Optional on the pick body. | |
submitted_by |
VARCHAR(255) | JWT subject of the submitter. | Set by the server. | |
created_at |
TIMESTAMPTZ | INDEX | Submitted at. | Returned on the pick acknowledgement. |
title_match_hints¶
PK variant. Exact mapping from a normalized title to an O*NET, no-company path only. Response: match_source=hint and query_info.hint_applied (omitted when no hint matches).
| Field | Type | Key | Description | Interface notes |
|---|---|---|---|---|
variant |
TEXT | PRIMARY | Normalized title (lowercase, single-space collapsed). | Match input after TITLECONVERT normalization. |
onet_code |
VARCHAR(32) | INDEX | Pinned O*NET. | TITLECONVERT data[].onet_code; hint_applied.onet_code. |
action |
VARCHAR(16) | pin (short-circuit) or promote (reserved). | hint_applied.action. | |
display_title |
TEXT | Optional display override. | TITLECONVERT data[].matched_name. | |
source |
VARCHAR(16) | curated | derived. | hint_applied.source. | |
support_count |
INT | Evidence count for derived rows. | Not served. | |
note |
TEXT | Why this hint exists. | Not served. | |
created_by |
VARCHAR(64) | Reviewer / generator id. | Not served. | |
created_at |
TIMESTAMPTZ | Created. | Not served. |