Metadata-Version: 2.3
Name: vivrecard
Version: 0.1.0
Summary: Crash capture and replay for async Python functions and background tasks
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# VivreCard 🏴‍☠️

> *Every crash leaves a card.*

**Crash capture and replay for async Python functions and background tasks.**

When an async function fails silently, VivreCard saves everything — inputs, context, traceback — so you can understand and reproduce the failure instantly.

## The Problem
```python
background_tasks.add_task(process_feedback, db, session)
# crashes silently... score is always 5... no idea why
```

## The Solution
```python
from vivrecard import capture, attach

@capture
async def process_feedback(db, session):
    attach("session_id", str(session.id))
    attach("role", session.role)
    ...
```

When it crashes:
```
🏴‍☠️ VivreCard | Crash captured: process_feedback
   Exception: JSONDecodeError: Expecting value: line 1 column 1
   Saved to: .vivrecard/2026-03-29T21-14-03_process_feedback.json
```

## Installation
```bash
pip install vivrecard
```

## Usage

### Capture crashes
```python
from vivrecard import capture, attach

@capture
async def my_background_task(user_id: int, data: dict):
    attach("user_id", user_id)  # attach extra context
    ...
```

### Redact sensitive fields
```python
@capture(redact=["password", "api_key"])
async def my_task(password: str, api_key: str):
    ...
```

### List captured crashes
```bash
vivrecard list
```

### Replay a crash
```bash
vivrecard replay .vivrecard/2026-03-29T21-14-03_process_feedback.json
```

## Crash Artifact

Every crash is saved as a JSON file in `.vivrecard/`:
```json
{
  "function": "process_feedback",
  "module": "app.services.interview",
  "is_async": true,
  "timestamp": "2026-03-29T21:14:03Z",
  "args": [],
  "kwargs": {"session_id": 42},
  "context": [{"key": "role", "value": "Software Engineer"}],
  "exception": {
    "type": "JSONDecodeError",
    "message": "Expecting value: line 1 column 1"
  },
  "traceback": "..."
}
```

## Why VivreCard?

In One Piece, a Vivre Card tracks someone's condition and location.
VivreCard tracks your async task's state at the moment it starts falling apart.

## License

MIT