scry-parse

Python parser for the scry-spec marker format. Conformant with scry-spec v1.1.2 (non-normative addition over v1.1.1 — no parser-relevant changes; the v1.1.2 "Recommended Operating Discipline" section binds consumer agents and tool-instruction surfaces, not parsers).

Install

uv pip install scry-parse
# or:
pip install scry-parse

Usage

from scry_parse import (
    parse_markers,
    validate_marker,
    check_cycles,
    mint_id,
    BASELINE_KINDS,
    BASELINE_STATUSES,
    EXTRAS_SIZE_CAP_BYTES,  # FR4.B (v1.1.0)
)

# Parse markers from file content
with open("my_file.md") as f:
    content = f.read()

result = parse_markers(content)

# Access by type
for entry in result.entries:
    print(entry.id, entry.kind, entry.summary)

for anchor in result.anchors:
    print(anchor.name, anchor.description)

for binding in result.bindings:
    print(binding.local_id, binding.ref)

# Or iterate all markers together
for marker in result.markers:
    print(type(marker).__name__, marker)

# Validate a parsed marker
vr = validate_marker(result.entries[0])
if not vr.valid:
    print(vr.errors)
if vr.warnings:
    print(vr.warnings)

# Detect cycles in depends_on relationships (FR12)
cycle_errors = check_cycles(result.entries)
if cycle_errors:
    for err in cycle_errors:
        print(err)  # "cycle detected: design.a~... → design.b~... → design.a~..."

# Generate a new marker ID
entry_id = mint_id("design", "auth-flow")           # random hash
entry_id = mint_id("design", "auth-flow", content)  # deterministic hash from content

Supported comment styles

Comment-prefix detection is automatic via YAML-key inference — no language hint required.

Line comments

Block comments (v1.0.1+)

Example JSDoc marker:

/**
 * @scry.entry
 * id: design.auth-flow~a1b2c3d4
 * kind: design
 * summary: JWT auth middleware
 * status: active
 * @scry.entry.end
 */

Public API

Dataclasses

• ParseResult — entries: list[EntryMarker], anchors: list[AnchorMarker], bindings: list[BindingMarker], markers property (all three combined)
• EntryMarker — id, kind, summary, status, weight, tags, rationale, applies, seeded_questions, depends_on, implements, supersedes, file, span, extras (FR4.B v1.1.0; dict[str, Any] | None, preserved structurally)
• AnchorMarker — name, description, seeded_questions, file, span
• BindingMarker — local_id, ref, comment, file, offset, span
• ValidationResult — valid, errors, warnings (FR4.B SHOULD-diagnostics for extras: empty map, nested/list value, oversize)

License

MIT — see LICENSE.