"Great software is built by great communities. Welcome to ours."
Click to expand / collapse
- 👋 Welcome
- 📋 Before You Start
- 🧭 Ways to Contribute
- ⚙️ Development Environment Setup
- 🌿 Branching Strategy
- 💻 Coding Standards
- ✅ Commit Message Convention
- 🔁 Pull Request Process
- 🔍 Finding & Claiming Issues
- 🏷️ Issue Labels & GSSoC Points
- 🧪 Testing Guidelines
- 📁 Project Structure Reference
- 🚫 What NOT to Do
- 🔐 Security Vulnerabilities
- 📜 Code of Conduct
- 💬 Community & Support
- 🙏 Recognition
Thank you for your interest in contributing to Execra — the Universal Execution Intelligence Layer! 🎉
Execra is an open-source, multimodal AI system designed to observe your actions in real time and guide you through correct execution before mistakes happen. It is proudly part of GirlScript Summer of Code (GSSoC) 2026, and we warmly welcome contributors of all backgrounds, experience levels, and skill sets.
Whether you're fixing a typo, writing a test, building a new feature, or improving documentation — every contribution matters.
┌────────────────────────────────────────────────────────────┐
│ THE EXECRA PHILOSOPHY │
│ │
│ Observe → Understand → Guide → Correct │
│ │
│ Apply this to your contributions too: │
│ Read → Understand the issue → Code the fix → PR it │
└────────────────────────────────────────────────────────────┘
Please read the following documents before making any contributions:
| Document | Purpose |
|---|---|
| README.md | Project overview, architecture & setup |
| CODE_OF_CONDUCT.md | Community behavior expectations |
| LICENSE | MIT License terms |
Important
By contributing to Execra, you agree that your contributions will be licensed under the MIT License.
There are many ways you can contribute to Execra, regardless of experience level:
|
|
Before cloning the project, ensure you have the following installed:
| Dependency | Minimum Version | Purpose |
|---|---|---|
| Python | 3.10+ | Core backend runtime |
| Node.js | 18+ | Frontend / Overlay build |
| FFmpeg | Any recent | Camera stream processing |
| Git | 2.30+ | Version control |
| Docker (optional) | 20+ | Container-based setup |
# 1. Fork the repository on GitHub
# Click the "Fork" button at https://github.com/yourusername/execra
# 2. Clone YOUR fork (replace YOUR_USERNAME)
git clone https://github.com/YOUR_USERNAME/execra.git
cd execra
# 3. Add the original repo as the upstream remote
git remote add upstream https://github.com/yourusername/execra.git
# 4. Verify remotes are configured correctly
git remote -v
# origin https://github.com/YOUR_USERNAME/execra.git (fetch)
# upstream https://github.com/yourusername/execra.git (fetch)
# 5. Create and activate a Python virtual environment
python -m venv venv
source venv/bin/activate # Linux / macOS
venv\Scripts\activate # Windows
# 6. Install all Python dependencies
pip install -r requirements.txt
# 7. Install development dependencies (linters, formatters, test tools)
pip install -r requirements-dev.txt
# 8. Install pre-commit hooks
pip install pre-commit
pre-commit install
# 9. Install dashboard dependencies
cd dashboard
npm install
cd ..
# 10. Configure environment variables
cp .env.example .env
# Open .env and add your API keys (OpenAI / Gemini)
# 11. Download YOLO model weights
python scripts/download_models.py
# 12. Verify setup by running tests
python -m pytest tests/
# 13. Start Execra locally
python main.py# Build and run all services with Docker Compose
docker-compose up --build
# Services will be available at:
# API Server → http://localhost:8000
# Svelte Dashboard → http://localhost:5173
# API Docs → http://localhost:8000/docsAlways sync your fork with upstream before starting new work:
# Fetch latest changes from upstream
git fetch upstream
# Switch to your local main branch
git checkout main
# Merge upstream changes into your local main
git merge upstream/main
# Push updated main to your fork
git push origin mainWe follow a feature-branch workflow. Never commit directly to main.
main
├── feature/screen-delta-detection
├── feature/trust-scorer-v2
├── fix/camera-feed-memory-leak
├── fix/ocr-null-handling-88
├── docs/api-reference-update
└── test/context-engine-coverage
| Type | Format | Example |
|---|---|---|
| New Feature | feature/short-description |
feature/consequence-simulation-engine |
| Bug Fix | fix/issue-number-description |
fix/88-camera-feed-memory-leak |
| Documentation | docs/what-you-are-documenting |
docs/trust-scorer-api-reference |
| Tests | test/module-being-tested |
test/context-engine-unit-tests |
| Refactor | refactor/component-name |
refactor/llm-client-abstraction |
| Chore | chore/task-description |
chore/update-yolo-dependencies |
# Always branch off from the latest main
git checkout main
git pull upstream main
# Create and switch to your new branch
git checkout -b feature/your-feature-name
# ... make your changes ...
# Push your branch to your fork
git push origin feature/your-feature-nameConsistent code is easier to review, maintain, and debug. Please follow these standards:
- Follow PEP 8 — Python's official style guide
- Use Black for auto-formatting (line length: 88)
- Use isort for import ordering
- Use flake8 for linting
# Format your code before committing
black .
isort .
flake8 .# ✅ GOOD — descriptive names, type hints, docstrings
def calculate_trust_score(
llm_confidence: float,
rule_validation: bool,
execution_trace_match: float
) -> dict:
"""
Calculate the overall trust score for an instruction.
Args:
llm_confidence: Confidence score from the LLM (0.0 - 1.0)
rule_validation: Whether rule-based validator approved the instruction
execution_trace_match: Similarity to known safe execution patterns
Returns:
dict: Contains 'score', 'level', and 'reasoning' keys
"""
...
# ❌ BAD — unclear names, no type hints, no docstring
def calc(a, b, c):
...- Always add type hints to function signatures
- Always add docstrings to public functions, classes, and modules
- Max line length: 88 characters (Black default)
- No unused imports — use
isortto clean up - No bare
except:— always catch specific exceptions - Use f-strings, not
.format()or%
- Follow ESLint rules defined in
.eslintrc - Use Prettier for formatting
- Prefer
constoverlet; avoidvar - Use descriptive component and variable names
# Lint and format frontend code
npm run lint
npm run format- No hardcoded secrets or API keys — use environment variables via
.env - No commented-out dead code in PRs — remove it
- Keep functions small and focused — single responsibility principle
- Write self-documenting code — names should explain intent
- Add comments only when the why is not obvious, not the what
We follow the Conventional Commits specification. All commit messages must adhere to this format:
<type>(<optional scope>): <short description>
[optional body]
[optional footer: e.g., Closes #42]
| Type | When to Use | Example |
|---|---|---|
feat |
Adding a new feature | feat: implement real-time screen delta detection |
fix |
Fixing a bug | fix(camera): resolve memory leak in feed handler (#88) |
docs |
Documentation changes only | docs: add API reference for context engine |
style |
Code formatting (no logic change) | style: reformat trust_scorer.py with black |
refactor |
Code restructuring (no feature/bug) | refactor: extract LLM client into abstraction layer |
test |
Adding or updating tests | test: add unit tests for consequence simulator |
chore |
Build, tooling, or dependency changes | chore: update YOLOv8 to v8.2.0 |
perf |
Performance improvement | perf: optimize screen capture frame rate |
ci |
CI/CD configuration changes | ci: add Python 3.12 to test matrix |
build |
Build system changes | build: add docker multi-stage build |
✅ feat: add OCR support for multi-language text detection (#42)
✅ fix(perception): handle null frame in screen_capture.py
✅ docs: update README getting started section
✅ test: add edge case coverage for trust scorer
❌ fixed stuff
❌ WIP
❌ update
❌ changes
❌ asdfgh
Note
Keep the subject line under 72 characters. Use the body to explain why the change was made, not what — the diff shows that.
YOUR CONTRIBUTION JOURNEY
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐
│ Claim │──►│ Branch │──►│ Code & │──►│ Open │
│ Issue │ │ Created │ │ Test │ │ PR │
└──────────┘ └──────────┘ └───────────┘ └────┬─────┘
│
┌──────────────────────────────────────┘
│
┌────────────▼───┐ ┌──────────────┐ ┌───────────────┐
│ Code Review │──►│ Changes │──►│ MERGED! 🎉 │
│ (Maintainer) │ │ Requested? │ │ Points Added │
└────────────────┘ └──────────────┘ └───────────────┘
- I have read and followed the contribution guidelines
- My branch is up to date with
upstream/main - All existing tests pass (
python -m pytest tests/) - I have written tests for my changes (where applicable)
- My code follows the coding standards (Black, isort, flake8 pass)
- I have added/updated docstrings for all public functions I touched
- I have updated documentation if my changes affect behavior
- I have linked the relevant GitHub issue in my PR
- My PR title follows the Conventional Commits format
feat(perception): add multi-language OCR support (#42)
fix(camera): resolve memory leak in frame handler (#88)
docs: update API reference for context engine
When opening a PR, fill out the provided template completely:
## 🔗 Related Issue
Closes #<issue-number>
## 📝 Summary of Changes
Brief description of what was changed and why.
## 🔍 Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Test addition
- [ ] Refactor / Code cleanup
## 🧪 How Was This Tested?
Describe the tests you ran and how to reproduce them.
## 📸 Screenshots (if applicable)
Add screenshots or screen recordings if this affects the UI.
## ✅ Checklist
- [ ] Code follows project style guidelines
- [ ] Tests pass locally
- [ ] Docstrings and comments added/updated
- [ ] Documentation updated if needed- Auto-checks run — CI will lint, test, and format-check your code
- Maintainer review — A maintainer will review within 3–5 business days
- Address feedback — If changes are requested, push new commits to the same branch
- Approval & merge — Once approved, a maintainer will merge your PR
- GSSoC points — Points are assigned after successful merge
Warning
Do NOT force-push to a branch that has an open PR — it makes reviewing harder. Instead, add new commits.
1. Go to → https://github.com/yourusername/execra/issues
2. Filter by labels:
- "good first issue" → for beginners
- "help wanted" → open for all
- "gssoc-2026" → GSSoC specific tasks
3. READ the full issue description before commenting
4. Comment: "I'd like to work on this! [brief plan of approach]"
5. Wait for a maintainer to assign it to you (usually within 24–48h)
6. Once assigned, create a branch and start working
Important
Do NOT submit a PR for an issue that is not assigned to you. This prevents duplicate work and ensures fair contribution tracking.
- Each contributor may have up to 2 issues assigned at a time
- If no progress is made within 7 days, the issue may be unassigned and reopened
- Do not ask to be assigned to multiple issues at once before completing existing ones
Points are awarded by GSSoC 2026 based on issue difficulty and contribution quality.
| Label | Points | Difficulty | Typical Tasks |
|---|---|---|---|
 good first issue |
10 pts | ⭐ Beginner | Fixing typos, adding docstrings, small UI tweaks, writing examples |
 easy |
25 pts | ⭐⭐ Easy | Adding unit tests, small bug fixes, minor feature additions |
 medium |
45 pts | ⭐⭐⭐ Medium | Feature modules, integration tasks, significant bug fixes |
 hard |
60 pts | ⭐⭐⭐⭐ Hard | Core architecture, new domain engines, performance optimization |
 documentation |
10–25 pts | Any | Guides, API docs, tutorials, diagrams |
 help wanted |
Varies | Varies | Any contributor, check issue details |
| Label | Meaning |
|---|---|
bug |
Confirmed bug that needs fixing |
enhancement |
Improvement to existing feature |
question |
Needs clarification before work begins |
wip |
Work in progress — do not pick up |
duplicate |
Issue already reported elsewhere |
invalid |
Not a valid bug/feature |
blocked |
Waiting on another issue/dependency |
gssoc-2026 |
Officially part of GSSoC 2026 program |
All contributions to core modules must include tests. We use pytest for Python testing.
# Run the full test suite
python -m pytest tests/
# Run specific test file
python -m pytest tests/unit/test_trust_scorer.py
# Run with verbose output
python -m pytest tests/ -v
# Run and show coverage report
python -m pytest tests/ --cov=core --cov-report=term-missing
# Run only tests matching a keyword
python -m pytest tests/ -k "trust_score"tests/
├── unit/ # Test individual functions/classes in isolation
│ ├── test_trust_scorer.py
│ ├── test_context_engine.py
│ ├── test_consequence_sim.py
│ └── test_ocr_engine.py
│
├── integration/ # Test interactions between modules
│ ├── test_perception_pipeline.py
│ └── test_intelligence_core.py
│
└── e2e/ # End-to-end workflows (full system tests)
└── test_digital_domain_workflow.py
# tests/unit/test_trust_scorer.py
import pytest
from core.intelligence.trust_scorer import calculate_trust_score
class TestCalculateTrustScore:
"""Unit tests for the trust score calculation function."""
def test_high_confidence_returns_trusted(self):
"""Score above 0.8 should return 'trusted' level."""
result = calculate_trust_score(
llm_confidence=0.95,
rule_validation=True,
execution_trace_match=0.90
)
assert result["level"] == "trusted"
assert result["score"] >= 0.80
def test_low_confidence_returns_uncertain(self):
"""Score below 0.5 should return 'uncertain' level."""
result = calculate_trust_score(
llm_confidence=0.30,
rule_validation=False,
execution_trace_match=0.20
)
assert result["level"] == "uncertain"
def test_returns_required_keys(self):
"""Result must always contain 'score', 'level', 'reasoning'."""
result = calculate_trust_score(0.7, True, 0.6)
assert "score" in result
assert "level" in result
assert "reasoning" in result
def test_invalid_confidence_raises_error(self):
"""Confidence values outside [0, 1] should raise ValueError."""
with pytest.raises(ValueError):
calculate_trust_score(1.5, True, 0.8)- New modules: Minimum 80% test coverage required
- Bug fixes: Must include a regression test proving the bug is fixed
- Refactors: All existing tests must continue to pass
Understanding the codebase before contributing is essential:
execra/
│
├── 📁 core/ ← Main Python backend
│ ├── perception/
│ │ ├── screen_capture.py # Screen capture engine
│ │ ├── camera_feed.py # Camera input handler
│ │ └── ocr_engine.py # Text recognition (Tesseract)
│ │
│ ├── intelligence/
│ │ ├── llm_client.py # LLM abstraction (GPT-4o / Gemini)
│ │ ├── context_engine.py # Session context manager
│ │ ├── consequence_sim.py # Outcome prediction engine
│ │ └── trust_scorer.py # Confidence scoring per instruction
│ │
│ ├── digital/
│ │ ├── code_tracer.py # Runtime execution tracer (sys.settrace)
│ │ ├── error_detector.py # Logical error identification
│ │ └── task_decomposer.py # High-level goal → structured steps
│ │
│ ├── physical/
│ │ ├── object_detector.py # YOLOv8-based object detection
│ │ ├── task_recognizer.py # Physical task classifier from vision
│ │ └── action_validator.py # Real-world action checker
│ │
│ └── hybrid/
│ ├── mode_manager.py # Passive / Active / Mixed mode switcher
│ ├── action_logger.py # Undo/Replay/Recovery stack
│ └── guidance_dispatcher.py # Routes instructions to output layer
│
├── 📁 dashboard/ ← SvelteKit Realtime Monitoring Dashboard
│ ├── src/ # Svelte 5 routes, components, and service layers
│ │ ├── lib/ # Core helpers e.g. websocket.svelte.ts
│ │ └── routes/ # Routing views (+page.svelte)
│ ├── static/ # Static public assets
│ └── package.json # SvelteKit dependencies
│
├── 📁 api/ ← FastAPI REST & WebSocket layer
│ ├── main.py # FastAPI application entrypoint
│ ├── routes/ # REST API route handlers
│ └── websockets/ # Real-time WebSocket communication
│
├── 📁 models/ ← AI model weights (not committed to git)
│ ├── yolo/ # YOLOv8 object detection weights
│ └── custom/ # Domain-specific classifiers
│
├── 📁 tests/ ← Test suite (unit + integration + e2e)
├── 📁 docs/ ← Project documentation
├── 📁 scripts/ ← Utility scripts
│
├── main.py ← Application entrypoint
├── requirements.txt ← Python runtime dependencies
├── requirements-dev.txt ← Dev/test dependencies
├── docker-compose.yml
└── .env.example ← Template for environment variables
| Module | Good Starting Points |
|---|---|
core/intelligence/trust_scorer.py |
Well-isolated, great for adding tests |
core/perception/ocr_engine.py |
Language/OCR improvements welcome |
api/routes/ |
Add new REST endpoints following existing patterns |
dashboard/src/ |
UI dashboard components, layout styles, and WebSocket hooks |
tests/ |
Writing missing unit tests for any core module |
docs/ |
Documentation, guides, API references |
╔══════════════════════════════════════════════════════════════╗
║ AVOID THESE ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ ❌ Submitting empty, trivial or AI-dump PRs for points ║
║ ❌ Spamming issues asking to be assigned without reading ║
║ ❌ Claiming issues and going silent for 7+ days ║
║ ❌ Pushing directly to main (your PR will be rejected) ║
║ ❌ Committing .env files, API keys or secrets ║
║ ❌ Committing model weights (use scripts/download_*.py) ║
║ ❌ Making changes outside the scope of the assigned issue ║
║ ❌ Force-pushing to a branch with an open PR ║
║ ❌ Copying code without proper attribution ║
║ ❌ Ignoring reviewer feedback without explanation ║
║ ║
╠══════════════════════════════════════════════════════════════╣
║ ALWAYS DO THIS ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ ✅ Read the full issue before asking questions ║
║ ✅ Test your changes locally before submitting a PR ║
║ ✅ Write clear, meaningful commit messages ║
║ ✅ Add docstrings and type hints to all new functions ║
║ ✅ Respond to review feedback within 3 days ║
║ ✅ Be respectful, patient, and kind with maintainers ║
║ ✅ Ask questions in Discussions — not in issue comments ║
║ ║
╚══════════════════════════════════════════════════════════════╝
Caution
Do NOT open a public GitHub Issue for security vulnerabilities.
If you discover a security vulnerability in Execra, please report it privately and responsibly:
- Email: youremail@example.com with subject
[SECURITY] Vulnerability Report - Include: Description, steps to reproduce, potential impact, and suggested fix (if known)
- Response time: We aim to acknowledge within 48 hours and patch within 7 days
- Credit: Responsible reporters will be credited in the security advisory (unless anonymity is preferred)
This project is governed by the Contributor Covenant Code of Conduct v2.1.
In summary, we expect all contributors to:
- 🤝 Be welcoming, inclusive, and respectful
- 🗣️ Use constructive and professional language
- 🌱 Support and uplift beginners — everyone starts somewhere
- 🚫 Avoid harassment, discrimination, or exclusionary behavior
- 🔍 Focus on the issue, not the person
Violations may be reported confidentially to youremail@example.com.
Maintainers have the right to remove, edit, or reject any comment, commit, code, or other contribution that violates this Code of Conduct.
| Channel | Purpose | Link |
|---|---|---|
| 💬 GitHub Discussions | General questions, ideas, showcasing work | Open Discussions |
| 🐛 Issues | Bug reports and feature requests | Open an Issue |
| Private or sensitive matters | youremail@example.com | |
| 🌸 GSSoC Portal | Program updates and leaderboard | gssoc.girlscript.tech |
Tip
Before asking for help, search existing issues and discussions first — your question may already be answered!
We deeply appreciate every contribution, no matter how small.
- All contributors will be listed in the project's Contributors section
- GSSoC participants earn points towards the official leaderboard for merged PRs
- Exceptional contributions may be highlighted in release notes and project announcements
- First-time contributors earn a special "First PR" recognition in the community
Thank you for making Execra better. 🚀
Built with ❤️ for GirlScript Summer of Code 2026
Execra — Execute without boundaries.