SG Ground Truth

Recorded behaviour of the Flow Production Tracking REST API.

sg-groundtruth.vercel.app renders every entry on this page, and pip install sg-groundtruth gets the client that measured them.

The REST documentation is incomplete and in places wrong. Every entry here is what a live Flow PT site answered when a probe asked it one question: the status code, the error string, the response shape, in the words the API used. The 51 probes that produced it are in this repository and run against any site.

Read it

git clone https://github.com/ksallee/sg-groundtruth

Then give an agent one line:

Read sg-groundtruth/corpus/INDEX.md first.
Open the door it names for the rules, and an entry only when a rule needs its evidence.

corpus/INDEX.md is generated and capped at 8 KB: every entry by name, and which door answers the thing you already know. A door under corpus/doors/ carries one line per entry and that entry's rules, copied whole, 2 to 36 KB a file. The entry holds the transcript, the sample and the tables. An agent that loads the corpus instead spends its context on the first call.

An agent with no clone fetches the same three tiers off the site. /llms.txt is the map, in the same words, with a URL in place of every name. .md appended to any door, entry or section URL returns the markdown that page was built from, frontmatter included.

https://sg-groundtruth.vercel.app/llms.txt                      24 KB, the map
https://sg-groundtruth.vercel.app/doors/field_types.md          29 KB, one door
https://sg-groundtruth.vercel.app/findings.md                   one section
https://sg-groundtruth.vercel.app/findings/026_result_order.md  4 KB, the file itself

The rendered page costs eleven bytes of markup per byte of finding. The twin costs none.

What is in corpus/

directory	holds
endpoints/	64 cards, one per REST call: what it takes, every status code it answers with, a recorded response
findings/entity_types/	17 cards, one per schema name: identity, the create contract, every link field, the status field
findings/field_types/	24 cards, one per data_type: what it reads, writes and clears as, and what filters it
findings/	40 questions, each answered by one probe, grouped by the phase of a session they bite in
recipes/	11 tasks, each with the calls that perform it, the real response, and the errors hit on the way
reports/	9 behaviours that should change, written for the team that owns the API: expected, actual, a runnable repro, and the proposed fix
INDEX.md	generated, 8 KB. Read this first
doors/	generated. One line per entry and its rules, between the map and the entries

Four ways in, one per thing a caller already knows before making a call: the call itself, the entity type, the field's data_type, or the task.

Why it exists

A 400 names the legal set and an agent recovers from it. A 200 that ignored what you sent teaches it nothing. Each row is a published finding.

you do this	this happens
Sort on a misspelled field	200. The sort is ignored, rows come back id ascending, and nothing says so
Page until links.next is absent	It is never absent. It is emitted on zero-row pages too. Stop when data is empty
Create rows in a batch	You get an id per row. A batch can return an id for a row it never made
Create a field whose display name is taken	201. You got <name>_1

Call the API with it

pip install sg-groundtruth

FPT is the client every probe here calls the API through, so what the corpus records is what it does. 75 lines, requests and nothing else.

from sg_groundtruth.client import FPT

fpt = FPT.from_env()                  # FPT_API_SITE_URL, _SCRIPT_NAME, _API_KEY
page = fpt.get("/entity/versions")    # the parsed body: data, links

get, post, put and delete take a path and pass every other keyword to requests, so params, json and files work as they do there. A non-2xx raises FPTError with the body intact.

The wheel is the client and the tools, never the corpus: clone the repository for that.

Mount it over MCP

PYTHONPATH=src python -m sg_groundtruth.mcp

Five tools, stdio, standard library only, so mounting it costs nothing beyond the clone. PYTHONPATH is not optional: the package is not installed. Registration for Claude Code and any other stdio client is in docs/mcp.md.

It answers what the API does. A Flow PT MCP server calls the API. An agent given both has to be told which is which.

Put your own site in it

The corpus covers any Flow PT site. One command measures yours: your custom entities, your field names, your status vocabularies, your projects.

cd sg-groundtruth
claude

Then ask for /sg-groundtruth-setup. Start the agent inside the clone: the command is one of this repository's own and is registered when the session starts.

Writes to your site	Nothing, unless a probe is run with --write
Project it may write into	The sandbox you name, and no other
Where your data goes	corpus.local/, gitignored, never leaves your machine

Scopes

Every entry declares one, because a measurement that is true of one site is not a fact about the API.

scope	true of	committed
api	Any Flow PT site: status codes, error strings, value shapes, operator vocabularies	Yes
site	One site: which custom entities are enabled, which fields exist, valid_values	Only when scrubbed
project	One project inside it: hidden_values, page columns, fill rates	No

valid_values is byte-identical at every scope and only hidden_values varies by project, so "which statuses can I use" has no site-level answer. That is why the last two are not one scope (probe 009).

Probes

python probes/017_filter_operators.py

One question per probe. A probe prints what the API answered and deletes anything it created before it exits; it never writes the corpus. An agent reads the output and writes the entry. Every entry names the probe that produced it, so a claim you doubt, you re-run.

Read-only by default. A write needs --write, and the only project a probe may write into is the sandbox named in .env.local.

Layout

path
corpus/	the corpus. scope: api, committed, the product
probes/	the scripts that produced it, plus check_corpus.py and index.py
src/sg_groundtruth/	the MCP server, the schema inspector, the client
site/	SvelteKit, prerendered static, renders the corpus and any local overlay
docs/	MCP registration, the example overlay, unverified operator claims
corpus.local/	your own site, written by the setup command. Gitignored

Branches

branch
dev	where work lands. Branch from it, and open the pull request against it
main	what a clone gets and what the site deploys from. dev merges here when it is ready

Every merge into main is tagged. Two families, because the corpus changes far more often than the client does:

tag	when	ships
corpus/<YYYY-MM-DD>	any merge into main	nothing. A date to compare against confirmed: and a Flow PT release
v<version>	[project].version in pyproject.toml changed	PyPI, through a published GitHub release on that tag

A tag alone publishes nothing: release.yml fires only on a published release.

Licence

MIT. Nothing AGPL enters this repository, at any depth. It is derived only from the public Flow PT REST documentation and this repository's own probes, so that studio legal can say yes without reading anything.