Word Graph

Word graph

Language: English · 简体中文

The Word Graph reveals shared vocabulary across a bounded sample of Wiki Pages and Sources. If Page A and Page B both contain a selected term, the graph connects both documents through that term node.

It is a discovery view, not a corpus-wide word index and not a semantic graph. A shared word proves sampled occurrence only; it does not prove equivalence, causality, or dependency.

When to use it

Use the Word Graph when a focused search finds several documents and you need to see:

• which vocabulary connects the result set;
• which Pages and Sources share a product name or technical term;
• which document deserves full inspection next;
• whether a mixed Chinese and English vocabulary cluster exists in the sample.

Skip it for a known Page or Source, an exhaustive frequency study, or code structure. Use Page/Source reads, external analysis, or CodeGraph instead.

Why it never loads all words

Token density grows much faster than document count. Building a browser graph for every token in a real Wiki would consume excessive database time, response bytes, layout work, and memory while producing an unreadable hairball.

LWC uses a query-first bounded pipeline:

focused query
    -> FTS candidate selection
    -> one page of documents
    -> bounded metadata and passage samples
    -> shared-term selection
    -> bounded term-document graph

The full vocabulary is never returned. Pagination changes the document sample instead of expanding one unbounded graph.

Fixed server-side budgets

Budget	Maximum
Searchable query terms	8
Documents per sample page	25
Selected terms	30
Passage samples per document	4
Inspected text across the sample	4 MiB
Nodes	200
Edges	500
Pagination offset	10,000
Metadata sample per document	16 KiB

Requests above supported document, term, or offset limits are clamped and reported through truncation_reasons. Empty queries and queries with more than eight searchable terms are rejected.

These limits are correctness contracts, not UI suggestions. A client must not try to bypass them by issuing an all-corpus request.

How the sample is built

1. LWC tokenizes the focused query with the same deterministic search rules used by the Wiki.
2. Indexed Page and Source candidates are selected by FTS rank, with stable type and identifier tie-breakers.
3. At most 25 documents are retained for the requested offset.
4. For each document, LWC inspects bounded title, summary, and path metadata plus at most four active passage spans.
5. Query terms present in the sample are retained first.
6. Additional terms must occur in at least two sampled documents. They are ordered by sample document frequency, then sample occurrences, then lexical order.
7. SAMPLE_CONTAINS edges connect selected terms to sampled documents and report sample occurrences.

This process is deterministic for the same canonical Wiki state, query, limits, and offset.

Use the Viewer

Start the local read-only Viewer:

lwc --scope project view

Use --no-open when browser launch is unwanted:

lwc --scope project view --no-open --port 0

Open Word graph, enter a focused query with at most eight searchable terms, and submit it. The graph stays empty until a query is submitted.

Use Previous and Next to inspect another bounded 25-document sample. Do not interpret a later page as an extension of one global graph; each page is its own sample window.

Read the response honestly

The response includes:

• normalized query_terms;
• document and term nodes;
• SAMPLE_CONTAINS edges with sample occurrence counts;
• has_more for another document page;
• truncated and truncation_reasons;
• enforced limits;
• diagnostics for inspected documents, spans, bytes, and tokens.

Common truncation reasons include document pagination, requested-limit clamping, metadata or byte budgets, selected-term limits, and edge limits. They describe the sample boundary; they are not errors to suppress.

Read-only API

The Viewer uses a bounded GET endpoint:

/api/graphs/words?query=projection&limit=25&term_limit=30&offset=0

The endpoint is read-only. It does not enable the document graph, build a CodeGraph index, refresh Sources, or mutate Wiki content. Unsupported write methods are rejected.

Interpretation rules

• Open the full Page or Source before promoting a visible relationship to a durable claim.
• A high sample occurrence count is not a corpus-wide frequency.
• A missing term may have fallen outside the selected sample, passage, byte, term, or edge budget.
• CJK and Latin tokens follow deterministic LWC tokenization; they are not dictionary-derived concepts.
• Use explicit document-graph relations only after evidence proves a semantic relationship.

Completion evidence

A Word Graph investigation is complete when:

• the query is focused and within eight searchable terms;
• the enforced limits and offset are recorded;
• pagination was used instead of requesting the whole corpus;
• has_more, truncation reasons, and diagnostics were considered;
• important connections were verified against full documents;
• sampled co-occurrence was not misreported as semantic fact.

Next: Tags and strong context