Read the runtime's own documentation

Prerequisite: ordinary Python and the Melder vocabulary. The installed package carries addressable documentation objects:

Object	Start with
`md.__architecture__`	System boundaries and execution flow
`md.__components__`	Component responsibilities and source locations
`md.__graph_network__`	Nodes, edges, traversal, and impact
`md.__graph_details__`	Detailed descriptions joined to the network

Address before reading

Check available, reason, and addressing. Survey with keys(), groups(), or index(), narrow with find() or search(), then read one section with get(key) or reader(key). Return a cite(key) address when another reader needs to verify it. verify() checks the shipped content against its recorded digest.

For a traceback, the graph lesson starts with node_at(source_path, line), then walks relationships and requests impact. Authored and derived edge provenance answer different questions; retain that distinction when interpreting the graph.

From map to implementation

The documents identify where to look. Read the relevant source before changing runtime behavior; a useful map still describes the revision that produced it. For source-controlled human diagrams, continue to Architecture & Drawings.

The workflow in code

These are the core steps from the saved example. Use its complete linked script for all class definitions and setup.

def main() -> None:
    # THESE ANSWER AT IMPORT. Nothing conjured, no Aether call made.
    for name in PROSE_DOCS + GRAPH_DOCS:
        view = getattr(md, name)
        assert view.document_name
        print(f"{name:<20} -> {type(view).__name__:<20} "
              f"available={view.available}")
    print()
    print("four documents, queryable with no Spellbook and no Conduit")

    architecture = md.__architecture__
    if not architecture.available:
        print("__architecture__ did not ship:", architecture.reason)
        print("  note it still ANSWERS - refused is not missing")
        return

    # 1. WHAT DO KEYS MEAN HERE? Ask before addressing.
    print()
    print("addressing:", architecture.addressing,
          f"  ({architecture.line_count} lines,",
          f"{architecture.char_count} chars)")

    # 2. THE CHEAP SURVEY. Keys and group rollups cost no document text.
    keys = architecture.keys()
    assert len(keys) > 0
    print()
    print("keys():", len(keys), "sections; first three:")
    for key in keys[:3]:
        print("   ", key)

    rollup = architecture.groups(1)
    print("groups(1):", len(rollup), "prefixes; first:",
          rollup[0].prefix, f"({rollup[0].sections} sections,",
          f"{rollup[0].line_count} lines)")

    # 3. THE INDEX IS SPANS, NOT PROSE. Sizing before reading, per section.
    sections = architecture.index()
    assert len(sections) == len(keys)
    biggest = max(sections, key=lambda s: s.line_count)
    print()
    print("index(): largest section is", biggest.key)
    print(f"   lines {biggest.start_line}-{biggest.end_line}"
          f" ({biggest.line_count} lines)")

    # 4. FIND ADDRESSES, SEARCH INVESTIGATES. Different questions.
    hits = architecture.search("melder", limit=3)
    print()
    print("search('melder'): top", len(hits), "by hit count")
    for hit in hits:
        print(f"   {hit.hits:>4} hits  line {hit.first_line:<6} {hit.key}")

    # 5. NOW PAY FOR ONE SECTION - and only one.
    target = keys[0]
    section = architecture.section(target)
    body = architecture.get(target)
    assert section.key == target
    assert isinstance(body, str)
    print()
    print(f"get({target!r}) -> {len(body)} chars,"
          f" {section.line_count} lines")

    # 6. A CITATION AN AGENT CAN HAND BACK. Falsifiable, unlike a summary.
    print("cite:", architecture.cite(target))
    print("cite(line=...):",
          architecture.cite(target, line=section.start_line))

    # 7. THE CURSOR IS SCOPED TO A SECTION, which is why narrowing first
    #    means never paging the document.
    reader = architecture.reader(target, line_target=20)
    chunk = reader.read()
    print()
    print("reader(key).read() ->", chunk.end_line - chunk.start_line,
          "lines, has_more =", chunk.has_more)
    print("  a cursor over ONE SECTION, not over the document")

    # 8. THE INTEGRITY GATE. The shipped text is checked against the
    #    digest its own index claimed.
    verified = architecture.verify()
    assert isinstance(verified, bool)
    print()
    print("verify() ->", verified,
          " sha:", (architecture.content_sha256 or "")[:12], "...")
    print("  an unavailable document answers False - nothing to check -")
    print("  and still reports `available` and `reason` rather than")
    print("  vanishing, because a gap invites an agent to invent")

    # 9. THE GRAPH DOCUMENTS ARE THESE PLUS NODES AND EDGES.
    graph = md.__graph_network__
    assert isinstance(graph, type(architecture)) or True
    print()
    print("__graph_network__ is a", type(graph).__name__,
          "- a document view PLUS:")
    if graph.available:
        print("   nodes:", graph.node_count, " edges:", graph.edge_count)
        print("   relations:", list(graph.relations)[:4])
        node_ids = graph.node_ids()
        if node_ids:
            first = node_ids[0]
            print("   node_ids()[0] ->", first)
            print("   details_key ->", graph.details_key(first))
    else:
        print("   did not ship:", graph.reason)

    print()
    print("survey with keys/groups, narrow with find/search, then pay")
    print("for one section - and answer with a citation, not a summary")

Runnable examples

The package reads itself to you — Expert 18
The codebase as a walkable graph — Expert 19
Protocol crafter the tool that writes — Expert 05

All expert examples · Level contents · Full contents

Canonical page source