promptlifter 0.5.0

LLM-powered conversation interface with intelligent context management, real-time search integration, and seamless conversation flow

PromptLifter

A conversation-focused LLM interface with intelligent context management, optional search integration, and optimized LLM interactions for conversational AI applications. Features real-time web search, vector database integration, and seamless conversation flow with automatic context optimization.

✨ Features

• Conversation-Focused: Maintains conversation history with automatic summarization and context flow
• Intelligent Context Management: Automatic context optimization for LLM token limits with smart relevance filtering
• Real-Time Search Integration: Conditional web search (Tavily) and vector search (Pinecone) with context-aware triggering
• Seamless Conversation Flow: Builds upon previous interactions for natural, context-aware responses
• Multiple LLM Support: OpenAI, Anthropic, Google, and custom/local LLM endpoints (Ollama, Lambda Labs, Together AI)
• Smart Embedding Service: Automatic fallback embedding with support for custom and commercial providers
• Production Ready: Security-hardened, optimized, and thoroughly tested with 115+ test cases
• Flexible Configuration: Configurable search behavior, token limits, and context strategies

🚀 Quick Start

Installation

From PyPI (Recommended)

pip install promptlifter

From Source

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

Basic Usage

import asyncio
from promptlifter import ConversationLLM

async def main():
    # Initialize conversation LLM
    llm = ConversationLLM()

    # Start a conversation
    response = await llm.chat("What is machine learning?")
    print(response.message)

    # Follow-up with context (automatically uses previous conversation)
    response = await llm.chat("Can you give me an example?")
    print(response.message)

if __name__ == "__main__":
    asyncio.run(main())

Quick Chat Function

import asyncio
from promptlifter import quick_chat

async def main():
    # One-liner for simple interactions
    response = await quick_chat("Explain quantum computing")
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

Command Line Usage

# Interactive mode
promptlifter --interactive

# Single query
promptlifter --query "Research AI in healthcare applications"

# Save results to file
promptlifter --query "Quantum computing research" --save results.json

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                                USER INTERFACE                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                     │
│  │     CLI     │    │  Python API │    │ Interactive │                     │
│  │  Interface  │    │             │    │    Mode     │                     │
│  └─────────────┘    └─────────────┘    └─────────────┘                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           MAIN APPLICATION                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────────────┐ │
│  │                        ConversationLLM                                 │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │ │
│  │  │   Conversation  │  │   Context       │  │   Context       │        │ │
│  │  │    Manager      │  │   Retriever     │  │   Optimizer     │        │ │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘        │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              SERVICES LAYER                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │    LLM      │  │ Embedding   │  │   Tavily    │  │  Pinecone   │       │
│  │  Service    │  │  Service    │  │   Search    │  │   Vector    │       │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           EXTERNAL PROVIDERS                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │   OpenAI    │  │ Anthropic   │  │   Google    │  │   Custom    │       │
│  │     API     │  │     API     │  │     API     │  │    LLM      │       │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │   Web       │  │  Vector     │  │  Local      │  │   Remote    │       │
│  │  Content    │  │  Database   │  │  Models     │  │  Services   │       │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘

DATA FLOW:
User Input → CLI/API → Main App → ConversationLLM → Context Management
                                                      ↓
External Search ← Context Retriever ← Context Analysis
                                                      ↓
LLM Processing ← Context Optimizer ← Search Results + History
                                                      ↓
Response Generation → User Output

🔧 Setup

1. Clone the Repository

git clone https://github.com/promptlifter/promptlifter
cd promptlifter

2. Install Dependencies

Option 1: Install from Source

pip install -e .

Option 2: Install with Development Dependencies

pip install -e ".[dev]"

Option 3: Install with Test Dependencies

pip install -e ".[test]"

3. Configure Environment Variables

Copy the example environment file and configure your API keys:

cp env.example .env

Edit .env with your configuration:

# Custom LLM Configuration (Primary - Local Models or OpenAI-Compatible APIs)
CUSTOM_LLM_ENDPOINT=http://localhost:11434
CUSTOM_LLM_MODEL=llama3.1
CUSTOM_LLM_API_KEY=

# LLM Provider Configuration (Choose ONE provider)
LLM_PROVIDER=custom  # custom, openai, anthropic, google

# Embedding Configuration (Choose ONE provider)
EMBEDDING_PROVIDER=custom  # custom, openai, anthropic
EMBEDDING_MODEL=nomic-embed-text  # Ollama embedding model (for custom provider) or OpenAI model name

# Commercial LLM Configuration (API keys for non-custom providers)
OPENAI_API_KEY=your-openai-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GOOGLE_API_KEY=your-google-api-key-here

# Search and Vector Configuration (Optional)
TAVILY_API_KEY=your-tavily-api-key-here
PINECONE_API_KEY=your-pinecone-api-key-here
PINECONE_INDEX=your-pinecone-index-name-here
PINECONE_NAMESPACE=research

# Conversation Context Settings
MAX_HISTORY_TOKENS=4000              # Maximum tokens for conversation history
MAX_CONTEXT_TOKENS=2000              # Maximum tokens for context assembly
ENABLE_AUTO_SEARCH=true              # Enable automatic search
SEARCH_RELEVANCE_THRESHOLD=0.7       # Minimum relevance score for search results

# Pinecone Search Configuration (Optional)
PINECONE_TOP_K=10                    # Number of results (default: 10)
PINECONE_SIMILARITY_THRESHOLD=0.7    # Minimum similarity (0.0-1.0)
PINECONE_INCLUDE_SCORES=true         # Show similarity scores
PINECONE_FILTER_BY_SCORE=true        # Filter by threshold

4. Set Up LLM Providers

Option 1: Local LLM (Recommended - No API Keys Needed)

Using Ollama (Easiest)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull Llama 3.1 model
ollama pull llama3.1

# Start Ollama server
ollama serve

Using Other Local LLM Servers

• LM Studio: Run with OpenAI-compatible API
• vLLM: Fast inference server
• Custom endpoints: Any OpenAI-compatible API

Option 2: OpenAI-Compatible APIs (Requires API Keys)

Lambda Labs Setup

1. Get API key from https://cloud.lambdalabs.com/
2. Add to .env:

CUSTOM_LLM_ENDPOINT=https://api.lambda.ai/v1
CUSTOM_LLM_MODEL=llama-4-maverick-17b-128e-instruct-fp8
CUSTOM_LLM_API_KEY=your-lambda-api-key-here

Together AI Setup

1. Get API key from https://together.ai/
2. Add to .env:

CUSTOM_LLM_ENDPOINT=https://api.together.xyz/v1
CUSTOM_LLM_MODEL=meta-llama/Llama-3.1-8B-Instruct
CUSTOM_LLM_API_KEY=your-together-api-key-here

Perplexity AI Setup

1. Get API key from https://www.perplexity.ai/
2. Add to .env:

CUSTOM_LLM_ENDPOINT=https://api.perplexity.ai
CUSTOM_LLM_MODEL=llama-3.1-8b-instruct
CUSTOM_LLM_API_KEY=your-perplexity-api-key-here

Option 3: Commercial LLM (Fallback)

OpenAI Setup

1. Get API key from https://platform.openai.com/api-keys
2. Add to .env:

OPENAI_API_KEY=sk-your-actual-key-here

Anthropic Setup

1. Get API key from https://console.anthropic.com/
2. Add to .env:

ANTHROPIC_API_KEY=sk-ant-your-actual-key-here

Google Setup

1. Get API key from https://makersuite.google.com/app/apikey
2. Add to .env:

GOOGLE_API_KEY=your-actual-key-here

5. Run the Application

Interactive Mode

promptlifter --interactive
# or
python -m promptlifter.main --interactive

Single Query Mode

promptlifter --query "Research quantum computing trends"
# or
python -m promptlifter.main --query "Research quantum computing trends"

6. Run Tests

# Run all tests
python run_tests.py

# Run specific tests
python run_tests.py config

# Run with pytest directly
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=promptlifter --cov-report=html

🆕 Recent Improvements (v0.5.0+)

Enhanced Context Management

• Simplified Relevance Scoring: Removed complex keyword matching in favor of trusting search engine results
• Improved Conversation Flow: Better follow-up question handling with context-aware search triggering
• Fixed Embedding Issues: Resolved 400 errors with custom embedding models and improved fallback handling

Smart Search Integration

• Context-Aware Search: Follow-up questions now properly use conversation context instead of unnecessary external searches
• Real-Time Web Search: Tavily integration provides current information for weather, news, and research queries
• Vector Database Support: Pinecone integration for knowledge base queries with similarity scoring

Production Ready

• 115+ Test Cases: Comprehensive test coverage including unit, integration, and configuration tests
• Clean Architecture: Simplified codebase with removed complexity and improved maintainability
• Better Error Handling: Graceful fallbacks and improved error messages

Key Fixes in v0.5.0

• ✅ Fixed Embedding Service: Resolved 400 errors when using custom embedding models with Ollama
• ✅ Improved Context Flow: Follow-up questions now maintain conversation context properly
• ✅ Simplified Relevance Logic: Removed brittle keyword matching for more reliable search results
• ✅ Enhanced Test Coverage: All 115 tests passing with comprehensive coverage
• ✅ Better Error Messages: More informative error handling and debugging information

🚀 How It Works

Conversation-Focused Architecture

1. Query Input: User provides a message or question
2. Context Analysis: System determines if external search is needed
3. Intelligent Search: When needed, performs web and/or vector search
4. Context Assembly: Combines conversation history with search results
5. LLM Processing: Generates response using optimized context
6. History Management: Updates conversation history with new interaction

Key Components

ConversationLLM

• Main interface for conversational interactions
• Manages conversation history and context
• Handles search integration automatically

ConversationContextManager

• Maintains conversation history with automatic summarization
• Manages token limits and context optimization
• Provides conversation statistics and export/import

ContextRetriever

• Intelligently determines when search is needed
• Performs conditional web and vector search
• Filters results by relevance

ContextOptimizer

• Assembles optimal context for LLM inference
• Manages token limits and compression
• Prioritizes most relevant information

🎯 Configuration Options

Conversation Settings

Setting	Type	Default	Description
max_history_tokens	int	4000	Maximum tokens to keep in conversation history
max_context_tokens	int	2000	Maximum tokens for context assembly
enable_auto_search	bool	true	Enable automatic search when needed
search_relevance_threshold	float	0.7	Minimum relevance score for search results
system_prompt	str	"You are a helpful assistant."	System prompt for LLM

Search Configuration

Setting	Type	Default	Description
PINECONE_TOP_K	int	10	Number of results to retrieve
PINECONE_SIMILARITY_THRESHOLD	float	0.7	Minimum similarity score (0.0-1.0)
PINECONE_INCLUDE_SCORES	bool	true	Include similarity scores in output
PINECONE_FILTER_BY_SCORE	bool	true	Filter results by similarity threshold

🔍 Advanced Usage

Custom Configuration

import asyncio
from promptlifter import ConversationLLM, ConversationConfig

async def main():
    # Create custom configuration
    config = ConversationConfig(
        max_history_tokens=3000,
        max_context_tokens=1500,
        enable_auto_search=True,
        search_relevance_threshold=0.8,
        system_prompt="You are a research assistant specializing in AI."
    )

    # Initialize with custom config
    llm = ConversationLLM(config)

    # Use the configured LLM
    response = await llm.chat("What are the latest AI trends?")
    print(response.message)

if __name__ == "__main__":
    asyncio.run(main())

Conversation Management

# Get conversation statistics
stats = llm.get_conversation_stats()
print(f"Total turns: {stats['total_turns']}")
print(f"Current tokens: {stats['current_tokens']}")

# Export conversation history
history = llm.export_conversation()
print(f"Exported {len(history)} conversation turns")

# Clear conversation
llm.clear_conversation()

# Import conversation history
llm.import_conversation(history)

Search Statistics

# Get retrieval statistics
retrieval_stats = llm.get_retrieval_stats()
print(f"Tavily enabled: {retrieval_stats['tavily_enabled']}")
print(f"Pinecone enabled: {retrieval_stats['pinecone_enabled']}")

# Get optimization statistics
optimization_stats = llm.get_optimization_stats()
print(f"Max tokens: {optimization_stats['max_tokens']}")
print(f"Compression enabled: {optimization_stats['compression_enabled']}")

🛠️ Troubleshooting

Common Issues

No Search Results

1. Check if ENABLE_AUTO_SEARCH=true and API keys are configured
2. Verify Tavily and Pinecone API keys are valid
3. Check if your Pinecone index has data

Context Too Long

1. Reduce MAX_CONTEXT_TOKENS or enable compression
2. Lower MAX_HISTORY_TOKENS to keep less history
3. Clear conversation regularly with llm.clear_conversation()

Memory Issues

1. Reduce MAX_HISTORY_TOKENS or clear conversation regularly
2. Use smaller context windows
3. Enable context compression

API Errors

1. Verify API keys are correct and have sufficient credits
2. Check API service status
3. Review rate limiting settings

Debug Information

import asyncio
import logging
from promptlifter import ConversationLLM

async def debug_example():
    # Enable detailed logging
    logging.basicConfig(level=logging.INFO)
    
    # Initialize LLM
    llm = ConversationLLM()

    # Get detailed response information
    response = await llm.chat("Your question")
    print(f"Context sources: {response.context_sources}")
    print(f"Tokens used: {response.tokens_used}")
    print(f"Conversation stats: {response.conversation_stats}")

if __name__ == "__main__":
    asyncio.run(debug_example())

Search Debugging

# Get search statistics
retrieval_stats = llm.get_retrieval_stats()
print(f"Retrieval: {retrieval_stats}")

# Get optimization statistics
optimization_stats = llm.get_optimization_stats()
print(f"Optimization: {optimization_stats}")

📦 Development & Release

For Developers

# Install development dependencies
pip install -e ".[dev]"

# Run quality checks
tox

# Run tests
pytest tests/ -v

# Format code
black promptlifter tests

For Contributors

Please see the project repository for development guidelines and contribution instructions.

Release Process

# Setup PyPI credentials
python scripts/setup_pypi.py

# Test release to TestPyPI
python scripts/release.py test

# Release to PyPI
python scripts/release.py release

🧪 Testing

The project includes comprehensive test coverage:

• Unit Tests: Individual component testing
• Integration Tests: End-to-end functionality testing
• Configuration Tests: Environment and setup validation
• Service Tests: LLM and embedding service testing

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test suites
pytest tests/test_conversation_interface_simple.py -v
pytest tests/test_conversation_interface.py::TestIntegration -v

# Run with coverage
pytest tests/ --cov=promptlifter --cov-report=html

🔒 Security & Quality

The codebase has been thoroughly audited for security and quality:

• Security Hardened: No vulnerabilities, secure coding practices
• Code Quality: No unused code, optimized imports, clean structure
• Production Ready: Comprehensive testing, proper logging, error handling
• Maintainable: Clean architecture, well-documented, consistent style

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Please see the project repository for detailed contribution guidelines.

📄 License

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

🙏 Acknowledgments

• Ollama for local LLM deployment
• Meta for Llama models
• Tavily for web search capabilities
• Pinecone for vector search infrastructure
• OpenAI for embedding models and API
• Anthropic for Claude models and API