Public preview — bilingual README + hero GIF + reproducible demo/eval#1
Merged
Conversation
The dogfooding CLI now prints which chat provider/model, embedding provider/model and graph backend are actually live, so screencasts and bug reports are unambiguous about the runtime under test. - CliRunner: extend the startup banner with Active profiles, Chat provider/model, Embedding provider/model, Graph DB. - RuntimeConfigReporter: new ApplicationRunner that logs the same resolved configuration at INFO level on startup (useful when running --mode=server or under spring-boot:run without the CLI). No domain or core changes. graph-rag-core: 65/65 tests still green.
New playbook 'sample-graph-v2-design.md' captures the Round 7 review outcome for the next-iteration sample graph: - Hard-locks scope to graph-rag-examples/ only. No enum or interface changes to graph-rag-core / starter; every new business relation is mapped onto an existing STRUCTURAL_TYPES value. - 12-node / 14-edge ceiling, with a regression / rollback / acceptance checklist so the upgrade can be reverted by deleting one fixture folder. - Conditionally gated: v2-mini only starts AFTER Round 7-8 prompt / judge tuning if L3 uplift is still < +1.0. Avoids burning open source readiness on speculative graph complexity.
Round 7.1 closes the 'manual GIF' gap left by Round 7. The demo is now a real local Ollama recording that anyone can reproduce. - demo-side-by-side.gif (820 KB, 1320x1100, 60 s): a single DAU question answered in --variant=both mode. PLAIN and GRAPH blocks are visible in the same frame; the GRAPH answer carries an explicit '(Graph lineage: DAU --[FORMULA_USES]--> New Users, DAU --[FILTERS_BY]--> active_days_dim)' trail so viewers can see what graph context buys over prose. - demo.tape: charmbracelet/vhs script. Dracula theme, 1320x1100, hides 28 s JVM warm-up, gives a 55 s answer window, then exits. - run-cli.sh: launcher used by the tape. Pre-built fat jar, --mode=cli --variant=both, port 8088 (avoids 8080 collisions), jar-existence check + friendly error message. Reproduce with: mvn -pl graph-rag-examples -am -DskipTests package brew install vhs vhs docs/assets/demo.tape
Public-facing copy now matches what the repo actually ships. README: - Front page embeds docs/assets/demo-side-by-side.gif directly (replacing the prior placeholder + ASCII mock-up). Caption is honest about what the GIF shows and links to the reproduction recipe. - 'Record the demo GIF yourself' section compressed from a 6-step manual procedure to a 3-line 'brew install vhs && vhs docs/assets/demo.tape' recipe; over-claim warnings retained. - Eval headline reflects the latest local Ollama run: L3 plain 2.50 vs graph 3.00 (delta +0.50), overall 2.80 vs 3.00 (delta +0.20). NORTH_STAR target of L3 >= +1.0 is still tracked honestly as 'not yet'. STATUS: - Round bumped 7 -> 7.1. Release-prep gap shrinks from 3 items to 2 (G1 'record demo GIF' moved from Human-pending to done). - Test baseline reaffirmed at 65 green tests in graph-rag-core. CHANGELOG (Unreleased): - New 'Side-by-side dogfooding GIF' and 'Repo-tracked recording recipe' entries under Round 7 + 7.1 'Added'. - Note clarifies Round 7 touched no production code; Round 7.1 added only docs assets and runtime banner copy. ROUNDS: - Appended full Round 7.1 entry: tool selection (vhs over asciinema/agg), question choice (q1 over q5 so PLAIN+GRAPH fit one frame), geometry tuning (1320x1100 / 13 pt), JVM warm-up hidden, rejected alternatives (composite GIF, sticking with spring-boot:run, outsourcing to Human), and ported pitfalls (missing 'timeout' on macOS, orphan ports, transient ttyd failure, Sleep 38 s too short).
Real user (Human reviewer) hit:
mvn -pl graph-rag-examples -am spring-boot:run ...
-> 'Unable to find a suitable main class' on the root graph-rag-harness pom
Root cause: with '-am' Maven adds every dependency module AND the root
pom to the reactor, and 'spring-boot:run' is a directly invoked plugin
goal that fires on every reactor project regardless of packaging. The
root project is packaging=pom with no main class, so the build dies on
module #1 and everything downstream is SKIPPED. The same '-am' with
'package' or 'compile' is safe because those lifecycle phases are
no-ops on pom modules.
Changes:
- README 'Run the side-by-side dogfooding CLI': split into a one-time
'install upstream modules' step (which needs -am) + a plain
'spring-boot:run on graph-rag-examples' step (which must NOT have
-am). Also points readers at the pre-built fat-jar route as an
even simpler alternative.
- README 'Run the evaluation harness': same two-step recipe, with
the fat-jar one-liner inline.
- New README 'Troubleshooting' section: documents the failure mode,
the cause, both safe fixes, and the orphan-port cleanup recipe.
- CONTRIBUTING 'Validation checklist': mirrors the install + run
split for the smoke-test command.
- PITFALLS.md: new P-005 entry capturing symptom / root cause / fix /
how-to-avoid for permanent retention.
- CHANGELOG (Unreleased): one-line note under Round 7 + 7.1 'Added'.
No production code changed. graph-rag-core: 65/65 tests still green.
…her path Polish the GitHub-facing README so it works for both English and Chinese readers and stops shipping known-stale snippets: - New README.zh.md: full Chinese translation, 1:1 section structure (13 ## sections, same code blocks). Pure translation — same Quick Start / Troubleshooting / eval table as the English version, just in 中文 with language-appropriate explanation tone. - Both READMEs get a language switcher at the very top so readers can flip between EN/中文 without scrolling. - Replaced the 'OWNER/REPO' placeholder badge block with a real CI badge pointing at MarcelLeon/graph-rag-harness Actions; the project already has .github/workflows/ci.yml so this badge is honest. - Fixed a stale path: the recording recipe used to say it 'runs /tmp/run-cli.sh', but the wrapper has been in the repo at docs/assets/run-cli.sh since Round 7.1. README now points at the in-repo path that the demo.tape actually invokes. CHANGELOG (Unreleased) updated with one bullet covering the bilingual README + badge/launcher fix. No production code changed. graph-rag-core: 65/65 tests still green.
Hero GIF (homepage, slow-network friendly): - New docs/assets/demo-short.gif (553 KB / ~27 s / 1240x760), variant=graph, real local Ollama, one short DAU question. Shows graphContext + FORMULA_USES / FILTERS_BY / SOURCE_TABLE relations + explicit Graph lineage trail. Replaces the 820 KB / 60 s demo-side-by-side.gif at the top of README / README.zh.md; the longer GIF is kept as 'extended demo' linked just below the hero. - New docs/assets/demo-short.tape (vhs script) reproduces it; trailing Sleep tuned to 23 s after first attempt truncated the answer at 18 s. - run-cli.sh: now honors VARIANT= env (default 'both') so the same launcher is reused by both the short tape (VARIANT=graph) and the extended tape. Status wording: 'public alpha' -> 'public preview' (more accurate given L3 +0.50 vs target +1.0). Replaced in: - README.md / README.zh.md (status badge URL, body sentence, milestone caption) - SECURITY.md (project state) - CONTRIBUTING.md (project state) The R6 'Public alpha polish' CHANGELOG heading is intentionally kept as historical record. Journal: STATUS.md bumped to R7.2, CHANGELOG Unreleased section extended with hero-GIF + wording bullets, ROUNDS.md appended with R7.2 entry (including rejected alternatives: variant=both at 25 s, 1.5x playback speed, deleting the old 60 s GIF).
MarcelLeon
changed the title
Owner
Author
|
approved |
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
1 participant
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.
Summary
This PR opens the project for public preview — the demo runs end-to-end, the eval is real, and the docs (now bilingual) explain how to reproduce everything in 5 minutes.
It promotes 9 commits worth of pre-release work from
init-pull-requestintomaster. There are no production-code changes that touch the dependency-graph engine: every commit is indocs/,graph-rag-examples/, journal files, or new assets (GIFs, tapes, launchers).What changed since the last
masterRuntimeConfigReporter— at startup the CLI prints active model, provider, graph backend, so the GIF self-documents the config.qwen3:8b+nomic-embed-textOllama recording (docs/assets/demo-side-by-side.gif, ~820 KB / 60 s), reproducible viadocs/assets/demo.tape+docs/assets/run-cli.sh. Kept as extended demo.docs/assets/demo-short.gif(553 KB / ~27 s /--variant=graph). Sits at the top of README / README.zh.md so first-time visitors on slow networks see graphContext + Graph lineage trail in <1 s.README.zh.md(full 1:1 Chinese translation, language switcher in both files). Fixed CI badge (realMarcelLeon/graph-rag-harnessworkflow) and a stale/tmp/run-cli.shpath.-am + spring-boot:runtrapmvn ... package, then plainspring-boot:runwithout-am).public alpha→public preview(more accurate given current L3 +0.50 vs target +1.0). Historical R6 CHANGELOG heading kept as-is.docs/playbooks/sample-graph-v2-design.md— zero-invasion conditional-GO design for the optional bigger sample graph (kept as a design fixture, not implemented).Verification
JAVA_HOME=$JAVA17_HOME mvn test -pl graph-rag-core -q→ 65/65 green at HEAD.Graph lineage:three lines, Confidence 1.00 all rendered before exit.STATUS.md,CHANGELOG.md,docs/journal/ROUNDS.mdare in sync; no AI-introduced// TODO.Out of scope (deliberately)
Self-checklist (per
AGENTS.md)@Disabled/@IgnoreGraphDatabaseClient)Noop*Impldeleted// TODOfor unresolved blockers