llinescan/agents.md

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

# 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

# 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

# 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

# Update all dependencies
uv sync --upgrade

# Remove a dependency
uv remove package_name

# Show installed packages
uv pip list

Virtual Environment Management

# 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 <command>

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

# 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

# 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

# Auto-generate output paths
results_dir = Path("results/video" if args.video else "results")
results_dir.mkdir(parents=True, exist_ok=True)

Error Handling

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

# 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

# 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.