QonQrete Logo QonQrete

Contexting Mechanism in QonQrete

QonQrete’s contexting mechanism is how the system provides its AI agents (including Qwen) with the necessary information to understand their current task, the state of the codebase, and the historical progression of work. It’s designed to be dynamic, layered, and optimized for LLM consumption.

The primary goal of contexting is to ensure that LLMs receive relevant, actionable information within their limited context windows, preventing “hallucination” and keeping them grounded in the project’s reality.

Layers of Context

QonQrete builds context for its AI agents using several interconnected layers:

1. tasq.d/ (Current Directive Context)

  • Source: qrane/paths.py, generated by qrane.py and handle_cheqpoint.
  • Content: The cyqleXXX_tasq.md file contains the explicit instructions and objectives for the current cycle. This is the most direct and immediate form of context.
  • Role in AI interaction: This file is usually the primary prompt for the instruqtor agent, setting the stage for what needs to be done. It often incorporates the reQap from the previous cycle, linking historical feedback to the current directive.

2. bloq.d/ (Structural Context / Code Skeletons)

  • Source: worqer/qompressor.py populates this directory (worqspace/bloq.d).
  • Content: Contains “qompressed” versions of source code files. These files retain structural elements (imports, function/class signatures, docstrings, comments) but strip out implementation bodies.
  • Role in AI interaction: Provides LLMs with an architectural overview of the codebase. When an agent needs to understand how to interact with an existing component or where to place new code, the bloq.d files offer a token-efficient map of the system’s structure. This structural context is often explicitly passed via the context_files argument to worqer/lib_ai.py.

3. qontext.d/ (Semantic Context / Code Index)

  • Source: worqer/qontextor.py populates this directory (worqspace/qontext.d).
  • Content: Stores YAML summaries of files. This process is now dual-mode:
    • Local Mode (provider: local): When configured for local execution, qontextor performs a deterministic analysis using a sophisticated stack of local tools. This is the default and recommended mode.
      • Python AST: Extracts the fundamental structure of the code, including function and class names and their signatures.
      • Docstrings: Parses docstrings to get a high-confidence understanding of what a function or class does.
      • Verb Heuristics: When docstrings are missing, it infers the purpose of a function based on its name (e.g., get_user implies retrieval).
      • Jedi: Performs static analysis to understand types and relationships between different parts of the code.
      • PyCG: Generates a call graph to understand the dependencies and execution flow between functions and modules.
      • Fast vs. Complex Mode:
        • local_mode: 'fast': Uses the first four layers of the stack 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.
    • AI Mode (provider: [ai_provider]): In legacy mode, it uses an AI to generate YAML summaries. For code, this includes structured data about symbols (name, type, signature, purpose, dependencies). For documentation and configuration, it includes concise summaries.
  • Role in AI interaction: Offers a higher-level, semantically rich understanding of the codebase. Agents can query this context to find relevant functions, understand their purposes, and identify dependencies without processing raw code. This semantic context is also passed via the context_files argument to worqer/lib_ai.py, supplementing or replacing direct code examination. The generation of this context can be disabled by setting use_qontextor: false in config.yaml.

4. QONQ_PREVIOUS_LOG (Operational History Context)

  • Source: qrane.py and worqer/lib_ai.py.
  • Content: The content of the qonsole.log file from the immediately preceding agent’s execution.
  • Role in AI interaction: worqer/lib_ai.py automatically injects this log as “FALLBACK CONTEXT” into the LLM prompt. This provides the current agent with an immediate historical context of what the previous agent did, saw, or outputted, ensuring continuity in multi-step operations.

5. qodeyard/ (Raw Codebase / Reference Context)

  • Source: The initial codebase provided to QonQrete.
  • Content: The full, uncompressed source code, documentation, and configuration files.
  • Role in AI interaction: While not directly fed to LLMs in its entirety due to token limits, qodeyard serves as the ultimate source of truth. Agents might refer to specific files from qodeyard when deep understanding or precise code modification is required, often by using tools that allow them to read specific files. qompressor and qontextor derive their initial information from qodeyard.

6. config.yaml and pipeline_config.yaml (System Configuration Context)

  • Source: User-defined configuration files in worqspace/.
  • Content: Defines system-wide parameters, agent configurations, AI provider details, and the pipeline of agents to be executed.
  • Role in AI interaction: While not directly fed to LLMs as a prompt, these configurations dictate the behavior of the QonQrete system itself, influencing how context is built and which agents are used. Certain agents might be designed to interpret or modify these configurations.

The Contexting Process

The contexting process in QonQrete involves:

  1. Initial Warmup: When qrane.py detects a qodeyard, it orchestrates an initial run of qompressor (to build bloq.d) and qontextor (to build qontext.d), establishing foundational structural and semantic context.
  2. Cycle-based Updates: In each operational cycle, the tasq.md provides the primary directive. Agents, when making LLM calls via lib_ai.py, dynamically assemble a prompt that includes:
    • The base_prompt (task-specific instructions).
    • The QONQ_PREVIOUS_LOG (operational history).
    • Relevant files from bloq.d (structural context).
    • Relevant files from qontext.d (semantic context).
  3. Cheqpoints and User Feedback: At cheqpoints, the reQap (operational memory) is presented. User review and potential edits directly influence the tasq.md for the next cycle, effectively allowing human intervention to refine the context.

By combining these layers, QonQrete ensures that its AI agents operate with a rich, layered, and token-optimized understanding of their environment and tasks.