HeurAMS/AGENTS.md

Agent Guide for HeurAMS

This document contains essential information for AI agents working in the HeurAMS (Heuristic Assisted Memory Scheduler) codebase.

Project Overview

HeurAMS is a Python-based memory scheduling application with a TUI interface built using Textual. It implements a spaced repetition system with configurable algorithms, puzzles, and data persistence.

Key Technologies:

• Python 3 (setuptools)
• Textual (TUI framework)
• TOML for configuration
• JSON and TOML for data persistence
• Bidirectional mapping via bidict

Project Structure:

src/heurams/
├── __init__.py              # Package entry point
├── context.py               # Global context, paths, config context manager
├── services/                # Core services (config, logger, timer, audio, TTS)
├── kernel/                  # Core business logic
│   ├── algorithms/          # Spaced repetition algorithms (FSRS, SM2)
│   ├── particles/           # Data models (Atom, Electron, Nucleon, Orbital)
│   ├── puzzles/             # Puzzle types (MCQ, cloze, recognition)
│   └── reactor/             # Scheduling and processing logic
├── providers/               # External service providers
│   ├── audio/               # Audio playback implementations
│   ├── tts/                 # Text-to-speech implementations
│   └── llm/                 # LLM integrations
├── interface/               # Textual TUI interface
│   ├── widgets/             # UI widget components
│   ├── screens/             # Application screens
│   └── __main__.py          # Application entry point
└── default/                 # Default configuration and data templates

Essential Commands

Development Setup

# Install dependencies
pip install -r requirements.txt

# Install package in development mode
pip install -e .

# Build package (produces dist/)
python -m build

Running the Application

# Run the TUI application
python -m heurams.interface

# Alternative: if installed via pip
heurams  # (if console scripts are configured)

Testing

# Run tests (if test suite exists)
pytest

# Run with coverage
pytest --cov=heurams

Note: The test directory appears to have been removed. Previous test files were located in tests/ (deleted per git status). If adding new tests, follow pytest conventions and place them in a tests/ directory at the project root.

Linting and Formatting

No specific linting or formatting configuration observed. Use standard Python conventions.

Code Organization

Key Modules

1. context.py (src/heurams/context.py):

   • Defines rootdir, workdir, and config_var (ContextVar) for configuration
   • Provides ConfigContext context manager for temporary configuration switching
   • Configuration is loaded from config/config.toml relative to workdir, falling back to default config

2. Services (src/heurams/services/):

   • config.py: ConfigFile class for TOML configuration management
   • logger.py: Comprehensive logging setup with rotation and namespacing
   • timer.py: Time services with configurable overrides for testing
   • audio_service.py: Audio playback abstraction
   • tts_service.py: Text-to-speech service abstraction

3. Kernel (src/heurams/kernel/):

   • Particles: Data models representing memory items:
     • Atom: Composite of Nucleon (content), Electron (algorithm data), Orbital (strategy)
     • Nucleon: Content data (TOML)
     • Electron: Algorithm data (JSON)
     • Orbital: Strategy configuration (TOML)
   • Algorithms: Spaced repetition algorithm implementations (FSRS, SM2)
   • Puzzles: Interactive puzzle types for review sessions
   • Reactor: Scheduling and state management

4. Providers (src/heurams/providers/):

   • Abstract base classes and implementations for external services
   • Audio playback (playsound_audio.py, termux_audio.py)
   • TTS (edge_tts.py)
   • LLM (openai.py)

5. Interface (src/heurams/interface/):

   • Textual-based TUI with multiple screens
   • Widgets for different puzzle types
   • CSS styling in css/ directory

Naming Conventions and Style Patterns

Code Style

• Indentation: 4 spaces (no tabs observed)
• Line length: No explicit limit, typical Python conventions
• Imports: Standard library first, then third-party, then local modules
• Type hints: Used extensively throughout codebase
• Docstrings: Chinese and English mixed, some functions have descriptive docstrings

Naming

• Classes: CamelCase (e.g., ConfigFile, BaseAlgorithm, HeurAMSApp)
• Functions/Methods: snake_case (e.g., get_daystamp, setup_logging)
• Variables: snake_case (e.g., config_var, atom_registry)
• Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_LOG_LEVEL)

Patterns Observed

• Use typing module for type annotations (TypedDict, Union, Optional, etc.)
• Context variables via contextvars for configuration management
• Registry pattern using bidict for global object tracking (e.g., atom_registry)
• Service abstraction with provider pattern (audio, TTS, LLM)
• Configuration-driven behavior with fallback defaults

Testing Approach

Current State: Test directory removed, but .pytest_cache indicates pytest was used.

If adding tests:

• Place tests in tests/ directory at project root
• Follow pytest conventions
• Use pytest.fixture for shared test resources
• Mock external dependencies (audio, TTS, LLM providers)
• Test configuration overrides via ConfigContext

Testable Components:

• Algorithm implementations (FSRS, SM2)
• Puzzle logic validation
• Configuration loading and saving
• Atom persistence and evaluation

Important Gotchas

Configuration Loading

• Configuration is loaded from config/config.toml relative to the current working directory
• If not found, falls back to src/heurams/default/config/config.toml
• The config_var ContextVar is used throughout the codebase to access configuration
• Use ConfigContext for temporary configuration changes in tests or specific operations

Path Handling

• rootdir: Package directory (src/heurams/)
• workdir: Current working directory (set at runtime)
• Data paths (nucleon_dir, electron_dir, etc.) are relative to workdir by default
• The application may change working directory in development mode (see __main__.py lines 61-63)

Eval Security

• The Atom.do_eval() method evaluates strings prefixed with "eval:" in data structures
• This is a security consideration - user-provided content could execute arbitrary code
• Evaluation is limited to a sandboxed environment but caution is advised

Logging

• Logging is configured automatically via logger.py setup
• Logs go to /tmp/heurams.log by default (configurable)
• Logger names are prefixed with "heurams." automatically
• Third-party library log levels are set to WARNING to reduce noise

Time Overrides

• daystamp_override and timestamp_override in config allow time manipulation for testing
• When set to values other than -1, they override get_daystamp() and get_timestamp()
• Useful for reproducible testing of scheduling algorithms

Configuration

Default Configuration (src/heurams/default/config/config.toml)

# Debug settings
persist_to_file = 1
daystamp_override = -1
timestamp_override = -1
quick_pass = 0

# Default number of new memory items
tasked_number = 8

# Timezone offset for daystamp calculation (seconds)
timezone_offset = +28800  # China Standard Time (UTC+8)

# Puzzle defaults
[puzzles.mcq]
max_riddles_num = 2

[puzzles.cloze]
min_denominator = 3

# Data paths (relative to workdir or absolute)
[paths]
nucleon_dir = "./data/nucleon"
electron_dir = "./data/electron"
orbital_dir = "./data/orbital"
cache_dir = "./data/cache"

User Configuration

Place config.toml in config/ directory relative to where the application is run. The structure should match the default configuration.

Running the Application

Development Mode

When running from within the project directory, the application may change working directory to ensure data paths resolve correctly (see __main__.py).

Production/Installed Mode

When installed via pip, the working directory is wherever the command is executed. Ensure a config/ directory with config.toml exists, or rely on defaults.

Entry Points

• Primary: python -m heurams.interface
• The __main__.py performs environment checks, ensures directories exist, then launches the Textual app

Development Setup

Dependencies

• Listed in requirements.txt: bidict, playsound, textual, toml
• Additional dependencies may be needed for specific providers (e.g., edge-tts)

Adding New Features

New Puzzle Type:

1. Add class in src/heurams/kernel/puzzles/
2. Inherit from BasePuzzle
3. Add corresponding widget in src/heurams/interface/widgets/
4. Integrate into appropriate screens

New Algorithm:

1. Add class in src/heurams/kernel/algorithms/
2. Inherit from BaseAlgorithm
3. Implement revisor(), is_due(), rate(), nextdate() methods
4. Update algorithm selection logic if needed

New Provider:

1. Add implementation in relevant provider directory (audio/, tts/, llm/)
2. Inherit from base class in same directory
3. Register in provider registry (see __init__.py in provider directories)

Data Models

• Nucleon: Content data (TOML), contains metadata and puzzle content
• Electron: Algorithm state (JSON), tracks review history and scheduling
• Orbital: Strategy configuration (TOML), defines review parameters
• Atom: Composite of all three, managed via atom_registry

Persistence

• Data is saved to paths specified in configuration
• Formats: TOML for Nucleon/Orbital, JSON for Electron
• Automatic directory creation on save
• The Atom.persist() method handles saving individual components

---

Last Updated: Based on codebase analysis on 2025-12-15