Metadata-Version: 2.4
Name: tcptune
Version: 2.0.0
Summary: Intelligent Linux network diagnostics and optimization platform.
Author-email: Jax <muxover@jax-development.com>
License: MIT
Project-URL: Repository, https://github.com/muxover/tcptune
Project-URL: Changelog, https://github.com/muxover/tcptune/blob/main/CHANGELOG.md
Keywords: linux,tcp,sysctl,networking,performance,cli,ebpf,diagnostics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.50
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.19; extra == "prometheus"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"

# TcpTune

<div align="center">

[![CI](https://github.com/muxover/tcptune/actions/workflows/ci.yml/badge.svg)](https://github.com/muxover/tcptune/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Intelligent Linux network diagnostics and optimization platform.**

</div>

---

TcpTune diagnoses your Linux TCP/network stack, explains what's wrong, and applies evidence-based sysctl tuning. Every recommendation includes the reason and the raw evidence behind it.

## Features

- Full network health scan with severity, confidence levels, and fix hints
- Adaptive sysctl recommendations based on RTT, BDP, and detected bottlenecks
- 8 diagnostic modules: retransmissions, bufferbloat, interface drops, MTU, congestion control, queue depth, latency jitter, memory pressure
- 6 workload profiles: gaming, streaming, WAN, API server, proxy, homelab
- Live textual TUI dashboard with sparklines and findings list
- Prometheus `/metrics` endpoint
- Tuning history with automatic rollback if score drops
- JSON and HTML reports
- Dry-run, diff, and sysctl.d drop-in file workflows
- Automation-friendly exit codes

## Installation

```bash
pip install tcptune
```

With Prometheus support:

```bash
pip install 'tcptune[prometheus]'
```

## Quick Start

```bash
# Diagnose the system
tcptune diag run

# See what would change
tcptune tune preview

# Apply with 5-minute auto-rollback if score drops
sudo tcptune tune apply --rollback-after 300

# Live dashboard
tcptune monitor dashboard

# Health score with exit code for automation
tcptune monitor score --exit-code
```

## Commands

### diag

| Command | Description |
|---|---|
| `tcptune diag run` | Full diagnostic scan |
| `tcptune diag run --json` | Machine-readable JSON output |
| `tcptune diag run --severity critical` | Filter by minimum severity |
| `tcptune diag explain <id>` | Full detail on one finding |
| `tcptune diag list` | List all diagnostic rule IDs |

### tune

| Command | Description |
|---|---|
| `tcptune tune preview` | Adaptive recommendations (dry view) |
| `tcptune tune preview --profile gaming` | Preview a workload profile |
| `tcptune tune preview --bandwidth 1Gbps --rtt 50ms` | BDP-based buffer preview |
| `sudo tcptune tune apply` | Apply adaptive recommendations |
| `sudo tcptune tune apply --preset throughput` | Apply a named preset |
| `sudo tcptune tune apply --profile proxy` | Apply a workload profile |
| `sudo tcptune tune apply --rollback-after 300` | Apply with auto-rollback after 5 min |
| `sudo tcptune tune rollback` | Restore last session |
| `tcptune tune history` | Show tuning log |

### monitor

| Command | Description |
|---|---|
| `tcptune monitor dashboard` | Live TUI dashboard |
| `tcptune monitor stream` | Line-delimited JSON stream (pipe-friendly) |
| `tcptune monitor score` | Print health score |
| `tcptune monitor score --exit-code` | Exit 0/1/2 by health grade |

### profile

| Command | Description |
|---|---|
| `tcptune profile list` | List available workload profiles |
| `tcptune profile show gaming` | Show what a profile sets |
| `sudo tcptune profile apply gaming` | Apply a profile |

### report

| Command | Description |
|---|---|
| `tcptune report json -o report.json` | JSON report |
| `tcptune report html -o report.html` | Self-contained HTML report |
| `tcptune report prometheus` | Start Prometheus `/metrics` HTTP server |

## Workload Profiles

| Profile | Best for |
|---|---|
| `gaming` | Low latency, minimal bufferbloat |
| `streaming` | High-throughput sustained transfers |
| `wan` | High-RTT WAN / satellite paths |
| `api-server` | Many short-lived HTTP connections |
| `proxy` | VPS / proxy / forwarding infrastructure |
| `homelab` | Balanced, conservative improvements |

## Project Layout

```
src/tcptune/
  cli/          Command groups (diag, tune, monitor, profile, report)
  core/         Snapshot, collector, analyzer, scorer, recommender
  collectors/   Data sources: procfs, sysctl, ss, tc, ethtool, ip
  diagnostics/  8 diagnostic modules with Finding dataclass
  tuning/       BDP math, presets, writer, history, rollback
  profiles/     6 workload profiles
  tui/          Textual TUI dashboard
  reporting/    JSON, HTML, Prometheus reporters
```

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | No critical findings / score >= 80 |
| `1` | Warnings present / score 50-79 |
| `2` | Critical findings / score < 50 |

## Automation

```bash
# CI health gate
tcptune monitor score --exit-code || echo "Network degraded"

# Pipe live metrics
tcptune monitor stream | jq .health_score

# Prometheus scrape target
tcptune report prometheus --port 9773 &
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

Licensed under [MIT](LICENSE).

## Links

- Repository: https://github.com/muxover/tcptune
- Issues: https://github.com/muxover/tcptune/issues
- Changelog: [CHANGELOG.md](CHANGELOG.md)

---

<p align="center">Made with ❤️ by Jax (@muxover)</p>
