LLB (Large Language Blocks)

A Python library for generating LLM-readable structured context.

Why LLB?

Serialize Python objects (especially graphs) into LLM-friendly text:

• Graph Mode: Nodes + edges with focus/radius context pruning
• Flat Mode: Simple independent block packaging

Installation

pip install llb_doc

Quick Start

Flat Mode - Independent Blocks

from llb_doc import create_llb, parse_llb

doc = create_llb()

# Method 1: Fluent API with builder pattern
doc.block("ticket", lang="en").meta(source="jira", priority="high").content(
    "User cannot upload files larger than 10MB"
).add()

# Method 2: Context manager
with doc.block("api", "json") as b:
    b.meta["source"] = "storage_service"
    b.content = '{"max_size": 5242880, "unit": "bytes"}'

# Method 3: Direct add
doc.add_block("note", "Config mismatch detected", source="code_review", lang="en")

# Render to LLB format
print(doc.render())

# Parse LLB text back to document
doc2 = parse_llb(doc.render())

Output

@block B1 ticket en
source=jira
priority=high

User cannot upload files larger than 10MB

@end B1

@block B2 api json
source=storage_service

{"max_size": 5242880, "unit": "bytes"}

@end B2

@block B3 note en
source=code_review

Config mismatch detected

@end B3

Graph Mode - Connected Nodes

from llb_doc import create_graph

g = create_graph()

# Add nodes
python = g.add_node("concept", "Python", id_="python", category="language")
django = g.add_node("concept", "Django", id_="django", category="framework")
flask = g.add_node("concept", "Flask", id_="flask", category="framework")

# Add edges
g.add_edge("python", "django", "has_framework")
g.add_edge("python", "flask", "has_framework")

# Render with focus and radius
print(g.render(focus="python", radius=1))

Output

@ctx C1
focus=python
radius=1
strategy=bfs
tiers=0:python;1:django,flask
@end C1

@node django concept
category=framework
tier=1
in_edges=['python:has_framework']
out_edges=[]

Django

@end django

@node flask concept
category=framework
tier=1
in_edges=['python:has_framework']
out_edges=[]

Flask

@end flask

@edge E1 python django has_framework @end

@edge E2 python flask has_framework @end

@node python concept
category=language
tier=0
in_edges=[]
out_edges=['django:has_framework', 'flask:has_framework']

Python

@end python

Block Structure

Each block follows this structure:

@block <id> <type> [lang]
key1=value1
key2=value2

<content>

@end <id>

Features

Document Operations

doc = create_llb()
b1 = doc.add_block("task", "First task")
b2 = doc.add_block("task", "Second task")

# Check, get, remove blocks
doc.has_block(b1.id)        # True
doc.get_block(b1.id)        # Block object
doc.remove_block(b1.id)     # Remove and return block

# Reorder blocks
doc.move_block(b2.id, 0)    # Move to position
doc.swap_blocks(b1.id, b2.id)  # Swap positions

# Prefix and suffix
doc.prefix = "# Analysis Context"
doc.suffix = "# End"

Custom Meta Generators

Auto-generate metadata for blocks:

from llb_doc import create_llb, meta_generator, Block

@meta_generator("word_count")
def gen_word_count(block: Block) -> str:
    return str(len(block.content.split()))

doc = create_llb(generators=[gen_word_count])
doc.add_block("text", "Hello world!")
print(doc.render())
# word_count=2 will be auto-added

Custom Block Sorters

Sort blocks in custom order:

from llb_doc import create_llb, block_sorter, Block

@block_sorter("by_priority")
def sort_by_priority(blocks: list[Block]) -> list[Block]:
    order = {"high": 0, "medium": 1, "low": 2}
    return sorted(blocks, key=lambda b: order.get(b.meta.get("priority", ""), 99))

doc = create_llb(sorters=[sort_by_priority])
doc.add_block("task", "Task A", priority="low")
doc.add_block("task", "Task B", priority="high")
print(doc.render(order="by_priority"))

Graph Mode Features

g = create_graph()

# Builder pattern for nodes
g.node("person").id("p1").meta(name="Alice").content("Developer").add()

# Builder pattern for edges
g.edge("p1", "c1", "works_at").meta(since="2020").content("Full-time").add()

# Render with different sorting strategies
g.render(focus="p1", radius=2, order="focus_last")   # Default: focus at end
g.render(focus="p1", radius=2, order="focus_first")  # Focus at beginning
g.render(focus="p1", radius=2, order="tier_asc")     # By tier ascending
g.render(focus="p1", radius=2, order="tier_desc")    # By tier descending

# Render all nodes without focus
g.render()  # No @ctx block, shows all nodes and edges

Free Mode - Full Control

For complex scenarios where you need explicit control over which nodes and edges to render:

from llb_doc import create_graph, Ctx

g = create_graph()
g.add_node("person", "Alice's full bio...", id_="N1")
g.add_node("person", "Bob's full bio...", id_="N2")
g.add_node("person", "Carol's full bio...", id_="N3")
g.add_edge("N1", "N2", "knows", id_="E1")
g.add_edge("N2", "N3", "knows", id_="E2")

# Render specific nodes/edges in exact order
# Use tuple (id, True) for brief mode (meta only, no content)
output = g.render_free(
    items=[
        "N1",           # full render
        ("N2", True),   # brief render (no content)
        "E1",           # full render
    ],
    ctx={
        "content": "Custom neighborhood view",
        "meta": {"view": "neighborhood", "roots": "N1"},
    },
)

# Custom brief renderer
output = g.render_free(
    items=["N1", ("N2", True), ("N3", True)],
    brief_renderer=lambda b: f"@{b.type} {b.id} [brief] @end",
)

Free mode features:

• Explicit ordering: Items render in the exact order you specify
• Brief mode: Use (id, True) tuple to render only meta (no content)
• Custom brief renderer: Pass a function to fully customize brief output
• Optional ctx: Pass dict or Ctx object, automatically placed at top

API Reference

Main Functions

GraphDocument Methods

Decorators

Classes

Types

Demo

Run the demo script to see all features in action:

python demo.py

License

MIT