Metadata-Version: 2.4
Name: postman-agent
Version: 1.0.9
Summary: AI Agent that auto-generates Postman Collections from backend code
Author-email: "M. Abubakar" <m.abubakar.codes@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Abubakar-webmaker/postman-ai-agent
Project-URL: Repository, https://github.com/Abubakar-webmaker/postman-ai-agent
Keywords: postman,api,ai,agent,langgraph,groq,express,fastapi,flask
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain>=0.2.0
Requires-Dist: langchain-groq>=0.1.0
Requires-Dist: langgraph>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Provides-Extra: gemini
Requires-Dist: langchain-google-genai; extra == "gemini"
Provides-Extra: ollama
Requires-Dist: langchain-ollama; extra == "ollama"
Provides-Extra: openai
Requires-Dist: langchain-openai; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic; extra == "anthropic"
Provides-Extra: mistral
Requires-Dist: langchain-mistralai; extra == "mistral"
Provides-Extra: cohere
Requires-Dist: langchain-cohere; extra == "cohere"
Provides-Extra: huggingface
Requires-Dist: langchain-huggingface; extra == "huggingface"
Provides-Extra: all-free
Requires-Dist: langchain-google-genai; extra == "all-free"
Requires-Dist: langchain-ollama; extra == "all-free"
Requires-Dist: langchain-openai; extra == "all-free"
Provides-Extra: all
Requires-Dist: langchain-google-genai; extra == "all"
Requires-Dist: langchain-ollama; extra == "all"
Requires-Dist: langchain-openai; extra == "all"
Requires-Dist: langchain-anthropic; extra == "all"
Requires-Dist: langchain-mistralai; extra == "all"
Requires-Dist: langchain-cohere; extra == "all"
Requires-Dist: langchain-huggingface; extra == "all"
Dynamic: license-file

# 🤖 Postman Collection AI Agent

> An AI-powered developer tool that automatically analyzes your backend code, detects API routes, groups them into smart folders, and imports a complete Postman Collection — in seconds.

[![PyPI version](https://badge.fury.io/py/postman-agent.svg)](https://pypi.org/project/postman-agent/)
[![PyPI downloads](https://img.shields.io/pypi/dm/postman-agent)](https://pypi.org/project/postman-agent/)
[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/abubakaranas921.postman-collection-ai-agent)](https://marketplace.visualstudio.com/items?itemName=abubakaranas921.postman-collection-ai-agent)
[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

---

## 📖 Story — Why This Was Built

Every backend developer faces the same problem: after building an API, you have to manually create Postman Collections — naming every route, adding request bodies, setting up folders, configuring auth headers. For a project with 30-50 routes, this takes **hours**.

This tool was built to solve that. Point it at any backend project and it automatically:
- Scans all files by **content** (not filename)
- Detects base paths from `app.use()` and combines with route paths
- Groups routes into **smart folders** (Authentication, Products, Orders...)
- Generates **realistic request bodies** based on route context
- Detects **auth type** (JWT, OAuth, API Key)
- Imports the complete collection directly into **your Postman workspace**

---

## 🚀 3 Ways To Use

### 1️⃣ CLI Tool (Recommended)
```bash
pip install postman-agent
postman-agent setup
postman-agent generate --scan .
```

### 2️⃣ VS Code Extension
Search **"Postman Collection AI Agent"** in VS Code Extensions → Right click any file or folder → Generate!

### 3️⃣ Web UI
```bash
git clone https://github.com/Abubakar-webmaker/postman-ai-agent
cd postman-ai-agent/frontend && npm install && npm run dev
```

---

Every request includes:
- ✅ Proper HTTP method
- ✅ Full path with base URL (`{{base_url}}`)
- ✅ Auth header (`Bearer {{token}}`)
- ✅ Realistic request body
- ✅ Path params as variables (`{{id}}`)
- ✅ Query params (`?page=1&limit=10`)
- ✅ Environment variables

---

## 🎯 Features

| Feature | Details |
|---------|---------|
| 🔍 Smart File Detection | Scans files by content — works with any filename |
| 📍 Base Path Detection | Detects `app.use('/api/auth', authRoutes)` automatically |
| 📁 Auto Folder Grouping | Authentication, Products, Orders, Payments... |
| 🔐 Auth Type Detection | JWT, OAuth, API Key auto-detected |
| 📝 Smart Route Names | Login, Register, Get All Products, Delete Order... |
| 🎯 Path Params | `:id`, `{userId}` detected and added as `{{id}}` |
| 🔍 Query Params | `?page=1&limit=10&q=search` auto-detected |
| 📦 Request Bodies | Realistic bodies based on route context |
| 🌍 Environment Variables | `base_url`, `token`, `refresh_token`, dynamic params |
| 🚀 Auto Import | Direct import to Postman workspace via API |
| 🔗 Instant Link | Get Postman collection URL after import |
| 💬 VS Code Chat Panel | Beautiful chat interface like Copilot |
| ⚡ Fast | Entire project analyzed in seconds |

---

## 🌐 Supported Frameworks

| Framework | Language | Detection Pattern |
|-----------|----------|-------------------|
| ✅ Express.js | JavaScript | `router.get('/path', handler)` |
| ✅ Fastify | JavaScript | `fastify.get('/path', handler)` |
| ✅ FastAPI | Python | `@app.get('/path')` |
| ✅ Flask | Python | `@app.route('/path', methods=['GET'])` |
| ✅ Django | Python | `path('endpoint/', view)` |

---

## 🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                    User Interface                    │
│         CLI  │  VS Code Extension  │  Web UI         │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│                  CLI Entry Point                     │
│              postman_agent/cli.py                    │
│                                                      │
│  • Smart file scanner (content-based)                │
│  • Multi-project support                             │
│  • API key management (setup/update/delete)          │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│               LangGraph AI Agent                     │
│            postman_agent/agent/graph.py              │
│                                                      │
│  AgentState                                          │
│  ┌─────────┐     ┌──────────────┐                   │
│  │  agent  │────▶│   generate   │────▶ END           │
│  │  node   │     │    node      │                    │
│  └─────────┘     └──────────────┘                   │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│                Code Parser                           │
│           postman_agent/tools/code_parser.py         │
│                                                      │
│  1. detect_auth_type()   → JWT / OAuth / API Key     │
│  2. Extract base paths   → app.use('/api/auth', ...) │
│  3. Split by file        → per-file route extraction │
│  4. Combine paths        → /api/auth + /login        │
│  5. detect_folder()      → Authentication folder     │
│  6. generate_name()      → "Login", "Get Products"   │
│  7. extract_path_params()→ :id → {{id}}              │
│  8. extract_query_params()→ ?page=1&limit=10         │
│  9. generate_body()      → Realistic request body    │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│              Postman Collection Builder              │
│           build_postman_collection()                 │
│                                                      │
│  • Groups routes into folders                        │
│  • Auth first (Authentication folder always first)   │
│  • Builds Postman v2.1 JSON format                   │
│  • Adds environment variables                        │
│  • Adds collection-level auth                        │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│               Postman API Import                     │
│           import_to_postman_tool()                   │
│                                                      │
│  POST https://api.getpostman.com/collections         │
│  → Returns collection URL                            │
└─────────────────────────────────────────────────────┘

---

## 🛠️ Tech Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| 🧠 Agent Framework | LangGraph | Multi-step agent workflow |
| 🤖 LLM | Groq (llama-3.1-8b-instant) | Fast, free inference |
| 🔧 Code Parser | Python AST + Regex | Route extraction |
| 🔗 Integration | Postman REST API | Collection import |
| 🐍 CLI Backend | Python + FastAPI | API server |
| 🎨 Frontend | React + TypeScript + Tailwind | Web UI |
| 🔌 VS Code | TypeScript Webview | Editor extension |
| 📦 Package | PyPI | Distribution |

---

## 🗓️ Development Journey

### v1.0.0 — Foundation
- Basic Express.js route detection with Regex
- Simple Postman Collection generation
- FastAPI backend + React frontend (Web UI)
- Manual Postman import (download JSON)

### v1.0.1 — CLI Tool
- Python CLI package (`postman-agent` command)
- Auto-import to Postman via API
- Setup command for API key management
- PyPI package published

### v1.0.2 — Bug Fixes
- Unicode encoding fix for Windows
- VS Code extension published to Marketplace
- Chat panel UI (Copilot-style interface)
- First-time setup flow in extension

### v1.0.3 — Multi-Framework Support
- FastAPI, Flask, Django support added
- Python AST parsing for accurate detection
- Content-based file detection (not filename)
- Auto key management (update/delete/keep)

### v1.0.4 — Professional Restructure
- Removed duplicate code and orphan files
- Single source of truth for parser logic
- CHANGELOG.md and CONTRIBUTING.md added
- Comprehensive .gitignore
- Version sync across all files

### v1.0.5 — Smart Collection (Latest)
- Base path detection (`app.use('/api/auth', authRoutes)`)
- Full path combining (`/api/auth` + `/login` = `/api/auth/login`)
- Smart folder grouping (Authentication, Products, Orders...)
- Human-readable route names (Login, Get All Products...)
- Path params as Postman variables (`{{id}}`)
- Query params auto-detection (`?page=1&limit=10`)
- Realistic request body generation
- Environment variables auto-creation
- Auth type detection (JWT, OAuth, API Key)
- Collection-level auth configuration

---

## ⚡ Quick Start

```bash
# 1. Install
pip install postman-agent

# 2. Setup (one time only)
postman-agent setup
# → Enter GROQ API Key (free at console.groq.com)
# → Enter Postman API Key (free at postman.com → Settings → API Keys)

# 3. Generate from any project
cd your-backend-project
postman-agent generate --scan .

# Output:
# ✅ Found 53 routes!
# 📁 Authentication (7 routes)
# 📁 Products (5 routes)
# 📁 Orders (4 routes)
# 🚀 Imported to Postman!
# 🔗 https://go.postman.co/collection/xxxxx
```

---

## 🔑 API Keys Setup

| Key | Where to Get | Cost |
|-----|-------------|------|
| GROQ_API_KEY | [console.groq.com](https://console.groq.com) → API Keys | Free |
| POSTMAN_API_KEY | [postman.com](https://postman.com) → Settings → API Keys | Free |

---

---

## 🔗 Links

| Resource | Link |
|----------|------|
| 📦 PyPI | [pypi.org/project/postman-agent](https://pypi.org/project/postman-agent/) |
| 🔌 VS Code | [Marketplace: Postman Collection AI Agent](https://marketplace.visualstudio.com/items?itemName=abubakaranas921.postman-collection-ai-agent) |
| 💼 GitHub | [Abubakar-webmaker/postman-ai-agent](https://github.com/Abubakar-webmaker/postman-ai-agent) |
| 🌐 Portfolio | [abubakar-portfolio-sage.vercel.app](https://abubakar-portfolio-sage.vercel.app) |

---

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 👨‍💻 Author

**M. Abubakar** — Full Stack Developer & AI Agent Builder

- 📧 m.abubakar.codes@gmail.com
- 💼 [@Abubakar-webmaker](https://github.com/Abubakar-webmaker)
- 🌐 [abubakar-portfolio-sage.vercel.app](https://abubakar-portfolio-sage.vercel.app)

---

## 📄 License

MIT License — feel free to use and modify!

---

⭐ **If this saved you time, please star the repo!**
