Metadata-Version: 2.4
Name: backendbrain
Version: 1.0.6
Summary: AI-Powered Backend Intelligence & Acceleration Platform for Django
Author-email: Aman Gupta <amangupta@example.com>
License: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: Django
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=3.2
Requires-Dist: pydantic>=1.10.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Dynamic: license-file

# 🧠 BackendBrain

> **AI-Powered Backend Intelligence & Acceleration Platform for Django**

BackendBrain is an intelligent backend optimization platform built specifically for Django applications. It doesn't just monitor your application—it observes, learns, analyzes, and accelerates your backend to improve performance while reducing unnecessary database load and infrastructure costs.

Unlike traditional monitoring tools, BackendBrain acts like an intelligent backend engineer running alongside your application.

---

# ✨ Features

## 📊 Intelligent Performance Analysis

* Analyze request performance in real time
* Detect slow API endpoints
* Monitor CPU and memory usage
* Track request latency
* Measure SQL execution time
* Generate Backend Health Scores

---

## 🗄 SQL Analyzer

Automatically detects common database performance problems, including:

* N+1 Queries
* Duplicate Queries
* Slow Queries
* Excessive Database Calls
* Missing ORM Optimizations
* Database Bottlenecks

BackendBrain also provides Django-specific recommendations such as:

* `select_related()`
* `prefetch_related()`
* Query optimization suggestions
* Performance improvement guidance

---

## 🚀 Accelerator

BackendBrain doesn't just identify performance issues—it actively improves application performance.

### Smart Response Cache

Frequently requested GET responses are intelligently cached using request fingerprinting.

Instead of executing the same database queries repeatedly, BackendBrain serves cached responses whenever it's safe to do so.

---

### Request Deduplication (Single-Flight)

Imagine 100 users requesting the same endpoint simultaneously.

Without BackendBrain:

```text
100 Requests
        ↓
100 Django Executions
        ↓
100 Database Queries
```

With BackendBrain:

```text
100 Requests
        ↓
BackendBrain Accelerator
        ↓
1 Database Query
        ↓
99 Requests Wait Briefly
        ↓
100 Responses Returned
```

Only one request reaches the database while the remaining requests reuse the result, preventing unnecessary database load during traffic spikes.

---

### Adaptive Cache Learning

BackendBrain continuously learns your application's traffic patterns and automatically identifies endpoints that benefit from caching.

It intelligently adjusts cache lifetimes based on how frequently underlying data changes.

---

## 💰 Infrastructure Cost Optimization

The Accelerator helps reduce unnecessary backend work by minimizing repeated database queries and application processing.

Potential benefits include:

* Lower database load
* Faster API responses
* Reduced CPU utilization
* Lower memory consumption
* Better handling of traffic spikes
* Increased request throughput
* Reduced cloud infrastructure costs by avoiding unnecessary compute and database operations

Typical request flow:

```text
Without BackendBrain

1000 Requests
      ↓
1000 Django Executions
      ↓
1000 Database Queries
      ↓
Higher CPU + Higher RDS Load + Higher Infrastructure Cost


With BackendBrain Accelerator

1000 Requests
      ↓
Smart Cache & Deduplication
      ↓
Only Required Database Queries
      ↓
Lower CPU + Lower Database Load + Lower Infrastructure Cost
```

> Actual performance improvements and infrastructure savings depend on your application's traffic patterns and workload.

---

# ⚡ Zero-Block Telemetry

BackendBrain is built around an asynchronous Event Bus architecture.

Telemetry collection happens in the background without blocking request processing.

**Measured middleware overhead:** **< 3 ms**

---

# 📦 Installation

```bash
pip install backendbrain
```

---

# ⚙️ Django Setup

## 1. Add BackendBrain

```python
INSTALLED_APPS += [
    "backendbrain.middleware.django",
]
```

---

## 2. Register Middleware

Place BackendBrain near the top of the middleware stack.

```python
MIDDLEWARE.insert(
    2,
    "backendbrain.middleware.django.BackendBrainMiddleware",
)
```

---

## 3. Configure

```python
BACKENDBRAIN = {
    "enabled": True,

    # Analysis
    "analyze": True,

    # Accelerator
    "response_cache": True,
    "cache_learning": True,
    "deduplication": True,

    # Storage
    "storage": "sqlite",

    # Privacy
    "privacy_mode": "strict",
}
```

---

# 🖥 CLI

Analyze collected telemetry:

```bash
backendbrain analyze
```

Generate an HTML performance report:

```bash
backendbrain report --format html
```

Initialize BackendBrain:

```bash
backendbrain init
```

---

# 🏗 Architecture

BackendBrain uses a fully decoupled event-driven architecture.

```text
Request
    ↓
BackendBrain Middleware
    ↓
Event Bus
    ↓
Collectors
    ↓
Memory Queue
    ↓
SQLite / PostgreSQL
    ↓
Analyzers
    ↓
Recommendations
    ↓
HTML Reports
```

The request lifecycle remains fast while telemetry is processed asynchronously in the background.

---

# 🔒 Privacy First

BackendBrain is designed to collect operational telemetry—not your business data.

By default it does **not** collect:

* Passwords
* Authentication tokens
* Session IDs
* API Keys
* Cookies
* Sensitive request payloads

Privacy mode can be configured to meet your application's requirements.

---

# 📈 Supported Databases

BackendBrain works with Django's ORM and supports:

* SQLite
* PostgreSQL
* MySQL
* MariaDB
* AWS RDS

No database-specific code changes are required.

---

# ❓ FAQ

### Will BackendBrain slow down my application?

No.

BackendBrain processes telemetry asynchronously and is designed to add minimal overhead to the request lifecycle.

---

### Does BackendBrain replace monitoring tools?

No.

BackendBrain complements existing monitoring platforms by providing Django-specific backend analysis, optimization recommendations, and request acceleration.

---

### Does it support Redis?

Yes.

The Accelerator can use either:

* In-Memory Cache
* Redis

depending on your configuration.

---

### Can I use only the Analyzer?

Yes.

You can enable analysis while keeping the Accelerator disabled.

---

### Is BackendBrain open source?

Yes.

BackendBrain is released under the MIT License.

---

# 📄 License

MIT License

---

# ⭐ Support the Project

If BackendBrain helps improve your application, please consider giving the project a ⭐ on GitHub and contributing improvements through issues or pull requests.
