feat: add --publish flag for understand-quickly registry integration#185
Open
amacsmith wants to merge 2 commits into
Open
feat: add --publish flag for understand-quickly registry integration#185amacsmith wants to merge 2 commits into
amacsmith wants to merge 2 commits into
Conversation
Adds a `--publish` flag (opt-in) that, after tutorial generation, emits
a small `generic@1` knowledge-graph projection of the tutorial
(abstractions as nodes; AnalyzeRelationships output + chapter ordering
as edges) at `<output>/<project>/tutorial.json` with metadata.{tool,
tool_version, generated_at, commit}.
When `UNDERSTAND_QUICKLY_TOKEN` is set, also fires a
`repository_dispatch` at `looptech-ai/understand-quickly` so the
registry resyncs the entry. Without the token, only the local file is
written — no network call, no failure.
New module `utils/uq_publish.py` is stdlib-only (urllib, subprocess,
json) — no new dependencies. Includes two unit tests using stdlib
`unittest`.
Spec: https://github.com/looptech-ai/understand-quickly/blob/main/docs/spec/code-graph-protocol.md
Action: https://github.com/looptech-ai/uq-publish-action
There was a problem hiding this comment.
Pull request overview
Adds an opt-in --publish integration that emits a generic@1 knowledge-graph JSON alongside the generated tutorial and (optionally) triggers an understand-quickly registry resync via GitHub repository_dispatch.
Changes:
- Introduces
--publishCLI flag and plumbs it through the flow to trigger publishing after tutorial generation. - Adds
utils/uq_publish.pyto build/write ageneric@1graph and optionally dispatch a registry sync event whenUNDERSTAND_QUICKLY_TOKENis set. - Adds README docs + basic unit tests for graph generation and the “no token” publish path.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
utils/uq_publish.py |
Implements graph projection, file writing, and optional GitHub dispatch to the registry. |
nodes.py |
Calls the publish logic in CombineTutorial.post when publish_to_uq is enabled. |
main.py |
Adds --publish flag and stores it in shared state (publish_to_uq). |
README.md |
Documents the opt-in publish flow and CI action usage. |
tests/test_uq_publish.py |
Adds unit tests for graph emission and local write without dispatch when token is unset. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+4
to
+5
| (nodes = chapters, edges = chapter relationships) and, if a token is set, | ||
| fires a `repository_dispatch` at the registry. |
| "label": abstr.get("name", f"abstraction {i}"), | ||
| "kind": "abstraction", | ||
| "description": abstr.get("description", ""), | ||
| "files": list(abstr.get("files", [])), |
Comment on lines
+84
to
+87
| "description": abstr.get("description", ""), | ||
| "files": list(abstr.get("files", [])), | ||
| "chapter_index": chapter_order.index(i) if i in chapter_order else None, | ||
| }) |
Comment on lines
+182
to
+191
| repo_slug = _detect_repo_slug(source_dir or Path.cwd(), repo_url) | ||
| if not repo_slug: | ||
| print("[uq-publish] could not detect github repo slug — skipping dispatch.", | ||
| file=log) | ||
| return {"dispatched": False, "metadata": metadata} | ||
|
|
||
| try: | ||
| status = dispatch( | ||
| repo_slug, token=token, schema=graph.get("schema", "generic@1"), | ||
| graph_path=str(output_path), commit=metadata.get("commit"), |
|
|
||
| ## 📡 Publish to understand-quickly (opt-in) | ||
|
|
||
| Add `--publish` to land the generated tutorial in [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly), a public registry of code-knowledge graphs that ships an MCP server. The flag emits a small `generic@1` JSON projection of the tutorial (chapters as nodes, relationships as edges) at `<output>/<project>/tutorial.json` with `metadata.{tool, tool_version, generated_at, commit}`. If `UNDERSTAND_QUICKLY_TOKEN` is set, it also fires a `repository_dispatch` so the registry resyncs the entry. |
Comment on lines
+18
to
+19
| {"name": "Flow", "description": "Pipeline orchestrator", "files": ["flow.py"]}, | ||
| {"name": "Node", "description": "Unit of work", "files": ["nodes.py"]}, |
- Resolve abstraction file indices to repo-relative paths via files_data (passed from shared['files']); fall back to 'file_indices' when absent so consumers don't get raw integers under a 'files' key. - Precompute chapter_index lookup dict to avoid O(n^2) chapter_order.index(). - Dispatch payload sends repo-relative POSIX graph_path; skip dispatch cleanly when the graph isn't inside source_dir. - Clarify module docstring (abstractions/chapters) and README that commit is only populated when a local git repo is available. - Update test fixtures to use integer indices, matching production data.
Author
|
Addressed @copilot review feedback:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
looptech-ai/understand-quicklyis a public registry of code-knowledge graphs that ships an MCP server and a stableregistry.jsonAPI. PocketFlow-Tutorial-Codebase-Knowledge already produces per-codebase knowledge artifacts (abstractions, ordered chapters, relationships) — exactly the producer shape the registry is designed for.Wiring a
--publishflag means any user who generates a tutorial can land in the registry with one flag, and AI agents (Claude, Codex, Cursor via MCP) can discover and consume their tutorial-knowledge graph immediately.output/<project>/; the registry only stores pointers and fetches fromraw.githubusercontent.com.metadata.commitis set), and a turnkey MCP server.What changes
utils/uq_publish.pymodule (stdlib-only —urllib,subprocess,json).--publishflag inmain.py(opt-in).CombineTutorial.post(innodes.py) that, when--publishis set, builds and writes the projection.tests/test_uq_publish.py(uses stdlibunittest, no new test deps).When
--publishis set, after the existing markdown tutorial is written:generic@1JSON projection is built — abstractions become nodes,AnalyzeRelationships.detailsplus the chapter ordering become edges.metadata.{tool, tool_version, generated_at, commit, project_name, repo_url, summary}.<output>/<project>/tutorial.json.$UNDERSTAND_QUICKLY_TOKENis set, fires arepository_dispatchatlooptech-ai/understand-quicklyso the registry's sync workflow re-pulls the entry. If unset, no network call.Diff stats
The
utils/uq_publish.pymodule is self-contained and only loaded when--publishis set (lazy import insideCombineTutorial.post).No-op default
Without
--publish, behavior is identical to today — no extra files, no new code paths. With--publishbut noUNDERSTAND_QUICKLY_TOKEN, only the localtutorial.jsonis written. Failures inside the publish block are caught and logged; tutorial generation never fails because of publish.Token setup
Fine-grained GitHub PAT, single permission:
looptech-ai/understand-quicklyonly.Repository dispatches: write. Nothing else.The recommended CI step is the
looptech-ai/uq-publish-action@v0.1.0Marketplace Action:Schema fit
generic@1only requiresnodesandedgesarrays, so the chapter/abstraction shape lands today with no schema PR. If you'd later prefer a richertutorial@1schema (chapter ordering, prerequisite edges, source-file citations), the registry has a format-authoring path.Test plan
python3 -m unittest tests.test_uq_publish -v— both tests green.python3 -m py_compile main.py nodes.py utils/uq_publish.py— all clean.python main.py --repo <url> --publishwithUNDERSTAND_QUICKLY_TOKENset and the repo registered fires the dispatch and the registry'ssync.ymlruns within ~1 minute.python main.py --repo <url> --publishwith the token unset writesoutput/<project>/tutorial.jsonand prints an informational line; no network call.Notes
The-Pocket/PocketFlow-Tutorial-Codebase-Knowledgeto the verified-publisher allowlist for auto-merge.--publishis governed by the Understand-Quickly Data License 1.0. It is opt-in, gated on the user settingUNDERSTAND_QUICKLY_TOKEN.Links
generic@1schema: https://github.com/looptech-ai/understand-quickly/blob/main/schemas/generic@1.jsonCurrent live state (sweep 2026-05-11)
The registry and its publishing surface are tagged and live:
looptech-ai/understand-quicklyv0.3.0@looptech-ai/understand-quickly-cli@0.1.2on npm@looptech-ai/understand-quickly-mcp@0.1.2on npmunderstand-quickly0.1.1 on PyPIlooptech-ai/uq-publish-action@v0.1.0on the GitHub Marketplaceio.github.looptech-ai/understand-quicklyNothing in this PR depends on any pre-release surface — all referenced artifacts are pinned versions.