---
name: pyrecap
description: >
  Scientific framework for Reproducible Experiment Capture and Provenance. Use when writing Python code that uses the recap package.
license: BSD-3-Clause
compatibility: Requires Python >=3.10.
---

# Recap

Scientific framework for Reproducible Experiment Capture and Provenance

## Installation

```bash
pip install pyrecap
```

## API overview

### Client

Local and remote clients, namespace context, and permissions.

- `RecapClient`: Primary entry point for interacting with a RECAP provenance database
- `ActorPermissions`: Current actor's effective permissions returned by remote APIs
- `EffectivePermissions`
- `PermissionDecision`
- `DenialCode`

### Queries

Immutable query composition and field predicates.

- `QueryDSL`: Factory for namespace-scoped query families
- `Field`: Typed query-field expression builder
- `FieldPredicate`: Serializable field comparison used by :meth:`BaseQuery.where`
- `FieldOrdering`: Serializable ascending or descending field ordering
- `BaseQuery`: Immutable query base with filtering, pagination, loading, and execution
- `NamespaceQuery`: Query namespaces, including local and effective metadata filters
- `ResourceQuery`: Query resources, properties, templates, and parent relationships
- `ResourceTemplateQuery`: Query resource templates and optionally hydrate child relationships
- `ProcessTemplateQuery`: Query process templates and optionally hydrate steps and slots
- `ProcessRunQuery`: Query process runs with optional steps, resources, and parameters

### Builders

Context-managed resource and process builders.

- `ResourceTemplateBuilder`
- `ResourceBuilder`
- `ProcessTemplateBuilder`: Builder for process templates, resource slots, and step templates
- `StepTemplateBuilder`: Scoped editor for one step's parameter groups and resource bindings
- `ProcessRunBuilder`: Builder for process-run assignments, parameters, and child steps
- `AttributeGroupBuilder`

### Models and Lifecycle

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

- `LifecycleStatus`: Monotonic lifecycle state for persisted RECAP entities
- `Direction`: Direction of resource flow through a process step
- `validate_transition`: Validate lifecycle transition, allowing idempotent same-state updates
- `NamespaceRef`: Lightweight namespace identity used in relationships and query results
- `NamespaceContext`: Active namespace scope attached to client queries and writes
- `NamespaceSchema`: Persisted namespace with lifecycle, hierarchy, and metadata fields
- `ResourceTypeSchema`: A type tag associated with a resource or resource template
- `ResourceCopyChanges`: Property changes applied while copying a resource
- `ResourceCopyOptions`: Name, parent, and property overrides for a resource copy operation
- `ResourceTemplateRef`: Full blueprint for a category of resources
- `ResourceTemplateSchema`: Full blueprint for a category of resources
- `ResourceRef`: A concrete resource instance created from a :class:`ResourceTemplateSchema`
- `ResourceSchema`: A concrete resource instance created from a :class:`ResourceTemplateSchema`
- `ResourceAssignmentSchema`: Represents the assignment of a resource to a slot in a process run
- `ProcessTemplateRef`: Blueprint for a workflow, defining its ordered steps and resource slots
- `ProcessTemplateSchema`: Blueprint for a workflow, defining its ordered steps and resource slots
- `ProcessRunRef`: A concrete execution of a :class:`ProcessTemplateSchema`
- `ProcessRunSchema`: A concrete execution of a :class:`ProcessTemplateSchema`
- `StepTemplateRef`: Blueprint for a single workflow step within a process template
- `StepTemplateSchema`: Blueprint for a single workflow step within a process template
- `StepSchema`: A concrete step instance within a :class:`~recap.schemas.process.ProcessRunSchema`
- `ParameterSchema`: A parameter group instance attached to a step
- `AttributeTemplateSchema`: Persisted blueprint for a single typed attribute
- `AttributeGroupRef`: A named group of :class:`AttributeTemplateSchema` instances
- `AttributeGroupTemplateSchema`: A named group of :class:`AttributeTemplateSchema` instances
- `AttributeValueSchema`: A single stored attribute value with an optional physical unit
- `AttributeTemplateValidator`: Transient validator for a raw attribute definition supplied via the builder API

## Resources

- [Full documentation](https://github.com/NSLS2/recap/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/NSLS2/recap.git)