Pyflix Torrent Streaming Assistant

You are an AI assistant working on the **pyflix** repository—a Python library for torrent streaming that powers torrent-dl.

Mandatory Pre-Check

**CRITICAL**: Before responding to ANY request, read:

1. `docs/agent-instructions/` - Agent protocols and requirements

2. `docs/adrs/` - Past architectural decisions

3. `docs/specs/` - Feature specifications

Technology Stack

Project Structure

```

pyflix/

├── torrent/ # Core torrent handling

│ ├── moov.py # Video MOOV atom detection

│ └── strategy.py # Download strategy engine

├── utils/ # Utility modules

│ ├── helpers.py # Common helper functions

│ ├── settings.py # Configuration management

│ ├── logger.py # Logging setup

│ └── output.py # Output formatting

├── docs/ # Documentation (THE BRAIN)

├── scripts/ # Automation scripts

└── tests/ # Test suite

```

Core Principles

1. Documentation First

2. Research Before Coding

3. Test Everything

4. Automate Repetition

Workflow Requirements

When Adding Features

1. Check if a spec exists in `docs/specs/`; create one if not

2. Review relevant ADRs in `docs/adrs/`

3. Research current best practices

4. Write tests alongside implementation

5. Update architecture docs if structure changes

6. Run validation: `./scripts/validate.sh`

When Fixing Bugs

1. Write a test that reproduces the bug

2. Fix the bug

3. Verify test passes

4. Update spec if behavior changed

5. Run full test suite

When Refactoring

1. Ensure tests exist for affected code

2. Make incremental changes

3. Run tests after each change

4. Update architecture diagrams

Code Style

Follow PEP 8 with Black formatting. Use type hints, prefer explicit over implicit, write descriptive names, and add docstrings to public functions.

**Good example:**

```python

def have_moov(video_file: str) -> bool:

"""Check if video file has MOOV atom before MDAT.

Args:

video_file: Path to the video file to analyze

Returns:

True if MOOV atom is properly positioned, False otherwise

"""

pass

```

**Avoid:**

```python

def check(f):

pass

```

Error Handling

Use specific exception types, log errors with context, provide actionable error messages, and don't silence exceptions without reason.

**Good example:**

```python

try:

result = process_video(path)

except VideoProcessingError as e:

log.error("Failed to process video %s: %s", path, e)

raise

except FileNotFoundError:

log.error("Video file not found: %s", path)

raise VideoNotFoundError(path) from None

```

**Avoid:**

```python

try:

result = process_video(path)

except:

pass

```

Testing Guidelines

Validation Commands

```bash

Run all checks

./scripts/validate.sh

Run tests only

pytest

Run tests with coverage

pytest --cov=torrent --cov=utils --cov-report=term-missing

Run linting

flake8 torrent utils

black --check torrent utils

```

Important Constraints

Getting Help

**Remember: When in doubt, research and document.**