HeurAMS/AGENTS.md

AGENTS.md — HeurAMS Codebase Guide

Project Overview

HeurAMS (潜进, v0.5.0 "fulcrum/支点") is a Heuristic Auxiliary Memory Scheduler — an open spaced-repetition scheduling platform. Licensed AGPL-3.0. Written in Python 3.10+.

The project uses a physics-inspired data model: nucleon (memory content) + electron (algorithm state) + orbital (review strategy) = atom (runtime memory unit).

Essential Commands

# Setup (uv recommended)
uv sync                                    # Install all deps & dev env
python3 -m pip install -e .                # Native pip alternative

# Run
uv run heurams                             # Verify CLI (just prints help)
uv run tui                                 # Launch Textual TUI
python3 -m heurams.interface               # Native pip alternative for TUI

# Formatting
black . --workers=1                        # Python (single-thread flag needed)
autoflake --in-place --remove-all-unused-imports --recursive ./src/ --exclude __init__.py
mdformat --number .                        # Markdown

# Tests (pytest, 128 tests across 9 test files as of v0.5.0)

```bash
uv run pytest                          # Run all tests
uv run pytest -v --tb=short            # Verbose, short tracebacks
uv run pytest tests/test_sm2.py        # Single test file
uv run pytest -k "test_interval"       # Filter by name
uv run pytest --cov=heurams --cov-report=term  # Coverage report (via pytest-cov)

Test structure:

• tests/conftest.py — Shared fixtures: timer_context (deterministic time overrides), sample_algodata_sm2, sample_algodata_nsp0
• tests/test_textproc.py — truncate, domize, undomize
• tests/test_hasher.py — get_md5, hash
• tests/test_epath.py — epath nested dict/list read/write access
• tests/test_lict.py — Lict collection (list+dict hybrid, dirty-sync)
• tests/test_evalizor.py — Evalizer eval-based template system
• tests/test_base_algorithm.py — BaseAlgorithm defaults, methods, integrity
• tests/test_sm2.py — SM-2: defaults, revisor (efactor/rept/interval logic), is_due, dates
• tests/test_nsp0.py — NSP-0: defaults, revisor (important/interval), is_due
• tests/test_electron.py — Electron: init, activation, revisor delegation, dict/list access, from_data

## Code Organization

src/heurams/ ├── init.py, main.py, context.py # Entry point, global ContextVar config ├── interface/ — Textual TUI (screens/, widgets/, css/) ├── kernel/ — Core logic │ ├── algorithms/ — SM-2, NSP-0, SM-15M, FSRS (stub) │ ├── particles/ — Atom, Electron, Nucleon, Orbital data models │ ├── puzzles/ — MCQ, Cloze, Recognition puzzle generators │ ├── reactor/ — Router → Procession → Expander state machines │ ├── repolib/ — Repo class (loads/saves repos from TOML/JSON dirs) │ └── auxiliary/ — Evalizer (eval-based template), Lict (dict+list hybrid) ├── services/ — Config, logger, timer, audio, TTS, favorites, attic, hasher, epath ├── providers/ — Pluggable drivers (TTS: edgetts/base; Audio: playsound/termux) ├── unifront/ — Unified frontend session (mostly stub) └── tools/ — csv2payload, zmqclient

Outside `src/`:
- `data/config/` — Hierarchical TOML config (see below)
- `data/repo/` — Memory repos (one TOML dir per repo set)
- `tests/` — Empty, no test infrastructure yet

## Architecture & Data Flow

### Layers (bottom-up)

1. **Kernel** — Algorithms, data models, puzzle generators, scheduling reactor
2. **Services** — Config, logging, timer, TTS, audio, favorites, persistence
3. **Providers** — Swappable backends (EdgeTTS, playsound, OpenAI LLM stub)
4. **Interface** — Textual TUI (Textual 8.x, CSS-based styling in `.tcss` files)
5. **Unifront** — Abstract frontend session (unimplemented)

### Review Flow

Router (global state machine) └─ contains → Procession(s) — one per phase (quick_review → recognition → final_review) └─ contains → Expander (per atom) — expands puzzle schedule into individual puzzle widgets └─ wraps → Puzzle widget (MCQ, Cloze, Recognition)

States managed via the `transitions` library (states defined in `states.py`).

## Key Patterns & Conventions

### Logging

Every module creates its own logger with `get_logger(__name__)`. Log files rotate at 10MB, up to 5 backups. Logs append to `heurams.log` in the working directory.

### Config System (`ConfigDict`)

Singleton per path. Lazy-loads TOML files on access. Directory convention:
- `_.toml` files = default values for that directory level (merged into parent)
- Files named `*.toml` = lazy-loaded on key access
- Directories = recursive sub-configs
- Access config via `config_var.get()["section"]["key"]`

### Context Management

```python
from heurams.context import config_var, ConfigContext, rootdir, workdir
config_var.get()                            # Current config (thread-safe)
with ConfigContext(test_config_provider):    # Scoped config override
    ...

State Machines (transitions library)

Three finite state machines with explicit state enums in states.py:

• RouterState: unsure → quick_review → recognition → final_review → finished
• ProcessionState: active → finished
• ExpanderState: exammode → retronly

Physics Metaphor Data Model

• Nucleon: Read-only content container. Wraps payload + typedef via Evalizer (eval-based template system). Created from (ident, (payload, common)) tuples.
• Electron: Algorithm-specific memory state. Wraps algodata dict with BaseAlgorithm interface. Created from (ident, algodata, algo_name) tuples.
• Orbital: Review strategy dict defining puzzle probabilities per phase.
• Atom: Runtime assembly of nucleon + electron + orbital + runtime flags. The primary object the UI works with.

Lict Collection

A MutableSequence subclass that maintains both list-like and dict-like access simultaneously. Used extensively for repo data. Appends are (key, value) tuples — keys must be unique strings. Supports lazy sync between internal list and dict representations.

Evalizer Template System

Recursively traverses data structures, evaluating strings prefixed with eval: via Python's eval() in a controlled namespace. Used in nucleon initialization. TODO/warning: noted for being risk-prone.

Repo (Memory Repository)

A directory of TOML/JSON files:

• manifest.toml — title, author, package name, description
• typedef.toml — Common metadata, puzzle definitions, annotations
• payload.toml — Individual memory items (keyed by ident)
• algodata.json — Algorithm state (keyed by ident, persistent)
• schedule.toml — Orbital/review schedule definition

Repos are loaded from data/repo/ via Repo.from_repodir(). Created from directory structure, no database required.

Algorithms

Name	File	Status
SM-2	sm2.py	Working — Classic SuperMemo 1987
NSP-0	nsp0.py	Working — Non-spaced filtering scheduler
SM-15M	sm15m.py + sm15m_calc.py	Working — Ported from CoffeeScript SM-15
FSRS	fsrs.py	Stub only — "尚未实现"
Base	base.py	Abstract base with defaults

All algorithms are class-method-based (@classmethod), registered in algorithms/__init__.py dict.

Services

• config.py — ConfigDict(UserDict) singleton, TOML lazy loader
• logger.py — get_logger(name) → hierarchical loggers under heurams.*
• timer.py — get_daystamp() / get_timestamp() with configurable overrides
• epath.py — Dot-notation access to nested dicts (epath(dct, "a.b.c"))
• attic.py — Struct-like pickle persistence (per-ident, supports <DAYSTAMP>/<TIMESTAMP> placeholders)
• hasher.py — MD5 hashing
• textproc.py — truncate(), domize(), undomize()
• audio_service.py — Routes through configured audio provider
• tts_service.py — Routes through configured TTS provider
• favorite_service.py — Favorite manager with JSON5 persistence (singleton)
• exceptions.py — WTFException
• version.py — ver = "0.5.0", stage = "prototype", codename = "fulcrum"

Important Gotchas

1. FSRS is not implemented — fsrs.py is just a logger.info("尚未实现") stub.
2. No tests — The tests/ directory is completely empty. There is no pytest config or test runner. Any code added should establish test infrastructure.
3. black --workers=1 — The multi-threaded worker flag has compatibility issues on some platforms.
4. autoflake must exclude __init__.py — Unused-import removal breaks __init__.py re-exports.
5. ConfigDict is a singleton per path — Creating ConfigDict with the same path returns the same instance. Don't create instances with default dict argument (raises WTFException).
6. eval() in Evalizer — The template system uses eval() under the hood. Marked as high-risk in comments. Any changes should prioritize replacement.
7. Don't run interface/__main__.py directly — It will misconfigure Python context. Always run via python -m heurams.interface or uv run tui.
8. No fast-forward merges — Project policy requires non-fast-forward merging only (git config merge.ff false).
9. id() is avoided for repo lookup — The dashboard explicitly notes id() can be reused, so it uses repolink dict keyed by package name string.
10. Termux support — There's a separate audio provider for Termux; the project maintains pip-compatibility specifically for Termux (where uv doesn't work well).
11. ZMQ debug server — Optional debug feature that opens a REP socket for remote code execution via pickle. Disabled by default.
12. Commit messages — Follow Conventional Commits spec. Written in Chinese or English.

Provider System

Providers are swappable implementations registered in __init__.py dicts:

• TTS: edgetts (Microsoft Edge TTS), basetts (stub)
• Audio: playsound (cross-platform), termux (Android Termux)
• LLM: openai (OpenAI-compatible API), no LLM provider is fully implemented yet

Selection is via data/config/services/*.toml (e.g., provider = "edgetts").

Dependencies (pyproject.toml)

Core: psutil, tabulate, textual>=8.2.3, toml, transitions, zmq Optional (in requirements.txt, commented out in pyproject.toml): edge-tts, jieba, openai, playsound