On this page

SystemDocumentView
- SystemDocumentView

SystemDocumentView

Receive this surface through md.architecture and md.components; use that owning object's public entry point.

Implementation source

class SystemDocumentView(entry: Mapping[str, object])[source]

Indexed, sliceable view over one shipped system document.

Purpose:: Give an agent a document it can interrogate rather than a document it must consume. Every read is bounded and every bound is stated up front by index().
Contract:: Immutable and shared. Section lookup is exact by key; find() covers the substring case. Slicing an unavailable document raises rather than returning empty text, because a silent empty slice reads exactly like a section that genuinely says nothing.

_document: The underlying StaticSystemDocument.

_entry: That document's manifest entry.

_sections: Ordered sections; non-None only after the key map is published.

_by_key: Key -> section, for exact lookup.

AGENT_ACCESS: public

AGENT_PURPOSE:: access: public. What melder.__architecture__ and __components__ return. Ask index() or groups() what is here and what each piece costs, search(needle) which sections discuss a term, then get(key) for one slice or reader()/stream() when a section is itself too large. cite(key) gives a ready-to-use document:start-end. verify() re-checks the shipped bytes. Slicing a document that failed its build-time proof RAISES rather than returning empty.

property name: str: Return the melder document name, e.g. __architecture__.

property document_name: str

Return the melder document name.

Contract:: Alias of name, kept because callers written against StaticSystemDocument already use it. The view now stands where the carrier used to, so it answers to both.

property title: str: Return the human-readable document title.

property summary: str: Return what this document is for, in one paragraph.

property source: str: Return the repository path this document was captured from.

property addressing: str

Return how sections are keyed.

Returns:

section when keys are heading paths, source_path when: keys are repository-relative file paths. Determines what a caller should pass to get().

Return type:

str

property available: bool

Return whether this document shipped with content.

Purpose:: False means the source pair failed its staleness proof at build time or was absent. reason says which. An unavailable document is NOT an empty document, and the distinction is the whole point: empty invites invention, refused does not.

property reason: str: Return why an unavailable document is unavailable, else empty.

property line_count: int: Return the document's line count as recorded by its index.

property content_sha256: str: Return the SHA-256 the index claimed for this document.

property char_count: int

Return the document's character count.

Contract:: Needs the text, so this materialises the payload. line_count comes from the manifest and does not.

render_markdown() → str[source]

Return the ENTIRE document as one string.

Purpose:: The unbudgeted escape hatch, kept because tooling that converts or re-emits a document legitimately needs all of it.
Contract:: No budget. For __graph_details__ this is megabytes in one value. An agent answering a question wants index() then get(); this is for machines, not for reading.

Returns:: The full document text.
Return type:: str
Raises:: RuntimeError -- When the document is unavailable.

render_json() → str[source]

Return the document's minified JSON hardcopy envelope.

Contract:: Synthesised on first call and cached on the carrier - the payload ships as a plain string literal, so no envelope exists until something asks for one. Same unbudgeted caveat as render_markdown().

Returns:: {"m": <markdown>}, minified.
Return type:: str
Raises:: RuntimeError -- When the document is unavailable.

index() → Tuple[Section, ...][source]

Return every section, in document order.

Purpose:

THE entry point for a lookup document. An agent calls this to see what can be asked and what each answer costs in lines, then calls get() or reader() for the one it wants.

For __architecture__ this is a table of contents, not a substitute for reading it - orientation does not come from two sampled sections.

Returns:: Ordered sections.
Return type:: Tuple[Section, ...]

keys() → Tuple[str, ...][source]: Return every section key, in document order.

find(needle: str) → Tuple[Section, ...][source]

Return sections whose key contains needle, case-insensitively.

Purpose:: Exact keys are long - a full heading path, or a full source path. An agent that knows it wants "conduit" should not have to reconstruct src/melder/aether/conduit/conduit.py to ask.
Contract:: Substring match on the key only, never on body text; a body search would mean reading the whole document, which is the cost this object exists to avoid. Document order is preserved, so for source_path addressing a directory prefix returns a subsystem's files contiguously.

Parameters:: needle -- Substring to look for.
Returns:: Matching sections, possibly empty.
Return type:: Tuple[Section, ...]

search(needle: str, *, limit: int = 25, preview_chars: int = 120) → Tuple[SearchHit, ...][source]

Return sections whose BODY mentions needle, ranked by hit count.

Purpose:

The one query find() cannot answer. find() matches section KEYS, which is useless for "where is thread safety discussed" - the concept lives in the prose, not in a heading. Without this an agent's only recourse is pulling a whole document and grepping, which for a document this size costs orders of magnitude more than the answer and defeats the entire design.

Contract:

Returns SECTIONS, never text - the result stays index-shaped, so a caller still chooses what to open. A line inside nested sections is attributed to the MOST SPECIFIC one containing it, because "Indexing > Verifying citations" is a more useful answer than "Indexing".

Costs one payload load and one pass over the document, measured at 4-8 ms on the largest documents here. That is real but it is paid once per process; the alternative is paying it in context, every time, forever.

Case-insensitive substring matching. Not tokenised - "thread" matches "threading", which for a code corpus is usually wanted.

Parameters:

needle -- Text to look for.
limit -- Maximum sections to return, highest hit count first.
preview_chars -- How much of the first matching line to include.

Returns:

Matching sections, most hits first, ties: broken by document order.

Return type:

Tuple[SearchHit, ...]

Raises:

RuntimeError -- When the document is unavailable.
ValueError -- When needle is empty - an empty needle matches every line and would return the whole index dressed as a result.

groups(depth: int = 3) → Tuple[Group, ...][source]

Return the index collapsed to one row per prefix.

Purpose:

index() on __graph_details__ is 575 rows - roughly 11k tokens, enough that an agent reaching for it first has already spent more than most answers are worth. This is the cheap overview that says where to drill: ~40 rows instead of 575.

Contract:

For source_path addressing, groups by the first depth path segments. For section addressing, by the first depth heading levels. Ordered by first appearance, so the grouping reads in document order rather than alphabetically.

DEPTH IS THE DIAL, and the default is deliberately shallow. This repo's tree runs eight segments deep in places; grouping at full directory depth gives 157 rows, which is a smaller cliff rather than no cliff. Start shallow, then re-group deeper on the branch you care about, or expand it with find(prefix).

Parameters:: depth -- How many path segments or heading levels to keep.
Returns:: One row per prefix.
Return type:: Tuple[Group, ...]
Raises:: ValueError -- When depth is below 1.

section(key: str) → Section[source]

Return one section by exact key.

Parameters:: key -- An exact key from keys().
Returns:: The addressed span.
Return type:: Section
Raises:: KeyError -- When the key is not in the index. The message offers the closest find() matches, because these keys are long enough that a near miss is the likely failure.

get(key: str) → str[source]

Return the full text of one section.

Purpose:: The target slice. This is the normal way to read a section that fits in one look; use reader() when it does not.

Parameters:

key -- An exact key from keys().

Returns:

The section's lines, joined.

Return type:

str

Raises:

KeyError -- When the key is not in the index.
RuntimeError -- When the document is unavailable, so a refused document can never be mistaken for an empty one.

cite(key: str, *, line: int | None = None) → str[source]

Return a document:start-end citation for a section.

Purpose:: This repository cites evidence as path:start_line-end_line. The numbers are already in the index, but formatting them by hand on every claim is exactly the kind of friction that ends with an agent citing nothing.

Parameters:

key -- An exact section key.
line -- Optional single line to cite instead of the whole span - pass a SearchHit.first_line to cite the match rather than the section containing it.

Returns:

e.g. src_graph.md:3518-3596, or src_graph.md:4752.

Return type:

str

Raises:

KeyError -- When the key is not in the index.

reader(key: str | None = None, *, line_target: int = 50, char_target: int = 8192) → AgentTextReader[source]

Return a private cursor over one section, or the whole document.

Purpose:: A section is not automatically small - the graph document's largest runs to hundreds of lines. This gives the same bounded, resumable read at section scale that the document-level reader gives at document scale, so there is no size at which the caller is forced back to a raw string.
Contract:: The cursor is the caller's alone; the indexed text behind it is shared and never copied. Positioned at the section's first line and NOT bounded at its last - a caller may read past the end into the following section, which is deliberate: sections are adjacent context, not walls.

Parameters:

key -- Section to start at, or None to start at the document's top.
line_target -- Lines per read, 2-100.
char_target -- Characters per read; whichever binds first wins.

Returns:

A cursor owned solely by the caller.

Return type:

AgentTextReader

Raises:

KeyError -- When the key is not in the index.
RuntimeError -- When the document is unavailable.
ValueError -- When a budget is outside ReaderPolicy bounds.

stream(key: str, *, line_target: int = 50, char_target: int = 8192) → Iterator[TextChunk][source]

Yield one section in bounded chunks, stopping at its end.

Purpose:: The generator form the reader does not give on its own: reader() runs to the end of the DOCUMENT, this stops at the end of the SECTION. An agent asking for one section wants one section.
Contract:: Chunks never extend past the section's last line; the final chunk is trimmed to fit. Lazy - nothing is read until iterated, and abandoning the generator costs nothing.

Parameters:

key -- An exact key from keys().
line_target -- Lines per chunk, 2-100.
char_target -- Characters per chunk.

Yields:

TextChunk -- Successive spans of the section.

Raises:

KeyError -- When the key is not in the index.
RuntimeError -- When the document is unavailable.

head(lines: int = 50) → TextChunk[source]: Return the document's opening lines.

tail(lines: int = 50) → TextChunk[source]: Return the document's closing lines.

verify() → bool[source]

Re-check the shipped text against the proof its index claimed.

Purpose:: The build verified the source pair. This verifies the SHIPPED payload, which is a different claim - it catches a corrupted wheel, a bad merge into a generated module, or a hand-edit of emitted code. A range from an unverified index is a guess wearing a line number; this is the refusal that prevents it, in-process.
Contract:: Recomputes the SHA-256 of the payload. Costs a full hash of the document, so it is a deliberate call, never implicit on read.

Returns:

True when the payload matches its recorded digest. Always: False for an unavailable document - there is nothing to verify.

Return type:

bool

Topic reference · Full contents