Lab AI Assistant

What the assistant can help with

The Lab AI Assistant is a manager workspace inside the Lab Panel. It can answer operational questions, open the right panel page, explain workflows, prepare data tables, and prepare certain operational actions for manager approval. It is designed for day-to-day lab management, not for public patients and not for staff accounts that do not have assistant permission.

The assistant is permission-gated. The AI Assistant feature must be enabled, the user must have labs.ai_assistant.access, the user must be able to access the selected tenant branch, and the user role must be Manager. If any of those conditions are missing, the assistant endpoints return forbidden or unavailable responses.

Use the assistant when a manager needs a faster way to find a page, ask for a short operational explanation, summarize current lab data, or prepare a non-destructive action that still requires explicit confirmation.

The assistant window

Open Kashef AI from the bottom section of the sidebar, directly above Settings. The sidebar button remains available while you move between panel pages and shows when the assistant is open.

Kashef AI opens as a compact floating window beside the sidebar, keeping the current page visible underneath. Use the pin button in the window header when you want a stable side pane for longer work. The pinned pane moves to the outer side of the workspace, shifts the page so content stays readable, and can be resized on desktop. Select the pin button again to return to the smaller floating window. Kashef remembers the chosen mode. Arabic layouts mirror the placement automatically, and mobile uses a near-full-screen overlay that closes with the close button, the backdrop, or Escape when a keyboard is attached.

The header shows the active conversation name plus New, pin or unpin, and close controls. Use the History tab beside Chat and Artifacts to find earlier conversations. The compact header, tabs, composer, and footer reserve most of the window height for the conversation. Visual motion runs once when an element appears instead of looping, and it is disabled when the device requests reduced motion.

The chat tab is the normal working area. The empty chat shows quick prompts such as KPI snapshot, navigating to orders, latest orders, or SLA risk. The composer accepts normal language, so managers can ask things like "show today's overdue orders", "open the cashier workbench", "how do I release reviewed results?", or "prepare a note for order 123".

Messages can include assistant text, tool progress messages, navigation artifacts, table artifacts, and pending action cards. The stream is live, so a manager may see short system updates such as checking lab records, preparing a table, or resolving a destination before the final answer appears.

Conversations and history

Each manager has their own conversation list. The assistant stores conversations by user and tenant when tenant isolation is supported. The history panel shows recent conversations, lets the user create a new conversation, rename a conversation, pin or unpin important conversations, search the list, and delete old conversations.

Conversation history is useful for follow-up questions. For example, a manager can ask for today's delayed orders, then ask "open the table again" or "explain why these are delayed" in the same thread. Do not use one long conversation for unrelated work across different shifts if it becomes confusing; create a new conversation for a new review session.

Scope: current branch or all branches

The assistant request includes a data scope. Current Branch limits data questions and actions to the active branch. All Branchs uses company scope and includes branches belonging to the same lab company. The context object resolves branch IDs from the selected scope, and tools must not widen that scope because the user asked them to.

Scope is one of the most important safety controls. If a manager asks for "all delayed orders" while the scope is current branch, the result should represent the selected branch only. If the manager wants company-wide review, switch the scope before asking. Always confirm the branch selector and scope before relying on a number in a management meeting.

For count-only SLA questions, the assistant calculates the summary directly from current records and returns a scoped table. All Branches means every accessible branch in the current lab company only; it never includes another company. The response states the applied scope and counts overdue, at-risk, and on-track work without exposing patient details.

Safety refusals

The assistant never exposes patient or clinical data from another lab company and never releases results by bypassing authorized clinical review and approval. If a prompt asks for either behavior, Kashef stops it before any AI provider, data tool, or data-changing action runs.

The conversation shows an explicit refusal instead of a generic outage. It explains the tenant and clinical-approval boundaries, confirms that no tool or mutation was attempted, and includes a reference ID. Kashef also records a safety audit event with the manager, branch, scope, policy codes, and a prompt hash; the raw sensitive prompt is not copied into the audit properties.

Specialist agents

The assistant routes each message to a specialist. The supervisor chooses between specialist agents, and the UI shows which agent was selected.

Insights Agent handles data retrieval, analytics, patient/order/result lookups, KPI summaries, trends, SLA risk, backlog breakdown, and generated tables. It retrieves live records through the guarded GraphQL path and should not guess numbers.

Help Desk Agent explains platform usage, capabilities, page purpose, and workflow steps. It can look up available features, navigation entries, and workflow guidance, but it should not fetch live records.

Navigation Agent resolves a user request to the best panel destination. It can open dashboard, operations workbench, orders, samples, results queue, home visit dispatch, cashier workbench, finance dashboard, and specific order pages when an order ID can be resolved.

Actions Agent prepares operational changes such as creating an order request, changing order status, assigning order staff, scheduling or reassigning home visits, marking sample status, and adding an order note. It does not execute changes directly.

Live Help Center grounding

For how-to, setup, troubleshooting, feature, and page-purpose questions, the Help Desk searches a live bilingual knowledge index before answering. That index is assembled from the authored English and Arabic Help Center guides and the Filament pages and resources that the current manager is actually allowed to open. It combines exact terms, colloquial wording, cross-language concepts, and character similarity, then fuses the rankings so questions do not need to copy a page label exactly.

New Help Center articles are discovered from the documentation folders without a separate AI manifest. Newly registered Lab Panel pages and resources are also included automatically when they are visible and permitted for the current manager. Help answers can therefore cite the matching guide or real panel destination instead of relying on a remembered, hard-coded workflow. The Help Desk still does not retrieve patient or operational records; live numbers and lists remain the Insights Agent's responsibility.

Data tables and artifacts

Kashef separates a management question from a request to display records. If you ask for an opinion, diagnosis, comparison, risk review, or recommendation, the Insights Agent reads the permitted live evidence and replies with a written analysis. It does not create a table merely because the evidence contains rows. Ask explicitly to show, list, tabulate, export, or download records when you want an interactive table.

For a management health review, the Insights Agent can use the same permitted patient, doctor, partner-lab, order, test, turnaround, catalog, pricing, finance, and inventory datasets available in the Reports cluster. It can combine that evidence with approval-pending transactions, suppliers, and the order pipeline. Useful prompts include "Show doctor performance this month", "Which catalog tests are missing prices?", and "Review the lab pipeline and tell me what needs attention." The answer should separate current facts from interpretation and tie each recommendation to evidence and the selected date, branch, or company scope.

The assistant is read-only while performing this analysis. It does not change a price, launch a promotion, place a purchase request, post finance entries, or approve operational work. Review the cited records in their normal Kashef pages before making a decision, especially when missing or late entries could affect the conclusion.

When the assistant prepares a table, a compact preview of up to five rows appears directly in the conversation, and the complete result also appears in the Artifacts tab. Select Open for the signed Assistant Query Table page. The page is temporary, restricted to the manager and tenant that requested it, and generated from cached data for a short window. Its language follows the language used in the request, even when that differs from the panel language.

The query table supports search, sorting, pagination, wrapped columns, and a Columns control for showing, hiding, and reordering fields. Kashef chooses a useful initial set from the request while keeping additional fields available. When a result represents a known Kashef record, linked values such as the order number or patient name open the real authorized record, and Open record is available as a row action. View details opens nested fields and related collections without expanding them into duplicate rows.

The generated table is intended for analysis and drill-down, not as the permanent source of truth. Complete edits and approvals on the linked order, patient, sample, result, finance, or inventory page so normal permissions and audit trails remain in force.

The artifacts tab may also show navigation artifacts. Those contain the destination title, summary, and an Open action. Navigation is guarded so the assistant cannot open arbitrary external URLs; destinations must be valid URLs inside the current lab panel tenant.

Pending actions and approval

The assistant can prepare actions, but manager confirmation is required before execution. When an action is prepared, the user reviews a confirmation modal with the action type and payload details. The manager can approve and execute the action, or reject it with a reason.

Pending actions expire after the configured assistant TTL. If an action is no longer pending or has expired, Kashef refuses execution and returns a clear status. Approved, rejected, failed, and executed actions are logged with the conversation, user, tenant, action type, payload, result, status, and duration where applicable.

The actions flow intentionally blocks destructive requests such as delete, purge, or irreversible cancel. If the manager needs a destructive administrative change, use the appropriate panel workflow with the normal permissions and audit trail.

Clinical release guidance

When asked how to release results, the Help Desk Agent loads the current result workflow policy before answering. Its answer must explicitly state that every entered result needs manager or authorized clinical-reviewer approval before final release. Entry, payment settlement, or a passing QC run alone never replaces that approval.

The grounded guidance also names the remaining sample, payment, QC, approval, and release-permission gates and links the user to Review and release results. If the workflow policy cannot be loaded, the assistant must stop short of release instructions and direct the manager to the real Results Review page and Help Center article. The application release service independently blocks missing or unapproved results even when the optional QC gate is disabled, so assistant wording and the enforced clinical workflow share the same mandatory approval boundary.

Debug and errors

In local environments the assistant can expose a debug tab. Debug mode shows raw stream events for development and troubleshooting. In production-like environments that tab may not be available, and normal managers should not need it.

If the assistant cannot stream a response, the UI shows an assistant error banner. Common causes include missing provider credentials, a model/provider timeout, a failed stream, or an unavailable tool. A safety refusal is not an outage and should not be retried unchanged. For operational errors, retry with a smaller question, verify assistant permissions, confirm the branch and scope, and check whether the data exists in the real panel page.

Good questions to ask

Good assistant prompts are specific and scoped. Ask "show the latest 10 orders for the current branch", "summarize SLA risk right now", "open order 145", "how do I enter reviewed results?", "prepare an order note for order 145 saying the patient requested WhatsApp delivery", or "show pending collections today".

Avoid prompts that ask the assistant to bypass policy, delete records, make clinical decisions without review, or expose data outside the selected branch/company scope. The assistant is a management helper; it does not replace the responsibility of the lab owner, manager, pathologist, accountant, or technician who approves the real-world work.