# sudohopex/kaligpt architecture

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

- Interactive diagram: https://gitdiagram.com/sudohopex/kaligpt
- Repository: https://github.com/sudohopex/kaligpt

## Overview

#### Purpose and Entry Points
HackerX/KaliGPT is a Linux command-line AI assistant aimed at ethical-hacking and cybersecurity workflows. Its installed `kaligpt` command routes user prompts to selectable AI providers, supports interactive model/tool management, can launch provider web chats, and manages provider credentials. The Python package entry point is `agents/__main__.py`; package initialization is in `agents/__init__.py`. Installation is orchestrated by `install.sh` and platform installers under `installers/`.

#### CLI Orchestration
`agents/__main__.py` is the top-level control boundary for command parsing and modes such as Gemini, Ollama, OpenRouter, ChatGPT, LiteLLM, web launch, API-key setup, update, and provider listing. It dispatches into provider implementations rather than exposing a web service. Provider/model configuration and persistent selection logic are centralized under:
- `agents/utils/agent_management.py`
- `agents/utils/agent_configs.py`
- `agents/utils/api.config.json`

#### Provider Adapter Layer
Each supported backend has a dedicated adapter module, insulating the CLI and shared agent flow from vendor SDK/API differences:
- `agents/gemini.py`
- `agents/chatgpt.py`
- `agents/ollama.py`
- `agents/openrouter.py`
- `agents/litellm_provider.py`

Gemini, OpenAI/ChatGPT, OpenRouter, and LiteLLM are network-backed providers requiring credentials; Ollama targets a local runtime but may also access cloud-hosted models. LiteLLM is the broad-provider integration point, advertised as supporting 100+ vendors.

#### Agent Conversation and Response Flow
A typical invocation flows from CLI mode/prompt selection to provider/model resolution, prompt construction, model execution, optional tool-call handling, and terminal rendering. Shared interaction responsibilities are separated into:
- `agents/utils/prompts.py`
- `agents/utils/parse_n_print_response.py`
- `agents/utils/openai_tool_adapter.py`

The OpenAI tool adapter is an important compatibility boundary: it likely normalizes tool/function-call semantics for provider responses into the application’s tool execution flow. Ollama-specific tool-thinking capability detection is isolated in `agents/utils/ollama_tool_think_support_check.py`.

#### Tool Execution and Web Retrieval
The agent can expose tools to models and execute actions locally or through external retrieval services. Tool implementations are grouped in:
- `agents/utils/tools/locals.py`
- `agents/utils/tools/web_request_framework.py`
- `agents/utils/tools/opensearchapi.py`

`locals.py` represents host-local actions, creating the principal boundary between model output and the user’s machine. Web requests are mediated by a shared framework, while OpenSearchAPI is a distinct external search service integration. `agents/utils/openserp_management.py` manages the search-service-facing behavior/configuration.

#### Configuration, Credentials, and User-Facing Launching
Provider API configuration is stored in `agents/utils/api.config.json`; agent defaults and model choices are handled through the agent configuration/management modules. The separate web-chat launcher uses:
- `agents/web_launcher.py`
- `agents/utils/web_launcher.json`

This path opens official provider web interfaces rather than sending requests through the CLI provider adapters.

#### Runtime and Delivery
The runtime is Python with dependencies declared in `requirements/pip-requirements.txt`. Delivery is shell-based: `install.sh` selects or invokes platform-specific scripts for Arch, Debian-family Linux, and Termux:
- `installers/installer.arch.sh`
- `installers/installer.deb.sh`
- `installers/installer.termux.sh`

The repository also contains a focused LiteLLM integration test at `tests/test_litellm_provider.py`, reflecting the provider abstraction’s external dependency risk.

Main entry points: [`agents/utils/prompts.py`](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/prompts.py) (Prompt builder), [`agents/utils/parse_n_print_response.py`](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/parse_n_print_response.py) (Response renderer), [`agents/__main__.py`](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/__main__.py) (kaligpt CLI entry), [`agents/utils/agent_management.py`](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/agent_management.py) (Agent management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Conversation"]
  node_entry["kaligpt CLI entry<br/>Python entry point<br/>[__main__.py]"]
  node_management["Agent management<br/>configuration service"]
  node_agent_configs["Agent defaults<br/>configuration module<br/>[agent_configs.py]"]
  node_api_config["Provider API config<br/>JSON configuration<br/>[api.config.json]"]
  node_prompts["Prompt builder<br/>conversation module<br/>[prompts.py]"]
  node_response_parser["Response renderer<br/>conversation module"]
  node_tool_adapter["OpenAI tool adapter<br/>compatibility adapter"]
  node_web_launcher["Provider web launcher<br/>browser launcher<br/>[web_launcher.py]"]
  node_web_launcher_config["Web launcher config<br/>JSON configuration<br/>[web_launcher.json]"]
end

subgraph group_providers["Provider Adapters"]
  node_gemini["Gemini<br/>provider adapter<br/>[gemini.py]"]
  node_chatgpt["ChatGPT<br/>provider adapter<br/>[chatgpt.py]"]
  node_ollama["Ollama<br/>provider adapter<br/>[ollama.py]"]
  node_openrouter["OpenRouter<br/>provider adapter<br/>[openrouter.py]"]
  node_litellm["LiteLLM<br/>provider adapter"]
  node_ollama_capability["Ollama tool-thinking check<br/>capability detection"]
end

subgraph group_tools["Tool Execution"]
  node_local_tools["Local tools<br/>host action tools<br/>[locals.py]"]
  node_web_framework["Web request framework<br/>retrieval framework"]
  node_opensearch["OpenSearchAPI<br/>external search integration<br/>[opensearchapi.py]"]
  node_openserp_management["Search service management<br/>search configuration"]
end

subgraph group_delivery["Runtime &amp; Delivery"]
  node_python_deps["Python dependencies<br/>dependency manifest"]
  node_installer["Linux installers<br/>shell delivery<br/>[install.sh]"]
end

node_entry -->|"selects provider/model"| node_management
node_management -->|"loads defaults"| node_agent_configs
node_management -->|"reads API settings"| node_api_config
node_entry -->|"builds request"| node_prompts
node_prompts -->|"prompt"| node_gemini
node_prompts -->|"prompt"| node_chatgpt
node_prompts -->|"prompt"| node_ollama
node_prompts -->|"prompt"| node_openrouter
node_prompts -->|"prompt"| node_litellm
node_ollama -.->|"checks tool support"| node_ollama_capability
node_gemini -->|"model response"| node_response_parser
node_chatgpt -->|"model response"| node_response_parser
node_ollama -->|"model response"| node_response_parser
node_openrouter -->|"model response"| node_response_parser
node_litellm -->|"model response"| node_response_parser
node_response_parser -->|"tool calls"| node_tool_adapter
node_tool_adapter -->|"executes local actions"| node_local_tools
node_tool_adapter -->|"executes retrieval"| node_web_framework
node_web_framework -->|"search request"| node_opensearch
node_openserp_management -.->|"configures"| node_opensearch
node_entry -->|"web-chat mode"| node_web_launcher
node_web_launcher -->|"loads destinations"| node_web_launcher_config
node_installer -->|"installs runtime dependencies"| node_python_deps

click node_entry "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/__main__.py"
click node_management "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/agent_management.py"
click node_agent_configs "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/agent_configs.py"
click node_api_config "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/api.config.json"
click node_prompts "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/prompts.py"
click node_response_parser "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/parse_n_print_response.py"
click node_tool_adapter "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/openai_tool_adapter.py"
click node_gemini "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/gemini.py"
click node_chatgpt "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/chatgpt.py"
click node_ollama "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/ollama.py"
click node_openrouter "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/openrouter.py"
click node_litellm "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/litellm_provider.py"
click node_ollama_capability "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/ollama_tool_think_support_check.py"
click node_local_tools "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/locals.py"
click node_web_framework "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/web_request_framework.py"
click node_opensearch "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/opensearchapi.py"
click node_openserp_management "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/openserp_management.py"
click node_web_launcher "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/web_launcher.py"
click node_web_launcher_config "https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/web_launcher.json"
click node_python_deps "https://github.com/sudohopex/kaligpt/blob/hackerx/requirements/pip-requirements.txt"
click node_installer "https://github.com/sudohopex/kaligpt/blob/hackerx/install.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_management,node_agent_configs,node_api_config,node_prompts,node_response_parser,node_tool_adapter,node_web_launcher,node_web_launcher_config toneBlue
class node_gemini,node_chatgpt,node_ollama,node_openrouter,node_litellm,node_ollama_capability toneAmber
class node_local_tools,node_web_framework,node_opensearch,node_openserp_management toneMint
class node_python_deps,node_installer toneRose
```

## Components

### CLI & Conversation

- [kaligpt CLI entry](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/__main__.py): Python entry point · Parses modes and dispatches provider, setup, update, and web-launch commands. · `agents/__main__.py`
- [Agent management](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/agent_management.py): configuration service · Resolves persistent provider and model selections. · `agents/utils/agent_management.py`
- [Agent defaults](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/agent_configs.py): configuration module · `agents/utils/agent_configs.py`
- [Provider API config](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/api.config.json): JSON configuration · Stores provider API settings and credentials metadata. · `agents/utils/api.config.json`
- [Prompt builder](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/prompts.py): conversation module · `agents/utils/prompts.py`
- [Response renderer](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/parse_n_print_response.py): conversation module · Parses model output and renders terminal responses. · `agents/utils/parse_n_print_response.py`
- [OpenAI tool adapter](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/openai_tool_adapter.py): compatibility adapter · Normalizes tool/function calls into the execution flow. · `agents/utils/openai_tool_adapter.py`
- [Provider web launcher](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/web_launcher.py): browser launcher · Opens official provider web chat interfaces. · `agents/web_launcher.py`
- [Web launcher config](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/web_launcher.json): JSON configuration · `agents/utils/web_launcher.json`

### Provider Adapters

- [Gemini](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/gemini.py): provider adapter · `agents/gemini.py`
- [ChatGPT](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/chatgpt.py): provider adapter · `agents/chatgpt.py`
- [Ollama](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/ollama.py): provider adapter · Targets the local Ollama runtime or cloud-hosted models. · `agents/ollama.py`
- [OpenRouter](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/openrouter.py): provider adapter · `agents/openrouter.py`
- [LiteLLM](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/litellm_provider.py): provider adapter · Broad integration path for 100+ vendors. · `agents/litellm_provider.py`
- [Ollama tool-thinking check](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/ollama_tool_think_support_check.py): capability detection · `agents/utils/ollama_tool_think_support_check.py`

### Tool Execution

- [Local tools](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/locals.py): host action tools · Principal boundary for model-directed actions on the user's machine. · `agents/utils/tools/locals.py`
- [Web request framework](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/web_request_framework.py): retrieval framework · `agents/utils/tools/web_request_framework.py`
- [OpenSearchAPI](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/tools/opensearchapi.py): external search integration · `agents/utils/tools/opensearchapi.py`
- [Search service management](https://github.com/sudohopex/kaligpt/blob/hackerx/agents/utils/openserp_management.py): search configuration · `agents/utils/openserp_management.py`

### Runtime & Delivery

- [Python dependencies](https://github.com/sudohopex/kaligpt/blob/hackerx/requirements/pip-requirements.txt): dependency manifest · `requirements/pip-requirements.txt`
- [Linux installers](https://github.com/sudohopex/kaligpt/blob/hackerx/install.sh): shell delivery · Platform installers for Arch, Debian-family Linux, and Termux. · `install.sh`

## Connections

- kaligpt CLI entry → Agent management: selects provider/model
- Agent management → Agent defaults: loads defaults
- Agent management → Provider API config: reads API settings
- kaligpt CLI entry → Prompt builder: builds request
- Prompt builder → Gemini: prompt
- Prompt builder → ChatGPT: prompt
- Prompt builder → Ollama: prompt
- Prompt builder → OpenRouter: prompt
- Prompt builder → LiteLLM: prompt
- Ollama → Ollama tool-thinking check: checks tool support
- Gemini → Response renderer: model response
- ChatGPT → Response renderer: model response
- Ollama → Response renderer: model response
- OpenRouter → Response renderer: model response
- LiteLLM → Response renderer: model response
- Response renderer → OpenAI tool adapter: tool calls
- OpenAI tool adapter → Local tools: executes local actions
- OpenAI tool adapter → Web request framework: executes retrieval
- Web request framework → OpenSearchAPI: search request
- Search service management → OpenSearchAPI: configures
- kaligpt CLI entry → Provider web launcher: web-chat mode
- Provider web launcher → Web launcher config: loads destinations
- Linux installers → Python dependencies: installs runtime dependencies