v0.2.0 - Folder-Based Prompts & Comprehensive Version Management

[0.2.0] - 2025-09-30

🚀 Major Release: Folder-Based Prompts & Comprehensive Version Management

This is a major architectural release that fundamentally transforms how Promptix manages prompts, introducing a Git-native, folder-based structure and comprehensive version management system. This release enhances developer experience, improves Git integration, and provides professional version control for AI prompts.

🎯 Breaking Changes

Folder-Based Prompt Storage

• Migration from prompts.yaml to prompts/ directory structure
• Each prompt now lives in its own folder with dedicated configuration and version history
• Migration is automatic - existing prompts.yaml files are automatically migrated to the new structure
• New structure provides:
  • Better Git diffs (changes to individual files instead of large YAML)
  • Clearer version history with dedicated version files
  • Improved readability and organization
  • Easier collaboration and code review

New Structure:

prompts/
├── CustomerSupport/
│   ├── config.yaml          # Prompt metadata and configuration
│   ├── current.md           # Current active version
│   └── versions/
│       ├── v1.md            # Version history
│       ├── v2.md
│       └── v3.md

Old Structure (deprecated):

prompts.yaml                 # All prompts in one file

Added

Comprehensive Version Management System

• Automatic Version Creation: Pre-commit hooks automatically create new versions when current.md changes
• Version Switching: Switch between different prompt versions with CLI or config
• Version Tracking: current_version field in config.yaml tracks active version
• Version Header Removal: Automatic removal of version metadata from prompt content
• Dual Support: Backward compatibility with legacy is_live flags while supporting new current_version tracking

Enhanced CLI Tools

• promptix version command group:

  • promptix version list <agent> - List all versions for an agent
  • promptix version create <agent> - Manually create a new version
  • promptix version switch <agent> <version> - Switch to a specific version
  • promptix version get <agent> - Get current active version

• promptix hooks command group:

  • promptix hooks install - Install pre-commit hook for automatic versioning
  • promptix hooks uninstall - Remove pre-commit hook
  • promptix hooks status - Check hook installation status
  • Automatic backup/restore of existing hooks
  • Safe hook installation with error handling

Git Pre-commit Hook

• Automatic version creation when current.md files are modified
• Automatic version deployment when current_version changes in config.yaml
• Intelligent file detection and processing
• Rich console output with clear status messages
• Comprehensive error handling and edge case coverage
• Hooks directory at repository root for easy version control

Enhanced Prompt Loader

• Automatic version header removal from prompt content
• Metadata integration from version headers
• Improved error messages and handling
• Support for both legacy and new version formats
• Better caching and performance optimization

Workspace Manager

• New workspace_manager.py module for prompt workspace operations
• Handles migration from prompts.yaml to folder structure
• Validates prompt configurations
• Manages workspace consistency and integrity

Comprehensive Documentation

• VERSIONING_GUIDE.md: Complete guide to the auto-versioning system

  • Quick start instructions
  • Architecture overview
  • Workflow examples
  • Git integration details
  • Troubleshooting guide

• TESTING_VERSIONING.md: Comprehensive testing documentation

  • Test structure overview
  • How to run tests
  • Coverage information
  • Test categories and examples

Extensive Test Suite

• 21 new test files with over 5,100 lines of test code

• Unit tests:

  • test_precommit_hook.py - Pre-commit hook functionality (439 lines)
  • test_enhanced_prompt_loader.py - Enhanced prompt loader (414 lines)
  • test_version_manager.py - Version manager CLI (421 lines)
  • test_hook_manager.py - Hook manager CLI (508 lines)

• Integration tests:

  • test_versioning_integration.py - Full workflow tests (491 lines)

• Functional tests:

  • test_versioning_edge_cases.py - Edge cases and error conditions (514 lines)

• Test helpers:

  • precommit_helper.py - Testable pre-commit hook wrapper (325 lines)

Cross-Platform Testing Improvements

• Windows CI fixes for Git repository cleanup
• Cross-platform directory removal utilities in test suite
• Safe file handling for read-only files on Windows
• Improved test reliability across Ubuntu, Windows, and macOS

CI/CD Enhancements

• Updated GitHub Actions dependencies:
  • actions/checkout from v3 to v5
  • actions/setup-python from v4 to v6
  • codecov/codecov-action from v4 to v5
• Improved CI reliability and performance
• Better dependency management with Dependabot

Changed

• Version Update: Bumped from 0.1.16 to 0.2.0 (major version bump for breaking changes)
• CLI Architecture: Enhanced CLI with command groups for better organization
• Prompt Loading: Improved prompt loader with version management integration
• Configuration Management: Enhanced config handling with version tracking
• Error Messages: More descriptive error messages with actionable guidance
• Git Integration: Better Git workflow with automatic version management

Improved

• Developer Experience:

  • Clearer prompt organization with folder structure
  • Better Git diffs for prompt changes
  • Easier code review process
  • Automated version management
  • Rich console output with formatting

• Version Control:

  • Professional version management for prompts
  • Automatic version creation on changes
  • Easy switching between versions
  • Full version history tracking

• Documentation:

  • Comprehensive guides for new features
  • Clear migration instructions
  • Extensive testing documentation
  • Better README with updated examples

• Testing:

  • Extensive test coverage for new features
  • Cross-platform test reliability
  • Comprehensive edge case coverage
  • Better test organization and helpers

• Code Quality:

  • Enhanced error handling throughout
  • Better logging and debugging support
  • Improved code organization
  • More maintainable architecture

Fixed

• Windows Testing Issues: Fixed PermissionError when cleaning up Git repositories in tests
• File Handling: Improved cross-platform file operations
• Version Migration: Smooth migration from legacy to new version system
• Git Integration: Better Git hook handling and installation
• Error Recovery: Improved error recovery in version management operations

Migration Guide

From prompts.yaml to Folder Structure:

The migration is automatic when you first run Promptix after upgrading:

1. Upgrade Promptix:

   pip install --upgrade promptix

2. Run any Promptix command:

   promptix studio  # or any other command

3. Your prompts are automatically migrated:

   • prompts.yaml → prompts/ directory structure
   • All existing prompts preserved
   • Version history maintained

4. Install automatic versioning (optional but recommended):

   promptix hooks install

5. Commit changes:

   git add prompts/
   git commit -m "Migrate to folder-based prompt structure"

The old prompts.yaml file is preserved for reference but no longer used.

Technical Improvements

• Modular Architecture: Better separation of concerns with dedicated managers
• Type Safety: Enhanced type annotations throughout new code
• Performance: Improved caching and file handling
• Reliability: Comprehensive error handling and edge case coverage
• Maintainability: Cleaner code structure and better documentation

Developer Experience Enhancements

• Automated Workflows: Pre-commit hooks handle version management automatically
• Clear Console Output: Rich formatting for CLI commands
• Better Error Messages: Actionable error messages with clear guidance
• Comprehensive Documentation: Guides for all new features
• Extensive Examples: Real-world usage examples in documentation

Backward Compatibility

• Legacy support for is_live flags in configurations
• Automatic migration from old to new structure
• Dual format support during transition period
• No breaking changes to existing API methods
• Existing code continues to work without modifications

Acknowledgments

This release represents a significant evolution of Promptix, bringing professional version control practices to AI prompt management. Special thanks to all contributors and users who provided feedback and testing assistance.

v0.1.16

[0.1.16] - 2025-09-21

🚀 Major Development Infrastructure & Documentation Overhaul

This release significantly enhances the development workflow, documentation infrastructure, and project maintainability with comprehensive tooling and automation improvements.

Added

Development Infrastructure & Automation

• Comprehensive Makefile: Added extensive development commands covering installation, testing, code quality, security auditing, documentation generation, build/release, environment management, Git helpers, Docker targets, and debugging utilities
• Pre-commit Hooks Suite: Implemented comprehensive pre-commit configuration with hooks for:
  • Code formatting (Black), import sorting (isort), linting (flake8)
  • Type checking (mypy), docstring style (pydocstyle)
  • Security scanning (bandit, safety), dependency security scanning
  • Code complexity checking, spelling, YAML/Markdown formatting
  • Python issue detection and requirements file validation
• Flake8 Configuration: Added standardized linting rules with specific ignores for certain files
• Dependabot Integration: Automated dependency updates with scheduled maintenance, reviewers, commit message prefixes, and organized dependency groups

CI/CD Pipeline Enhancements

• Expanded Testing Matrix: Extended CI to support more Python versions (3.9-3.13) and operating systems (Ubuntu, Windows, macOS)
• Concurrency Management: Added concurrency settings to optimize CI resource usage
• Performance & Integration Testing: Dedicated CI jobs for performance benchmarks and integration testing
• Enhanced Workflow: Updated setup-python action, added comprehensive status checks, and final job status verification

Documentation Infrastructure

• Complete Documentation Suite: Comprehensive Sphinx-based documentation including:
  • API Reference: Full API documentation with detailed class and method references
  • Installation Guide: Multi-environment installation instructions with troubleshooting
  • Quick Start Guide: Step-by-step getting started tutorial with practical examples
  • User Guide: Comprehensive guide covering project structure, advanced features, and best practices
• Custom Styling: Enhanced documentation appearance with custom CSS for improved readability, code block styling, API documentation spacing, and professional theming
• Sphinx Configuration: Complete Sphinx setup with extensions, themes, and output configurations for HTML, LaTeX, and other formats

Project Standards & Guidelines

• Contributing Guidelines: Comprehensive CONTRIBUTING.md with development setup, code standards, testing practices, security guidelines, and pull request processes
• AI Agent Coding Directives: Established coding standards for clarity, readability, modularity, organization, documentation, testing, and data structure best practices

Enhanced Logging System

• Structured Logging: Upgraded logging module with JSON output support, configurable log levels, multiple output formats, context injection, and performance monitoring capabilities

Changed

• Version Update: Bumped version from 0.1.15 to 0.1.16 across all configuration files
• Development Dependencies: Expanded pyproject.toml with comprehensive tooling dependencies for testing, linting, documentation, security, and code analysis
• Documentation Structure: Reorganized and enhanced documentation hierarchy with improved navigation and content organization

Technical Improvements

• Code Quality Enforcement: Automated code quality checks through pre-commit hooks and CI pipeline
• Security Posture: Enhanced security scanning with bandit, safety, and dependency vulnerability detection
• Development Experience: Streamlined development workflow with Makefile targets and automated tooling
• Documentation Generation: Automated documentation building and publishing pipeline
• Testing Infrastructure: Improved test coverage tracking and performance monitoring
• Dependency Management: Automated dependency updates and security vulnerability monitoring

Developer Experience Enhancements

• Simplified Workflow: One-command setup and development operations through Makefile
• Comprehensive Tooling: Integrated code formatting, linting, type checking, and security scanning
• Enhanced Documentation: Professional-grade documentation with API references and guides
• Automated Quality Checks: Pre-commit hooks ensure code quality before commits
• Multi-environment Support: Consistent development experience across different platforms

Infrastructure & Maintenance

• Automated Updates: Dependabot configuration for seamless dependency management
• Quality Metrics: Integrated code coverage, complexity analysis, and performance benchmarks
• Cross-platform Compatibility: Enhanced CI testing across multiple Python versions and operating systems
• Security Scanning: Comprehensive security analysis and vulnerability detection.

v0.1.15.1

[v0.1.15.1]

Bug Fix for Test Suite

v0.1.15

[0.1.15] - 2025-09-11

Added

• README in tests/ directory detailing how to run tests and testing conventions

Changed

• Test performance thresholds updated to be CI-friendly
• Integration tests use working Promptix implementation by default

Fixed

• All tests passing consistently against source code (via PYTHONPATH=src)

v0.1.14

[0.1.14] - 2025-09-10

🧹 Code Quality & Architecture Enhancements

This release focuses on significant code quality improvements, reducing technical debt, and enhancing maintainability without breaking existing functionality.

Added

• Centralized Validation Engine (src/promptix/core/validation.py)
  • Unified validation system consolidating scattered validation logic
  • Pluggable validation strategies for different validation types
  • Support for variable, structural, builder, and custom validation patterns
  • Extensible architecture for future validation needs
  • Enhanced error reporting with contextual information

Changed

• Schema Validation Consolidation

  • Replaced scattered validation logic across multiple files with centralized engine
  • Updated base.py, storage/loaders.py, and components/variable_validator.py to use unified validation
  • Improved error handling and consistency across validation operations
  • Maintained backward compatibility through wrapper classes

• Duplicate Code Elimination in Adapters

  • Enhanced base adapter class (adapters/_base.py) with comprehensive common functionality
  • Extracted ~60% duplicate code from OpenAI and Anthropic adapters
  • Added common parameter validation, tool handling, and schema manipulation utilities
  • Reduced total adapter code by ~200 lines while improving consistency

• Enhanced Type Annotations

  • Added comprehensive type hints throughout the codebase
  • Improved IDE support and static analysis capabilities
  • Enhanced documentation through better type information
  • Better development experience with enhanced autocomplete and error detection

v0.1.13

[0.1.13] - 2025-09-09

🏗️ Architecture Improvements

Added

• Dependency Injection System: Implemented comprehensive DI container (container.py) for better testability and modularity
  • Support for singleton, factory, and transient service lifetimes
  • Scoped containers for isolated testing
  • Automatic dependency resolution with type checking
• Focused Component Architecture: Broke down monolithic classes into single-responsibility components
  • PromptLoader: Handles prompt loading and caching logic
  • VariableValidator: Manages schema validation and type checking
  • TemplateRenderer: Processes Jinja2 template rendering
  • VersionManager: Manages prompt versioning logic
  • ModelConfigBuilder: Builds model configurations for different providers
• Standardized Exception Hierarchy: Comprehensive custom exception system (exceptions.py)
  • Base PromptixError class with structured error details
  • Specialized exceptions for different error categories (validation, storage, tools, etc.)
  • Enhanced error messages with contextual information and debugging details
  • Support for error chaining and detailed error reporting

Changed

• Refactored Main Classes: Promptix and PromptixBuilder classes now use dependency injection
  • Maintained backward compatibility while improving internal structure
  • Better separation of concerns following Single Responsibility Principle
  • Enhanced testability through dependency injection
• Improved Error Handling: Consistent error handling patterns across the entire codebase
  • All components now use standardized exceptions
  • Better error context and debugging information
  • Graceful error recovery where appropriate

Technical Improvements

• Better Testability: All components can be easily mocked and tested in isolation
• Improved Maintainability: Clear separation of responsibilities makes code easier to understand and modify
• Enhanced Modularity: Components can be replaced or extended without affecting other parts of the system
• Type Safety: Enhanced type checking throughout the dependency injection system
• Logging Integration: Better logging integration across all components

Backward Compatibility

• All existing public APIs remain unchanged
• Existing code will continue to work without modifications
• Internal refactoring does not affect end-user experience

Developer Experience

• Cleaner, more maintainable codebase
• Better error messages with actionable information
• Improved debugging capabilities through structured error details
• Enhanced testing infrastructure for better reliability

v0.1.12

🚨 Breaking Changes

• Minimum Python version updated: Now requires Python 3.9+ (previously 3.8+)

🐛 Fixed

• Fixed TypeError: 'type' object is not subscriptable error when running on Python 3.8
• Updated type annotations in config.py to use List[Type] instead of list[Type] for better compatibility
• Updated CI/CD workflows to use Python 3.9+ for testing and publishing

🔄 Changed

• Minimum Python version requirement updated from 3.8 to 3.9
• Removed Python 3.8 from supported versions in package classifiers
• Updated Black formatter target version to py39

📦 Installation

pip install promptix==0.1.12

3. **Publish the release** - This will automatically trigger the PyPI publishing workflow!

### **What Happens Next:**
- ✅ GitHub release created with tag `v0.1.12`
- 🚀 CI/CD workflow automatically publishes to PyPI
- 📦 Users can install with `pip install promptix==0.1.12`

The fix ensures that users won't encounter the Python 3.8 compatibility error anymore, as the package now properly requires Python 3.9+ and uses compatible type annotations.

Would you like me to help with anything else for the release process?

v0.1.10

[0.1.10] - 2025-03-12

Added

• Enhanced tools_template functionality: Variables set with .with_var() are now accessible in tools_template for conditional tool selection
• Added example showcasing conditional tools selection based on variables
• Added comprehensive tests for conditional tools feature

v0.1.9

[0.1.9] - 2025-03-03

Changed

• Promptix Studio Updated
• Updated README

v0.1.8

[0.1.8] - 2025-03-03

Changed

• Updated PyProject.toml and Added MANIFEST.in
• Making the Promptix Studio fully functional.