MarkBack

Appearance

Python API ​

The Python package mirrors the format: parse files into records, write records back out, and lint for structural issues.

Install: pip install markback | View on PyPI

Read Records ​

py
from markback import parse_file

result = parse_file("labels.mb")
for record in result.records:
    print(record.id, record.feedback)

Write Records ​

py
from markback import Record, write, write_string

records = [
    Record(feedback="approved", id="item-1", content="First item"),
    Record(feedback="rejected", id="item-2", content="Second item"),
]

# Write to file
write("output.mb", records)

# Or get a string
text = write_string(records)

Append a Record ​

py
from markback import Record, FileRef, append

record = Record(feedback="approved", file=FileRef("./data/item.txt"))
append("labels.mb", record)

Lint Records ​

py
from markback import lint_file

result = lint_file("output.mb")
if result.has_errors:
    for diagnostic in result.diagnostics:
        print(diagnostic)

Record Model Overview ​

  • Record: feedback (required), id (optional), by (optional), file (optional FileRef), input (optional FileRef), tags (list), content (optional), metadata (dict)
  • FileRef: points to external content (@file or @input), with optional line/character ranges
  • ParseResult: records, diagnostics, has_errors, has_warnings, scope, covers, version
  • parse_feedback: helper for structured feedback parsing when you choose to interpret labels and attributes

Attributed Feedback ​

Use the by field to track who provided feedback:

py
from markback import Record, write

records = [
    Record(feedback="approved", id="item-1", by="alice", content="First item"),
    Record(feedback="needs work", id="item-2", by="bob", content="Second item"),
]

write("output.mb", records)

Tags ​

Use the tags field for categorization:

py
from markback import Record, write

records = [
    Record(feedback="approved", id="item-1", tags=["training", "batch-1"], content="Example"),
]

write("output.mb", records)

Parsing Helpers ​

py
from markback import parse_string, parse_directory

inline = """
%markback 2

@id example
@tag training

Inline content.
<<< good; quality=high
"""

result = parse_string(inline)
result = parse_directory("./datasets")

Normalize Files ​

py
from markback import normalize

# Rewrite a file in canonical V2 form
canonical = normalize("messy.mb", in_place=True)