annoscript 0.1.0__tar.gz

annoscript-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.credential
+__pycache__/
+*.py[cod]
+.venv/
+lev-live-report*.json
+.env
+.env.*
+*.pem
+*.key
+credential.sh
+dist/
+build/
+*.egg-info/

annoscript-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stevenybw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

annoscript-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: annoscript
+Version: 0.1.0
+Summary: AnnoScript: Programmable AI Annotation
+Project-URL: Homepage, https://annoscript.chukonu.ai
+Project-URL: Repository, https://github.com/stevenybw/annoscript
+Project-URL: Issues, https://github.com/stevenybw/annoscript/issues
+Author: stevenybw
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.128.1; extra == 'server'
+Requires-Dist: uvicorn<1,>=0.40; extra == 'server'
+Provides-Extra: tokenizer
+Requires-Dist: transformers==5.17.0; extra == 'tokenizer'
+Description-Content-Type: text/markdown
+
+# AnnoScript: Programmable AI Annotation
+
+AnnoScript compiles Python annotation programs into a serializable intermediate
+representation and an execution plan. Decision operations and generation
+operations can use separate model backends while sharing program state.
+
+The client supports Python 3.10+. Runtime and server execution require Python 3.12+.
+
+## Install
+
+```bash
+pip install annoscript
+# Local execution and the durable server (Python 3.12+):
+pip install 'annoscript[server]'
+# Optional pinned local tokenizer support:
+pip install 'annoscript[tokenizer]'
+```
+
+Python imports use `annoscript`, for example `from annoscript.client import AnnoClient`.
+The eDSL context is `annoscript.anno.Anno`; the runtime and durable-job clients are
+`AnnoRuntime`, `AnnoJobClient`, and `AnnoRemoteClient` in their corresponding modules.
+This release replaces the former Lev Python namespace. Version-1 serialized IR,
+execution plans, durable-job protocols and the `legacy` backend profile remain compatible.
+
+## Synthetic example
+
+`annoscript_examples.request.annotate` classifies a synthetic document, conditionally
+generates a title, and produces tags and source spans. The example demonstrates
+all six operators without requiring an application dataset.
+
+```bash
+python -m annoscript.inspect annoscript_examples/request.json --show-source
+python -m annoscript.inspect annoscript_examples/request.execution_plan.json
+python -m annoscript.inspect annoscript_examples/request.execution_plan.json --format html -o /tmp/lev-plan.html
+```
+
+To regenerate the saved example with Python 3.12:
+
+```python
+from pathlib import Path
+from annoscript.compiler import compile_program
+from annoscript.plan_lowering import lower_to_plan
+from annoscript_examples.request import annotate
+
+program = compile_program(annotate)
+Path("annoscript_examples/request.json").write_text(program.to_json(indent=2) + "\n")
+Path("annoscript_examples/request.execution_plan.json").write_text(lower_to_plan(program).to_json(indent=2) + "\n")
+```
+
+## Configuration
+
+Install `requirements.txt` for the client and `requirements-server.txt` for
+local execution or the durable job server. Copy `.credential.example` to an
+ignored local file and supply the desired endpoints and model names.
+Environment variables override values from an explicitly supplied environment file.
+Canonical `ANNO_*` keys take precedence over legacy `LEV_*` aliases within the same
+layer. Process environment values override file values regardless of their prefix;
+explicit API arguments take precedence over both. Credentials stay outside packages.
+
+| Variable | Purpose |
+| --- | --- |
+| `ANNO_DECISION_BASE_URL` | Decision provider URL |
+| `ANNO_DECISION_AUTH_TOKEN` | Decision provider credential |
+| `ANNO_DECISION_MODEL` | Decision model identifier |
+| `ANNO_GENERATE_BASE_URL` | Generation provider URL |
+| `ANNO_GENERATE_AUTH_TOKEN` | Generation provider credential |
+| `ANNO_GENERATE_MODEL` | Generation model identifier |
+| `ANNO_GENERATE_PROFILE` | `legacy` (default) or `qwen_vllm` wire protocol |
+| `ANNO_GENERATE_TOKENIZER_DIR` | Caller-provided tokenizer directory when required by policy |
+
+Keep live service settings and credentials outside version control.
+The `legacy` profile name describes a supported request protocol.
+
+```bash
+python -m annoscript_examples.run --env-file .credential --inputs /tmp/documents.json --mode speculative
+```
+
+This command calls the caller's configured services. Inspecting IR, previewing
+resolved requests and running the offline tests do not call model services.
+
+## Execution and backends
+
+Programs use `choice`, `noul`, `score`, `generate`, `generate_list` and `extract`.
+`constrain` declares hard runtime constraints. `system_prompt` supplies shared
+instructions; preconditions validate inputs locally before dispatch.
+
+`AnnoClient` supports strict, eager and speculative execution. The runtime
+handles bounded concurrency, batching, cancellation, repair and result ordering.
+Examples, field names, nullable output and per-call requirements are included in
+the IR and execution-plan bindings. Decision and generation request adapters
+are explicitly selectable and can be inspected without dispatch.
+
+```bash
+python -m annoscript.preview annoscript_examples/request_preview.decision.json
+python -m annoscript.preview annoscript_examples/request_preview.generation.json
+```
+
+Remote execution exchanges serialized IR. Durable jobs bind an immutable
+release to resumable, idempotent result retrieval. See [remote protocol](remote_protocol.md)
+and [durable jobs](job_protocol.md) for request formats and error semantics.
+
+## Offline verification
+
+```bash
+ANNO_RUN_LIVE_TESTS=0 python -m annoscript.client_tests -q
+ANNO_RUN_LIVE_TESTS=0 python -m unittest discover -q
+python -m annoscript.grammar_tests -v
+python -m annoscript.cross_version_tests --client-python /path/to/python3.10 --server-python /path/to/python3.12
+python -m annoscript.job_cross_version_tests --client-python /path/to/python3.10 --server-python /path/to/python3.12
+```
+
+The CPU grammar suite requires Python 3.12 and `requirements-test-grammar.txt`.
+Cross-version checks use loopback HTTP and deterministic model doubles. They do
+not require provider credentials or download models. Additional pinned decoder
+acceptance instructions are in [third_party/xgrammar](third_party/xgrammar/README.md).
+
+See [motivation](motivation.md) and [operator interfaces](design_api.md) for the
+design rationale and API contracts.

annoscript-0.1.0/README.md

@@ -0,0 +1,118 @@
+# AnnoScript: Programmable AI Annotation
+
+AnnoScript compiles Python annotation programs into a serializable intermediate
+representation and an execution plan. Decision operations and generation
+operations can use separate model backends while sharing program state.
+
+The client supports Python 3.10+. Runtime and server execution require Python 3.12+.
+
+## Install
+
+```bash
+pip install annoscript
+# Local execution and the durable server (Python 3.12+):
+pip install 'annoscript[server]'
+# Optional pinned local tokenizer support:
+pip install 'annoscript[tokenizer]'
+```
+
+Python imports use `annoscript`, for example `from annoscript.client import AnnoClient`.
+The eDSL context is `annoscript.anno.Anno`; the runtime and durable-job clients are
+`AnnoRuntime`, `AnnoJobClient`, and `AnnoRemoteClient` in their corresponding modules.
+This release replaces the former Lev Python namespace. Version-1 serialized IR,
+execution plans, durable-job protocols and the `legacy` backend profile remain compatible.
+
+## Synthetic example
+
+`annoscript_examples.request.annotate` classifies a synthetic document, conditionally
+generates a title, and produces tags and source spans. The example demonstrates
+all six operators without requiring an application dataset.
+
+```bash
+python -m annoscript.inspect annoscript_examples/request.json --show-source
+python -m annoscript.inspect annoscript_examples/request.execution_plan.json
+python -m annoscript.inspect annoscript_examples/request.execution_plan.json --format html -o /tmp/lev-plan.html
+```
+
+To regenerate the saved example with Python 3.12:
+
+```python
+from pathlib import Path
+from annoscript.compiler import compile_program
+from annoscript.plan_lowering import lower_to_plan
+from annoscript_examples.request import annotate
+
+program = compile_program(annotate)
+Path("annoscript_examples/request.json").write_text(program.to_json(indent=2) + "\n")
+Path("annoscript_examples/request.execution_plan.json").write_text(lower_to_plan(program).to_json(indent=2) + "\n")
+```
+
+## Configuration
+
+Install `requirements.txt` for the client and `requirements-server.txt` for
+local execution or the durable job server. Copy `.credential.example` to an
+ignored local file and supply the desired endpoints and model names.
+Environment variables override values from an explicitly supplied environment file.
+Canonical `ANNO_*` keys take precedence over legacy `LEV_*` aliases within the same
+layer. Process environment values override file values regardless of their prefix;
+explicit API arguments take precedence over both. Credentials stay outside packages.
+
+| Variable | Purpose |
+| --- | --- |
+| `ANNO_DECISION_BASE_URL` | Decision provider URL |
+| `ANNO_DECISION_AUTH_TOKEN` | Decision provider credential |
+| `ANNO_DECISION_MODEL` | Decision model identifier |
+| `ANNO_GENERATE_BASE_URL` | Generation provider URL |
+| `ANNO_GENERATE_AUTH_TOKEN` | Generation provider credential |
+| `ANNO_GENERATE_MODEL` | Generation model identifier |
+| `ANNO_GENERATE_PROFILE` | `legacy` (default) or `qwen_vllm` wire protocol |
+| `ANNO_GENERATE_TOKENIZER_DIR` | Caller-provided tokenizer directory when required by policy |
+
+Keep live service settings and credentials outside version control.
+The `legacy` profile name describes a supported request protocol.
+
+```bash
+python -m annoscript_examples.run --env-file .credential --inputs /tmp/documents.json --mode speculative
+```
+
+This command calls the caller's configured services. Inspecting IR, previewing
+resolved requests and running the offline tests do not call model services.
+
+## Execution and backends
+
+Programs use `choice`, `noul`, `score`, `generate`, `generate_list` and `extract`.
+`constrain` declares hard runtime constraints. `system_prompt` supplies shared
+instructions; preconditions validate inputs locally before dispatch.
+
+`AnnoClient` supports strict, eager and speculative execution. The runtime
+handles bounded concurrency, batching, cancellation, repair and result ordering.
+Examples, field names, nullable output and per-call requirements are included in
+the IR and execution-plan bindings. Decision and generation request adapters
+are explicitly selectable and can be inspected without dispatch.
+
+```bash
+python -m annoscript.preview annoscript_examples/request_preview.decision.json
+python -m annoscript.preview annoscript_examples/request_preview.generation.json
+```
+
+Remote execution exchanges serialized IR. Durable jobs bind an immutable
+release to resumable, idempotent result retrieval. See [remote protocol](remote_protocol.md)
+and [durable jobs](job_protocol.md) for request formats and error semantics.
+
+## Offline verification
+
+```bash
+ANNO_RUN_LIVE_TESTS=0 python -m annoscript.client_tests -q
+ANNO_RUN_LIVE_TESTS=0 python -m unittest discover -q
+python -m annoscript.grammar_tests -v
+python -m annoscript.cross_version_tests --client-python /path/to/python3.10 --server-python /path/to/python3.12
+python -m annoscript.job_cross_version_tests --client-python /path/to/python3.10 --server-python /path/to/python3.12
+```
+
+The CPU grammar suite requires Python 3.12 and `requirements-test-grammar.txt`.
+Cross-version checks use loopback HTTP and deterministic model doubles. They do
+not require provider credentials or download models. Additional pinned decoder
+acceptance instructions are in [third_party/xgrammar](third_party/xgrammar/README.md).
+
+See [motivation](motivation.md) and [operator interfaces](design_api.md) for the
+design rationale and API contracts.

annoscript-0.1.0/annoscript/__init__.py

@@ -0,0 +1 @@
+"""AnnoScript's Python eDSL, compiler, execution plans and API-backed runtime."""

annoscript-0.1.0/annoscript/_backend_profiles.py

@@ -0,0 +1,17 @@
+"""Generation wire profiles shared by configuration readers; no backend imports."""
+
+GENERATION_PROFILES = ("legacy", "qwen_vllm")
+
+
+def validate_extract_mode(mode, profile):
+    if type(mode) is not str or mode not in ("validated", "substring_chars"):
+        raise ValueError("extract_mode must be validated or substring_chars")
+    if mode == "substring_chars" and profile != "qwen_vllm":
+        raise ValueError("substring_chars requires qwen_vllm")
+    return mode
+
+
+def validate_generation_profile(profile):
+    if type(profile) is not str or profile not in GENERATION_PROFILES:
+        raise ValueError("generation profile must be legacy or qwen_vllm")
+    return profile

annoscript-0.1.0/annoscript/_client_common.py

@@ -0,0 +1,287 @@
+"""Python 3.10+ contracts shared by local and remote clients; no execution imports."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from types import FunctionType, TracebackType
+from typing import Generic, List, Literal, TypeAlias, TypeVar
+from weakref import WeakKeyDictionary
+
+from annoscript.anno import Anno
+
+
+JSONValue: TypeAlias = (
+    str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+)
+State: TypeAlias = str | list[JSONValue] | dict[str, JSONValue]
+R = TypeVar("R", bound=JSONValue)
+InputCheck: TypeAlias = Callable[[State], None]
+
+# Keep local checks outside the program function's attributes and execution body.
+_PRECONDITIONS: WeakKeyDictionary[
+    Callable[[Anno], JSONValue], tuple[InputCheck, ...]
+] = WeakKeyDictionary()
+# Only this registry's text values are exported as remote program configuration.
+_SYSTEM_PROMPTS: WeakKeyDictionary[Callable[[Anno], JSONValue], str] = WeakKeyDictionary()
+
+
+class InputValidationError(ValueError):
+    """An input failed a client-local precondition, before remote submission."""
+
+
+def require(condition: bool, *, message: str) -> None:
+    """Check an input condition locally; raise InputValidationError on failure.
+
+    This ordinary Python function remains active under optimization. It never
+    invokes inference, repairs inputs, or propagates constraints to the eDSL.
+    """
+    if not condition:
+        raise InputValidationError(message)
+
+
+def precondition(
+    check: InputCheck,
+) -> Callable[[Callable[[Anno], R]], Callable[[Anno], R]]:
+    """Register a client-local input check and return the original program.
+
+    Checks are synchronous, deterministic, read-only Python functions. Return
+    None for success and raise InputValidationError for an invalid input. Other
+    exceptions indicate a checker defect and abort submission. Checks must not
+    invoke models or make network requests.
+
+    Registration does not run checks or wrap the program. Direct program calls
+    do not run checks; AnnoClient implementations run them before any remote
+    submission. Stacked decorators are checked in source order (top to bottom),
+    stopping at the first failed check for each input.
+
+    The registry is local only. Remote program packaging must exclude these
+    decorator declarations, check functions, and their validation dependencies.
+    """
+    if not callable(check):
+        raise TypeError("precondition requires a callable input check")
+
+    def register(program: Callable[[Anno], R]) -> Callable[[Anno], R]:
+        if not isinstance(program, FunctionType):
+            raise TypeError("precondition must decorate a Python function")
+        _PRECONDITIONS[program] = (check,) + _PRECONDITIONS.get(program, ())
+        return program
+
+    return register
+
+
+def system_prompt(
+    prompt: str,
+) -> Callable[[Callable[[Anno], R]], Callable[[Anno], R]]:
+    """Declare shared model instructions and return the original program.
+
+    The client exports this text as program configuration. The runtime binds it
+    to every record's injected AnnoScript and applies it to LLM operations, including
+    calls inside helper functions. Decision requests use their own instructions
+    and requirements. API guarantees and hard constraints remain independently
+    enforced. Mapping shared instructions to a model is the runtime's job.
+
+    Registration neither wraps nor executes the program and creates no context.
+    Direct Python calls do not inject the prompt. Each program may declare one
+    system prompt; any repeated declaration raises ValueError. Empty strings
+    are allowed and preserved. Prompt text is sent as configuration, without
+    executing the decorator remotely or exporting local precondition checks.
+    """
+    if not isinstance(prompt, str):
+        raise TypeError("system_prompt requires a string")
+
+    def register(program: Callable[[Anno], R]) -> Callable[[Anno], R]:
+        if not isinstance(program, FunctionType):
+            raise TypeError("system_prompt must decorate a Python function")
+        if program in _SYSTEM_PROMPTS:
+            raise ValueError("a program may declare only one system_prompt")
+        _SYSTEM_PROMPTS[program] = prompt
+        return program
+
+    return register
+
+
+@dataclass(frozen=True)
+class ResultError:
+    """A per-input failure, including local validation or unsatisfied constraints."""
+
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Result(Generic[R]):
+    """One terminal outcome, identified by its zero-based input index.
+
+    Success preserves the program's return value, including ``None``. An error
+    carries no value. A list-valued result stays one result, not multiple items.
+    """
+
+    index: int
+    status: Literal["success", "error"]
+    value: R | None = None
+    error: ResultError | None = None
+
+    def __post_init__(self) -> None:
+        if type(self.index) is not int or self.index < 0:
+            raise ValueError("index must be a nonnegative integer")
+        if self.status == "success":
+            if self.error is not None:
+                raise ValueError("a successful result cannot contain an error")
+        elif self.status == "error":
+            if not isinstance(self.error, ResultError) or self.value is not None:
+                raise ValueError("an error result requires ResultError and no value")
+        else:
+            raise ValueError("status must be 'success' or 'error'")
+
+
+class ResultStream(Iterator[Result[R]], ABC):
+    """A single-pass result iterator with explicit resource ownership.
+
+    Use ``with`` when stopping early: breaking a plain ``for`` loop does not
+    close the stream. Exhaustion and iteration errors automatically close it.
+    Concrete transports implement ``_next_result`` and ``_close`` and call
+    ``super().__init__()`` when overriding construction.
+
+    Streams are intended for consumption and closure by a single thread.
+    """
+
+    def __init__(self) -> None:
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def __iter__(self) -> ResultStream[R]:
+        return self
+
+    def __next__(self) -> Result[R]:
+        if self._closed:
+            raise StopIteration
+        try:
+            return self._next_result()
+        except StopIteration:
+            self.close()
+            raise
+        except BaseException:
+            try:
+                self.close()
+            except BaseException:
+                import logging
+                logging.getLogger(__name__).warning("Result cleanup failed while handling another exception")
+            raise
+
+    def close(self) -> None:
+        """Stop receiving results and release resources; repeated calls are harmless.
+
+        Closing discards undelivered results. No further work may be submitted.
+        The transport should request cancellation of pending
+        work, without promising that already-running remote work can be stopped.
+        The stream stays closed even if transport cleanup raises an exception.
+        """
+        if not self._closed:
+            self._closed = True
+            self._close()
+
+    def __enter__(self) -> ResultStream[R]:
+        if self._closed:
+            raise RuntimeError("cannot enter a closed result stream")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        if exc_type is None:
+            self.close()
+        else:
+            try:
+                self.close()
+            except BaseException:
+                import logging
+                logging.getLogger(__name__).warning("Result cleanup failed while handling another exception")
+        return False
+
+    @abstractmethod
+    def _next_result(self) -> Result[R]:
+        """Return the next result, or raise StopIteration when fully exhausted.
+
+        Return per-input failures as error results. Raise submission-level or
+        transport failures as exceptions; the stream will then close itself.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def _close(self) -> None:
+        """Release local resources and request cancellation, at most once.
+
+        This hook must not submit new work or wait for unfinished work to
+        complete. It is also called after normal exhaustion or iteration errors.
+        """
+        raise NotImplementedError
+
+
+def get_program_config(program: Callable[[Anno], R]) -> dict[str, JSONValue]:
+    """Return fresh, JSON-compatible execution settings for remote submission.
+
+    Export system-prompt text only, never local check functions or rules.
+    Programs without a declaration have no system_prompt configuration key.
+    Reading configuration does not execute the program or its preconditions.
+    """
+    prompt = _SYSTEM_PROMPTS.get(program)
+    return {} if prompt is None else {"system_prompt": prompt}
+
+
+def validate_inputs(
+    program: Callable[[Anno], R], inputs: List[State]
+) -> dict[int, ResultError]:
+    """Run the whole batch's preconditions locally, without running program.
+
+    Call before any remote submission. Return invalid-input errors keyed by
+    original list index; the remaining indices passed all registered checks.
+    Only InputValidationError becomes an item error. Unexpected exceptions
+    and non-None check returns abort validation and must prevent submission.
+
+    This helper validates the outer list and program-specific preconditions.
+    Concrete clients also validate the generic JSON input contract.
+    """
+    if not isinstance(inputs, list):
+        raise TypeError("inputs must be a list")
+    checks = _PRECONDITIONS.get(program, ())
+    errors = {}
+    for index, state in enumerate(inputs):
+        try:
+            for check in checks:
+                if check(state) is not None:
+                    raise TypeError("precondition checks must return None on success")
+        except InputValidationError as error:
+            errors[index] = ResultError(code="invalid_input", message=str(error))
+    return errors
+
+
+def prepare_inputs(program, inputs):
+    """Snapshot JSON inputs, then check all valid shapes before any submission.
+
+    Return (indexed states, local errors), retaining the original input indices.
+    Unexpected checker exceptions propagate before either client dispatches work.
+    """
+    from annoscript._data import snapshot
+
+    if not isinstance(inputs, list):
+        raise TypeError("inputs must be a list")
+    errors, valid = {}, []
+    for index, state in enumerate(inputs):
+        try:
+            valid.append((index, snapshot(state, state=True)))
+        except (ValueError, RecursionError):
+            errors[index] = ResultError(
+                "invalid_input",
+                "input must contain finite JSON data and have string, array or object shape",
+            )
+    checked = validate_inputs(program, [state for _, state in valid])
+    errors.update({valid[i][0]: error for i, error in checked.items()})
+    return [item for i, item in enumerate(valid) if i not in checked], errors

annoscript-0.1.0/annoscript/_data.py

@@ -0,0 +1,37 @@
+"""JSON snapshots and immutable inference payloads; no application code runs here."""
+
+import math
+from types import MappingProxyType
+from collections.abc import Mapping
+
+
+def snapshot(value, path="$", *, state=False):
+    if state and type(value) not in (str, list, dict):
+        raise ValueError(f"{path}: input must be a string, list or object")
+    if value is None or type(value) in (str, bool, int):
+        return value
+    if type(value) is float and math.isfinite(value):
+        return value
+    if type(value) is list:
+        return [snapshot(v, f"{path}[{i}]") for i, v in enumerate(value)]
+    if type(value) is dict:
+        if any(type(k) is not str for k in value):
+            raise ValueError(f"{path}: object keys must be strings")
+        return {k: snapshot(v, f"{path}.{k}") for k, v in value.items()}
+    raise ValueError(f"{path}: expected finite JSON data")
+
+
+def freeze(value):
+    if isinstance(value, Mapping):
+        return MappingProxyType({k: freeze(v) for k, v in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(freeze(v) for v in value)
+    return value
+
+
+def thaw(value):
+    if isinstance(value, Mapping):
+        return {k: thaw(v) for k, v in value.items()}
+    if isinstance(value, tuple):
+        return [thaw(v) for v in value]
+    return value