update docs

.gitignore

@@ -183,6 +183,3 @@ app.log
 
 # data
 *.png
-
-# Claude Code project-specific instructions
-CLAUDE.md

CLAUDE.md

@@ -0,0 +1,183 @@
+# Claude Development Guidelines
+
+This file contains project-specific guidelines for Claude Code when working on this project.
+
+## Code Style
+
+### Comments
+- Use docstrings for all functions, classes, and modules
+- Follow Google-style docstrings
+- Add inline comments for complex logic
+- Avoid obvious comments
+- Comments should start with lowercase letters
+
+### Type Hints
+- Use type hints for all function parameters and return values
+- Import types from typing module when needed
+- use X | Y, list[X], dict[K, V] syntax; avoid typing imports for these
+
+### Imports
+- Group imports: standard library, third-party, local
+- Use absolute imports (e.g., `from <package_name>.<modlue_name> import func` not `from .<module_name> import func`)
+- Sort imports alphabetically within groups
+- Avoid wildcard imports
+
+### Code Formatting
+- Line length: 99 characters
+- Use 4 spaces for indentation
+- Follow PEP 8 conventions
+- Use meaningful variable names
+- Use idx for index
+- Use adjectives after nouns, such as idx_train and idx_test rather than train_idx and test_idx
+- Include newline at the end of every .py file
+- Do not allow trailing whitespace
+- Do not include whitespace for blank lines
+- Use single quotes for strings
+- Add a comma to the end of multi-line function arguments:
+```python
+foo(
+    param1,
+    param2,
+)
+```
+not
+```python
+foo(
+    param1,
+    param2
+)
+```
+
+### Misc
+- Use `pathlib.Path` instead of `os` for path handling
+- Use f-strings for all string interpolation, including `logger` calls and `print` statements — never `%s` formatting or `.format()`
+
+## Testing
+
+### Unit Tests
+- Use pytest framework
+- Test directory structure must mirror the source package structure exactly:
+  strip the `<package_name>/` prefix and prepend `tests/` — the rest of the path is identical.
+  `<package_name>/a/b/c.py` → `tests/a/b/test_c.py`, at every level of nesting without exception.
+  - Each subdirectory under `tests/` must have an `__init__.py`
+- Create test classes for each function
+- Use fixtures for common test data; place fixtures in a `conftest.py` in the same directory as the tests that use them
+- Test assets (e.g. sample images) live in an `assets/` subdirectory alongside the tests that use them
+- Aim for high test coverage
+- Test both success and failure cases
+
+### Test Structure
+```python
+class Test<function_name>:
+    """Test the function <function_name>."""
+
+    def test_<function_name>_<scenario>(self):
+        # Arrange
+        # Act
+        # Assert
+```
+
+### Mocking
+- Use unittest.mock for external dependencies
+- Mock at the boundary of your system
+- Use dependency injection when possible
+
+## Documentation
+
+### Docstrings
+```python
+def function_name(param1: Type1, param2: Type2) -> ReturnType:
+    """Brief description of function.
+
+    Longer description if needed.
+
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+
+    Returns:
+        Description of return value
+
+    Raises:
+        ExceptionType: Description of when this exception is raised
+    """
+```
+If there are too many params for a single line, put one param per line, indented four spaces:
+```python
+def function_name(
+    param1: Type1,
+    param2: Type2,
+    param3: Type3,
+    param4: Type4,
+) -> ReturnType:
+```
+
+### Module Documentation
+- Every module should have a module-level docstring
+- Describe the purpose and main functionality
+
+## Error Handling
+
+### Exceptions
+- Use specific exception types
+- Provide meaningful error messages
+- Log errors appropriately
+- Use try/except blocks judiciously
+
+### Logging
+- Use Python's logging module
+- Include appropriate log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- Log important events and errors
+- Include context in log messages
+
+## Project Structure
+
+### Package Organization
+- Keep modules focused and cohesive
+- Use clear, descriptive module names
+- Group related functionality together
+- Avoid circular imports
+
+### File Naming
+- Use snake_case for Python files
+- Use descriptive names
+- Group related files in subdirectories
+
+## CLI Guidelines
+
+### Command Structure
+- Use subcommands for different operations
+- Provide clear help messages
+- Validate input parameters
+- Handle errors gracefully
+
+### Configuration
+- Use sensible defaults
+- Validate configuration before execution
+
+## Dependencies
+
+### Adding Dependencies
+- Only add dependencies that are truly needed
+- Prefer well-maintained packages
+- Do not pin versions
+- Update pyproject.toml and document changes
+
+### Version Management
+- Use semantic versioning
+- Update version in pyproject.toml
+- Tag releases appropriately
+
+## Git Workflow
+
+### Commits
+- Write clear, descriptive commit messages
+- Make atomic commits
+- Include tests with feature commits
+- Run tests before committing
+
+### Branches
+- Use feature branches for development
+- Keep branches focused and short-lived
+- Merge with pull requests
+- Delete merged branches

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+m.whiteway@columbia.edu.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.