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 an entry only when its one-liner falls short.

corpus/INDEX.md is generated: 67 KB, one line per entry with its verdict and its tags. The corpus behind it is much larger, and an agent that loads all of it spends its context on the first call.

An agent with no clone fetches the same files off the site. .md appended to any entry or section URL returns the markdown that page was built from, frontmatter included, and /llms.txt is one line per entry with its verdict and the URL of its markdown.

https://sg-groundtruth.vercel.app/llms.txt                      44 KB, every entry, one line each
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/

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.

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.

Scopes

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

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

Branches

A release to PyPI is a published GitHub release, cut from main, and only when the package itself changed. The corpus changes far more often than the client does.

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.