# GEMINI.md

## Project Overview

This project is a Streamlit web application called "AI Prompt Optimizer" with enhanced UI/UX and advanced optimization capabilities. Its purpose is to help users reduce the cost of using large language models (LLMs) by intelligently optimizing their prompts. It shortens prompts by removing filler words, simplifying phrases, and using sophisticated linguistic techniques, thereby reducing the number of tokens sent to the API. The application provides real-time analysis of optimizations and displays accurate cost savings for various popular LLM providers.

The LLM-based optimizer features 8 specialized personas and uses the Tavily Search API to enhance prompts with real-time information. The application now provides actual analysis of transformations applied rather than generic templates.

The main technologies used are:

*   **Streamlit:** For the modern, gradient-based user interface with responsive design.
*   **spaCy:** For natural language processing (NLP) tasks like identifying parts of speech.
*   **tiktoken:** For accurately counting tokens using model-specific encodings (`o200k_base` for GPT-5).
*   **Lemminflect:** For lemmatization (reducing words to their base form).
*   **LangChain:** For LLM integration, tool usage, and usage metadata tracking.
*   **Tavily:** For web search integration.
*   **UsageMetadataCallbackHandler:** For tracking actual API token consumption.

The architecture is simple:

*   `app.py`: Contains the Streamlit UI code, handling user input and displaying the results.
*   `engine.py`: Contains the core prompt optimization logic in the `AdvancedPromptOptimizer` class.
*   `llm_optimizer.py`: Contains the logic for the LLM-based optimizer.

## Architecture Deep Dive

This section provides a more detailed look at how the different parts of the application work together.

### `app.py` - The Enhanced User Interface

`app.py` is the main entry point of the application. It's responsible for creating a modern, professional user interface using the Streamlit library. Here's a breakdown of its key functions:

*   **Enhanced UI Layout:** Features a gradient-based header, card-style components, and responsive side-by-side layouts for optimizer options.
*   **Advanced Styling:** Includes custom CSS for modern buttons, hover effects, and professional visual hierarchy.
*   **Smart Input Organization:** Side-by-side layout for spaCy optimization level and GPT-5 persona/API key inputs.
*   **User Input:** Creates intuitive input fields including text areas, dropdowns, sliders, and secure password inputs for API keys.
*   **Orchestration:** When the user clicks "Optimize", `app.py` orchestrates the optimization process by calling the appropriate optimizer module based on user selection.
*   **Advanced Results Display:** Shows optimized prompts, real-time optimization analysis, accurate token savings, cost metrics, and actual API usage statistics.

### `engine.py` - The Local Optimizer

`engine.py` contains the `AdvancedPromptOptimizer` class, which implements the local, rule-based optimization logic. This optimizer does not require an internet connection or any API keys. It uses the following techniques to optimize the prompt:

*   **Filler Word Removal:** It removes common filler words (e.g., "very", "really", "actually") that don't add much meaning to the prompt.
*   **Phrase Simplification:** It replaces complex phrases with simpler alternatives (e.g., "in order to" with "to").
*   **Lemmatization:** It reduces words to their base form (e.g., "running" to "run"). This is done using the `lemminflect` library.

### `llm_optimizer.py` - The Advanced LLM-based Optimizer

`llm_optimizer.py` contains the logic for the LLM-based optimizer with advanced analysis capabilities. This optimizer uses a large language model (`openai/gpt-5-chat-latest`) to perform context-aware optimization with real-time analysis. Here's how it works:

*   **API Call with Tracking:** Makes API calls to the AIMLAPI endpoint using `UsageMetadataCallbackHandler` to capture actual token usage.
*   **8 Specialized Personas:** Each persona provides specific role-based optimization:
    - Default, UI/UX Designer, Software Engineer, Marketing Copywriter
    - Creative Writer, Technical Writer, Legal Advisor, Medical Professional, Financial Analyst
*   **Real Optimization Analysis:** The `analyze_prompt_changes()` function analyzes actual transformations:
    - Detects removed filler words
    - Identifies sentence restructuring
    - Tracks passive-to-active voice conversion
    - Measures vocabulary simplification
*   **Advanced Tokenization:** Uses `get_accurate_token_count()` with model-specific encodings (`o200k_base` for GPT-5)
*   **Tavily Search Integration:** Enhances prompts with real-time web information
*   **Comprehensive Return Data:** Returns optimized prompt, changes analysis, and token usage metadata

### Advanced Cost Calculation & Analysis

The application provides sophisticated cost analysis with multiple layers of accuracy:

*   **Model-Specific Tokenization:** Uses `o200k_base` encoding for GPT-5 and latest models, with automatic fallback to `cl100k_base`
*   **Real Usage Tracking:** Captures actual API token consumption through `UsageMetadataCallbackHandler`
*   **Cost Breakdown:** Displays separate input/output cost analysis with savings calculations
*   **Visual Metrics:** Shows percentage savings, token reduction, and cost reduction in professional card layouts
*   **Model Rates:** Pre-configured cost rates for GPT-4, Claude Opus, Claude Sonnet, LLaMA 2, and custom models

## Building and Running

To build and run the project, follow these steps:

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/yourusername/ai-prompt-optimizer.git
    ```
2.  **Navigate to the project directory:**
    ```bash
    cd ai-prompt-optimizer
    ```
3.  **Install the dependencies:**
    ```bash
    pip install -r requirements.txt
    ```
4.  **Create a `.env` file** in the root of the project and add your API keys:
    ```
    AIMLAPI_API_KEY=<YOUR_API_KEY>
    TAVILY_API_KEY=<YOUR_TAVILY_API_KEY>
    ```
5.  **Run the Streamlit application:**
    ```bash
    streamlit run app.py
    ```

## Development Conventions

*   The code is well-structured and follows Python best practices.
*   The `engine.py` file is dedicated to the core logic, separating it from the UI code in `app.py`.
*   The use of `requirements.txt` ensures that the project's dependencies are clearly defined and can be easily installed.
*   The `README.md` file is comprehensive and provides clear instructions for installation and usage.