design-research-problems 0.1.0__py3-none-any.whl

design_research_problems/__init__.py

@@ -0,0 +1,73 @@
+"""Curated public package interface with lazily resolved exports."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Final
+
+from design_research_problems._lazy_exports import module_dir, resolve_lazy_export
+
+_EXPORTS: Final[dict[str, str]] = {
+    "ProblemKind": "design_research_problems.problems:ProblemKind",
+    "ProblemMetadata": "design_research_problems.problems:ProblemMetadata",
+    "ProblemTaxonomy": "design_research_problems.problems:ProblemTaxonomy",
+    "Citation": "design_research_problems.problems:Citation",
+    "ProblemAsset": "design_research_problems.problems:ProblemAsset",
+    "TextProblem": "design_research_problems.problems:TextProblem",
+    "OptimizationProblem": "design_research_problems.problems:OptimizationProblem",
+    "GrammarProblem": "design_research_problems.problems:GrammarProblem",
+    "ProblemRegistry": "design_research_problems._catalog:ProblemRegistry",
+    "MissingOptionalDependencyError": "design_research_problems._exceptions:MissingOptionalDependencyError",
+    "ProblemEvaluationError": "design_research_problems._exceptions:ProblemEvaluationError",
+    "get_problem": "design_research_problems._catalog:get_problem",
+    "list_problems": "design_research_problems._catalog:list_problems",
+}
+
+__all__ = ["__version__", *_EXPORTS.keys()]
+
+try:
+    __version__ = version("design-research-problems")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+
+def __getattr__(name: str) -> object:
+    """Resolve and cache one deferred public export.
+
+    Args:
+        name: Public symbol name requested from the package module.
+
+    Returns:
+        Resolved export object.
+    """
+    return resolve_lazy_export(
+        module_name=__name__,
+        exports=_EXPORTS,
+        export_name=name,
+        namespace=globals(),
+    )
+
+
+def __dir__() -> list[str]:
+    """Return package attributes, including deferred exports.
+
+    Returns:
+        Sorted attribute list for interactive discovery.
+    """
+    return module_dir(globals(), __all__)
+
+
+if TYPE_CHECKING:
+    from ._catalog import ProblemRegistry as ProblemRegistry
+    from ._catalog import get_problem as get_problem
+    from ._catalog import list_problems as list_problems
+    from ._exceptions import MissingOptionalDependencyError as MissingOptionalDependencyError
+    from ._exceptions import ProblemEvaluationError as ProblemEvaluationError
+    from .problems import Citation as Citation
+    from .problems import GrammarProblem as GrammarProblem
+    from .problems import OptimizationProblem as OptimizationProblem
+    from .problems import ProblemAsset as ProblemAsset
+    from .problems import ProblemKind as ProblemKind
+    from .problems import ProblemMetadata as ProblemMetadata
+    from .problems import ProblemTaxonomy as ProblemTaxonomy
+    from .problems import TextProblem as TextProblem

design_research_problems/_assets/catalog/peanut_sheller_fu2010/citation.bib

@@ -0,0 +1,5 @@
+@article{fu2010design,
+  title={Design team convergence: the influence of example solution quality},
+  author={Fu, Katherine and Cagan, Jonathan and Kotovsky, Kenneth},
+  year={2010}
+}

design_research_problems/_assets/catalog/peanut_sheller_fu2010/problem.toml

@@ -0,0 +1,26 @@
+problem_id = "peanut_sheller_fu2010"
+title = "Design Problem - Device to shell peanuts"
+summary = "A text-based design prompt about a low-cost peanut sheller for small-scale farmers."
+kind = "text"
+statement_file = "statement.md"
+citation_file = "citation.bib"
+citation_key = "fu2010design"
+citation_kind = "bibtex"
+feature_flags = [
+  "statement-markdown",
+  "citation-backed",
+  "prompt-packet",
+  "human-subjects-ready",
+]
+
+[taxonomy]
+formulation = "textual_prompt"
+convexity = "not_applicable"
+design_variable_type = "not_applicable"
+is_dynamic = false
+orientation = "engineering_practical"
+feasibility_ratio_hint = 1.0
+objective_mode = "qualitative"
+constraint_nature = "informal"
+bounds_summary = "not_applicable"
+tags = ["text", "human-subjects", "agriculture", "mechanical-design"]

design_research_problems/_assets/catalog/peanut_sheller_fu2010/statement.md

@@ -0,0 +1,18 @@
+# Design Problem - Device to shell peanuts
+
+In places like Haiti and certain West African countries, peanuts are a
+significant crop. Most peanut farmers shell their peanuts by hand, an
+inefficient and labor-intensive process. Our goal is to build a low-cost,
+easy to manufacture peanut sheller targeted at individuals and small
+cooperatives that will increase the productivity of the peanut farmers.
+Further, this peanut sheller should be manufacturable with materials that are
+readily available in the target communities. Our target throughput is
+approximately 50 kg (110 lbs) per hour.
+
+# Customer Needs
+
+- Must remove the shell with minimal damage to the peanuts.
+- Electrical outlets are not available as a power source.
+- A large quantity of peanuts must be quickly shelled.
+- Low cost.
+- Easy to manufacture.

design_research_problems/_assets/catalog/pill_capsule_min_area/problem.toml

@@ -0,0 +1,28 @@
+problem_id = "pill_capsule_min_area"
+title = "Pill capsule minimum-area problem"
+summary = "A two-variable constrained optimization problem that minimizes capsule surface area at fixed volume."
+kind = "optimization"
+statement_file = "statement.md"
+implementation = "design_research_problems.problems.optimization._pill:PillCapsuleMinArea"
+feature_flags = [
+  "statement-markdown",
+  "bounded-variables",
+  "equality-constraint",
+  "seeded-data-generation",
+  "optional-solver",
+]
+
+[parameters]
+required_volume = 1e-6
+
+[taxonomy]
+formulation = "nonlinear_program"
+convexity = "not_guaranteed"
+design_variable_type = "continuous"
+is_dynamic = false
+orientation = "mathematical"
+feasibility_ratio_hint = 0.5
+objective_mode = "single"
+constraint_nature = "hard"
+bounds_summary = "radius and length bounded on [0, 1]"
+tags = ["optimization", "continuous", "nonlinear", "single-objective"]

design_research_problems/_assets/catalog/pill_capsule_min_area/statement.md

@@ -0,0 +1,8 @@
+# Pill capsule minimum-area problem
+
+Minimize the surface area of a capsule-shaped pill while satisfying a fixed
+volume requirement. The design variables are the capsule radius and cylindrical
+section length. Both variables are bounded on [0, 1].
+
+This seed problem is a compact constrained optimization benchmark for design
+research workflows and solver experiments.

design_research_problems/_assets/catalog/planar_truss_span/problem.toml

@@ -0,0 +1,30 @@
+problem_id = "planar_truss_span"
+title = "Planar truss span grammar problem"
+summary = "A discrete topology grammar for adding and removing joints and members in a planar truss."
+kind = "grammar"
+statement_file = "statement.md"
+implementation = "design_research_problems.problems.grammar._planar_truss:PlanarTrussSpanProblem"
+feature_flags = [
+  "statement-markdown",
+  "serializable-state",
+  "discrete-actions",
+  "optional-evaluator",
+  "external-adapter",
+]
+
+[parameters]
+span = 10.0
+max_height = 5.0
+load_magnitude = 1000.0
+
+[taxonomy]
+formulation = "discrete_grammar"
+convexity = "not_applicable"
+design_variable_type = "discrete"
+is_dynamic = false
+orientation = "engineering_practical"
+feasibility_ratio_hint = 0.25
+objective_mode = "single"
+constraint_nature = "hard"
+bounds_summary = "planar topology over a fixed span and height envelope"
+tags = ["grammar", "truss", "discrete", "topology"]

design_research_problems/_assets/catalog/planar_truss_span/statement.md

@@ -0,0 +1,10 @@
+# Planar truss span grammar problem
+
+Create a stable, lightweight planar truss spanning a fixed distance between a
+left pinned support and a right roller support. The grammar begins with the
+supports and one loaded free joint. Designers can add interior joints, add
+members, and remove members.
+
+States are evaluated by translating the library-owned grammar state into a
+fresh `trussme.Truss`, applying the load, and attempting a structural
+analysis. Singular or unstable states are treated as infeasible results.

design_research_problems/_catalog/__init__.py

@@ -0,0 +1,5 @@
+"""Catalog loading and registry exports."""
+
+from ._registry import ProblemRegistry, get_problem, list_problems
+
+__all__ = ["ProblemRegistry", "get_problem", "list_problems"]

design_research_problems/_catalog/_loader.py

@@ -0,0 +1,220 @@
+"""Load packaged problem manifests and resources."""
+
+from __future__ import annotations
+
+import tomllib
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from typing import Any, cast
+
+from design_research_problems._catalog._manifest import ProblemManifest
+from design_research_problems.problems._metadata import (
+    Citation,
+    ProblemAsset,
+    ProblemKind,
+    ProblemMetadata,
+    ProblemTaxonomy,
+)
+
+_PACKAGE = "design_research_problems"
+_CATALOG_DIR = "_assets/catalog"
+
+
+def _catalog_root() -> Traversable:
+    """Return the traversable root directory for packaged catalog resources.
+
+    Returns:
+        Package resource directory containing all problem entries.
+    """
+    return files(_PACKAGE).joinpath("_assets", "catalog")
+
+
+def _resource_root(resource_dir: str) -> Traversable:
+    """Return the traversable root directory for one packaged resource path.
+
+    Args:
+        resource_dir: Package-relative resource directory.
+
+    Returns:
+        Traversable directory for the requested resource path.
+    """
+    return files(_PACKAGE).joinpath(*resource_dir.split("/"))
+
+
+def _parse_problem_kind(raw_kind: str) -> ProblemKind:
+    """Parse one manifest problem-kind string into the enum.
+
+    Args:
+        raw_kind: Raw string from the manifest file.
+
+    Returns:
+        Parsed problem kind.
+
+    Raises:
+        ValueError: If the manifest contains an unsupported problem kind.
+    """
+    normalized = raw_kind.strip().lower()
+    if normalized == "text":
+        return ProblemKind.TEXT
+    if normalized == "optimization":
+        return ProblemKind.OPTIMIZATION
+    if normalized == "grammar":
+        return ProblemKind.GRAMMAR
+    raise ValueError(f"Unsupported problem kind: {raw_kind!r}")
+
+
+def _parse_citations(raw_data: dict[str, Any], resource_dir: str) -> tuple[Citation, ...]:
+    """Build citation objects from one manifest payload.
+
+    Args:
+        raw_data: Parsed TOML manifest mapping.
+        resource_dir: Package-relative resource directory for the entry.
+
+    Returns:
+        Parsed citations in manifest order.
+    """
+    citations: list[Citation] = []
+    citation_file = raw_data.get("citation_file")
+    if isinstance(citation_file, str):
+        resource = _resource_root(resource_dir).joinpath(citation_file)
+        raw_text = resource.read_text(encoding="utf-8")
+        citations.append(
+            Citation(
+                key=str(raw_data.get("citation_key", "")),
+                kind=str(raw_data.get("citation_kind", "bibtex")),
+                raw_text=raw_text,
+                url=cast(str | None, raw_data.get("citation_url")),
+            )
+        )
+
+    for entry in cast(list[dict[str, Any]], raw_data.get("citations", [])):
+        citations.append(
+            Citation(
+                key=str(entry["key"]),
+                kind=str(entry.get("kind", "inline")),
+                raw_text=str(entry["raw_text"]),
+                url=cast(str | None, entry.get("url")),
+            )
+        )
+
+    return tuple(citations)
+
+
+def _parse_assets(raw_assets: list[dict[str, Any]]) -> tuple[ProblemAsset, ...]:
+    """Build asset metadata objects from raw manifest entries.
+
+    Args:
+        raw_assets: Raw asset dictionaries from the manifest.
+
+    Returns:
+        Parsed asset metadata tuple.
+    """
+    return tuple(
+        ProblemAsset(
+            name=str(entry["name"]),
+            media_type=str(entry["media_type"]),
+            description=str(entry.get("description", "")),
+            resource_path=str(entry["path"]),
+        )
+        for entry in raw_assets
+    )
+
+
+def _parse_feature_flags(raw_flags: list[object]) -> tuple[str, ...]:
+    """Build a normalized, deterministic feature-flag tuple.
+
+    Args:
+        raw_flags: Raw feature-flag values from the manifest.
+
+    Returns:
+        Sorted unique normalized feature flags.
+    """
+    normalized: set[str] = set()
+    for raw_flag in raw_flags:
+        flag = str(raw_flag).strip().lower().replace(" ", "-")
+        if flag:
+            normalized.add(flag)
+    return tuple(sorted(normalized))
+
+
+def _parse_taxonomy(raw_taxonomy: dict[str, Any]) -> ProblemTaxonomy:
+    """Build the shared taxonomy object from raw manifest data.
+
+    Args:
+        raw_taxonomy: Raw taxonomy mapping from the manifest.
+
+    Returns:
+        Parsed taxonomy object.
+    """
+    return ProblemTaxonomy(
+        formulation=str(raw_taxonomy.get("formulation", "unspecified")),
+        convexity=str(raw_taxonomy.get("convexity", "unknown")),
+        design_variable_type=str(raw_taxonomy.get("design_variable_type", "unknown")),
+        is_dynamic=bool(raw_taxonomy.get("is_dynamic", False)),
+        orientation=str(raw_taxonomy.get("orientation", "unknown")),
+        feasibility_ratio_hint=raw_taxonomy.get("feasibility_ratio_hint"),
+        objective_mode=str(raw_taxonomy.get("objective_mode", "single")),
+        constraint_nature=str(raw_taxonomy.get("constraint_nature", "unspecified")),
+        bounds_summary=str(raw_taxonomy.get("bounds_summary", "unspecified")),
+        tags=tuple(str(tag) for tag in raw_taxonomy.get("tags", [])),
+    )
+
+
+def _load_single_manifest(entry: Any) -> ProblemManifest:
+    """Load one problem manifest directory.
+
+    Args:
+        entry: Traversable directory representing one problem entry.
+
+    Returns:
+        Parsed problem manifest object.
+    """
+    raw_text = entry.joinpath("problem.toml").read_text(encoding="utf-8")
+    raw_data = tomllib.loads(raw_text)
+    resource_dir = f"{_CATALOG_DIR}/{entry.name}"
+    metadata = ProblemMetadata(
+        problem_id=str(raw_data["problem_id"]),
+        title=str(raw_data["title"]),
+        summary=str(raw_data["summary"]),
+        kind=_parse_problem_kind(str(raw_data["kind"])),
+        taxonomy=_parse_taxonomy(cast(dict[str, Any], raw_data.get("taxonomy", {}))),
+        citations=_parse_citations(raw_data, resource_dir),
+        assets=_parse_assets(cast(list[dict[str, Any]], raw_data.get("assets", []))),
+        feature_flags=_parse_feature_flags(cast(list[object], raw_data.get("feature_flags", []))),
+        implementation=cast(str | None, raw_data.get("implementation")),
+    )
+    statement_resource = str(raw_data.get("statement_file", "statement.md"))
+    parameters = cast(dict[str, object], raw_data.get("parameters", {}))
+    return ProblemManifest(
+        metadata=metadata,
+        resource_dir=resource_dir,
+        statement_resource=statement_resource,
+        parameters=parameters,
+    )
+
+
+def load_problem_manifests() -> dict[str, ProblemManifest]:
+    """Load all packaged problem manifests.
+
+    Returns:
+        Mapping of problem IDs to parsed manifests.
+    """
+    manifests: dict[str, ProblemManifest] = {}
+    for entry in sorted(_catalog_root().iterdir(), key=lambda item: item.name):
+        if not entry.is_dir():
+            continue
+        manifest = _load_single_manifest(entry)
+        manifests[manifest.metadata.problem_id] = manifest
+    return manifests
+
+
+def load_statement_text(manifest: ProblemManifest) -> str:
+    """Load the statement markdown for one problem manifest.
+
+    Args:
+        manifest: Parsed manifest describing the packaged resource path.
+
+    Returns:
+        UTF-8 Markdown statement text.
+    """
+    return _resource_root(manifest.resource_dir).joinpath(manifest.statement_resource).read_text(encoding="utf-8")

design_research_problems/_catalog/_manifest.py

@@ -0,0 +1,22 @@
+"""Manifest types for packaged problem resources."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from design_research_problems.problems._metadata import ProblemMetadata
+
+
+@dataclass(frozen=True)
+class ProblemManifest:
+    """Container for one packaged catalog entry."""
+
+    metadata: ProblemMetadata
+    """Loaded problem metadata used for registry lookups."""
+    resource_dir: str
+    """Package-relative directory containing the problem resources."""
+    statement_resource: str
+    """File name of the packaged Markdown statement."""
+    parameters: Mapping[str, object]
+    """Implementation-specific manifest parameters."""

design_research_problems/_catalog/_registry.py

@@ -0,0 +1,199 @@
+"""Problem registry facade."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import import_module
+from typing import cast
+
+from design_research_problems._catalog._loader import load_problem_manifests, load_statement_text
+from design_research_problems._catalog._manifest import ProblemManifest
+from design_research_problems._exceptions import ProblemEvaluationError
+from design_research_problems.problems import GrammarProblem, OptimizationProblem, ProblemKind, TextProblem
+from design_research_problems.problems._assets import PackageResourceBundle
+from design_research_problems.problems._metadata import ProblemMetadata
+
+
+def _resolve_object(import_path: str) -> object:
+    """Import one ``module:attribute`` object reference.
+
+    Args:
+        import_path: Import target in ``module:attribute`` form.
+
+    Returns:
+        Imported Python object.
+
+    Raises:
+        design_research_problems.ProblemEvaluationError: If the import path is malformed.
+    """
+    module_path, _, attr_name = import_path.partition(":")
+    if not module_path or not attr_name:
+        raise ProblemEvaluationError(f"Invalid implementation path: {import_path!r}")
+    return getattr(import_module(module_path), attr_name)
+
+
+ProblemInstance = TextProblem | OptimizationProblem | GrammarProblem
+
+
+class ProblemRegistry:
+    """Lazy-loading registry for the packaged problem catalog."""
+
+    def __init__(self) -> None:
+        """Initialize an empty lazy registry cache."""
+        self._manifests: dict[str, ProblemManifest] | None = None
+
+    def _catalog(self) -> dict[str, ProblemManifest]:
+        """Return the cached manifest catalog.
+
+        Returns:
+            Mapping of problem IDs to parsed manifests.
+        """
+        if self._manifests is None:
+            self._manifests = load_problem_manifests()
+        return self._manifests
+
+    def list(self) -> tuple[ProblemMetadata, ...]:
+        """Return all problem metadata in ID-sorted order.
+
+        Returns:
+            Metadata entries sorted by problem ID.
+        """
+        return tuple(self._catalog()[problem_id].metadata for problem_id in sorted(self._catalog()))
+
+    def by_kind(self, kind: ProblemKind) -> tuple[ProblemMetadata, ...]:
+        """Return metadata entries with the requested kind.
+
+        Args:
+            kind: Problem family to filter for.
+
+        Returns:
+            Matching metadata entries.
+        """
+        return tuple(metadata for metadata in self.list() if metadata.kind is kind)
+
+    def feature_flags(self, problem_id: str) -> tuple[str, ...]:
+        """Return the feature flags for one problem ID.
+
+        Args:
+            problem_id: Stable catalog identifier.
+
+        Returns:
+            Feature flags in deterministic sorted order.
+
+        Raises:
+            KeyError: If the ID is unknown.
+        """
+        manifest = self._catalog().get(problem_id)
+        if manifest is None:
+            raise KeyError(f"Unknown problem id: {problem_id}")
+        return manifest.metadata.feature_flags
+
+    def kind_feature_flags(self) -> dict[ProblemKind, tuple[str, ...]]:
+        """Return aggregated feature flags for each problem family.
+
+        Returns:
+            Mapping of problem kinds to the union of feature flags across that family.
+        """
+        grouped: dict[ProblemKind, set[str]] = {kind: set() for kind in ProblemKind}
+        for metadata in self.list():
+            grouped[metadata.kind].update(metadata.feature_flags)
+        return {kind: tuple(sorted(grouped[kind])) for kind in ProblemKind}
+
+    def search(
+        self,
+        tags: tuple[str, ...] = (),
+        text: str = "",
+        feature_flags: tuple[str, ...] = (),
+    ) -> tuple[ProblemMetadata, ...]:
+        """Search metadata by tags and free text.
+
+        Args:
+            tags: Tags that must all be present on a matching entry.
+            text: Case-insensitive free-text search term.
+            feature_flags: Feature flags that must all be present on a matching entry.
+
+        Returns:
+            Matching metadata entries.
+        """
+        tag_set = {tag.lower() for tag in tags}
+        feature_flag_set = {flag.strip().lower().replace(" ", "-") for flag in feature_flags}
+        text_query = text.strip().lower()
+        matches: list[ProblemMetadata] = []
+        for metadata in self.list():
+            if tag_set and not tag_set.issubset({tag.lower() for tag in metadata.taxonomy.tags}):
+                continue
+            if feature_flag_set and not feature_flag_set.issubset(set(metadata.feature_flags)):
+                continue
+            haystack = " ".join(
+                (metadata.problem_id, metadata.title, metadata.summary, *metadata.taxonomy.tags)
+            ).lower()
+            if text_query and text_query not in haystack:
+                continue
+            matches.append(metadata)
+        return tuple(matches)
+
+    def get(self, problem_id: str) -> ProblemInstance:
+        """Instantiate one problem by ID.
+
+        Args:
+            problem_id: Stable catalog identifier.
+
+        Returns:
+            Loaded problem instance.
+
+        Raises:
+            KeyError: If the ID is unknown.
+            design_research_problems.ProblemEvaluationError: If the packaged implementation metadata is invalid.
+        """
+        manifest = self._catalog().get(problem_id)
+        if manifest is None:
+            raise KeyError(f"Unknown problem id: {problem_id}")
+
+        statement_markdown = load_statement_text(manifest)
+        if manifest.metadata.kind is ProblemKind.TEXT:
+            return TextProblem(
+                metadata=manifest.metadata,
+                statement_markdown=statement_markdown,
+                assets=manifest.metadata.assets,
+                resource_bundle=PackageResourceBundle("design_research_problems", manifest.resource_dir),
+            )
+
+        implementation = manifest.metadata.implementation
+        if implementation is None:
+            raise ProblemEvaluationError(f"Problem {problem_id!r} is missing an implementation path.")
+
+        target = _resolve_object(implementation)
+        factory = getattr(target, "from_manifest", None)
+        if callable(factory):
+            manifest_factory = cast(Callable[[ProblemManifest, str], ProblemInstance], factory)
+            return manifest_factory(manifest, statement_markdown)
+
+        if callable(target):
+            direct_factory = cast(Callable[[object, str], ProblemInstance], target)
+            return direct_factory(manifest.metadata, statement_markdown)
+
+        raise ProblemEvaluationError(f"Problem implementation for {problem_id!r} is not callable.")
+
+
+_DEFAULT_REGISTRY = ProblemRegistry()
+
+
+def list_problems() -> tuple[str, ...]:
+    """Return all packaged problem IDs.
+
+    Returns:
+        Stable problem IDs in sorted order.
+    """
+    return tuple(metadata.problem_id for metadata in _DEFAULT_REGISTRY.list())
+
+
+def get_problem(problem_id: str) -> TextProblem | OptimizationProblem | GrammarProblem:
+    """Return one problem instance by ID.
+
+    Args:
+        problem_id: Stable catalog identifier.
+
+    Returns:
+        Loaded problem instance.
+    """
+    return _DEFAULT_REGISTRY.get(problem_id)

design_research_problems/_exceptions.py

@@ -0,0 +1,11 @@
+"""Package-specific exceptions."""
+
+from __future__ import annotations
+
+
+class MissingOptionalDependencyError(ImportError):
+    """Raised when a caller uses an optional integration that is not installed."""
+
+
+class ProblemEvaluationError(RuntimeError):
+    """Raised when a problem definition is internally inconsistent."""