design-research

Important

Current monthly release: Meridian Map - April 2026
Due: May 8, 2026
Tracks: April 2026 work

design-research is the umbrella entry-point package in the cmudrc design research ecosystem.

It provides a thin, submodule-first namespace over the ecosystem's specialized component libraries.

Overview

This package focuses on discoverability and coherence rather than reimplementation:

• Submodule-first top-level API: problems, agents, experiments, analysis
• Wrapper submodules that mirror each sibling library's public API by default
• Shared ecosystem framing and philosophy in one canonical package
• Lightweight wrapper design that preserves modular versioning boundaries

Quickstart

Requires Python 3.12+. Maintainer workflows target Python 3.12 (.python-version).

python -m venv .venv
source .venv/bin/activate
make dev
make test
python -m pip install "llama-cpp-python[server]" huggingface-hub
make run-example
make examples-test

make run-example is the live canonical walkthrough. It uses a managed llama.cpp client, a workflow-backed strategy comparison, canonical exports, and downstream analysis helpers. The live workflow path now uses the sibling public seams directly: a prompt-built design_research.agents.Workflow, design_research.agents.PromptWorkflowAgent, design_research.agents.SeededRandomBaselineAgent, design_research.experiments.resolve_problem(...), and design_research.experiments.run_study(..., agent_bindings=...), plus design_research.analysis.integration. Install llama-cpp-python[server] first. If you want the client to fetch its default GGUF model automatically, also install huggingface-hub; otherwise set LLAMA_CPP_MODEL to a specific local GGUF file.

make examples-test stays deterministic and offline-first by default. It runs the two non-live recipe-first examples and skips the live walkthrough unless RUN_LIVE_EXAMPLE=1.

Install from PyPI:

pip install design-research

Then start from the umbrella namespace:

import design_research as dr
from design_research import problems, agents, experiments, analysis

problem_ids = problems.list_problems()
problem = problems.get_problem(problem_ids[0])

print(type(problem).__name__)
print(agents.MultiStepAgent)
print(experiments.Study)
print(analysis.validate_unified_table)

The package root intentionally stays small: it exports only __version__ and the four wrapper submodules. Reach the stable user-facing APIs through design_research.problems, design_research.agents, design_research.experiments, and design_research.analysis rather than a flattened root namespace.

Start Here

Choose your entry point based on how much of the ecosystem you need:

• Start with design-research when you want one stable namespace and one set of docs across problems, agents, experiments, and analysis.
• Install a sibling package directly when you only need one layer or want package-specific internals; direct sibling use is fully supported.
• See Compatibility and Start Here for the tested package combination and install guidance.
• See Prompt-Framing Study Walkthrough for the canonical live composed workflow, and the bundled deterministic examples for the smaller recipe-first entry points.

Ecosystem Integration

The Design Research Collective maintains a modular ecosystem of libraries for studying human and AI design behavior.

• design-research-agents implements AI participants, workflows, and tool-using reasoning patterns.
• design-research-problems provides benchmark design tasks, prompts, grammars, and evaluators.
• design-research-analysis analyzes the traces, event tables, and outcomes generated during studies.
• design-research-experiments sits above the stack as the study-design and orchestration layer, defining hypotheses, factors, conditions, replications, and artifact flows across agents, problems, and analysis.

Together these libraries support end-to-end design research pipelines, from study design through execution and interpretation.

Philosophy

The full ecosystem philosophy is documented in the published philosophy page.

Docs

See the published documentation for quickstart, concepts, workflow framing, philosophy, and API reference.

Build docs locally with:

make docs

Public API

The supported top-level public surface is whatever is exported from design_research.__all__.

Top-level exports include:

• Wrapper submodules: problems, agents, experiments, analysis
• Package metadata: __version__

Contributing

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