How 3mper0rr/dualminddiffai works
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: loader.py Loader · safe.py Safe path · raw.py Raw path · llm.py LLM client
Components 20
Dual analysis
Document ingestion, two model paths, and comparison output.
- Main · Drives the dual-analysis workflow.
main.py - Loader · Reads source documents into the analysis pipeline.
core/loader.py - Sample text · Reference document used by the pipeline.
data/sample.txt - Safe path · Constrained analysis channel.
engines/safe.py - Raw path · Less filtered analysis channel.
engines/raw.py - LLM client · Shared abstraction for model calls.
llm.py - Diff · Compares safe and raw outputs.
core/diff.py - Analysis output · Printed SAFE, RAW, and DIFF sections.
Agent tools
Function-calling workflow and its tool boundary.
- Agent CLI · Drives the function-calling workflow.
fc_module.py - Tool loop · Interprets prompts and sequences tool calls.
- File tools · Reads, lists, and saves local artifacts.
- Fetch URL · Retrieves remote web content.
- CVE lookup · Queries NVD for vulnerability intelligence.
- Safe shell · Runs only an allowlisted set of commands.
- Session log · Optional saved run record or report.
External systems
Model providers and outside services used by the repo.
- LLM providers · Gemini, Groq, OpenRouter, and Ollama-style backends.
- Filesystem · Local disk used for inputs and saved outputs.
- NVD · Source for CVE intelligence.
- Web · Remote HTTP resources fetched by the agent.
- Allowlist · Permitted commands for shell execution.
Connections 22
- 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.