Insight dashboards

“How many works, how many copies, which ones never go out”: the question comes up in every module, with the same screen shape. A row of cards, a clickable table below. The kernel provides the screen; your module provides the numbers.

from kewos.insights import (
    InsightCard, InsightColumn, InsightRow, InsightsState,
    has_insights_provider, register_insights_provider,
)


class TitleInsights:
    def state(self, session, classes) -> InsightsState:
        title = classes["library_title"]
        titles = list(session.execute(select(title).order_by(title.name)).scalars())
        return InsightsState(
            title="insights.library.title",
            cards=(
                InsightCard(key="titles", label="insights.library.titles", value=str(len(titles))),
            ),
            columns=(InsightColumn(key="name", label="library_title.name"),),
            rows=tuple(
                InsightRow(record_id=int(t.id), cells={"name": t.name}) for t in titles
            ),
        )


def register_library_insights() -> None:
    if not has_insights_provider("library_title"):        # boot re-imports
        register_insights_provider("library_title", TitleInsights())

One generic endpoint serves all of it:

GET /api/v1/insights/library_title

{"title":"insights.library.title",
 "cards":[{"key":"titles","value":"8"},{"key":"copies","value":"8"},
          {"key":"orphans","value":"1","token":"destructive"}],
 "columns":[{"key":"name","label":"library_title.name","kind":"text"}, ...],
 "rows":[{"record_id":2,"cells":{"name":"A Brief History of Time","copies":1}}, ...]}

No screen is written. Labels are i18n keys, columns carry a kind (text, progress, badge) that picks the cell renderer, and record_id turns every row into a link to the record. A model with no provider answers 404: the surface invents nothing.

The trap: a filtered number is not a wrong number, but your sentence can be

The session you receive is the filtered session. It shows only what the caller may see, which is exactly what you want for a count. But a conclusion drawn from two counts can become a lie.

The provider above counts works, counts copies, and derives the works “with no copy”. Run by two users against the same database:

manager :   8 works,  8 copies,  1 with no copy
visitor :   8 works,  0 copies,  8 with no copy

The visitor may read the catalogue, not the copies. Both of their counts are correct. The sentence built from them is false: those eight works do have copies, the visitor cannot see them. And the card is red, which makes a missing number look like a problem.

Two ways out, to be chosen deliberately:

• do not derive: show what you count, not what you conclude from it;
• restrict the dashboard to a role that sees all the data it depends on, and say so in the model’s permissions instead of hoping.

What you must never do is bypass the filtered session to “get the real number”: that would reveal through an aggregate what the list refuses to show.

Four of the product’s modules ship an insights provider: learning, the sales pipeline, e-signature and marketing.