🔥 PromptForge

Lightweight AI Prompt Engineering Management & Optimization CLI Engine

English · 简体中文 · 繁體中文

---

🎉 Project Introduction

PromptForge is a zero-dependency, pure-Python CLI tool designed for AI prompt engineering management and optimization. In the era of LLMs, crafting effective prompts is a critical skill — PromptForge provides a complete toolkit for managing, versioning, scoring, optimizing, and exporting your prompts.

💡 Why PromptForge?

• Tired of scattered prompt files? → PromptForge gives you a centralized vault with full-text search and tagging
• Want to improve prompt quality? → Built-in multi-dimensional quality scoring engine with actionable suggestions
• Need version control for prompts? → Git-like version history with diff and rollback support
• Running A/B tests on prompts? → Built-in variant comparison with automated ranking
• Sharing prompts with your team? → Multi-format export (JSON, YAML, Markdown, TOML, ENV)

✨ Key Differentiators

Feature	PromptForge	Typical Alternatives
Dependencies	✅ Zero (pure stdlib)	❌ Node.js / npm required
Quality Scoring	✅ 5-dimension analysis	❌ None or basic
Version Control	✅ Built-in with diff	❌ Manual file management
A/B Testing	✅ Multi-variant comparison	❌ Not available
Encryption	✅ Built-in prompt encryption	❌ Not available
Multi-format Export	✅ 5 formats	⚠️ Limited

---

✨ Core Features

📝 Prompt Management

• Add / Edit / Delete prompts with rich metadata (description, category, tags)
• Full-text search across prompt names, descriptions, tags, and content
• Tag-based filtering and categorization system
• Auto-naming with smart content-based suggestions

📊 Quality Scoring Engine

• 5-dimensional analysis: Clarity, Specificity, Structure, Actionability, Context Richness
• A+ to F grading system with visual score bars
• Actionable suggestions for improving weak prompts
• Strength identification to reinforce what works

📄 Version Control

• Git-like versioning for every prompt change
• Diff viewer to compare versions side-by-side
• One-click rollback to any previous version
• Complete change history with timestamps

🧪 A/B Testing

• Multi-variant comparison with automated ranking
• Per-metric analysis (overall, clarity, specificity, etc.)
• JSON output for integration with CI/CD pipelines

🔐 Encryption

• Built-in encryption for sensitive prompts (API keys, proprietary templates)
• Password-based key derivation (SHA-256)
• Secure storage in the local vault

📦 Multi-format Export/Import

• Export: JSON, YAML, Markdown, TOML, ENV
• Import: JSON, Markdown, ENV
• Batch operations: Export/import all prompts at once
• Metadata inclusion: Optional metadata in exports

📋 Template System

• Variable interpolation with {{variable}} syntax
• Template library management
• One-command rendering with variable substitution

---

🚀 Quick Start

📋 Prerequisites

• Python 3.9+ (that's it!)

🔧 Installation

# Clone the repository
git clone https://github.com/gitstq/PromptForge.git
cd PromptForge

# Install (optional - you can also run directly)
pip install -e .

⚡ Run Without Installation

cd PromptForge
PYTHONPATH=src python -m promptforge.cli <command>

🎯 First Steps

# 1. Initialize a prompt vault
promptforge init

# 2. Add your first prompt
promptforge add "You are an expert Python developer. Write a function that sorts a list of integers using merge sort." -n "merge-sort" -d "Merge sort implementation" -t "python,algorithm,coding"

# 3. Check the quality score
promptforge score merge-sort

# 4. Get optimization suggestions
promptforge optimize merge-sort

# 5. List all prompts
promptforge list

# 6. Export to JSON
promptforge export merge-sort -f json -o my-prompt.json

---

📖 Detailed Usage Guide

Prompt Lifecycle

# Create
promptforge add "Your prompt content with {{variables}}" -n "my-prompt" -d "Description" -t "tag1,tag2" -c category

# Read
promptforge show my-prompt              # Full details
promptforge show my-prompt --raw        # Raw content only
promptforge show my-prompt --version 2  # Specific version

# Update
promptforge edit my-prompt -c "Updated content" -d "New description"

# Delete
promptforge delete my-prompt            # With confirmation
promptforge delete my-prompt -f         # Force delete

Quality Scoring

# Score a managed prompt
promptforge score my-prompt

# Score raw text directly
promptforge score "Your prompt text here" --raw

# JSON output for automation
promptforge score my-prompt --json

A/B Testing

# Compare current prompt with variants
promptforge test my-prompt -v "Variant A content" "Variant B content"

# Compare by specific metric
promptforge test my-prompt -v "Variant A" "Variant B" -m clarity

# JSON output
promptforge test my-prompt -v "Variant A" "Variant B" --json

Version Control

# View change history
promptforge log
promptforge log my-prompt -n 10

# Compare versions
promptforge diff my-prompt
promptforge diff my-prompt --from 1 --to 3

# Rollback
promptforge rollback my-prompt 2

Templates

# Create a template
promptforge template create greeting "Hello {{name}}, welcome to {{place}}!"

# List templates
promptforge template list

# Render with variables
promptforge template render greeting name=Alice place=Wonderland

Search & Filter

# Search by keyword
promptforge search "python"

# Search in content
promptforge search "algorithm" --content

# Filter by category and tags
promptforge list -c coding -t "python,algorithm"

Encryption

# Encrypt a sensitive prompt
promptforge encrypt my-api-prompt --key "my-secret-key"

# Decrypt
promptforge decrypt my-api-prompt --key "my-secret-key"

# Set default key in config
promptforge config encryption_key "my-default-key"

Export & Import

# Export single prompt
promptforge export my-prompt -f markdown -o prompt.md

# Export all prompts
promptforge export all -f json -o all-prompts.json

# Import from file
promptforge import prompts.json -f json --merge

# Import with default category
promptforge import prompts.json -f json --category "shared"

---

💡 Design Philosophy & Roadmap

🎨 Design Principles

1. Zero Dependencies — Pure Python standard library, no external packages needed
2. CLI-First — Designed for terminal power users and automation
3. Developer Experience — Clear error messages, helpful suggestions, colorful output
4. Privacy-First — All data stored locally, optional encryption for sensitive content
5. Extensible — Clean architecture that's easy to extend with new features

🗺️ Roadmap

• v1.1: LLM Provider Integration (OpenAI, Anthropic, DeepSeek) for live testing
• v1.2: Interactive TUI mode with rich terminal UI
• v1.3: Prompt sharing via Git repositories
• v1.4: Web dashboard for visual prompt management
• v2.0: Plugin system for custom scoring rules and exporters

---

📦 Installation & Deployment

From Source

git clone https://github.com/gitstq/PromptForge.git
cd PromptForge
pip install -e .

As a CLI Tool

After installation, the promptforge command is available globally:

promptforge --version
promptforge init

Running Tests

cd PromptForge
python -m pytest tests/ -v

Compatible Environments

Platform	Python 3.9	Python 3.10	Python 3.11	Python 3.12	Python 3.13
Linux ✅	✅	✅	✅	✅	✅
macOS ✅	✅	✅	✅	✅	✅
Windows ✅	✅	✅	✅	✅	✅

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

We follow the Angular Commit Convention:

• feat: New features
• fix: Bug fixes
• docs: Documentation updates
• refactor: Code refactoring
• test: Test additions/updates
• chore: Maintenance tasks

Issue Reporting

Please use GitHub Issues to report bugs or request features.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Made with 🔥 by Lobster Dev

---

🇨🇳 简体中文

🔥 PromptForge

轻量级AI Prompt工程化管理与智能优化CLI引擎

---

🎉 项目介绍

PromptForge 是一款零依赖、纯Python标准库实现的AI Prompt工程化管理与优化CLI工具。在LLM时代，精心设计Prompt是一项关键技能——PromptForge为管理、版本控制、评分、优化和导出Prompt提供了完整的工具链。

💡 为什么选择PromptForge？

• 厌倦了散落各处的Prompt文件？ → PromptForge提供集中式保险库，支持全文搜索和标签管理
• 想提升Prompt质量？ → 内置5维度质量评分引擎，提供可操作的优化建议
• 需要Prompt版本控制？ → 类Git的版本历史，支持差异对比和一键回滚
• 想做Prompt A/B测试？ → 内置多变体对比，自动排名
• 需要与团队共享Prompt？ → 支持多格式导出（JSON、YAML、Markdown、TOML、ENV）

✨ 核心特性

特性	PromptForge	常见替代方案
外部依赖	✅ 零依赖（纯标准库）	❌ 需要Node.js/npm
质量评分	✅ 5维度分析	❌ 无或基础
版本控制	✅ 内置差异对比	❌ 手动文件管理
A/B测试	✅ 多变体对比排名	❌ 不可用
加密存储	✅ 内置Prompt加密	❌ 不可用
多格式导出	✅ 5种格式	⚠️ 有限

🚀 快速开始

# 克隆仓库
git clone https://github.com/gitstq/PromptForge.git
cd PromptForge

# 安装（可选）
pip install -e .

# 初始化Prompt保险库
promptforge init

# 添加第一个Prompt
promptforge add "你是一位Python专家。请编写一个使用归并排序对整数列表进行排序的函数。" -n "merge-sort" -d "归并排序实现" -t "python,算法,编程"

# 查看质量评分
promptforge score merge-sort

# 获取优化建议
promptforge optimize merge-sort

📖 详细使用指南

# Prompt生命周期管理
promptforge add "内容" -n "名称" -d "描述" -t "标签1,标签2" -c 分类
promptforge show my-prompt
promptforge edit my-prompt -c "更新内容"
promptforge delete my-prompt

# 质量评分
promptforge score my-prompt
promptforge score "原始Prompt文本" --raw

# A/B测试
promptforge test my-prompt -v "变体A" "变体B"

# 版本控制
promptforge log
promptforge diff my-prompt
promptforge rollback my-prompt 2

# 模板系统
promptforge template create greeting "你好{{name}}，欢迎来到{{place}}！"
promptforge template render greeting name=小明 place=北京

# 搜索过滤
promptforge search "python" --content
promptforge list -c coding -t "python,algorithm"

# 加密
promptforge encrypt my-prompt --key "密钥"
promptforge decrypt my-prompt --key "密钥"

# 导入导出
promptforge export my-prompt -f markdown -o prompt.md
promptforge export all -f json -o all.json
promptforge import prompts.json -f json --merge

💡 设计思路与迭代规划

设计原则：

1. 零依赖 — 纯Python标准库，无需安装任何外部包
2. CLI优先 — 为终端高级用户和自动化场景设计
3. 开发者体验 — 清晰的错误提示、有用的建议、彩色输出
4. 隐私优先 — 所有数据本地存储，敏感内容可选加密
5. 可扩展 — 清晰的架构，易于添加新功能

迭代规划：

• v1.1: LLM提供商集成（OpenAI、Anthropic、DeepSeek）实时测试
• v1.2: 交互式TUI模式
• v1.3: 通过Git仓库共享Prompt
• v1.4: Web可视化仪表盘
• v2.0: 插件系统

🤝 贡献指南

欢迎贡献！请遵循以下规范：

1. Fork 本仓库
2. 创建 特性分支 (git checkout -b feature/amazing-feature)
3. 提交 更改 (git commit -m 'feat: 新增功能')
4. 推送 分支 (git push origin feature/amazing-feature)
5. 发起 Pull Request

---

🇹🇼 繁體中文

🔥 PromptForge

輕量級AI Prompt工程化管理與智慧優化CLI引擎

---

🎉 專案介紹

PromptForge 是一款零依賴、純Python標準庫實作的AI Prompt工程化管理與優化CLI工具。在LLM時代，精心設計Prompt是一項關鍵技能——PromptForge為管理、版本控制、評分、優化和匯出Prompt提供了完整的工具鏈。

💡 為什麼選擇PromptForge？

• 厭倦了散落各處的Prompt檔案？ → PromptForge提供集中式保險庫，支援全文搜尋和標籤管理
• 想提升Prompt品質？ → 內建5維度品質評分引擎，提供可操作的優化建議
• 需要Prompt版本控制？ → 類Git的版本歷史，支援差異對比和一鍵回滾
• 想做Prompt A/B測試？ → 內建多變體對比，自動排名
• 需要與團隊共享Prompt？ → 支援多格式匯出（JSON、YAML、Markdown、TOML、ENV）

✨ 核心特性

特性	PromptForge	常見替代方案
外部依賴	✅ 零依賴（純標準庫）	❌ 需要Node.js/npm
品質評分	✅ 5維度分析	❌ 無或基礎
版本控制	✅ 內建差異對比	❌ 手動檔案管理
A/B測試	✅ 多變體對比排名	❌ 不可用
加密儲存	✅ 內建Prompt加密	❌ 不可用
多格式匯出	✅ 5種格式	⚠️ 有限

🚀 快速開始

# 克隆倉庫
git clone https://github.com/gitstq/PromptForge.git
cd PromptForge

# 安裝（可選）
pip install -e .

# 初始化Prompt保險庫
promptforge init

# 新增第一個Prompt
promptforge add "你是一位Python專家。請編寫一個使用合併排序對整數列表進行排序的函數。" -n "merge-sort" -d "合併排序實作" -t "python,演算法,程式設計"

# 查看品質評分
promptforge score merge-sort

# 取得優化建議
promptforge optimize merge-sort

📖 詳細使用指南

# Prompt生命週期管理
promptforge add "內容" -n "名稱" -d "描述" -t "標籤1,標籤2" -c 分類
promptforge show my-prompt
promptforge edit my-prompt -c "更新內容"
promptforge delete my-prompt

# 品質評分
promptforge score my-prompt
promptforge score "原始Prompt文本" --raw

# A/B測試
promptforge test my-prompt -v "變體A" "變體B"

# 版本控制
promptforge log
promptforge diff my-prompt
promptforge rollback my-prompt 2

# 模板系統
promptforge template create greeting "你好{{name}}，歡迎來到{{place}}！"
promptforge template render greeting name=小明 place=台北

# 搜尋過濾
promptforge search "python" --content
promptforge list -c coding -t "python,algorithm"

# 加密
promptforge encrypt my-prompt --key "密鑰"
promptforge decrypt my-prompt --key "密鑰"

# 匯入匯出
promptforge export my-prompt -f markdown -o prompt.md
promptforge export all -f json -o all.json
promptforge import prompts.json -f json --merge

💡 設計思路與迭代規劃

設計原則：

1. 零依賴 — 純Python標準庫，無需安裝任何外部套件
2. CLI優先 — 為終端進階使用者和自動化場景設計
3. 開發者體驗 — 清晰的錯誤提示、有用的建議、彩色輸出
4. 隱私優先 — 所有資料本地儲存，敏感內容可選加密
5. 可擴展 — 清晰的架構，易於新增功能

迭代規劃：

• v1.1: LLM提供商整合（OpenAI、Anthropic、DeepSeek）即時測試
• v1.2: 互動式TUI模式
• v1.3: 透過Git倉庫共享Prompt
• v1.4: Web視覺化儀表板
• v2.0: 外掛系統

🤝 貢獻指南

歡迎貢獻！請遵循以下規範：

1. Fork 本倉庫
2. 建立 特性分支 (git checkout -b feature/amazing-feature)
3. 提交 變更 (git commit -m 'feat: 新增功能')
4. 推送 分支 (git push origin feature/amazing-feature)
5. 發起 Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

本專案採用 MIT 授權條款 — 詳見 LICENSE 檔案。