bannin 0.1.0__tar.gz

bannin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bannin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bannin-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: bannin
+Version: 0.1.0
+Summary: Universal monitoring platform — watch your machines, LLMs, notebooks, and coding tools from your phone.
+Author: Bannin Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Lakshman-P4/Bannin.dev
+Project-URL: Issues, https://github.com/Lakshman-P4/Bannin.dev/issues
+Keywords: monitoring,system-metrics,llm,gpu,colab,kaggle,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: gpu
+Requires-Dist: pynvml>=11.5.0; extra == "gpu"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: pynvml>=11.5.0; extra == "all"
+Requires-Dist: mcp>=1.2.0; extra == "all"
+Dynamic: license-file
+
+# Bannin
+
+**番人** (Japanese for "watchman") — a universal monitoring agent for your machine, your LLMs, and your cloud notebooks.
+
+*You hit run. You walk away. Then what?*
+
+---
+
+## What It Does
+
+Bannin runs on your machine (or inside a cloud notebook) and monitors everything: CPU, RAM, GPU, disk, running processes, LLM conversation health, API usage, and cloud session health. It predicts out-of-memory crashes before they happen, scores your AI conversation quality, fires smart alerts, and gives you plain-English summaries of how your system is doing.
+
+It also works as an **MCP server** — meaning AI coding tools (Claude Code, Cursor, Windsurf) can query your system health through natural conversation.
+
+## Install
+
+```bash
+pip install bannin
+```
+
+With GPU monitoring and MCP server support:
+
+```bash
+pip install "bannin[all]"
+```
+
+## Quick Start
+
+**Start the agent:**
+
+```bash
+bannin start
+```
+
+**Open the dashboard:**
+
+Visit [localhost:8420](http://localhost:8420) in your browser.
+
+**Use with Claude Code (MCP):**
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bannin": {
+      "command": "python",
+      "args": ["-m", "bannin.mcp"]
+    }
+  }
+}
+```
+
+Then ask Claude things like:
+- "How's my system doing?"
+- "What processes are using the most memory?"
+- "Am I going to run out of RAM?"
+- "How healthy is this conversation?"
+
+## Features
+
+### System Monitoring
+- CPU, RAM, disk, network -- real-time with 30-minute history
+- GPU monitoring (NVIDIA via pynvml)
+- Top processes by resource usage with friendly names and category badges
+- Process descriptions and tooltips for 97 common applications
+- Plain-English system health summaries
+
+### Intelligence
+- OOM (out-of-memory) prediction with confidence scores and time-to-crash estimates
+- Smart alerts with cooldowns (17+ configurable rules)
+- Training progress detection (tqdm interception, stdout parsing)
+- ETA estimation for long-running tasks
+- L2 recommendations -- actionable suggestions from cross-signal analysis (12 rules)
+- Built-in chatbot for natural language system health queries
+
+### LLM Health Monitoring
+- Conversation health scoring (7 signals, 0-100 score) across Claude Code, Cursor, Windsurf, Ollama
+- Real Claude Code session data via JSONL transcript reading (actual token counts)
+- MCP session tracking with fatigue scoring and token estimation
+- Ollama local LLM monitoring -- auto-detect, VRAM tracking, model load/unload
+- LLM connection scanner -- detects 9 AI tool types running on your system
+- Per-source health breakdown with combined worst-of scoring
+
+### LLM API Tracking
+- Wrap OpenAI, Anthropic, and Google API clients to track token usage and cost
+- Context window exhaustion prediction
+- Latency degradation detection
+- Cost calculation across 30+ models and 7 providers
+
+### Cloud Notebooks
+- Google Colab: session time, GPU type changes, VRAM, storage, tier detection
+- Kaggle: GPU quota tracking, session limits, output size, internet detection
+
+### Persistent Analytics
+- Event pipeline with SQLite + FTS5 full-text search
+- Query history by type, severity, or keyword
+- 30-day retention with automatic pruning
+- Separate analytics dashboard at port 8421
+
+### MCP Server (9 Tools)
+- `get_system_metrics` -- full system snapshot (CPU, RAM, disk, network, GPU)
+- `get_running_processes` -- top processes by CPU/memory with friendly names
+- `predict_oom` -- memory exhaustion prediction with confidence
+- `get_training_status` -- tracked task progress and ETAs
+- `get_active_alerts` -- current monitoring alerts
+- `check_context_health` -- conversation health score with component breakdown
+- `get_recommendations` -- L2 actionable recommendations
+- `query_history` -- search analytics event history
+- `search_events` -- full-text search across stored events
+
+### Live Dashboard
+- Real-time metrics with color-coded gauges (cyan/amber/red)
+- Visual urgency indicators (amber glow at 60%, red pulse at 80%+)
+- Conversation health accordion with per-source breakdown
+- Connection badges for auto-detected LLM tools
+- Memory trend chart (5-minute rolling)
+- Process table with friendly names and hover tooltips
+- OOM prediction display
+- Alert banner with severity indicators
+- Built-in chatbot ("Ask Bannin") with 15 intents
+- Loading eye animation
+
+## API
+
+The agent exposes a local REST API at `localhost:8420`:
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/health` | GET | Agent alive check |
+| `/status` | GET | Agent identity (hostname, OS, version, uptime) |
+| `/metrics` | GET | Full system snapshot (CPU, RAM, disk, network, GPU) |
+| `/processes` | GET | Top processes with friendly names and categories |
+| `/summary` | GET | Plain-English system health summary |
+| `/chat` | POST | Chatbot (natural language system health assistant) |
+| `/alerts` | GET | Full alert history for this session |
+| `/alerts/active` | GET | Currently active alerts |
+| `/predictions/oom` | GET | OOM prediction with confidence |
+| `/history/memory` | GET | Memory usage history over last N minutes |
+| `/tasks` | GET | Tracked tasks (training progress, ETAs) |
+| `/recommendations` | GET | L2 actionable recommendations |
+| `/llm/usage` | GET | LLM session health and usage summary |
+| `/llm/calls` | GET | Recent LLM API call history |
+| `/llm/health` | GET | Unified conversation health score (combined + per-source) |
+| `/llm/context` | GET | Context window exhaustion prediction |
+| `/llm/latency` | GET | Response latency trend analysis |
+| `/llm/connections` | GET | Auto-detected LLM tools running on system |
+| `/ollama` | GET | Ollama local LLM status and loaded models |
+| `/mcp/session` | POST | Receive MCP session health push |
+| `/mcp/sessions` | GET | List all live MCP sessions |
+| `/analytics/stats` | GET | Analytics store statistics |
+| `/analytics/events` | GET | Query stored events with filters |
+| `/analytics/search` | GET | Full-text search across events |
+| `/analytics/timeline` | GET | Event timeline |
+| `/platform` | GET | Cloud notebook platform info (Colab/Kaggle) |
+| `/stream` | GET | Server-Sent Events for live dashboard updates |
+
+## Python API
+
+```python
+import bannin
+
+# Monitor system during a block of code
+with bannin.watch():
+    train_model()
+
+# Wrap an LLM client to track tokens and cost
+import openai
+client = bannin.wrap(openai.OpenAI())
+
+# Track a specific scope
+with bannin.track("my-experiment"):
+    response = client.chat.completions.create(...)
+```
+
+## CLI
+
+```bash
+bannin start                    # Start the agent (dashboard at localhost:8420)
+bannin start --port 9000        # Start on a custom port
+bannin mcp                      # Start the MCP server (stdio transport)
+bannin analytics                # Start the analytics dashboard (port 8421)
+bannin history                  # Query stored event history
+bannin history --since 2h       # Events from the last 2 hours
+bannin history --search "OOM"   # Full-text search
+bannin history --json           # Raw JSON output
+```
+
+## What's Coming
+
+- Phone alerts (push notifications when tasks finish or systems need attention)
+- Browser extension for ChatGPT, Claude.ai, and Gemini monitoring
+- Context transfer -- carry conversation state to a fresh chat when health degrades
+- macOS Apple Silicon GPU support
+- Shareable dashboards via bannin.dev
+
+## Requirements
+
+- Python 3.9+
+- Works on Windows, macOS, and Linux
+
+## License
+
+[MIT](LICENSE)

bannin-0.1.0/README.md

@@ -0,0 +1,204 @@
+# Bannin
+
+**番人** (Japanese for "watchman") — a universal monitoring agent for your machine, your LLMs, and your cloud notebooks.
+
+*You hit run. You walk away. Then what?*
+
+---
+
+## What It Does
+
+Bannin runs on your machine (or inside a cloud notebook) and monitors everything: CPU, RAM, GPU, disk, running processes, LLM conversation health, API usage, and cloud session health. It predicts out-of-memory crashes before they happen, scores your AI conversation quality, fires smart alerts, and gives you plain-English summaries of how your system is doing.
+
+It also works as an **MCP server** — meaning AI coding tools (Claude Code, Cursor, Windsurf) can query your system health through natural conversation.
+
+## Install
+
+```bash
+pip install bannin
+```
+
+With GPU monitoring and MCP server support:
+
+```bash
+pip install "bannin[all]"
+```
+
+## Quick Start
+
+**Start the agent:**
+
+```bash
+bannin start
+```
+
+**Open the dashboard:**
+
+Visit [localhost:8420](http://localhost:8420) in your browser.
+
+**Use with Claude Code (MCP):**
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bannin": {
+      "command": "python",
+      "args": ["-m", "bannin.mcp"]
+    }
+  }
+}
+```
+
+Then ask Claude things like:
+- "How's my system doing?"
+- "What processes are using the most memory?"
+- "Am I going to run out of RAM?"
+- "How healthy is this conversation?"
+
+## Features
+
+### System Monitoring
+- CPU, RAM, disk, network -- real-time with 30-minute history
+- GPU monitoring (NVIDIA via pynvml)
+- Top processes by resource usage with friendly names and category badges
+- Process descriptions and tooltips for 97 common applications
+- Plain-English system health summaries
+
+### Intelligence
+- OOM (out-of-memory) prediction with confidence scores and time-to-crash estimates
+- Smart alerts with cooldowns (17+ configurable rules)
+- Training progress detection (tqdm interception, stdout parsing)
+- ETA estimation for long-running tasks
+- L2 recommendations -- actionable suggestions from cross-signal analysis (12 rules)
+- Built-in chatbot for natural language system health queries
+
+### LLM Health Monitoring
+- Conversation health scoring (7 signals, 0-100 score) across Claude Code, Cursor, Windsurf, Ollama
+- Real Claude Code session data via JSONL transcript reading (actual token counts)
+- MCP session tracking with fatigue scoring and token estimation
+- Ollama local LLM monitoring -- auto-detect, VRAM tracking, model load/unload
+- LLM connection scanner -- detects 9 AI tool types running on your system
+- Per-source health breakdown with combined worst-of scoring
+
+### LLM API Tracking
+- Wrap OpenAI, Anthropic, and Google API clients to track token usage and cost
+- Context window exhaustion prediction
+- Latency degradation detection
+- Cost calculation across 30+ models and 7 providers
+
+### Cloud Notebooks
+- Google Colab: session time, GPU type changes, VRAM, storage, tier detection
+- Kaggle: GPU quota tracking, session limits, output size, internet detection
+
+### Persistent Analytics
+- Event pipeline with SQLite + FTS5 full-text search
+- Query history by type, severity, or keyword
+- 30-day retention with automatic pruning
+- Separate analytics dashboard at port 8421
+
+### MCP Server (9 Tools)
+- `get_system_metrics` -- full system snapshot (CPU, RAM, disk, network, GPU)
+- `get_running_processes` -- top processes by CPU/memory with friendly names
+- `predict_oom` -- memory exhaustion prediction with confidence
+- `get_training_status` -- tracked task progress and ETAs
+- `get_active_alerts` -- current monitoring alerts
+- `check_context_health` -- conversation health score with component breakdown
+- `get_recommendations` -- L2 actionable recommendations
+- `query_history` -- search analytics event history
+- `search_events` -- full-text search across stored events
+
+### Live Dashboard
+- Real-time metrics with color-coded gauges (cyan/amber/red)
+- Visual urgency indicators (amber glow at 60%, red pulse at 80%+)
+- Conversation health accordion with per-source breakdown
+- Connection badges for auto-detected LLM tools
+- Memory trend chart (5-minute rolling)
+- Process table with friendly names and hover tooltips
+- OOM prediction display
+- Alert banner with severity indicators
+- Built-in chatbot ("Ask Bannin") with 15 intents
+- Loading eye animation
+
+## API
+
+The agent exposes a local REST API at `localhost:8420`:
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/health` | GET | Agent alive check |
+| `/status` | GET | Agent identity (hostname, OS, version, uptime) |
+| `/metrics` | GET | Full system snapshot (CPU, RAM, disk, network, GPU) |
+| `/processes` | GET | Top processes with friendly names and categories |
+| `/summary` | GET | Plain-English system health summary |
+| `/chat` | POST | Chatbot (natural language system health assistant) |
+| `/alerts` | GET | Full alert history for this session |
+| `/alerts/active` | GET | Currently active alerts |
+| `/predictions/oom` | GET | OOM prediction with confidence |
+| `/history/memory` | GET | Memory usage history over last N minutes |
+| `/tasks` | GET | Tracked tasks (training progress, ETAs) |
+| `/recommendations` | GET | L2 actionable recommendations |
+| `/llm/usage` | GET | LLM session health and usage summary |
+| `/llm/calls` | GET | Recent LLM API call history |
+| `/llm/health` | GET | Unified conversation health score (combined + per-source) |
+| `/llm/context` | GET | Context window exhaustion prediction |
+| `/llm/latency` | GET | Response latency trend analysis |
+| `/llm/connections` | GET | Auto-detected LLM tools running on system |
+| `/ollama` | GET | Ollama local LLM status and loaded models |
+| `/mcp/session` | POST | Receive MCP session health push |
+| `/mcp/sessions` | GET | List all live MCP sessions |
+| `/analytics/stats` | GET | Analytics store statistics |
+| `/analytics/events` | GET | Query stored events with filters |
+| `/analytics/search` | GET | Full-text search across events |
+| `/analytics/timeline` | GET | Event timeline |
+| `/platform` | GET | Cloud notebook platform info (Colab/Kaggle) |
+| `/stream` | GET | Server-Sent Events for live dashboard updates |
+
+## Python API
+
+```python
+import bannin
+
+# Monitor system during a block of code
+with bannin.watch():
+    train_model()
+
+# Wrap an LLM client to track tokens and cost
+import openai
+client = bannin.wrap(openai.OpenAI())
+
+# Track a specific scope
+with bannin.track("my-experiment"):
+    response = client.chat.completions.create(...)
+```
+
+## CLI
+
+```bash
+bannin start                    # Start the agent (dashboard at localhost:8420)
+bannin start --port 9000        # Start on a custom port
+bannin mcp                      # Start the MCP server (stdio transport)
+bannin analytics                # Start the analytics dashboard (port 8421)
+bannin history                  # Query stored event history
+bannin history --since 2h       # Events from the last 2 hours
+bannin history --search "OOM"   # Full-text search
+bannin history --json           # Raw JSON output
+```
+
+## What's Coming
+
+- Phone alerts (push notifications when tasks finish or systems need attention)
+- Browser extension for ChatGPT, Claude.ai, and Gemini monitoring
+- Context transfer -- carry conversation state to a fresh chat when health degrades
+- macOS Apple Silicon GPU support
+- Shareable dashboards via bannin.dev
+
+## Requirements
+
+- Python 3.9+
+- Works on Windows, macOS, and Linux
+
+## License
+
+[MIT](LICENSE)

bannin-0.1.0/bannin/__init__.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+import threading
+from types import TracebackType
+
+from bannin.core.collector import get_all_metrics
+from bannin.llm.wrapper import wrap
+from bannin.llm.tracker import track
+
+
+class Bannin:
+    """Main Bannin agent — collects metrics and exposes API."""
+
+    def __init__(self, port: int = 8420) -> None:
+        self._port = port
+        self._server_thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self._running = False
+
+    def start(self) -> None:
+        """Start the agent API server in a background thread."""
+        import uvicorn
+        from bannin.api import app
+
+        with self._lock:
+            if self._running:
+                return
+            self._running = True
+            self._server_thread = threading.Thread(
+                target=uvicorn.run,
+                kwargs={"app": app, "host": "127.0.0.1", "port": self._port, "log_level": "warning"},
+                daemon=True,
+            )
+            self._server_thread.start()
+
+    def stop(self) -> None:
+        """Mark the agent as stopped. The daemon thread exits with the process."""
+        with self._lock:
+            self._running = False
+            self._server_thread = None
+
+    def metrics(self) -> dict:
+        """Get a snapshot of current system metrics."""
+        from bannin.core.gpu import get_gpu_metrics
+        data = get_all_metrics()
+        data["gpu"] = get_gpu_metrics()
+        return data
+
+
+def progress(name: str, current: int, total: int | None = None, *, port: int = 8420) -> None:
+    """Report training progress to the running Bannin agent.
+
+    Call this from any script to push progress to the dashboard without
+    needing bannin.watch(). The CLI agent must be running separately.
+    Silently ignores network failures (agent not running, connection refused).
+    Raises ValueError for obviously invalid inputs.
+
+    The HTTP POST has a 2-second timeout. For tight training loops, consider
+    calling every N iterations rather than every single step.
+
+    Usage:
+        import bannin
+        for epoch in range(1, 11):
+            train_epoch()
+            bannin.progress("Training GPT", current=epoch, total=10)
+    """
+    if not name or not isinstance(name, str):
+        raise ValueError("name must be a non-empty string")
+    if not isinstance(current, int) or current < 0:
+        raise ValueError("current must be a non-negative integer")
+    if total is not None and (not isinstance(total, int) or total < 1):
+        raise ValueError("total must be a positive integer or None")
+
+    import json
+    import os
+    import urllib.request
+
+    payload = json.dumps({
+        "name": name,
+        "current": current,
+        "total": total,
+        "pid": os.getpid(),
+    }).encode()
+
+    try:
+        req = urllib.request.Request(
+            f"http://127.0.0.1:{port}/tasks",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=2)
+    except Exception:
+        # Fire-and-forget: agent may not be running. No logging here because
+        # this function is called from user scripts that may not have bannin
+        # logging configured. The agent-side POST /tasks endpoint logs errors.
+        pass
+
+
+class watch:
+    """Context manager that runs the Bannin agent during a block of code.
+
+    Usage:
+        with bannin.watch():
+            train_model()
+    """
+
+    def __init__(self, port: int = 8420) -> None:
+        self._agent = Bannin(port=port)
+
+    def __enter__(self) -> Bannin:
+        self._agent.start()
+        self._history = None
+        self._progress = None
+        try:
+            from bannin.intelligence.history import MetricHistory
+            self._history = MetricHistory.get()
+            self._history.start()
+            from bannin.intelligence.progress import ProgressTracker
+            self._progress = ProgressTracker.get()
+            self._progress.hook_all()
+        except Exception:
+            if self._progress is not None:
+                self._progress.unhook_all()
+            if self._history is not None:
+                self._history.stop()
+            self._agent.stop()
+            raise
+        return self._agent
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> bool:
+        if self._progress is not None:
+            self._progress.unhook_all()
+        if self._history is not None:
+            self._history.stop()
+        self._agent.stop()
+        return False

bannin-0.1.0/bannin/analytics/__init__.py

@@ -0,0 +1,3 @@
+"""Bannin analytics -- persistent event storage and querying."""
+
+from __future__ import annotations