The assistant

The assistant is the sparkle button at the bottom right of every view. It is one for the whole installation, governed by a platform admin from the Platform page (/admin), and it is itself a chatty graph: the admin builds it in Studio and measures it in Research like any other.

What it knows

knowledge	how
where you are	every turn carries the session state: route, workspace, research, graph, dataset, job, language
this documentation and the catalogue of views	the docs_search tool, over passages embedded by the platform
what your workspace learned	research_recall over the curated reasoning of your researches
your researches, datasets, jobs, experiments	the platform MCP («Chatty (this platform)»), acting as you

Answers are markdown: documentation is cited as links to the page and section, Python is quoted from the chatty-lab package when code is the better tool, and a view is given as a route you can follow.

Switching it on

1. Pick the platform workspace on the Platform page: the workspace whose keys (or the shared budget) pay for the assistant.

   That workspace may only contain admins, and the rule holds in both directions: you cannot pick a workspace that has non-admin members, and once a workspace is the platform one, nobody can be invited into it — or demoted inside it — as a plain member. It is not an organisational preference: that workspace lends its keys to everyone, and anyone inside it can read them (an HTTP tool that names a secret, an MCP server with its environment). A plain member there would hold the same access as an admin without anyone deciding it.

2. Press Create the reference graph. That creates, in the platform workspace, an agent «Chatty assistant» with docs_search, research_recall and the platform MCP, and a graph input → template → sub_agent → output around it; the graph is chosen and the assistant is switched on. The same press files that graph as the repository of a research called Assistant in the platform workspace (adopting it: pressing again finds the same research), and the page offers Open its research. The node that answers exposes its soul and its model as parameters, so an experiment over that research sees them without anyone touching the canvas.

3. Edit it in Studio when you want: the persona, the tools, the shape of the graph. Pressing the button again refreshes the pair back to the reference; copy it under another name first if you want to keep an edit.

4. Choose the model it answers with, under the graph, on this same page. The assistant has no model of its own: it is the model of the agent its graph runs, in the platform workspace, and the list offers what that workspace reaches with its keys or the shared budget. Only an admin changes it, and only here: the bar never offers a model picker. If a node of the graph carries a model of its own (an experiment moving it as a parameter), the page says so, because then the agent’s model is not what that node runs with.

What it can do on your screen

Some things cannot be done by a server: they happen in the browser you are looking at. The assistant asks your browser to do those, and it answers back:

tool	what it does
propose_plan	shows you what it means to do, and waits
navigate	takes you to a view of the app
canvas_read	reads the graph canvas you have open: node ids, types, labels, edges
canvas_seed	puts a whole graph on that canvas at once — every node and every edge
canvas_add_node	adds a single node to that canvas
canvas_connect	connects two of its nodes
canvas_select	selects one, which opens its configuration

Anything that writes is shown to you first. The bar puts up a card saying what it wants to do; nothing happens until you press the button. Reading and navigating do not wait. What it did appears under the answer with a tick, so you can see what changed.

The canvas edits go through the same collaborative document the canvas itself writes to, so they undo with Ctrl+Z, reach anyone else looking at that graph, and are saved like any other edit.

Operations: the plan, and why it is not a formality

Asking for something built — «create a research with a graph that reads this dataset and scores against the reference» — is not one write but eight. Instead of eight cards, the assistant shows you one plan: a line saying what the whole thing does and the steps it will take. You say go ahead once, and the steps run without asking again; what each one did appears under the answer.

Saying nothing yet is a real no. The credential the assistant carries for that turn is minted read only: while no plan is approved, every write it attempts — creating a research, a dataset or a job, running anything, deleting anything — is refused by the platform itself, with a message telling it to propose a plan first. It is not that the assistant has been told to ask; it is that it cannot not ask. Your yes is what opens the credential, for that turn and no further: the next question starts locked again.

Building a graph, it validates before it draws. It composes the nodes and edges, checks them with the platform’s validate_graph (which saves nothing and returns what is wrong), fixes what it says, and only then seeds the canvas — in one go, so you never watch half a graph appear.

Rejecting the plan rejects everything

If you say no, nothing is written, and the assistant is told so. It will offer something else rather than trying anyway — and if it did try, the platform would refuse it.

Only where a browser is

These tools exist only while a browser declares them. The same graph run from Python, from an experiment or from the queue simply does not have them, and the assistant is told so rather than pretending it acted.

Deployments: two versions, half the people each

The assistant answers with the graph as it stands — until you deploy. A deployment says which versions of that graph answer, and with what weight. It is on the Platform page, under the assistant.

1. Mint the versions you want to compare, in Studio, in the platform workspace. Pressing Create the reference graph mints the first one for you; the rest come from editing the graph and committing, like any other graph.
2. Add a variant per version, name each one (A, B, «without docs_search»…) and give it a weight. Two variants with weights 1 and 1 see half the traffic each; 9 and 1 is a careful rollout.
3. Deploy. That closes whatever was deployed before — there is one deployment at a time, because two would be two answers to «which version is answering?».

Who sees which one is not stored. It comes out of a hash of the person and the deployment, so it is the same every time it is asked: a person keeps their variant for as long as the deployment lasts and their thread does not change voice halfway. Changing the split means opening another deployment, which reshuffles everyone — and that is right, since the numbers of a split belong to that split.

Two variants may not point at the same version: the turns are attributed to the version that answered them, so their numbers could not be told apart.

Retire puts it back to the graph as it stands. What was measured stays.

What people said, and what it cost

Every answer in the bar carries a thumbs pair. What a person says is kept with their turn, and the Platform page reads it back per variant: turns, how many were answered, thumbs up and down, how long it took, and what it cost. The cost is not copied into the turn — it is read from the run that produced it, so there is one figure and not two that drift.

Questions to a dataset takes what people actually asked under a deployment and writes it as a dataset in the platform workspace, with the question, the answer that was given, the view they were on, and the thumbs and comment the person left. The dataset is filed in the Assistant research, the one whose repository is the assistant’s graph. That is the first link of the loop the platform measures everything else with: from there, running a version over that dataset is an ordinary experiment with a judge as the score, one experiment per version, and the research shows the versions side by side; comparing what two variants answered to different people is an evaluation job, and the verdict ascends to a finding. Two variants never answer the same question in production, so comparing them properly means asking again.

Measure versions closes that loop from the same page. Tick the versions of the assistant’s graph you want compared, pick one of the datasets filed in its research (the turns you just filed, usually), name the judge’s model and its scale, and press Measure. One experiment per version is created, pinned to that version and to the same snapshot of the dataset, filed in the Assistant research, and launched; the table underneath reads the research back — trials, how many rows answered, the judge’s mean score, and what it cost — one row per version, newest first, refreshing while anything is still running. The judge is the same for every version on purpose: two numbers from two judges are not comparable. Deploying the winner is the deployment block above. The judge’s own tokens are not counted in the trial’s cost.

What usually comes next

Above the input the bar shows up to three next moves: what people who were in this same situation did afterwards. They are suggested before you ask anything — no turn is opened and no model is spent — and tapping one sends it as your question.

What the platform learns from is the shape of a situation, never its contents: the route with the ids stripped out (/research/:id) and the names of the state fields that carried something. No id, no id of a research, and not a word anybody wrote. And a move is only suggested once several different people have made it — the floor is three by default and is the assistant_suggestion_floor setting of the platform workspace. A new installation has three of nothing, which is why the floor can be lowered; lowering it to one means a suggestion can describe what one identifiable person did.

Only moves, never plumbing

The suggestions come from a curated list of actions a person recognises as a next step — start a research, set up an experiment, compare two trials. What the assistant calls to carry them out (searching the docs, validating a graph) is never suggested, and neither is anything destructive: a platform does not suggest deleting because other people deleted.

The assistant can ask the same question itself, with the next_steps tool, when someone asks “what now?” in words.

Starting over

The bar is one thread per person, and it does not expire: what you asked yesterday is part of what the assistant reads before answering today. Start over (the pencil in the bar’s header) draws a line: from there on the assistant neither shows nor reads what came before, and whatever state memory the assistant’s agent had built up for you is forgotten with it. Nothing is deleted — the record of every turn is what the admin’s analytics and the recommender are built on; it simply stops being the conversation.

The documentation index

The pages of this site and the catalogue of views travel inside the backend, one passage per section. Shortly after starting, and every few hours, the backend compares what it carries with what is indexed and writes only what changed, so a deploy with two new pages embeds two pages and nothing else. The Platform page shows the index: pages, passages, how many have a vector, which model embedded them, and Reindex now.

Without an embedding model

The assistant still searches the documentation, by text. Lend an embedding model from the shared budget, or set the platform workspace’s system embedder, and the next pass adds the vectors.

Ceilings and record

Each person gets a number of turns per hour; the installation runs a bounded number of turns at once; a turn is stopped after a few minutes. Every turn is recorded with its session state, the tools it used, the outcome and the latency, and the run’s trace holds the rest — that record is what the admin’s analytics and the recommender are built on.

The thread’s memory key is derived from the graph and the person, so two people are never in the same thread. That matters the moment the assistant’s agent is given any memory strategy other than None: the assistant is one graph for the whole platform, and a key derived from the graph alone would have put everyone’s conversation in one place.