# talgaon4/promptcraft-api architecture

> Architecture diagram of the GitHub repository talgaon4/promptcraft-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/talgaon4/promptcraft-api
- Repository: https://github.com/talgaon4/promptcraft-api

## Overview

##### Project type and purpose
- This is a Python-based full-stack API library (PromptCraft API) with an interactive Streamlit frontend.
- Purpose: automatically optimize AI prompts by tracking usage, collecting feedback, and iteratively generating improved prompt versions via an LLM service.

##### File structure
- Top level:
- interface/: Streamlit app (interface/app.py, interface/launch.py)
- prompt_optimizer/: core library code
- tests, test_*.py: unit/integration tests
- prompt_optimizer modules:
- api.py, auto_optimizer.py, optimization_manager.py – external entrypoints
- core/: feedback_collector, models, optimizer_engine, prompt_manager, response_tracker
- services/llm_service.py – integration with external LLMs
- storage/: base & local_storage (persistence)
- strategies/: optimization strategies (bandit, reward_model, etc.)

##### README insights
- Exposes a PromptOptimizer class for registration, usage recording, feedback capture, and optimization.
- Dependencies: Python, Streamlit, LLM provider SDK.

a. Main components
1. Client Layer
- CLI / Python consumer using PromptOptimizer API
- Streamlit Web UI
2. API Layer
- prompt_optimizer/api.py
3. Core Engine
- Prompt Manager (register, versioning)
- Feedback Collector
- Response Tracker
- Optimizer Engine (orchestration)
- Optimization Manager & auto-optimizer
4. Strategy Modules
- Reward model bandit
- Simple AI strategy
- Component strategies (promotion, shadow testing, etc.)
5. Services
- LLM Service (external API wrapper)
6. Storage
- Local Storage (JSON, file, or extendable base storage)
b. Relationships and interactions
- Client → API: calls register_prompt, record_prompt_use, record_response, record_feedback, optimize_prompt
- API → Core Engine: delegates business logic
- Core Engine → Services/LLM: sends prompt text, retrieves LLM responses during optimization
- Core Engine → Storage: persists prompts, instances, responses, feedback, version history
- Strategy Modules are invoked by the Optimizer Engine to decide how to generate next prompt versions
- Streamlit UI ↔ API: REST-like or direct import for interactive operations and real-time visualizations
c. Architectural patterns & principles
- Layered architecture: separation between interface, API, business logic, persistence, and external services
- Strategy pattern: pluggable optimization algorithms under strategies/
- Dependency inversion: core refers to abstract storage base and LLM service interfaces
- Single responsibility: each module focuses on one aspect (e.g., feedback collection vs. prompt management)
d. Key technologies & frameworks
- Python (3.x)
- Streamlit (interface)
- External LLM provider SDK (wrapped in llm_service.py)
- Local JSON/file storage (local_storage.py) – swapable for databases

##### Detail
- Version history flow in the Prompt Manager component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLIConsumer["CLI / Python Consumer"]:::client
        StreamlitApp["Streamlit App"]:::client
        StreamlitLauncher["Streamlit Launcher"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["PromptCraft API<br/>(prompt_optimizer/api.py)"]:::api
    end

    %% Core Engine Layer
    subgraph "Core Engine" 
        PromptManager["Prompt Manager<br/>(prompt_optimizer/core/prompt_manager.py)"]:::core
        FeedbackCollector["Feedback Collector<br/>(prompt_optimizer/core/feedback_collector.py)"]:::core
        ResponseTracker["Response Tracker<br/>(prompt_optimizer/core/response_tracker.py)"]:::core
        OptimizationManager["Optimization Manager<br/>(prompt_optimizer/optimization_manager.py)"]:::core
        AutoOptimizer["Auto-Optimizer<br/>(prompt_optimizer/auto_optimizer.py)"]:::core
        OptimizerEngine["Optimizer Engine<br/>(prompt_optimizer/core/optimizer_engine.py)"]:::core
    end

    %% Strategy Modules
    subgraph "Strategy Modules"
        BaseStrategy["Base Strategy<br/>(prompt_optimizer/strategies/base_strategy.py)"]:::strategy
        RewardModelBandit["RewardModelBandit Strategy<br/>(reward_model_bandit.py)"]:::strategy
        SimpleAIStrategy["Simple AI Strategy<br/>(prompt_optimizer/strategies/simple_ai_strategy.py)"]:::strategy
        BanditComponent["Bandit Component<br/>(prompt_optimizer/strategies/components/bandit.py)"]:::strategy
        PromotionComponent["Promotion Component<br/>(prompt_optimizer/strategies/components/promotion.py)"]:::strategy
        ShadowTestingComponent["Shadow Testing Component<br/>(prompt_optimizer/strategies/components/shadow_testing.py)"]:::strategy
    end

    %% External Services
    subgraph "External Services"
        LLMService["LLM Service<br/>(prompt_optimizer/services/llm_service.py)"]:::external
    end

    %% Storage Layer
    subgraph "Storage"
        StorageBase["Storage Base<br/>(prompt_optimizer/storage/base.py)"]:::storage
        LocalStorage["Local Storage<br/>(prompt_optimizer/storage/local_storage.py)"]:::storage
    end

    %% Relationships
    StreamlitLauncher -->|launches| StreamlitApp
    CLIConsumer -->|calls API| API
    StreamlitApp -->|uses API| API

    API -->|register/record/optimize| PromptManager
    API -->|record responses| ResponseTracker
    API -->|collect feedback| FeedbackCollector
    API -->|manage optimization| OptimizationManager
    API -->|orchestrate auto-opt| AutoOptimizer

    OptimizationManager -->|coordinate| OptimizerEngine
    AutoOptimizer -->|trigger| OptimizerEngine

    OptimizerEngine -->|invoke| BaseStrategy
    BaseStrategy --> RewardModelBandit
    BaseStrategy --> SimpleAIStrategy

    RewardModelBandit --> BanditComponent
    RewardModelBandit --> PromotionComponent
    RewardModelBandit --> ShadowTestingComponent

    PromptManager -->|persist prompts| StorageBase
    ResponseTracker -->|persist responses| StorageBase
    FeedbackCollector -->|persist feedback| StorageBase
    OptimizerEngine -->|store new versions| StorageBase

    OptimizerEngine -->|call LLM| LLMService
    StorageBase -.->|implements| LocalStorage

    %% Click Events
    click StreamlitApp "https://github.com/talgaon4/promptcraft-api/blob/master/interface/app.py"
    click StreamlitLauncher "https://github.com/talgaon4/promptcraft-api/blob/master/interface/launch.py"
    click CLIConsumer "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/api.py"
    click API "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/api.py"
    click PromptManager "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/core/prompt_manager.py"
    click FeedbackCollector "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/core/feedback_collector.py"
    click ResponseTracker "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/core/response_tracker.py"
    click OptimizerEngine "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/core/optimizer_engine.py"
    click OptimizationManager "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/optimization_manager.py"
    click AutoOptimizer "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/auto_optimizer.py"
    click LLMService "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/services/llm_service.py"
    click StorageBase "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/storage/base.py"
    click LocalStorage "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/storage/local_storage.py"
    click BaseStrategy "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/base_strategy.py"
    click RewardModelBandit "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/reward_model_bandit.py"
    click BanditComponent "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/components/bandit.py"
    click PromotionComponent "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/components/promotion.py"
    click ShadowTestingComponent "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/components/shadow_testing.py"
    click SimpleAIStrategy "https://github.com/talgaon4/promptcraft-api/blob/master/prompt_optimizer/strategies/simple_ai_strategy.py"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef api fill:#DFF7DF,stroke:#28a745,color:#155724,stroke-width:1px;
    classDef core fill:#E3F2FD,stroke:#1976d2,color:#0D47A1,stroke-width:1px;
    classDef strategy fill:#FFF4E5,stroke:#FF9800,color:#E65100,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#4A148C,stroke-width:1px;
    classDef storage fill:#F5F5F5,stroke:#9E9E9E,color:#424242,stroke-width:1px,stroke-dasharray: 5 5;
```
