# Sondeo Roadmap

## Vision

Sondeo is a **zero-dependency Python profiler** that makes performance debugging as simple as adding a decorator. It's built for developers who want to understand their code's behavior without wrestling with complex profiling tools.

The name "sondeo" means "survey" or "probe" in Spanish — that's exactly what it does: probe your code, survey its performance, and report what it finds.

### Design Principles

- **Zero config** — `@profile` and you're done
- **Zero dependencies** — stdlib only for core features
- **Minimal overhead** — don't slow down what you're measuring
- **Composable** — decorators, context managers, CLI — mix and match
- **Report anywhere** — terminal, JSON, HTML, or pipe to your own tools

---

## v0.1.0 — Foundation (current)

The core profiling engine with three measurement modes.

- [x] `@profile` decorator — cProfile-backed function profiling
- [x] `timer()` context manager — block-level timing
- [x] `@memprof` decorator — memory allocation tracking via tracemalloc
- [x] `trace()` context manager — call tree capture with timing
- [x] Console reporter — text and JSON output
- [x] CLI — `sondeo run script.py`
- [x] Result collection and clearing API

---

## v0.2.0 — Structured Logging

Unified log collection that captures both profiling data and application logs in a single timeline.

- [x] `@log` decorator — capture function entry/exit with args and return values
- [x] `sondeo.log()` — drop-in logger that feeds into the profiling timeline
- [x] Log levels (debug, info, warn, error) with colored terminal output
- [x] Correlation IDs — link logs to profiled function calls
- [x] Log filters — include/exclude by module, level, or pattern
- [x] Timeline view — interleaved logs and profiling data in chronological order

---

## v0.3.0 — Rich Reports + Cacao UI Dashboard

Visual output for terminal, browser, and CI. The interactive dashboard is powered by [Cacao](https://github.com/jhd3197/Cacao) as an optional `sondeo[ui]` extra — sondeo stays zero-dependency by default.

### Terminal (optional `sondeo[rich]` extra)
- [ ] Colored tables, progress bars, sparklines
- [ ] Tree view for call traces

### Interactive Dashboard (optional `sondeo[ui]` extra)
- [ ] `sondeo.reporter.ui` module — Cacao-based dashboard renderer
- [ ] `serve_report()` — one-call function that opens a live dashboard in the browser
- [ ] `sondeo run app.py --report ui` — CLI flag to open dashboard after profiling
- [ ] **Timing panel** — sortable table with function name, elapsed, calls, avg per call
- [ ] **Memory panel** — peak/current/allocated with top allocation lines per function
- [ ] **Call tree panel** — collapsible, color-coded trace tree (green/yellow/red by timing)
- [ ] **Flamegraph** — horizontal stacked bar chart using Cacao's chart components
- [ ] **Timeline view** — interleaved logs + profiling events in chronological order
- [ ] **Summary metrics** — total time, peak memory, slowest function, deepest call stack
- [ ] Dark/light theme support (inherits from Cacao)
- [ ] Export from dashboard — download report as JSON or static HTML snapshot

### CI / Automation
- [ ] Markdown report output for CI/CD pipelines
- [ ] `sondeo report` CLI command — generate reports from saved data

```python
# Programmatic usage
from sondeo import profile, memprof
from sondeo.reporter.ui import serve_report

@profile
def process():
    ...

@memprof
def allocate():
    ...

process()
allocate()
serve_report()  # opens Cacao dashboard on localhost:8000
```

```bash
# CLI usage
sondeo run app.py --report ui
```

---

## v0.4.0 — Async & Concurrency

First-class support for async code and threading.

- [x] `@profile` works on `async def` functions
- [x] `async with timer()` variant
- [x] Thread-aware profiling — per-thread timing and call trees
- [x] asyncio task tracking — see which coroutines are slow
- [x] Deadlock and contention detection hints

---

## v0.5.0 — Comparative Profiling

Compare performance across runs to catch regressions.

- [ ] `sondeo save` — persist profiling results to `.sondeo/` directory
- [ ] `sondeo diff` — compare two runs side-by-side
- [ ] Regression detection — flag functions that got slower
- [ ] Baseline management — set and compare against baselines
- [ ] CI integration — exit with non-zero if regressions detected
- [ ] JSON diff output for automated pipelines

---

## v0.6.0 — Live Monitoring

Real-time profiling for long-running processes.

- [ ] `sondeo attach <pid>` — attach to a running Python process
- [ ] Live stats streaming to terminal
- [ ] Periodic snapshots — profile at intervals without stopping
- [ ] Memory leak detection — track allocation growth over time

---

## v0.7.0 — Instrumentation API

Programmatic control for embedding sondeo in other tools.

- [ ] `Profiler` class — start/stop/snapshot API
- [ ] Event hooks — on_profile_complete, on_memory_spike, on_slow_call
- [ ] Export formats — pstats, speedscope JSON, Chrome trace format
- [ ] Plugin system — custom reporters, custom collectors
- [ ] Python API for CI integration (`sondeo.compare(baseline, current)`)

---

## v1.0.0 — Stable Release

Production-ready with comprehensive docs.

- [ ] Complete API documentation
- [ ] Cookbook with common profiling patterns
- [ ] Performance guarantees — documented overhead per feature
- [ ] Stable public API with semantic versioning
- [ ] PyPI release with all extras tested

---

## Future Ideas (post v1.0)

These are possibilities, not commitments. Driven by real usage.

- **cacao-sondeo plugin** — Cacao plugin (via `PluginRegistry`) that injects a profiling panel into any Cacao app's sidebar — live profiling without leaving your app
- **GPU profiling** — CUDA/Metal timing for ML workloads
- **Network profiling** — track HTTP request timing
- **Database query profiling** — capture SQL execution time
- **Distributed tracing** — OpenTelemetry-compatible spans
- **VS Code extension** — inline profiling annotations in the editor
- **Jupyter integration** — `%%sondeo` cell magic

---

## Contributing

This project is part of the [cacao-research](https://github.com/cacao-research) organization. Open issues for feature requests or bugs.
