Metadata-Version: 2.4
Name: syslens
Version: 1.0.1
Summary: A lightweight observability, diagnostics, and anomaly detection platform for developer environments
Author-email: Sahan Pramuditha <sahan.dev.tech@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Sahan Pramuditha
        
        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.
        
Project-URL: Homepage, https://github.com/SahanPramuditha-Dev/Syslens
Project-URL: Documentation, https://github.com/SahanPramuditha-Dev/Syslens#readme
Project-URL: Repository, https://github.com/SahanPramuditha-Dev/Syslens
Project-URL: Changelog, https://github.com/SahanPramuditha-Dev/Syslens/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/SahanPramuditha-Dev/Syslens/issues
Keywords: system,monitoring,telemetry,diagnostics,anomaly-detection,observability,performance,cli,dashboard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100.0; extra == "dashboard"
Requires-Dist: uvicorn>=0.22.0; extra == "dashboard"
Requires-Dist: websockets>=11.0; extra == "dashboard"
Provides-Extra: full
Requires-Dist: syslens[dashboard]; extra == "full"
Provides-Extra: dev
Requires-Dist: syslens[dashboard]; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.23.0; extra == "dev"
Dynamic: license-file

# 🧠 SysLens

**SysLens** is a lightweight, local-first system telemetry intelligence and observability platform designed for developers. It combines low-overhead metrics collection with a behavioral anomaly engine, actionable troubleshooting diagnostics, a modular plugin system, and dual frontend options (a dark-glass web dashboard and a premium terminal interface).

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)

---

## ✨ Features

- **📊 Comprehensive Telemetry**: Real-time tracking of CPU utilization, logical core frequencies, virtual memory state, disk partition IO, system uptime, and top resource-hogging processes.
- **📈 Rolling Behavioral Baselines**: Learns system behavior patterns dynamically. Calculates rolling means and standard deviations locally to detect subtle deviations without external DBs.
- **⚠ Z-Score Anomaly Engine**: Identifies CPU, memory, and disk IO spikes, categorizes severity (`LOW`, `MEDIUM`, `HIGH`), and detects correlated bottlenecks (e.g. concurrent CPU and RAM stress).
- **🔌 Extensible Plugins**: Supports built-in plugins for Battery Health and GPU utilization, with runtime loading for custom external scripts.
- **🖥️ Premium CLI Toolkit**:
  - `syslens scan` - Side-by-side terminal dashboard pane.
  - `syslens health` - Quick diagnostic checklist and score (`0-100`).
  - `syslens live` - Real-time btop-inspired terminal stream.
- **glassmorphic Web UI**: Stunning dark-glass design running on a FastAPI + WebSocket backend with live Chart.js animations.

---

## 🚀 Quick Start

### Installation

Install dependencies and run SysLens in editable mode:

```bash
# Clone the repository
git clone https://github.com/SahanPramuditha-Dev/Syslens.git
cd Syslens

# Install core library + CLI
pip install -e .

# Install with the web dashboard (FastAPI + WebSocket)
pip install -e .[dashboard]
```

### CLI Command Reference

SysLens packages itself into two console command scripts (`syslens` and `syslensd`):

| Command | Action |
|:---|:---|
| `syslens scan` | Fetch a structured, double-column telemetry summary. |
| `syslens scan --json` | Output system snapshot as a clean JSON structure. |
| `syslens health` | Execute diagnostics, check anomalies, and view recommendations. |
| `syslens live` | Run the real-time split-pane terminal dashboard stream. |
| `syslens serve` / `syslensd` | Launch the FastAPI local server (default: `http://127.0.0.1:8000`). |
| `syslens export` | Export the current snapshot to a glassmorphism HTML report. |

---

## 🎨 Terminal Preview

### `syslens scan`
```text
--------------------- SYSLENS - ENTERPRISE TELEMETRY SCAN ---------------------

+------- ENVIRONMENT METADATA -------+  +--------- SYSTEM HEALTH KPI ---------+
|   * OS Platform : Windows 11       |  |                                     |
| (AMD64)                            |  |   Overall Rating : DEGRADED         |
|   * Hostname    : Dev-Station      |  |   Health Score   : 64.3 / 100       |
|   * Local IP    : 192.168.1.6      |  |   Status Gauge   :                  |
|   * Uptime      : 1h 42m 2s        |  | ##############-------- 64.3%        |
+------------------------------------+  +-------------------------------------+

+------- TELEMETRY STATISTICS -------+  +--------- TOP PROCESS HOGS ----------+
|  Resource   Meter       Details    |  |  PID    Name   CPU %      %  Status |
|  CPU        ##-------   16 Cores   |  |  7820   Code   0.0%  2.92%  running |
|             16.1%       @ 2400MHz  |  |  22448  Code   0.0%  2.88%  running |
|  Memory     #########   11.25 GB   |  |  13084  chrome 0.0%  2.78%  running |
+------------------------------------+  +-------------------------------------+
```

---

## 📦 Developer SDK Usage

SysLens can be directly embedded into your Python application or backend script.

### 0. Single top-level import (recommended)
```python
import syslens

metrics = syslens.get_system_info()
print(f"CPU: {metrics['cpu_usage']}%  |  Memory: {metrics['memory_usage']}%")

score = syslens.calculate_health(metrics)
print(f"Health score: {score:.1f}/100")
```

### 1. Library Telemetry Snapshot
```python
from syslens.core.system import get_system_info
from syslens.core.health import calculate_health

# Fetch raw metrics dict
metrics = get_system_info()
print(f"CPU usage: {metrics['cpu_usage']}%, Memory usage: {metrics['memory_usage']}%")

# Generate Health Score
score = calculate_health(metrics)
print(f"System Health Rating: {score}/100")
```

### 2. Runtime Anomaly Detection
```python
from syslens.engine.detector import AnomalyDetector

detector = AnomalyDetector()

# Periodic tick checks (returns any deviations matching the rolling baseline)
anomalies = detector.tick()
if anomalies:
    for anomaly in anomalies:
         print(f"[{anomaly['severity']}] {anomaly['metric']}: {anomaly['description']}")
```

---

## 🛠️ Repository Navigation

To learn more about SysLens, read the comprehensive guides in the repository:
- **[ARCHITECTURE.md](file:///c:/D/Projects/Python/Syslens/ARCHITECTURE.md)**: Explore the data flow, Mermaid architecture diagrams, and baseline Z-score formulas.
- **[TESTING.md](file:///c:/D/Projects/Python/Syslens/TESTING.md)**: Guidelines for running pytest, mocking hardware info, and reviewing code coverage.
- **[CONTRIBUTING.md](file:///c:/D/Projects/Python/Syslens/CONTRIBUTING.md)**: How to submit bug reports, pull requests, and code extensions.
- **[ROADMAP.md](file:///c:/D/Projects/Python/Syslens/ROADMAP.md)**: Development milestones and future goals.
- **[CHANGELOG.md](file:///c:/D/Projects/Python/Syslens/CHANGELOG.md)**: Detailed version history and release notes.

---

## 📜 License

Distributed under the MIT License. See [LICENSE](file:///c:/D/Projects/Python/Syslens/LICENSE) for more details.
