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
```bash
# 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
```bash
# Run the TUI application
python -m heurams.interface

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

### Testing
```bash
# 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`)
```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*