TSYS-AIOS-GIS/AGENTS.md

AIOS-Public Agents

This document tracks the various agents, tools, and systems used in the AIOS-Public project.

Documentation Tools

RCEO-AIOS-Public-Tools-DocMaker Container Family

Purpose: Documentation generation containers with multiple document conversion tools, organized in a layered architecture.

Container/Stack Names:

• RCEO-AIOS-Public-Tools-DocMaker-Base: Base documentation environment
• RCEO-AIOS-Public-Tools-DocMaker-Light: Lightweight documentation tools (fast-starting)
• RCEO-AIOS-Public-Tools-DocMaker-Full: Full documentation with LaTeX-full
• RCEO-AIOS-Public-Tools-DocMaker-Computational: All documentation tools plus computational tools (R, Python, Jupyter, Octave)

Technology Stack:

• Base: Debian Bookworm slim
• Bash
• Python 3
• Node.js
• Rust (with Cargo)
• Pandoc
• LaTeX (varies by container: light packages in base/full in full)
• mdBook (installed via Cargo)
• mdbook-pdf (installed via Cargo)
• Typst
• Marp CLI
• Wandmalfarbe pandoc-latex-template: Beautiful Eisvogel LaTeX template for professional PDF generation
• Spell/Grammar checking:
  • Hunspell (with en-US dictionary)
  • Aspell (with en dictionary)
  • Vale (style and grammar linter)
• Reading time estimation: mdstat
• Additional text processing tools
• Computational tools in Computational container:
  • R programming language
  • Python scientific stack (pandas, numpy, matplotlib, scipy)
  • Jupyter notebooks
  • GNU Octave
  • bc (command-line calculator)

Usage:

• Use Light container for quick documentation tasks (COO mode)
• Use Full container for complex document generation (COO mode)
• Use Computational container for data analysis and R&D work (CTO mode)
• Base container serves as foundation for other containers

Docker Configuration:

• Located in the Docker/ directory
• Each container has its own subdirectory with Dockerfile and docker-compose.yml
• Maps the project root directory to /workspace inside the container
• Uses UID/GID mapping for proper file permissions across environments
• Can be run with docker-compose up from each container's directory

Container Usage Map:

• Light container: COO mode, quick documentation tasks (CV, proposals, governance docs)
• Full container: COO mode, complex document generation with LaTeX-full
• Computational container: CTO mode, data analysis and R&D work (R, Python, Jupyter)

Commands to run:

Using the wrapper script (recommended - handles UID/GID automatically):

# Build and start the lightweight container (COO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
./docker-compose-wrapper.sh up --build

# Build and start the full documentation container (COO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Full
./docker-compose-wrapper.sh up --build

# Build and start the computational container (CTO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational
./docker-compose-wrapper.sh up --build

# Run commands in containers with automatic user mapping:
./docker-compose-wrapper.sh run docmaker-light [command]        # Light container
./docker-compose-wrapper.sh run docmaker-full [command]         # Full container  
./docker-compose-wrapper.sh run docmaker-computational [command] # Computational container

Using docker-compose directly (requires manual environment variables):

# Set environment variables for proper file permissions
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)

# Build and start containers
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
docker-compose up --build

# Example usage of documentation tools with wrapper script:

# Spell checking with hunspell
./docker-compose-wrapper.sh run docmaker-full hunspell -d en_US document.md

# Create timeline with Markwhen (not currently available)
# This will be enabled when Markwhen installation issue is resolved
# ./docker-compose-wrapper.sh run docmaker-full markwhen input.mw --output output.html

# Grammar/style checking with Vale
./docker-compose-wrapper.sh run docmaker-full vale document.md

# Reading time estimation
./docker-compose-wrapper.sh run docmaker-full python3 -m mdstat document.md

# Run R analysis (in computational container)
./docker-compose-wrapper.sh run docmaker-computational Rscript analysis.R

# Run Python analysis (in computational container)
./docker-compose-wrapper.sh run docmaker-computational python analysis.py

# Check spelling with aspell
./docker-compose-wrapper.sh run docmaker-full aspell -c document.md

User Management: All containers run as non-root user ReachableCEO-Tools with UID/GID mapping from the host environment to ensure proper file permissions.