source .venv/bin/activate # On Windows: .venv\Scripts\activate
19
```
20
21
3. **Install in editable mode with dev dependencies:**
22
23
```bash
24
pip install -e ".[dev]"
25
```
26
27
4. **Install FFmpeg** (required for video processing):
28
29
```bash
30
# macOS
31
brew install ffmpeg
32
33
# Ubuntu/Debian
34
sudo apt install ffmpeg
35
```
36
37
5. **Set up at least one AI provider API key:**
38
39
```bash
40
export OPENAI_API_KEY="sk-..."
41
# or
42
export ANTHROPIC_API_KEY="sk-ant-..."
43
# or
44
export GEMINI_API_KEY="..."
45
```
46
47
## Running Tests
48
49
```bash
50
pytest tests/
51
```
52
53
To run tests with coverage:
54
55
```bash
56
pytest tests/ --cov=video_processor
57
```
58
59
## Code Style
60
61
This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting.
62
63
**Check for lint issues:**
64
65
```bash
66
ruff check .
67
```
68
69
**Auto-fix lint issues:**
70
71
```bash
72
ruff check --fix .
73
```
74
75
**Format code:**
76
77
```bash
78
ruff format .
79
```
80
81
**Verify formatting (without modifying files):**
82
83
```bash
84
ruff format --check .
85
```
86
87
The project targets a line length of 100 characters and Python 3.10+. See `pyproject.toml` for the full Ruff configuration.
88
89
## Commit Conventions
90
91
Write clear, descriptive commit messages. Use the imperative mood in the subject line:
92
93
- `Add knowledge graph merging for batch mode`
94
- `Fix frame extraction crash on zero-length videos`
95
- `Update API provider discovery to handle rate limits`
96
97
Keep the subject line under 72 characters. Use the body to explain *what* and *why*, not *how*.
98
99
## Pull Request Process
100
101
1. **Create a branch** from `main` for your work:
102
103
```bash
104
git checkout -b your-branch-name
105
```
106
107
2. **Make your changes.** Write tests for new functionality and ensure existing tests still pass.
108
109
3. **Lint and format** your code before committing:
110
111
```bash
112
ruff check .
113
ruff format .
114
```
115
116
4. **Push your branch** and open a pull request against `main`.
117
118
5. **Fill out the PR template.** Describe your changes, the type of change, and your test plan.
119
120
6. **Address review feedback.** A maintainer will review your PR and may request changes. We aim to review PRs within a few business days.
121
122
## Reporting Bugs and Requesting Features
123
124
- **Bugs:** Open an issue using the [Bug Report](https://github.com/ConflictHQ/PlanOpticon/issues/new?template=bug_report.yml) template.
125
- **Features:** Open an issue using the [Feature Request](https://github.com/ConflictHQ/PlanOpticon/issues/new?template=feature_request.yml) template.
126
- **Questions:** Start a thread in [Discussions](https://github.com/ConflictHQ/PlanOpticon/discussions).
127
128
## Code of Conduct
129
130
This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold it.
131
132
## Security
133
134
If you discover a security vulnerability, please do **not** open a public issue. Instead, follow the process described in our [Security Policy](SECURITY.md).
135
136
## License
137
138
By contributing to PlanOpticon, you agree that your contributions will be licensed under the [MIT License](../LICENSE).