----------------------------------------------------------------------
This is the API documentation for the recap library.
----------------------------------------------------------------------


## Client

Local and remote clients, namespace context, and permissions.


RecapClient(connection_state: recap.client.connection_state.ConnectionState, *, namespace_path: str | None = None, namespace_context: recap.schemas.namespace.NamespaceContext | None = None)

Primary entry point for interacting with a RECAP provenance database.

``RecapClient`` wraps a SQLAlchemy session and exposes factory methods for
creating and loading the core domain objects: namespaces, resources,
resource templates, process templates, and process runs.

Use :meth:`from_sqlite` for local SQLite databases and :meth:`from_url` for
remote recap servers. These are the canonical initialization methods.

The client can be used as a context manager, which closes the underlying
engine on exit:

    with RecapClient.from_sqlite() as client:
        client.create_namespace("projects")
        client.create_namespace("projects/my-project")

ActorPermissions(*, identities: tuple[recap.authentication.models.ProviderIdentity, ...], snapshot_generation: str | None, effective_scopes: frozenset[recap.authorization.scopes.Scope], matched_namespace_paths: tuple[str, ...], groups: tuple[str, ...], roles: tuple[str, ...]) -> None

Current actor's effective permissions returned by remote APIs.

EffectivePermissions(*, identities: tuple[recap.authentication.models.ProviderIdentity, ...], snapshot_generation: str | None, effective_scopes: frozenset[recap.authorization.scopes.Scope], matched_namespace_paths: tuple[str, ...], grants: tuple[recap.authorization.snapshot.GrantProvenance, ...]) -> None

PermissionDecision(*, allowed: bool, denial_code: recap.client.permissions.DenialCode | None = None, permissions: recap.client.permissions.EffectivePermissions | None = None) -> None

DenialCode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)


## Queries

Immutable query composition and field predicates.


QueryDSL(backend: 'ReadBackend', *, context: recap.schemas.namespace.NamespaceContext, on_unloaded: Literal['silent', 'warn', 'raise'] = 'warn')

Factory for namespace-scoped query families.

Field(path: str)

Typed query-field expression builder.

Comparisons create immutable :class:`FieldPredicate` values; ``asc`` and
``desc`` create :class:`FieldOrdering` values. Use query ``where`` calls
for AND semantics instead of Python ``and``/``or``.

FieldPredicate(*, field: str, op: Literal['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in', 'contains', 'starts_with', 'ends_with'], value: Any) -> None

Serializable field comparison used by :meth:`BaseQuery.where`.

FieldOrdering(*, field: str, direction: Literal['asc', 'desc'] = 'asc') -> None

Serializable ascending or descending field ordering.

BaseQuery(backend: 'ReadBackend', *, context: recap.schemas.namespace.NamespaceContext, model: type[~SchemaT] | None = None, filters: dict[str, typing.Any] | None = None, predicates: list[typing.Any] | None = None, orderings: list[typing.Any] | None = None, preloads: list[str] | None = None, limit: int | None = None, offset: int | None = None, property_filters: list[recap.dsl.query.PropertyFilter] | None = None, parent_resource_id: uuid.UUID | None = None, parameter_filters: list[recap.dsl.query.ParameterFilter] | None = None, include_archived: bool = False, local_metadata_filters: dict[str, typing.Any] | None = None, effective_metadata_filters: dict[str, typing.Any] | None = None, load_mode: Optional[Literal['none', 'eager']] = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None)

Immutable query base with filtering, pagination, loading, and execution.

NamespaceQuery(backend: 'ReadBackend', *, context: recap.schemas.namespace.NamespaceContext, model: type[~SchemaT] | None = None, filters: dict[str, typing.Any] | None = None, predicates: list[typing.Any] | None = None, orderings: list[typing.Any] | None = None, preloads: list[str] | None = None, limit: int | None = None, offset: int | None = None, property_filters: list[recap.dsl.query.PropertyFilter] | None = None, parent_resource_id: uuid.UUID | None = None, parameter_filters: list[recap.dsl.query.ParameterFilter] | None = None, include_archived: bool = False, local_metadata_filters: dict[str, typing.Any] | None = None, effective_metadata_filters: dict[str, typing.Any] | None = None, load_mode: Optional[Literal['none', 'eager']] = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None)

Query namespaces, including local and effective metadata filters.

ResourceQuery(backend: 'ReadBackend', *, shape: Literal['full', 'ref', 'schema'] = 'full', load: Literal['none', 'eager', 'full'] = 'none', expand: bool | None = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None, **kwargs)

Query resources, properties, templates, and parent relationships.

ResourceTemplateQuery(backend: 'ReadBackend', *, shape: Literal['full', 'ref', 'schema'] = 'full', load: Literal['none', 'eager', 'full'] = 'none', expand: bool | None = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None, **kwargs)

Query resource templates and optionally hydrate child relationships.

ProcessTemplateQuery(backend: 'ReadBackend', *, shape: Literal['full', 'ref', 'schema'] = 'full', load: Literal['none', 'eager', 'full'] = 'none', expand: bool | None = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None, **kwargs)

Query process templates and optionally hydrate steps and slots.

ProcessRunQuery(backend: 'ReadBackend', *, shape: Literal['full', 'ref', 'schema'] = 'full', load: Literal['none', 'eager', 'full'] = 'none', expand: bool | None = None, on_unloaded: Optional[Literal['silent', 'warn', 'raise']] = None, **kwargs)

Query process runs with optional steps, resources, and parameters.


## Builders

Context-managed resource and process builders.


ResourceTemplateBuilder(name: str | None, type_names: list[str] | None = None, version: str = '1.0', parent: Optional[ForwardRef('ResourceTemplateBuilder')] = None, *, backend: recap.client.backend.ClientBackend, namespace_context: recap.schemas.namespace.NamespaceContext, resource_template_id: uuid.UUID | None = None, on_existing: Literal['silent', 'warn', 'raise'] = 'warn', command_context: recap.commands.models.CommandContext)

ResourceBuilder(name: str | None, template_name: str | None, template_version: str = '1.0', *, backend: recap.client.backend.ClientBackend, namespace_context: recap.schemas.namespace.NamespaceContext, parent: 'ResourceBuilder | ResourceSchema | None' = None, resource_id: uuid.UUID | None = None, on_existing: Literal['create', 'silent', 'warn', 'raise'] = 'warn', command_context: recap.commands.models.CommandContext, transaction: recap.dsl.builder_state.BuilderTransactionState | None = None)

ProcessTemplateBuilder(name: str | None, version: str | None, *, backend: recap.client.backend.ClientBackend, namespace_context: recap.schemas.namespace.NamespaceContext, command_context: recap.commands.models.CommandContext, process_template_id: uuid.UUID | None = None, on_existing: Literal['silent', 'warn', 'raise'] = 'warn')

Builder for process templates, resource slots, and step templates.

Context-manager exit commits clean work and rolls back exceptions. Existing
templates load by UUID; ``on_existing`` controls identity reuse, while draft
validation reports invalid slots, steps, or parameters before submission.

StepTemplateBuilder(parent: recap.dsl.process_builder.ProcessTemplateBuilder, step_template: recap.schemas.step.StepTemplateSchema | None = None, draft_name: str | None = None)

Scoped editor for one step's parameter groups and resource bindings.

ProcessRunBuilder(name: str | None, description: str | None, template_name: str | None, version: str | None = None, *, backend: recap.client.backend.ClientBackend, namespace_context: recap.schemas.namespace.NamespaceContext, process_run_id: uuid.UUID | None = None, on_existing: Literal['silent', 'warn', 'raise'] = 'warn', command_context: recap.commands.models.CommandContext, template_id: uuid.UUID | None = None)

Builder for process-run assignments, parameters, and child steps.

Clean context-manager exit commits and exception exit rolls back local work;
command-backed remote builders submit validated drafts. UUID loading,
``on_existing``, lifecycle methods, and validation errors are preserved.

AttributeGroupBuilder(group_name: str, parent: ~ParentType)


## Models and Lifecycle

Public schemas, lifecycle state, directions, and copy options.


LifecycleStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Monotonic lifecycle state for persisted RECAP entities.

Direction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Direction of resource flow through a process step.

validate_transition(source: recap.lifecycle.LifecycleStatus, target: recap.lifecycle.LifecycleStatus) -> None

Validate lifecycle transition, allowing idempotent same-state updates.

Parameters
----------
source, target
    Current and requested lifecycle states.

Raises
------
ValueError
    If transition would move an entity backwards or out of ``ARCHIVED``.

NamespaceRef(*, id: uuid.UUID, path: str) -> None

Lightweight namespace identity used in relationships and query results.

NamespaceContext(*, id: uuid.UUID, path: str, metadata_json: dict[str, typing.Any] = <factory>, status: recap.lifecycle.LifecycleStatus | None = None, revision: int | None = None, etag: str | None = None) -> None

Active namespace scope attached to client queries and writes.

NamespaceSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], path: str, parent_id: uuid.UUID | None = None, status: recap.lifecycle.LifecycleStatus, revision: int, metadata_json: dict[str, typing.Any] = <factory>) -> None

Persisted namespace with lifecycle, hierarchy, and metadata fields.

ResourceTypeSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field']) -> None

A type tag associated with a resource or resource template.

Resources can carry multiple type tags (e.g. ``"container"``,
``"plate"``, ``"library_plate"``).  Process template resource slots
filter compatible resources by matching against these tags.

Attributes:
    name: The type tag string (e.g. ``"library_plate"``).

ResourceCopyChanges(*, properties: dict[str, dict[str, typing.Any]] = <factory>) -> None

Property changes applied while copying a resource.

ResourceCopyOptions(*, name: str | None = None, parent_id: uuid.UUID | None = None, changes: recap.schemas.resource.ResourceCopyChanges = <factory>) -> None

Name, parent, and property overrides for a resource copy operation.

ResourceTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], slug: typing.Annotated[str | None, 'simple_field'] = None, version: typing.Annotated[str, 'simple_field'], labels: typing.Annotated[list[str], 'simple_field', BeforeValidator(func=<function <lambda> at 0x7f15cdca8ae0>, json_schema_input_type=PydanticUndefined)] = <factory>, types: list[recap.schemas.resource.ResourceTypeSchema] = <factory>, parent: recap.schemas.resource.ResourceTemplateRef | None = None, children: dict[str, typing.Self] = <factory>, attribute_group_templates: list[recap.schemas.attribute.AttributeGroupTemplateSchema] = <factory>) -> None

Full blueprint for a category of resources.

Defines the complete structure of a resource: its type tags, optional
parent template, child templates (and their own property groups), and
the attribute group templates whose property groups will be instantiated
on every resource created from this template.

Attributes:
    name: Unique human-readable template name.
    slug: Snake_case identifier derived from *name*.
    version: Version string (e.g. ``"1.0"``).
    types: List of :class:`ResourceTypeSchema` tags.
    parent: Reference to the parent template, excluded from serialisation.
    children: Mapping of child name → child :class:`ResourceTemplateSchema`
        for nested resource hierarchies (e.g. wells inside a plate).
    attribute_group_templates: Property group blueprints that will be
        instantiated on each :class:`ResourceSchema`.

ResourceTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], slug: typing.Annotated[str | None, 'simple_field'] = None, version: typing.Annotated[str, 'simple_field'], labels: typing.Annotated[list[str], 'simple_field', BeforeValidator(func=<function <lambda> at 0x7f15cdca8ae0>, json_schema_input_type=PydanticUndefined)] = <factory>, types: list[recap.schemas.resource.ResourceTypeSchema] = <factory>, parent: recap.schemas.resource.ResourceTemplateRef | None = None, children: dict[str, typing.Self] = <factory>, attribute_group_templates: list[recap.schemas.attribute.AttributeGroupTemplateSchema] = <factory>) -> None

Full blueprint for a category of resources.

Defines the complete structure of a resource: its type tags, optional
parent template, child templates (and their own property groups), and
the attribute group templates whose property groups will be instantiated
on every resource created from this template.

Attributes:
    name: Unique human-readable template name.
    slug: Snake_case identifier derived from *name*.
    version: Version string (e.g. ``"1.0"``).
    types: List of :class:`ResourceTypeSchema` tags.
    parent: Reference to the parent template, excluded from serialisation.
    children: Mapping of child name → child :class:`ResourceTemplateSchema`
        for nested resource hierarchies (e.g. wells inside a plate).
    attribute_group_templates: Property group blueprints that will be
        instantiated on each :class:`ResourceSchema`.

ResourceSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], copied_from_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, template: recap.schemas.resource.ResourceTemplateSchema | None = None, parent: recap.schemas.resource.ResourceSchema | None = None, children: dict[str, typing.Self] = <factory>, properties: pydantic.main.BaseModel | dict[str, recap.schemas.resource.PropertySchema] = <factory>) -> None

A concrete resource instance created from a :class:`ResourceTemplateSchema`.

Resources are the primary trackable entities in RECAP.  They can represent
physical objects (plates, samples), digital artifacts (data files), or
logical items (computed results).  Every resource carries:

* An identity (:attr:`~recap.schemas.common.CommonFields.id`,
  :attr:`name`).
* A reference to the template it was created from.
* A hierarchy of child resources (auto-created from the template).
* Property groups populated with live :class:`~recap.schemas.attribute.AttributeValueSchema`
  values.

Accessing and updating properties::

    well = plate.children["A01"]
    well.properties.content.volume.value   # 10.0
    well.properties.content.volume = 8.5   # mutates in-place

Attributes:
    name: Display name of this resource instance.
    template: The :class:`ResourceTemplateSchema` this instance was
        created from.
    parent: Lightweight reference to the parent resource, or ``None``
        for top-level resources.  Excluded from serialisation.
    children: Mapping of child name → child :class:`ResourceSchema`.
    properties: A dynamically-generated Pydantic model whose fields are
        the property group slugs, each holding a
        :class:`PropertySchema`.

ResourceSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], copied_from_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, template: recap.schemas.resource.ResourceTemplateSchema | None = None, parent: recap.schemas.resource.ResourceSchema | None = None, children: dict[str, typing.Self] = <factory>, properties: pydantic.main.BaseModel | dict[str, recap.schemas.resource.PropertySchema] = <factory>) -> None

A concrete resource instance created from a :class:`ResourceTemplateSchema`.

Resources are the primary trackable entities in RECAP.  They can represent
physical objects (plates, samples), digital artifacts (data files), or
logical items (computed results).  Every resource carries:

* An identity (:attr:`~recap.schemas.common.CommonFields.id`,
  :attr:`name`).
* A reference to the template it was created from.
* A hierarchy of child resources (auto-created from the template).
* Property groups populated with live :class:`~recap.schemas.attribute.AttributeValueSchema`
  values.

Accessing and updating properties::

    well = plate.children["A01"]
    well.properties.content.volume.value   # 10.0
    well.properties.content.volume = 8.5   # mutates in-place

Attributes:
    name: Display name of this resource instance.
    template: The :class:`ResourceTemplateSchema` this instance was
        created from.
    parent: Lightweight reference to the parent resource, or ``None``
        for top-level resources.  Excluded from serialisation.
    children: Mapping of child name → child :class:`ResourceSchema`.
    properties: A dynamically-generated Pydantic model whose fields are
        the property group slugs, each holding a
        :class:`PropertySchema`.

ResourceAssignmentSchema(*, slot: recap.schemas.resource.ResourceSlotSchema, resource: recap.schemas.resource.ResourceSchema, step_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None) -> None

Represents the assignment of a resource to a slot in a process run.

When a :class:`~recap.schemas.process.ProcessRunSchema` is executed,
resources are bound to the resource slots declared on the process template.
Each :class:`ResourceAssignmentSchema` captures one such binding.

Attributes:
    slot: The :class:`ResourceSlotSchema` the resource is assigned to.
    resource: The :class:`ResourceSchema` that was assigned.
    step_id: UUID of the specific step this assignment is scoped to,
        or ``None`` if the assignment spans the entire process run.

ProcessTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], version: typing.Annotated[str, 'simple_field'], labels: typing.Annotated[list[str], 'simple_field', BeforeValidator(func=<function <lambda> at 0x7f15cdca8ae0>, json_schema_input_type=PydanticUndefined)] = [], step_templates: dict[str, recap.schemas.step.StepTemplateSchema] = {}, resource_slots: list[recap.schemas.resource.ResourceSlotSchema] = []) -> None

Blueprint for a workflow, defining its ordered steps and resource slots.

A :class:`ProcessTemplateSchema` is created once and reused across
multiple :class:`ProcessRunSchema` instances.  It declares:

* An ordered set of :class:`~recap.schemas.step.StepTemplateSchema`
  instances that represent the phases of the workflow.
* A list of :class:`~recap.schemas.resource.ResourceSlotSchema` entries
  that specify which resource types can be assigned to the process and
  in which direction (input / output).

Attributes:
    name: Unique human-readable template name.
    version: Version string (e.g. ``"1.0"``).
    is_active: When ``False`` the template is retired and new runs cannot
        be created against it.
    step_templates: Ordered mapping of step name →
        :class:`~recap.schemas.step.StepTemplateSchema`.
    resource_slots: List of
        :class:`~recap.schemas.resource.ResourceSlotSchema` entries
        declaring the typed input/output slots.

ProcessTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], version: typing.Annotated[str, 'simple_field'], labels: typing.Annotated[list[str], 'simple_field', BeforeValidator(func=<function <lambda> at 0x7f15cdca8ae0>, json_schema_input_type=PydanticUndefined)] = [], step_templates: dict[str, recap.schemas.step.StepTemplateSchema] = {}, resource_slots: list[recap.schemas.resource.ResourceSlotSchema] = []) -> None

Blueprint for a workflow, defining its ordered steps and resource slots.

A :class:`ProcessTemplateSchema` is created once and reused across
multiple :class:`ProcessRunSchema` instances.  It declares:

* An ordered set of :class:`~recap.schemas.step.StepTemplateSchema`
  instances that represent the phases of the workflow.
* A list of :class:`~recap.schemas.resource.ResourceSlotSchema` entries
  that specify which resource types can be assigned to the process and
  in which direction (input / output).

Attributes:
    name: Unique human-readable template name.
    version: Version string (e.g. ``"1.0"``).
    is_active: When ``False`` the template is retired and new runs cannot
        be created against it.
    step_templates: Ordered mapping of step name →
        :class:`~recap.schemas.step.StepTemplateSchema`.
    resource_slots: List of
        :class:`~recap.schemas.resource.ResourceSlotSchema` entries
        declaring the typed input/output slots.

ProcessRunSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], description: typing.Annotated[str, 'simple_field'] = '', copied_from_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, template: recap.schemas.process.ProcessTemplateSchema | None = None, steps: dict[str, recap.schemas.step.StepSchema] = {}, assigned_resources: dict[str, recap.schemas.resource.ResourceAssignmentSchema] = {}) -> None

A concrete execution of a :class:`ProcessTemplateSchema`.

A :class:`ProcessRunSchema` is the primary provenance record.  It links
together:

* The workflow that was executed (``template``).
* The resources that were used (``assigned_resources``).
* The parameter values captured at each step (``steps``).
* The namespace it belongs to (``namespace_id``).

Chain multiple process runs by using the output resource of one run as
the input of the next, creating a queryable provenance graph.

Attributes:
    name: Display name for this run (e.g. ``"Run 001"``).
    description: Free-text description of what this run represents.
    namespace_id: UUID of the owning Namespace.
    template: The :class:`ProcessTemplateSchema` this run instantiates.
    steps: Mapping of step name → :class:`~recap.schemas.step.StepSchema`
        with live parameter values.
    assigned_resources: Mapping of slot name →
        :class:`~recap.schemas.resource.ResourceAssignmentSchema`
        binding resources to their slots.  Keyed by
        :attr:`~recap.schemas.resource.ResourceSlotSchema.name` so that
        a specific assignment can be retrieved directly, e.g.
        ``run.assigned_resources["crystal_plate"]``.

ProcessRunSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], namespace_id: typing.Annotated[uuid.UUID, 'simple_field'], status: typing.Annotated[recap.lifecycle.LifecycleStatus, 'simple_field'], revision: typing.Annotated[int, 'simple_field'], name: typing.Annotated[str, 'simple_field'], description: typing.Annotated[str, 'simple_field'] = '', copied_from_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, template: recap.schemas.process.ProcessTemplateSchema | None = None, steps: dict[str, recap.schemas.step.StepSchema] = {}, assigned_resources: dict[str, recap.schemas.resource.ResourceAssignmentSchema] = {}) -> None

A concrete execution of a :class:`ProcessTemplateSchema`.

A :class:`ProcessRunSchema` is the primary provenance record.  It links
together:

* The workflow that was executed (``template``).
* The resources that were used (``assigned_resources``).
* The parameter values captured at each step (``steps``).
* The namespace it belongs to (``namespace_id``).

Chain multiple process runs by using the output resource of one run as
the input of the next, creating a queryable provenance graph.

Attributes:
    name: Display name for this run (e.g. ``"Run 001"``).
    description: Free-text description of what this run represents.
    namespace_id: UUID of the owning Namespace.
    template: The :class:`ProcessTemplateSchema` this run instantiates.
    steps: Mapping of step name → :class:`~recap.schemas.step.StepSchema`
        with live parameter values.
    assigned_resources: Mapping of slot name →
        :class:`~recap.schemas.resource.ResourceAssignmentSchema`
        binding resources to their slots.  Keyed by
        :attr:`~recap.schemas.resource.ResourceSlotSchema.name` so that
        a specific assignment can be retrieved directly, e.g.
        ``run.assigned_resources["crystal_plate"]``.

StepTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], attribute_group_templates: list[recap.schemas.attribute.AttributeGroupTemplateSchema] = [], resource_slots: dict[str, recap.schemas.resource.ResourceSlotSchema] = {}) -> None

Blueprint for a single workflow step within a process template.

Declares the parameter groups (attribute group templates) that capture
data recorded during execution of the step, and the resource slot roles
that map resources to their function within this particular step.

Attributes:
    name: Human-readable step name (e.g. ``"Echo Transfer"``).
    attribute_group_templates: Parameter group blueprints whose
        :class:`ParameterSchema` instances will be created when a
        :class:`StepSchema` is instantiated.
    resource_slots: Mapping of role name →
        :class:`~recap.schemas.resource.ResourceSlotSchema` describing
        which resources play which role in this step (e.g. ``"source"``
        and ``"destination"``).

StepTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], attribute_group_templates: list[recap.schemas.attribute.AttributeGroupTemplateSchema] = [], resource_slots: dict[str, recap.schemas.resource.ResourceSlotSchema] = {}) -> None

Blueprint for a single workflow step within a process template.

Declares the parameter groups (attribute group templates) that capture
data recorded during execution of the step, and the resource slot roles
that map resources to their function within this particular step.

Attributes:
    name: Human-readable step name (e.g. ``"Echo Transfer"``).
    attribute_group_templates: Parameter group blueprints whose
        :class:`ParameterSchema` instances will be created when a
        :class:`StepSchema` is instantiated.
    resource_slots: Mapping of role name →
        :class:`~recap.schemas.resource.ResourceSlotSchema` describing
        which resources play which role in this step (e.g. ``"source"``
        and ``"destination"``).

StepSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], template: recap.schemas.step.StepTemplateSchema | None = None, parameters: pydantic.main.BaseModel | dict[str, recap.schemas.step.ParameterSchema] = {}, state: typing.Annotated[recap.schemas.common.StepStatus, 'simple_field'] = <StepStatus.PENDING: 'PENDING'>, process_run_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, parent_id: typing.Annotated[uuid.UUID | None, 'simple_field'] = None, children: list[recap.schemas.step.StepSchema] = <factory>, resources: dict[str, recap.schemas.resource.ResourceSchema] = <factory>) -> None

A concrete step instance within a :class:`~recap.schemas.process.ProcessRunSchema`.

Each step corresponds to one :class:`StepTemplateSchema` from the parent
process template and carries the actual parameter values recorded during
execution, plus a lifecycle state.

Attributes:
    name: Step name, matching the template step name.
    template: The :class:`StepTemplateSchema` this step was created from.
    parameters: A dynamically-generated Pydantic model whose fields are
        the parameter group slugs, each holding a
        :class:`ParameterSchema` instance with live values.
    state: Current lifecycle state; one of
        :attr:`~recap.schemas.common.StepStatus.PENDING`,
        :attr:`~recap.schemas.common.StepStatus.IN_PROGRESS`, or
        :attr:`~recap.schemas.common.StepStatus.COMPLETE`.
    process_run_id: UUID of the parent
        :class:`~recap.schemas.process.ProcessRunSchema`.

ParameterSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], template: recap.schemas.attribute.AttributeGroupTemplateSchema, values: pydantic.main.BaseModel) -> None

A parameter group instance attached to a step.

Mirrors the structure of :class:`~recap.schemas.resource.PropertySchema`
but scoped to a process step rather than a resource.  Parameter values
record what settings were used when executing a step (e.g. transfer
volumes, imaging exposure times).

Parameter values are accessed via the ``step.parameters.<group_slug>``
shortcut::

    step.parameters.transfer.volume.value   # 100
    step.parameters.transfer.volume = 50    # mutate in-place

Attributes:
    template: The :class:`~recap.schemas.attribute.AttributeGroupTemplateSchema`
        that defines the parameters in this group.
    values: A dynamically-generated Pydantic model whose fields are
        the attribute slugs, each holding an
        :class:`~recap.schemas.attribute.AttributeValueSchema`.

AttributeTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], slug: typing.Annotated[str, 'simple_field'], value_type: Annotated[Literal['int', 'float', 'bool', 'str', 'datetime', 'array', 'enum'], 'simple_field'], unit: typing.Annotated[str | None, 'simple_field'], default_value: Annotated[Any, 'simple_field'], metadata_json: typing.Annotated[dict[str, typing.Any] | None, 'simple_field'] = <factory>) -> None

Persisted blueprint for a single typed attribute.

An :class:`AttributeTemplateSchema` belongs to an
:class:`AttributeGroupTemplateSchema` and defines the name, type, default
value, optional unit, and optional validation metadata for one data field.

Attributes:
    name: Human-readable attribute name (may contain spaces or mixed case).
    slug: Snake_case identifier derived from *name*, used for Python
        attribute access (e.g. ``prop.values.catalog_id``).
    value_type: One of the :data:`~recap.schemas.attribute.TypeName`
        literals — ``"int"``, ``"float"``, ``"bool"``, ``"str"``,
        ``"datetime"``, ``"array"``, or ``"enum"``.
    unit: Physical unit string (e.g. ``"uL"``), or ``None`` when
        the attribute is dimensionless.
    default_value: The value stored when a resource is instantiated
        without an explicit override.
    metadata: Optional dict carrying extra validation hints:

        - ``min`` / ``max`` — numeric bounds for ``int`` and ``float``.
        - ``choices`` — list of allowed strings for ``enum``.

AttributeGroupTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], slug: typing.Annotated[str, 'simple_field'], attribute_templates: list[recap.schemas.attribute.AttributeTemplateSchema] = []) -> None

A named group of :class:`AttributeTemplateSchema` instances.

Property groups organise related attributes together.  For example, a
``"content"`` group on a well resource might contain ``smiles``,
``catalog_id``, and ``volume``.

Attributes:
    name: Human-readable group name.
    slug: Snake_case identifier; used as the Python attribute on the
        ``properties`` object (e.g. ``resource.properties.content``).
    attribute_templates: Ordered list of attribute blueprints belonging
        to this group.

AttributeGroupTemplateSchema(*, id: typing.Annotated[uuid.UUID, 'simple_field'], create_date: typing.Annotated[datetime.datetime, 'simple_field'], modified_date: typing.Annotated[datetime.datetime, 'simple_field'], name: typing.Annotated[str, 'simple_field'], slug: typing.Annotated[str, 'simple_field'], attribute_templates: list[recap.schemas.attribute.AttributeTemplateSchema] = []) -> None

A named group of :class:`AttributeTemplateSchema` instances.

Property groups organise related attributes together.  For example, a
``"content"`` group on a well resource might contain ``smiles``,
``catalog_id``, and ``volume``.

Attributes:
    name: Human-readable group name.
    slug: Snake_case identifier; used as the Python attribute on the
        ``properties`` object (e.g. ``resource.properties.content``).
    attribute_templates: Ordered list of attribute blueprints belonging
        to this group.

AttributeValueSchema(*, value: Any = None, unit: str | None = None, metadata_json: dict[str, typing.Any] = <factory>) -> None

A single stored attribute value with an optional physical unit.

Instances of this class are what you read and write when accessing
resource properties or step parameters at runtime::

    well.properties.content.volume.value   # 10.0
    well.properties.content.volume.unit    # "uL"
    str(well.properties.content.volume)    # "10.0uL"

    # Mutate the value in-place (unit is preserved)
    well.properties.content.volume = 8.5

Attributes:
    value: The stored scalar value.  Type is validated against the
        corresponding :class:`AttributeTemplateSchema` at write time.
    unit: Physical unit string, or ``None`` for dimensionless attributes.
        Preserved across value assignments.

AttributeTemplateValidator(*, name: str, type: Literal['int', 'float', 'bool', 'str', 'datetime', 'array', 'enum'], unit: str | None = '', default: Any = None, metadata: dict[str, typing.Any] | None = <factory>) -> None

Transient validator for a raw attribute definition supplied via the builder API.

This model is used **only** during builder operations to validate and
coerce the dict-style attribute definitions that users pass to
``add_properties()`` and similar methods before they are written to the
database.  It is not persisted.

Example input accepted by ``add_properties()``::

    {"name": "volume", "type": "float", "default": 10.0, "unit": "uL",
     "metadata": {"min": 0, "max": 20.0}}

Attributes:
    name: Attribute name (may contain spaces).
    type: One of the :data:`TypeName` literals.
    unit: Physical unit string.  Defaults to an empty string.
    default: Default value, coerced to the Python type for *type* by
        :meth:`coerce_default`.
    metadata: Optional validation hints (``min``, ``max``, ``choices``).