Metadata-Version: 2.4
Name: design-research-experiments
Version: 0.1.0
Summary: Study-definition and orchestration layer for the cmudrc design research ecosystem
Author: The Design Research Collective
Maintainer-email: "Christopher C. McComb" <ccm@cmu.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cmudrc/design-research-experiments
Project-URL: Repository, https://github.com/cmudrc/design-research-experiments
Project-URL: Issues, https://github.com/cmudrc/design-research-experiments/issues
Keywords: design,research,experiments,orchestration,doe
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pre-commit<5,>=3.7; extra == "dev"
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"
Requires-Dist: ruff<1,>=0.6.0; extra == "dev"
Requires-Dist: sphinx<9,>=7.4; extra == "dev"
Requires-Dist: sphinx-rtd-theme<4,>=2.0; extra == "dev"
Requires-Dist: twine<7,>=5.1; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
Requires-Dist: uv<1,>=0.6; extra == "dev"
Dynamic: license-file

# design-research-experiments
[![CI](https://github.com/cmudrc/design-research-experiments/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/design-research-experiments/actions/workflows/ci.yml)
[![Docs](https://github.com/cmudrc/design-research-experiments/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/design-research-experiments/actions/workflows/docs-pages.yml)

`design-research-experiments` is the hypothesis-first study-definition and
experiment-orchestration layer in the cmudrc design research ecosystem.

It composes sibling libraries rather than reimplementing them:

- `design-research-agents` for executable agent behavior, workflows, and traces
- `design-research-problems` for problem catalogs, registries, and evaluators
- `design-research-analysis` for downstream unified-table analysis and reporting

## Overview

This package centers on reproducible experiment structure and execution:

- typed schemas for studies, factors, blocks, hypotheses, outcomes, and analysis plans
- design-of-experiments materialization (full/constrained factorial, randomized block,
  repeated measures, latin square, custom matrices)
- run orchestration with deterministic seeding, checkpointing, and resume support
- canonical artifact exports (`study.yaml`, `manifest.json`, `conditions.csv`,
  `runs.csv`, `events.csv`, `evaluations.csv`, and machine-readable hypothesis/plan files)
- thin adapters that connect to the public APIs of sibling agent/problem/analysis libraries

## Quickstart

Requires Python 3.12+.
Reproducible release installs are pinned to Python `3.12.12` (`.python-version`).

```bash
python -m venv .venv
source .venv/bin/activate
make dev
make test
```

Run a basic example:

```bash
make run-example
```

## CLI

The package installs a `drexp` CLI:

```bash
drexp validate-study path/to/study.yaml
drexp materialize-design path/to/study.yaml
drexp generate-doe --kind lhs --factors-json '{"x": [0, 1], "y": [10, 20]}' --n-samples 12 --out artifacts/doe.csv
drexp run-study path/to/study.yaml
drexp resume-study path/to/study.yaml
drexp export-analysis path/to/study.yaml
drexp bundle-results path/to/output_dir
```

## Examples

See [examples/README.md](examples/README.md) for runnable scripts, including
end-to-end recipe executions.

## Docs

See the [published documentation](https://cmudrc.github.io/design-research-experiments/)
for guides and API reference.

Build docs locally with:

```bash
make docs
```

## Public API

Top-level exports are intentionally small:

- `Study`, `Factor`, `Level`, `Constraint`, `Condition`, `Block`
- `RecipeStudyConfig`, recipe-specific typed config classes
- `Hypothesis`, `OutcomeSpec`, `AnalysisPlan`
- `RunSpec`, `RunResult`, `BenchmarkBundle`
- `build_design`, `generate_doe`, `materialize_conditions`
- `build_prompt_framing_study`, `build_optimization_benchmark_study`, and other recipe builders
- `run_study`, `resume_study`
- `export_analysis_tables`, `validate_study`

## Contributing

Contribution workflow and quality gates are documented in `CONTRIBUTING.md`.
