prompts-conductor/README.md

⚡ Wire up your AI prompts - The ultimate CLI for AI workflow orchestration. Create, manage, and chain prompts across 400+ AI platforms with enterprise security, version control, and automation. Includes comprehensive CLI documentation.

# ⚡ Prompts Conductor ⚡

[![Website](https://img.shields.io/badge/Website-prompts--conductor.com-blue?style=for-the-badge&logo=globe)](https://prompts-conductor.com) [![Version](https://img.shields.io/badge/Version-v2.2.13-green?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/prompts-conductor) [![Beta](https://img.shields.io/badge/Beta-2.2.14-orange?style=for-the-badge&logo=beta)](https://prompts-conductor.com) [![License](https://img.shields.io/badge/License-All%20Rights%20Reserved-red?style=for-the-badge&logo=law)](LICENSE)

> **"Wire up your AI prompts"** - A powerful CLI for creating, managing, and orchestrating AI prompt workflows with truly agnostic multi-platform support.

## ⚠️ Beta Version Notice


This is a beta version of Prompts Conductor. I apologize for any bumpy development experiences during this phase. The system is actively being refined and improved based on real-world usage and feedback.

**Key Commitments:**
- ✅ **Version Retention**: I am committed to maintaining all versions going forward. No versions will be removed from the npm registry, ensuring stability and backward compatibility for all users.
- 🔄 **Continuous Improvement**: Regular updates and bug fixes based on user feedback
- 🛡️ **Stability Focus**: Prioritizing reliability over new features during beta

> Please report any issues or provide feedback to help improve the experience at info@prompts-conductor.com

---
## 🔧 **Recent Updates**

### Latest Version: v2.2.14
- **Path Management**: Fixed path resolution and management issues
- **Stability**: Improved overall system reliability and error handling

### Previous Updates
- **v2.2.13**: Enhanced conductor chain execution and template validation
- **v2.2.12**: Added MLM integration and improved security features

## 📚 **Documentation**

> **📖 Full documentation available at:** [www.prompts-conductor.com](https://www.prompts-conductor.com)

---

## 🚀 Quick Start

```bash
# Install globally
npm install -g prompts-conductor

# Or use locally with bun
bun add prompts-conductor

# Initialize your workspace
pc init

# Create your first template
pc template create "Hello World" "Say hello to {{name}}"

# Run the template
pc template run "Hello World" --ai-platform openai --vars name="World"
```

## 📋 Complete CLI Command Reference

### Core Commands

| Command | Alias | Description |
|---------|-------|-------------|
| `template` | `t` | Template management - create, edit, run AI prompts |
| `conductor` | - | Workflow orchestration - chain templates together |
| `models` | `m` | AI model management - discover and configure models |
| `platforms` | `p` | Platform configuration - manage AI platforms |
| `setup` | - | Interactive setup wizard for easy configuration |

### Automation & Management

| Command | Alias | Description |
|---------|-------|-------------|
| `auto-manager` | `auto` | Manage automated features and AI agents |
| `config` | `cfg` | Global configuration and settings |
| `test-setup` | `testSetup` | Set up mock platform for testing |

### Security & Privacy

| Command | Alias | Description |
|---------|-------|-------------|
| `security` | `sec` | Security management - API keys and encryption |
| `privacy` | - | GDPR and privacy compliance |

### Development Tools

| Command | Alias | Description |
|---------|-------|-------------|
| `api-test` | `apiTest` | Test AI platform APIs and connections |
| `network-logs` | `networkLogs` | Network request/response logging |
| `doctor` | - | System diagnostics and validation |
| `search` | `sr` | Search templates, schemas, and conductors |

### Advanced Features

| Command | Alias | Description |
|---------|-------|-------------|
| `mlm` | - | MLM-powered template enhancement |
| `mlm-setup` | `mlmSetup` | Configure MLM API connections |
| `tap` | - | Command logging and event tracking |
| `trashbin` | `tbin` | Manage soft-deleted items |
| `git` | - | Git repository management |
| `schema` | `sch` | Schema definition and management |
| `advanced` | `a` | Advanced features and utilities |

### Documentation

| Command | Alias | Description |
|---------|-------|-------------|
| `docs` | `d` | Comprehensive documentation and guides |
| `examples` | - | Show example templates and use cases |
| `help` | - | Display help for any command |

### Global Options

| Option | Description |
|--------|-------------|
| `-V, --version` | Show version number |
| `--features` | Show features list |
| `--commands` | Show commands list |
| `--help` | Display help information |
| `--docs` | Show documentation |
| `--interactive` | Run in interactive mode |

## 🎯 Common Workflows

### Template Management
```bash
# Create a new template
pc template create my_prompt

# List all templates
pc template list

# Run a template with variables
pc template run my_prompt --vars '{"topic": "AI"}'

# Edit existing template
pc template edit my_prompt

# Export template for sharing
pc template export my_prompt --format yaml
```

### Conductor Workflows
```bash
# Create a conductor workflow
pc conductor create my_workflow

# Add templates to conductor
pc conductor add-template my_workflow research_template
pc conductor add-template my_workflow writing_template

# Run the workflow
pc conductor run my_workflow --shared-context

# Selective chain execution
pc conductor run my_workflow --chains "research,write"
```

### Model Management
```bash
# List all available models
pc models list

# Search for specific models
pc models search gpt

# Discover models from platforms
pc models discover

# Add a new model
pc models add openai gpt-4

# Get model suggestions
pc models suggest my_template
```

### Platform Configuration
```bash
# List configured platforms
pc platforms list

# Add a new platform
pc platforms add openai --default-model gpt-4

# Configure platform settings
pc platforms configure openai

# Test platform connectivity
pc platforms test openai

# Create unified configuration
pc platforms unified-config
```

### Security Management
```bash
# Setup security
pc security setup

# Check security status
pc security check

# Validate API key
pc security validate openai

# Test API connection
pc security test openai

# Rotate API keys
pc security rotate openai
```

---

## 🎯 **Core Capabilities**

### **🎨 Template Management** ✅
- **Smart Templates** - Create reusable prompts with dynamic variables and validation
- **Variable System** - Type-safe variable substitution with custom validation rules
- **Template Categories** - Organize by data, prompts, API, frontend, backend, devops, testing, documentation, creative, academic, business
- **Version Control** - Track template changes and maintain history
- **Import/Export** - Support for PTBC, YAML, and JSON formats

### **🎼 Conductor Workflows** ✅
- **Multi-Step Orchestration** - Chain templates together for complex workflows
- **Selective Execution** - Run specific steps or entire chains
- **Shared Context** - Pass data between workflow steps
- **Conditional Logic** - Execute steps based on results
- **Parallel Processing** - Run multiple templates simultaneously
- **🔄 Ad-Hoc Chain Execution** - Run template chains with shared context outside conductors
- **⚡ Dynamic Workflow Creation** - Create complex workflows on-the-fly without setup

### **🔌 Multi-Platform Support** ✅
- **Truly Agnostic Architecture** - Add ANY AI platform with custom configuration
- **Multiple API Formats** - OpenAI, Anthropic, Google, Azure, Custom, Generic
- **Custom Endpoints** - Use any API endpoint you want
- **Custom Request/Response Formatting** - Define your own API structures
- **Custom Validation Rules** - Platform-specific parameter validation
- **Easy Platform Switching** - Use different platforms for different templates
- **Test and Validate** - Verify platform connections before use

### **🔐 Enterprise Security** ✅
- **AES-256 Encryption** - Military-grade encryption for API keys and sensitive data
- **Key Rotation** - Automatic API key rotation for enhanced security
- **Rate Limiting** - Configurable rate limiting per platform
- **Input Validation** - Comprehensive input sanitization and validation
- **Secure Storage** - Encrypted local storage with environment variable support
- **Audit Logging** - Track all security-related operations

### **🤖 AI Automation** ✅
- **Background Agents** - Run AI workflows in the background
- **Scheduled Tasks** - Automate template execution on schedules
- **Auto-Cleanup** - Automatic cleanup of temporary files and logs
- **Auto-Backup** - Scheduled backup of templates and configurations
- **Auto-Validation** - Continuous validation of templates and configurations
- **Auto-Sync** - Automatic synchronization of configuration files

### **📊 Real-Time Monitoring** ✅
- **Network Analytics** - Monitor API calls and response times
- **Performance Tracking** - Track execution times and resource usage
- **Error Monitoring** - Comprehensive error tracking and reporting
- **Usage Analytics** - Monitor template and platform usage patterns
- **Health Checks** - System health monitoring and diagnostics

### **🔍 Advanced Search & Discovery** ✅
- **Semantic Search** - Find templates by content and meaning
- **Tag-Based Organization** - Organize with custom tags and categories
- **Fuzzy Matching** - Intelligent search with typo tolerance
- **Context-Aware Results** - Search results based on usage context
- **Cross-Platform Discovery** - Find models and platforms across services

---

## 🚀 **Power Features - What Makes Prompts Conductor Unique**

### **🔄 Template Chain Execution with Shared Context**
One of the most powerful capabilities that sets Prompts Conductor apart is the ability to run templates and template chains **outside of conductors** while maintaining shared context between executions.

**What This Enables:**
- **Instant Workflows** - Create complex workflows without any setup or configuration
- **Shared Context** - Variables persist across the entire execution sequence
- **Dynamic Composition** - Mix and match any templates or chains on demand
- **Quick Prototyping** - Test different workflow combinations instantly
- **Scriptable Execution** - Easy to automate and integrate into CI/CD pipelines

**Example:**
```bash
# Run a complete content pipeline with shared context and initial variables
pc template run-chain "research,outline,write,seo,review" --shared-context --vars '{"topic": "AI Ethics", "tone": "professional", "length": 1000}'

# Or build dynamically:
pc template run research --vars '{"topic": "AI Ethics"}' --shared-context
pc template run write --shared-context
pc template run review --shared-context
```

### **⚡ Multi-Platform Chain Execution**
Run different AI platforms on each template step while maintaining shared context throughout the entire chain.

**What This Enables:**
- **Platform Specialization** - Use the best AI platform for each specific task
- **Cost Optimization** - Mix expensive and affordable models strategically
- **Performance Tuning** - Use fast models for simple tasks, powerful models for complex ones
- **Fallback Support** - Automatically switch platforms if one fails
- **Workflow Flexibility** - Create truly agnostic AI workflows

**Example:**
```bash
# Research with Claude, Writing with GPT-4, Review with Gemini
pc template run research --ai-platform anthropic --shared-context
pc template run write --ai-platform openai --shared-context  
pc template run review --ai-platform google --shared-context
```

---

## 🛠️ **Complete Feature List**

### **Template System** ✅
- **Smart Creation** - AI-assisted template generation with best practices
- **Variable Management** - Type-safe variables with validation and defaults
- **Category Organization** - 12+ predefined categories for easy organization
- **Version History** - Complete change tracking and rollback capabilities
- **Import/Export** - Multi-format support (PTBC, YAML, JSON)
- **Template Chains** - Link multiple templates for complex workflows
- **Custom Validation** - Platform-specific validation rules
- **Example Management** - Store and manage input/output examples

### **Conductor Orchestration** ✅
- **Workflow Management** - Create and manage complex AI workflows
- **Step-by-Step Execution** - Run workflows step by step or all at once
- **Context Sharing** - Pass data between workflow steps
- **Conditional Logic** - Execute steps based on previous results
- **Parallel Processing** - Run multiple steps simultaneously
- **Error Handling** - Graceful error handling and recovery
- **Progress Tracking** - Monitor workflow execution progress
- **Resource Management** - Control costs and execution time limits

### **Platform Management** ✅
- **Unified Configuration** - Single configuration system for all platforms
- **Custom API Formats** - Support for any REST API structure
- **Dynamic Discovery** - Automatic platform and model detection
- **Connection Testing** - Validate platform connectivity
- **API Key Management** - Secure storage and rotation of API keys
- **Rate Limit Management** - Platform-specific rate limiting
- **Model Routing** - Intelligent model selection and routing
- **Fallback Support** - Automatic fallback to alternative platforms

### **Security & Privacy** ✅
- **Encrypted Storage** - AES-256 encryption for all sensitive data
- **Key Rotation** - Automatic API key rotation
- **Rate Limiting** - Configurable rate limiting per platform
- **Input Validation** - Comprehensive input sanitization
- **Audit Logging** - Complete audit trail of all operations
- **Environment Integration** - Secure integration with environment variables
- **CI/CD Support** - Secure operation in automated environments
- **Privacy Controls** - Granular control over data sharing

### **Automation Engine** ✅
- **Background Processing** - Run AI workflows in the background
- **Scheduled Execution** - Automate tasks on custom schedules
- **Auto-Optimization** - Automatic performance optimization
- **Resource Management** - Automatic resource cleanup and management
- **Health Monitoring** - Continuous system health monitoring
- **Error Recovery** - Automatic error recovery and retry logic
- **Performance Tuning** - Dynamic performance optimization
- **Load Balancing** - Intelligent load distribution across platforms

### **Storage & Synchronization** ✅
- **PTBC Format** - Proprietary binary format for efficient storage
- **Config Sync** - Automatic configuration synchronization
- **Backup Management** - Automated backup and restore
- **Version Control** - Git integration for template management
- **Conflict Resolution** - Automatic conflict detection and resolution
- **Multi-Device Sync** - Synchronize across multiple devices
- **Offline Support** - Work offline with local caching
- **Data Migration** - Easy migration between formats and versions

### **🔄 Comprehensive Import/Export System** ✅
- **Universal Format Support** - Import/export from JSON, YAML, and PTBC formats
- **Platform Management** - Export/import platform configurations with conflict resolution
- **Template Chain Portability** - Share and migrate template chains across environments
- **Conductor Chain Management** - Full chain reconstruction and step management
- **Configuration Migration** - Selective import/export of platforms, models, and settings
- **Cross-Environment Sync** - Move configurations between development and production
- **Backup & Recovery** - Comprehensive disaster recovery and data portability
- **Team Collaboration** - Share templates and configurations with team members

### **Developer Experience** ✅
- **CLI Interface** - Intuitive command-line interface
- **Interactive Mode** - User-friendly interactive prompts
- **Help System** - Comprehensive help and documentation
- **Error Handling** - Clear error messages and suggestions
- **Debugging Tools** - Built-in debugging and troubleshooting
- **Testing Support** - Built-in testing and validation tools
- **Plugin System** - Extensible architecture for custom functionality
- **API Access** - Programmatic access to all features

---

## 🎯 **Use Cases**

### **Content Creation** ✅
- **Blog Writing** - Generate blog posts, articles, and content
- **Social Media** - Create engaging social media content
- **Marketing Copy** - Generate marketing materials and campaigns
- **Documentation** - Create technical documentation and guides
- **Creative Writing** - Generate stories, poems, and creative content

### **Development & DevOps** ✅
- **Code Generation** - Generate code snippets and templates
- **API Development** - Create and test API endpoints
- **Database Design** - Generate database schemas and queries
- **Testing** - Create test cases and scenarios
- **Deployment** - Automate deployment workflows

### **Business & Analytics** ✅
- **Data Analysis** - Generate data analysis reports
- **Business Plans** - Create business plans and strategies
- **Market Research** - Generate market analysis reports
- **Financial Modeling** - Create financial models and projections
- **Customer Support** - Generate support documentation and responses

### **Research & Education** ✅
- **Academic Writing** - Generate research papers and essays
- **Lesson Plans** - Create educational content and lesson plans
- **Study Materials** - Generate study guides and materials
- **Research Reports** - Create research summaries and reports
- **Knowledge Management** - Organize and structure knowledge

---

## 🚀 **Getting Started**

### **Installation**

```bash
# Global installation (recommended)
npm install -g prompts-conductor

# Local installation
npm install prompts-conductor

# Using Bun
bun add prompts-conductor
```

### **Initial Setup**

```bash
# Initialize your workspace
pc init

# Configure your first platform
pc platforms add openai --default-model gpt-4

# Set your API key
pc advanced security set-api-key openai YOUR_API_KEY
```

### **Create Your First Template**

```bash
# Create a simple template
pc template create "Greeting" "Hello {{name}}! How are you today?"

# Run the template
pc template run "Greeting" --vars name="World"
```

---

## 🔧 **Platform Management**

Configure and manage ANY AI platform with truly agnostic support:

```bash
# Add ANY platform with custom configuration
pc platforms add my_custom_platform --endpoint "https://api.mycustomai.com/v1" --format custom
pc platforms add openai --default-model gpt-4
pc platforms add claude --default-model claude-3-sonnet

# List all configured platforms
pc platforms list

# Test platform connectivity
pc platforms test my_custom_platform

# Discover available models on a platform
pc models discover my_custom_platform
```

---

## 📚 **Documentation**

- **CLI Commands**: `pc --help`
- **Template Guide**: `pc docs template`
- **Conductor Guide**: `pc docs conductor`
- **Platform Setup**: `pc docs platforms`
- **Security Guide**: `pc docs security`

---

## 🤝 **Contributing**

This is a private repository focused on delivering a stable, feature-rich AI workflow management system. The codebase is actively maintained and improved based on real-world usage patterns.

---

## 📖 Detailed CLI Command Reference

### Template Commands (`pc template`)

| Command | Alias | Description |
|---------|-------|-------------|
| `create [name]` | `c` | Create a new template |
| `rename <oldName> <newName>` | `rn` | Rename a template |
| `edit <name>` | `e` | Edit existing template |
| `delete <name>` | `d` | Delete a template |
| `list` | `l` | List all templates |
| `show [name]` | `s` | Show template details |
| `validate [name]` | `v` | Validate template structure |
| `backup [name]` | `b` | Create backup of templates |
| `restore <backup-path>` | `r` | Restore templates from backup |
| `fix [name]` | `fx` | Fix common template issues |
| `add-platform <name> <platform>` | `ap` | Add AI platform support |
| `remove-platform <name> <platform>` | `rp` | Remove AI platform support |
| `create-from-template <newName> <source>` | `cft` | Create from existing template |
| `history` | `h` | Manage template history |
| `storage` | `st` | Manage storage configuration |
| `chain` | `tch` | Template chain management |
| `run <name>` | `r` | Run template with AI platform |
| `export <name>` | `x` | Export template to file |
| `import <file>` | `i` | Import template from file |

### Conductor Commands (`pc conductor`)

| Command | Alias | Description |
|---------|-------|-------------|
| `create <name>` | `c` | Create a new conductor |
| `delete <name>` | `d` | Delete a conductor |
| `rename <oldName> <newName>` | `rn` | Rename a conductor |
| `config <name>` | `cfg` | Configure conductor settings |
| `add-template <conductor> <template>` | `at` | Add template to conductor |
| `remove-template <conductor> <template>` | `rt` | Remove template from conductor |
| `add-chain <conductor> <chain>` | `ac` | Add template chain to conductor |
| `remove-chain <conductor> <chain>` | `rc` | Remove template chain |
| `context <conductor>` | `ctx` | Manage shared context |
| `search <query>` | `s` | Search conductors |
| `list` | `l` | List all conductors |
| `show [name]` | `sh` | Show conductor details |
| `export <name>` | `x` | Export conductor to file |
| `import <file>` | `i` | Import conductor from file |
| `run [name]` | `r` | Run conductor workflow |
| `edit <name>` | `e` | Edit conductor configuration |

### Models Commands (`pc models`)

| Command | Alias | Description |
|---------|-------|-------------|
| `list` | `l` | List all supported models |
| `search <pattern>` | `s` | Search models by name/category |
| `info [platform]` | `i` | Show model details |
| `stats` | `st` | Show usage statistics |
| `validate` | `v` | Validate model configuration |
| `validate-models` | `vm` | Validate all models |
| `add <platform> <model>` | `a` | Add new model |
| `remove <platform> <model>` | `rm` | Remove model |
| `auto-add` | `aa` | Auto-add from platforms |
| `discover` | `d` | Discover available models |
| `adapters` | - | List dynamic adapters |
| `validate-config` | `vc` | Validate routing config |
| `suggest [template]` | `sg` | Get model suggestions |
| `sync` | `sy` | Sync from external sources |
| `routing` | `route` | Show routing information |
| `export` | `x` | Export models config |
| `import <file>` | `im` | Import models config |

### Auto-Manager Commands (`pc auto-manager`)

| Command | Alias | Description |
|---------|-------|-------------|
| `cleanup` | - | Manage auto-cleanup |
| `backup` | - | Manage auto-backup |
| `validation` | - | Manage auto-validation |
| `sync` | - | Manage auto-sync |
| `cache` | - | Manage auto-cache |
| `schema-enhancement` | - | Manage schema enhancement |
| `status` | - | Show all features status |
| `config` | - | Manage configuration |
| `all` | - | Manage all features |
| `agents` | `pilot` | AI agent autopilot |
| `management` | `mgmt` | Manage automation |

### Platform Commands (`pc platforms`)

| Command | Alias | Description |
|---------|-------|-------------|
| `list` | `l` | List configured platforms |
| `add <name>` | `a` | Add new platform |
| `configure <platform>` | `c` | Configure platform |
| `set-model-metadata <platform> <model>` | `smm` | Set model metadata |
| `remove <platform>` | `rm` | Remove platform |
| `validate` | `v` | Validate configurations |
| `backup` | `b` | Backup configurations |
| `restore <file>` | `r` | Restore from backup |
| `unified-config` | `uc` | Create unified config |
| `edit [platform]` | `e` | Edit configuration |
| `test <platform>` | - | Test platform connectivity |
| `export [options]` | `x` | Export platform configurations |
| `import <file> [options]` | `i` | Import platform configurations |

### Security Commands (`pc security`)

| Command | Alias | Description |
|---------|-------|-------------|
| `setup` | - | Setup security configuration |
| `check` | - | Check security status |
| `list` | - | List stored API keys |
| `remove <platform>` | - | Remove API key |
| `validate <platform>` | - | Validate API key |
| `test <platform>` | - | Test API key with call |
| `list-keys` | - | List keys with values |
| `rotate <platform>` | - | Rotate API key |

### Privacy Commands (`pc privacy`)

| Command | Alias | Description |
|---------|-------|-------------|
| `export-data` | `export` | Export user data (GDPR) |
| `show-data` | `show` | Show stored data |
| `forget-me` | `forget` | Delete all data (GDPR) |
| `consent` | - | Manage consent settings |
| `policy` | - | Show privacy policy |
| `audit` | - | Manage audit logs |

### MLM Commands (`pc mlm`)

| Command | Alias | Description |
|---------|-------|-------------|
| `enhance <template>` | - | Enhance template using MLM |
| `suggest-variables <template>` | - | Suggest variables |
| `assess-quality <template>` | - | Assess template quality |
| `suggest-chain <goal>` | - | Suggest prompt chains |
| `predict-context <template>` | - | Predict missing context |
| `validate-schema <schema> [data]` | - | Validate schema |
| `enhance-schema <schema> <template>` | - | Generate enhanced schema |

### TAP Commands (`pc tap`)

| Command | Alias | Description |
|---------|-------|-------------|
| `log <command>` | `l` | Add logging for command |
| `notify <command>` | `n` | Add notification |
| `track <command>` | `t` | Add event tracking |
| `list` | `l` | List configured events |
| `remove <id>` | `r` | Remove event by ID |
| `enable` | - | Enable TAP functionality |
| `disable` | - | Disable TAP functionality |
| `config` | - | Configure TAP settings |
| `stats` | - | Show TAP statistics |

### Configuration Commands (`pc config`)

| Command | Alias | Description |
|---------|-------|-------------|
| `show` | - | Show current configuration |
| `edit` | - | Edit configuration |
| `backup` | - | Backup configuration |
| `restore` | - | Restore configuration |
| `lint` | - | Lint configuration |
| `migrate` | - | Migrate configuration |
| `settings` | - | Manage settings |
| `system` | - | System configuration |

---

## 📚 Documentation

> **📖 Full documentation available at:** [www.prompts-conductor.com](https://www.prompts-conductor.com)

---

## 📄 License

**All Rights Reserved** - Copyright (c) 2025 Friedrich Timm

This software is provided free of charge for personal and commercial use, subject to the following key conditions:

- **Usage Only**: You may use this software for any lawful purpose
- **No Modification**: You may not modify, adapt, or create derivative works
- **No Redistribution**: You may not redistribute or make available to third parties
- **No Forking**: You may not fork or create competing versions
- **All Rights Reserved**: All rights remain with the copyright holder

**Full license details**: [LICENSE](LICENSE)

**For legal questions**: info@prompts-conductor.com

---

## 🔗 **Links**

- **Website**: [prompts-conductor.com](https://prompts-conductor.com)
- **Support**: info@prompts-conductor.com

---

*Built with ❤️ for AI developers and content creators*