QonQrete - Secure AI Construction Loop System

QonQrete is a Secure AI Construction Loop System, using a Multi-Agent Pipeline Orchestrator in a Sandbox environment with YAML Configuration. In short: it spawns 3 AI agents in a sandbox/container and makes them work together on tasks. It can run with a hard requirement for user approval between steps, or in a fully autonomous mode where it keeps running until the user decides to stop it.

QonQrete is a multi-agent orchestration system designed for secure, observable, and human-in-the-loop software construction. It operates on the principle of a secure build environment (Qage), managed by a host-level orchestrator (Qrane).

This architecture ensures that AI-generated code and processes cannot affect the host system, providing a robust framework for autonomous and semi-autonomous development.

Major Improvements: The Dual-Core Memory System with Local Qontextor

This release enhances the Dual-Core Memory System by making the qontextor agent capable of running in a fully local mode. It now performs deterministic analysis of Python code using a sophisticated stack of local tools to generate structural and semantic context at high speed with zero token cost.

The Local Qontextor Stack

The local qontextor now uses a multi-layered approach to understand your code without sending it to an AI:

Layer	Technology	Purpose
1. Structure	Python AST	Extracts the fundamental structure of the code, including function and class names and their signatures.
2. High-Level Purpose	Docstrings	Parses docstrings to get a high-confidence understanding of what a function or class does.
3. Inferred Purpose	Verb Heuristics	When docstrings are missing, it infers the purpose of a function based on its name (e.g., `get_user` implies retrieval).
4. Type Inference	Jedi	Performs static analysis to understand types and relationships between different parts of the code.
5. Call Graph	PyCG	Generates a call graph to understand the dependencies and execution flow between functions and modules.

Fast vs. Complex Local Mode

The local qontextor can be configured in worqspace/config.yaml:

local_mode: 'fast': Uses the first four layers of the stack (AST, Docstrings, Heuristics, Jedi) for a very fast analysis.
local_mode: 'complex': Adds a fifth layer, using a local sentence-transformers model to create deep semantic embeddings of the code’s purpose. This allows for more advanced queries and a deeper understanding of the code, at the cost of a slightly slower analysis.

The Scenario: A medium-sized project (50 files, ~10,000 lines of code).

Raw Size: ~100,000 Tokens.

Metric	Old Approach (Send Full Code)	New Approach (Dual-Core)	Improvement
Context Sent	100,000 Tokens (Full Repo)	~4,000 Tokens (Skeletons)	~96% Reduction
Indexing Cost	High (AI-based)	Zero (Local analysis)	Infinitely Cheaper
Cost per Run	~$0.25 (GPT-4o)	~$0.01 (GPT-4o)	25x Cheaper
Speed	Slow (Huge prompt processing)	Fast (Tiny prompt)	~3x Faster
Memory	Persistent	Persistent & Infinite Context	Upgraded

Summary: You are paying 4% of the cost for 100% of the intelligence, with zero cost for indexing.

Version

Version: v1.0.0-stable (See VERSION file for the canonical version).

What’s New in v1.0.0

Bulletproof Language Detection: 400+ language keywords for all AI providers
Enforced Briq Sensitivity: Guaranteed briq counts with automatic retry/merge
New CLI Flags: -c/--cyqles for cycle override
Updated Defaults: sensitivity 7, cycles 4
100% Pass Rate: Validated with 90 WoNQ Matrix runs

Note on TUI Mode and Agent Testing:

The Text-based User Interface (TUI) mode is currently under active development and may still have bugs. While the agent setup is dynamic, extensive testing is still required.

We welcome community contributions! If you encounter any issues or have suggestions, please report them. Your feedback is invaluable in helping us improve the system.

Core Principles

Isolation by Design: All agent execution occurs within the Qage, a Docker container that acts as a secure sandbox. The Qrane, running on the host, manages the workflow.
Configuration-Driven: The agent models and cycle limits are defined declaratively in worqspace/config.yaml.
File-Based Communication: Agents communicate by reading and writing markdown files to a shared worqspace/ volume, creating a transparent and auditable “chat history”.
Human-in-the-Loop Control: By default, a non-negotiable CheQpoint pauses the system after each cyQle. The user, acting as the gateQeeper, must review the results and provide explicit instructions to [Q]ontinue, [T]weaQ, or [X]Quit. This behavior can be configured to be autonomous by default.

Architecture Overview

qrane/: Contains the Python-based Qrane orchestrator and its command-line interface.
worqer/: Contains the individual AI agent scripts (instruQtor, construQtor, inspeQtor). It also includes specialized agents like qompressor for creating low-token context, qontextor for mapping the codebase, and calqulator for cost estimation.
worqspace/: The shared data plane. It contains all configuration, the initial tasQ, and all generated plans (briQ), summaries (exeQ), and reviews (reQap).

The Workflow CyQle

A cyQle consists of three main phases, orchestrated by the Qrane:

Plan (instruQtor): A qwen-max agent reads the high-level tasQ and creates a series of markdown briQ files, which contain a detailed, high-level plan for the executor agent.
Execute (construQtor): A qwen-max agent is invoked for each briQ. It reads the high-level plan and uses its own powerful agency and tools to generate all necessary files and code in the qodeyard/ directory.
Review (inspeQtor): A qwen-max agent reviews the code generated by the construQtor, assesses its quality, and produces a final reQap (review) with an assessment and suggestions for the next cycle.
CheQpoint (gateQeeper): The Qrane pauses the system and displays the reQap, waiting for the user’s command to proceed.

System Requirements

The Qrane orchestrator runs directly on the host, while the Qrew of AI agents runs inside a sandboxed container.

1. Docker

Docker is the default, essential runtime for the secure Qage environment.

macOS: Install Docker Desktop for Mac.
Linux:
- Debian/Ubuntu: sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
- Fedora/CentOS: sudo dnf install dnf-plugins-core && sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo && sudo dnf install docker-ce docker-ce-cli containerd.io
Windows: Install Docker Desktop for Windows.

Note for Docker Desktop (macOS & Windows) Users: You MUST grant Docker permission to access the project directory. Go to Settings > Resources > File Sharing and add the path to your qonqrete project folder. This allows the worqspace volume to be mounted correctly.

2. Microsandbox (Optional)

As a lightweight alternative to Docker, you can use msb.

Installation: Follow the instructions at the official Microsandbox repository.
You can set msb as the default runtime in worqspace/pipeline_config.yaml.

Getting Started

For a full guide on setting up the environment and running your first cyQle, please see QUICKSTART.md.

API Key Configuration: Before running, you must export the API keys for the AI providers you intend to use. The system will automatically check for the necessary keys based on your worqspace/config.yaml.

export OPENAI_API_KEY='your-key'
export GOOGLE_API_KEY='your-key' (or GEMINI_API_KEY)
export ANTHROPIC_API_KEY='your-key'
export DEEPSEEK_API_KEY='your-key'

First, initialize the system. This builds the secure container environment.

# For Docker (default)
./qonqrete.sh init

# If you use Microsandbox
./qonqrete.sh init --msb

To run the system with the Text-based User Interface (TUI) and set an operational mode:

./qonqrete.sh run --tui --mode security

To run in autonomous mode with a specific task granularity:

./qonqrete.sh run --auto --briq-sensitivity 2

To force user-gated mode (overriding a config file set to auto):

./qonqrete.sh run --user

You can override the configured runtime using flags:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

./qonqrete.sh clean

License

QonQrete is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This ensures that any modifications or derivative works deployed as a service must also be released as open source under the same license. See the LICENSE file for full text.