api-reference.md

# API Reference

> **API documentation** for all infrastructure modules

**Quick Reference:** [Modules Guide](../modules/modules-guide.md) | [Infrastructure Docs](../../infrastructure/AGENTS.md) | [Getting Started](../guides/getting-started.md)

This document provides the API reference for all public functions and
classes exported by `infrastructure/<pkg>/__init__.py`. All modules
follow the thin-orchestrator pattern.

**Note**: These modules are part of the infrastructure layer. For
project-specific code, see `projects/{name}/src/`.

## How this file is maintained

The per-package symbol listings below the
`<!-- BEGIN:API_REFERENCE -->
<!-- This block is generated by `scripts/generate_api_reference_doc.py` from each package's `__init__.py` `__all__`. Do not hand-edit. Hand-written prose belongs **above** the markers. -->

## Package: `infrastructure.autoresearch`

### `AutoResearchConfig`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchIssue`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchPlan`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchReport`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchStage`

*symbol — defined in `infrastructure.autoresearch`*

### `BenchmarkTask`

*symbol — defined in `infrastructure.autoresearch`*

### `BudgetPolicy`

*symbol — defined in `infrastructure.autoresearch`*

### `build_autoresearch_plan`

*symbol — defined in `infrastructure.autoresearch`*

### `EvidenceLink`

*symbol — defined in `infrastructure.autoresearch`*

### `ExperimentCandidate`

*symbol — defined in `infrastructure.autoresearch`*

### `EXTRINSIC_QUALITY_CHECKS`

*symbol — defined in `infrastructure.autoresearch`*

### `INTRINSIC_QUALITY_CHECKS`

*symbol — defined in `infrastructure.autoresearch`*

### `load_autoresearch_config`

*symbol — defined in `infrastructure.autoresearch`*

### `parse_string_sequence`

*symbol — defined in `infrastructure.autoresearch`*

### `ResearchIdea`

*symbol — defined in `infrastructure.autoresearch`*

### `ResearchProgram`

*symbol — defined in `infrastructure.autoresearch`*

### `ReviewGate`

*symbol — defined in `infrastructure.autoresearch`*

### `RunLedger`

*symbol — defined in `infrastructure.autoresearch`*

### `SecurityProfile`

*symbol — defined in `infrastructure.autoresearch`*

### `validate_autoresearch_plan`

*symbol — defined in `infrastructure.autoresearch`*

### `ValidationPhase`

*symbol — defined in `infrastructure.autoresearch`*

### `write_autoresearch_report`

*symbol — defined in `infrastructure.autoresearch`*

## Package: `infrastructure.benchmark`

### `BenchmarkManifest`

*symbol — defined in `infrastructure.benchmark`*

### `BenchmarkScore`

*symbol — defined in `infrastructure.benchmark`*

### `load_benchmark_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `RubricScore`

*symbol — defined in `infrastructure.benchmark`*

### `RubricSet`

*symbol — defined in `infrastructure.benchmark`*

### `run_benchmark_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `score_project_against_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `score_rubric`

*symbol — defined in `infrastructure.benchmark`*

### `scores_to_dict`

*symbol — defined in `infrastructure.benchmark`*

### `scores_to_markdown`

*symbol — defined in `infrastructure.benchmark`*

### `write_default_manifest`

*symbol — defined in `infrastructure.benchmark`*

## Package: `infrastructure.core`

### `CheckpointManager`

*class — defined in `infrastructure.core.runtime.checkpoint`*

```python
class CheckpointManager(checkpoint_dir: Path | None=None, project_name: str='project', repo_root: Path | None=None, project_dir: Path | None=None)
```

Manages pipeline checkpoints for resume capability.

### `format_duration`

*function — defined in `infrastructure.core.logging.helpers`*

```python
format_duration(seconds: float) -> str
```

Format duration in seconds to human-readable string (e.g., '1m 23s', '45s').

### `get_logger`

*function — defined in `infrastructure.core.logging.setup`*

```python
get_logger(name: str) -> logging.Logger
```

Return a logger configured with standard handlers for the given name.

### `log_operation`

*function — defined in `infrastructure.core.logging.pipeline_logging`*

```python
log_operation(operation: str, logger: logging.Logger | None=None, level: int=logging.INFO, min_duration_to_log: float=0.1, log_completion: bool=True) -> Iterator[None]
```

Context manager that logs operation start, completion, and failure.

### `log_stage`

*function — defined in `infrastructure.core.logging.pipeline_logging`*

```python
log_stage(stage_num: int, total_stages: int, stage_name: str, logger: logging.Logger | None=None) -> None
```

Log a numbered pipeline stage header with a visual separator.

### `log_success`

*function — defined in `infrastructure.core.logging.pipeline_logging`*

```python
log_success(message: str, logger: logging.Logger | None=None) -> None
```

Log message at INFO level prefixed with the success emoji.

### `monitor_performance`

*function — defined in `infrastructure.core.runtime.function_profiler`*

```python
monitor_performance(operation_name: str, track_memory: bool=True) -> Callable[[Callable[..., Any]], Callable[..., Any]]
```

Decorator for monitoring function performance via the global CodeProfiler.

### `ProgressBar`

*class — defined in `infrastructure.core.progress`*

```python
class ProgressBar(total: int, task: str='', width: int=30, show_eta: bool=True, update_interval: float=0.1, use_ema: bool=True)
```

Simple text-based progress bar for terminal output.

### `SystemHealthChecker`

*class — defined in `infrastructure.core.runtime.health_check`*

```python
class SystemHealthChecker(repo_root: Path | None=None, start_time: float | None=None, network_test_hosts: tuple[str, ...] | None=None)
```

Comprehensive system health monitoring.

### `TemplateError`

*class — defined in `infrastructure.core._exceptions_core`*

```python
class TemplateError(message: str, context: dict[str, Any] | None=None, suggestions: list[str] | None=None, recovery_commands: list[str] | None=None)
```

Base exception for all template-related errors.

## Package: `infrastructure.doctor`

### `build_plans_for_findings`

*function — defined in `infrastructure.doctor.fixers`*

```python
build_plans_for_findings(findings: list[Finding], state: DoctorState, *, max_therapy: TherapyLevel=TherapyLevel.CONSERVATIVE, selected_codes: frozenset[str] | None=None, selected_fix_ids: frozenset[str] | None=None) -> list[FixPlan]
```

Translate findings into a deduplicated, ordered list of plans.

### `compute_exit_code`

*function — defined in `infrastructure.doctor.reporter`*

```python
compute_exit_code(findings: Iterable[Finding]) -> int
```

Map the worst finding severity into a stable exit code.

### `compute_scorecard`

*function — defined in `infrastructure.doctor.scorecard`*

```python
compute_scorecard(findings: Iterable[Finding]) -> tuple[float, dict[str, float]]
```

Return ``(overall, per_dimension)`` 0–100 scores.

### `DETECTORS`

*symbol — defined in `infrastructure.doctor.detectors`*

### `DIMENSION_WEIGHTS`

*constant — defined in `infrastructure.doctor.scorecard`*

```python
DIMENSION_WEIGHTS: dict[str, float] = {'environment': 2.0, 'project_layout': 2.0, 'hygiene': 1.0, 'tooling_state': ...
```

### `DIMENSIONS`

*constant — defined in `infrastructure.doctor.scorecard`*

```python
DIMENSIONS: dict[str, str] = {'DOC1': 'environment', 'DOC2': 'project_layout', 'DOC3': 'hygiene', 'DOC4': ...
```

### `DoctorReport`

*class — defined in `infrastructure.doctor.models`*

```python
class DoctorReport
```

Aggregate result of one doctor run.

### `DoctorSafetyError`

*class — defined in `infrastructure.doctor.safety`*

```python
class DoctorSafetyError(RuntimeError)
```

Raised when the safety contract cannot be honoured.

### `DoctorState`

*class — defined in `infrastructure.doctor.safety`*

```python
class DoctorState(repo_root: Path)
```

Filesystem layout for doctor state.

### `EXIT_CRITICAL`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_CRITICAL = 3
```

### `EXIT_ERROR`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_ERROR = 2
```

### `EXIT_HEALTHY`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_HEALTHY = 0
```

### `EXIT_REGRESSION`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_REGRESSION = 4
```

### `EXIT_USAGE`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_USAGE = 64
```

### `EXIT_WARN`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_WARN = 1
```

### `Finding`

*class — defined in `infrastructure.doctor.models`*

```python
class Finding
```

Outcome of one read-only detector.

### `FIXER_REGISTRY`

*constant — defined in `infrastructure.doctor.fixers`*

```python
FIXER_REGISTRY: dict[str, FixerFn] = {'fix_make_run_sh_executable': build_fix_make_run_sh_executable, 'fix_clean_p...
```

### `FixPlan`

*class — defined in `infrastructure.doctor.models`*

```python
class FixPlan
```

Declarative description of an intended mutation.

### `load_journal`

*function — defined in `infrastructure.doctor.safety`*

```python
load_journal(state: DoctorState) -> list[MutateRecord]
```

Return every record in the journal, oldest first.

### `mutate`

*function — defined in `infrastructure.doctor.safety`*

```python
mutate(plan: FixPlan, state: DoctorState) -> MutateRecord
```

Execute ``plan`` under the full safety contract.

### `MutateRecord`

*class — defined in `infrastructure.doctor.models`*

```python
class MutateRecord
```

Audit record produced by the mutate() chokepoint.

### `register_handler`

*function — defined in `infrastructure.doctor.safety`*

```python
register_handler(action_kind: str, handler: ActionHandler) -> None
```

Register an :class:`ActionHandler` for ``action_kind``.

### `render_report_json`

*function — defined in `infrastructure.doctor.reporter`*

```python
render_report_json(report: DoctorReport, *, indent: int | None=2) -> str
```

Render the report as JSON for agent consumption.

### `render_report_text`

*function — defined in `infrastructure.doctor.reporter`*

```python
render_report_text(report: DoctorReport) -> str
```

Render the full report as a text block.

### `RepairLevel`

*class — defined in `infrastructure.doctor.models`*

```python
class RepairLevel
```

One available therapy for a finding.

### `run_detectors`

*symbol — defined in `infrastructure.doctor.detectors`*

### `Severity`

*class — defined in `infrastructure.doctor.models`*

```python
class Severity(IntEnum)
```

Ordered diagnostic severity. Higher = worse.

### `TherapyLevel`

*class — defined in `infrastructure.doctor.models`*

```python
class TherapyLevel(IntEnum)
```

How radical a fixer is.

### `undo`

*function — defined in `infrastructure.doctor.safety`*

```python
undo(record: MutateRecord, state: DoctorState) -> MutateRecord
```

Restore the filesystem to the pre-mutation state for ``record``.

## Package: `infrastructure.documentation`

### `ApiEntry`

*class — defined in `infrastructure.documentation.glossary_gen`*

```python
class ApiEntry
```

Represents a public API entry from source code.

### `build_api_index`

*function — defined in `infrastructure.documentation.glossary_gen`*

```python
build_api_index(src_dir: str) -> list[ApiEntry]
```

Scan `src_dir` and collect public functions/classes with summaries.

### `FigureManager`

*class — defined in `infrastructure.documentation.figure_manager`*

```python
class FigureManager(registry_file: str | None=None)
```

Manages figures with automatic numbering and cross-referencing.

### `FigureMetadata`

*class — defined in `infrastructure.documentation.figure_manager`*

```python
class FigureMetadata
```

Metadata for a figure.

### `generate_markdown_table`

*function — defined in `infrastructure.documentation.glossary_gen`*

```python
generate_markdown_table(entries: list[ApiEntry]) -> str
```

Generate a Markdown table from API entries.

### `ImageManager`

*class — defined in `infrastructure.documentation.image_manager`*

```python
class ImageManager(figure_manager: FigureManager | None=None)
```

Manages image insertion and cross-referencing in markdown files.

### `MarkdownIntegration`

*class — defined in `infrastructure.documentation.markdown_integration`*

```python
class MarkdownIntegration(manuscript_dir: Path | None=None, figure_manager: FigureManager | None=None)
```

Integrates figures and references into markdown files.

## Package: `infrastructure.llm`

### `generate_review_with_metrics`

*function — defined in `infrastructure.llm.review.generation`*

```python
generate_review_with_metrics(client: LLMClient, text: str, review_type: ReviewType, review_name: str, template_class: 'type[ResearchTemplate]', model_name: str='', temperature: float=0.3, max_tokens: int | None=None, max_retries: int=1) -> tuple[str | None, ReviewMetrics]
```

Generate a review using a specified template and record execution metrics.

### `GenerationOptions`

*class — defined in `infrastructure.llm.core.config`*

```python
class GenerationOptions
```

Per-query generation options for LLM requests.

### `get_template`

*function — defined in `infrastructure.llm.templates`*

```python
get_template(name: str) -> ResearchTemplate
```

Get a template by name.

### `is_off_topic`

*function — defined in `infrastructure.llm.validation.format`*

```python
is_off_topic(text: str) -> bool
```

Check if response contains off-topic indicators.

### `LLMClient`

*class — defined in `infrastructure.llm.core.client`*

```python
class LLMClient(config: OllamaClientConfig | None=None)
```

Client for interacting with LLM providers (Ollama).

### `OllamaClientConfig`

*class — defined in `infrastructure.llm.core.config`*

```python
class OllamaClientConfig(**kwargs: Any)
```

Configuration for LLM interaction.

### `validate_complete`

*function — defined in `infrastructure.llm.validation.core`*

```python
validate_complete(content: str, mode: ResponseMode=ResponseMode.STANDARD, schema: dict[str, Any] | None=None) -> bool
```

Validate LLM response content based on the response mode.

## Package: `infrastructure.methods`

### `build_methods_orchestration_plan`

*function — defined in `infrastructure.methods.orchestration`*

```python
build_methods_orchestration_plan(repo_root: Path | str, project_name: str, *, projects_dir: str='projects') -> MethodsOrchestrationPlan
```

Build a deterministic methods orchestration plan for a project.

### `MethodsIssue`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsIssue
```

One methods orchestration validation issue.

### `MethodsOrchestrationPlan`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsOrchestrationPlan
```

Repository-derived methods orchestration plan for one project.

### `MethodStage`

*class — defined in `infrastructure.methods.models`*

```python
class MethodStage
```

One pipeline stage viewed as a methods/reproducibility contract.

### `render_methods_orchestration_markdown`

*function — defined in `infrastructure.methods.orchestration`*

```python
render_methods_orchestration_markdown(plan: MethodsOrchestrationPlan) -> str
```

Render a methods orchestration plan as Markdown.

### `validate_methods_orchestration_plan`

*function — defined in `infrastructure.methods.orchestration`*

```python
validate_methods_orchestration_plan(plan: MethodsOrchestrationPlan, *, repo_root: Path | str='.') -> tuple[MethodsIssue, ...]
```

Validate that the methods plan has the publication-critical surfaces.

## Package: `infrastructure.orchestration`

### `build_parser`

*function — defined in `infrastructure.orchestration.cli`*

```python
build_parser() -> argparse.ArgumentParser
```

Build the top-level argparse parser.

### `main`

*function — defined in `infrastructure.orchestration.cli`*

```python
main(argv: Sequence[str] | None=None) -> int
```

Entry point. Returns process exit code.

### `MENU_OPTIONS`

*constant — defined in `infrastructure.orchestration.menu`*

```python
MENU_OPTIONS: tuple[tuple[str, str, str], ...] = (('0', 'Environment Setup', '00_setup_environment.py'), ('1', 'Run Tests', '0...
```

### `PipelineRunner`

*class — defined in `infrastructure.orchestration.pipeline_runner`*

```python
class PipelineRunner
```

Thin facade over :class:`PipelineExecutor`.

### `render_menu`

*function — defined in `infrastructure.orchestration.menu`*

```python
render_menu(current_project: str) -> str
```

Return a deterministic menu string for the given current project.

### `run_secure_pipeline`

*function — defined in `infrastructure.orchestration.secure_run`*

```python
run_secure_pipeline(repo_root: Path, options: SecureRunOptions, *, runner_cls=PipelineRunner, processor_factory=None) -> int
```

Run the secure pipeline.

### `select_project_interactive`

*function — defined in `infrastructure.orchestration.discovery`*

```python
select_project_interactive(projects: Sequence[ProjectInfo], *, current: str | None=None, reader: Callable[[], str]=input, writer: TextIO | None=None) -> str | None
```

Interactive project picker.

### `setup_stage_log`

*function — defined in `infrastructure.orchestration.stage_logger`*

```python
setup_stage_log(repo_root: Path, project_name: str, stage_name: str, *, log_name: str=DEFAULT_LOG_NAME, layout: str='per_project', now: datetime | None=None) -> Path
```

Create the log directory and append a session-start banner.

### `validate_project_slug`

*function — defined in `infrastructure.orchestration.discovery`*

```python
validate_project_slug(slug: str, repo_root: Path) -> str
```

Validate a user-supplied project slug against discovered projects.

## Package: `infrastructure.project`

### `build_codegraph_files_command`

*function — defined in `infrastructure.project.codegraph`*

```python
build_codegraph_files_command(path: Path) -> CodeGraphCommand
```

Build a JSON file-list command for scope verification.

### `build_codegraph_init_command`

*function — defined in `infrastructure.project.codegraph`*

```python
build_codegraph_init_command(path: Path, *, index: bool=True) -> CodeGraphCommand
```

Build the recommended CodeGraph initialization command for ``path``.

### `build_scope_check_command`

*function — defined in `infrastructure.project.codegraph`*

```python
build_scope_check_command(path: Path) -> CodeGraphCommand
```

Build the first command in the CodeGraph scope verification workflow.

### `CodeGraphCommand`

*class — defined in `infrastructure.project.codegraph`*

```python
class CodeGraphCommand
```

A shell command recommendation without executing it.

### `discover_projects`

*function — defined in `infrastructure.project.discovery`*

```python
discover_projects(repo_root: Path | str, projects_dir: str='projects') -> list[ProjectInfo]
```

Discover all valid projects in the active projects directory.

### `find_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
find_setup_hook(project_dir: Path) -> Path | None
```

Locate the project's setup hook script, if any.

### `get_project_metadata`

*function — defined in `infrastructure.project.metadata`*

```python
get_project_metadata(project_dir: Path) -> dict[str, Any]
```

Extract metadata from project configuration files.

### `preflight_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
preflight_setup_hook(project_dir: Path) -> tuple[bool, list[str]]
```

Validate the project's setup-hook prerequisites.

### `ProjectInfo`

*class — defined in `infrastructure.project.project_info`*

```python
class ProjectInfo
```

Information about a discovered project.

### `public_ci_source_paths`

*symbol — defined in `infrastructure.project`*

### `public_project_infos`

*symbol — defined in `infrastructure.project`*

### `PUBLIC_PROJECT_NAMES`

*symbol — defined in `infrastructure.project`*

### `public_project_names`

*symbol — defined in `infrastructure.project`*

### `resolve_project_root`

*function — defined in `infrastructure.core.project_paths`*

```python
resolve_project_root(repo_root: Path | str, project_name: str) -> Path
```

Return the directory for *project_name*, preferring the hot seat over WIP trees.

### `run_project_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
run_project_setup_hook(project_dir: Path) -> bool
```

Run the project's setup hook, if present.

### `validate_project_structure`

*function — defined in `infrastructure.project.validation`*

```python
validate_project_structure(project_dir: Path) -> tuple[bool, str]
```

Validate that project has required directory structure.

### `verify_codegraph_scope_payload`

*function — defined in `infrastructure.project.codegraph`*

```python
verify_codegraph_scope_payload(payload: str) -> list[str]
```

Return private/local project paths found in a CodeGraph files payload.

## Package: `infrastructure.prose`

### `analyze_files`

*function — defined in `infrastructure.prose.report`*

```python
analyze_files(files: Mapping[str, str], *, long_sentence_threshold: int=35) -> ManuscriptReport
```

Build a :class:`ManuscriptReport` from a ``{filename: text}`` mapping.

### `analyze_manuscript`

*function — defined in `infrastructure.prose.report`*

```python
analyze_manuscript(manuscript_dir: Path | str, *, long_sentence_threshold: int=35) -> ManuscriptReport
```

Read every Markdown file in *manuscript_dir* and analyse it.

### `analyze_quality`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
analyze_quality(text: str, *, long_sentence_threshold: int=35) -> QualityReport
```

Run every detector over *text* and return a :class:`QualityReport`.

### `analyze_structure`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
analyze_structure(markdown: str) -> StructureReport
```

Build a :class:`StructureReport` for *markdown*.

### `analyze_text`

*function — defined in `infrastructure.prose.report`*

```python
analyze_text(name: str, raw_text: str, *, long_sentence_threshold: int=35) -> FileReport
```

Analyze a single text blob and return a :class:`FileReport`.

### `compute_metrics`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
compute_metrics(text: str) -> ProseMetrics
```

Compute :class:`ProseMetrics` for *text*.

### `count_syllables`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
count_syllables(word: str) -> int
```

Estimate syllables in *word* using vowel-group heuristic.

### `detect_hedge_words`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_hedge_words(text: str) -> list[str]
```

Return list of hedge words present in *text* (with duplicates).

### `detect_long_sentences`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_long_sentences(text: str, *, threshold: int=35) -> list[str]
```

Return sentences with > *threshold* words.

### `detect_passive_sentences`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_passive_sentences(text: str) -> list[str]
```

Return sentences with at least one "be + past participle" pair.

### `extract_citation_keys`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
extract_citation_keys(text: str) -> list[str]
```

Extract Pandoc-style ``@key`` citations from *text*.

### `FileReport`

*class — defined in `infrastructure.prose.report`*

```python
class FileReport
```

Per-file prose report.

### `Heading`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class Heading
```

One heading in a Markdown document.

### `is_complex_word`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
is_complex_word(word: str) -> bool
```

A "complex word" for Gunning Fog: ≥3 syllables, not proper noun,

### `load_report_json`

*function — defined in `infrastructure.prose.report`*

```python
load_report_json(path: Path | str) -> ManuscriptReport
```

Load a :class:`ManuscriptReport` from on-disk JSON.

### `ManuscriptReport`

*class — defined in `infrastructure.prose.report`*

```python
class ManuscriptReport
```

Aggregate report for an entire manuscript directory.

### `normalise_for_prose`

*function — defined in `infrastructure.prose.markdown`*

```python
normalise_for_prose(text: str) -> str
```

Apply all stripping passes in canonical order.

### `parse_headings`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
parse_headings(markdown: str) -> list[Heading]
```

Extract ATX (#-style) headings from *markdown*, ignoring code fences.

### `ProseMetrics`

*class — defined in `infrastructure.prose.analysis.metrics`*

```python
class ProseMetrics
```

Container for prose metrics.

### `QualityReport`

*class — defined in `infrastructure.prose.analysis.quality`*

```python
class QualityReport
```

Aggregate quality flags.

### `read_manuscript_dir`

*function — defined in `infrastructure.prose.markdown`*

```python
read_manuscript_dir(manuscript_dir: Path | str, *, include: str='*.md', exclude_filenames: tuple[str, ...]=('preamble.md', 'config.yaml.example', 'AGENTS.md', 'README.md', 'SYNTAX.md')) -> dict[str, str]
```

Read every Markdown file in *manuscript_dir* into a ``{name: text}`` map.

### `render_outline`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
render_outline(report: StructureReport) -> str
```

Render *report* as a plain-text bulleted outline.

### `Section`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class Section
```

A heading together with the body text up to the next same-or-shallower heading.

### `split_paragraphs`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
split_paragraphs(text: str) -> list[str]
```

Split *text* on blank lines into non-empty paragraphs.

### `split_sentences`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
split_sentences(text: str) -> list[str]
```

Split *text* into sentences using a conservative heuristic.

### `strip_fences`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_fences(text: str) -> str
```

Remove fenced code blocks (``` ... ```).

### `strip_front_matter`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_front_matter(text: str) -> str
```

Remove a leading YAML front-matter block, if any.

### `strip_inline_code`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_inline_code(text: str) -> str
```

Remove inline code spans (`...`).

### `strip_links_to_text`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_links_to_text(text: str) -> str
```

Replace ``[label](url)`` with ``label`` and drop ``![alt](url)``.

### `StructureReport`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class StructureReport
```

Outline of a Markdown document, with per-section word counts.

### `tokenize_words`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
tokenize_words(text: str) -> list[str]
```

Return the list of word tokens in *text*.

### `write_report`

*function — defined in `infrastructure.prose.report`*

```python
write_report(report: ManuscriptReport, output_path: Path | str) -> Path
```

Persist *report* as pretty-printed JSON.

## Package: `infrastructure.publishing`

### `calculate_complexity_score`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
calculate_complexity_score(metadata: PublicationMetadata) -> int
```

Backwards-compatible alias — prefer ``calculate_metadata_complexity_score``.

### `CitationStyle`

*class — defined in `infrastructure.publishing.models`*

```python
class CitationStyle
```

Container for citation style configuration.

### `create_academic_profile_data`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
create_academic_profile_data(metadata: PublicationMetadata) -> dict[str, Any]
```

Create academic profile data for ORCID, ResearchGate, etc.

### `create_github_release`

*function — defined in `infrastructure.publishing.github.release`*

```python
create_github_release(tag_name: str, release_name: str, description: str, assets: list[Path], token: str, repo: str, *, base_url: str='https://api.github.com', target_commitish: str='main') -> str
```

Create a GitHub release with attached assets.

### `create_publication_announcement`

*function — defined in `infrastructure.publishing.announcement`*

```python
create_publication_announcement(metadata: PublicationMetadata) -> str
```

Create a publication announcement for social media and blogs.

### `create_publication_package`

*function — defined in `infrastructure.publishing.package`*

```python
create_publication_package(output_dir: Path, metadata: PublicationMetadata) -> dict[str, Any]
```

Create a publication package with all necessary files.

### `create_repository_metadata`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
create_repository_metadata(metadata: PublicationMetadata) -> str
```

Create repository metadata JSON for GitHub/GitLab.

### `create_submission_checklist`

*function — defined in `infrastructure.publishing.checklist`*

```python
create_submission_checklist(metadata: PublicationMetadata) -> str
```

Create a submission checklist for academic conferences/journals.

### `extract_citations_from_markdown`

*function — defined in `infrastructure.publishing.citations`*

```python
extract_citations_from_markdown(markdown_files: list[Path]) -> list[str]
```

Extract all citations from markdown files.

### `extract_publication_metadata`

*function — defined in `infrastructure.publishing._metadata_extraction`*

```python
extract_publication_metadata(markdown_files: list[Path]) -> PublicationMetadata
```

Extract publication metadata from markdown files.

### `generate_citation_apa`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_apa(metadata: PublicationMetadata) -> str
```

Generate APA citation format.

### `generate_citation_bibtex`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_bibtex(metadata: PublicationMetadata) -> str
```

Generate BibTeX citation format.

### `generate_citation_mla`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_mla(metadata: PublicationMetadata) -> str
```

Generate MLA citation format.

### `generate_citations_markdown`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citations_markdown(metadata: PublicationMetadata) -> str
```

Generate markdown section with all citation formats.

### `generate_doi_badge`

*function — defined in `infrastructure.publishing.announcement`*

```python
generate_doi_badge(doi: str, style: str='zenodo') -> str
```

Generate DOI badge markdown.

### `generate_publication_metrics`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
generate_publication_metrics(metadata: PublicationMetadata) -> dict[str, Any]
```

Generate publication metrics for reporting.

### `generate_publication_summary`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
generate_publication_summary(metadata: PublicationMetadata) -> str
```

Generate a publication summary for repository README.

### `prepare_arxiv_submission`

*function — defined in `infrastructure.publishing.arxiv.submission`*

```python
prepare_arxiv_submission(output_dir: Path, metadata: PublicationMetadata) -> Path
```

Prepare a submission package for arXiv upload.

### `PublicationMetadata`

*class — defined in `infrastructure.publishing.models`*

```python
class PublicationMetadata
```

Container for publication metadata.

### `publish_to_zenodo`

*function — defined in `infrastructure.publishing.zenodo.publish`*

```python
publish_to_zenodo(metadata: PublicationMetadata, file_paths: list[Path], access_token: str, sandbox: bool=True, *, base_url: str | None=None) -> PublishResult
```

Publish research artifacts to Zenodo and return DOI plus deposition id.

### `validate_doi`

*function — defined in `infrastructure.publishing._metadata_extraction`*

```python
validate_doi(doi: str) -> bool
```

Validate DOI format and checksum.

### `validate_publication_readiness`

*function — defined in `infrastructure.publishing.readiness`*

```python
validate_publication_readiness(markdown_files: list[Path], pdf_files: list[Path]) -> dict[str, Any]
```

Validate that the project is ready for publication.

### `ZenodoClient`

*class — defined in `infrastructure.publishing.zenodo.client`*

```python
class ZenodoClient(config: ZenodoConfig)
```

Client for the Zenodo Deposit REST API.

### `ZenodoConfig`

*class — defined in `infrastructure.publishing.zenodo.config`*

```python
class ZenodoConfig
```

Configuration for Zenodo API client.

## Package: `infrastructure.reference`

### `BibDatabase`

*class — defined in `infrastructure.reference.citation.models`*

```python
class BibDatabase
```

A collection of :class:`BibEntry` records preserving insertion order.

### `BibEntry`

*class — defined in `infrastructure.reference.citation.models`*

```python
class BibEntry
```

A single BibTeX record.

### `BibParseError`

*class — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
class BibParseError(ValueError)
```

Raised when the parser encounters a malformed BibTeX construct.

### `generate_citation_key`

*function — defined in `infrastructure.reference.citation.converter`*

```python
generate_citation_key(*, authors: list[str], year: int | str | None, title: str, fallback: str='anon') -> str
```

Build a citation key in the project's house style.

### `paper_to_bibentry`

*function — defined in `infrastructure.reference.citation.converter`*

```python
paper_to_bibentry(paper: 'Paper', *, citation_key: str | None=None, entry_type: str | None=None) -> BibEntry
```

Convert a :class:`Paper` record into a :class:`BibEntry`.

### `parse_bibfile`

*function — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
parse_bibfile(path: Path | str, *, encoding: str='utf-8') -> BibDatabase
```

Read and parse a ``.bib`` file from *path*.

### `parse_bibtex`

*function — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
parse_bibtex(text: str) -> BibDatabase
```

Parse *text* into a :class:`BibDatabase`.

### `render_database`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
render_database(database: BibDatabase) -> str
```

Render an entire :class:`BibDatabase` to a BibTeX string.

### `render_entry`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
render_entry(entry: BibEntry) -> str
```

Render a single :class:`BibEntry` to a BibTeX string.

### `write_bibfile`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
write_bibfile(path: Path | str, database: BibDatabase, *, encoding: str='utf-8') -> Path
```

Render *database* and write it to *path*.

## Package: `infrastructure.rendering`

### `discover_manuscript_files`

*function — defined in `infrastructure.rendering.manuscript_discovery`*

```python
discover_manuscript_files(manuscript_dir: Path) -> list[Path]
```

Discover manuscript files with proper ordering and filtering.

### `DocxRenderResult`

*class — defined in `infrastructure.rendering.docx_renderer`*

```python
class DocxRenderResult
```

Outcome of a DOCX render.

### `EpubRenderResult`

*class — defined in `infrastructure.rendering.epub_renderer`*

```python
class EpubRenderResult
```

Outcome of an EPUB render.

### `EXCLUDED_DOC_FILENAMES`

*constant — defined in `infrastructure.rendering.manuscript_injection`*

```python
EXCLUDED_DOC_FILENAMES: frozenset[str] = frozenset({'AGENTS.md', 'README.md', 'SYNTAX.md'})
```

### `render_docx`

*function — defined in `infrastructure.rendering.docx_renderer`*

```python
render_docx(combined_md: Path, output_path: Path, *, bibliography: Path | None=None, reference_doc: Path | None=None, pandoc_path: str='pandoc', extra_args: list[str] | None=None) -> DocxRenderResult
```

Render *combined_md* to a DOCX at *output_path*.

### `render_epub`

*function — defined in `infrastructure.rendering.epub_renderer`*

```python
render_epub(combined_md: Path, output_path: Path, *, bibliography: Path | None=None, cover_image: Path | None=None, pandoc_path: str='pandoc', extra_args: list[str] | None=None) -> EpubRenderResult
```

Render *combined_md* to an EPUB at *output_path*.

### `RenderingConfig`

*class — defined in `infrastructure.rendering.config`*

```python
class RenderingConfig
```

Configuration for rendering output.

### `RenderManager`

*class — defined in `infrastructure.rendering.core`*

```python
class RenderManager(config: RenderingConfig | None=None, manuscript_dir: Path | None=None, figures_dir: Path | None=None)
```

Orchestrates rendering of all output formats.

### `substitute_manuscript_text`

*function — defined in `infrastructure.rendering.manuscript_injection`*

```python
substitute_manuscript_text(text: str, variables: dict[str, str]) -> tuple[str, list[str]]
```

Replace ``{{KEY}}`` placeholders in *text* with values from *variables*.

### `verify_figures_exist`

*function — defined in `infrastructure.rendering.manuscript_discovery`*

```python
verify_figures_exist(project_root: Path, manuscript_dir: Path) -> dict[str, Any]
```

Verify expected figures exist, return status.

### `write_resolved_manuscript_tree`

*function — defined in `infrastructure.rendering.manuscript_injection`*

```python
write_resolved_manuscript_tree(project_root: Path | str, variables: dict[str, str]) -> Path
```

Write resolved copies of ``manuscript/*.md`` into ``output/manuscript/``.

## Package: `infrastructure.reporting`

### `collect_output_statistics`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
collect_output_statistics(repo_root: Path, project_name: str='project', project_dir: Path | None=None) -> dict[str, Any]
```

Collect comprehensive output file statistics.

### `collect_project_metrics`

*function — defined in `infrastructure.reporting._executive_collectors`*

```python
collect_project_metrics(repo_root: Path, project_name: str, project_dir: Path | None=None) -> ProjectMetrics
```

Collect all metrics for a single project.

### `Control`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Control
```

One interactive control (slider / dropdown / toggle).

### `DASHBOARD_AVAILABLE`

*constant — defined in `infrastructure.reporting`*

```python
DASHBOARD_AVAILABLE = True
```

### `ErrorAggregator`

*class — defined in `infrastructure.reporting.error_aggregator`*

```python
class ErrorAggregator()
```

Aggregate and categorize errors from pipeline execution.

### `ErrorEntry`

*class — defined in `infrastructure.reporting.error_aggregator`*

```python
class ErrorEntry
```

Single error or warning entry.

### `ExecutiveSummary`

*class — defined in `infrastructure.reporting._executive_models`*

```python
class ExecutiveSummary
```

Executive summary aggregating all project metrics.

### `FileType`

*class — defined in `infrastructure.reporting.output_organizer`*

```python
class FileType(Enum)
```

Enumeration of supported file types for output organization.

### `generate_executive_summary`

*function — defined in `infrastructure.reporting._executive_renderers`*

```python
generate_executive_summary(repo_root: Path, project_names: list[str]) -> ExecutiveSummary
```

Generate complete executive summary for all projects.

### `generate_markdown_report`

*function — defined in `infrastructure.reporting.markdown_formatter`*

```python
generate_markdown_report(data: dict[str, Any]) -> str
```

Generate human-readable markdown report from test data.

### `generate_multi_project_report`

*function — defined in `infrastructure.reporting.multi_project_reporter`*

```python
generate_multi_project_report(repo_root: Path, project_names: list[str], output_dir: Path) -> dict[str, Path]
```

Orchestrate executive reporting for multiple projects into output_dir.

### `generate_multi_project_summary_report`

*function — defined in `infrastructure.reporting.multi_project_reporter`*

```python
generate_multi_project_summary_report(result: MultiProjectResult, projects: list[Any], output_dir: Path) -> dict[str, Path]
```

Generate comprehensive multi-project summary report.

### `generate_pipeline_report`

*function — defined in `infrastructure.reporting.pipeline_report_model`*

```python
generate_pipeline_report(stage_results: list[_StageResultDict], total_duration: float, repo_root: Path, *, test_results: dict[str, Any] | None=None, validation_results: dict[str, Any] | None=None, performance_metrics: dict[str, Any] | None=None, error_summary: dict[str, Any] | None=None, output_statistics: dict[str, Any] | None=None, project_name: str | None=None, project_dir: Path | None=None) -> PipelineReport
```

Generate consolidated pipeline report from stage results and optional extras.

### `generate_summary_report`

*function — defined in `infrastructure.reporting.report_builder`*

```python
generate_summary_report(repo_root: Path | None=None) -> dict[str, Any]
```

Generate comprehensive test summary report.

### `get_error_aggregator`

*function — defined in `infrastructure.reporting.error_aggregator`*

```python
get_error_aggregator() -> 'ErrorAggregator'
```

Get global error aggregator instance (lazily initialized).

### `InteractiveDashboard`

*class — defined in `infrastructure.reporting.interactive_dashboard`*

```python
class InteractiveDashboard(title: str, subtitle: str='', project_name: str='', repo_root: Path | None=None)
```

Build a single self-contained interactive simulation dashboard.

### `Invariant`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Invariant
```

A single numerical invariant to validate.

### `load_infrastructure_results`

*function — defined in `infrastructure.reporting.result_loaders`*

```python
load_infrastructure_results(repo_root: Path | None=None) -> InfraResults
```

Load infrastructure test results from root coverage files.

### `load_test_results`

*function — defined in `infrastructure.reporting.result_loaders`*

```python
load_test_results(project_name: str, repo_root: Path | None=None, project_dir: Path | None=None) -> dict[str, Any]
```

Load test results from a project's output directory; returns {} if not found.

### `log_output_summary`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
log_output_summary(output_dir: Path, stats: dict[str, Any], structure_validation: dict[str, Any] | None=None) -> None
```

Generate summary of output copying results.

### `OutputOrganizer`

*class — defined in `infrastructure.reporting.output_organizer`*

```python
class OutputOrganizer
```

Centralized organizer for executive summary and multi-project outputs.

### `Panel`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Panel
```

One Plotly figure on the dashboard.

### `ProjectMetrics`

*class — defined in `infrastructure.reporting._executive_models`*

```python
class ProjectMetrics
```

Complete metrics for a single project.

### `reset_error_aggregator`

*function — defined in `infrastructure.reporting.error_aggregator`*

```python
reset_error_aggregator() -> None
```

Reset global error aggregator (for testing).

### `run_test_summary_generation`

*function — defined in `infrastructure.reporting.markdown_formatter`*

```python
run_test_summary_generation() -> int
```

Main entry point for generating test summary reports.

### `save_error_summary`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_error_summary(errors: list[dict[str, Any]], output_dir: Path) -> dict[str, Any]
```

Aggregate errors, write JSON and Markdown reports, and return the summary dict.

### `save_executive_summary`

*function — defined in `infrastructure.reporting._executive_renderers`*

```python
save_executive_summary(summary: ExecutiveSummary, output_dir: Path) -> dict[str, Path]
```

Save executive summary in multiple formats.

### `save_performance_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_performance_report(performance_metrics: dict[str, Any], output_dir: Path) -> Path
```

Write performance_metrics dict to performance_report.json and return the path.

### `save_pipeline_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_pipeline_report(report: PipelineReport, output_dir: Path, formats: list[str] | None=None) -> dict[str, Path]
```

Save pipeline report in multiple formats; returns dict mapping format to path.

### `save_test_results`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_test_results(test_results: dict[str, Any], output_dir: Path) -> Path
```

Write test_results dict to test_results.json and return the path.

### `save_validation_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_validation_report(validation_results: dict[str, Any], output_dir: Path) -> dict[str, Path]
```

Generate validation report as JSON and Markdown; returns paths by format key.

### `write_output_statistics_reports`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
write_output_statistics_reports(project_output_dir: Path, stats: dict[str, Any]) -> tuple[Path, Path]
```

Write text and JSON output statistics reports under ``output/reports``.

## Package: `infrastructure.scientific`

### `benchmark_function`

*function — defined in `infrastructure.scientific.benchmarking`*

```python
benchmark_function(func: Callable[..., Any], test_inputs: list[Any], iterations: int=100) -> BenchmarkResult
```

Benchmark function performance across multiple inputs.

### `BenchmarkResult`

*class — defined in `infrastructure.scientific.benchmarking`*

```python
class BenchmarkResult
```

Container for benchmark results.

### `check_numerical_stability`

*function — defined in `infrastructure.scientific.stability`*

```python
check_numerical_stability(func: Callable[..., Any], test_inputs: list[Any], tolerance: float=1e-12) -> StabilityTest
```

Check numerical stability of a function across a range of inputs.

### `check_research_compliance`

*function — defined in `infrastructure.scientific.validation`*

```python
check_research_compliance(func: Callable[..., Any]) -> dict[str, Any]
```

Check function compliance with research software standards.

### `confirm_improvement`

*function — defined in `infrastructure.scientific.confirmation`*

```python
confirm_improvement(evaluate: Callable[[tuple[float, ...], int], float], candidate: tuple[float, ...], baseline_metric: float, seeds: Sequence[int], noise_scale: float, sigma: float=2.0) -> Confirmation
```

Confirm a candidate beats ``baseline_metric`` beyond the noise band.

### `Confirmation`

*class — defined in `infrastructure.scientific.confirmation`*

```python
class Confirmation
```

Outcome of a multi-seed confirmation check.

### `create_scientific_module_template`

*function — defined in `infrastructure.scientific.templates`*

```python
create_scientific_module_template(module_name: str) -> str
```

Create a template for a new scientific module.

### `create_scientific_test_suite`

*function — defined in `infrastructure.scientific.templates`*

```python
create_scientific_test_suite(module_name: str) -> str
```

Create a comprehensive test suite for a scientific module.

### `create_scientific_workflow_template`

*function — defined in `infrastructure.scientific.templates`*

```python
create_scientific_workflow_template(workflow_name: str) -> str
```

Create a template for scientific research workflows.

### `format_benchmark_report`

*function — defined in `infrastructure.scientific.benchmarking`*

```python
format_benchmark_report(benchmark_results: list[BenchmarkResult]) -> str
```

Format a Markdown performance analysis report from benchmark results.

### `generate_api_documentation`

*function — defined in `infrastructure.scientific.documentation`*

```python
generate_api_documentation(module: Any) -> str
```

Generate comprehensive API documentation for a scientific module.

### `generate_performance_report`

*function — defined in `infrastructure.scientific.benchmarking`*

```python
generate_performance_report(benchmark_results: list[BenchmarkResult]) -> str
```

Generate a performance analysis report.

### `generate_scientific_documentation`

*function — defined in `infrastructure.scientific.documentation`*

```python
generate_scientific_documentation(func: Callable[..., Any]) -> str
```

Generate scientific documentation for a function.

### `StabilityTest`

*class — defined in `infrastructure.scientific.stability`*

```python
class StabilityTest
```

Container for numerical stability test results.

### `validate_scientific_best_practices`

*function — defined in `infrastructure.scientific.validation`*

```python
validate_scientific_best_practices(module: Any) -> dict[str, Any]
```

Validate that a module follows scientific computing best practices.

### `validate_scientific_implementation`

*function — defined in `infrastructure.scientific.validation`*

```python
validate_scientific_implementation(func: Callable[..., Any], test_cases: list[tuple[Any, Any]]) -> _ValidationResults
```

Validate scientific implementation against known test cases.

## Package: `infrastructure.search`

### `AbstractFetcher`

*class — defined in `infrastructure.search.literature.fulltext`*

```python
class AbstractFetcher(*, http_client: HttpClient | None=None, cache_dir: Path | str | None=None, timeout: float=15.0, arxiv_base_url: str | None=None)
```

Populate :attr:`Paper.abstract` for records that lack one.

### `ArxivBackend`

*class — defined in `infrastructure.search.literature.arxiv_backend`*

```python
class ArxivBackend(*, http_client: HttpClient | None=None, base_url: str | None=None, timeout: float=15.0)
```

arXiv export API. Returns Atom XML; we parse it locally.

### `BackendError`

*class — defined in `infrastructure.search.literature.base`*

```python
class BackendError(RuntimeError)
```

Raised by a backend when the request itself fails (network, parse).

### `CrossrefBackend`

*class — defined in `infrastructure.search.literature.crossref_backend`*

```python
class CrossrefBackend(*, http_client: HttpClient | None=None, base_url: str | None=None, mailto: str | None=None, timeout: float=15.0)
```

Crossref REST API (no auth required).

### `enrich_papers`

*function — defined in `infrastructure.search.literature.fulltext`*

```python
enrich_papers(papers: Iterable[Paper], *, abstracts: AbstractFetcher | None=None, fulltext: FulltextFetcher | None=None, force: bool=False) -> list[FetchResult]
```

Run the configured fetchers over *papers* in order (abstract first).

### `ExaClient`

*class — defined in `infrastructure.search.exa.client`*

```python
class ExaClient(config: ExaConfig, *, http_client: ExaHttpClient | None=None)
```

Thin, dependency-injected client for the Exa REST API.

### `ExaConfig`

*class — defined in `infrastructure.search.exa.config`*

```python
class ExaConfig
```

Immutable Exa client configuration.

### `ExaError`

*class — defined in `infrastructure.search.exa.errors`*

```python
class ExaError(message: str, *, status: int | None=None, body: str | None=None)
```

Raised when an Exa request fails (transport, non-2xx status, or parse).

### `FetchResult`

*class — defined in `infrastructure.search.literature.fulltext`*

```python
class FetchResult
```

Outcome of a fetch operation.

### `FulltextFetcher`

*class — defined in `infrastructure.search.literature.fulltext`*

```python
class FulltextFetcher(*, http_client: HttpClient | None=None, cache_dir: Path | str | None=None, timeout: float=60.0, max_chars: int | None=200000)
```

Populate :attr:`Paper.fulltext` from PDF / HTML sources.

### `LiteratureClient`

*class — defined in `infrastructure.search.literature.client`*

```python
class LiteratureClient(backends: Iterable[SearchBackend], *, cache: SearchCache | None=None)
```

Run a :class:`SearchQuery` across multiple :class:`SearchBackend`s.

### `LocalBackend`

*class — defined in `infrastructure.search.literature.local_backend`*

```python
class LocalBackend(corpus_path: Path | str)
```

Search a JSON corpus on disk.

### `merge_papers`

*function — defined in `infrastructure.search.literature.models`*

```python
merge_papers(papers: Iterable[Paper]) -> list[Paper]
```

Deduplicate *papers* by canonical key, keeping the highest-scored copy.

### `Paper`

*class — defined in `infrastructure.search.literature.models`*

```python
class Paper
```

A normalised literature-search result.

### `PaperclipBackend`

*class — defined in `infrastructure.search.literature.paperclip_backend`*

```python
class PaperclipBackend(*, api_key: str, http_client: HttpClient | None=None, base_url: str | None=None, timeout: float=30.0)
```

Paperclip (paperclip.gxl.ai) HTTP backend.

### `SearchBackend`

*class — defined in `infrastructure.search.literature.base`*

```python
class SearchBackend(abc.ABC)
```

Abstract base class for literature-search backends.

### `SearchCache`

*class — defined in `infrastructure.search.literature.cache`*

```python
class SearchCache(cache_dir: Path | str, *, ttl_seconds: int | None=None)
```

JSON-file cache for :class:`SearchResult` objects.

### `SearchQuery`

*class — defined in `infrastructure.search.literature.models`*

```python
class SearchQuery
```

A literature search request.

### `SearchResult`

*class — defined in `infrastructure.search.literature.models`*

```python
class SearchResult
```

The aggregate response to a :class:`SearchQuery`.

### `write_corpus`

*function — defined in `infrastructure.search.literature.fulltext`*

```python
write_corpus(papers: Iterable[Paper], path: Path | str) -> Path
```

Persist a list of (possibly enriched) papers as a JSON corpus file.

## Package: `infrastructure.sia`

### `AgentExecutionLog`

*symbol — defined in `infrastructure.sia`*

### `append_generation`

*symbol — defined in `infrastructure.sia`*

### `EvaluationResult`

*symbol — defined in `infrastructure.sia`*

### `GenerationArtifacts`

*symbol — defined in `infrastructure.sia`*

### `GenerationState`

*symbol — defined in `infrastructure.sia`*

### `init_context`

*symbol — defined in `infrastructure.sia`*

### `load_agent_execution`

*symbol — defined in `infrastructure.sia`*

### `read_results_json`

*symbol — defined in `infrastructure.sia`*

### `run_evaluation`

*symbol — defined in `infrastructure.sia`*

### `run_sia_loop`

*symbol — defined in `infrastructure.sia`*

### `RunConfig`

*symbol — defined in `infrastructure.sia`*

### `TaskLayout`

*symbol — defined in `infrastructure.sia`*

### `validate_task_dir`

*symbol — defined in `infrastructure.sia`*

### `write_results_json`

*symbol — defined in `infrastructure.sia`*

## Package: `infrastructure.skills`

### `build_manifest_payload`

*function — defined in `infrastructure.skills.discovery`*

```python
build_manifest_payload(skills: Sequence[SkillDescriptor]) -> dict[str, Any]
```

Build the canonical JSON-serializable manifest structure.

### `build_skill_index_markdown`

*function — defined in `infrastructure.skills.discovery`*

```python
build_skill_index_markdown(skills: Sequence[SkillDescriptor], *, search_roots: Sequence[str] | None=None) -> str
```

Build a human-readable Markdown index for discovered skills.

### `check_skill_contracts`

*function — defined in `infrastructure.skills.contracts`*

```python
check_skill_contracts(repo_root: Path | str) -> list[str]
```

Return all docs/prompts skill contract issues for a repository.

### `DEFAULT_SKILL_SEARCH_ROOTS`

*constant — defined in `infrastructure.skills.discovery`*

```python
DEFAULT_SKILL_SEARCH_ROOTS: tuple[str, ...] = ('infrastructure', 'projects', 'docs/prompts', '.cursor/skills')
```

### `discover_skills`

*function — defined in `infrastructure.skills.discovery`*

```python
discover_skills(repo_root: Path | str, *, search_roots: Sequence[str] | None=None) -> list[SkillDescriptor]
```

Discover all ``SKILL.md`` files under configured roots and parse frontmatter.

### `iter_contract_skill_paths`

*function — defined in `infrastructure.skills.contracts`*

```python
iter_contract_skill_paths(repo_root: Path | str) -> Iterable[Path]
```

Yield workflow skill files whose metadata contract is enforced.

### `iter_skill_paths`

*function — defined in `infrastructure.skills.discovery`*

```python
iter_skill_paths(repo_root: Path, roots: Sequence[str]) -> Iterator[Path]
```

Yield absolute paths to ``SKILL.md`` under each root relative to ``repo_root``.

### `load_manifest`

*function — defined in `infrastructure.skills.discovery`*

```python
load_manifest(manifest_path: Path | str) -> dict[str, Any]
```

Load a manifest JSON file.

### `load_skill_descriptor`

*function — defined in `infrastructure.skills.discovery`*

```python
load_skill_descriptor(skill_path: Path, repo_root: Path) -> SkillDescriptor
```

Read a SKILL.md file and return a :class:`SkillDescriptor`.

### `manifest_matches_discovery`

*function — defined in `infrastructure.skills.discovery`*

```python
manifest_matches_discovery(repo_root: Path | str, manifest_path: Path | str, *, search_roots: Sequence[str] | None=None) -> tuple[bool, str]
```

Return whether the manifest matches current :func:`discover_skills` output.

### `manifest_skill_dicts_for_prompt`

*function — defined in `infrastructure.skills.discovery`*

```python
manifest_skill_dicts_for_prompt(skills: Sequence[SkillDescriptor]) -> list[dict[str, str]]
```

Compact rows suitable for logging or prompt injection.

### `skill_descriptors_as_json_serializable`

*function — defined in `infrastructure.skills.discovery`*

```python
skill_descriptors_as_json_serializable(skills: Sequence[SkillDescriptor]) -> list[dict[str, Any]]
```

Convert descriptors to plain dicts (paths as strings) for JSON APIs.

### `SkillDescriptor`

*class — defined in `infrastructure.skills.discovery`*

```python
class SkillDescriptor
```

One discovered skill file with parsed YAML frontmatter.

### `split_yaml_frontmatter`

*function — defined in `infrastructure.skills.discovery`*

```python
split_yaml_frontmatter(source: str) -> tuple[dict[str, Any] | None, str]
```

Split leading YAML frontmatter from markdown body.

### `validate_skill_contract_file`

*function — defined in `infrastructure.skills.contracts`*

```python
validate_skill_contract_file(skill_path: Path | str) -> list[str]
```

Return contract issues for one workflow ``SKILL.md`` file.

### `write_skill_manifest`

*function — defined in `infrastructure.skills.discovery`*

```python
write_skill_manifest(repo_root: Path | str, output_path: Path | str | None=None, *, search_roots: Sequence[str] | None=None) -> Path
```

Write skill manifest JSON for editors and agents.

## Package: `infrastructure.steganography`

### `embed_steganography`

*function — defined in `infrastructure.steganography.core`*

```python
embed_steganography(input_pdf: Path, output_pdf: Path | None=None, config: SteganographyConfig | None=None, title: str='', authors: list[str] | None=None, keywords: list[str] | None=None, author_emails: list[str] | None=None) -> Path
```

Convenience function — create a processor and run it.

### `process_pdf`

*constant — defined in `infrastructure.steganography.core`*

```python
process_pdf = embed_steganography
```

### `resolve_build_timestamp`

*function — defined in `infrastructure.steganography.config`*

```python
resolve_build_timestamp(*, deterministic: bool | None=None, repo_root: Path | None=None) -> str
```

Return an ISO-8601 build timestamp.

### `SteganographyConfig`

*class — defined in `infrastructure.steganography.config`*

```python
class SteganographyConfig
```

Configuration for steganographic PDF post-processing.

### `SteganographyProcessor`

*class — defined in `infrastructure.steganography.core`*

```python
class SteganographyProcessor(config: SteganographyConfig | None=None)
```

Orchestrates steganographic PDF post-processing.

## Package: `infrastructure.validation`

### `assign_severity`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
assign_severity(issue: ValidationIssue) -> str
```

Assign severity level to an issue.

### `categorize_by_type`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
categorize_by_type(issues: list[ValidationIssue]) -> dict[str, list[ValidationIssue]]
```

Categorize issues by their type and severity.

### `discover_markdown_files`

*function — defined in `infrastructure.validation.content.discovery`*

```python
discover_markdown_files(root: Path, *, scope: MarkdownDiscoveryScope='tree', repo_root: Path | None=None) -> list[Path]
```

Discover markdown files under *root* according to *scope*.

### `extract_text_from_pdf`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
extract_text_from_pdf(pdf_path: Path) -> str
```

Extract all text content from a PDF file with robust error handling and fallbacks.

### `filter_false_positives`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
filter_false_positives(issues: list[ValidationIssue]) -> list[ValidationIssue]
```

Filter out false positive issues from the list.

### `generate_audit_report`

*function — defined in `infrastructure.validation.repo.audit_orchestrator`*

```python
generate_audit_report(scan_results: ScanResults, output_format: str='markdown', show_green_flags: bool=False) -> str
```

Generate a formatted audit report with red/yellow/green severity flag classification.

### `generate_integrity_report`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
generate_integrity_report(report: IntegrityReport) -> str
```

Generate a human-readable integrity report.

### `generate_issue_summary`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
generate_issue_summary(issues: list[ValidationIssue]) -> dict[str, Any]
```

Generate a summary of issues by category and severity.

### `group_related_issues`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
group_related_issues(issues: list[ValidationIssue]) -> list[list[ValidationIssue]]
```

Group related issues together for better analysis.

### `is_false_positive`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
is_false_positive(issue: ValidationIssue) -> bool
```

Determine if an issue is likely a false positive.

### `LinkValidator`

*class — defined in `infrastructure.validation.integrity.link_validator`*

```python
class LinkValidator(repo_root: Path)
```

Validates markdown links and file references.

### `prioritize_issues`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
prioritize_issues(issues: list[ValidationIssue]) -> list[ValidationIssue]
```

Sort issues by priority (severity, then type).

### `run_comprehensive_audit`

*function — defined in `infrastructure.validation.repo.audit_orchestrator`*

```python
run_comprehensive_audit(repo_root: Path, verbose: bool=False, include_code_validation: bool=True, include_directory_validation: bool=True, include_import_validation: bool=True, include_placeholder_validation: bool=True) -> ScanResults
```

Run audit across all validation modules and return categorized scan results.

### `scan_for_issues`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
scan_for_issues(text: str) -> dict[str, int]
```

Scan extracted text for common rendering issues.

### `validate_citations`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_citations(md_paths: list[str], repo_root: str | Path, bib_file: str | Path | list[str | Path] | None=None) -> list[DiagnosticEvent]
```

Verify every ``[@key]`` citation resolves in the project's BibTeX file(s).

### `validate_copied_outputs`

*function — defined in `infrastructure.validation.output.validator`*

```python
validate_copied_outputs(output_dir: Path) -> bool
```

Validate all project outputs were copied successfully.

### `validate_figure_registry`

*function — defined in `infrastructure.validation.content.figure_validator`*

```python
validate_figure_registry(registry_path: Path, manuscript_dir: Path) -> tuple[bool, list[str]]
```

Validate figure registry against manuscript references.

### `validate_images`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_images(md_paths: list[str], repo_root: str | Path, extra_search_dirs: list[str | Path] | None=None) -> list[DiagnosticEvent]
```

Validate that all referenced images exist in the filesystem.

### `validate_markdown`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_markdown(markdown_dir: str | Path, repo_root: str | Path, strict: bool=False) -> tuple[list[DiagnosticEvent], int]
```

Validate all markdown files in a directory.

### `validate_math`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_math(md_paths: list[str], repo_root: str | Path) -> list[DiagnosticEvent]
```

Validate mathematical equation formatting and labeling.

### `validate_output_structure`

*function — defined in `infrastructure.validation.output.validator`*

```python
validate_output_structure(output_dir: Path) -> dict[str, Any]
```

Validate complete output directory structure.

### `validate_pandoc_pitfalls`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_pandoc_pitfalls(md_paths: list[str], repo_root: str | Path) -> list[DiagnosticEvent]
```

Flag markdown patterns Pandoc converts to LaTeX ``\mid`` in text mode.

### `validate_pdf_rendering`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
validate_pdf_rendering(pdf_path: Path, n_words: int=200) -> dict[str, Any]
```

Perform comprehensive validation of PDF rendering.

### `validate_refs`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_refs(md_paths: list[str], repo_root: str | Path, labels: set[str], anchors: set[str]) -> list[DiagnosticEvent]
```

Validate cross-references, internal links, and external URLs.

### `verify_academic_standards`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_academic_standards(markdown_files: list[Path]) -> dict[str, bool]
```

Verify compliance with academic writing standards.

### `verify_cross_references`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_cross_references(markdown_files: list[Path]) -> dict[str, bool]
```

Verify cross-reference integrity in markdown files.

### `verify_data_consistency`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_data_consistency(data_files: list[Path]) -> dict[str, bool]
```

Verify data file consistency and integrity.

### `verify_file_integrity`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_file_integrity(file_paths: list[Path], expected_hashes: dict[str, str] | None=None) -> dict[str, bool]
```

Verify file integrity using hash comparison.

### `verify_output_integrity`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_output_integrity(output_dir: Path, manuscript_dir: Path | None=None) -> IntegrityReport
```

Perform comprehensive integrity verification of all outputs.
<!-- END:API_REFERENCE -->

---

## Summary

This API reference covers all public functions and classes exported
from `infrastructure/<pkg>/__init__.py` (`__all__`). For
project-specific code, see each project's `src/AGENTS.md`.

All infrastructure modules:

- Follow the thin-orchestrator pattern
- Maintain required test coverage (90% project, 60% infra)
- Include type hints
- Provide detailed docstrings

**Related Documentation:**

- [Modules Guide](../modules/modules-guide.md) — Usage examples
- [Infrastructure Docs](../../infrastructure/AGENTS.md) — Infrastructure module implementation
- [Project Source Docs](../../projects/templates/template_code_project/src/AGENTS.md) — Project module implementation
- [Best Practices](../best-practices/best-practices.md) — Usage recommendations