From 441398077ca2338303386849643ce34fe2cc0914 Mon Sep 17 00:00:00 2001 From: yair-mv Date: Sat, 8 Nov 2025 12:56:03 +0200 Subject: [PATCH] Add AI agent development guide - Create comprehensive agents.md with uv workflow instructions - Include environment setup, dependency management, and testing guidelines - Provide development patterns for AI agents working with this project - Cover troubleshooting, best practices, and example workflows - Document project structure and key dependencies --- agents.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..633ad19 --- /dev/null +++ b/agents.md @@ -0,0 +1,225 @@ +# AI Agent Development Guide + +This guide provides instructions for AI agents working with this Python project using `uv` for dependency management. + +## Environment Setup + +### Prerequisites +- Python 3.8+ installed +- `uv` package manager installed +- Git for version control + +### Project Structure +``` +llinescan/ +├── main.py # Main strip photography application +├── pyproject.toml # Project configuration and dependencies +├── uv.lock # Locked dependency versions +├── readme.md # User documentation +├── agents.md # This file - AI agent guide +├── results/ # Output directory for generated files +│ ├── video/ # MJPEG video outputs +│ └── debug/ # Debug analysis outputs +└── .gitignore # Git ignore patterns +``` + +## Working with UV + +### Initial Setup +```bash +# Sync dependencies from lock file +uv sync + +# This creates a virtual environment and installs all dependencies +# The virtual environment is automatically managed by uv +``` + +### Running the Application +```bash +# Basic usage - uv automatically activates the virtual environment +uv run main.py input_video.avi + +# With specific parameters +uv run main.py input_video.avi --threshold 0.01 --video --fps 30 --timestamp + +# Debug mode for threshold analysis +uv run main.py input_video.avi --debug +``` + +### Development Workflow + +#### Adding Dependencies +```bash +# Add a new dependency +uv add package_name + +# Add development dependency +uv add --dev package_name + +# Add with version constraint +uv add "package_name>=1.0,<2.0" +``` + +#### Managing Dependencies +```bash +# Update all dependencies +uv sync --upgrade + +# Remove a dependency +uv remove package_name + +# Show installed packages +uv pip list +``` + +#### Virtual Environment Management +```bash +# uv automatically manages virtual environments +# No need to manually activate/deactivate + +# To run Python directly in the environment +uv run python + +# To run any command in the environment +uv run +``` + +## Development Guidelines for AI Agents + +### Code Modifications +1. **Read existing code first**: Use `read_file` to understand current implementation +2. **Test changes incrementally**: Make small changes and test with `uv run` +3. **Follow existing patterns**: Maintain consistency with current code style +4. **Update documentation**: Modify `readme.md` when adding features + +### Testing Workflow +```bash +# Test basic functionality +uv run main.py test_video.avi --threshold 0.0 --start 0 --end 100 + +# Test video generation +uv run main.py test_video.avi --video --fps 10 --timestamp --output test.avi + +# Test debug mode +uv run main.py test_video.avi --debug +``` + +### Common Tasks + +#### Adding New Features +1. Create feature branch: `git checkout -b feature/new-feature` +2. Implement changes in `main.py` +3. Test with various parameters +4. Update documentation in `readme.md` +5. Commit and merge when complete + +#### Debugging Issues +1. Use `--debug` mode to analyze video processing +2. Test with small frame ranges (`--start 0 --end 50`) +3. Check output file sizes and dimensions +4. Use `ffprobe` to verify video properties + +#### Performance Optimization +1. Profile with small test cases first +2. Monitor memory usage with large videos +3. Test different threshold values for compression +4. Verify output quality vs. processing time + +### File I/O Patterns + +#### Input Validation +```python +# Check video file exists +video_path = Path(args.video_file) +if not video_path.exists(): + print(f"Error: Video file not found: {video_path}") + sys.exit(1) +``` + +#### Output Organization +```python +# Auto-generate output paths +results_dir = Path("results/video" if args.video else "results") +results_dir.mkdir(parents=True, exist_ok=True) +``` + +#### Error Handling +```python +try: + # Video processing code + process_video(...) +except Exception as e: + print(f"Error: {e}") + sys.exit(1) +``` + +### Dependencies Overview + +Key packages used in this project: +- **opencv-python**: Video processing and computer vision +- **numpy**: Numerical operations and array handling +- **matplotlib**: Plotting and graph generation for debug mode +- **pathlib**: Modern path handling (built-in) +- **argparse**: Command-line argument parsing (built-in) + +### Environment Variables + +No special environment variables required. The project uses: +- Current working directory for relative paths +- `results/` subdirectories for organized output +- Automatic virtual environment management via `uv` + +### Troubleshooting + +#### Common Issues +1. **Import errors**: Run `uv sync` to ensure dependencies are installed +2. **Permission errors**: Check file/directory permissions +3. **Video codec issues**: Ensure input video is readable by OpenCV +4. **Memory issues**: Use smaller frame ranges for testing + +#### Debug Commands +```bash +# Check uv environment +uv pip list + +# Verify Python version +uv run python --version + +# Test basic imports +uv run python -c "import cv2, numpy, matplotlib; print('All imports successful')" +``` + +### Best Practices for AI Agents + +1. **Always use `uv run`** instead of direct python execution +2. **Test with small datasets** before processing large videos +3. **Check file sizes** to ensure reasonable output +4. **Use relative paths** for portability +5. **Follow existing code patterns** for consistency +6. **Update documentation** when adding features +7. **Commit frequently** with descriptive messages +8. **Test edge cases** (empty videos, single frames, etc.) + +### Example Agent Workflow + +```bash +# 1. Understand current state +uv run main.py --help + +# 2. Test existing functionality +uv run main.py sample.avi --debug + +# 3. Make incremental changes +# (edit main.py) + +# 4. Test changes +uv run main.py sample.avi --new-feature + +# 5. Verify output +ls -la results/ + +# 6. Commit when working +git add . && git commit -m "Add new feature" +``` + +This workflow ensures reliable development and testing in the uv-managed environment. \ No newline at end of file