Skip to content

title: Regnify Tool: get_rep_register

Regnify Tool: get_rep_register

Back to Regnify Product Docs

| Document Type | Regnify Internal | | Status | current | | Last Updated | 2026-05-05 |

Previous Next

Purpose

get_rep_register is the primary tool for all org-wide representative queries -- health badge distribution (GREEN/AMBER/RED counts), roster listing, rep count, and compliance snapshot. It fetches real-time data from the NestJS GraphQL resolver repProfilesWithHealth and returns every rep under the target organisation with their compliance status pre-computed server-side.

Use this tool instead of any GraphQL repProfiles query for rep-count, badge-distribution, or org-wide rep-status questions. The data comes from the live database -- never fabricate rep data; always call the tool.

Signature

get_rep_register(org: OrgRef | None = None) -> dict

Parameters

Parameter Type Required Description
org {"kind": "org", "id": <int>} No Principal organisation reference. When omitted or None, defaults to ctx.org_id (the authenticated user's organisation binding). Only pass explicitly when the user names a specific different organisation.

org default behaviour

  • COMP, HR_ADMIN, ORG_ADMIN users: bound to a single organisation -- org can be omitted; the tool uses ctx.org_id automatically.
  • SYS_ADMIN users: have no organisation binding (ctx.org_id is None). If org is omitted for a SYS_ADMIN, the tool raises ValueError instructing the LLM to ask the user which organisation to query. Never guess or fabricate an org ID for SYS_ADMIN users -- ask them.
  • FI_USER and REP_USER: The underlying NestJS resolver repProfilesWithHealth is guarded with @Roles("COMP", "HR_ADMIN", "ORG_ADMIN", "SYS_ADMIN"). FI_USER and REP_USER calling this tool will receive a GraphQL authorization error (403/Unauthorized). If an FI_USER or REP_USER asks about rep health, direct them to their own Rep Portal dashboard instead.

Return Shape

{
  "org_id": <int>,
  "reps": [
    {
      "rep_profile_id": <int>,
      "user_id": "<Keycloak sub UUID string>",
      "rep_number": "<string or null>",
      "user_name": "<string or null>",
      "flag": "green" | "amber" | "red",
      "reasons": ["<string>", ...],
      "cpd_hours_ytd": <float>,
      "cpd_hours_ethics_ytd": <float>,
      "cpd_hours_product_ytd": <float>,
      "cycle_year": <int>,
      "has_missing_required": <bool>
    },
    ...
  ]
}

Field Details

  • rep_profile_id: Numeric primary key. Use this as the id in RepProfileRef ({"kind": "rep_profile", "id": <int>}) when calling per-rep tools like get_cpd_status, analyze_cert_gap, draft_cpd_reminder, or detect_attestation_anomaly.
  • user_id: Keycloak sub claim (String UUID). This is the user's identity foreign key -- NOT the same as rep_profile_id.
  • flag: Server-side computed health badge. Three values only.
  • reasons: Human-readable explanation strings for the flag (e.g., "Missing required module M5", "CPD ethics hours below threshold").
  • cpd_hours_ytd / cpd_hours_ethics_ytd / cpd_hours_product_ytd: Current calendar year CPD hour totals (year-to-date).
  • has_missing_required: Boolean. true when the rep has at least one required CMFAS module not yet passed.

Health Badge (flag) Logic

The flag is computed server-side by the repProfilesWithHealth resolver -- not by the chatbot LLM. The server applies these rules (derived from FAA-N26 and SFA competency requirements):

Flag Condition
GREEN All required CMFAS modules passed AND CPD meets FAA-N26 thresholds (30 hours total: ≥6h Core CPD [ethics/rules, IBF/SCI-accredited] + ≥24h Supplementary CPD in the current cycle year)
AMBER All required CMFAS modules passed BUT CPD is below one or more FAA-N26 thresholds
RED At least one required CMFAS module is missing (not passed / expired) -- CPD status is irrelevant once a CMFAS gap exists

The server-side classification is a deterministic rule engine (structural thresholds, CLAUDE.md section 10-clean). No LLM re-classification is needed -- surface the server's flag and reasons verbatim to the user.

Use Cases

  1. Org-wide roster: User asks "show me all reps" or "list representatives in my org" -- call with org omitted.
  2. Badge distribution: User asks "how many RED reps do we have?" -- call, then count flags from the return payload. Example: 3 GREEN, 2 AMBER, 1 RED.
  3. Compliance snapshot: User asks "what's our compliance status?" -- call, summarize flag distribution, highlight RED reps by name.
  4. Pre-step for per-rep drill-down: After getting the roster, use individual rep_profile_id values to call analyze_cert_gap (for CMFAS gap details), get_cpd_status (for hour breakdown), or draft_cpd_reminder (for RED/AMBER reps).

Combination Patterns

  • get_rep_register + get_cpd_status: Get the roster, identify reps with AMBER flags, then drill into their specific CPD hour breakdown.
  • get_rep_register + analyze_cert_gap: Get the roster, identify RED reps, then run per-rep CMFAS gap analysis to determine exactly which modules are missing.
  • get_rep_register + draft_cpd_reminder: Get the roster, identify reps below CPD thresholds, draft reminders for each.

Error Conditions

Condition Behaviour
org is None and ctx.org_id is None (SYS_ADMIN) ValueError -- ask the user which organisation to query
GraphQL transport error RuntimeError -- surfaces verbatim; relay to user
No reps in org Returns {"org_id": <id>, "reps": []} -- empty list, no error

Important Rules

  1. Always call the tool -- never answer rep-count, roster, or badge questions from memory or inference. The data is live; stale answers are fabrications.
  2. Use rep_profile_id from the response when calling per-rep tools. Do not invent rep IDs.
  3. Do not ask the user for their org ID unless they are SYS_ADMIN. The auth context already has it.
  4. When in doubt, attempt the call -- let the tool surface real errors rather than preemptively claiming connection issues.

Previous Next

Back to Regnify Product Docs