Shared Types#

Exceptions#

exception design_research_problems.MissingOptionalDependencyError[source]#: Raised when a caller uses an optional integration that is not installed.

exception design_research_problems.ProblemEvaluationError[source]#: Raised when a problem definition is internally inconsistent.

Metadata#

For the downstream compatibility-guaranteed subset used by study-generation tooling, see Downstream Metadata Contract.

The private problems._metadata implementation path is contributor-only. Public users should import these compatibility-guaranteed aliases from the top-level package.

class design_research_problems.ProblemKind(*values)[source]: Supported high-level problem kinds.

class design_research_problems.ProblemMetadata(problem_id, title, summary, kind, taxonomy, citations, assets, capabilities, study_suitability, benchmark_card=None, implementation=None)[source]

Packaged metadata for one problem entry.

assets: Packaged non-code assets associated with the problem.

benchmark_card = None: Optional benchmark contract metadata.

capabilities: Machine-readable implementation and packaging capabilities.

citations: Canonical source citations.

property feature_flags

Return the compatibility union of capabilities and study-suitability flags.

Returns:: Sorted union of both controlled-vocabulary flag sets.

has_feature(feature_flag)[source]

Return whether this problem advertises one feature flag.

Parameters:: feature_flag – Feature flag name to test.
Returns:: True when the normalized feature flag is present.

implementation = None: Optional module:attribute import path for executable problem types.

kind: Canonical high-level problem kind.

problem_id: Stable catalog identifier.

study_suitability: Machine-readable study-use labels for the entry.

summary: Short one-paragraph description.

taxonomy: Shared descriptive taxonomy.

title: Display title shown to users.

class design_research_problems.ProblemCatalogSummary(problem_id, title, kind, summary, tags, formulation, design_variable_type, objective_mode, constraint_nature, bounds_summary, capabilities, study_suitability)[source]

Compact problem metadata for search results and agent context windows.

bounds_summary: Human-readable summary of bounds or design-space limits.

capabilities: Machine-readable implementation and packaging capabilities.

constraint_nature: Constraint strictness label such as hard, soft, or informal.

design_variable_type: Variable domain such as continuous, discrete, or mixed.

formulation: High-level mathematical or representational formulation.

classmethod from_metadata(metadata)[source]

Build a compact summary from one full metadata record.

Parameters:: metadata – Full problem metadata.
Returns:: Compact catalog summary suitable for search results.

kind: Canonical high-level problem kind.

objective_mode: Objective structure such as single, multi, or qualitative.

problem_id: Stable catalog identifier.

study_suitability: Machine-readable study-use labels for the entry.

summary: Short one-paragraph problem description.

tags: Searchable descriptive tags.

title: Display title shown to users.

to_dict()[source]

Return a JSON-compatible summary dictionary.

Returns:: Dictionary form with enum values normalized to strings.

class design_research_problems.ProblemTaxonomy(formulation, convexity, design_variable_type, is_dynamic, orientation, feasibility_ratio_hint, objective_mode, constraint_nature, bounds_summary, tags, deliverable_type=None, timebox_hint_minutes=None, participants=None, evaluation_mode=None)[source]

Shared descriptive taxonomy for all problem families.

bounds_summary: Human-readable summary of bounds or design-space limits.

constraint_nature: Constraint strictness label such as hard, soft, or informal.

convexity: Convexity characterization when applicable.

deliverable_type = None: Expected participant output such as sketches or concepts.

design_variable_type: Variable domain such as continuous, discrete, or mixed.

evaluation_mode = None: Typical study outcome mode such as novelty or requirement coverage.

feasibility_ratio_hint: Optional rough estimate of the feasible design-space fraction.

formulation: High-level mathematical or representational formulation.

is_dynamic: Whether the problem changes over time during evaluation or optimization.

objective_mode: Objective structure such as single, multi, or qualitative.

orientation: Problem framing such as engineering-practical or mathematical.

participants = None: Typical participation mode such as individual or team.

tags: Searchable descriptive tags.

timebox_hint_minutes = None: Typical task duration for the prompt when known.

class design_research_problems.Citation(key, kind, authors, title, year, raw_text, venue=None, doi=None, formatted_text=None, url=None, provisional=False)[source]

Citation metadata for one problem entry.

authors: Structured author list used for search and summary rendering.

doi = None: Digital object identifier when known.

formatted_text = None: Optional curated display string.

key: Stable citation key, typically a BibTeX identifier.

kind: Citation format label such as bibtex or inline.

provisional = False: Whether the record is intentionally incomplete and needs follow-up.

raw_text: Canonical raw citation text.

summary_text()[source]

Return a short human-readable citation line.

Returns:: Curated citation text when available, otherwise a synthesized summary.

title: Canonical work title.

url = None: Optional canonical source URL.

venue = None: Journal, conference, or source venue when known.

year: Publication year when known.

class design_research_problems.ProblemAsset(name, media_type, description, resource_path)[source]

Metadata for a non-code packaged asset.

description: Short human-readable asset description.

media_type: Media type such as image/png or text/plain.

name: Logical asset name used by the public API.

resource_path: Path to the packaged resource relative to the problem directory.