ARQ: Augmented Reasoning Query

ARQ integrates structured reasoning patterns with declarative workflow execution, enabling LLMs to follow explicit guidelines and produce auditable decision traces.

Overview

ARQ enhances LLM decision-making by requiring explicit structured reasoning (ARQ queries) before task execution. This repository provides:

• ARQ Pattern: JSON Schema-validated reasoning queries that enforce guideline adherence
• Workflow Integration: Declarative workflows (JSON + Markdown) with ARQ-enhanced nodes
• Audit Trail: Complete trace of all ARQ queries and outcomes
• Flask UI: Web interface for prompt editing and workflow execution

Quick Start

Prerequisites

• Python 3.8+
• Ollama running locally (http://localhost:11434)
• Model llama3:8b available (or configure your own)

Installation

pip install -r prototype/requirements.txt

Run Workflow

# Command line
python run_arq_workflow.py tomato

# Or via UI
python scripts/arq_prompt_ui.py
# Open http://localhost:5004

Architecture

workflow.json → WorkflowRunner → NodeExecutor → ArqPromptBuilder
                                                      ↓
                                              LLMClient (Ollama)
                                                      ↓
                                              ArqValidator
                                                      ↓
                                              State + ARQ Trace

Components:

• WorkflowRunner: Executes workflows from JSON DAG definitions
• NodeExecutor: Executes individual nodes with ARQ integration
• ArqPromptBuilder: Constructs ARQ-enhanced prompts with variable substitution
• ArqValidator: Validates ARQ queries against JSON Schema
• LlmClient: Ollama API client with robust JSON extraction

Key Features

• Structured Reasoning: ARQ queries enforce explicit context, guidelines, constraints, and reasoning
• Schema Validation: All ARQ queries validated against JSON Schema before execution
• State Management: Workflow state flows between nodes with full traceability
• Declarative Workflows: Define workflows in JSON (DAG) + Markdown (node specs)
• Audit Trail: Complete arqTrace logs all queries, timestamps, and outcomes

Project Structure

.
├── prototype/              # Core implementation
│   ├── workflow_runner.py  # Workflow execution engine
│   ├── node_executor.py    # Node execution with ARQ
│   ├── arq_validator.py   # JSON Schema validation
│   └── llm_client.py       # Ollama API client
├── workflows/              # Workflow definitions
│   └── arq-toy/v1/        # Example workflow
│       ├── workflow.json   # DAG definition
│       └── nodes/          # Node specifications (Markdown)
├── scripts/
│   └── arq_prompt_ui.py   # Flask UI (prompts + workflows)
└── .context/              # Design documentation

Usage Example

Workflow Definition (workflows/arq-toy/v1/workflow.json):

{
  "id": "arq-toy-v1",
  "nodes": [
    {"id": "classify-item", "specPath": "./nodes/classify-item.md"}
  ],
  "edges": [{"from": "start", "to": "classify-item"}]
}

Node Spec (nodes/classify-item.md):

## ARQ Template
```json
{
  "current_context": "We received item: '{item}'",
  "active_guideline": "Classify using botanical rules",
  "reasoning": "Apply botanical definition"
}

Execution Result:

{
  "item": "tomato",
  "classification": "fruit",
  "arqTrace": [
    {
      "node_id": "classify-item",
      "arq_query": {...},
      "timestamp": "2025-01-05T10:30:00Z",
      "outcome": "fruit"
    }
  ]
}

Documentation

• Prototype Details: .context/260105_ARQ-WF-Integration_Prototyping.md
• ARQ Specification: .context/ARQ-lightweight-langgraph4j.md
• Prototype README: prototype/README.md

Requirements

• jsonschema>=4.17.0: ARQ query validation
• requests>=2.31.0: Ollama API calls
• flask: Web UI (for scripts/arq_prompt_ui.py)

License

[Add your license here]