Multi-Agent Validation for Explainable Visual Reasoning and Image Consistency Knowledge
maverick-oss is the open-source, reference-free release of the broader MAVERICK research framework, developed as part of a Master's Thesis in Artificial Intelligence by Eduardo J. Barrios.
The repository provides a modular pipeline for image description with vision-language models (VLMs). It is designed for research contexts that require interpretable visual reasoning, explicit uncertainty handling, and configurable prompt-based experimentation.
MAVERICK is motivated by evidence that visual understanding is not a single-pass process. Human observers identify objects and regions, organize spatial and semantic relations, integrate prior knowledge, and revise interpretations when ambiguity or inconsistency is detected. This view is consistent with research on scene perception and visual cognition, where object recognition, eye movements, scene interpretation, and cognitive processing interact dynamically (Henderson & Hollingworth, 1999). It also follows the broader account of vision as an interaction between low-level visual input, spatial organization, object structure, and higher-level interpretation (Palmer, 1999).
maverick-oss operationalizes this process as four stages:
- Identification: detect salient visual elements, attributes, regions, and uncertainties.
- Description: generate an initial image description from the identified elements.
- Critique: evaluate the description for completeness, clarity, uncertainty, and unsupported claims.
- Refinement: produce a revised final description using the observations and critique.
The system contains exactly four configurable agents:
| Agent | Name | Role |
|---|---|---|
| A1 | Identifier | Extracts salient objects, entities, regions, attributes, and uncertainties from the image. |
| A2 | Descriptor | Generates an initial description from A1 observations. |
| A3 | Critic | Reviews the description without using an external reference description. |
| A4 | Refiner | Produces the final description by integrating A1, A2, and A3 outputs. |
Each agent can be assigned its own model, API key, base URL, temperature, and prompt. The implementation uses an OpenAI-compatible chat-completion interface, allowing different hosted or local providers to be tested through the same abstraction.
Prompts are stored in src/maverick_oss/prompts.py:
A1_IDENTIFIER_PROMPTA2_DESCRIPTOR_PROMPTA3_CRITIC_PROMPTA4_REFINER_PROMPT
The default prompts follow structured prompting principles: each prompt defines the agent role, task objective, input contract, reasoning procedure, constraints, and expected output format. They are intentionally domain-general and should be adapted for specific experimental settings.
Prompt behavior should be treated as experimentally sensitive. VLM outputs can vary with prompt wording, decoding parameters, model family, and visual encoder design. In transformer-based vision systems, image evidence is often represented through patch-level tokens; therefore, patch resolution, visual tokenization, and cross-modal alignment may influence which objects, attributes, colors, and spatial relations are emphasized. maverick-oss keeps agents, prompts, and models configurable because different LLM/VLM backends may show different concept associations, spatial-reasoning limitations, and grounding behavior, as reported in work on concept association bias (Yamada et al., 2024) and spatial reasoning in vision-language models (Kamath et al., 2023).
This repository supports reference-free execution only.
The full MAVERICK research framework includes additional reference-based validation components. Those components, including external text-to-text validation modules and unpublished evaluation metrics, are not included in this public release.
maverick-oss therefore does not compare generated descriptions against reference descriptions. The public release is limited to the four-agent reference-free pipeline described above.
maverick-oss uses an OpenAI-compatible API for VLM and language-model calls. Compatible providers include OpenAI, llm7.io, local OpenAI-compatible endpoints, and other services exposing /chat/completions APIs.
Hosted providers require API keys. Enter credentials only in the application GUI; do not add them to source files or commit them to version control.
maverick-oss is designed as a GUI-driven application to make the four-agent workflow accessible to non-technical users. API credentials, provider endpoints, models, system prompts, image uploads, execution, and results are all managed in the Streamlit interface. No environment variables or Python configuration files are required.
After the one-time installation and launch steps below, use only the browser GUI:
- Open Agent setup in the left sidebar.
- Expand A1, A2, A3, and A4.
- Enter the API key, base URL, and model for each agent. Agents may use different models or OpenAI-compatible providers.
- Optionally select Edit system prompt to review or customize each agent's existing built-in instructions. Select Restore default prompt at any time to discard edits and reload that agent's original system prompt.
- Upload a PNG, JPEG, or WebP image.
- Select Run reference-free pipeline.
- Read the Identifier, Descriptor, Critic, and Refiner results in separate tabs.
Settings and API keys are entered for the current GUI session. The app validates all four agent configurations before making a request and identifies any missing field directly on screen.
The prompt editor is preloaded from the corresponding A1-A4 defaults defined in
src/maverick_oss/prompts.py. Editing text in the GUI changes the prompt for the
current session only; it does not modify the source file.
These are the only command-line steps. They install the application and open its GUI; day-to-day configuration and usage happen inside the interface.
Install dependencies:
python -m pip install -r requirements.txtRun the interface:
streamlit run maverick-oss.pymaverick-oss is a simplified public release intended to support transparent, reproducible research on multi-agent VLM workflows. It excludes unpublished components from the full MAVERICK framework while preserving a usable foundation for reference-free visual reasoning experiments.
The repository includes automated sanity checks for the GUI startup, all four default system prompts, independent per-agent API/model configuration, pipeline wiring, validation messages, and prompt restoration. GitHub runs the complete test suite with Python 3.10 and 3.12 on every push and pull request. These checks do not contact model providers or require real API keys.
This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).
Attribution to Eduardo J. Barrios is required in derivative works, publications, and redistributed versions of this project. See LICENSE for the license notice and terms.
If you use maverick-oss in academic or applied work, please cite the repository using the metadata in CITATION.cff.
@software{barrios_maverick_oss_2026,
author = {Barrios, Eduardo J.},
title = {maverick-oss: A Reference-Free Multi-Agent Pipeline for Image Description with Vision-Language Models},
year = {2026},
license = {MPL-2.0}
}maverick-oss is provided for research and educational purposes. Users are responsible for validating outputs before applying the system in high-stakes or domain-specific settings.