pyclairvoyant 1.0.0

Predict where your Python code will crash — before it does

🔮 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:

Line 42 → 72.3% Crash Probability

---

🏃 Dynamic Runtime Tracing

Run your application and collect execution coverage:

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:

pip install pyclairvoyant

Verify installation:

pyclairvoyant --help

---

⚡ Quick Start

Analyze a Python file:

pyclairvoyant myapp.py

Analyze and trace execution:

pyclairvoyant myapp.py --run

Generate HTML report:

pyclairvoyant myapp.py -o report.html

Generate JSON report:

pyclairvoyant myapp.py -o report.json

---

🧠 How It Works

Step 1 — Parse

PyClairvoyant converts source code into an AST representation.

Python Source
      ↓
AST Tree

---

Step 2 — Detect Risks

The engine scans for dangerous coding patterns.

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.

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

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

Output

⚠ Line 2

Risk Category:
None Safety

Crash Probability:
72%

Suggestion:
Add a None check before accessing user.

---

🏗 Example Workflow

# 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:

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

cd pyclairvoyant

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest

---

📦 Building & Publishing

Build package:

python -m build

Upload to PyPI:

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.