API Reference

Parsing

Parse raw model output into a value validated against a Pydantic v2 type.

Create a streaming parser. Feed text chunks into the returned StreamParser.

Parse raw model output with full debug trace.

Returns a ParseDebug with all candidate interpretations, the selected candidate, and the final value.

Extraction

`Resolver`

Bases: Protocol

Protocol for evidence alignment resolvers.

Implementations take extracted field values and align them back to source text.

`TokenAlignmentResolver` `dataclass`

Default resolver using token-based alignment (exact, lesser, fuzzy).

`SupportsBatchInfer`

Bases: Protocol

`submit_batch(requests: Sequence[InferenceRequest], **kwargs: Any) -> str`

Submit a batch job, return a batch_id.

`poll_batch(batch_id: str) -> BatchStatus`

Check batch status.

`retrieve_batch(batch_id: str) -> Sequence[str]`

Retrieve completed batch results.

`StaticProvider` `dataclass`

Deterministic provider for local demos/tests.

If outputs has a single item, it is repeated for every prompt. If outputs is shorter than prompts, the last output is repeated.

`ChunkDebug` `dataclass`

Per-chunk debug information collected during extraction.

`Document` `dataclass`

`from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `classmethod`

Fetch text content from a URL and create a Document.

Requires httpx: pip install parsantic[web]

`afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `async` `classmethod`

Async version of from_url.

`get_resolver(resolver: Resolver | None = None, *, options: AlignmentOptions | None = None, tokenizer: TokenizerName | Tokenizer | None = None) -> Resolver`

Return the provided resolver or create a default TokenAlignmentResolver.

Coercion

`CoerceOptions` `dataclass`

Options for coercion & scoring.

`coerce_jsonish_to_python(value: JsonishValue, adapter: TypeAdapter[Any], *, options: CoerceOptions, allow_partial: bool = False) -> ScoredValue`

Coerce JsonishValue candidates to a python object validated by a TypeAdapter.

Strategy: - if AnyOf: coerce each candidate, validate, pick best score. - otherwise: attempt direct validation; if it fails, apply light coercions and retry.

Coerce a Python object with full debug trace.

Returns a ParseDebug with candidate info and the final value.

Update

High-level LLM-powered update for existing objects via JSON Patch.

Given an existing document (dict or Pydantic model), an instruction describing what changed, and a target schema, :func:update calls an LLM to produce RFC 6902 JSON Patch operations, applies them, validates the result, and optionally retries on validation failure.

Requires the [ai] extra (pip install "parsantic[ai]").

Example::

from parsantic import update

result = update(
    existing={"name": "Alex", "role": "Engineer", "skills": ["Python"]},
    instruction="Alex got promoted to Senior Engineer and picked up Rust.",
    target=User,
    model="openai:gpt-4o-mini",
)
result.value   # User(name='Alex', role='Senior Engineer', skills=['Python', 'Rust'])
result.patches # [JsonPatchOp(op='replace', path='/role', ...), ...]

`UpdateResult` `dataclass`

Result of an :func:update call.

Attributes

value The validated updated object. patches All patches applied (accumulated across retries). doc_before The original document as a dict (before any patches). doc_after_patches The final patched document as a dict (after all patches). raw_text Raw LLM output from the last successful call. attempts Number of LLM calls made (1 means no retries were needed).

`doc_after: dict[str, Any]` `property`

Backward-compatible alias for doc_after_patches.

`update(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T]`

Update an existing object with new information using an LLM.

Calls an LLM to generate RFC 6902 JSON Patch operations, applies them to existing, validates against target, and retries on failure.

Parameters

existing The current object as a dict or Pydantic model instance. instruction Natural language description of what changed. target The Pydantic model class or TypeAdapter to validate against. model Model string (e.g. "openai:gpt-4o-mini") or a provider instance. policy Patch safety policy. Defaults to no remove, max 50 ops. max_retries Maximum number of retry attempts on validation failure. provider_kwargs Extra kwargs passed to the provider constructor.

Returns

UpdateResult[T] The validated updated object with patch metadata.

`aupdate(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T]` `async`

Async version of :func:update.

JSON Patch

Apply a sequence of JSON Patch operations to doc and return the result.

The input doc is never mutated; a deep copy is made before applying any operations.

Parameters

doc The document to patch. patches Ordered list of :class:JsonPatchOp operations. policy Safety policy to enforce. See :class:PatchPolicy.

Returns

Any The patched document.

Raises

PatchError If any operation fails (missing path, bad index, etc.). PolicyViolationError If the patch set violates the active policy.

Apply patches then validate the result against a Pydantic type.

If doc is a :class:~pydantic.BaseModel it is first converted to a dict via :meth:~pydantic.BaseModel.model_dump.

Returns a :class:~parsantic.api.ParseResult with the validated value, empty flags, and a score of 0.

Raises

PatchError If any patch operation fails. PolicyViolationError If the patches violate the active policy. pydantic.ValidationError If the patched document does not conform to target.

Coerce various patch representations into a list of :class:JsonPatchOp.

Handles common LLM failure modes:

A list[dict] of raw patch dicts.
A JSON string containing a list of patches.
A dict with a "patches" key wrapping the actual list.
A JSON string wrapping a dict with a "patches" key.
A single dict (treated as a one-element list).
Already-validated :class:JsonPatchOp instances (pass-through).

Raises

PatchError If the input cannot be interpreted as a list of patches.

Types

Options for coercion & scoring.

Configurable retry strategy.

Attributes

max_retries Maximum number of retry attempts (0 = no retries). base_delay Initial delay in seconds before first retry. backoff_factor Multiplier applied to delay on each subsequent retry. max_delay Upper bound on delay in seconds. jitter If True, add random jitter (0 to 50% of delay) to prevent thundering herd.

`delay_for_attempt(attempt: int) -> float`

Compute delay in seconds before the given retry attempt (0-indexed).

`wait(attempt: int) -> None`

Sleep for the computed delay (sync).

`async_wait(attempt: int) -> None` `async`

Sleep for the computed delay (async).

Bases: BaseModel

A single RFC 6902 JSON Patch operation.

Only add, replace, and remove are supported. value is required for add and replace and ignored for remove.

Result of an :func:update call.

Attributes

value The validated updated object. patches All patches applied (accumulated across retries). doc_before The original document as a dict (before any patches). doc_after_patches The final patched document as a dict (after all patches). raw_text Raw LLM output from the last successful call. attempts Number of LLM calls made (1 means no retries were needed).

`doc_after: dict[str, Any]` `property`

Backward-compatible alias for doc_after_patches.

`from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `classmethod`

Fetch text content from a URL and create a Document.

Requires httpx: pip install parsantic[web]

`afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `async` `classmethod`

Async version of from_url.

Bases: str, Enum

API Reference

Parsing

Extraction

Resolver

TokenAlignmentResolver dataclass

SupportsBatchInfer

submit_batch(requests: Sequence[InferenceRequest], **kwargs: Any) -> str

poll_batch(batch_id: str) -> BatchStatus

retrieve_batch(batch_id: str) -> Sequence[str]

StaticProvider dataclass

ChunkDebug dataclass

Document dataclass

from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document classmethod

afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document async classmethod

get_resolver(resolver: Resolver | None = None, *, options: AlignmentOptions | None = None, tokenizer: TokenizerName | Tokenizer | None = None) -> Resolver

Coercion

CoerceOptions dataclass

coerce_jsonish_to_python(value: JsonishValue, adapter: TypeAdapter[Any], *, options: CoerceOptions, allow_partial: bool = False) -> ScoredValue

Update

UpdateResult dataclass

Attributes

doc_after: dict[str, Any] property

update(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T]

Parameters

Returns

aupdate(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T] async

JSON Patch

Parameters

Returns

Raises

Raises

Raises

Types

Attributes

delay_for_attempt(attempt: int) -> float

wait(attempt: int) -> None

async_wait(attempt: int) -> None async

Attributes

doc_after: dict[str, Any] property

from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document classmethod

afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document async classmethod

`Resolver`

`TokenAlignmentResolver` `dataclass`

`SupportsBatchInfer`

`submit_batch(requests: Sequence[InferenceRequest], **kwargs: Any) -> str`

`poll_batch(batch_id: str) -> BatchStatus`

`retrieve_batch(batch_id: str) -> Sequence[str]`

`StaticProvider` `dataclass`

`ChunkDebug` `dataclass`

`Document` `dataclass`

`from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `classmethod`

`afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `async` `classmethod`

`get_resolver(resolver: Resolver | None = None, *, options: AlignmentOptions | None = None, tokenizer: TokenizerName | Tokenizer | None = None) -> Resolver`

`CoerceOptions` `dataclass`

`coerce_jsonish_to_python(value: JsonishValue, adapter: TypeAdapter[Any], *, options: CoerceOptions, allow_partial: bool = False) -> ScoredValue`

`UpdateResult` `dataclass`

`doc_after: dict[str, Any]` `property`

`update(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T]`

`aupdate(existing: dict[str, Any] | BaseModel, instruction: str, target: type[T] | TypeAdapter[T], *, model: str | Any | None = None, policy: PatchPolicy | None = None, max_retries: int = 2, retry: RetryPolicy | None = None, provider_kwargs: dict[str, Any] | None = None) -> UpdateResult[T]` `async`

`delay_for_attempt(attempt: int) -> float`

`wait(attempt: int) -> None`

`async_wait(attempt: int) -> None` `async`

`doc_after: dict[str, Any]` `property`

`from_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `classmethod`

`afrom_url(url: str, *, document_id: str | None = None, additional_context: str | None = None, timeout: float = 30.0, headers: dict[str, str] | None = None) -> Document` `async` `classmethod`