Metadata-Version: 2.4
Name: django-orbit
Version: 0.10.0
Summary: AI agent-native observability and debugging for Django
Author: Django Orbit Contributors
Maintainer: Django Orbit Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/astro-stack/django-orbit
Project-URL: Documentation, https://astro-stack.github.io/django-orbit
Project-URL: Repository, https://github.com/astro-stack/django-orbit
Project-URL: Changelog, https://github.com/astro-stack/django-orbit/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/astro-stack/django-orbit/issues
Keywords: django,debugging,observability,ai,agents,mcp,monitoring,telescope,profiling,debug-toolbar
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
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: Operating System :: OS Independent
Classifier: Programming Language :: Python
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 :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: django-stubs>=4.0; extra == "dev"
Requires-Dist: mcp>=1.0; extra == "dev"
Dynamic: license-file

# Django Orbit

**AI agent-native observability and debugging for Django.**

Django Orbit is a reusable Django app that records what your application is doing and exposes it through a dashboard and MCP tools. It captures requests, SQL queries, logs, exceptions, cache operations, jobs, storage, mail, permissions and more, then links related events by `family_hash` so humans and AI agents can debug from one coherent timeline.

Unlike Django Debug Toolbar, Orbit does not inject HTML into your app. It lives at its own isolated `/orbit/` URL and is designed to observe from a distance without interfering with the host project.

<img width="1312" height="612" alt="Django Orbit Dashboard" src="https://github.com/user-attachments/assets/87528512-b458-4217-8dde-699a23c507ce" />

[![PyPI version](https://img.shields.io/pypi/v/django-orbit?style=flat-square)](https://pypi.org/project/django-orbit/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=flat-square&logo=python)](https://python.org)
[![Django](https://img.shields.io/badge/Django-4.0%2B-green?style=flat-square&logo=django)](https://djangoproject.com)
[![License](https://img.shields.io/badge/License-MIT-purple?style=flat-square)](LICENSE)
[![Code Style](https://img.shields.io/badge/Code%20Style-Black-black?style=flat-square)](https://github.com/psf/black)

- [Documentation](https://astro-stack.github.io/django-orbit)
- [Try the demo](#try-the-demo)
- [MCP / AI assistant setup](#mcp-ai-assistant-setup)

## Why Orbit

Django teams increasingly debug with AI coding agents, but most local observability tools are built only for humans. Orbit is built for both:

- humans get a focused dashboard for inspecting runtime behavior;
- agents get structured MCP tools for investigation and handoff;
- captured events are grouped by request family, so evidence stays connected;
- agent output is masked, bounded and read-only by default.

| Capability | Django Debug Toolbar | Django Orbit |
|---|---:|---:|
| Runs outside your app UI | No | Yes |
| Works with APIs and SPAs | Limited | Yes |
| Persistent request history | No | Yes |
| SQL, logs and exceptions together | Partial | Yes |
| Background jobs and infrastructure events | No | Yes |
| Agent-native MCP debugging tools | No | Yes |
| Request-to-fix handoff bundles | No | Yes |
| Plug-and-play watcher health | No | Yes |

Inspired by Laravel Telescope, Spatie Ray and Django Debug Toolbar.

## What Orbit Tracks

| Category | Events |
|---|---|
| HTTP | Requests, responses, headers, body, status codes |
| Database | SQL queries, slow queries, duplicate query / N+1 signals |
| Logging | Python `logging` output, any level |
| Exceptions | Exception type, message, traceback and request context |
| Cache | GET hits/misses, SET, DELETE |
| Models | ORM create, update and delete events |
| Commands | `manage.py` executions with exit code |
| HTTP Client | Outgoing requests via supported clients |
| Mail | Sent email metadata and body previews |
| Signals | Django signal dispatches |
| Jobs | Celery, Django-Q, RQ and APScheduler signals/hooks |
| Redis | GET, SET, DEL, HGET, LPUSH and more |
| Permissions | Authorization checks, granted/denied |
| Transactions | `atomic()` commits and rollbacks |
| Storage | File save/open/delete operations |

All events can be linked by `family_hash`, which lets you inspect every query, log and exception associated with one request or operation.

## What's New in v0.10.0

Orbit v0.10.0 introduces the agent-native debugging base:

- safe MCP serialization with sensitive-key masking and deterministic truncation;
- `audit_mcp_exposure` to inspect the effective agent data policy;
- `investigate_request` for request-family diagnosis;
- `investigate_exception_group` for exception blast-radius analysis;
- `create_incident_bundle` for JSON or Markdown handoff bundles;
- `build_debug_brief` for matching ticket/error text to Orbit evidence;
- `propose_fix_hypotheses` for ranked fix directions;
- `propose_test_plan` for regression/performance test suggestions;
- `MCP_ENABLED: False` now blocks all MCP tools with a stable disabled response.

Telemetry opt-in is not part of v0.10.0. It is intentionally being kept for a separate future release.

## Installation

```bash
pip install django-orbit
```

For AI assistant integration, install the MCP extra:

```bash
pip install django-orbit[mcp]
```

## Quick Start

Add Orbit to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "orbit",
]
```

Add the middleware early in the stack:

```python
MIDDLEWARE = [
    "orbit.middleware.OrbitMiddleware",
    # ...
]
```

Mount the dashboard URLs:

```python
from django.urls import include, path

urlpatterns = [
    path("orbit/", include("orbit.urls")),
    # ...
]
```

Run migrations and start Django:

```bash
python manage.py migrate orbit
python manage.py runserver
```

Visit `http://localhost:8000/orbit/`.

## Try the Demo

```bash
git clone https://github.com/astro-stack/django-orbit.git
cd django-orbit
pip install -e .
python demo.py setup
python manage.py runserver
```

| URL | Purpose |
|---|---|
| `http://localhost:8000/` | Demo app |
| `http://localhost:8000/orbit/` | Orbit dashboard |
| `http://localhost:8000/orbit/stats/` | Stats dashboard |
| `http://localhost:8000/orbit/health/` | Watcher health dashboard |

## MCP AI Assistant Setup

Orbit exposes a local MCP server so AI assistants can query live Django runtime evidence.

```bash
pip install django-orbit[mcp]
```

Add this server to Claude Desktop, Cursor, Windsurf or any MCP-compatible client:

```json
{
  "mcpServers": {
    "django-orbit": {
      "command": "python",
      "args": ["manage.py", "orbit_mcp"],
      "cwd": "/path/to/your/django/project"
    }
  }
}
```

The server launches on demand over stdio. It is read-only: it queries `OrbitEntry` data and never mutates the host app.

### Raw Telemetry Tools

| Tool | Purpose |
|---|---|
| `get_recent_requests` | Last N requests with status, path and duration |
| `get_slow_queries` | SQL queries above the configured threshold |
| `get_exceptions` | Exceptions within a time window |
| `get_n1_patterns` | Requests with duplicate-query evidence |
| `get_request_detail` | All events for one `family_hash` |
| `search_entries` | Keyword search across entries |
| `get_stats_summary` | Error rate, average response time and cache stats |

### Agent-Native Tools

| Tool | Purpose |
|---|---|
| `audit_mcp_exposure` | Show the effective MCP safety policy |
| `investigate_request` | Diagnose one request family: timeline, signals, queries, hypotheses and next actions |
| `investigate_exception_group` | Summarize an exception fingerprint and affected paths |
| `create_incident_bundle` | Create JSON or Markdown handoff from request, fingerprint or ticket text |
| `build_debug_brief` | Match natural-language ticket text to recent evidence |
| `propose_fix_hypotheses` | Rank likely fix directions from captured evidence |
| `propose_test_plan` | Suggest regression/performance tests for the observed issue |

### Agent Workflow

A typical ticket-to-fix handoff looks like this:

```text
build_debug_brief("checkout returns 500 payment token rejected")
create_incident_bundle("fingerprint", "<fingerprint>", format="markdown")
propose_fix_hypotheses("fingerprint", "<fingerprint>")
propose_test_plan("family_hash", "<family_hash>")
```

The goal is not for Orbit to edit code. The goal is to give a human or coding agent enough structured, safe evidence to reproduce, test and fix the issue.

## Agent Safety

Agent-facing output goes through Orbit's safe serializer:

- sensitive keys are masked using `MASK_KEYS`;
- payloads can be disabled with `MCP_INCLUDE_PAYLOADS: False`;
- result sizes are bounded by `MCP_MAX_LIMIT`;
- oversized payloads are replaced with truncation metadata;
- `MCP_ENABLED: False` blocks all MCP tools with a stable disabled response.

Example:

```python
ORBIT_CONFIG = {
    "MCP_ENABLED": True,
    "MCP_INCLUDE_PAYLOADS": True,
    "MCP_MAX_LIMIT": 100,
    "MCP_MAX_PAYLOAD_CHARS": 12000,
}
```

## Configuration

All settings go in `ORBIT_CONFIG` or `ORBIT` in `settings.py`. Most projects can start with defaults.

```python
ORBIT_CONFIG = {
    "ENABLED": True,
    "SLOW_QUERY_THRESHOLD_MS": 500,
    "STORAGE_LIMIT": 1000,

    # Access control. Set this for shared/staging environments.
    "AUTH_CHECK": lambda request: request.user.is_staff,

    # Keep Orbit from breaking the host app if a watcher fails.
    "WATCHER_FAIL_SILENTLY": True,

    # MCP / agent exposure controls.
    "MCP_ENABLED": True,
    "MCP_INCLUDE_PAYLOADS": True,
    "MCP_MAX_LIMIT": 100,
    "MCP_MAX_PAYLOAD_CHARS": 12000,
}
```

All watchers can be controlled individually with `RECORD_*` flags such as `RECORD_REQUESTS`, `RECORD_QUERIES`, `RECORD_EXCEPTIONS`, `RECORD_JOBS`, `RECORD_REDIS`, `RECORD_TRANSACTIONS` and `RECORD_STORAGE`.

See the [configuration docs](https://astro-stack.github.io/django-orbit/configuration/) for the full list.

## Dashboard

### Main Dashboard: `/orbit/`

The main dashboard shows a live feed of captured entries. You can filter by type, search, inspect details, export JSON and navigate related entries.

### Stats Dashboard: `/orbit/stats/`

The stats dashboard summarizes request throughput, Apdex, percentiles, error rate, slow queries, cache hit rate, job health and security/permission signals.

### Health Dashboard: `/orbit/health/`

Each watcher registers with Orbit's health system. Failed or missing integrations are shown without taking down the rest of Orbit.

## Storage Backends

By default, Orbit stores entries in the project's default database. For production or heavier usage, route Orbit writes to a dedicated database alias:

```python
DATABASES = {
    "default": {...},
    "orbit": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "orbit.sqlite3",
    },
}

ORBIT_CONFIG = {
    "STORAGE_BACKEND": "orbit.backends.django_db.DjangoDBBackend",
    "STORAGE_DB_ALIAS": "orbit",
}
```

```bash
python manage.py migrate orbit --database=orbit
```

## Security Model

Orbit is powerful because it records application behavior. Treat access to `/orbit/` and MCP as developer/operator access.

Recommended defaults for shared environments:

```python
ORBIT_CONFIG = {
    "AUTH_CHECK": lambda request: request.user.is_staff,
    "MCP_ENABLED": False,  # enable only where local agent access is intended
    "WATCHER_FAIL_SILENTLY": True,
}
```

Orbit masks common sensitive keys in request data and agent-facing output, but you should still avoid exposing Orbit dashboards or MCP servers to untrusted users.

## Roadmap

The v0.10.0 base makes Orbit agent-native. Next tracks:

- OpenTelemetry bridge for interoperability with wider observability tooling;
- AI/LLM watcher for provider/model/token/tool-call metadata;
- dashboard affordances for copying incident bundles;
- GitHub/Jira ticket handoff flows;
- deeper query and regression analysis.

See [Agent-Native Roadmap](https://astro-stack.github.io/django-orbit/roadmap/).

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).
