Metadata-Version: 2.4
Name: aidbg
Version: 0.1.2
Summary: Local-first CLI AI debugger for Python projects
Author-email: Kumar Nihal <nihalpandey1205@email.com>
License: MIT License
        
        Copyright (c) 2026 Kumar Nihal
        
        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/KNIHAL/aidbg
Project-URL: Repository, https://github.com/KNIHAL/aidbg
Project-URL: Issues, https://github.com/KNIHAL/aidbg/issues
Keywords: ai debugger,python debugger,llm debugging,cli tool,local-first ai,traceback analyzer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: ollama
Requires-Dist: requests>=2.31.0; extra == "ollama"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Dynamic: license-file

# AI Debugger - aidbg

**aidbg** is a local-first, CLI-based AI debugging tool for Python projects.

It wraps program execution, detects runtime failures, collects minimal diagnostic context, and returns a structured debugging explanation using an LLM — without running background processes or monitoring your system.

aidbg activates only when your program crashes, analyzes the error, prints a concise fix, and exits immediately.

---

## ✨ Why aidbg?

Modern developers often copy-paste tracebacks into AI chat tools to debug errors.

aidbg removes that friction.

Instead of:
```bash
python app.py
# copy error
# open browser
# paste into AI
```

You do:
```bash
aidbg run app.py
```

And get:

- Root Cause
- Fix
- Short Explanation

All inside your terminal.

----

### 🔍 Key Features

- CLI-based execution wrapper
- Event-driven (no background daemon)
- Zero idle CPU usage
- Minimal context collection
- Token-controlled LLM responses
- Guardrails against unsafe or hacky fixes
- Multi-provider support:
    - Groq
    - OpenAI
    - Ollama (local)

- Global and project-level configuration
- Fully open-source core

---

### 🧠 How It Works

Execution Flow:

```lua
aidbg run app.py
  → executes script
  → detects crash (non-zero exit)
  → extracts traceback
  → collects minimal context
  → sends structured prompt to LLM
  → prints debugging result
  → exits
```

**aidbg never:**

- Runs continuously
- Monitors your system
- Sends your full repository
- Collects environment variables
- Reads .env files
- Uploads datasets

---

#### 📦 Installation

```bash
pip install aidbg
```

**Or from source:**

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

#### ⚙️ Configuration

**Initialize configuration:**

```bash
aidbg init
```

**Project-specific config:**

```bash
aidbg init --local
```

**Config priority:**

1. Project config (.aidbg/config.json)

2. Global config (~/.aidbg/config.json)


---

#### 🛠 Usage

```bash
aidbg run app.py
```

**Example output:**

```vbnet
Root Cause:
Division by zero.

Fix:
Validate the divisor before performing the division.

Explanation:
Python raises ZeroDivisionError when the divisor is zero.
```
----

#### 🔐 Privacy Model

aidbg follows a minimal context principle.

**Collected:**

- Relevant traceback frames
- Failing file + line number
- Code snippet around failure
- Shallow project structure (depth ≤ 2)
- Python version
- OS
- requirements.txt (if present)

**Never collected:**

- Full repository
- Secrets
- Environment variables
- Binary files
- Historical logs

---

#### 🧩 Project Structure

```yaml
aidbg/
│
├─ cli.py
│   Entry point for CLI commands.
│
├─ runner.py
│   Executes target Python script via subprocess.
│
├─ trigger.py
│   Crash detection and LLM orchestration logic.
│
├─ init.py
│   Interactive configuration (global / project).
│
├─ config.py
│   Configuration loading and priority resolution.
│
├─ prompt.py
│   LLM system and user prompt construction.
│
├─ logic/
│   ├─ complexity.py
│   │   Error classification (simple vs complex).
│   └─ token_budget.py
│       Fixed token budget logic.
│
├─ context/
│   ├─ collector.py
│   │   Traceback parsing and file extraction.
│   ├─ project_tree.py
│   │   Shallow project structure extraction.
│   ├─ environment.py
│   │   Python version and OS detection.
│   └─ dependencies.py
│       Lightweight dependency parsing.
│
├─ llm/
│   ├─ base.py
│   ├─ groq.py
│   ├─ openai.py
│   └─ ollama.py
│
└─ tests/
    Basic unit tests for stability.
```

----

#### 🧪 Testing
```bash
pytest
```

----


#### 📈 Roadmap

**Phase 1 (Current):**

- CLI tool
- Multi-provider support
- Token-controlled responses
- Guarded fix suggestions

**Phase 2 (Planned):**

- Specialized lightweight debugging model
- Optional hosted API
- Possible commercial extension
- The core CLI tool will remain open-source.

---

### 📄 License

MIT License.

The open-source CLI tool is released under MIT.
Future hosted APIs or proprietary debugging models may be released under separate commercial terms.

---

### 🤝 Contributing

Pull requests welcome.
Please keep contributions minimal, testable, and consistent with the local-first philosophy.
