Metadata-Version: 2.4
Name: pyclairvoyant
Version: 1.0.0
Summary: Predict where your Python code will crash — before it does
Project-URL: Homepage, https://github.com/mohammadrezamirtaleb/pyclairvoyant
Project-URL: Repository, https://github.com/mohammadrezamirtaleb/pyclairvoyant
Project-URL: Documentation, https://github.com/mohammadrezamirtaleb/pyclairvoyant
Author-email: Mohammad Reza Mirtaleb <mohammadrezamirtaleb@example.com>
License: MIT
License-File: LICENSE
Keywords: code-quality,crash-prediction,debugging,risk-analysis,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🔮 PyClairvoyant

**Find hidden failure points, estimate crash probability, and improve software reliability before deployment.**

---

# 🚀 Overview

**PyClairvoyant** is an intelligent Python code analysis framework that predicts where your application is most likely to fail.

Unlike traditional linters that simply flag code smells, PyClairvoyant combines:

* Static AST Analysis
* Runtime Execution Tracing
* Risk Scoring Models
* Crash Probability Estimation

to identify dangerous code paths and estimate the likelihood of runtime failures.

Think of it as a **risk radar for Python applications**.

---

# 🎯 Why PyClairvoyant?

Modern software systems often fail because of hidden runtime issues that pass traditional code reviews:

* Accessing `None` objects
* Division by zero
* Missing dictionary keys
* Unsafe file operations
* Untested execution paths
* SQL injection vulnerabilities
* Dangerous use of `eval()` and `exec()`

PyClairvoyant detects these issues and quantifies their risk level.

Instead of telling you:

> "This code might be problematic"

it tells you:

> "This line has a 72% probability of causing a runtime failure."

---

# ✨ Key Features

## 🔍 Advanced Static Analysis

Scans Python source code using the Abstract Syntax Tree (AST) and identifies high-risk patterns.

Detects:

* Unsafe None access
* Division by zero
* Unsafe indexing
* Direct dictionary access
* Broad exception handling
* SQL injection risks
* File I/O misuse
* Mutable default arguments
* Dangerous recursion
* eval/exec usage

---

## 📊 Crash Probability Estimation

Each suspicious line receives a calculated crash probability based on:

* Pattern severity
* Code complexity
* Nesting depth
* Runtime coverage
* Risk multipliers

Example:

```text
Line 42 → 72.3% Crash Probability
```

---

## 🏃 Dynamic Runtime Tracing

Run your application and collect execution coverage:

```bash
pyclairvoyant app.py --run
```

PyClairvoyant identifies:

* Executed code paths
* Untested branches
* Hidden failure zones

and adjusts risk calculations accordingly.

---

## 📈 Beautiful Reports

Generate reports in multiple formats:

### Terminal Output

Color-coded risk visualization.

### JSON Reports

Perfect for CI/CD pipelines.

### HTML Reports

Interactive and shareable dashboards.

---

# 📦 Installation

Install from PyPI:

```bash
pip install pyclairvoyant
```

Verify installation:

```bash
pyclairvoyant --help
```

---

# ⚡ Quick Start

Analyze a Python file:

```bash
pyclairvoyant myapp.py
```

Analyze and trace execution:

```bash
pyclairvoyant myapp.py --run
```

Generate HTML report:

```bash
pyclairvoyant myapp.py -o report.html
```

Generate JSON report:

```bash
pyclairvoyant myapp.py -o report.json
```

---

# 🧠 How It Works

## Step 1 — Parse

PyClairvoyant converts source code into an AST representation.

```text
Python Source
      ↓
AST Tree
```

---

## Step 2 — Detect Risks

The engine scans for dangerous coding patterns.

```text
AST
 ↓
Risk Detection Engine
 ↓
Findings
```

---

## Step 3 — Score Severity

Every finding receives a severity score.

Example:

| Pattern          | Severity |
| ---------------- | -------- |
| SQL Injection    | 10       |
| eval() Usage     | 10       |
| None Access      | 9        |
| Division by Zero | 9        |
| Unsafe Indexing  | 8        |
| Broad Except     | 6        |

---

## Step 4 — Estimate Failure Probability

Risk scores are converted into a crash probability model.

```text
Risk Factors
      +
Complexity
      +
Coverage
      ↓
Crash Probability
```

---

# 📋 Supported Detection Categories

| Category        | Examples                       |
| --------------- | ------------------------------ |
| 💥 None Safety  | Nullable access                |
| ➗ Arithmetic    | Division by zero               |
| 📏 Collections  | Invalid indexing               |
| 🔑 Dictionaries | Missing keys                   |
| 📁 File I/O     | Unsafe file handling           |
| 🌐 Network      | Unprotected requests           |
| 🎯 Exceptions   | Broad exception blocks         |
| 🗃️ SQL         | String-formatted queries       |
| 👃 Code Smells  | eval, exec                     |
| 🔄 Recursion    | Missing termination conditions |

---

# 📄 Example

### Input

```python
user = get_user("alice")
email = user["email"]
```

### Output

```text
⚠ Line 2

Risk Category:
None Safety

Crash Probability:
72%

Suggestion:
Add a None check before accessing user.
```

---

# 🏗 Example Workflow

```bash
# Analyze source code
pyclairvoyant app.py

# Run dynamic analysis
pyclairvoyant app.py --run

# Export HTML dashboard
pyclairvoyant app.py -o report.html
```

---

# 🔬 Use Cases

### Software Development

Find hidden bugs before deployment.

### DevOps

Integrate risk reports into CI/CD pipelines.

### Cybersecurity

Detect unsafe code constructs.

### Code Reviews

Prioritize high-risk findings.

### Education

Teach defensive programming practices.

---

# 🛠 Development

Clone repository:

```bash
git clone https://github.com/pyclairvoyant/pyclairvoyant.git

cd pyclairvoyant
```

Install development dependencies:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

---

# 📦 Building & Publishing

Build package:

```bash
python -m build
```

Upload to PyPI:

```bash
twine upload dist/*
```

---

# 🗺 Roadmap

Planned features:

* Machine Learning Risk Models
* VSCode Extension
* GitHub Actions Integration
* Historical Risk Tracking
* Team Dashboards
* Security-Focused Rulesets
* AI-Powered Fix Suggestions

---

# 🤝 Contributing

Contributions, issues, and feature requests are welcome.

If you'd like to improve PyClairvoyant:

1. Fork the repository
2. Create a feature branch
3. Commit changes
4. Submit a pull request

---

# 👨‍💻 Author

## Mohammad Reza Mirtaleb

MSC at Petroleum University of Technology, Abadan Faculty

AI Engineer | Machine Learning & Deep Learning Engineer | Data Scientist | NLP Expert (LLMs and VLMs) | RAG and Multi-Agent Systems Developer

Building intelligent solutions for real-world challenges.

---

# 🎯 Project Mission

PyClairvoyant was created with one simple goal:

> Help developers identify software failures before they happen.

By combining static analysis, runtime intelligence, and probabilistic risk estimation, PyClairvoyant aims to make Python applications safer, more reliable, and easier to maintain.

---

# 📜 License

MIT License

Copyright (c) 2026 Mohammad Reza Mirtaleb

Free to use, modify, and distribute.
