Coach assistant

The assistant is an AI chat for coaches inside the web app. It reads studio data through tools and answers in Hebrew. It never writes during a chat turn. When the model wants to change something it stores a proposal, and the change happens only when the coach confirms it with a second request. Source: backend/apps/core-api/src/modules/assistant/ (assistant.routes.ts, assistant.controller.ts, assistant.service.ts, assistant.schema.ts). The module has no repository file. The service calls Prisma directly.

Mounting and auth

Router	Base path	Middleware
`assistantRouter`	`/v1/web/assistant`	Web lane: `serviceAuth`, `webUserContext`, `webLimiter`

Every handler goes through callerOf in the controller:

Missing studioId or userId on req.auth throws UNAUTHORIZED (401).
Role TRAINEE throws FORBIDDEN (403) with coaches only.
OWNER, HEAD_COACH and SUB_COACH are allowed.

See API overview for how the web lane builds req.auth.

Data scope

Each turn resolves the caller’s access with coachAccessFrom from middleware/coach-access.ts, using the caller’s Coach row (role, permissions, active).

A studio owner sees every trainee.
A coach whose permissions limit them to assigned trainees only sees clients that have a ClientCoach assignment to them. Their task list is limited to tasks assigned to them or tied to their trainees.
A coach with no Coach row, or with trainees: "all", sees the whole studio.
A dismissed coach (active: false) gets FORBIDDEN (403) with this team member has been removed.

Every tool query includes studioId and deletedAt: null. Admin. The service treats the caller as admin when the lane role is OWNER or the Coach row has role HEAD_COACH. Admins get the monthly revenue figure. The system prompt tells the model whether the user is an admin.

Environment variables

Variable	Use
`ANTHROPIC_API_KEY`	Key for the Anthropic provider. When empty, chat throws `INTERNAL`
`ANTHROPIC_WORKSPACE_ID`	Optional. Sent as the `anthropic-workspace-id` header
`AGENT_MODEL`	Model id. Shared with the WhatsApp AI agent

The assistant uses createAnthropic from @ai-sdk/anthropic and generateText from the ai package, with stopWhen: stepCountIs(8) and maxOutputTokens: 1600.

Reply shape

chat and confirm both return an AssistantReply.

type AssistantReply = {
  text: string;
  stats?: { label: string; value: string }[];
  list?: string[];
  proposal?: {
    id: string;
    kind: 'update_program' | 'swap_meal' | 'update_trainee' | 'create_task' | 'send_message';
    title: string;
    summary: string[];
    expiresAt: string;
  };
};

text is Hebrew and may contain **bold** and newlines.
stats are number cards, at most 8.
list is a bullet list, at most 12 lines.
proposal is present when the turn produced a pending change. summary holds human readable “before to after” lines. expiresAt is an ISO timestamp 15 minutes ahead.

Endpoints

`POST /v1/web/assistant/chat`

Sends one message and returns the assistant’s reply. Auth: web lane, roles OWNER, HEAD_COACH, SUB_COACH.

string

required

1 to 4000 characters.

string

Accepted by the schema but not used. The controller passes only message to the service. The thread is always the caller’s single thread.

What the service does:

Throws if no Anthropic provider is configured.
Reads or creates the thread id in Redis and refreshes its 48 hour expiry.
Increments the daily counter. Over the cap, it returns a fixed “daily limit reached” reply. That reply is not saved to history.
Resolves the caller’s scope, loads the stored history and builds the message list. Only the text of earlier turns is replayed to the model. Stats, lists and proposals from earlier turns are not.
Runs the model with the tool set below.
Builds the reply. The model is told to finish with the reply tool, and that tool’s text, stats and list are used. If it did not call reply, the raw model text is used. If get_business_stats ran and the model sent no stats, the cards from that tool are attached anyway. If any propose_* tool ran, the last proposal is attached.
Appends the user message and the reply to history.

If the model call throws, the error is logged and a fixed failure reply is returned with status 200. That turn is not saved to history. Response: 200.

{
  "ok": true,
  "data": {
    "threadId": "5f0c7a1e-2b0f-4e8a-9a55-3d1f7f2f8f10",
    "reply": {
      "text": "Here is where the studio stands today.",
      "stats": [
        { "label": "מתאמנים פעילים", "value": "84" },
        { "label": "משימות פתוחות", "value": "12" }
      ],
      "list": ["3 subscriptions end within 30 days"]
    }
  },
  "requestId": "req_123"
}

A reply that carries a proposal:

{
  "ok": true,
  "data": {
    "threadId": "5f0c7a1e-2b0f-4e8a-9a55-3d1f7f2f8f10",
    "reply": {
      "text": "I prepared the task. Press confirm to create it.",
      "proposal": {
        "id": "9b2d6c44-7a1e-4f3b-8a0d-1c2e3f4a5b6c",
        "kind": "create_task",
        "title": "פתיחת משימה לNoa Example",
        "summary": ["משימה: \"Call about measurements\"", "מתאמנים: Noa Example"],
        "expiresAt": "2026-10-07T08:45:00.000Z"
      }
    }
  },
  "requestId": "req_123"
}

Errors:

Code	Status	When
`VALIDATION`	422	`message` missing, empty or over 4000 characters
`UNAUTHORIZED`	401	Missing auth context
`FORBIDDEN`	403	Trainee role, or a dismissed coach
`INTERNAL`	500	`assistant AI is not configured`

`POST /v1/web/assistant/confirm`

Executes a stored proposal. Auth: web lane, roles OWNER, HEAD_COACH, SUB_COACH.

string

required

The proposal.id from a chat reply.

The proposal is read with Redis GETDEL, so it can be used once. A double click, a retry or a second tab gets NOT_FOUND. The stored studioId and userId must match the caller. A mismatch throws FORBIDDEN, and the proposal is still consumed. The caller’s scope is resolved again at confirm time, so a coach who lost access to a trainee after the proposal was made cannot execute it. After execution, a “confirmed” user line and the result are appended to history. What each kind does on confirm:

`kind`	Effect
`update_trainee`	Re-applies the field whitelist, then updates the `Client` row
`create_task`	Creates one `InboxItem` per trainee with `type: "MANUAL"`, `source: "manual"`, the title, priority and optional `dueAt`. The task is assigned to the trainee’s responsible coach (`Client.coachId`) when there is one, otherwise it is unassigned. See Tasks
`swap_meal`	Loads the program, replaces the meal at the stored day and meal index, runs the whole content through `normalizeNutritionContent` and saves it. The meal keeps its `id` and its `target`
`update_program`	Normalizes the stored content again, keeps the row’s AutoFit metadata with `keepAutofitMeta`, and saves it to `Program.content`
`send_message`	Push: `notifier.send(studioId, "TRAINER_MESSAGE", ...)` with the text as the body override. WhatsApp: `smartsend.sendMessage` with the studio’s own key from `Studio.settings.smartsend.apiKey`

send_message reports soft failures in the reply text with status 200, not as errors: the studio has the TRAINER_MESSAGE notification switched off, the trainee has no registered device, WhatsApp is not connected, or the trainee has no phone. A WhatsApp message sent this way is not stored as a WhatsappMessage row. Program edits made through the assistant write straight to Program.content. This code path does not send a plan-updated notification. Response: 200.

{
  "ok": true,
  "data": {
    "reply": {
      "text": "נפתחה משימה ✅ \"Call about measurements\""
    }
  },
  "requestId": "req_123"
}

Errors:

Code	Status	When
`VALIDATION`	422	`proposalId` missing
`NOT_FOUND`	404	`proposal not found, expired or already confirmed`, `client not found`, `clients not found`, `program not found`
`FORBIDDEN`	403	`this proposal belongs to another user`, trainee role, or a dismissed coach
`BAD_REQUEST`	400	`nothing to update` (the trainee patch is empty after the whitelist)
`CONFLICT`	409	`the program changed since this was proposed` (it became a PDF plan, or the day or meal index no longer exists)

A failed confirm does not restore the proposal. The coach has to ask again.

`GET /v1/web/assistant/thread`

Returns the caller’s stored conversation. Auth: web lane, roles OWNER, HEAD_COACH, SUB_COACH. Response: 200. threadId is null when no conversation exists. Messages are oldest first, up to 24.

{
  "ok": true,
  "data": {
    "threadId": "5f0c7a1e-2b0f-4e8a-9a55-3d1f7f2f8f10",
    "messages": [
      { "role": "user", "text": "How many active trainees do I have?" },
      {
        "role": "assistant",
        "text": "You have 84 active trainees.",
        "stats": [{ "label": "מתאמנים פעילים", "value": "84" }]
      }
    ]
  },
  "requestId": "req_123"
}

An assistant message in history can still carry a proposal object after that proposal expired or was confirmed.

`DELETE /v1/web/assistant/thread`

Starts a new conversation by deleting the thread id and the history. Auth: web lane, roles OWNER, HEAD_COACH, SUB_COACH. Response: 204 with no body. Pending proposals and the daily counter are not cleared.

Tools

The model gets eleven tools. Tool inputs are validated twice: by generateText and again inside each tool. A validation or lookup failure is returned to the model as an Error: ... string so it can recover. An AppError is rethrown.

Read tools

Tool	Input	Returns
`search_trainees`	`query` (string)	Up to 8 in-scope trainees matching name, phone or email, with `id`, `name`, `phone`, `status`, `planName`, `endsOn`
`get_trainee`	`idOrName` (string)	One trainee by id, or by name when exactly one matches. Includes profile fields, tags, responsible coach name, the live subscription (`planName`, `status`, `priceAgorot`, `startedOn`, `endsOn`), the latest weight and up to 6 programs. Several name matches return `multipleMatches` with up to 5 candidates
`get_program`	`clientId`, `type` (`TRAINING` or `NUTRITION`)	The normalized content of the trainee’s program of that type
`list_open_tasks`	none	Up to 20 open `InboxItem` rows, highest priority first, with the linked client
`get_business_stats`	none	Seven KPI cards, plus monthly revenue for admins

Program selection for get_program and the program proposals: the active program of that type, or else the most recently updated of the trainee’s last five. File plans (anything isFilePlan from modules/programs/plan-kind.ts matches) are refused with an error string because they have no days, meals or targets. get_business_stats returns these cards, all limited to the caller’s scope:

Active trainees (clients with status ACTIVE).
New this month (clients created since the first of the month).
Open tasks.
Urgent tasks (open tasks with priority 2 or higher).
Renewals in 30 days (active clients whose endsOn falls in the next 30 days and who have no scheduled subscription ending later).
Check-ins today (clients whose lastCheckInAt is today).
Workouts this week (WorkoutLog rows in the last 7 days).
Monthly revenue, admins only. The sum of priceAgorot over live subscriptions in the whole studio whose span touches the current month, shown in shekels.

Day and month boundaries use the server’s local time, not the studio timezone.

Proposal tools

Each of these stores a proposal in Redis and returns it to the model. Nothing is written to the database.

Tool	Input	Limits and checks
`propose_update_trainee`	`clientId`, `patch` (object)	Only `name`, `firstName`, `lastName`, `phone`, `email` and `goal` survive. Values must be non-empty strings. `phone` goes through `normalizePhone` and is dropped when it normalizes to empty
`propose_create_task`	`clientIds` (1 to 50), `title` (1 to 200 chars), `priority` (0 to 3, default 1), `dueAt` (ISO date, optional)	Every id must be in scope, or the whole proposal is refused. `dueAt` is stored as noon of that date
`propose_swap_meal`	`clientId`, `dayIndex`, `mealIndex`, `newMeal` (object)	Needs a regular nutrition program, an existing day and meal, and a non-empty `newMeal.items` array. `newMeal` may carry `name` or `label`, `type`, `time`, `prep` and `items`
`propose_update_program`	`clientId`, `type`, `newContent` (object)	Replaces the whole content. The content is normalized at propose time. The summary compares day and exercise counts for training, or day, meal and calorie target for nutrition
`propose_send_message`	`clientId`, `text` (1 to 1000 chars), `channel` (`push` or `whatsapp`)	One trainee per message. WhatsApp is refused when the trainee has no phone

When several proposals are made in one turn, each is stored but only the last one is returned in the reply.

The `reply` tool

reply takes text (required), stats (up to 8) and list (up to 12). It writes nothing. It is how the model hands back a structured answer.

What the assistant cannot do

There are no tools for deleting anything, for charges and payments, or for team management. The system prompt tells the model to say that these are done in the app.

Redis keys

Key	Type	Expiry	Purpose
`perform:assistant-history:<userId>`	list	48 hours	Last 24 thread messages
`perform:assistant-thread:<userId>`	string	48 hours, refreshed each turn	Thread id
`perform:assistant-cap:<userId>:<date>`	counter	25 hours	Daily message count
`perform:assistant-proposal:<id>`	string	15 minutes	A pending proposal with its payload, `studioId` and `userId`

History, thread and cap keys are keyed by user id only. They do not include the studio id.

Limits

Limit	Value
Message length	4000 characters
Messages per user per UTC day	300
History kept	24 entries, 48 hours
Proposal lifetime	15 minutes, single use
Model steps per turn	8
Output tokens per turn	1600
Trainees per proposed task	50
Message text for `propose_send_message`	1000 characters

WhatsApp AI agent for the WhatsApp version, which runs its tools through the automation API.
Notification configs for the TRAINER_MESSAGE type the push channel uses.
WhatsApp for connecting the SmartSend key the WhatsApp channel needs.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Coach assistant

Mounting and auth

Data scope

Environment variables

Reply shape

Endpoints

`POST /v1/web/assistant/chat`

`POST /v1/web/assistant/confirm`

`GET /v1/web/assistant/thread`

`DELETE /v1/web/assistant/thread`

Tools

Read tools

Proposal tools

The `reply` tool

What the assistant cannot do

Redis keys

Limits

​Mounting and auth

​Data scope

​Environment variables

​Reply shape

​Endpoints

​POST /v1/web/assistant/chat

​POST /v1/web/assistant/confirm

​GET /v1/web/assistant/thread

​DELETE /v1/web/assistant/thread

​Tools

​Read tools

​Proposal tools

​The reply tool

​What the assistant cannot do

​Redis keys

​Limits

​Related pages

Mounting and auth

Data scope

Environment variables

Reply shape

Endpoints

`POST /v1/web/assistant/chat`

`POST /v1/web/assistant/confirm`

`GET /v1/web/assistant/thread`

`DELETE /v1/web/assistant/thread`

Tools

Read tools

Proposal tools

The `reply` tool

What the assistant cannot do

Redis keys

Limits

Related pages