chore: modernize project files and add skill development guide (#114)

solderzzc · web-flow · commit 2a9c2ab1b221 · 2026-03-01T23:16:31.000-08:00
- .gitignore: modernize with Python, ML models, Docker, IDE sections
- CONTRIBUTING.md: add skill-focused contributing guide
- CODE_OF_CONDUCT.md: update to Contributor Covenant 2.1
- Contributions.md: refresh third-party acknowledgments for 2026
- FUNDING.yml: move to .github/ (GitHub convention)
- docs/skill-development.md: add comprehensive skill development guide
  covering SKILL.md format, parameter types, JSON-lines protocol, and
  skill categories
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
diff --git a/.gitignore b/.gitignore
@@ -1,15 +1,52 @@
-model
+# ─── Python ───────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+.eggs/
+.venv/
+venv/
+env/
+
+# ─── ML Models & Data ────────────────────────────────
+*.pt
+*.pth
+*.onnx
+*.tflite
+*.pb
+*.h5
+*.safetensors
+model/
 model.tgz
-*.pyc
-runtime
+*.tgz
+weights/
+runs/
+
+# ─── Build ────────────────────────────────────────────
 build/build/*
 build/dist/*
 build/runtime_arch
 build/*
-*node_modules/*
-test/node_modules/*
-*.tgz
-.DS_Store
+runtime
+
+# ─── Node ─────────────────────────────────────────────
+node_modules/
+
+# ─── Docker ───────────────────────────────────────────
 docker/db
 volumes
+
+# ─── IDE & OS ─────────────────────────────────────────
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.env.local
+
+# ─── Project Specific ────────────────────────────────
 src/yolov7_reid/src/models/mgn_R50-ibn.onnx
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -2,75 +2,48 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to a positive environment for our
+community include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
 
-Examples of unacceptable behavior by participants include:
+Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic
- address, without explicit permission
+  address, without their explicit permission
 * Other conduct which could reasonably be considered inappropriate in a
- professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
+  professional setting
 
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at . All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,54 @@
+# Contributing to DeepCamera
+
+Thank you for your interest in contributing to DeepCamera! This project is evolving into an open-source AI skill platform for [SharpAI Aegis](https://sharpai.org).
+
+## How to Contribute
+
+### 🛠️ Build a New Skill
+
+The best way to contribute is by building a new skill. Each skill is a self-contained folder under `skills/` with:
+
+1. **`SKILL.md`** — declares parameters (rendered as UI in Aegis) and capabilities
+2. **`requirements.txt`** — Python dependencies
+3. **`scripts/`** — entry point using JSON-lines stdin/stdout protocol
+
+See [`skills/detection/yolo-detection-2026/`](skills/detection/yolo-detection-2026/) for a complete reference implementation.
+
+### 📋 Skill Ideas We Need
+
+- Camera providers: Eufy, Reolink, Tapo, Ring
+- Messaging channels: Matrix, LINE, Signal
+- Automation triggers: MQTT, webhooks
+- AI models: VLM scene analysis, SAM2 segmentation, depth estimation
+
+### 🐛 Report Issues
+
+- Use [GitHub Issues](https://github.com/SharpAI/DeepCamera/issues)
+- Include your platform, Python version, and steps to reproduce
+
+### 📝 Improve Documentation
+
+- Fix typos, improve clarity, add examples
+- Add platform-specific setup guides under `docs/`
+
+## Development Setup
+
+```bash
+git clone https://github.com/SharpAI/DeepCamera.git
+cd DeepCamera
+
+# Work on a skill
+cd skills/detection/yolo-detection-2026
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Code Style
+
+- Python: follow PEP 8
+- Use type hints where practical
+- Add docstrings to public functions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
diff --git a/Contributions.md b/Contributions.md
@@ -1,14 +1,23 @@
-# Contributions
-This project contains source code or library dependencies from the follow projects:
-* Tensorflow available at: https://github.com/tensorflow/tensorflow Apache License 2.0
-* MXNet available at: https://github.com/apache/incubator-mxnet Apache License 2.0
-* TVM available at: https://github.com/dmlc/tvm Apache License 2.0
-* Shinobi project available at: https://gitlab.com/Shinobi-Systems/Shinobi/ Copyright (c) 2018 Shinobi Systems
-* Termux project available at: https://github.com/termux/termux-app GPLv3/Apache License 2.0
-* Insightface project available at: https://github.com/deepinsight/insightface MIT License
-* Easyrs project available at: https://github.com/silvaren/easyrs MIT License
-* Nodejs: https://nodejs.org Copyright Node.js contributors. All rights reserved.
-* Python: https://www.python.org Python 2.7 license
-* Gcc for termux with fortran scipy etc: https://github.com/its-pointless/gcc_termux
-* RembrandtAndroid project available at https://github.com/imgly/RembrandtAndroid
-* Great English-writing introduction on [analyticsvidhya](https://www.analyticsvidhya.com/blog/2019/04/top-5-machine-learning-github-reddit/)
+# Third-Party Licenses & Acknowledgments
+
+This project uses or was inspired by the following open-source projects:
+
+## AI & ML Frameworks
+* [Ultralytics](https://github.com/ultralytics/ultralytics) — YOLOv8/v10/v11 (AGPL-3.0)
+* [Insightface](https://github.com/deepinsight/insightface) — Face recognition (MIT)
+* [FastReID](https://github.com/JDAI-CV/fast-reid) — Person re-identification (Apache-2.0)
+
+## Legacy Dependencies (src/)
+* [TensorFlow](https://github.com/tensorflow/tensorflow) — Apache License 2.0
+* [MXNet](https://github.com/apache/incubator-mxnet) — Apache License 2.0
+* [TVM](https://github.com/dmlc/tvm) — Apache License 2.0
+
+## Infrastructure
+* [Milvus](https://github.com/milvus-io/milvus) — Vector database (Apache-2.0)
+* [go2rtc](https://github.com/AlexxIT/go2rtc) — RTSP/WebRTC streaming (MIT)
+* [Node.js](https://nodejs.org) — MIT
+* [Python](https://www.python.org) — PSF License
+
+## Historical
+* Shinobi — https://gitlab.com/Shinobi-Systems/Shinobi/
+* Termux — https://github.com/termux/termux-app (GPLv3)
diff --git a/docs/skill-development.md b/docs/skill-development.md
@@ -0,0 +1,113 @@
+# Skill Development Guide
+
+This guide explains how to create a new skill for the DeepCamera skill catalog.
+
+## What is a Skill?
+
+A skill is a self-contained folder that provides an AI capability to [SharpAI Aegis](https://sharpai.org). Skills communicate with Aegis via **JSON lines** over stdin/stdout.
+
+## Skill Structure
+
+```
+skills/<category>/<skill-name>/
+├── SKILL.md              # Manifest + setup instructions
+├── requirements.txt      # Python dependencies
+├── scripts/
+│   └── main.py           # Entry point
+├── assets/
+│   └── icon.png          # 64×64 icon (optional)
+└── tests/
+    └── test_main.py      # Tests (optional)
+```
+
+## SKILL.md Format
+
+The `SKILL.md` file has two parts:
+1. **YAML frontmatter** — machine-readable parameters and capabilities
+2. **Markdown body** — human/LLM-readable setup instructions
+
+```yaml
+---
+name: my-skill
+description: "What this skill does"
+version: 1.0.0
+
+parameters:
+  - name: model
+    label: "Model"
+    type: select
+    options: ["option1", "option2"]
+    default: "option1"
+    group: Model
+
+capabilities:
+  my_capability:
+    script: scripts/main.py
+    description: "What this capability does"
+---
+
+# My Skill
+
+Description of the skill.
+
+## Setup
+
+Step-by-step setup instructions that SharpAI Aegis's
+LLM agent can read and execute.
+```
+
+## Parameter Types
+
+| Type | Renders As | Example |
+|------|-----------|---------|
+| `string` | Text input | Email, URL, API key |
+| `password` | Masked input | Passwords, tokens |
+| `number` | Number input with min/max | Confidence threshold |
+| `boolean` | Toggle switch | Enable/disable feature |
+| `select` | Dropdown | Model selection |
+| `url` | URL input with validation | Server address |
+| `camera_select` | Camera picker | Target cameras |
+
+## JSON Lines Protocol
+
+Scripts communicate with Aegis via stdin/stdout. Each line is a JSON object.
+
+### Script → Aegis (stdout)
+
+```jsonl
+{"event": "ready", "model": "...", "device": "..."}
+{"event": "detections", "camera_id": "...", "objects": [...]}
+{"event": "error", "message": "...", "retriable": true}
+```
+
+### Aegis → Script (stdin)
+
+```jsonl
+{"event": "frame", "camera_id": "...", "frame_path": "...", "timestamp": "..."}
+{"command": "stop"}
+```
+
+## Categories
+
+| Category | Directory | Use For |
+|----------|-----------|---------|
+| `detection` | `skills/detection/` | Object detection, person recognition |
+| `analysis` | `skills/analysis/` | VLM scene understanding, offline analysis |
+| `transformation` | `skills/transformation/` | Depth estimation, style transfer |
+| `annotation` | `skills/annotation/` | Dataset labeling, COCO export |
+| `camera-providers` | `skills/camera-providers/` | Blink, Eufy, Ring, Reolink, Tapo |
+| `streaming` | `skills/streaming/` | RTSP/WebRTC via go2rtc |
+| `channels` | `skills/channels/` | Messaging: Matrix, LINE, Signal |
+| `automation` | `skills/automation/` | MQTT, webhooks, HA triggers |
+| `integrations` | `skills/integrations/` | Home Assistant bridge |
+
+## Testing Locally
+
+```bash
+# Test your skill without Aegis by piping JSON:
+echo '{"event": "frame", "camera_id": "test", "frame_path": "/tmp/test.jpg"}' | python scripts/main.py
+```
+
+## Reference
+
+See [`skills/detection/yolo-detection-2026/`](../skills/detection/yolo-detection-2026/) for a complete working example.
