diff --git a/.gitignore b/.gitignore index a7526e9..29b6aeb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ # Project specific additions +AGENTS.md .devflag .vscode/ .directory diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 46cc8aa..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,238 +0,0 @@ -# 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) -``` - -### 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 - -## 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* \ No newline at end of file