infrastructure-overview

Category: Tools & Productivity | Uploader: docxology | Downloads: 0 | Version: v1.0（Latest）

Top-level skill for the research template infrastructure layer. Use in Cursor, Claude Code, or similar agents when editing or importing anything under infrastructure/, understanding the two-layer architecture, or wiring build/validation/rendering/publishing. Covers module discovery, import patterns, thin orchestrators, per-subpackage SKILL.md paths, and .cursor/skill_manifest.json (see infrastructure.skills).

Changelog: Source: GitHub https://github.com/docxology/template

Directory Structure

Current level: tree/main/infrastructure/

📁 config/
- 📄 .env.template 605 B
- 📄 AGENTS.md 684 B
- 📄 README.md 401 B
- 📄 secure_config.yaml 4.5 KB
- 📄 SKILL.md 1.1 KB
📁 core/
- 📁 config/
  - 📄 __init__.py 607 B
  - 📄 cli.py 2.6 KB
  - 📄 formatting.py 1.5 KB
  - 📄 loader.py 6.2 KB
  - 📄 queries.py 6.7 KB
  - 📄 schema.py 3.0 KB
- 📁 files/
  - 📄 __init__.py 654 B
  - 📄 cleanup.py 5.0 KB
  - 📄 cleanup_helpers.py 4.1 KB
  - 📄 cleanup_root.py 3.5 KB
  - 📄 coverage_cleanup.py 3.3 KB
  - 📄 inventory.py 6.8 KB
  - 📄 inventory_entry.py 1.1 KB
  - 📄 inventory_reports.py 5.3 KB
  - 📄 operations.py 8.2 KB
- 📁 logging/
  - 📄 __init__.py 1.4 KB
  - 📄 constants.py 1.2 KB
  - 📄 diagnostic.py 7.8 KB
  - 📄 formatters.py 2.1 KB
  - 📄 helpers.py 1.4 KB
  - 📄 pipeline_logging.py 7.1 KB
  - 📄 progress.py 9.3 KB
  - 📄 setup.py 6.2 KB
  - 📄 utils.py 3.7 KB
- 📁 pipeline/
  - 📄 __init__.py 1.2 KB
  - 📄 _monitor_types.py 2.2 KB
  - 📄 _performance_monitor.py 5.2 KB
  - 📄 _stage_tracker.py 6.2 KB
  - 📄 dag.py 9.9 KB
  - 📄 executor.py 12.7 KB
  - 📄 multi_project.py 10.4 KB
  - 📄 pipeline.yaml 2.5 KB
  - 📄 resume.py 6.5 KB
  - 📄 stage_monitor.py 1.2 KB
  - 📄 stages.py 8.1 KB
  - 📄 summary.py 5.1 KB
  - 📄 summary_formatters.py 9.5 KB
  - 📄 summary_helpers.py 4.1 KB
  - 📄 summary_models.py 1021 B
  - 📄 types.py 2.7 KB
- 📁 runtime/
  - 📄 __init__.py 1.1 KB
  - 📄 _directories.py 4.9 KB
  - 📄 _packages.py 3.9 KB
  - 📄 _python_env.py 5.1 KB
  - 📄 checkpoint.py 9.6 KB
  - 📄 env_deps.py 5.6 KB
  - 📄 environment.py 1.3 KB
  - 📄 eta.py 3.3 KB
  - 📄 function_profiler.py 8.5 KB
  - 📄 health_check.py 10.1 KB
  - 📄 retry.py 7.6 KB
- 📁 telemetry/
  - 📄 __init__.py 1.1 KB
  - 📄 AGENTS.md 2.1 KB
  - 📄 collector.py 15.1 KB
  - 📄 config.py 2.3 KB
  - 📄 models.py 4.5 KB
  - 📄 README.md 1.2 KB
  - 📄 SKILL.md 2.0 KB
- 📄 __init__.py 2.0 KB
- 📄 _exceptions_core.py 7.7 KB
- 📄 _exceptions_domains.py 2.8 KB
- 📄 _optional_deps.py 618 B
- 📄 _rate_limiting.py 6.9 KB
- 📄 _validation.py 4.9 KB
- 📄 AGENTS.md 98.4 KB
- 📄 cli.py 1.8 KB
- 📄 cli_handlers.py 8.1 KB
- 📄 cli_parser.py 2.9 KB
- 📄 credentials.py 6.0 KB
- 📄 errors.py 6.5 KB
- 📄 exceptions.py 2.9 KB
- 📄 install_commands.py 1.4 KB
- 📄 menu.py 2.0 KB
- 📄 progress.py 11.8 KB
- 📄 README.md 15.9 KB
- 📄 script_discovery.py 5.6 KB
- 📄 security.py 3.1 KB
- 📄 SKILL.md 5.0 KB
📁 docker/
- 📄 AGENTS.md 400 B
- 📄 docker-compose.yml 1.2 KB
- 📄 Dockerfile 1.5 KB
- 📄 README.md 161 B
- 📄 SKILL.md 1.2 KB
📁 documentation/
- 📄 __init__.py 875 B
- 📄 AGENTS.md 14.4 KB
- 📄 figure_manager.py 9.2 KB
- 📄 generate_glossary_cli.py 2.8 KB
- 📄 glossary_gen.py 4.3 KB
- 📄 image_manager.py 7.7 KB
- 📄 markdown_integration.py 7.6 KB
- 📄 README.md 19.4 KB
- 📄 SKILL.md 2.1 KB
📁 llm/
- 📁 cli/
  - 📄 __init__.py 145 B
  - 📄 AGENTS.md 15.0 KB
  - 📄 main.py 8.4 KB
  - 📄 README.md 7.5 KB
- 📁 core/
  - 📄 __init__.py 736 B
  - 📄 _connection.py 11.5 KB
  - 📄 _prompt_availability.py 754 B
  - 📄 _stream_helpers.py 1.6 KB
  - 📄 _stream_impl.py 11.8 KB
  - 📄 _structured_queries.py 12.2 KB
  - 📄 _text_utils.py 1.1 KB
  - 📄 AGENTS.md 14.9 KB
  - 📄 client.py 14.3 KB
  - 📄 config.py 10.6 KB
  - 📄 context.py 9.8 KB
  - 📄 log_preview.py 434 B
  - 📄 README.md 4.4 KB
  - 📄 response_saver.py 4.8 KB
  - 📄 sanitization.py 6.4 KB
- 📁 prompts/
  - 📁 compositions/
    
    📄 AGENTS.md 17.7 KB
    
    📄 README.md 4.0 KB
    
    📄 retry_prompts.json 1.1 KB
  - 📁 fragments/
    
    📄 AGENTS.md 16.8 KB
    
    📄 content_requirements.json 1.1 KB
    
    📄 format_requirements.json 308 B
    
    📄 README.md 4.2 KB
    
    📄 section_structures.json 4.8 KB
    
    📄 system_prompts.json 1.3 KB
    
    📄 token_budget_awareness.json 457 B
    
    📄 validation_hints.json 403 B
  - 📁 templates/
    
    📄 AGENTS.md 18.5 KB
    
    📄 manuscript_reviews.json 5.7 KB
    
    📄 paper_summarization.json 2.9 KB
    
    📄 README.md 5.2 KB
  - 📄 __init__.py 447 B
  - 📄 _fragment_builders.py 8.7 KB
  - 📄 AGENTS.md 20.8 KB
  - 📄 composer.py 5.3 KB
  - 📄 loader.py 7.0 KB
  - 📄 README.md 4.1 KB
- 📁 review/
  - 📄 __init__.py 1.5 KB
  - 📄 AGENTS.md 20.1 KB
  - 📄 formatting.py 8.0 KB
  - 📄 generation.py 13.8 KB
  - 📄 generator.py 4.9 KB
  - 📄 io.py 1.2 KB
  - 📄 metrics.py 1.9 KB
  - 📄 ollama_setup.py 8.8 KB
  - 📄 pipeline_runner.py 7.3 KB
  - 📄 quality.py 8.8 KB
  - 📄 README.md 3.9 KB
  - 📄 review_analysis.py 4.2 KB
  - 📄 saving.py 9.5 KB
- 📁 templates/
  - 📄 __init__.py 3.2 KB
  - 📄 AGENTS.md 21.2 KB
  - 📄 base.py 692 B
  - 📄 helpers.py 6.0 KB
  - 📄 literature_analysis.py 5.1 KB
  - 📄 manuscript.py 1.7 KB
  - 📄 manuscript_reviews.py 10.2 KB
  - 📄 manuscript_suggestions.py 8.7 KB
  - 📄 manuscript_translation.py 5.7 KB
  - 📄 paper_summarization.py 16.5 KB
  - 📄 README.md 4.7 KB
  - 📄 research.py 2.4 KB
- 📁 utils/
  - 📄 __init__.py 742 B
  - 📄 AGENTS.md 18.1 KB
  - 📄 heartbeat.py 9.2 KB
  - 📄 models.py 14.0 KB
  - 📄 ollama.py 1.6 KB
  - 📄 README.md 4.7 KB
  - 📄 server.py 6.1 KB
- 📁 validation/
  - 📄 __init__.py 1.7 KB
  - 📄 AGENTS.md 24.3 KB
  - 📄 core.py 9.7 KB
  - 📄 detection.py 12.1 KB
  - 📄 format.py 6.2 KB
  - 📄 README.md 6.3 KB
  - 📄 repetition.py 635 B
  - 📄 similarity.py 3.9 KB
  - 📄 structure.py 4.7 KB
- 📄 __init__.py 1.4 KB
- 📄 AGENTS.md 29.2 KB
- 📄 README.md 4.6 KB
- 📄 SKILL.md 4.4 KB
📁 project/
- 📁 manuscript/
  - 📄 98_symbols_glossary.md 189 B
  - 📄 AGENTS.md 1.2 KB
  - 📄 README.md 1.1 KB
- 📄 __init__.py 688 B
- 📄 AGENTS.md 10.6 KB
- 📄 discovery.py 5.8 KB
- 📄 metadata.py 3.3 KB
- 📄 project_info.py 2.6 KB
- 📄 README.md 6.3 KB
- 📄 SKILL.md 2.8 KB
- 📄 validation.py 2.1 KB
📁 publishing/
- 📄 __init__.py 2.2 KB
- 📄 _metadata_extraction.py 4.8 KB
- 📄 _metadata_reporting.py 6.4 KB
- 📄 AGENTS.md 6.0 KB
- 📄 announcement.py 2.1 KB
- 📄 api.py 3.5 KB
- 📄 checklist.py 3.0 KB
- 📄 citations.py 5.0 KB
- 📄 cli.py 9.1 KB
- 📄 metadata.py 866 B
- 📄 models.py 714 B
- 📄 package.py 2.6 KB
- 📄 platforms.py 6.8 KB
- 📄 publish_cli.py 1.8 KB
- 📄 readiness.py 3.3 KB
- 📄 README.md 4.4 KB
- 📄 SKILL.md 3.1 KB
📁 rendering/
- 📄 __init__.py 480 B
- 📄 _pdf_combined_renderer.py 15.5 KB
- 📄 _pdf_figure_paths.py 6.5 KB
- 📄 _pdf_latex_bibliography.py 2.4 KB
- 📄 _pdf_latex_helpers.py 8.4 KB
- 📄 _pdf_latex_pipeline.py 8.7 KB
- 📄 _pdf_latex_validation.py 3.2 KB
- 📄 _pdf_markdown_combine.py 3.5 KB
- 📄 _pdf_math_delimiters.py 5.3 KB
- 📄 _pdf_pandoc_engine.py 9.2 KB
- 📄 _pdf_preflight.py 2.8 KB
- 📄 _pdf_tex_transforms.py 611 B
- 📄 _pipeline_summary.py 9.1 KB
- 📄 AGENTS.md 24.3 KB
- 📄 cli.py 3.5 KB
- 📄 config.py 2.7 KB
- 📄 convert_latex_images.lua 8.8 KB
- 📄 core.py 8.9 KB
- 📄 ide_style.css 1.5 KB
- 📄 latex_discovery.py 3.2 KB
- 📄 latex_package_validator.py 1.3 KB
- 📄 latex_utils.py 6.3 KB
- 📄 latex_validation.py 6.3 KB
- 📄 manuscript_discovery.py 5.8 KB
- 📄 pdf_renderer.py 8.6 KB
- 📄 pipeline.py 13.6 KB
- 📄 poster_renderer.py 1.1 KB
- 📄 README.md 27.3 KB
- 📄 render_all_cli.py 929 B
- 📄 SKILL.md 3.6 KB
- 📄 slides_renderer.py 11.0 KB
- 📄 web_renderer.py 11.3 KB
📁 reporting/
- 📄 __init__.py 3.4 KB
- 📄 _csv_comparative.py 5.7 KB
- 📄 _csv_project_breakdown.py 6.2 KB
- 📄 _csv_tables.py 12.7 KB
- 📄 _dashboard_charts.py 30.4 KB
- 📄 _dashboard_constants.py 260 B
- 📄 _dashboard_csv.py 1.2 KB
- 📄 _dashboard_matplotlib.py 8.7 KB
- 📄 _dashboard_specialized.py 48.1 KB
- 📄 _executive_analysis.py 6.1 KB
- 📄 _executive_collectors.py 11.0 KB
- 📄 _executive_health.py 12.2 KB
- 📄 _executive_models.py 2.7 KB
- 📄 _executive_renderers.py 4.0 KB
- 📄 _executive_report_formats.py 15.5 KB
- 📄 AGENTS.md 32.8 KB
- 📄 coverage_analysis.py 7.7 KB
- 📄 coverage_json_parser.py 2.7 KB
- 📄 coverage_parser.py 11.3 KB
- 📄 coverage_reporter.py 1.0 KB
- 📄 error_aggregator.py 11.4 KB
- 📄 executive_reporter.py 1.9 KB
- 📄 html_templates.py 4.9 KB
- 📄 log_analysis.py 3.4 KB
- 📄 manuscript_overview.py 5.0 KB
- 📄 markdown_formatter.py 6.9 KB
- 📄 multi_project_reporter.py 9.5 KB
- 📄 output_organizer.py 10.1 KB
- 📄 output_statistics.py 8.9 KB
- 📄 page_grid.py 5.2 KB
- 📄 page_rendering.py 7.2 KB
- 📄 pipeline_html.py 5.2 KB
- 📄 pipeline_io.py 8.2 KB
- 📄 pipeline_markdown.py 4.1 KB
- 📄 pipeline_report_model.py 4.2 KB
- 📄 pipeline_test_runner.py 19.1 KB
- 📄 pytest_output_parser.py 5.5 KB
- 📄 README.md 11.4 KB
- 📄 report_builder.py 5.9 KB
- 📄 report_generator.py 4.8 KB
- 📄 result_loaders.py 4.6 KB
- 📄 SKILL.md 3.9 KB
- 📄 suite_runner.py 9.7 KB
📁 scientific/
- 📄 __init__.py 2.0 KB
- 📄 AGENTS.md 7.5 KB
- 📄 benchmarking.py 6.7 KB
- 📄 documentation.py 3.9 KB
- 📄 README.md 3.7 KB
- 📄 SKILL.md 2.8 KB
- 📄 stability.py 3.1 KB
- 📄 templates.py 9.8 KB
- 📄 validation.py 9.9 KB
📁 skills/
- 📄 __init__.py 1.0 KB
- 📄 __main__.py 188 B
- 📄 AGENTS.md 1.9 KB
- 📄 cli.py 3.4 KB
- 📄 discovery.py 7.8 KB
- 📄 README.md 575 B
- 📄 SKILL.md 1.0 KB
📁 steganography/
- 📄 __init__.py 1.3 KB
- 📄 AGENTS.md 1.7 KB
- 📄 barcode_generators.py 3.9 KB
- 📄 barcode_payload.py 4.0 KB
- 📄 barcodes.py 7.5 KB
- 📄 config.py 5.5 KB
- 📄 core.py 16.1 KB
- 📄 encryption.py 5.8 KB
- 📄 hashing.py 2.9 KB
- 📄 metadata.py 6.3 KB
- 📄 overlays.py 10.2 KB
- 📄 README.md 4.0 KB
- 📄 SKILL.md 3.6 KB
📁 validation/
- 📁 cli/
  - 📄 __init__.py 33 B
  - 📄 __main__.py 183 B
  - 📄 main.py 7.0 KB
  - 📄 markdown.py 3.7 KB
  - 📄 pdf.py 5.4 KB
- 📁 content/
  - 📄 __init__.py 688 B
  - 📄 figure_validator.py 3.6 KB
  - 📄 markdown_validator.py 14.2 KB
  - 📄 pdf_validator.py 9.6 KB
- 📁 docs/
  - 📄 __init__.py 882 B
  - 📄 _docs_scan_report.py 4.1 KB
  - 📄 accuracy.py 14.9 KB
  - 📄 completeness.py 7.2 KB
  - 📄 discovery.py 15.8 KB
  - 📄 models.py 2.2 KB
  - 📄 quality.py 6.6 KB
  - 📄 scanner.py 10.9 KB
- 📁 integrity/
  - 📄 __init__.py 1.8 KB
  - 📄 check_links.py 34.2 KB
  - 📄 checks.py 23.9 KB
  - 📄 link_validator.py 17.5 KB
- 📁 output/
  - 📄 __init__.py 552 B
  - 📄 no_mock_enforcer.py 2.1 KB
  - 📄 pipeline.py 14.4 KB
  - 📄 validator.py 17.4 KB
- 📁 repo/
  - 📄 __init__.py 846 B
  - 📄 _repo_ast.py 1.9 KB
  - 📄 _repo_documented_commands.py 2.9 KB
  - 📄 _repo_scan_report.py 2.4 KB
  - 📄 audit_orchestrator.py 15.5 KB
  - 📄 issue_categorizer.py 13.9 KB
  - 📄 known_exceptions.py 8.4 KB
  - 📄 models.py 793 B
  - 📄 scanner.py 17.2 KB
- 📄 __init__.py 3.4 KB
- 📄 AGENTS.md 39.3 KB
- 📄 README.md 18.9 KB
- 📄 SKILL.md 4.3 KB
📄 __init__.py 2.4 KB
📄 AGENTS.md 30.8 KB
📄 PAI.md 2.1 KB
📄 README.md 13.4 KB
📄 SKILL.md 5.8 KB

SKILL.md

---
name: infrastructure-overview
description: Top-level skill for the research template infrastructure layer. Use in Cursor, Claude Code, or similar agents when editing or importing anything under infrastructure/, understanding the two-layer architecture, or wiring build/validation/rendering/publishing. Covers module discovery, import patterns, thin orchestrators, per-subpackage SKILL.md paths, and .cursor/skill_manifest.json (see infrastructure.skills).
---

# Infrastructure Layer

The `infrastructure/` package provides generic, reusable functionality for research projects. All business logic resides here (Layer 1) or in project-specific `src/` (Layer 2). Scripts are thin orchestrators that coordinate these modules.

## Finding skills (Cursor and other agents)

- **Hub:** This file lists every subpackage skill and a module map.
- **Manifest:** `.cursor/skill_manifest.json` lists every skill (`name`, `description`, `path`); regenerate with `uv run python -m infrastructure.skills write`.
- **Search:** `infrastructure/**/SKILL.md` (15 files: hub `infrastructure/SKILL.md` + 13 top-level subpackage skills + `infrastructure/core/telemetry/SKILL.md`).
- **In Cursor:** `@infrastructure/SKILL.md` or `@infrastructure/<module>/SKILL.md` to load context; pair with the matching `AGENTS.md` for API tables.
- **Frontmatter:** Each `SKILL.md` has YAML `name` and `description` for routing (see also the table in `infrastructure/README.md`).

## Module Map

| Module | Purpose | Key Imports |
|--------|---------|-------------|
| `config/` | Repo defaults (`.env.template`, `secure_config.yaml`) | (YAML/dotenv; use `core.config_loader`) |
| `core/` | Logging, config, exceptions, pipeline, progress, retry, security | `get_logger`, `load_config`, `PipelineExecutor` |
| `docker/` | `Dockerfile`, `docker-compose.yml` for container runs | (CLI / `docs/CLOUD_DEPLOY.md`) |
| `validation/` | PDF/Markdown/output validation, link checking, audits | `validate_pdf_rendering`, `validate_markdown`, `verify_output_integrity` |
| `rendering/` | Multi-format output (PDF, HTML, slides) | `RenderManager`, `RenderingConfig` |
| `documentation/` | Figure/image management, markdown integration, glossary | `FigureManager`, `ImageManager`, `MarkdownIntegration` |
| `llm/` | Local LLM integration via Ollama | `LLMClient`, `LLMConfig`, `OutputValidator` |
| `publishing/` | Academic publishing (DOI, citations, Zenodo, arXiv) | `publish_to_zenodo`, `generate_citation_bibtex` |
| `reporting/` | Pipeline reports, error aggregation, dashboards | `generate_pipeline_report`, `get_error_aggregator` |
| `scientific/` | Benchmarking, numerical stability, scientific templates | `benchmark_function`, `check_numerical_stability` |
| `project/` | Multi-project discovery and validation | `discover_projects`, `validate_project_structure` |
| `skills/` | Enumerate and parse `SKILL.md`; maintain Cursor manifest | `discover_skills`, `write_skill_manifest` |
| `steganography/` | Cryptographic PDF watermarking and verification | `SteganographyProcessor`, `StegoParams` |
| `core/telemetry/` | Unified pipeline telemetry (stage resources + diagnostics, JSON/text reports) | `TelemetryCollector`, `TelemetryConfig` |

## Import Patterns

```python
# Convenience imports (exported on infrastructure package root)
from infrastructure import get_logger, load_config, TemplateError

# Direct submodule imports (recommended for clarity)
from infrastructure.core import CheckpointManager
from infrastructure.core.pipeline import PipelineExecutor
from infrastructure.rendering import RenderManager
from infrastructure.llm.core.client import LLMClient
from infrastructure.validation import validate_markdown, validate_pdf_rendering
from infrastructure.skills import discover_skills

# In project scripts (thin orchestrator pattern)
from infrastructure.core.logging.utils import get_logger
from infrastructure.validation import validate_pdf_rendering
```

## Architecture Principles

1. **Thin Orchestrator Pattern** — Scripts import from infrastructure; never implement business logic
2. **No Mocks Policy** — All tests use real data and computations
3. **Test Coverage** — Infrastructure requires 60%+ coverage
4. **Exception Hierarchy** — All errors extend `TemplateError` from `infrastructure.core.exceptions`
5. **Unified Logging** — Always use `get_logger(__name__)` for consistent output

## Common Workflows

### Running Infrastructure Tests

```bash
uv run pytest tests/infra_tests/ --cov=infrastructure --cov-fail-under=60
```

### Using the Pipeline

```bash
python3 scripts/execute_pipeline.py --project code_project --core-only
```

### Validating Outputs

```bash
python3 -m infrastructure.validation.cli.main markdown projects/code_project/manuscript/
python3 -m infrastructure.validation.cli.main pdf output/code_project/pdf/
```

## Submodule Skills

Each subpackage has a `SKILL.md` (YAML frontmatter + body) for agent discovery—search the repo for `infrastructure/**/SKILL.md` or open paths below:

- `infrastructure/config/SKILL.md` — Repo configuration templates and secure defaults
- `infrastructure/core/SKILL.md` — Foundation utilities
- `infrastructure/docker/SKILL.md` — Container build and compose
- `infrastructure/documentation/SKILL.md` — Figure and doc management
- `infrastructure/llm/SKILL.md` — LLM integration
- `infrastructure/project/SKILL.md` — Project discovery and validation
- `infrastructure/publishing/SKILL.md` — Academic publishing
- `infrastructure/rendering/SKILL.md` — Output generation
- `infrastructure/reporting/SKILL.md` — Pipeline reporting
- `infrastructure/scientific/SKILL.md` — Scientific computing
- `infrastructure/skills/SKILL.md` — Programmatic skill discovery and manifest I/O
- `infrastructure/steganography/SKILL.md` — Secure PDF post-processing
- `infrastructure/core/telemetry/SKILL.md` — Unified pipeline telemetry (nested under `core/`)
- `infrastructure/validation/SKILL.md` — Quality assurance

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

infrastructure-overview

Directory Structure

SKILL.md

Report

Notice