Skip to content

modules-guide.md

Latest commit

 

History

History
150 lines (104 loc) · 5.47 KB

modules-guide.md

File metadata and controls

150 lines (104 loc) · 5.47 KB

🔬 Modules Guide

Guide to Layer-1 infrastructure modules

Quick Reference: API Reference | Architecture | Infrastructure Docs

Counting: The overview table lists 14 named areas (including Skills and Telemetry as first-class). Other docs may say 13 subpackages when telemetry is treated as part of core/—same tree, different grouping. See infrastructure/AGENTS.md for the authoritative layout.

Module Overview

Module Purpose Key Features Guide
⚙️ Core Shared utilities Logging, config, exceptions Details
📄 Documentation Doc generation Figure management, API glossary Details
✅ Validation Output verification File integrity, cross-reference validation Details
📚 Publishing Academic workflows DOI validation, citation generation Details
🔬 Scientific Research best practices Numerical stability, benchmarking Details
🤖 LLM Local LLM & literature Ollama integration, templates, literature search Details
🎨 Rendering Multi-format output PDF, slides, web, poster Details
📊 Reporting Pipeline reporting Reports, error aggregation Details
🔍 Project Project discovery Multi-project orchestration Details
🔒 Steganography Provenance & watermarking Alpha-channel overlays, QR barcodes, PDF metadata Details
⚙️ Config Configuration schemas Secure config, environment templates —
🐳 Docker Containerization Dockerfile, docker-compose —
🔍 Skills SKILL.md discovery Cursor manifest, agent routing (discover_skills) Details
📡 Telemetry Unified pipeline telemetry Stage resource metrics, diagnostic aggregation, JSON/text reports —

All modules follow the thin orchestrator pattern with test coverage.

Quick Start

Integrity Checking

from pathlib import Path

from infrastructure.validation.integrity import verify_output_integrity

report = verify_output_integrity(Path("output"))
if report.overall_integrity:
    print("All checks passed")

Documentation Generation

from infrastructure.documentation.glossary_gen import build_api_index, generate_markdown_table

entries = build_api_index("projects/code_project/src/")
table_md = generate_markdown_table(entries)
print(f"API entries: {len(entries)}")

CLI: uv run python -m infrastructure.documentation.generate_glossary_cli projects/code_project/src/ projects/code_project/manuscript/98_symbols_glossary.md (second path is the markdown file to inject into; created if missing).

LLM Assistance

from infrastructure.llm import LLMClient

client = LLMClient()
response = client.query("Summarize the key findings")

PDF Rendering

from infrastructure.rendering import RenderManager

manager = RenderManager()
pdf_path = manager.render_pdf(Path("manuscript/main.tex"))

Integration with Build Pipeline

# Validate outputs for a project (after render / copy)
uv run python scripts/04_validate_output.py --project code_project

# Manual integrity check on final deliverables tree
uv run python -m infrastructure.validation.cli integrity output/code_project/

Integration Patterns

Using Multiple Modules Together

from pathlib import Path

from infrastructure.publishing import extract_publication_metadata
from infrastructure.validation.integrity import verify_output_integrity


def comprehensive_validation(output_dir: Path, manuscript_files: list[Path]) -> dict:
    """Run validation suite."""
    return {
        "integrity": verify_output_integrity(output_dir),
        "publishing": extract_publication_metadata(manuscript_files),
    }

Module Dependencies

Module Dependencies Test Coverage
Core pathlib, logging 83%
Documentation pathlib 80%
Validation hashlib, pathlib 81%
Publishing requests, bibtexparser 86%
Scientific numpy, time, psutil 88%
LLM requests, ollama 91%
Rendering pandoc, xelatex 91%
Reporting json, pathlib 75%
Project pathlib 85%
Steganography PIL/Pillow, qrcode, pypdf 80%
Skills pathlib 85%
Telemetry psutil, json, pathlib 84%

All modules work independently or together with minimal coupling.

Best Practices

  1. Integrate Early - Include modules in your workflow from the beginning
  2. Automate Validation - Set up automated checks in your build pipeline
  3. Monitor Performance - Track algorithm performance over time

See Also

The modules provide enterprise-grade capabilities while maintaining simplicity. Each can be used independently or integrated into validation workflows.