> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/ai/snapfix-ai.md).

# Snapfix AI

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/snapfix-ai.md).
{% endhint %}

**Snapfix AI**, also called **Simon**, is a chat assistant for one **site**, in the web app and both mobile apps. People type, or speak in the apps, a question about the site's **tasks**, rooms and documents, or ask it to create tasks. It answers in text, offers chips and questions, shows **task cards** for the tasks it prepares or creates, and cites the site's **documents**, which open at the cited page. It shows only on sites where Snapfix AI is switched on. Production runs an older Simon agent than the v2 agent most of the code describes; this page describes today's product against production, and marks what is known only from the v2 code \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

## Rules

### Which Simon runs

* Production (`ai-agent.snapfix.com`) runs the older agent. It serves the saved chats, the list of a user's chats, jobs, feedback and the brand-standards documents ([AI API: Simon versions](https://docs.snapfix.com/engineering-reference/api/ai.md), [Calls only production serves](https://docs.snapfix.com/engineering-reference/api/ai.md#calls-only-production-serves)) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* The v2 agent runs only on the test host. It lacks the chat list, a saved chat's turns and the document routes, so once it replaces production, iOS will start a new chat at every open, Android's restored chat will come back empty, and document cards and the viewer will stop working.
* Rules below marked "v2" come from the v2 code; production's version of them was not read \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

### Who can use it

* Snapfix AI shows for a site whose switch (`fAiAgentEnabled`) is on. The web also hides it while a multi-site is selected. No code in the repos turns the switch on, the staff admin app included \[[ASK-181](https://github.com/snapfix/docs/blob/main/ASK.md#ask-181-who-switches-snapfix-ai-and-snapfix-recommends-on-for-a-site)] ([Snapfix AI: Who](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md)).
* Every signed-in member of such a site can use it; no role changes it. Simon acts on the Snapfix APIs as the signed-in user, so what it reads and changes follows that user's rights ([Snapfix AI](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md)).
* v2: the agent itself never reads the switch, and its check that the user belongs to the site is skipped while the site's details are cached or when the lookup fails. It reads the user from the sign-in token without checking its signature. A user without access gets a generic error that offers a retry ([`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)).
* Debug builds show it on every site: iOS only in the simulator, Android in every debug build.

### Chatting

* On open, the web restores the browser tab's chat for the site, iOS restores the site's newest chat and loads older messages as the user scrolls, and Android keeps the chat while the app runs and restores its recent turns after a restart. With nothing to restore, the apps ask Simon for starter chips ([Snapfix AI: Actions](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#actions)) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* When no starter chips arrive, the web shows four built-in topics, iOS five English prompts, one of which sends "Something else..." as a message, and Android none. Under the greeting, every site gets "How can I assist with today's housekeeping operations?" \[[ASK-188](https://github.com/snapfix/docs/blob/main/ASK.md#ask-188-should-snapfix-ais-empty-screen-ask-about-housekeeping-on-every-site)], and the greeting's hours differ by platform.
* A message is typed text; the message box is off while a reply streams. No app limits the length; v2 refuses a message over 4,000 characters ([Snapfix AI: Inputs](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#inputs)).
* In the apps, holding the microphone turns speech into text on the phone, and the text is sent when the user lets go; no audio reaches Snapfix. On iOS the recognition may run on Apple's servers ([Snapfix AI: Inputs](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#inputs)).
* No platform sends photos or files: the web's and iOS's attach controls are commented out. Android's question card has a camera that adds a placeholder picture that is never sent.
* Each message tells Simon where the user is: the site, and the group, task or building in view ([Snapfix AI: Actions](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#actions)).
* Simon can ask several questions in a card; "Send" posts all the answers in one turn. iOS shows "submit clarification" as the user's message, and its retry drops the answers ([Question card](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#question-card)).
* v2: Simon prepares a change, such as a new task, and makes it only after the user confirms. Its iOS starter-chip dismissal runs and saves a model turn.
* Answers show in the user's language when the site's AI translation switch (`fAiLanguageTranslationEnabled`) is on, with "See original" to go back ([Snapfix AI: Actions](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#actions)).

### Cards in an answer

* Task cards show each task's group, room, area, priority, assignee and status. Created tasks have "View Task", and several have "View All {N} Tasks" ([Cards in an answer](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#cards-in-an-answer)).
* Document cards name each cited document, with "View document". Production sends them; the v2 agent sends none \[[ASK-180](https://github.com/snapfix/docs/blob/main/ASK.md#ask-180-which-service-indexes-and-serves-the-brand-standards-documents-and-does-it-check-the-callers-site-and-group)]. Both apps label every card "PDF".
* "View document" opens [Source document](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md) at the cited page when the page is reliable, else at the first page. iOS also jumps to a page the server marks as a guess.
* Each platform sends only the selected site when it asks for a document, and none checks the document's site or group itself; whether production's document service does is open \[[ASK-180](https://github.com/snapfix/docs/blob/main/ASK.md#ask-180-which-service-indexes-and-serves-the-brand-standards-documents-and-does-it-check-the-callers-site-and-group)] ([Source document: Access](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md#access)).

### New chat, retry and errors

* "Refresh" on the web and "New chat" on Android delete the chat on the server without asking. The iOS refresh icon starts a new chat and leaves the old one on the server. What the button should do is open \[[ASK-184](https://github.com/snapfix/docs/blob/main/ASK.md#ask-184-what-should-snapfix-ais-refresh-button-do)].
* "Close" keeps the chat.
* A failed reply shows an error under the user's message, with a retry when the server marks the error retryable. The web also offers it after every HTTP failure, including requests that can't succeed. iOS hides the server's reason for three error codes, the usage limit among them ([Snapfix AI: States](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#states)).
* v2: a site and a user can each have a monthly token budget, and a turn past it stops with the server's usage-limit message; with no budget set there is no limit \[[ASK-182](https://github.com/snapfix/docs/blob/main/ASK.md#ask-182-what-monthly-snapfix-ai-budgets-apply-and-who-sets-them)].
* v2: every turn is saved, and only a delete removes a chat; nothing deletes chats by age \[[ASK-183](https://github.com/snapfix/docs/blob/main/ASK.md#ask-183-how-long-should-snapfix-ai-keep-chats)].

### First-run tour

* People whose `showAiAgentTooltip` flag is 1 get a short tour: three steps on the web and iOS, two tips on Android. The web clears the flag on the server when the tour ends, and the apps when the first tip shows ([First-run tour](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#first-run-tour)).

### Data and providers

* v2: each turn, its recent history, the data Simon reads and document passages go to OpenAI, and the apps never name the provider \[[ASK-177](https://github.com/snapfix/docs/blob/main/ASK.md#ask-177-do-the-customer-terms-cover-sending-task-text-photos-recordings-and-chats-to-ai-providers)].
* iOS prints the streamed answers to the device log in every build.
* No plan limit applies in the client code.

## Flow

```mermaid
flowchart TD
  button["Snapfix AI button"] --> on{"Site switch on, and on the web no multi-site?"}
  on -- no --> none["No button"]
  on -- yes --> open["Open: restore the saved chat, or starter chips"]
  open --> send["Type, speak or tap a chip"]
  send --> reply["Reply streams: text, chips, questions"]
  reply -- "questions" --> card["Question card: answers sent in one turn"]
  card --> reply
  reply -- "tasks" --> tasks["Task cards: View Task"]
  reply -- "cited documents" --> doc["View document: the cited page"]
  reply -- "failure" --> err["Error, retry when offered"]
  open -- "Refresh or New chat" --> reset["Web and Android delete the server chat; iOS starts a new one"]
```

## Platforms

| Capability                 | Web                                                                                                                                             | iOS                                                                                                                                                                                        | Android                                                                                                                                                                                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Where it opens             | A side panel, on every page                                                                                                                     | A card, from the main screens, Home, the chat tab and the task page                                                                                                                        | A sheet, from the group list and a group's task list                                                                                                                                             |
| Restore on open            | The browser tab's chat \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] | The site's newest chat, with older messages on scroll \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; none on v2 | In memory while the app runs, recent turns after a restart \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; empty on v2 |
| Voice                      | No                                                                                                                                              | Hold the microphone                                                                                                                                                                        | Hold the voice button                                                                                                                                                                            |
| Photos and files           | No                                                                                                                                              | No                                                                                                                                                                                         | No; a placeholder on the question card                                                                                                                                                           |
| Built-in starter chips     | Four, translated                                                                                                                                | Five, English                                                                                                                                                                              | None                                                                                                                                                                                             |
| Refresh or new chat        | Deletes the server chat                                                                                                                         | Keeps the server chat                                                                                                                                                                      | Deletes the server chat                                                                                                                                                                          |
| Document viewer            | A full page; a message and "Download" for other files                                                                                           | A sheet; an empty sheet for other files                                                                                                                                                    | A screen; other files go to another app                                                                                                                                                          |
| Error text from the server | Always shown                                                                                                                                    | Hidden for three codes                                                                                                                                                                     | Shown for errors that are not retryable                                                                                                                                                          |
| Translation                | Yes                                                                                                                                             | Yes                                                                                                                                                                                        | Yes                                                                                                                                                                                              |

## Screens

* [Snapfix AI](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md): the panel, card or sheet, the question card and the tour.
* [Source document](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md): the viewer behind "View document".

## API and data

* [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream): one turn, streamed as [Simon stream events](https://docs.snapfix.com/engineering-reference/api/ai.md#simon-stream-events).
* [`GET /simon/messages`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonmessages): a page of a chat's messages, for the web and iOS. [`GET /simon/session/{session_id}`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonsessionsession_id): the web's check and Android's restore. [`DELETE /simon/session/{session_id}`](https://docs.snapfix.com/engineering-reference/api/ai.md#delete-simonsessionsession_id): the web's "Refresh" and Android's "New chat".
* `GET /simon/sessions` (iOS) and `GET /brand-standards/documents/{id}` (all three) are served by production only ([Calls only production serves](https://docs.snapfix.com/engineering-reference/api/ai.md#calls-only-production-serves)). The web's job and feedback calls are defined and never made \[[ASK-185](https://github.com/snapfix/docs/blob/main/ASK.md#ask-185-should-the-snapfix-ai-job-and-feedback-calls-be-built-or-removed)].
* The tour flag: [`PUT /v1/app/user`](https://docs.snapfix.com/engineering-reference/api/account.md#put-v1appuser) on the web, `save_pri_user_v7` in the apps ([Users API](https://docs.snapfix.com/engineering-reference/api/users.md)). Translations: [Reference API](https://docs.snapfix.com/engineering-reference/api/reference.md).
* Tables: the switches are in [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md). v2 keeps chats and usage in its own database (`simon_messages`, `simon_usage`, `simon_budgets`); the staging `ai_agent_*` tables, such as [`ai_agent_messages`](https://docs.snapfix.com/engineering-reference/db/tables/ai_agent_messages.md), are read by no repo \[[ASK-179](https://github.com/snapfix/docs/blob/main/ASK.md#ask-179-which-database-does-snapfix-ai-use-in-production-and-are-the-ai_agent_-tables-still-used)].

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md): the tasks Simon reads and creates, and the task cards that open them.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): the group, room and building context of a question.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md) and [Site switching](https://docs.snapfix.com/product/features/groups/site-switching.md): the site the chat belongs to; the web loads the new site's chat after a switch.
* [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md): a separate AI feature for new tasks, with its own switch.
* The Simon host \[[ASK-8](https://github.com/snapfix/docs/blob/main/ASK.md#ask-8-confirm-the-environments)] and the AI provider behind it \[[ASK-177](https://github.com/snapfix/docs/blob/main/ASK.md#ask-177-do-the-customer-terms-cover-sending-task-text-photos-recordings-and-chats-to-ai-providers)].

## Edge cases

* **Switch off:** no button and no message.
* **Several sites:** the web hides the button while a multi-site is selected; switching site stops the reply and loads that site's chat.
* **Usage limit reached:** the web and Android show the server's message; iOS shows only "Couldn't generate a response.".
* **Expired sign-in:** Android refreshes it once and resends; when that fails, "Your session expired. Please sign in again." ([Snapfix AI: States](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md#states)).
* **Offline:** iOS shows "Something went wrong" with a retry; Android shows its error under the message, or "Couldn't reach Snapfix AI. Check your connection and try again." as a toast, and "Connection lost. Please check your internet." for voice.
* **Document errors:** the web tells "no access" from "not found"; the apps show one generic message.
* **Accessibility:** some iOS and Android buttons have no label, or the wrong one, for screen readers.
* **Time zones:** the greeting follows the device's hour.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/ai/snapfix-ai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
