Metadata-Version: 2.4
Name: akdogan
Version: 1.1.0
Summary: Universal LLM-optimized project snapshot tool
Author: Berke Akdogan
License: MIT License
        
        Copyright (c) 2025 Berke AKDOGAN 
        
        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.
        
Keywords: llm,snapshot,ai,code-extractor,project-tree
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: openpyxl
Dynamic: license-file

# akdogan — Universal LLM-Optimized Project Snapshot Tool

[![PyPI version](https://img.shields.io/pypi/v/akdogan.svg)](https://pypi.org/project/akdogan/)
[![Python versions](https://img.shields.io/pypi/pyversions/akdogan.svg)](https://pypi.org/project/akdogan/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**akdogan** is a lightweight, cross-platform tool designed to bridge the gap between complex software projects and Large Language Models (LLMs).

It instantly converts your entire project—directory structure, source code, and data previews—into a single, structured `.txt` file optimized for the context windows of ChatGPT, Claude, Gemini, and Llama.

---

## 🧠 Why Use akdogan?

Developers often struggle to share code context with AI because:
- **ZIP files** are often rejected or hard to parse.
- **Copy-pasting** dozens of files manually is tedious.
- **Binary files** (images, pyc) create noise and waste tokens.
- **Large CSV/Excel** files consume context limits without providing structure.

**akdogan solves this** by intelligently curating your project into a single, token-efficient text file.

---

## ✨ Key Features

- **📂 Visual Directory Tree:** Generates a clean map of your project structure.
- **📄 Smart Content Extraction:** Reads `.py`, `.js`, `.html`, `.rs`, `.go` and more.
- **📊 Data Previews:** Automatically extracts only the **first 5 rows** of `.csv` and `.xlsx` files (skips bulk data).
- **🚫 Noise Filtering:** Ignores system files like `.git`, `__pycache__`, `node_modules`, `venv`, and binary executables.
- **🧪 Dual Mode:** Run it from the terminal (CLI) or import it in your Python scripts.
- **🖥️ Cross-Platform:** 100% compatible with Windows, macOS, and Linux.

---

## 🚀 Installation

Requires Python **3.8+**.

```bash
pip install akdogan
```

## 📦 CLI Usage

Navigate to your project folder and run:

```bash
# Snapshot the current directory
akdogan .
```

Options

Target a specific directory:

```bash
akdogan /Users/berke/dev/my-cool-project
```

Save to a specific output file:

```bash
akdogan . -o context_for_gpt.txt
```

## 🐍 Python Library Usage

You can also use akdogan programmatically within your automation scripts:

```python
import akdogan

# Generate snapshot for the current directory
akdogan.snapshot('.')

# Or target a specific path
akdogan.snapshot('/path/to/target')
```

This will generate a file named `snapshot_<folder>_<timestamp>.txt` automatically.

## 📁 Output Format Example

The generated text file is structured specifically for LLM comprehension:

```
=== PROJECT TREE ===

my_project/
    ├── app.py
    ├── utils/
    │   └── helper.py
    └── data/
        └── dataset.csv

=== FILE CONTENTS ===

--- FILE: app.py ---
import os
def main():
    print("Hello World")

--- FILE: utils/helper.py ---
def help_me():
    return True

--- FILE: data/dataset.csv ---
id,name,role
1,Alice,Admin
2,Bob,User
<<FIRST 5 ROWS ONLY>>
```

---

## 🛠 Development

To contribute or modify the tool locally:

Clone the repository:

```bash
git clone https://github.com/yourusername/akdogan.git
cd akdogan
```

Run locally:

```bash
python -m akdogan .
```

Run tests:

```bash
pytest
```

Build package:

```bash
python -m build
```

---

## 📜 License

This project is licensed under the MIT License. See the `LICENSE` file for details.

Copyright © 2025 Berke Akdoğan
