# 3mper0rr/dualminddiffai architecture

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

- Interactive diagram: https://gitdiagram.com/3mper0rr/dualminddiffai
- Repository: https://github.com/3mper0rr/dualminddiffai

## Overview

1. **What this repo is**
   - DualMindDiffAI is a Python project with two distinct workflows:
     - a **dual-LLM comparison pipeline** that analyzes the same input through two model paths and diffs the results
     - a **function-calling agent** that can use tools like file access, URL fetching, CVE lookup, and safe shell commands

2. **Primary entry points**
   - `main.py` drives the dual-analysis workflow.
   - `fc_module.py` drives the tool-using function-calling workflow.
   - `menu.sh` is likely a convenience wrapper for interactive launching, but not a core subsystem.

3. **DualMind analysis flow**
   - Input begins as a local text file, typically `data/sample.txt`.
   - `core/loader.py` is the ingestion boundary for reading document content.
   - `main.py` sends that content, along with a prompt, into two separate model paths:
     - **safe** analysis
     - **raw** analysis
   - The two outputs are then compared by `core/diff.py`, which produces the “DIFF” section shown in the README.

4. **Safe vs raw model boundary**
   - `engines/safe.py` and `engines/raw.py` represent two LLM-facing execution modes.
   - The architecture treats these as separate analysis channels, not just model aliases.
   - The output contract is simple and user-facing:
     - SAFE = filtered or constrained interpretation
     - RAW = less filtered interpretation
     - DIFF = comparison of reasoning differences

5. **Shared model/provider layer**
   - `llm.py` is the likely shared abstraction for calling external model APIs.
   - The README indicates support for:
     - **Ollama cloud**
     - **Google Gemini**
   - This suggests the repo is provider-agnostic at the orchestration layer, with provider details pushed into engine/client code rather than the main pipeline.

6. **Function-calling subsystem**
   - `fc_module.py` is a separate architecture from the diff pipeline.
   - It exposes a command-line interface where a natural-language prompt is interpreted into tool use.
   - Supported provider targets in the README are:
     - Google Gemini
     - Groq
     - OpenRouter
   - This module is more agentic: the model decides which tools to call, possibly in sequence.

7. **Available tools and external boundaries**
   - The function-calling system can access:
     - local files (`read_file`, `list_files`)
     - report output (`save_report`)
     - network resources (`fetch_url`)
     - CVE intelligence via NVD (`search_cve`)
     - constrained shell execution (`run_command`)
   - This creates a clear boundary between model reasoning and real-world side effects.

8. **Safety boundary for shell execution**
   - `run_command` is explicitly restricted to a small allowlist:
     - `nmap`, `whois`, `dig`, `curl`, `ping`, `ls`, `cat`, `file`, `strings`
   - This is important architecturally because it prevents the agent from being a general-purpose shell executor.

9. **Data directories and persistence**
   - `data/` contains input artifacts, with `sample.txt` as the reference document.
   - The README also references output reports and session logs, implying the app writes analysis artifacts to disk.
   - The function-calling workflow is therefore not read-only; it can produce durable reports and logs.

10. **Runtime and configuration model**
   - The project is a Python application using `requests` and `python-dotenv`.
   - Runtime behavior is configured through environment variables such as:
     - `OLLAMA_API_KEY`
     - `OLLAMA_BASE_URL`
     - `GOOGLE_API_KEY`
   - Model choice is configured at runtime in `main.py` for the diff pipeline, and via CLI flags in `fc_module.py` for the agent pipeline.

11. **Output structure**
   - The diff workflow prints three blocks:
     - SAFE
     - RAW
     - DIFF
   - The function-calling workflow prints tool invocation traces, tool results, a final response, and optionally a logged session file.
   - These are two distinct presentation contracts, matching the two subsystems.

12. **Likely high-level architecture diagram**
   - One box for **document ingestion** (`core/loader.py` + `data/`)
   - One box for **dual-model orchestration** (`main.py`, `engines/*`, `llm.py`)
   - One box for **diff generation** (`core/diff.py`)
   - One separate box for **agent/tool execution** (`fc_module.py` + tools)
   - External boxes for **LLM providers**, **NVD**, **filesystem**, and **safe shell commands**

Main entry points: [`core/loader.py`](https://github.com/3mper0rr/dualminddiffai/blob/main/core/loader.py) (Loader), [`engines/safe.py`](https://github.com/3mper0rr/dualminddiffai/blob/main/engines/safe.py) (Safe path), [`engines/raw.py`](https://github.com/3mper0rr/dualminddiffai/blob/main/engines/raw.py) (Raw path), [`llm.py`](https://github.com/3mper0rr/dualminddiffai/blob/main/llm.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dual_pipeline["Dual analysis"]
  node_main_py["Main<br/>entrypoint<br/>[main.py]"]
  node_loader_py["Loader<br/>ingest<br/>[loader.py]"]
  node_sample_txt["Sample text<br/>input data<br/>[sample.txt]"]
  node_safe_engine["Safe path<br/>llm mode<br/>[safe.py]"]
  node_raw_engine["Raw path<br/>llm mode<br/>[raw.py]"]
  node_llm_client["LLM client<br/>provider api<br/>[llm.py]"]
  node_diff_py{{"Diff<br/>comparison<br/>[diff.py]"}}
  node_dual_output["Analysis output<br/>report"]
end

subgraph group_agent_system["Agent tools"]
  node_fc_module["Agent CLI<br/>entrypoint<br/>[fc_module.py]"]
  node_tool_router["Tool loop<br/>orchestration"]
  node_file_tools["File tools<br/>local access"]
  node_url_fetch["Fetch URL<br/>network tool"]
  node_cve_lookup["CVE lookup<br/>intel tool"]
  node_shell_exec["Safe shell<br/>restricted exec"]
  node_session_log["Session log<br/>artifact"]
end

subgraph group_external_services["External systems"]
  node_provider_llms(("LLM providers<br/>external models"))
  node_filesystem[("Filesystem<br/>external storage")]
  node_nvd(("NVD<br/>external api"))
  node_web(("Web<br/>external network"))
  node_allowlist{{"Allowlist<br/>policy boundary"}}
end

node_main_py -->|"select input"| node_sample_txt
node_main_py -->|"load"| node_loader_py
node_loader_py -->|"send text"| node_safe_engine
node_loader_py -->|"send text"| node_raw_engine
node_safe_engine -->|"call model"| node_llm_client
node_raw_engine -->|"call model"| node_llm_client
node_llm_client -->|"API request"| node_provider_llms
node_safe_engine -->|"result"| node_diff_py
node_raw_engine -->|"result"| node_diff_py
node_diff_py -->|"render"| node_dual_output
node_fc_module -->|"start agent"| node_tool_router
node_tool_router -->|"invoke"| node_file_tools
node_tool_router -->|"invoke"| node_url_fetch
node_tool_router -->|"invoke"| node_cve_lookup
node_tool_router -->|"invoke"| node_shell_exec
node_file_tools -->|"read/write"| node_filesystem
node_url_fetch -->|"http"| node_web
node_cve_lookup -->|"query"| node_nvd
node_shell_exec -->|"gate"| node_allowlist
node_shell_exec -->|"side effects"| node_filesystem
node_tool_router -->|"emit"| node_session_log
node_session_log -->|"save"| node_filesystem

click node_main_py "https://github.com/3mper0rr/dualminddiffai/blob/main/main.py"
click node_loader_py "https://github.com/3mper0rr/dualminddiffai/blob/main/core/loader.py"
click node_sample_txt "https://github.com/3mper0rr/dualminddiffai/blob/main/data/sample.txt"
click node_safe_engine "https://github.com/3mper0rr/dualminddiffai/blob/main/engines/safe.py"
click node_raw_engine "https://github.com/3mper0rr/dualminddiffai/blob/main/engines/raw.py"
click node_llm_client "https://github.com/3mper0rr/dualminddiffai/blob/main/llm.py"
click node_diff_py "https://github.com/3mper0rr/dualminddiffai/blob/main/core/diff.py"
click node_fc_module "https://github.com/3mper0rr/dualminddiffai/blob/main/fc_module.py"

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_main_py,node_loader_py,node_sample_txt,node_safe_engine,node_raw_engine,node_llm_client,node_diff_py,node_dual_output toneBlue
class node_fc_module,node_tool_router,node_file_tools,node_url_fetch,node_cve_lookup,node_shell_exec,node_session_log toneAmber
class node_provider_llms,node_filesystem,node_nvd,node_web,node_allowlist toneMint
```

## Components

### Dual analysis

Document ingestion, two model paths, and comparison output.

- [Main](https://github.com/3mper0rr/dualminddiffai/blob/main/main.py): entrypoint · Drives the dual-analysis workflow. · `main.py`
- [Loader](https://github.com/3mper0rr/dualminddiffai/blob/main/core/loader.py): ingest · Reads source documents into the analysis pipeline. · `core/loader.py`
- [Sample text](https://github.com/3mper0rr/dualminddiffai/blob/main/data/sample.txt): input data · Reference document used by the pipeline. · `data/sample.txt`
- [Safe path](https://github.com/3mper0rr/dualminddiffai/blob/main/engines/safe.py): llm mode · Constrained analysis channel. · `engines/safe.py`
- [Raw path](https://github.com/3mper0rr/dualminddiffai/blob/main/engines/raw.py): llm mode · Less filtered analysis channel. · `engines/raw.py`
- [LLM client](https://github.com/3mper0rr/dualminddiffai/blob/main/llm.py): provider api · Shared abstraction for model calls. · `llm.py`
- [Diff](https://github.com/3mper0rr/dualminddiffai/blob/main/core/diff.py): comparison · Compares safe and raw outputs. · `core/diff.py`
- **Analysis output**: report · Printed SAFE, RAW, and DIFF sections.

### Agent tools

Function-calling workflow and its tool boundary.

- [Agent CLI](https://github.com/3mper0rr/dualminddiffai/blob/main/fc_module.py): entrypoint · Drives the function-calling workflow. · `fc_module.py`
- **Tool loop**: orchestration · Interprets prompts and sequences tool calls.
- **File tools**: local access · Reads, lists, and saves local artifacts.
- **Fetch URL**: network tool · Retrieves remote web content.
- **CVE lookup**: intel tool · Queries NVD for vulnerability intelligence.
- **Safe shell**: restricted exec · Runs only an allowlisted set of commands.
- **Session log**: artifact · Optional saved run record or report.

### External systems

Model providers and outside services used by the repo.

- **LLM providers**: external models · Gemini, Groq, OpenRouter, and Ollama-style backends.
- **Filesystem**: external storage · Local disk used for inputs and saved outputs.
- **NVD**: external api · Source for CVE intelligence.
- **Web**: external network · Remote HTTP resources fetched by the agent.
- **Allowlist**: policy boundary · Permitted commands for shell execution.

## Connections

- Main → Sample text: select input · Main workflow starts from a local document.
- Main → Loader: load · Reads document content into memory.
- Loader → Safe path: send text · Feeding the same content to the safe analysis channel.
- Loader → Raw path: send text · Feeding the same content to the raw analysis channel.
- Safe path → LLM client: call model · Safe mode uses the shared LLM abstraction.
- Raw path → LLM client: call model · Raw mode uses the shared LLM abstraction.
- LLM client → LLM providers: API request · Routes requests to supported model backends.
- Safe path → Diff: result · Safe output becomes one side of the comparison.
- Raw path → Diff: result · Raw output becomes the other side of the comparison.
- Diff → Analysis output: render · Produces the human-facing SAFE/RAW/DIFF view.
- Agent CLI → Tool loop: start agent · Entry point for the tool-using workflow.
- Tool loop → File tools: invoke · Uses local file read/list/save capabilities.
- Tool loop → Fetch URL: invoke · Fetches remote resources when needed.
- Tool loop → CVE lookup: invoke · Queries CVE intelligence from NVD.
- Tool loop → Safe shell: invoke · Runs constrained shell commands.
- File tools → Filesystem: read/write · Local artifacts and reports are persisted on disk.
- Fetch URL → Web: http · Network boundary for fetched content.
- CVE lookup → NVD: query · External vulnerability lookup service.
- Safe shell → Allowlist: gate · Only allowlisted commands may execute.
- Safe shell → Filesystem: side effects · Command output may be captured to local artifacts.
- Tool loop → Session log: emit · Agent run can produce a saved trace or report.
- Session log → Filesystem: save · Persistent session artifacts are written locally.