som-parser

Parse and query SOM (Semantic Object Model) output in Python. SOM is a structured JSON format that represents web pages as semantic regions and elements, designed for AI agents, browser automation, and web scraping. This library provides Pydantic v2 models for type-safe parsing, validation, and a rich set of query utilities to extract exactly what you need.

Install

pip install som-parser

Quick Start

Parse Plasmate output

import subprocess
from som_parser import parse_som, from_plasmate

# Parse a SOM JSON string or dict
som = parse_som('{"som_version": "0.1", ...}')

# Or parse raw Plasmate CLI output directly
result = subprocess.run(["plasmate", "https://example.com"], capture_output=True, text=True)
som = from_plasmate(result.stdout)

print(som.title)       # "Example Domain"
print(som.url)         # "https://example.com/"
print(som.som_version) # "0.1"

Find links

from som_parser import parse_som, get_links, find_by_role

som = parse_som(data)

# Get all links as simple dicts
for link in get_links(som):
    print(f"{link['text']} -> {link['href']}")

# Or find by role for full SomElement objects
for el in find_by_role(som, "link"):
    print(el.id, el.text, el.attrs.href)

Get interactive elements

from som_parser import parse_som, get_interactive_elements

som = parse_som(data)
for el in get_interactive_elements(som):
    print(f"{el.id}: {el.role.value} - actions: {[a.value for a in el.actions]}")

Convert to markdown

from som_parser import parse_som, to_markdown

som = parse_som(data)
print(to_markdown(som))

Use Pydantic models directly

from som_parser import Som, SomElement, ElementRole

# Validate and construct from a dict
som = Som.model_validate(my_dict)

# Access typed fields
for region in som.regions:
    for element in region.elements:
        if element.role == ElementRole.LINK:
            print(element.attrs.href)

# Serialize back to JSON
print(som.model_dump_json(indent=2))

API Reference

Parser

Query Utilities

Types

All Pydantic v2 models are exported from the top level:

• Som, SomRegion, SomElement, SomElementAttrs, SomMeta
• StructuredData, LinkElement, SelectOption, ListItem
• RegionRole, ElementRole, ElementAction, SemanticHint (enums)

Links

• SOM Spec
• Plasmate
• GitHub Repository

License

Apache-2.0