# xissax/alpha-co-vision architecture

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

- Interactive diagram: https://gitdiagram.com/xissax/alpha-co-vision
- Repository: https://github.com/xissax/alpha-co-vision

## Overview

##### Main Architectural Components
- Camera/Capture Module – Represented in main.py (and main2exp.py for the experimental feature). This module is responsible for obtaining frames from the webcam.
- Config & Initialization – Represented by config.py that holds API keys and configuration settings.
- Image Processing Module – Represented by image_processing.py. It contains functions to convert frames (typically from OpenCV) into formats (e.g., PIL images) suitable for further processing.
- Caption Generation Module – Represented by caption_generation.py. This module uses the BLIP model (running in half-precision on Mac M1) to generate captions from images.
- Response Generation Module – Represented by response_generation.py (and possibly openai_response_generation.py). These files implement the logic to generate conversational responses using the Cohere API (and potential support for OpenAI).
- /Output Module – Implicit in main.py/main2exp.py, as the generated captions and responses are overlaid on the webcam feed. Other functionalities such as mirrored video display are also handled here.

- Flow then continues to the Caption Generation module where the BLIP model generates textual captions.
- The caption then is sent to the Response Generation module (which may branch into separate ones for Cohere and possibly OpenAI) that produces a conversational response.
- Finally, both the caption and the response are fed back to the Display module, which updates the on-screen video feed with overlays.
- A configuration snippet (from config.py) that is accessed at initialization by both the caption and response modules.

##### Architectural Patterns and Technologies
- This is essentially a pipeline architecture with a sequential flow: capture → process → caption → generate response → display.
- Edge details: the use of "half-precision (float16)" processing for performance on Mac M1, and the experimental improvements in main2exp.py (mirroring, reduced repetition, etc.).
- You may also note that there’s a modular design where each functionality (image processing, captioning, response generation) is separated into its own Python module.

##### Final Checklist
- Core modules with clear, concise labels.
- Application logic modules
- External dependencies/APIs
- Configuration components
- Special design patterns (like the pipeline or modular separation of concerns) and note where future enhancements may be integrated.

Feel free to ask if additional clarifications or further details are needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Section
    subgraph "Camera Input"
        CameraInput("Camera Input Module (main.py/main2exp.py)"):::module
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Config("Config & Initialization (config.py)"):::config
        ImageProcessing("Image Processing (image_processing.py)"):::module
        CaptionGeneration("Caption Generation (caption_generation.py)"):::module
        ResponseGen("Response Generation (response_generation.py & openai_response_generation.py)"):::module
        BLIP("BLIP Model"):::external
        Cohere("Cohere API"):::external
        OpenAI("OpenAI API"):::external
    end

    %% Output Section
    subgraph "Output"
        Display("Display/Output Module (main.py/main2exp.py)"):::module
    end

    %% Data Flow Arrows
    CameraInput -->|"frame"| ImageProcessing
    ImageProcessing -->|"processedFrame"| CaptionGeneration
    CaptionGeneration -->|"caption"| ResponseGen
    ResponseGen -->|"overlayResult"| Display
    CameraInput -->|"rawFeed"| Display

    %% Configuration Usage
    Config ---|"usedBy"| CaptionGeneration
    Config ---|"usedBy"| ResponseGen

    %% External Service Interactions
    CaptionGeneration ---|"uses"| BLIP
    ResponseGen ---|"calls"| Cohere
    ResponseGen ---|"optionallyCalls"| OpenAI

    %% Click Events for Component Mapping
    click CameraInput "https://github.com/xissax/alpha-co-vision/blob/main/main.py"
    click CameraInput "https://github.com/xissax/alpha-co-vision/blob/main/main2exp.py"
    click Config "https://github.com/xissax/alpha-co-vision/blob/main/config.py"
    click ImageProcessing "https://github.com/xissax/alpha-co-vision/blob/main/image_processing.py"
    click CaptionGeneration "https://github.com/xissax/alpha-co-vision/blob/main/caption_generation.py"
    click ResponseGen "https://github.com/xissax/alpha-co-vision/blob/main/response_generation.py"
    click ResponseGen "https://github.com/xissax/alpha-co-vision/blob/main/openai_response_generation.py"
    click Display "https://github.com/xissax/alpha-co-vision/blob/main/main.py"
    click Display "https://github.com/xissax/alpha-co-vision/blob/main/main2exp.py"

    %% Styles for Color Coding
    classDef module fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef external fill:#FFCC80,stroke:#E65100,stroke-width:2px,stroke-dasharray: 5,5;
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:2px,stroke-dasharray: 2,2;
```
