# 🚀 PyDSA Engine v0.2.0

<p align="center">
  <img src="https://img.shields.io/pypi/v/pydsa-engine" alt="PyPI Version">
  <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</p>

<p align="center">
  <b>A Semantic AI-Powered Data Structures & Algorithms Execution Engine</b>
</p>

<p align="center">
  Search. Execute. Trace. Benchmark. Learn.
</p>

---

# 🎉 What's New in v0.2.0

### 🏎️ Benchmark Engine

PyDSA Engine now includes a powerful benchmarking system.

Benchmark any supported algorithm directly from your terminal:

```bash
pydsa benchmark "two sum"
```

Get:

* Average Runtime
* Fastest Execution
* Slowest Execution
* Execution Statistics
* Performance Insights

Perfect for:

* Competitive Programmers
* Interview Preparation
* Performance Analysis
* DSA Learning

---

# 🌟 Overview

**PyDSA Engine** is a next-generation Data Structures & Algorithms execution environment built for developers, students, educators, researchers, and AI applications.

Instead of remembering exact problem names, simply describe what you're looking for and let the AI-powered routing engine find the correct algorithm instantly.

PyDSA Engine combines:

* AI Semantic Search
* Dynamic Execution
* Algorithm Benchmarking
* Visual Debugging
* FastAPI Integration
* Complexity Analysis

into a single developer-friendly package.

---

# ✨ Features

## 🧠 AI Semantic Search

Find algorithms using natural language.

Example:

```bash
pydsa search "water container"
```

Automatically finds:

```text
Container With Most Water
```

---

## ⚡ Dynamic Algorithm Execution

Execute algorithms directly from the terminal.

Supports:

* Arrays
* Strings
* Integers
* Matrices
* Graphs
* Trees

Example:

```bash
pydsa solve "two sum" "[2,7,11,15]" "9"
```

---

## 🔍 Visual X-Ray Tracer

Watch your algorithm execute line-by-line.

Example:

```bash
pydsa solve "two sum" "[2,7,11,15]" "9" --trace
```

Features:

* Variable Tracking
* Execution Flow
* Step-by-Step Debugging
* Educational Learning Mode

---

## 🏎️ Benchmark Engine

Benchmark algorithm performance instantly.

Example:

```bash
pydsa benchmark "two sum"
```

Sample Output:

```text
┌─────────────────────────────┐
│ Benchmark Results           │
├─────────────────────────────┤
│ Problem: Two Sum            │
│ Runs: 1000                  │
│ Avg Runtime: 0.000031 sec   │
│ Best Runtime: 0.000019 sec  │
│ Worst Runtime: 0.000064 sec │
└─────────────────────────────┘
```

Perfect for:

* Comparing solutions
* Optimization analysis
* Performance profiling
* Learning complexity behavior

---

## 📋 Clipboard Integration

Copy optimal solutions directly into your clipboard.

Example:

```bash
pydsa solve "two sum" --copy
```

Requirements:

```bash
pip install pyperclip
```

---

## 🌐 Built-in FastAPI Server

Turn PyDSA into a backend microservice instantly.

Powered by:

* FastAPI
* OpenAPI
* Swagger UI

---

## 📈 Complexity Analysis

Every execution automatically displays:

* Time Complexity
* Space Complexity
* Difficulty
* Category

---

## 📚 Massive Algorithm Database

Includes:

* 3900+ Problems
* LeetCode Problems
* Design Problems
* Graph Problems
* Dynamic Programming
* Trees
* Linked Lists
* Advanced Data Structures

---

# 📦 Installation

Install from PyPI:

```bash
pip install pydsa-engine
```

Verify Installation:

```bash
pydsa --help
```

---

# 💻 CLI Usage

## 1️⃣ Search Problems

Use natural language to find algorithms.

```bash
pydsa search "water container"
```

Example:

```text
Found:
Container With Most Water

Difficulty: Medium
Category: Two Pointers
```

---

## 2️⃣ View Source Code

Display the optimal implementation.

```bash
pydsa solve "max water" --show-code
```

---

## 3️⃣ Copy Source Code

Copy directly into your IDE.

```bash
pydsa solve "two sum" --copy
```

---

## 4️⃣ Execute Algorithms

Run algorithms with actual inputs.

```bash
pydsa solve "two sum" "[2,7,11,15]" "9"
```

Output:

```text
Result:
[0,1]

Time Complexity:
O(n)

Space Complexity:
O(n)
```

---

## 5️⃣ X-Ray Trace Execution

Visual debugging mode.

```bash
pydsa solve "two sum" "[2,7,11,15]" "9" --trace
```

Example:

```text
Line 12:
num = 2
target = 9

Line 13:
lookup = {2: 0}
```

---

## 6️⃣ Benchmark Algorithms

Analyze algorithm performance.

```bash
pydsa benchmark "two sum"
```

Other examples:

```bash
pydsa benchmark "container with most water"

pydsa benchmark "merge intervals"

pydsa benchmark "longest substring without repeating characters"
```

---

# 🌐 REST API Server

Launch FastAPI Server:

```bash
pydsa serve --port 8000
```

Server:

```text
http://127.0.0.1:8000
```

Swagger UI:

```text
http://127.0.0.1:8000/docs
```

Redoc:

```text
http://127.0.0.1:8000/redoc
```

---

## Example API Request

### Endpoint

```http
POST /solve
```

### Request

```json
{
  "query": "two sum",
  "inputs": [
    [2,7,11,15],
    9
  ],
  "trace": true
}
```

### Response

```json
{
  "result": [0,1],
  "time_complexity": "O(n)",
  "space_complexity": "O(n)"
}
```

---

# 📚 Supported Categories

Current Categories:

* Arrays
* Strings
* Linked Lists
* Trees
* Binary Trees
* Binary Search Trees
* Graphs
* Dynamic Programming
* Greedy Algorithms
* Backtracking
* Recursion
* Sliding Window
* Two Pointers
* Hash Tables
* Heaps
* Queues
* Stacks
* Tries
* Design Problems
* Math
* Bit Manipulation

and many more...

---

# 🏗 Architecture

```text
PyDSA Engine
│
├── CLI Interface
├── AI Semantic Search
├── Vector Search Engine
├── Dynamic Execution Engine
├── Visual X-Ray Tracer
├── Benchmark Engine
├── Clipboard Manager
├── FastAPI Server
├── Complexity Analyzer
└── Algorithm Database (3900+)
```

---

# 🛠 Development Setup

Clone Repository:

```bash
git clone https://github.com/Abhi112ss/pydsa.git
```

Move into Project:

```bash
cd pydsa
```

Install Editable Mode:

```bash
pip install -e .
```

Install Development Dependencies:

```bash
pip install pytest
```

---

# ✅ Testing

Run Tests:

```bash
pytest
```

Run Coverage:

```bash
pytest --cov=pydsa
```

---

# 🤝 Contributing

Contributions are welcome.

Ways to contribute:

* Add Algorithms
* Improve Documentation
* Improve Search Accuracy
* Add New CLI Features
* Optimize Benchmark Engine
* Improve Tracing System
* Performance Improvements

Workflow:

```bash
fork → feature branch → commit → pull request
```

---

# 🛣 Roadmap

## ✅ v0.2.0

* AI Semantic Search
* Dynamic Execution Engine
* Visual X-Ray Tracer
* Benchmark Engine
* FastAPI REST Server
* Clipboard Integration
* Complexity Analysis

## 🚀 Upcoming

* Visual Graph Explorer
* Interactive Tree Visualizer
* Algorithm Playground
* AI Tutor Mode
* LeetCode Sync
* Competitive Programming Assistant
* Web Dashboard
* Performance Charts

---

# 📄 License

Licensed under the MIT License.

```text
MIT License
```

See the LICENSE file for details.

---

<p align="center">
  Built with ❤️ for the Python & DSA Community
</p>

<p align="center">
  <b>PyDSA Engine — Search. Execute. Trace. Benchmark. Learn.</b>
</p>
