Blocks

Block type definitions and models.

Core Models

Block

The main block model representing extracted content:

from hother.streamblocks.core.models import Block

block = Block(
    block_type="message",
    metadata={"author": "assistant"},
    content="Hello, how can I help you?"
)

# Access properties
print(block.block_type)  # "message"
print(block.content)     # "Hello, how can I help you?"
print(block.metadata)    # {"author": "assistant"}

BlockCandidate

Represents a potential block during parsing:

from hother.streamblocks.core.models import BlockCandidate

candidate = BlockCandidate(
    syntax=syntax,
    start_line=1,
)

Block Types

Streamblocks supports various block types for different content:

Message Blocks

For text messages and responses:

block = Block(
    block_type="message",
    metadata={"author": "assistant"},
    content="Hello, how can I help you?"
)

Tool Call Blocks

For function/tool invocations:

block = Block(
    block_type="tool_call",
    metadata={"name": "search", "id": "call_123"},
    content='{"query": "weather today"}'
)

Code Blocks

For code snippets:

block = Block(
    block_type="code",
    metadata={"language": "python"},
    content="print('Hello, World!')"
)

Custom Block Types

Define custom block types for your application:

from hother.streamblocks.core.models import Block

class ConfigBlock(Block):
    block_type = "config"

    def validate(self) -> bool:
        import json
        try:
            json.loads(self.content)
            return True
        except json.JSONDecodeError:
            return False

API Reference

hother.streamblocks.core.models

Core models for StreamBlocks.

Block

Bases: BaseModel

User-facing base class for defining block types.

This minimal class contains only the essential fields (metadata and content). Users inherit from this to define their block types.

Usage

class YesNo(Block[YesNoMetadata, YesNoContent]): pass

Access fields

block: Block[YesNoMetadata, YesNoContent] block.metadata.prompt # Type-safe access to metadata fields block.content.response # Type-safe access to content fields

content class-attribute instance-attribute

content: TContent = Field(
    ..., description="Parsed block content"
)

metadata class-attribute instance-attribute

metadata: TMetadata = Field(
    ..., description="Parsed block metadata"
)

BlockCandidate

Tracks a potential block being accumulated.

content_lines instance-attribute

content_lines: list[str] = []

content_validation_error instance-attribute

content_validation_error: str | None = None

content_validation_passed instance-attribute

content_validation_passed: bool = True

current_section instance-attribute

current_section: SectionType = HEADER

lines instance-attribute

lines: list[str] = []

metadata_lines instance-attribute

metadata_lines: list[str] = []

metadata_validation_error instance-attribute

metadata_validation_error: str | None = None

metadata_validation_passed instance-attribute

metadata_validation_passed: bool = True

parsed_content instance-attribute

parsed_content: dict[str, Any] | None = None

parsed_metadata instance-attribute

parsed_metadata: dict[str, Any] | None = None

raw_text property

raw_text: str

Get the raw text of all accumulated lines.

start_line instance-attribute

start_line = start_line

state instance-attribute

state = HEADER_DETECTED

syntax instance-attribute

syntax = syntax

add_line

add_line(line: str) -> None

Add a line to the candidate.

cache_content_validation

cache_content_validation(
    passed: bool, error: str | None
) -> None

Cache content validation result.

This method encapsulates validation result storage, providing a clear interface for the state machine to cache validation state.

Parameters:

Name	Type	Description	Default
passed	bool	Whether content validation passed	required
error	str | None	Error message if validation failed, None otherwise	required

cache_metadata_validation

cache_metadata_validation(
    passed: bool, error: str | None
) -> None

Cache metadata validation result.

This method encapsulates validation result storage, providing a clear interface for the state machine to cache validation state.

Parameters:

Name	Type	Description	Default
passed	bool	Whether metadata validation passed	required
error	str | None	Error message if validation failed, None otherwise	required

compute_hash

compute_hash() -> str

Compute hash of first N chars for ID (N defined in constants).

transition_to_content

transition_to_content() -> None

Transition from metadata/header to content section.

This method encapsulates the section state transition logic, making the state change explicit and centralized.

transition_to_metadata

transition_to_metadata() -> None

Transition from header to metadata section.

This method encapsulates the section state transition logic, making the state change explicit and centralized.

ExtractedBlock

Bases: Block[TMetadata, TContent]

Full runtime representation of an extracted block.

This class extends the minimal Block with extraction metadata like line numbers, syntax name, and hash ID. The processor creates instances of this class when blocks are successfully extracted.

The metadata and content fields are typed generics, allowing type-safe access to block-specific fields.

content class-attribute instance-attribute

content: TContent = Field(
    ..., description="Parsed block content"
)

hash_id class-attribute instance-attribute

hash_id: str = Field(
    ..., description="Hash-based ID for the block"
)

line_end class-attribute instance-attribute

line_end: int = Field(..., description="Ending line number")

line_start class-attribute instance-attribute

line_start: int = Field(
    ..., description="Starting line number"
)

metadata class-attribute instance-attribute

metadata: TMetadata = Field(
    ..., description="Parsed block metadata"
)

raw_text class-attribute instance-attribute

raw_text: str = Field(
    ..., description="Original raw text of the block"
)

syntax_name class-attribute instance-attribute

syntax_name: str = Field(
    ...,
    description="Name of the syntax that extracted this block",
)

extract_block_types

extract_block_types(
    block_class: type[Any],
) -> tuple[type[BaseMetadata], type[BaseContent]]

Extract metadata and content type parameters from a Block class.

For classes inheriting from Block[M, C], Pydantic resolves the concrete types and stores them in the field annotations during class definition. This function extracts those resolved types from model_fields.

Parameters:

Name	Type	Description	Default
block_class	type[Any]	The block class to extract types from	required

Returns:

Type	Description
tuple[type[BaseMetadata], type[BaseContent]]	Tuple of (metadata_class, content_class)