# dtnewman/zev architecture

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

- Interactive diagram: https://gitdiagram.com/dtnewman/zev
- Repository: https://github.com/dtnewman/zev

## Overview

##### Project type and purpose
- Zev is a Python‐based CLI tool whose job is to translate natural‐language queries into shell commands by calling out to large language model (LLM) backends (OpenAI, Google Gemini, or Ollama). It is an open‐source utility focused on command discovery and safety checks.

##### File structure
- Top‐level:
- pyproject.toml, README.md, LICENSE, .github/workflows/publish.yml
- src/zev:
- main.py – the CLI entrypoint
- config/ – setup routines and typed config objects
- constants.py – global constants
- utils.py – helper routines (e.g. clipboard, formatting)
- llms/ – core abstraction (inference_provider_base.py, llm.py, types.py) plus three subfolders (gemini/, openai/, ollama/) each containing a provider adapter and a setup module.

##### README for additional insights
- Describes interactive vs direct‐query modes, supported providers, setup process, safety warnings, and dependencies (xclip, wl-clipboard) for clipboard integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CLI
    User["User"]:::external -->|invokes zev CLI| CLI["CLI Interface"]:::core

    %% Subgraphs
    subgraph "CLI Layer"
        CLI
        Constants["Global Constants"]:::core
    end

    subgraph "Configuration Manager" 
        Setup["Config Setup"]:::core
        Types["Config Types"]:::core
    end

    subgraph "Utility & Safety"
        Utils["Utils & Safety Checker"]:::core
    end

    subgraph "LLM Abstraction" 
        Base["InferenceProviderBase"]:::abstraction
        Impl["LLM Interface"]:::abstraction
        LLTypes["Shared Types"]:::abstraction
    end

    subgraph "Provider Adapters" 
        subgraph OpenAI
            OAIProv["OpenAIProvider"]:::abstraction
            OASetup["OpenAI Setup"]:::abstraction
        end
        subgraph Gemini
            GemProv["GeminiProvider"]:::abstraction
            GemSetup["Gemini Setup"]:::abstraction
        end
        subgraph Ollama
            OllProv["OllamaProvider"]:::abstraction
            OllSetup["Ollama Setup"]:::abstraction
        end
    end

    subgraph "External Services"
        OAAPI["OpenAI API"]:::external
        GemAPI["Google Gemini API"]:::external
        OllAPI["Ollama Local Server"]:::external
    end

    subgraph "OS Integration"
        Clipboard["Clipboard Tools"]:::os
        Shell["Shell Execution"]:::os
    end

    %% Connections
    CLI -->|loads config| Setup
    CLI -->|loads config| Types
    CLI -->|reads constants| Constants
    CLI -->|passes query| Utils
    Utils -->|checked query| Base
    Base -->|uses types| LLTypes
    Base -->|delegates to| Impl
    Impl -->|selects adapter| OAIProv
    Impl -->|selects adapter| GemProv
    Impl -->|selects adapter| OllProv
    OAIProv -->|API key+payload| OAAPI
    GemProv -->|API key+payload| GemAPI
    OllProv -->|API payload| OllAPI
    OAAPI -->|raw response| OAIProv
    GemAPI -->|raw response| GemProv
    OllAPI -->|raw response| OllProv
    OAIProv -->|normalized cmd| Utils
    GemProv -->|normalized cmd| Utils
    OllProv -->|normalized cmd| Utils
    Utils -->|safety re-check| CLI
    CLI -->|output cmd| Clipboard
    CLI -->|execute cmd| Shell

    %% Click Events
    click CLI "https://github.com/dtnewman/zev/blob/main/src/zev/main.py"
    click Setup "https://github.com/dtnewman/zev/blob/main/src/zev/config/setup.py"
    click Types "https://github.com/dtnewman/zev/blob/main/src/zev/config/types.py"
    click Constants "https://github.com/dtnewman/zev/blob/main/src/zev/constants.py"
    click Utils "https://github.com/dtnewman/zev/blob/main/src/zev/utils.py"
    click Base "https://github.com/dtnewman/zev/blob/main/src/zev/llms/inference_provider_base.py"
    click Impl "https://github.com/dtnewman/zev/blob/main/src/zev/llms/llm.py"
    click LLTypes "https://github.com/dtnewman/zev/blob/main/src/zev/llms/types.py"
    click OAIProv "https://github.com/dtnewman/zev/blob/main/src/zev/llms/openai/provider.py"
    click OASetup "https://github.com/dtnewman/zev/blob/main/src/zev/llms/openai/setup.py"
    click GemProv "https://github.com/dtnewman/zev/blob/main/src/zev/llms/gemini/provider.py"
    click GemSetup "https://github.com/dtnewman/zev/blob/main/src/zev/llms/gemini/setup.py"
    click OllProv "https://github.com/dtnewman/zev/blob/main/src/zev/llms/ollama/provider.py"
    click OllSetup "https://github.com/dtnewman/zev/blob/main/src/zev/llms/ollama/setup.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef abstraction fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    classDef external fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
    classDef os fill:#e0e0e0,stroke:#737373,stroke-width:2px
    class User,OAAPI,GemAPI,OllAPI external
```
