# tensorsofthewall/bettersearch architecture

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

- Interactive diagram: https://gitdiagram.com/tensorsofthewall/bettersearch
- Repository: https://github.com/tensorsofthewall/bettersearch

## Overview

Based on our analysis of the file structure and README content, BetterSearch is a desktop search tool that combines traditional file indexing with large language model (LLM) capabilities to transform natural language queries into search operations. In essence, it’s a hybrid application that comprises backend processing (indexing files, embedding text, and generating SQL queries using LLMs) and a simple front-end (via the Python app entry point) primarily designed for Windows at its current stage. The system uses separate components for handling file indexing, querying, and model interactions, and it supports various compute modes (CPU-only, multiple GPU modes) through different configuration files.

##### Main Components Identification
- Application Entry Point: Represented by app.py, which initializes and launches the desktop app.
- Core Modules Directory (bettersearch/):
- Setup and Initialization: bettersearch/__init__.py and setup.py for package and dependency setup.
- Source Code Directory (bettersearch/src):
- Database Component (bettersearch/src/database):
▪ File Indexing: file_indexer.py is responsible for scanning the file system and updating the index.
▪ Parsing and Utility Functions: parse.py and util.py handle file content extraction and processing.
▪ Embedding Model Integration: embedding_model.py uses advanced embedding models (gte-v1.5) to convert text files into vector representations.
▪ Constants: constants.py holds configuration or magic numbers used across the database operations.
- Pipeline Component (bettersearch/src/pipeline):
▪ Query Processing: pipeline.py orchestrates end-to-end query execution (from natural language query interpretation to final SQL generation).
▪ Prompts for LLMs: llama_prompt.md and sqlcoder_prompt.md define the templates for the LLM models.
▪ Pipeline Utilities: util.py supporting additional functions for pipeline operations.
- Configuration and Environment: Multiple configuration files (settings.cfg, various GPU JSON config files, bettersearch_env.yml) define deployment and runtime settings.
- Documentation: The docs/ folder with additional explanations and images.

##### Relationships and Interactions
- The Application Entry Point (app.py) triggers the initialization routines.
- The File Indexer from the database component continuously monitors the filesystem for changes and updates the content index. This component accesses file parsing utilities.
- The Embedding Model processes content into vector embeddings, which are then stored (possibly in an embedded database like Chroma as hinted in the README).
- The Pipeline component receives natural language queries, uses prompt templates (via llama_prompt.md and sqlcoder_prompt.md) to generate a corresponding SQL query or perform content search.
- The compute mode configurations (CPU-only and GPU variants) affect model loading details, influencing how the embedding and query generation modules interact with the hardware.
- All components communicate through clearly defined function calls within the package; directional data flow goes from user query -> pipeline processing -> file indexing/DB lookup -> LLM query generation -> final response.

##### Architectural Patterns and Design Principles
- Modular Design: Separation of concerns between file indexing (database), query processing (pipeline), and application startup.
- Extensibility: The configuration files and prompt templates make it easy to adapt to various compute settings and upgrade model integrations.
- Configuration-driven Behavior: Different JSON and YAML files adjust the compute mode and resource management.

##### Technologies and Frameworks
- Python (>=3.9) is the core language.
- LLM models such as SQLCoder and gte-v1.5 from HuggingFace are integrated.
- Dependency management via Conda (using bettersearch_env.yml).
- Libraries like LangChain, Transformers, OpenVINO, Optimum, and Chroma play key roles in model serving, optimizations, and database handling.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Desktop Application
    A["app.py"]:::desktop

    %% Core Initialization
    subgraph "Core Initialization"
        B1["__init__.py"]:::init
        B2["setup.py"]:::init
    end

    %% Connections from App to Core Initialization
    A --> B1
    A --> B2

    %% File System Indexing
    subgraph "File System Indexing"
        FI["File Indexer"]:::indexing
        FP["Parse"]:::indexing
        FU["Util"]:::indexing
        EM["Embedding Model"]:::indexing
        DC["Database Constants"]:::indexing
    end

    %% Query Processing Pipeline
    subgraph "Query Processing Pipeline"
        QP["Query Pipeline"]:::pipeline
        LLM1["Llama Prompt"]:::pipeline
        LLM2["SQLCoder Prompt"]:::pipeline
        PU["Pipeline Utilities"]:::pipeline
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        CFG1["settings.cfg"]:::config
        CFG2["cpu_only.json"]:::config
        CFG3["budget_gpu_config.json"]:::config
        CFG4["normal_gpu_config.json"]:::config
        CFG5["overkill_gpu_config.json"]:::config
        CFG6["bettersearch_env.yml"]:::config
        CI["Config Influence"]:::config
    end

    %% Documentation
    subgraph "Documentation"
        DOC["Documentation"]:::docs
    end

    %% Arrows from Core Initialization to main components
    B1 --> FI
    B2 --> FI
    B1 --> QP
    B2 --> QP

    %% Direct interactions from Desktop Application
    A -->|"trigger_indexing"| FI
    A -->|"process_query"| QP

    %% Internal connections in File System Indexing
    FI -->|"uses"| FP
    FI -->|"uses"| FU
    FI -->|"embedding"| EM
    EM -->|"const"| DC

    %% Internal connections in Query Processing Pipeline
    QP --> LLM1
    QP --> LLM2
    QP --> PU

    %% Configuration Influence on components
    CFG1 --> CI
    CFG2 --> CI
    CFG3 --> CI
    CFG4 --> CI
    CFG5 --> CI
    CFG6 --> CI
    CI -->|"configures"| EM
    CI -->|"configures"| QP

    %% Link Documentation
    B1 --> DOC

    %% Click Events
    click A "https://github.com/tensorsofthewall/bettersearch/blob/main/app.py"
    click B1 "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/__init__.py"
    click B2 "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/setup.py"
    click FI "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/database/file_indexer.py"
    click FP "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/database/parse.py"
    click FU "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/database/util.py"
    click EM "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/database/embedding_model.py"
    click DC "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/database/constants.py"
    click QP "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/pipeline/pipeline.py"
    click LLM1 "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/pipeline/llama_prompt.md"
    click LLM2 "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/pipeline/sqlcoder_prompt.md"
    click PU "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch/src/pipeline/util.py"
    click CFG1 "https://github.com/tensorsofthewall/bettersearch/blob/main/settings.cfg"
    click CFG2 "https://github.com/tensorsofthewall/bettersearch/blob/main/cpu_only.json"
    click CFG3 "https://github.com/tensorsofthewall/bettersearch/blob/main/budget_gpu_config.json"
    click CFG4 "https://github.com/tensorsofthewall/bettersearch/blob/main/normal_gpu_config.json"
    click CFG5 "https://github.com/tensorsofthewall/bettersearch/blob/main/overkill_gpu_config.json"
    click CFG6 "https://github.com/tensorsofthewall/bettersearch/blob/main/bettersearch_env.yml"
    click DOC "https://github.com/tensorsofthewall/bettersearch/tree/main/docs/"

    %% Styles
    classDef desktop fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef init fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef indexing fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef pipeline fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef docs fill:#FFB6C1,stroke:#000,stroke-width:1px;
```
