ChatMaestro · Scenarios · Admin & system

Inspect Embeddings

Admin  Check what is registered for embedding, whether it is covered, and whether the queue is healthy.
Screen  Embeddings embeddings-setup.html
Reads  what gets embedded embedding_ingest_registrythe vectors embeddingthe queue embedding_job
Key fields  which table source_schema · source_tablewhat text to embed text_templatehow to split it chunking_policywhat to carry along filter_columnsswitched on? is_activejob health status · attempts · error

1 · Given / When / Then

Human wording first; the exact table/field in mono.
Given
The signed-in person is an admin. Embedding is registry-driven: a row in embedding_ingest_registry declares that a given table should be embedded, and how.
When
On the Embeddings Screen they review the registry: which tables are registered, the text_template that composes the text, the chunking_policy, the filter_columns carried onto each vector, and whether the entry is_active. They then check coverage and the health of the embedding_job queue.
Then
Reading changes nothing. Re-queueing a stuck job sets its status back to pending; the worker picks it up, replaces that source row's embedding rows, and finishes at done.
reads embedding_ingest_registry, embedding, embedding_job  writes embedding_job.status when re-queued
Variations and exceptions
If…Then…
A registry entry is set to is_active = falseNew work stops; the rule and the vectors already built stay.
Source rows have no embedding rowsRetrieval silently misses them — the coverage view exists to make that visible.
A job keeps failingIt shows a rising attempts and a stored error instead of retrying forever in silence; re-queueing sets it back to pending.
The text_template or chunking_policy is changedExisting vectors were built under the earlier rule and match the new one only after a re-embed.
Acceptance test — Given a failed embedding job, When the admin re-queues it, Then its status returns to pending and on success reaches done with that source row's embedding rows replaced, not duplicated.

2 · The Journey, Screen by Screen

Registry → coverage → queue health.
Open the embeddings page Embeddings Screen See what's registered embedding_ingest_registry Check coverage embedding rows per source Check the queue embedding_job: pending / failed Re-queue anything stuck status → pending, attempts++ retrieval is trustworthy

3 · In Plain English

Retrieval only works if the material was actually turned into vectors. This screen exists so that this is checkable rather than assumed.

What gets embedded is not hard-coded. A registry says: this table, composed into text this way, split this way, carrying these extra fields for filtering. Turn an entry off and new work stops without destroying what is there.

Two failure modes are worth watching: gaps, meaning source rows nothing was ever built for, and stuck jobs. Both are shown rather than hidden, and a stuck job records how often it tried and what the error was, so you are diagnosing rather than guessing.

If in doubt you can always rebuild. The vectors are derived from the source text, so re-embedding costs time and nothing else.

Fits the schema cleanly. The embedding_job state machine is drawn in Ingest a document; this scenario is the operational view over it. embedding is derived data: losing it costs compute, never information.