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
Copy link
Copy Markdown
Sorry, something went wrong.
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
Copy link
Copy Markdown
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 --publish CLI flag and plumbs it through the flow to trigger publishing after tutorial generation.
- Adds utils/uq_publish.py to build/write a generic@1 graph and optionally dispatch a registry sync event when UNDERSTAND_QUICKLY_TOKEN is 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.
Sorry, something went wrong.
Comment thread
utils/uq_publish.py
Outdated
Comment on lines
+4
to
+5
| (nodes = chapters, edges = chapter relationships) and, if a token is set, | ||
| fires a `repository_dispatch` at the registry. |
Comment thread
utils/uq_publish.py
Outdated
| "label": abstr.get("name", f"abstraction {i}"), | ||
| "kind": "abstraction", | ||
| "description": abstr.get("description", ""), | ||
| "files": list(abstr.get("files", [])), |
Comment thread
utils/uq_publish.py
Outdated
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 thread
utils/uq_publish.py
Outdated
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"), |
Comment thread
README.md
Outdated
|
|
||
| ## 📡 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 thread
tests/test_uq_publish.py
Outdated
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.
Copy link
Copy Markdown
Author
|
Addressed @copilot review feedback:
|
Sorry, something went wrong.
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-quickly is a public registry of code-knowledge graphs that ships an MCP server and a stable registry.json API. 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 --publish flag 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.
What changes
When --publish is set, after the existing markdown tutorial is written:
Diff stats
The utils/uq_publish.py module is self-contained and only loaded when --publish is set (lazy import inside CombineTutorial.post).
No-op default
Without --publish, behavior is identical to today — no extra files, no new code paths. With --publish but no UNDERSTAND_QUICKLY_TOKEN, only the local tutorial.json is 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:
The recommended CI step is the looptech-ai/uq-publish-action@v0.1.0 Marketplace Action:
Schema fit
generic@1 only requires nodes and edges arrays, so the chapter/abstraction shape lands today with no schema PR. If you'd later prefer a richer tutorial@1 schema (chapter ordering, prerequisite edges, source-file citations), the registry has a format-authoring path.
Test plan
Notes
Links
Current live state (sweep 2026-05-11)
The registry and its publishing surface are tagged and live:
Nothing in this PR depends on any pre-release surface — all referenced artifacts are pinned versions.