> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.content

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Exports

| Name | Kind |
| - | - |
| [`AssetRef`](#assetref) | Class |
| [`Audio`](#audio) | Class |
| [`AudioConstraints`](#audioconstraints) | Class |
| [`ContentConstraints`](#contentconstraints) | Value or type alias |
| [`ContentPart`](#contentpart) | Value or type alias |
| [`Data`](#data) | Class |
| [`DataConstraints`](#dataconstraints) | Class |
| [`File`](#file) | Class |
| [`FileConstraints`](#fileconstraints) | Class |
| [`Image`](#image) | Class |
| [`ImageConstraints`](#imageconstraints) | Class |
| [`Text`](#text) | Class |
| [`Video`](#video) | Class |
| [`VideoConstraints`](#videoconstraints) | Class |
| [`constraint_schema_extension`](#constraint_schema_extension) | Function |
| [`content_constraints`](#content_constraints) | Function |
| [`content_schema_extension`](#content_schema_extension) | Function |

## AssetRef

A backend-neutral reference to bytes held by an asset store.

```python theme={null}
AssetRef(
    *,
    assetId: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')],
    store: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')] = 'default',
    mediaType: str | None = None,
    sizeBytes: Annotated[int | None, Ge(ge=0)] = None,
    type: Literal['asset'] = 'asset',
    label: Annotated[str | None, MinLen(min_length=1), MaxLen(max_length=128)] = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `asset_id` | `str` | `—` |
| `store` | `str` | `'default'` |
| `media_type` | `str \| None` | `None` |
| `size_bytes` | `int \| None` | `None` |
| `type` | `Literal['asset']` | `'asset'` |
| `label` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `assetId` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')]` | Required |
> | `store` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')]` | `'default'` |
> | `mediaType` | `str \| None` | `None` |
> | `sizeBytes` | `Annotated[int \| None, Ge(ge=0)]` | `None` |
> | `type` | `Literal['asset']` | `'asset'` |
> | `label` | `Annotated[str \| None, MinLen(min_length=1), MaxLen(max_length=128)]` | `None` |
>
> ```python theme={null}
> from harnest.content import AssetRef
>
> ref = AssetRef(assetId=...)
> ```

## Audio

Inline or stored audio with optional authoritative media metadata.

```python theme={null}
Audio(
    *,
    assetId: Annotated[str | None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')] = None,
    store: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')] = 'default',
    data: str | None = None,
    mediaType: str | None = None,
    sizeBytes: Annotated[int | None, Ge(ge=0)] = None,
    type: Literal['audio'] = 'audio',
    durationSeconds: Annotated[float | None, Ge(ge=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = None,
    sampleRateHz: Annotated[int | None, Gt(gt=0)] = None,
    channels: Annotated[int | None, Gt(gt=0)] = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `asset_id` | `str \| None` | `None` |
| `store` | `str` | `'default'` |
| `data` | `str \| None` | `None` |
| `media_type` | `str \| None` | `None` |
| `size_bytes` | `int \| None` | `None` |
| `type` | `Literal['audio']` | `'audio'` |
| `duration_seconds` | `float \| None` | `None` |
| `sample_rate_hz` | `int \| None` | `None` |
| `channels` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `assetId` | `Annotated[str \| None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')]` | `None` |
> | `store` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')]` | `'default'` |
> | `data` | `str \| None` | `None` |
> | `mediaType` | `str \| None` | `None` |
> | `sizeBytes` | `Annotated[int \| None, Ge(ge=0)]` | `None` |
> | `type` | `Literal['audio']` | `'audio'` |
> | `durationSeconds` | `Annotated[float \| None, Ge(ge=0), _PydanticGeneralMetadata(allow_inf_nan=False)]` | `None` |
> | `sampleRateHz` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
> | `channels` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
>
> ```python theme={null}
> from harnest.content import Audio
>
> audio = Audio()
> ```

## AudioConstraints

Reusable limits for an audio field declared with `Annotated`.

```python theme={null}
AudioConstraints(
    media_types: frozenset[str] | None = None,
    max_bytes: int | None = None,
    min_duration_seconds: float | None = None,
    max_duration_seconds: float | None = None,
    min_sample_rate_hz: int | None = None,
    max_sample_rate_hz: int | None = None,
    min_channels: int | None = None,
    max_channels: int | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `media_types` | `frozenset[str] \| None` | `None` |
| `max_bytes` | `int \| None` | `None` |
| `min_duration_seconds` | `float \| None` | `None` |
| `max_duration_seconds` | `float \| None` | `None` |
| `min_sample_rate_hz` | `int \| None` | `None` |
| `max_sample_rate_hz` | `int \| None` | `None` |
| `min_channels` | `int \| None` | `None` |
| `max_channels` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `media_types` | `frozenset[str] \| None` | `None` |
> | `max_bytes` | `int \| None` | `None` |
> | `min_duration_seconds` | `float \| None` | `None` |
> | `max_duration_seconds` | `float \| None` | `None` |
> | `min_sample_rate_hz` | `int \| None` | `None` |
> | `max_sample_rate_hz` | `int \| None` | `None` |
> | `min_channels` | `int \| None` | `None` |
> | `max_channels` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import AudioConstraints
>
> constraints = AudioConstraints()
> ```

## ContentConstraints

```python theme={null}
ContentConstraints = harnest.content.ImageConstraints | harnest.content.AudioConstraints | harnest.content.VideoConstraints | harnest.content.FileConstraints | harnest.content.DataConstraints
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.content import ContentConstraints
> ```

## ContentPart

```python theme={null}
ContentPart = Annotated[harnest.content.Text | harnest.content.Image | harnest.content.Audio | harnest.content.Video | harnest.content.File | harnest.content.Data[Any] | harnest.content.AssetRef, FieldInfo(annotation=None, required=True, discriminator='type')]
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.content import ContentPart
> ```

## Data

Typed JSON application data carried as an ordered content part.

```python theme={null}
Data(*, type: Literal['data'] = 'data', value: ~DataValue) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `type` | `Literal['data']` | `'data'` |
| `value` | `DataValue` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `type` | `Literal['data']` | `'data'` |
> | `value` | `~DataValue` | Required |
>
> ```python theme={null}
> from harnest.content import Data
>
> data = Data(value=...)
> ```

## DataConstraints

Reusable serialized-size limits for typed JSON application data.

```python theme={null}
DataConstraints(media_types: frozenset[str] | None = None, max_bytes: int | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `media_types` | `frozenset[str] \| None` | `None` |
| `max_bytes` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `media_types` | `frozenset[str] \| None` | `None` |
> | `max_bytes` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import DataConstraints
>
> constraints = DataConstraints()
> ```

## File

An inline or stored file with safe display and document metadata.

```python theme={null}
File(
    *,
    assetId: Annotated[str | None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')] = None,
    store: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')] = 'default',
    data: str | None = None,
    mediaType: str | None = None,
    sizeBytes: Annotated[int | None, Ge(ge=0)] = None,
    type: Literal['file'] = 'file',
    name: Annotated[str | None, MinLen(min_length=1), MaxLen(max_length=255)] = None,
    pageCount: Annotated[int | None, Gt(gt=0)] = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `asset_id` | `str \| None` | `None` |
| `store` | `str` | `'default'` |
| `data` | `str \| None` | `None` |
| `media_type` | `str \| None` | `None` |
| `size_bytes` | `int \| None` | `None` |
| `type` | `Literal['file']` | `'file'` |
| `name` | `str \| None` | `None` |
| `page_count` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `assetId` | `Annotated[str \| None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')]` | `None` |
> | `store` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')]` | `'default'` |
> | `data` | `str \| None` | `None` |
> | `mediaType` | `str \| None` | `None` |
> | `sizeBytes` | `Annotated[int \| None, Ge(ge=0)]` | `None` |
> | `type` | `Literal['file']` | `'file'` |
> | `name` | `Annotated[str \| None, MinLen(min_length=1), MaxLen(max_length=255)]` | `None` |
> | `pageCount` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
>
> ```python theme={null}
> from harnest.content import File
>
> file = File()
> ```

## FileConstraints

Reusable limits for a file field declared with `Annotated`.

```python theme={null}
FileConstraints(
    media_types: frozenset[str] | None = None,
    max_bytes: int | None = None,
    max_pages: int | None = None,
    archives_allowed: bool | None = None,
    max_expanded_bytes: int | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `media_types` | `frozenset[str] \| None` | `None` |
| `max_bytes` | `int \| None` | `None` |
| `max_pages` | `int \| None` | `None` |
| `archives_allowed` | `bool \| None` | `None` |
| `max_expanded_bytes` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `media_types` | `frozenset[str] \| None` | `None` |
> | `max_bytes` | `int \| None` | `None` |
> | `max_pages` | `int \| None` | `None` |
> | `archives_allowed` | `bool \| None` | `None` |
> | `max_expanded_bytes` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import FileConstraints
>
> constraints = FileConstraints()
> ```

## Image

An inline or stored image with optional authoritative dimensions.

```python theme={null}
Image(
    *,
    assetId: Annotated[str | None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')] = None,
    store: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')] = 'default',
    data: str | None = None,
    mediaType: str | None = None,
    sizeBytes: Annotated[int | None, Ge(ge=0)] = None,
    type: Literal['image'] = 'image',
    width: Annotated[int | None, Gt(gt=0)] = None,
    height: Annotated[int | None, Gt(gt=0)] = None,
    animated: bool | None = None,
    frameCount: Annotated[int | None, Gt(gt=0)] = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `asset_id` | `str \| None` | `None` |
| `store` | `str` | `'default'` |
| `data` | `str \| None` | `None` |
| `media_type` | `str \| None` | `None` |
| `size_bytes` | `int \| None` | `None` |
| `type` | `Literal['image']` | `'image'` |
| `width` | `int \| None` | `None` |
| `height` | `int \| None` | `None` |
| `animated` | `bool \| None` | `None` |
| `frame_count` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `assetId` | `Annotated[str \| None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')]` | `None` |
> | `store` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')]` | `'default'` |
> | `data` | `str \| None` | `None` |
> | `mediaType` | `str \| None` | `None` |
> | `sizeBytes` | `Annotated[int \| None, Ge(ge=0)]` | `None` |
> | `type` | `Literal['image']` | `'image'` |
> | `width` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
> | `height` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
> | `animated` | `bool \| None` | `None` |
> | `frameCount` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
>
> ```python theme={null}
> from harnest.content import Image
>
> image = Image()
> ```

## ImageConstraints

Reusable limits for an image field declared with `Annotated`.

```python theme={null}
ImageConstraints(
    media_types: frozenset[str] | None = None,
    max_bytes: int | None = None,
    min_width: int | None = None,
    max_width: int | None = None,
    min_height: int | None = None,
    max_height: int | None = None,
    max_pixels: int | None = None,
    min_aspect_ratio: float | None = None,
    max_aspect_ratio: float | None = None,
    animated: bool | None = None,
    max_frames: int | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `media_types` | `frozenset[str] \| None` | `None` |
| `max_bytes` | `int \| None` | `None` |
| `min_width` | `int \| None` | `None` |
| `max_width` | `int \| None` | `None` |
| `min_height` | `int \| None` | `None` |
| `max_height` | `int \| None` | `None` |
| `max_pixels` | `int \| None` | `None` |
| `min_aspect_ratio` | `float \| None` | `None` |
| `max_aspect_ratio` | `float \| None` | `None` |
| `animated` | `bool \| None` | `None` |
| `max_frames` | `int \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `media_types` | `frozenset[str] \| None` | `None` |
> | `max_bytes` | `int \| None` | `None` |
> | `min_width` | `int \| None` | `None` |
> | `max_width` | `int \| None` | `None` |
> | `min_height` | `int \| None` | `None` |
> | `max_height` | `int \| None` | `None` |
> | `max_pixels` | `int \| None` | `None` |
> | `min_aspect_ratio` | `float \| None` | `None` |
> | `max_aspect_ratio` | `float \| None` | `None` |
> | `animated` | `bool \| None` | `None` |
> | `max_frames` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import ImageConstraints
>
> constraints = ImageConstraints()
> ```

## Text

An ordered UTF-8 text part in a portable message.

```python theme={null}
Text(*, type: Literal['text'] = 'text', text: Annotated[str, MinLen(min_length=1)]) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `type` | `Literal['text']` | `'text'` |
| `text` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `type` | `Literal['text']` | `'text'` |
> | `text` | `Annotated[str, MinLen(min_length=1)]` | Required |
>
> ```python theme={null}
> from harnest.content import Text
>
> text = Text(text=...)
> ```

## Video

Inline or stored video with optional authoritative media metadata.

```python theme={null}
Video(
    *,
    assetId: Annotated[str | None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')] = None,
    store: Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')] = 'default',
    data: str | None = None,
    mediaType: str | None = None,
    sizeBytes: Annotated[int | None, Ge(ge=0)] = None,
    type: Literal['video'] = 'video',
    width: Annotated[int | None, Gt(gt=0)] = None,
    height: Annotated[int | None, Gt(gt=0)] = None,
    durationSeconds: Annotated[float | None, Ge(ge=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = None,
    frameRate: Annotated[float | None, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = None,
    hasAudio: bool | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `asset_id` | `str \| None` | `None` |
| `store` | `str` | `'default'` |
| `data` | `str \| None` | `None` |
| `media_type` | `str \| None` | `None` |
| `size_bytes` | `int \| None` | `None` |
| `type` | `Literal['video']` | `'video'` |
| `width` | `int \| None` | `None` |
| `height` | `int \| None` | `None` |
| `duration_seconds` | `float \| None` | `None` |
| `frame_rate` | `float \| None` | `None` |
| `has_audio` | `bool \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `assetId` | `Annotated[str \| None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$')]` | `None` |
> | `store` | `Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9._~-]{0,63}$')]` | `'default'` |
> | `data` | `str \| None` | `None` |
> | `mediaType` | `str \| None` | `None` |
> | `sizeBytes` | `Annotated[int \| None, Ge(ge=0)]` | `None` |
> | `type` | `Literal['video']` | `'video'` |
> | `width` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
> | `height` | `Annotated[int \| None, Gt(gt=0)]` | `None` |
> | `durationSeconds` | `Annotated[float \| None, Ge(ge=0), _PydanticGeneralMetadata(allow_inf_nan=False)]` | `None` |
> | `frameRate` | `Annotated[float \| None, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)]` | `None` |
> | `hasAudio` | `bool \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import Video
>
> video = Video()
> ```

## VideoConstraints

Reusable limits for a video field declared with `Annotated`.

```python theme={null}
VideoConstraints(
    media_types: frozenset[str] | None = None,
    max_bytes: int | None = None,
    min_duration_seconds: float | None = None,
    max_duration_seconds: float | None = None,
    min_width: int | None = None,
    max_width: int | None = None,
    min_height: int | None = None,
    max_height: int | None = None,
    max_pixels: int | None = None,
    min_frame_rate: float | None = None,
    max_frame_rate: float | None = None,
    audio_allowed: bool | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `media_types` | `frozenset[str] \| None` | `None` |
| `max_bytes` | `int \| None` | `None` |
| `min_duration_seconds` | `float \| None` | `None` |
| `max_duration_seconds` | `float \| None` | `None` |
| `min_width` | `int \| None` | `None` |
| `max_width` | `int \| None` | `None` |
| `min_height` | `int \| None` | `None` |
| `max_height` | `int \| None` | `None` |
| `max_pixels` | `int \| None` | `None` |
| `min_frame_rate` | `float \| None` | `None` |
| `max_frame_rate` | `float \| None` | `None` |
| `audio_allowed` | `bool \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `media_types` | `frozenset[str] \| None` | `None` |
> | `max_bytes` | `int \| None` | `None` |
> | `min_duration_seconds` | `float \| None` | `None` |
> | `max_duration_seconds` | `float \| None` | `None` |
> | `min_width` | `int \| None` | `None` |
> | `max_width` | `int \| None` | `None` |
> | `min_height` | `int \| None` | `None` |
> | `max_height` | `int \| None` | `None` |
> | `max_pixels` | `int \| None` | `None` |
> | `min_frame_rate` | `float \| None` | `None` |
> | `max_frame_rate` | `float \| None` | `None` |
> | `audio_allowed` | `bool \| None` | `None` |
>
> ```python theme={null}
> from harnest.content import VideoConstraints
>
> constraints = VideoConstraints()
> ```

## constraint\_schema\_extension

Render one immutable constraint as the public JSON Schema extension.

```python theme={null}
constraint_schema_extension(constraint: ContentConstraints) -> dict[str, Any]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `constraint` | `ContentConstraints` | Required |
>
> ```python theme={null}
> from harnest.content import constraint_schema_extension
>
> result = constraint_schema_extension(constraint=...)
> ```

## content\_constraints

Extract constraint metadata recursively from an authored annotation.

```python theme={null}
content_constraints(annotation: Any) -> tuple[ContentConstraints, ...]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `annotation` | `Any` | Required |
>
> ```python theme={null}
> from harnest.content import content_constraints
>
> result = content_constraints(annotation=...)
> ```

## content\_schema\_extension

Render an annotation's single constraint as `x-harnest-media`.

```python theme={null}
content_schema_extension(annotation: Any) -> dict[str, Any]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `annotation` | `Any` | Required |
>
> ```python theme={null}
> from harnest.content import content_schema_extension
>
> result = content_schema_extension(annotation=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.