# Skua

**Shareable URLs for notebook outputs**

One function call turns plots, DataFrames, and text into permanent links.
Re-run the cell to update — same URL, fresh results.

## Installation

```bash
pip install getskua
```

No setup required. No account, no API key. The only runtime dependency is `requests`.

## Quick Start

```python
import matplotlib.pyplot as plt
import skua

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
ax.set_title("Quadratic Growth")

result = skua.record(fig, title="Quadratic Growth")
print(result.url)  # https://skua.dev/f/abc123
```

Share the URL with anyone. Call `skua.record()` again with the same title to update in place.

## Supported Types

Skua auto-detects the object type and picks the right serializer:

- **Matplotlib figures** — high-DPI PNG
- **Plotly figures** — fully interactive (zoom, pan, hover, export)
- **Pandas DataFrames** — sortable, filterable tables
- **Polars DataFrames** — same interactive tables (LazyFrames collected automatically)
- **NumPy arrays** — rendered as tables
- **PIL Images** — saved as PNG
- **Lists of dicts** — rendered as tables (handy for HuggingFace pipelines, eval loops)
- **PyTorch / TensorFlow tensors** — image tensors as PNG, others as tables
- **Anything else** — falls back to string representation

Skua uses your installed libraries to serialize objects, so there are never version conflicts.

## API

### `skua.record(obj, title, description=None, public=None)`

Capture and share a Python object. Returns a `RecordResult` with `.url` and `.metadata`.
In Jupyter, the original object is displayed inline.

### `skua.init(public=None)`

Set session-wide defaults. Call once at the top of a notebook — per-call arguments override.

### `skua.login()`

Open the browser to verify your email. Verified accounts get 90-day retention (vs 7 days), 50 findings (vs 10), and a public profile page at `skua.dev/u/username`.

### `skua.token("sk_...")`

Paste the token you receive by email after `skua.login()`.

## Limits

Anonymous sessions work out of the box:

- 7-day retention, 10 findings, 20 uploads/hour, 10 MB per finding

Verify your email to unlock:

- 90-day retention (resets on update, 1-year max), 50 findings, 10 MB per finding

## Privacy

Every finding is accessible to anyone who has its URL. URLs contain random IDs that are not guessable or listed anywhere, but there is no login-gated access control. The `public` flag only controls whether a finding appears on your profile page — it does not restrict access to the URL itself. Do not record sensitive data.

## Documentation

Full docs, live examples, and the API reference at [skua.dev/docs](https://skua.dev/docs).

## License

MIT

## Support

Questions or feedback? Email **hello@skua.dev** or open an issue on [GitHub](https://github.com/franklinstlabs/skua).
