django-nocturne 0.1.0__tar.gz

django_nocturne-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to django-nocturne will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-19
+
+### Added
+- `NocturneMiddleware` — zero-code request/response logging with exception capture and stacktrace recording
+- Statistical anomaly detection via Z-score across 5-minute error-rate buckets (MEDIUM / HIGH / CRITICAL severity tiers)
+- Multi-signal health scoring (0–100) combining error rate, response time, and volume signals
+- AI-powered root-cause analysis via LangChain: supports Anthropic Claude, OpenAI GPT-4o, Google Gemini, and local Ollama models
+- Webhook alerting — HMAC-SHA256 signed payloads with `WebhookEvent` delivery history
+- Health trend tracking — per-service `HealthSnapshot` model; `snapshot_health` management command
+- Real-time browser dashboard with Chart.js: error rate timeline, health bar chart with trend arrows, log level distribution, slowest endpoints, request volume sparkline, service status board
+- Global timeframe filter (15M / 30M / 1H / 3H / 6H / 12H / 24H / 7D) controlling all charts simultaneously
+- Log Explorer with expandable rows, syntax-highlighted stacktraces, and in-place AI analysis (4-state UX: idle → loading → result → cached)
+- Anomaly detail modal with Z-score visualiser, AI diagnosis, and webhook delivery status
+- Webhook Activity panel with live delivery feed and test webhook button
+- Health Trends panel with per-service cards (colour-coded by trend direction)
+- Full DRF REST API: health, logs, anomalies, webhooks, dashboard data
+- Two-tier permission model: `nocturne.view_nocturne` (read) vs superuser (write/admin)
+- `generate_demo_logs` management command: 975 entries, 3 realistic error spikes with stacktraces, seeded WebhookEvents and HealthSnapshots
+- `nocturne_config` and `test_ai_diagnosis` management commands
+- Django admin integration for all models
+- Support for Django 4.0–5.0, Python 3.9–3.12

django_nocturne-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rishav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_nocturne-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include nocturne/templates *
+recursive-include nocturne/static *
+recursive-include nocturne/migrations *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

django_nocturne-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: django-nocturne
+Version: 0.1.0
+Summary: Intelligent observability for Django. Detect anomalies, diagnose with AI, alert via webhooks — plug in, migrate, done.
+Author-email: Rishav <rishav00a@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/rishav00a/django-nocturne
+Project-URL: Documentation, https://django-nocturne.readthedocs.io
+Project-URL: Repository, https://github.com/rishav00a/django-nocturne
+Project-URL: Bug Tracker, https://github.com/rishav00a/django-nocturne/issues
+Project-URL: Changelog, https://github.com/rishav00a/django-nocturne/blob/main/CHANGELOG.md
+Keywords: django,observability,apm,monitoring,anomaly-detection,logging,webhook,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.0
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: numpy>=1.24
+Requires-Dist: requests>=2.28
+Requires-Dist: langchain-core>=0.2
+Provides-Extra: ollama
+Requires-Dist: langchain-ollama>=0.1; extra == "ollama"
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.1; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.1; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: langchain-google-genai>=0.1; extra == "gemini"
+Provides-Extra: all
+Requires-Dist: langchain-ollama>=0.1; extra == "all"
+Requires-Dist: langchain-anthropic>=0.1; extra == "all"
+Requires-Dist: langchain-openai>=0.1; extra == "all"
+Requires-Dist: langchain-google-genai>=0.1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: factory-boy>=3.2; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Dynamic: license-file
+
+# django-nocturne
+
+> Intelligent observability for Django. Detect anomalies, diagnose with AI, alert via webhooks — plug in, migrate, done.
+
+[![PyPI version](https://badge.fury.io/py/django-nocturne.svg)](https://badge.fury.io/py/django-nocturne)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-nocturne.svg)](https://pypi.org/project/django-nocturne/)
+[![Django Versions](https://img.shields.io/pypi/djversions/django-nocturne.svg)](https://pypi.org/project/django-nocturne/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/rishav00a/django-nocturne/actions/workflows/ci.yml/badge.svg)](https://github.com/rishav00a/django-nocturne/actions/workflows/ci.yml)
+
+---
+
+## What is django-nocturne?
+
+**django-nocturne** is a plug-and-play APM (Application Performance Monitoring) library for Django. It silently observes every HTTP request, statistically detects error spikes, asks an AI to diagnose them, fires webhook alerts, and renders a real-time dashboard — all with zero instrumentation changes to your application code.
+
+### Features
+
+- **Zero-code observability** — one middleware entry records every request automatically
+- **Statistical anomaly detection** — Z-score analysis across 5-minute buckets; three severity tiers (MEDIUM / HIGH / CRITICAL)
+- **Multi-signal health scoring** — composite 0–100 score from error rate, response time, and volume signals
+- **AI-powered root-cause analysis** — LangChain interface supports Anthropic Claude, OpenAI GPT, Google Gemini, and local Ollama models
+- **Webhook alerting** — HMAC-SHA256 signed payloads delivered to any HTTP endpoint when thresholds are breached
+- **Health trend tracking** — per-service snapshots over time; dashboard shows improving/degrading/stable trends
+- **Real-time dashboard** — Chart.js visualisations, log explorer with syntax-highlighted stacktraces, anomaly detail modals
+- **Timeframe filter** — global 15M / 30M / 1H / 3H / 6H / 12H / 24H / 7D filter controlling all charts simultaneously
+- **REST API** — full DRF API for health, logs, anomalies, webhooks, and dashboard data
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Core (no AI)
+pip install django-nocturne
+
+# With your preferred AI backend
+pip install "django-nocturne[anthropic]"   # Claude
+pip install "django-nocturne[openai]"      # GPT-4o
+pip install "django-nocturne[ollama]"      # Local Llama via Ollama
+pip install "django-nocturne[gemini]"      # Google Gemini
+```
+
+### 2. Configure (`settings.py`)
+
+```python
+INSTALLED_APPS = [
+    # ... your apps ...
+    "nocturne",
+]
+
+MIDDLEWARE = [
+    # ... other middleware ...
+    "nocturne.middleware.NocturneMiddleware",   # add last
+]
+
+NOCTURNE = {
+    "SERVICE_NAME": "my-api",
+    "ANOMALY_THRESHOLD": 2.0,              # Z-score cutoff
+    "AI_BACKEND": "anthropic",             # 'anthropic' | 'openai' | 'ollama' | 'gemini'
+    "AI_DIAGNOSIS_ENABLED": True,
+    "ANTHROPIC_API_KEY": env("ANTHROPIC_API_KEY"),
+    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
+}
+```
+
+### 3. Wire up URLs (`urls.py`)
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("nocturne/", include("nocturne.urls")),
+    # ...
+]
+```
+
+### 4. Migrate and run
+
+```bash
+python manage.py migrate
+python manage.py runserver
+```
+
+Open **http://localhost:8000/nocturne/dashboard/** — log in as a superuser.
+
+---
+
+## Configuration Reference
+
+All settings live inside the `NOCTURNE` dict in `settings.py`.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `SERVICE_NAME` | `"default"` | Tag applied to all log entries by the middleware |
+| `ANOMALY_THRESHOLD` | `2.0` | Z-score threshold to trigger anomaly detection |
+| `RETENTION_DAYS` | `30` | Auto-purge log entries older than N days |
+| `EXCLUDE_PATHS` | `["/health", "/static", "/favicon.ico"]` | Paths skipped by middleware |
+| `LOGIN_URL` | `"/admin/login/"` | Redirect for unauthenticated dashboard access |
+| `AI_BACKEND` | `"ollama"` | Active LLM backend: `anthropic` / `openai` / `ollama` / `gemini` |
+| `AI_DIAGNOSIS_ENABLED` | `True` | Master toggle for all AI calls |
+| `ANTHROPIC_API_KEY` | `""` | Claude API key |
+| `ANTHROPIC_MODEL` | `"claude-sonnet-4-6"` | Claude model ID |
+| `OLLAMA_BASE_URL` | `"http://localhost:11434"` | Ollama server URL |
+| `OLLAMA_MODEL` | `"llama3.2"` | Ollama model name |
+| `OPENAI_API_KEY` | `""` | OpenAI API key |
+| `OPENAI_MODEL` | `"gpt-4o"` | OpenAI model ID |
+| `OPENAI_BASE_URL` | `"https://api.openai.com/v1"` | Override for Azure / Groq / vLLM |
+| `GEMINI_API_KEY` | `""` | Google Gemini API key |
+| `GEMINI_MODEL` | `"gemini-1.5-flash"` | Gemini model ID |
+| `WEBHOOK_SECRET` | `""` | HMAC-SHA256 secret for webhook signature validation |
+
+---
+
+## API Reference
+
+All endpoints are prefixed with `/nocturne/` (or wherever you mounted the URLs).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `api/health/` | view | Health scores, error rate, anomaly counts |
+| `GET` | `api/logs/` | view | Paginated log entries (no stacktrace) |
+| `POST` | `api/logs/ingest/` | view | Ingest a log entry externally |
+| `GET` | `api/logs/<id>/` | view | Full log entry including stacktrace |
+| `POST` | `api/logs/<id>/analyse/` | view | AI root-cause analysis for a log |
+| `GET` | `api/anomalies/` | view | List anomaly events |
+| `PATCH` | `api/anomalies/<id>/` | admin | Resolve an anomaly |
+| `POST` | `api/detect/` | admin | Trigger anomaly detection scan |
+| `GET` | `api/dashboard/data/` | view | All chart data in one response |
+| `GET` | `api/webhooks/` | admin | List webhook configurations |
+| `POST` | `api/webhooks/` | admin | Create webhook configuration |
+| `PUT` | `api/webhooks/<id>/` | admin | Update webhook configuration |
+| `DELETE` | `api/webhooks/<id>/` | admin | Delete webhook configuration |
+| `GET` | `api/webhooks/events/` | view | Webhook delivery history |
+| `POST` | `api/webhooks/test/` | admin | Send test webhook to all active configs |
+| `POST` | `api/webhook/receive/` | admin | Simulated receiver endpoint |
+| `GET` | `dashboard/` | view | Browser dashboard (HTML) |
+
+**Auth tiers:**
+- `view` — superuser **or** user with `nocturne.view_nocturne` permission
+- `admin` — superuser only
+
+---
+
+## Webhook Payload
+
+When an anomaly is detected, Nocturne fires this payload to every active webhook config:
+
+```json
+{
+  "event": "anomaly.detected",
+  "timestamp": "2026-06-19T03:22:27Z",
+  "watchdog_version": "0.1.0",
+  "anomaly": {
+    "id": 42,
+    "service": "auth-service",
+    "severity": "CRITICAL",
+    "z_score": 4.7,
+    "error_count": 50,
+    "window_start": "...",
+    "window_end": "...",
+    "ai_diagnosis": "..."
+  },
+  "health": {
+    "score_before": 85.0,
+    "score_after": 20.0,
+    "trend": "degrading"
+  },
+  "action_required": true,
+  "dashboard_url": "/nocturne/dashboard/"
+}
+```
+
+Headers sent:
+- `Content-Type: application/json`
+- `X-Watchdog-Event: anomaly.detected`
+- `X-Watchdog-Severity: CRITICAL`
+- `X-Watchdog-Signature: sha256=<hmac>` (when `WEBHOOK_SECRET` is set)
+
+---
+
+## Management Commands
+
+Commands included with the package (available after `pip install django-nocturne`):
+
+| Command | Description |
+|---------|-------------|
+| `nocturne_config` | Print resolved NOCTURNE settings + DB stats |
+| `test_ai_diagnosis` | Verify AI backend is working |
+| `create_nocturne_user` | Create a viewer user with correct permissions |
+| `snapshot_health` | Take a health snapshot for all active services |
+
+```bash
+python manage.py nocturne_config
+python manage.py test_ai_diagnosis
+python manage.py test_ai_diagnosis --backend openai
+python manage.py create_nocturne_user
+python manage.py create_nocturne_user --username viewer1 --password secret
+python manage.py snapshot_health
+```
+
+Commands available in the example project only:
+
+| Command | Description |
+|---------|-------------|
+| `generate_demo_logs` | Seed 975 demo logs with 3 anomaly spikes, WebhookEvents, and HealthSnapshots |
+
+```bash
+python manage.py generate_demo_logs
+```
+
+---
+
+## Running the Example Project
+
+```bash
+git clone https://github.com/rishav00a/django-nocturne
+cd django-nocturne
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[anthropic]"   # or [ollama], [openai], [gemini]
+cd example_project
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py generate_demo_logs
+python manage.py runserver
+```
+
+Visit **http://localhost:8000/nocturne/dashboard/** and log in.
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_nocturne-0.1.0/README.md

@@ -0,0 +1,257 @@
+# django-nocturne
+
+> Intelligent observability for Django. Detect anomalies, diagnose with AI, alert via webhooks — plug in, migrate, done.
+
+[![PyPI version](https://badge.fury.io/py/django-nocturne.svg)](https://badge.fury.io/py/django-nocturne)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-nocturne.svg)](https://pypi.org/project/django-nocturne/)
+[![Django Versions](https://img.shields.io/pypi/djversions/django-nocturne.svg)](https://pypi.org/project/django-nocturne/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/rishav00a/django-nocturne/actions/workflows/ci.yml/badge.svg)](https://github.com/rishav00a/django-nocturne/actions/workflows/ci.yml)
+
+---
+
+## What is django-nocturne?
+
+**django-nocturne** is a plug-and-play APM (Application Performance Monitoring) library for Django. It silently observes every HTTP request, statistically detects error spikes, asks an AI to diagnose them, fires webhook alerts, and renders a real-time dashboard — all with zero instrumentation changes to your application code.
+
+### Features
+
+- **Zero-code observability** — one middleware entry records every request automatically
+- **Statistical anomaly detection** — Z-score analysis across 5-minute buckets; three severity tiers (MEDIUM / HIGH / CRITICAL)
+- **Multi-signal health scoring** — composite 0–100 score from error rate, response time, and volume signals
+- **AI-powered root-cause analysis** — LangChain interface supports Anthropic Claude, OpenAI GPT, Google Gemini, and local Ollama models
+- **Webhook alerting** — HMAC-SHA256 signed payloads delivered to any HTTP endpoint when thresholds are breached
+- **Health trend tracking** — per-service snapshots over time; dashboard shows improving/degrading/stable trends
+- **Real-time dashboard** — Chart.js visualisations, log explorer with syntax-highlighted stacktraces, anomaly detail modals
+- **Timeframe filter** — global 15M / 30M / 1H / 3H / 6H / 12H / 24H / 7D filter controlling all charts simultaneously
+- **REST API** — full DRF API for health, logs, anomalies, webhooks, and dashboard data
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Core (no AI)
+pip install django-nocturne
+
+# With your preferred AI backend
+pip install "django-nocturne[anthropic]"   # Claude
+pip install "django-nocturne[openai]"      # GPT-4o
+pip install "django-nocturne[ollama]"      # Local Llama via Ollama
+pip install "django-nocturne[gemini]"      # Google Gemini
+```
+
+### 2. Configure (`settings.py`)
+
+```python
+INSTALLED_APPS = [
+    # ... your apps ...
+    "nocturne",
+]
+
+MIDDLEWARE = [
+    # ... other middleware ...
+    "nocturne.middleware.NocturneMiddleware",   # add last
+]
+
+NOCTURNE = {
+    "SERVICE_NAME": "my-api",
+    "ANOMALY_THRESHOLD": 2.0,              # Z-score cutoff
+    "AI_BACKEND": "anthropic",             # 'anthropic' | 'openai' | 'ollama' | 'gemini'
+    "AI_DIAGNOSIS_ENABLED": True,
+    "ANTHROPIC_API_KEY": env("ANTHROPIC_API_KEY"),
+    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
+}
+```
+
+### 3. Wire up URLs (`urls.py`)
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("nocturne/", include("nocturne.urls")),
+    # ...
+]
+```
+
+### 4. Migrate and run
+
+```bash
+python manage.py migrate
+python manage.py runserver
+```
+
+Open **http://localhost:8000/nocturne/dashboard/** — log in as a superuser.
+
+---
+
+## Configuration Reference
+
+All settings live inside the `NOCTURNE` dict in `settings.py`.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `SERVICE_NAME` | `"default"` | Tag applied to all log entries by the middleware |
+| `ANOMALY_THRESHOLD` | `2.0` | Z-score threshold to trigger anomaly detection |
+| `RETENTION_DAYS` | `30` | Auto-purge log entries older than N days |
+| `EXCLUDE_PATHS` | `["/health", "/static", "/favicon.ico"]` | Paths skipped by middleware |
+| `LOGIN_URL` | `"/admin/login/"` | Redirect for unauthenticated dashboard access |
+| `AI_BACKEND` | `"ollama"` | Active LLM backend: `anthropic` / `openai` / `ollama` / `gemini` |
+| `AI_DIAGNOSIS_ENABLED` | `True` | Master toggle for all AI calls |
+| `ANTHROPIC_API_KEY` | `""` | Claude API key |
+| `ANTHROPIC_MODEL` | `"claude-sonnet-4-6"` | Claude model ID |
+| `OLLAMA_BASE_URL` | `"http://localhost:11434"` | Ollama server URL |
+| `OLLAMA_MODEL` | `"llama3.2"` | Ollama model name |
+| `OPENAI_API_KEY` | `""` | OpenAI API key |
+| `OPENAI_MODEL` | `"gpt-4o"` | OpenAI model ID |
+| `OPENAI_BASE_URL` | `"https://api.openai.com/v1"` | Override for Azure / Groq / vLLM |
+| `GEMINI_API_KEY` | `""` | Google Gemini API key |
+| `GEMINI_MODEL` | `"gemini-1.5-flash"` | Gemini model ID |
+| `WEBHOOK_SECRET` | `""` | HMAC-SHA256 secret for webhook signature validation |
+
+---
+
+## API Reference
+
+All endpoints are prefixed with `/nocturne/` (or wherever you mounted the URLs).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `api/health/` | view | Health scores, error rate, anomaly counts |
+| `GET` | `api/logs/` | view | Paginated log entries (no stacktrace) |
+| `POST` | `api/logs/ingest/` | view | Ingest a log entry externally |
+| `GET` | `api/logs/<id>/` | view | Full log entry including stacktrace |
+| `POST` | `api/logs/<id>/analyse/` | view | AI root-cause analysis for a log |
+| `GET` | `api/anomalies/` | view | List anomaly events |
+| `PATCH` | `api/anomalies/<id>/` | admin | Resolve an anomaly |
+| `POST` | `api/detect/` | admin | Trigger anomaly detection scan |
+| `GET` | `api/dashboard/data/` | view | All chart data in one response |
+| `GET` | `api/webhooks/` | admin | List webhook configurations |
+| `POST` | `api/webhooks/` | admin | Create webhook configuration |
+| `PUT` | `api/webhooks/<id>/` | admin | Update webhook configuration |
+| `DELETE` | `api/webhooks/<id>/` | admin | Delete webhook configuration |
+| `GET` | `api/webhooks/events/` | view | Webhook delivery history |
+| `POST` | `api/webhooks/test/` | admin | Send test webhook to all active configs |
+| `POST` | `api/webhook/receive/` | admin | Simulated receiver endpoint |
+| `GET` | `dashboard/` | view | Browser dashboard (HTML) |
+
+**Auth tiers:**
+- `view` — superuser **or** user with `nocturne.view_nocturne` permission
+- `admin` — superuser only
+
+---
+
+## Webhook Payload
+
+When an anomaly is detected, Nocturne fires this payload to every active webhook config:
+
+```json
+{
+  "event": "anomaly.detected",
+  "timestamp": "2026-06-19T03:22:27Z",
+  "watchdog_version": "0.1.0",
+  "anomaly": {
+    "id": 42,
+    "service": "auth-service",
+    "severity": "CRITICAL",
+    "z_score": 4.7,
+    "error_count": 50,
+    "window_start": "...",
+    "window_end": "...",
+    "ai_diagnosis": "..."
+  },
+  "health": {
+    "score_before": 85.0,
+    "score_after": 20.0,
+    "trend": "degrading"
+  },
+  "action_required": true,
+  "dashboard_url": "/nocturne/dashboard/"
+}
+```
+
+Headers sent:
+- `Content-Type: application/json`
+- `X-Watchdog-Event: anomaly.detected`
+- `X-Watchdog-Severity: CRITICAL`
+- `X-Watchdog-Signature: sha256=<hmac>` (when `WEBHOOK_SECRET` is set)
+
+---
+
+## Management Commands
+
+Commands included with the package (available after `pip install django-nocturne`):
+
+| Command | Description |
+|---------|-------------|
+| `nocturne_config` | Print resolved NOCTURNE settings + DB stats |
+| `test_ai_diagnosis` | Verify AI backend is working |
+| `create_nocturne_user` | Create a viewer user with correct permissions |
+| `snapshot_health` | Take a health snapshot for all active services |
+
+```bash
+python manage.py nocturne_config
+python manage.py test_ai_diagnosis
+python manage.py test_ai_diagnosis --backend openai
+python manage.py create_nocturne_user
+python manage.py create_nocturne_user --username viewer1 --password secret
+python manage.py snapshot_health
+```
+
+Commands available in the example project only:
+
+| Command | Description |
+|---------|-------------|
+| `generate_demo_logs` | Seed 975 demo logs with 3 anomaly spikes, WebhookEvents, and HealthSnapshots |
+
+```bash
+python manage.py generate_demo_logs
+```
+
+---
+
+## Running the Example Project
+
+```bash
+git clone https://github.com/rishav00a/django-nocturne
+cd django-nocturne
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[anthropic]"   # or [ollama], [openai], [gemini]
+cd example_project
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py generate_demo_logs
+python manage.py runserver
+```
+
+Visit **http://localhost:8000/nocturne/dashboard/** and log in.
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).