SmartCash YOLOv5 Development Guide
This skill guides AI assistants working on the SmartCash project - a YOLOv5 with EfficientNet-B4 implementation for Alfrida Sabar's research.
Project Context
This is a Python-based machine learning project with strict standards for modularity, testing, and documentation. The project uses a virtual environment named 'venv-test' (venv_linux) and follows PEP8 conventions.
Step-by-Step Instructions
1. Initial Context Loading
**CRITICAL: Always start by reading these files:**
Read `PLANNING.md` to understand architecture, goals, and constraintsRead `MODEL_ARC.md` to understand the model architectureRead `TASK.md` to check current tasks and project status2. Task Management
Before starting any work:
Check if the task exists in `TASK.md`If not listed, add it with: task description + today's dateAfter completing a task, immediately mark it as completed in `TASK.md`Add any discovered sub-tasks to a "Discovered During Work" section in `TASK.md`3. Code Structure Rules
**File Size Limit:**
Never create files longer than 500 lines of codeIf approaching limit, refactor into modules or helper files**Organization:**
Organize code into clearly separated modules by feature/responsibilityUse clear, consistent imports (prefer relative imports within packages)Use `python_dotenv` and `load_env()` for environment variables**Virtual Environment:**
Always use `venv_linux` (venv-test) for Python commandsUse it for running scripts, tests, and installations4. Testing Requirements
**For every new feature:**
Create Pytest unit tests in `/tests` folderMirror the main app structure in test organizationInclude minimum 3 tests: 1. Expected use case
2. Edge case
3. Failure case
**When updating logic:**
Check if existing unit tests need updatesUpdate tests immediately after code changes5. Code Style Standards
**Python Standards:**
Follow PEP8Use type hints for all functionsFormat code with `black`**Docstring Format (Google style):**
```python
def function_name(param1: type) -> return_type:
"""
Brief summary of what the function does.
Args:
param1 (type): Description of parameter.
Returns:
type: Description of return value.
"""
```
6. Logger Usage (Critical)
**DO:**
Use instance loggers (`self.logger`) instead of module-level loggersUse function-based logger access (`_get_logger()`) for module operationsPrevent logger propagation with `logger.propagate = False` in UI setupUse operation container logging for UI components**DON'T:**
Don't use module-level logger declarationsDon't call logger objects directly in event handlersDon't mix standard logging with UI container logging7. Type Safety and Error Handling
**DO:**
Add comprehensive type checking with `isinstance(data, dict)` before `.get()`Handle both dict and string inputs gracefullyProvide fallback values and error messages for invalid typesUse try-catch blocks around all UI operations with proper error logging**DON'T:**
Don't assume data structures are always dictionariesDon't call `.get()` on variables that might be stringsDon't ignore None or empty values in formatting functions8. UI Module Architecture (if applicable)
**Standardized container order:**
1. Header
2. Form
3. Action
4. Summary
5. Operation
6. Footer
**Best Practices:**
Register components with clear, consistent namingUse SharedMethodRegistry for cross-module functionalityImplement proper cleanup in module destructorsStore both header_container object and widget separatelyImplement `_update_status()` helper methodsProvide real-time feedback (info, success, warning, error states)9. Documentation Updates
**When to update ARCHITECTURE.md:**
New UI features addedDependencies changedSetup steps modified**Code Comments:**
Comment non-obvious codeUse inline `# Reason:` comments for complex logicEnsure understandability for mid-level developers10. AI Behavior Rules
**Critical Rules:**
Never assume missing context - ask questions if uncertainNever hallucinate libraries or functions - only use verified Python packagesAlways confirm file paths and module names exist before referencingNever delete or overwrite existing code unless explicitly instructed or part of TASK.md**Verification Steps:**
Verify imports are available before using themCheck that referenced files existConfirm module structure matches PLANNING.md conventionsCommon Anti-Patterns to Avoid
**Architecture violations:**
Don't bypass BaseUIModule pattern for new modulesDon't duplicate common functionality (use mixins instead)Don't create direct dependencies between modulesDon't implement complex multi-tab interfaces**Performance issues:**
Don't create memory leaks by not cleaning up event handlersDon't hold references to large objects in module-level variablesDon't initialize heavy operations during module importDon't block the UI thread with long-running operationsExample Workflow
```
1. Read PLANNING.md, MODEL_ARC.md, TASK.md
2. Check/add task in TASK.md
3. Implement feature following structure rules
4. Create 3+ Pytest tests in /tests
5. Format with black, add docstrings
6. Update TASK.md as completed
7. Update ARCHITECTURE.md if needed
```
Constraints
Maximum 500 lines per fileMinimum 3 unit tests per featureGoogle-style docstrings requiredPEP8 compliance mandatoryUse venv-test for all Python execution