sg-groundtruth 0.1.0__tar.gz

sg_groundtruth-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.env.local
+__pycache__/
+*.pyc
+.venv/
+.schema-cache/
+*.local.json
+.DS_Store
+.idea/
+.vscode/
+corpus.local/
+.playwright-mcp/
+node_modules/
+.svelte-kit/
+site/build/
+dist/
+*.egg-info/
+
+# No longer written: the default lives in site/vite.config.js so a fresh clone builds unconfigured.
+site/.env
+
+# Stray screenshots
+/page.png
+
+# Live status icons, fetched at build time from the configured site (site/scripts/
+# fetch-status-icons.mjs). Never committed: the sprite is the vendor's artwork, and the
+# deploy fetches its own copy from the env vars set on Vercel.
+site/static/status-sprite.png
+site/src/lib/content/status-icons.json

sg_groundtruth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Sallee and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sg_groundtruth-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: sg-groundtruth
+Version: 0.1.0
+Summary: Thin Flow Production Tracking REST client, and an MCP server for the recorded-behaviour corpus that documents it
+Project-URL: Homepage, https://github.com/ksallee/sg-groundtruth
+Project-URL: Source, https://github.com/ksallee/sg-groundtruth
+Project-URL: Issues, https://github.com/ksallee/sg-groundtruth/issues
+Author: Kevin Sallee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autodesk,flow-production-tracking,mcp,shotgrid,shotgun,vfx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# SG Ground Truth
+
+Recorded behaviour of the Flow Production Tracking REST API.
+
+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.
+
+## 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 |
+| `INDEX.md` | generated. Read this first |
+
+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` |
+
+## 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](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 |
+
+## Licence
+
+[MIT](LICENSE). 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.

sg_groundtruth-0.1.0/README.md

@@ -0,0 +1,114 @@
+# SG Ground Truth
+
+Recorded behaviour of the Flow Production Tracking REST API.
+
+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.
+
+## 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 |
+| `INDEX.md` | generated. Read this first |
+
+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` |
+
+## 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](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 |
+
+## Licence
+
+[MIT](LICENSE). 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.

sg_groundtruth-0.1.0/corpus/endpoints/README.md

@@ -0,0 +1,17 @@
+# Endpoint cards
+
+One card per REST call, named by the call. The card holds what is true of the endpoint rather than of a
+data type or an entity type: what it takes, what it answers, what a real response looks like, and the
+edge cases that live on the call.
+
+It does not restate a finding. Every finding and recipe names its `endpoints:`, and the index and the
+site render those verdicts under the card, so the quirks are on the page without being written twice.
+
+`endpoint:` is the canonical spelling and the identity. `<type>` is the plural URL segment, `<Type>` the
+schema name, `<id>` a row id, `<field>` a field name.
+
+Every card states `coverage:`: `measured` when every call on it was made and answered, otherwise
+`partial` or `untested` with an `unmeasured:` line saying what was not reached. A card is the unit a
+docs sweep adds, so it is written before anything has been probed and the key is what keeps that
+visible. The index and the site badge anything that is not `measured` and repeat the reason on the
+row and on the page.

sg_groundtruth-0.1.0/experiments/run3/README.md

@@ -0,0 +1,14 @@
+# Run 3
+
+The grading material and the seed inventory are deliberately **not here** while the run is in progress.
+
+Arm a is given the whole repository, including `probes/`, the schema inspector, the MCP server and the
+slash commands, because that is what someone who clones this actually has. An answer key stored inside
+the repository would be part of what that arm can read.
+
+During the run they live in `~/dev/run3-grading/`, which no arm can reach: arm a is scoped to this
+repository, arms b and c are scoped to their own directories. They come back here with the result.
+
+`experiments/weekly-report/` stays where it is. It records a previous run and names several of the same
+traps. Arm a can read it, and a person who cloned this repository could too, so that is a real advantage
+rather than a leak. `RESULT.md` has to say whether arm a used it.

sg_groundtruth-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sg-groundtruth"
+version = "0.1.0"
+description = "Thin Flow Production Tracking REST client, and an MCP server for the recorded-behaviour corpus that documents it"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kevin Sallee" }]
+keywords = ["shotgrid", "shotgun", "flow-production-tracking", "autodesk", "vfx", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://github.com/ksallee/sg-groundtruth"
+Source = "https://github.com/ksallee/sg-groundtruth"
+Issues = "https://github.com/ksallee/sg-groundtruth/issues"
+
+[project.scripts]
+sg-groundtruth-mcp = "sg_groundtruth.mcp:main"
+
+# The wheel is the client and the tools, never the corpus. The corpus is read from a clone, because
+# every entry names the probe that produced it and re-running that probe is the point; a corpus
+# frozen into a release is one nobody can check. `mcp.py` says so when it cannot find one.
+[tool.hatch.build.targets.wheel]
+packages = ["src/sg_groundtruth"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/sg_groundtruth", "README.md", "LICENSE"]