Differences

This shows you the differences between two versions of the page.

--- ai_gateway [2026/11/04 16:59] – created Gareth Johnstone
+++ ai_gateway [2026/11/04 17:09] (current) – Gareth Johnstone
@@ Line 1: / Line 1: @@
-====== IQX AI Gateway ======
+<note>
+The UI and API examples on this page are representative mockups — hostnames, keys, names and figures shown are illustrative, not live screenshots.
+</note>
-The **IQX AI Gateway** is the single front door for every AI feature in IQX. Instead of each part of the product talking to an AI provider directly, everything — the **IQXAssist** chat your consultants use, the wiki help assistant, CV reformatting, photo and document reading, audio transcription — calls //one// internal service. That service picks a model, routes the request, retries elsewhere if something is down, meters the spend, logs the usage, and hands the answer back.
+===== IQX AI Gateway =====
-In short: it is an AI //router// and //control plane//. The clever bits (which model, failover, cost caps, encryption) live in one place, so every IQX feature behaves the same way and we can add or swap models without touching the apps.
+The **IQX AI Gateway** is the single front door for every AI feature in IQX. Instead of each part of the product talking to an AI provider directly, everything — the **IQXAssist** chat your consultants use, the wiki help assistant, CV reformatting, document and photo reading, audio transcription — calls //one// internal service. That service picks a model, routes the request, retries elsewhere if something is down, meters the spend, logs the usage, and hands the answer back.
-**At a glance**
+In short, it is an AI //router// and //control plane//: the clever bits (which model, failover, cost caps, encryption) live in one place, so every IQX feature behaves the same way and we can add or swap models without touching the apps.
-  * **EU-hosted, open-weight models** behind it — nothing is sent to the big US AI vendors.
+<note tip>
+**At a glance**
+  * **EU-hosted, open-weight models** — nothing is sent to the big US AI vendors.
   * **One API key per tenant/client**, with per-key capabilities and a monthly **spend cap**.
-  * **Automatic failover** — if a model or provider fails, the gateway transparently tries another.
+  * **Automatic failover** — if a model is unavailable, the gateway transparently tries another.
   * **OpenAI-compatible** — point any OpenAI SDK at ''/v1'' and it just works.
-  * Chat history stored in **MongoDB in the UK**, **encrypted per message** (AES-256-CBC), auto-deleted **30 days** after last use.
+  * Chat history stored in **MongoDB in the UK**, **encrypted per message**, auto-deleted **30 days** after last use.
+</note>
 ----
-====== Two ways to use it ======
+===== IQXAssist — the in-app chat =====
-There are two surfaces on top of the same gateway:
+IQXAssist is the assistant your consultants talk to inside IQX. Unlike a standard "question and answer" bot, it is **context-aware**: it knows which candidate or contact record you are viewing and can pull live data specific to them.
-^ Surface ^ Who uses it ^ What it is ^
+<row>
-| **IQXAssist (chat)** | Consultants, inside IQX | A stateful conversational assistant that can read IQX records and take actions (find shifts, check compliance, book, set availability) through controlled tools. |
+<col md="7">
-| **The HTTP API** | IQX services & scripts | A set of stateless endpoints for one-shot jobs — summarise, rewrite a CV, read a photo or document, transcribe audio, or a raw OpenAI-compatible chat call. |
+<image shape="thumbnail">{{:aigw_chat.png|IQXAssist finding suitable shifts, running a compliance check, and booking — all in one conversation.}}</image>
+</col>
-Both share the same keys, the same failover and the same spend caps.
+<col md="5">
+== Two modes ==
-----
+The chat works in two modes depending on what you ask:
-====== IQXAssist (the chat) ======
+  * **Conversational** — answers general questions, drafts text, or summarises information already in the chat.
+  * **Agent (live data)** — when you ask for specific records or actions (e.g. "show me open shifts"), it uses secure tools to fetch real-time data from IQX before answering.
-IQXAssist is the assistant your consultants talk to inside IQX. It always works **in the context of the record on screen** (e.g. the candidate they're looking at) and can call a small set of IQX tools to do real work — not just chat.
+Every session is tied to the record you are viewing. Navigate to a different candidate and a new chat begins, so data can't cross over between records.
+</col>
+</row>
-{{:ai_gateway:iqxassist_chat.png?direct&780|IQXAssist: finding suitable shifts, running a compliance check, and booking — all in one conversation.}}
+==== What it can pull in (read) ====
-===== What it can do =====
+IQXAssist has strictly defined **tools** that let it read specific parts of a record. These are read-only and never change anything.
-The assistant has five tools. Read-only tools run freely; **write** tools (booking, availability) are **only** carried out after the consultant explicitly confirms, and are then re-validated on the server before anything is saved.
+^ Data type ^ What it can see ^ Best way to ask ^
+| **Timesheets / records** | Pay status, hours, rates, notes, placements | "Show timesheets from 1 Jan to 1 Feb" |
+| **Shifts** | Open shifts the candidate is suitable and available for | "What shifts are open for them next week?" |
+| **Availability** | Holidays and unavailability blocks | "Are they available in March?" |
+| **Compliance** | Licence details, training, medicals, right to work | "Compliance-check them for the Friday night shift" |
-^ Tool ^ Type ^ What it does ^
+<note tip>
-| Candidate data | read | Pulls live IQX records for the candidate in context (timesheets, notes, placements…) over a date range. |
+**The "date range" rule** \\
-| Matching shifts | read | Finds **open** shifts the in-context candidate is suitable and available for. |
+To avoid overloading the system, the AI looks for a specific timeframe. If you ask for records without a date it may default to the last 30 days or ask you to clarify. Try to specify: "last month", "next week", or "since Jan 2024".
-| Compliance check | read | Checks whether the candidate is compliant for one specific shift, with a pass/warning/fail breakdown and an overall % score. |
+</note>
-| Book shift | **write** | Books the candidate into a shift. Only ever after explicit confirmation; refused server-side if availability/compliance/booking rules fail. |
-| Set availability | **write** | Records the candidate's availability (available / unavailable / holiday) over a date range, optionally by weekday or time window. |
-Which tools a key can use is set **per API key** — a disabled tool is never even offered to the model.
+==== Taking actions (write) ====
-----
+IQXAssist can also do things on your say-so — propose a **shift booking** or record an **availability change**.
-====== How it works ======
+<note important>
+Write actions are **only ever carried out after you explicitly confirm them**, and every action is re-validated server-side (availability, compliance, booking rules, still-open) before anything is saved. If a rule fails, the action is refused and the reason is shown.
+</note>
-Every request — chat or API — flows through the same pipeline:
+==== Drafting & formatting ====
-<code>
+One of the handiest features is drafting communications:
-  IQX app / service
-        │   Authorization: Bearer <key>.<user>
-        ▼
-  ┌──────────────── IQX AI Gateway ─────────────────┐
-  │   auth  →  spend-cap check  →  pick model        │
-  │            ┌───────────┴───────────┐             │
-  │        model A                 model B           │   ← EU-hosted
-  │            └──────► failover ◄──────┘            │
-  │   log usage · meter cost · encrypt & store chat  │
-  └─────────────────────┬────────────────────────────┘
-                        ▼
-                  response to caller
-</code>
-===== Models & failover =====
+  * **Emails** — ask it to "write an email…" and it produces a professional, contact-event-ready email (subject and body).
+  * **Text / SMS** — ask for a "text message" and it keeps the wording short and casual, suitable for mobile.
-The gateway offers a range of EU-hosted, open-weight models — a fast general model (the default), a higher-capability model, a **vision** model for reading images, and an **audio** model for transcription. Which one serves a request is chosen by the gateway; callers never hard-code a model. If a model or provider fails, rate-limits or can't serve the request, the gateway **transparently fails over** to another so the caller still gets an answer. The specific models are managed centrally and can change without any change to the apps.
+==== Smart touches ====
-===== Spend caps =====
+  * **Streaming responses** — answers appear in real time as the AI works, rather than waiting for the whole reply.
+  * **Auto-titling** — each session is given a short title from the first few messages, so it's easy to find later.
-Each key has an optional **monthly spend cap**. The gateway meters cost on every call and hard-stops once the cap is reached (a cap of 0 means "unlimited"). This protects against runaway cost per client.
+----
-===== Storage, encryption & retention =====
+===== The API — endpoint by endpoint =====
-  * Chat history and usage logs live in **MongoDB hosted in the UK**.
+Every capability is also a single HTTP call, so any IQX service or script can use it. Authenticate with a Bearer key — the optional user id after the dot attributes usage to a person:
-  * Chat message content is **individually encrypted at rest** (AES-256-CBC, unique salt + IV per message; the key is held by the server, outside the database).
-  * A chat session and all its messages are **automatically deleted 30 days** after the last interaction. Uploaded files (CVs, images, audio) are swept within ~1 hour. Usage logs keep **metadata only** (no message content).
-  * Model inference is **transient** — prompts are processed, not stored, by the model providers.
-----
+<code>Authorization: Bearer YOUR_KEY.USER_ID</code>
-====== What it can do — endpoint by endpoint ======
+Here is what each endpoint takes in and gives back.
-Every capability is one HTTP call. Authenticate with a Bearer key (''Authorization: Bearer <key>.<userId>'' — the optional ''.<userId>'' attributes usage to a person). Here's what each endpoint takes in and gives back.
+==== Read a document — get JSON out ====
-===== Read a document — get JSON out =====
+Send an image plus a prompt. Ask a plain question and get an answer, or ask for the fields and they come back parsed in ''response.json''. Driving licences, passports, DBS certificates, timesheets, whiteboards — all fair game.
-Send an image and a prompt. Ask a plain question and get an answer, or ask for the fields and they come back parsed in ''response.json''. Driving licences, passports, DBS certificates, timesheets, whiteboards — all fair game.
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_image.png|POST /api/image — upload a driving licence, get structured JSON back.}}</image>
+</col></row>
-{{:ai_gateway:showcase_image.png?direct&860|POST /api/image — upload a driving licence, get structured JSON back.}}
+==== Lift the photo off an ID ====
-===== Lift the photo off an ID =====
+Finds the portrait on a licence, passport or ID card and crops it out — ready to save straight to the candidate's record as their profile picture.
-Finds the portrait on a licence, passport or ID card and crops it out — ready to set as a candidate's profile picture.
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_extract_photo.png|POST /api/extract-photo — crop the portrait out of an ID.}}</image>
+</col></row>
-{{:ai_gateway:showcase_extract_photo.png?direct&860|POST /api/extract-photo — crop the portrait out of an ID.}}
+==== Transcribe audio ====
-===== Transcribe audio =====
 Drop in a voice note or interview recording and get an accurate transcript straight back.
-{{:ai_gateway:showcase_transcribe.png?direct&860|POST /api/transcribe — audio in, transcript out.}}
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_transcribe.png|POST /api/transcribe — audio in, transcript out.}}</image>
+</col></row>
-===== Reformat a CV to house style =====
+==== Reformat a CV to house style ====
-Upload a candidate's CV (PDF or Word) plus your template and logo; get back a consistent, branded CV.
+Upload a candidate's CV (PDF or Word) plus your template and logo; get back a consistent, branded CV. Personal contact details are **automatically redacted** in the process.
-{{:ai_gateway:showcase_cv.png?direct&860|POST /api/cv/reformat — any CV in, your branded house style out.}}
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_cv.png|POST /api/cv/reformat — any CV in, your branded house style out.}}</image>
+</col></row>
-===== Tighten rough CV wording =====
+==== Tighten rough CV wording ====
 Clean up a candidate's own words into polished, professional CV copy.
-{{:ai_gateway:showcase_cvrewrite.png?direct&860|POST /api/cv-rewrite — rough text in, polished copy out.}}
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_cvrewrite.png|POST /api/cv-rewrite — rough text in, polished copy out.}}</image>
+</col></row>
-===== One-shot answers over a record =====
+==== One-shot answers over a record ====
 Send a record (or any document) plus a prompt and get a tidy answer back — great for summaries embedded in other IQX screens.
-{{:ai_gateway:showcase_query.png?direct&860|POST /api/query — record plus prompt in, tidy answer out.}}
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_query.png|POST /api/query — record plus prompt in, tidy answer out.}}</image>
+</col></row>
+==== Drop-in OpenAI-compatible endpoint ====
+Point any OpenAI SDK at ''/v1'' and it just works — streaming and tools included. The gateway picks the model and handles failover underneath. ''GET /v1/models'' returns a friendly model list for a picker.
+<row><col md="12">
+<image shape="thumbnail">{{:aigw_developer.png|POST /v1/chat/completions — standard OpenAI calls, routed and capped by the gateway.}}</image>
+</col></row>
+----
-===== Drop-in OpenAI-compatible endpoint =====
+===== Security & data =====
-Point any OpenAI SDK at ''https://gateway.iqx.scot/v1'' and it just works — streaming and tools included. The gateway picks the model and handles failover underneath. ''GET /v1/models'' returns the friendly model list for a picker.
+<row>
+<col md="6">
+<note>
+**Private by design**
+  * Chat content is **individually encrypted at rest** — even database administrators can't read the raw message history.
+  * Sessions are **context-isolated** per record, so data never crosses between candidates.
+  * The models **do not train** on your data.
+  * CV contact details (phone, email, address) are **redacted** automatically.
+</note>
+</col>
-{{:ai_gateway:showcase_developer.png?direct&860|POST /v1/chat/completions — standard OpenAI calls, routed and capped by the gateway.}}
+<col md="6">
+<note>
+**Where it lives**
+  * Chat history and usage logs are stored in **MongoDB in the UK**.
+  * Sessions and their messages are **auto-deleted 30 days** after the last interaction; uploaded files are swept within an hour.
+  * Model inference runs on **EU-hosted** providers and is **transient** — prompts are processed, not stored.
+  * Usage logs keep **metadata only** (no message content).
+</note>
+</col>
+</row>
 ----
-====== Endpoint reference ======
+===== Endpoint reference =====
 ^ Endpoint ^ Method ^ Purpose ^
@@ Line 138: / Line 176: @@
 | ''/api/cv-rewrite'' | POST | Rewrite / tidy CV text to a prompt. |
 | ''/api/cv/reformat'' | POST | Reformat an uploaded CV (PDF/DOCX) into an HTML template, optional logo. |
-| ''/api/image'' | POST | Vision — ask a question about an uploaded image, or extract its fields as JSON. |
+| ''/api/image'' | POST | Vision — ask a question about an image, or extract its fields as JSON. |
 | ''/api/extract-photo'' | POST | Vision — crop the portrait photo out of an ID image. |
 | ''/api/transcribe'' | POST | Audio — transcribe an uploaded audio file. |
@@ Line 149: / Line 187: @@
 ----
-====== Getting access ======
+===== Getting access =====
 Keys, capabilities and spend caps are managed by IQX in the gateway admin. If you need a key for a new service or client, or want a capability enabled, contact the IQX development team.
-//Note: hostnames, key values, names and figures on this page are illustrative. The mockups are representative of the real UI/API, not live screenshots.//