Metadata-Version: 2.4
Name: design-research-problems
Version: 0.2.1
Summary: A compendium of canonical design research problems
Author: The Design Research Collective
Maintainer-email: "Christopher C. McComb" <ccm@cmu.edu>
License-Expression: MIT
Project-URL: Homepage, https://cmudrc.github.io/design-research-problems/
Project-URL: Documentation, https://cmudrc.github.io/design-research-problems/
Project-URL: Repository, https://github.com/cmudrc/design-research-problems
Project-URL: Issues, https://github.com/cmudrc/design-research-problems/issues
Keywords: design,research,optimization,benchmark,problems
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gmpb<1,>=0.1.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: scipy<2,>=1.13
Provides-Extra: grammar
Requires-Dist: trussme>=0.1.0; extra == "grammar"
Provides-Extra: battery
Requires-Dist: pybamm<26,>=25.12; extra == "battery"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1; extra == "mcp"
Provides-Extra: cad
Requires-Dist: build123d<1,>=0.8; extra == "cad"
Provides-Extra: opt
Requires-Dist: scipy<2,>=1.11; extra == "opt"
Provides-Extra: solvers
Requires-Dist: nevergrad<2,>=1.0; extra == "solvers"
Requires-Dist: pymoo<1,>=0.6; extra == "solvers"
Provides-Extra: pandas
Requires-Dist: pandas<3,>=2.2; extra == "pandas"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: mcp<2,>=1; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pydata-sphinx-theme<1,>=0.16; 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: setuptools>=77; extra == "dev"
Requires-Dist: sphinx<9,>=7.4; extra == "dev"
Requires-Dist: sphinx-copybutton<1,>=0.5; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid<2,>=1.0; extra == "dev"
Requires-Dist: twine<7,>=5.1; extra == "dev"
Requires-Dist: wheel>=0.45; extra == "dev"
Dynamic: license-file

# design-research-problems
[![CI](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
[![Coverage](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
[![Examples Passing](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-passing.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/examples.yml)
[![Public API In Examples](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-api-coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/examples.yml)
[![Docs](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml)

<!-- release-callout:start -->
> [!IMPORTANT]
> Current monthly release: [Monarch Maze - May 2026](https://github.com/cmudrc/design-research-problems/milestone/2)  
> Due: May 1, 2026  
> Tracks: April 2026 work
<!-- release-callout:end -->

`design-research-problems` is a compact library and compendium of design research
problems. It packages canonical research prompts, optimization benchmarks, and
discrete grammar-style problems behind a small, typed Python API.

## Overview

- Five problem families: text, decision, optimization, grammar, and MCP, plus a linked ideation metadata catalog.
- Shared model contracts built around `Problem` and `ComputableProblem`, with family-specific subclasses on top.
- A seed catalog that includes 126 ideation prompt records plus packaged decision, optimization, grammar, and MCP benchmarks.
- Optional integrations for `trussme`, `pybamm`, `mcp`, Build123d, and external solver backends.
- Typed metadata, a curated public API, runnable examples, and Sphinx docs.

## Quickstart

Requires Python 3.12+.
Local workflows target Python `3.12` in `.python-version`.

Create and activate a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

Install in editable mode for local development:

```bash
make dev
make test
```

Or install from PyPI:

```bash
pip install design-research-problems
```

Optional extras:

```bash
pip install "design-research-problems[grammar]"
pip install "design-research-problems[battery]"
pip install "design-research-problems[mcp,cad]"
pip install "design-research-problems[solvers,pandas]"
```

Then inspect the catalog directly from the installed package:

```bash
python3 -c "import design_research_problems as derp; print(derp.list_problems())"
```

And inspect the ideation corpus:

```bash
python3 -c "import design_research_problems as derp; print(len(derp.get_ideation_catalog().list_prompts()))"
```

Launch the packaged desktop GUIs with:

```bash
python3 -m design_research_problems.gui --app iot
python3 -m design_research_problems.gui --app truss
```

The IoT GUI renders a continuous room-temperature colorbar, and the truss GUI
only evaluates structurally when the design is not under-determined.

Run one checked-in example from repository root:

```bash
PYTHONPATH=src python examples/catalog/list_and_load.py
```

## Examples

Start with [examples/README.md](https://github.com/cmudrc/design-research-problems/blob/main/examples/README.md)
for runnable examples across all problem families.

## Docs

See the [published documentation](https://cmudrc.github.io/design-research-problems/)
for quickstart, problem-family guides, generated catalog pages, and API reference.

Build docs locally with:

```bash
make docs
```

## Public API

The supported public surface is whatever is exported from `design_research_problems.__all__`.

Top-level exports include:

- Shared contracts and family bases: `Problem`, `ComputableProblem`, `ProblemKind`, `ProblemMetadata`, `ProblemTaxonomy`, `Citation`, `ProblemAsset`, `TextProblem`, `DecisionProblem`, `OptimizationProblem`, `GrammarProblem`, and `MCPProblem`.
- Family-specific evaluation contracts: `DecisionEvaluation`, `OptimizationEvaluation`, and `GrammarTransition`.
- Catalog access: `ProblemRegistry`, `get_problem`, `get_problem_as`, and `list_problems`.
- Ideation metadata API: `IdeationCatalog`, `IdeationPromptRecord`, `IdeationPromptVariant`, `IdeationPromptFamily`, `IdeationStudy`, `EvidenceTier`, and `get_ideation_catalog`.
- Public exceptions: `MissingOptionalDependencyError` and `ProblemEvaluationError`.

## Contributing

Contribution workflow and quality gates are documented in
[CONTRIBUTING.md](https://github.com/cmudrc/design-research-problems/blob/main/CONTRIBUTING.md).
