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.

Shared metadata and catalog-facing problem types.

class design_research_problems.problems._metadata.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.

design_research_problems.problems._metadata.KNOWN_PROBLEM_CAPABILITIES = frozenset({'baseline-solver', 'bounded-variables', 'citation-backed', 'discrete-actions', 'equality-constraint', 'external-adapter', 'optional-evaluator', 'packaged-assets', 'prompt-packet', 'serializable-state', 'statement-markdown'})#: Controlled vocabulary for problem capabilities.

design_research_problems.problems._metadata.KNOWN_STUDY_SUITABILITY = frozenset({'human-subjects-ready', 'ideation-friendly', 'intervention-ready', 'requirements-study-ready', 'variety-study-ready'})#: Controlled vocabulary for study-suitability tags.

class design_research_problems.problems._metadata.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.

class design_research_problems.problems._metadata.ProblemBenchmarkCard(benchmark_question=None, physically_modeled=(), deliberate_surrogates=(), representation_mode=None, default_evaluation_mode=None, supported_evaluation_modes=(), validation_scope=(), solver_role=None)[source]#

Optional benchmark contract metadata for one packaged problem.

benchmark_question = None#: Research question the benchmark is intended to probe.

default_evaluation_mode = None#: Default evaluator or fidelity mode used by the implementation.

deliberate_surrogates = ()#: Short claims about intentionally simplified benchmark abstractions.

physically_modeled = ()#: Short claims about what is physically modeled.

representation_mode = None#: Primary design representation exposed to the user.

solver_role = None#: How bundled solve routines should be interpreted.

supported_evaluation_modes = ()#: Allowed evaluator or fidelity modes for the problem.

validation_scope = ()#: Validation envelope or sanity-check claims for the benchmark.

class design_research_problems.problems._metadata.ProblemKind(*values)[source]#: Supported high-level problem families.

class design_research_problems.problems._metadata.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#: High-level problem family.

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.problems._metadata.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.