36
CLAUDE.md
36
CLAUDE.md
@@ -30,9 +30,28 @@ The app will be available at http://127.0.0.1:8050
|
||||
**Run tests:**
|
||||
|
||||
```bash
|
||||
uv sync --extra test
|
||||
uv run pytest tests/ -v
|
||||
```
|
||||
|
||||
**Development tools:**
|
||||
|
||||
```bash
|
||||
# Install all dev dependencies
|
||||
uv sync --extra dev
|
||||
|
||||
# Linting and formatting
|
||||
uv run ruff check src/ tests/
|
||||
uv run ruff format src/ tests/
|
||||
|
||||
# Type checking
|
||||
uv run mypy src/embeddingbuddy/
|
||||
|
||||
# Security scanning
|
||||
uv run bandit -r src/
|
||||
uv run safety check
|
||||
```
|
||||
|
||||
**Test with sample data:**
|
||||
Use the included `sample_data.ndjson` and `sample_prompts.ndjson` files for testing the application functionality.
|
||||
|
||||
@@ -42,7 +61,7 @@ Use the included `sample_data.ndjson` and `sample_prompts.ndjson` files for test
|
||||
|
||||
The application follows a modular architecture with clear separation of concerns:
|
||||
|
||||
```
|
||||
```text
|
||||
src/embeddingbuddy/
|
||||
├── app.py # Main application entry point and factory
|
||||
├── main.py # Application runner
|
||||
@@ -72,27 +91,32 @@ src/embeddingbuddy/
|
||||
### Key Components
|
||||
|
||||
**Data Layer:**
|
||||
|
||||
- `data/parser.py` - NDJSON parsing with error handling
|
||||
- `data/processor.py` - Data transformation and combination logic
|
||||
- `models/schemas.py` - Dataclasses for type safety and validation
|
||||
|
||||
**Algorithm Layer:**
|
||||
|
||||
- `models/reducers.py` - Modular dimensionality reduction with factory pattern
|
||||
- Supports PCA, t-SNE (openTSNE), and UMAP algorithms
|
||||
- Abstract base class for easy extension
|
||||
|
||||
**Visualization Layer:**
|
||||
|
||||
- `visualization/plots.py` - Plot factory with single and dual plot support
|
||||
- `visualization/colors.py` - Color mapping and grayscale conversion utilities
|
||||
- Plotly-based 2D/3D scatter plots with interactive features
|
||||
|
||||
**UI Layer:**
|
||||
|
||||
- `ui/layout.py` - Main application layout composition
|
||||
- `ui/components/` - Reusable, testable UI components
|
||||
- `ui/callbacks/` - Organized callbacks grouped by functionality
|
||||
- Bootstrap-styled sidebar with controls and large visualization area
|
||||
|
||||
**Configuration:**
|
||||
|
||||
- `config/settings.py` - Centralized settings with environment variable support
|
||||
- Plot styling, marker configurations, and app-wide constants
|
||||
|
||||
@@ -112,16 +136,19 @@ Optional fields: `id`, `category`, `subcategory`, `tags`
|
||||
The refactored callback system is organized by functionality:
|
||||
|
||||
**Data Processing (`ui/callbacks/data_processing.py`):**
|
||||
|
||||
- File upload handling
|
||||
- NDJSON parsing and validation
|
||||
- Data storage in dcc.Store components
|
||||
|
||||
**Visualization (`ui/callbacks/visualization.py`):**
|
||||
|
||||
- Dimensionality reduction pipeline
|
||||
- Plot generation and updates
|
||||
- Method/parameter change handling
|
||||
|
||||
**Interactions (`ui/callbacks/interactions.py`):**
|
||||
|
||||
- Point click handling and detail display
|
||||
- Reset functionality
|
||||
- User interaction management
|
||||
@@ -131,15 +158,18 @@ The refactored callback system is organized by functionality:
|
||||
The modular design enables comprehensive testing:
|
||||
|
||||
**Unit Tests:**
|
||||
|
||||
- `tests/test_data_processing.py` - Parser and processor logic
|
||||
- `tests/test_reducers.py` - Dimensionality reduction algorithms
|
||||
- `tests/test_visualization.py` - Plot creation and color mapping
|
||||
|
||||
**Integration Tests:**
|
||||
|
||||
- End-to-end data pipeline testing
|
||||
- Component integration verification
|
||||
|
||||
**Key Testing Benefits:**
|
||||
|
||||
- Fast test execution (milliseconds vs seconds)
|
||||
- Isolated component testing
|
||||
- Easy mocking and fixture creation
|
||||
@@ -167,6 +197,7 @@ Uses modern Python stack with uv for dependency management:
|
||||
5. **Tests** - Write tests for all new functionality
|
||||
|
||||
**Code Organization Principles:**
|
||||
|
||||
- Single responsibility principle
|
||||
- Clear module boundaries
|
||||
- Testable, isolated components
|
||||
@@ -174,7 +205,8 @@ Uses modern Python stack with uv for dependency management:
|
||||
- Error handling at appropriate layers
|
||||
|
||||
**Testing Requirements:**
|
||||
|
||||
- Unit tests for all core logic
|
||||
- Integration tests for data flow
|
||||
- Component tests for UI elements
|
||||
- Maintain high test coverage
|
||||
- Maintain high test coverage
|
||||
|
Reference in New Issue
Block a user