Learning Helper¶

This graph turns three course sources into a Word handbook. By the end of the page, you will understand human scope selection, three-way parallel processing, a join, coverage review, and conditional rendering with ordinary Slots and Rules.

The live path requires a working Codex executor, document-generation tools, and the OCR environment declared by the case.

Complete graph definition¶

The page embeds the configuration used by the case. You can also download the raw YAML.

version: 1
project:
  name: learning-helper
  default_targets: [handbook]
slots:
  knowledge: { kind: file, path: inputs/Knowledge.md }
  examples: { kind: file, path: inputs/Examples.md }
  expansion: { kind: file, path: inputs/Expansion.md }
  scope_prompt: { kind: file, path: fixtures/scope.md }
  docx_builder: { kind: file, path: build-docx.sh }
  scope: { kind: file, path: scope.md }
  knowledge_distillation: { kind: file, path: distillations/Knowledge.md }
  examples_distillation: { kind: file, path: distillations/Examples.md }
  expansion_distillation: { kind: file, path: distillations/Expansion.md }
  template: { kind: file, path: template.md }
  conclusion: { kind: file, path: conclusion.md }
  draft: { kind: file, path: draft.md }
  coverage: { kind: file, path: coverage.json }
  handbook: { kind: file, path: handbook.docx }
rules:
  - id: choose_scope
    in: [scope_prompt]
    out: [scope]
    run: { using: human, command: "Confirm the course scope from this exact file" }
  - id: distill_knowledge
    in: [scope, knowledge]
    out: [knowledge_distillation]
    permissions: { network: none, secrets: [] }
    run:
      using: codex
      model: gpt-5.6-luna
      reasoning_effort: none
      command: >-
        Read in/scope and in/knowledge. Produce a concise teaching distillation
        in out/knowledge_distillation. Preserve definitions and equations,
        explain why each idea matters, and do not invent facts or write other
        paths.
  - id: distill_examples
    in: [scope, examples]
    out: [examples_distillation]
    permissions: { network: none, secrets: [] }
    run:
      using: codex
      model: gpt-5.6-luna
      reasoning_effort: none
      command: >-
        Read in/scope and in/examples. Write out/examples_distillation as a
        compact worked-example section. Retain concrete steps and answers,
        connect them to the requested scope, and write no other path.
  - id: distill_expansion
    in: [scope, expansion]
    out: [expansion_distillation]
    permissions: { network: none, secrets: [] }
    run:
      using: codex
      model: gpt-5.6-luna
      reasoning_effort: none
      command: >-
        Read in/scope and in/expansion. Write out/expansion_distillation with
        useful extensions, caveats, and connections, grounded only in the
        supplied source. Write no other path.
  - id: build_template
    in: [scope]
    out: [template]
    run: "printf '# Learning Handbook\n\nScope is revision-bound.\n' > out/template"
  - id: build_conclusion
    in: [scope]
    out: [conclusion]
    run: "printf '## Conclusion\n\nEvery source contributes to the synthesis.\n' > out/conclusion"
  - id: assemble_draft
    in: [template, conclusion, knowledge_distillation, examples_distillation, expansion_distillation]
    out: [draft]
    run: >-
      cat in/template in/examples_distillation in/expansion_distillation
      in/knowledge_distillation in/conclusion > out/draft;
      printf '\nCoverage: complete\nEquation: x^2 + y^2 = z^2\n' >> out/draft
  - id: review_coverage
    in: [draft, coverage]
    out: [coverage]
    when: >-
      test "$(jq -r '.draft_checksum // ""' coverage)" != "$(cksum draft | cut -d' ' -f1)"
    run: >-
      checksum=$(cksum in/draft | cut -d' ' -f1);
      if grep -q 'Coverage: complete' in/draft; then decision=accept; else decision=revise; fi;
      printf '{"decision":"%s","draft_checksum":"%s"}\n' "$decision" "$checksum" > out/coverage
  - id: render_docx
    in: [draft, coverage, scope, docx_builder]
    out: [handbook]
    when: "test \"$(jq -r '.decision' coverage)\" = accept"
    run: "sh in/docx_builder in/draft out/handbook"

What each Slot does¶

Slot	Kind	Role in the graph
`knowledge`	file	Definitions, equations, and core knowledge.
`examples`	file	Worked steps, exercises, and answers.
`expansion`	file	Extensions, caveats, and related ideas.
`scope_prompt`	file	The scope request shown to the person making the decision.
`docx_builder`	file	The script that converts the Markdown draft into DOCX.
`scope`	file	The Human Rule decision read by all three distillation Rules.
`knowledge_distillation`	file	Teaching-oriented treatment of the knowledge source.
`examples_distillation`	file	Teaching-oriented treatment of the examples source.
`expansion_distillation`	file	Teaching-oriented treatment of the expansion source.
`template`	file	Fixed handbook title and opening.
`conclusion`	file	Fixed handbook conclusion.
`draft`	file	The Markdown join of all five content branches.
`coverage`	file	Coverage decision and the checksum of the reviewed draft.
`handbook`	file	The generated Word document.

Each source has a normal Slot and a direct writer. The graph shape is known before execution; no dynamic subgraph is needed.

What each Rule does¶

Rule	Reads	Writes	Work
`choose_scope`	scope_prompt	scope	Asks a person to confirm the course scope.
`distill_knowledge`	scope, knowledge	knowledge_distillation	Preserves definitions and equations and explains why they matter.
`distill_examples`	scope, examples	examples_distillation	Preserves concrete steps and answers as a worked-example section.
`distill_expansion`	scope, expansion	expansion_distillation	Extracts useful extensions and caveats from the supplied source.
`build_template`	scope	template	Creates the fixed title and records that scope is Revision-bound.
`build_conclusion`	scope	conclusion	Creates the fixed ending.
`assemble_draft`	template, conclusion, three distillations	draft	Joins the content and adds a coverage marker and equation.
`review_coverage`	draft, coverage	coverage	Rechecks when the draft checksum changes and writes accept or revise.
`render_docx`	draft, coverage, scope, docx_builder	handbook	Builds the DOCX only when coverage is accepted.

The three distillation Rules share only scope, so the scheduler can run them in parallel. Changing Knowledge.md makes the knowledge branch and its downstream work stale while the other two branches can reuse their Receipts.

Run and inspect it¶

Start with the deterministic contract path.

scripts/test-real-world-cases.sh learning-helper contract

It checks cache reuse, final-output propagation, and selective invalidation after changing one source.

Run the live path after preparing the agent, document tools, and OCR environment.

scripts/test-real-world-cases.sh learning-helper live

Inspect handbook.docx, then change only inputs/Knowledge.md and run again. The Examples and Expansion Receipts should remain reusable.