> 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/engineering-reference/db/tables/viewpoint-17.md).

# Ai tables

{% hint style="info" %}
Generated from the staging database schema, with descriptions drafted by agents ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/db/tables/viewpoint-17.md).
{% endhint %}

## Description

Snapfix AI and AI suggestions: agent sessions and messages, brand documents, task insight and title-style data, token usage, the AI job log and queue.

## Tables

| Name                                                                                                                                        | Columns | Comment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Type       |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| [ai\_agent\_feedback](https://docs.snapfix.com/engineering-reference/db/tables/ai_agent_feedback.md)                                        | 16      | One rating a user gave a Snapfix AI agent answer, thumbs up or down or 1 to 5 stars, with an optional comment, the chat session and the command type. No in-scope repo reads or writes it, though it has rows \[[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), [ASK-244](https://github.com/snapfix/docs/blob/main/ASK.md#ask-244-which-service-writes-the-ai-agent-and-brand-document-tables-and-in-what-time-unit)].                    | BASE TABLE |
| [ai\_agent\_messages](https://docs.snapfix.com/engineering-reference/db/tables/ai_agent_messages.md)                                        | 10      | One message of an AI agent chat, by the user or the assistant. No repo reads or writes it; snapfix\_ai\_agent keeps Simon's chat turns in its own table simon\_messages, which the staging schema does not have \[[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)].                                                                                                                                                                         | BASE TABLE |
| [ai\_agent\_sessions](https://docs.snapfix.com/engineering-reference/db/tables/ai_agent_sessions.md)                                        | 12      | One Snapfix AI agent chat session of a user on a site, with its title, a short snippet and a message count. No in-scope repo reads or writes it, though it has rows \[[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), [ASK-244](https://github.com/snapfix/docs/blob/main/ASK.md#ask-244-which-service-writes-the-ai-agent-and-brand-document-tables-and-in-what-time-unit)].                                                              | BASE TABLE |
| [ai\_brand\_document\_permissions](https://docs.snapfix.com/engineering-reference/db/tables/ai_brand_document_permissions.md)               | 8       | One grant on a brand-standards document (document\_uuid) to one principal, with a permission level. No in-scope repo reads or writes it \[[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), [ASK-244](https://github.com/snapfix/docs/blob/main/ASK.md#ask-244-which-service-writes-the-ai-agent-and-brand-document-tables-and-in-what-time-unit)].                                                                       | BASE TABLE |
| [ai\_brand\_documents](https://docs.snapfix.com/engineering-reference/db/tables/ai_brand_documents.md)                                      | 21      | One brand-standards document for Snapfix AI, with its file name, S3 key and indexing status. No in-scope repo names the table; on staging all rows but one are copies of compliance documents (source comply) \[[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), [ASK-244](https://github.com/snapfix/docs/blob/main/ASK.md#ask-244-which-service-writes-the-ai-agent-and-brand-document-tables-and-in-what-time-unit)]. | BASE TABLE |
| [ai\_task\_insight\_sync\_checkpoint](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_insight_sync_checkpoint.md)          | 5       | One watermark of aitask\_pyserver's assignee-insight seeder: how far it has read tPri\_Job, either for one group (uuid\_tParent empty) or for one site (parent mode, uuid\_tBusiness empty). Every staging row is a per-site watermark.                                                                                                                                                                                                                                                                                                                  | BASE TABLE |
| [ai\_task\_title\_style\_profile](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_title_style_profile.md)                  | 5       | One style profile of a site's task titles, which aitask\_pyserver builds from the site's human-written titles for its AI title suggestions. Empty on staging; the service reads it only when title style learning is on, and that setting is off by default.                                                                                                                                                                                                                                                                                             | BASE TABLE |
| [ai\_task\_title\_style\_sync\_checkpoint](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_title_style_sync_checkpoint.md) | 4       | One watermark per site for rebuilding its title style profile, written by aitask\_pyserver's title style seeder. Empty on staging, like the profile table.                                                                                                                                                                                                                                                                                                                                                                                               | BASE TABLE |
| [ai\_task\_user\_activity](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_user_activity.md)                               | 4       | One user's newest task chat message time and newest sign-in time, which aitask\_pyserver's assignee suggestions pass to the model.                                                                                                                                                                                                                                                                                                                                                                                                                       | BASE TABLE |
| [ai\_task\_user\_job\_resolution](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_user_job_resolution.md)                  | 7       | One finished (green) task, with its title, the user who finished it and how long it took, for aitask\_pyserver's assignee suggestions.                                                                                                                                                                                                                                                                                                                                                                                                                   | BASE TABLE |
| [ai\_task\_user\_outstanding](https://docs.snapfix.com/engineering-reference/db/tables/ai_task_user_outstanding.md)                         | 4       | Number of a user's assigned tasks in one group (uuid\_tBusiness) that are not green yet, for aitask\_pyserver's assignee suggestions.                                                                                                                                                                                                                                                                                                                                                                                                                    | BASE TABLE |
| [ai\_token\_usage](https://docs.snapfix.com/engineering-reference/db/tables/ai_token_usage.md)                                              | 26      | One AI call (translation, tag, room, area, title, group, assignee or Simon) with its provider, model, tokens, cost and outcome. api\_php\_live\_v2 writes the translation calls and aitask\_pyserver the others; rows keep request and answer text with no retention.                                                                                                                                                                                                                                                                                    | BASE TABLE |
| [log\_ai\_job](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md)                                                      | 11      | One AI suggestion event on a task, by category, with the suggested value or the value the user chose instead; aitask\_pyserver reads the title rows to learn title style.                                                                                                                                                                                                                                                                                                                                                                                | BASE TABLE |
| [queue\_ai](https://docs.snapfix.com/engineering-reference/db/tables/queue_ai.md)                                                           | 10      | One php-apis AI run that creates, and then assigns, housekeeping tasks for a site, with its stage and progress. Empty on staging.                                                                                                                                                                                                                                                                                                                                                                                                                        | BASE TABLE |
| [tag\_vision\_job](https://docs.snapfix.com/engineering-reference/db/tables/tag_vision_job.md)                                              | 10      | Unused. Links one image analysis (tag\_vision) to one task; no rows on staging and only its migration names it \[[ASK-242](https://github.com/snapfix/docs/blob/main/ASK.md#ask-242-can-the-unused-copy-and-scratch-tables-be-dropped)].                                                                                                                                                                                                                                                                                                                 | BASE TABLE |

## Relations

```mermaid
erDiagram


"ai_agent_feedback" {
}
"ai_agent_messages" {
}
"ai_agent_sessions" {
}
"ai_brand_document_permissions" {
}
"ai_brand_documents" {
}
"ai_task_insight_sync_checkpoint" {
}
"ai_task_title_style_profile" {
}
"ai_task_title_style_sync_checkpoint" {
}
"ai_task_user_activity" {
}
"ai_task_user_job_resolution" {
}
"ai_task_user_outstanding" {
}
"ai_token_usage" {
}
"log_ai_job" {
}
"queue_ai" {
}
"tag_vision_job" {
}
```

***

> Generated by [tbls](https://github.com/k1LoW/tbls)


---

# 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/engineering-reference/db/tables/viewpoint-17.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.
