Metadata-Version: 2.4
Name: brakit
Version: 0.1.2
Summary: Zero-config observability for Python web frameworks
Project-URL: Homepage, https://brakit.ai
Project-URL: Repository, https://github.com/brakit-ai/brakit
Project-URL: Issues, https://github.com/brakit-ai/brakit/issues
Project-URL: Documentation, https://github.com/brakit-ai/brakit#readme
License-Expression: MIT
Keywords: debugging,fastapi,flask,observability,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: flask>=2.0; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Requires-Dist: uvicorn[standard]>=0.20; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Description-Content-Type: text/markdown

  Brakit Python SDK

  AI writes your code. Brakit watches what it does. 
  Every request, query, and API call mapped to the action that triggered it. See your entire backend at a glance. 
  Open source · Local first · Zero config · AI-native via MCP

  GitHub (https://github.com/brakit-ai/brakit) •
  Website (https://brakit.ai) •
  Contributing (https://github.com/brakit-ai/brakit/blob/main/CONTRIBUTING.md)

---

  Brakit Actions — endpoints grouped by user action
  
  Every endpoint grouped by the action that triggered it — see "Sign Up" and "Load Dashboard", not 47 raw requests

  Brakit Dashboard — issues surfaced automatically
  
  Brakit catches N+1 queries, PII leaks, and slow endpoints as you develop

  Claude reading Brakit findings in VS Code
  
  Claude reads issues via MCP and fixes your code

## Quick Start

The Python SDK captures queries, fetches, and requests from your **FastAPI** or **Flask** backend and forwards them to the Brakit dashboard running in your Node.js frontend.

### 1. Install the Node.js core (runs the dashboard)

```bash
npx brakit install
```

### 2. Install the Python SDK

```bash
pip install brakit
```

### 3. Add one import to your app

**FastAPI:**
```python
import brakit  # must be before FastAPI import
from fastapi import FastAPI

app = FastAPI()
```

**Flask:**
```python
import brakit  # must be before Flask import
from flask import Flask

app = Flask(__name__)
```

That's it. Start both apps normally. The Python SDK auto-detects your framework, instruments queries and fetches, and forwards everything to the Brakit dashboard at `http://localhost:<port>/__brakit`.

---

## What You Get

- **Cross-service tracing** — FETCH from Next.js to FastAPI? The DB query inside FastAPI nests under the fetch automatically
- **Full server tracing** — DB queries, outgoing HTTP calls, errors — zero code changes
- **Live dashboard** at `/__brakit` — performance overview, request timeline, scatter charts
- **8 security rules** scanned against live traffic — leaked secrets, PII in responses, missing auth flags
- **N+1 query detection** — same query pattern repeated 5+ times in a single request
- **AI-native via MCP** — Claude Code and Cursor can query issues and verify fixes directly

---

## Supported Frameworks

| Framework | Status    |
| --------- | --------- |
| FastAPI   | Supported |
| Flask     | Supported |
| Django    | Planned   |

## Supported Databases

| Driver     | Status    |
| ---------- | --------- |
| SQLAlchemy | Supported |
| asyncpg    | Supported |
| psycopg    | Planned   |

## Supported HTTP Clients

| Library  | Status    |
| -------- | --------- |
| urllib3  | Supported |
| httpx    | Supported |
| aiohttp  | Supported |
| requests | Supported (via urllib3) |

---

## How It Works

```
import brakit  →  auto-detect framework  →  instrument everything
                        |
                        +-- DB queries    (SQLAlchemy, asyncpg)
                        +-- HTTP fetches  (httpx, aiohttp, urllib3)
                        +-- Errors        (global exception hooks)
                        +-- Logs          (logging module)
                              |
                              +-- Forward to Node.js dashboard via localhost
```

`import brakit` patches your framework's middleware to capture request/response pairs, hooks into database drivers and HTTP clients, and forwards telemetry to the Brakit dashboard running in your Node.js process. No proxy, no extra ports.

### Production Safety

Brakit never runs in production. Multiple layers ensure it:

| Layer                        | How it blocks                             |
| ---------------------------- | ----------------------------------------- |
| `should_activate()`          | Checks `NODE_ENV` + 15 cloud/CI env vars  |
| devDependency                | Not installed in production                |
| `safe_wrap` + circuit breaker | Errors in brakit code fall back silently  |
| `BRAKIT_DISABLE=true`        | Manual kill switch                        |

---

## Optional Dependencies

```bash
# FastAPI support
pip install brakit[fastapi]

# Flask support
pip install brakit[flask]

# Development (tests, linting)
pip install brakit[dev]
```

---

## Development

```bash
git clone https://github.com/brakit-ai/brakit.git
cd brakit/sdks/python

pip install -e ".[dev]"
pytest tests/ -v
```

---

## Contributing

Brakit is early and moving fast. Areas where help would be great:

- **Database adapters** — psycopg, Tortoise ORM, Django ORM
- **Framework adapters** — Django, Starlette
- **HTTP client hooks** — more client libraries
- **Security rules** — new patterns, configurable severity

Please open an issue first for larger changes so we can discuss the approach.

## License

[MIT](https://github.com/brakit-ai/brakit/blob/main/LICENSE)
