Initial commit: QAgents-workflos multi-agent quantum circuit optimization system

.env.example

@@ -0,0 +1,76 @@
+# QAgents-Workflows Environment Configuration
+# Copy this file to .env and fill in your actual values
+# For Hugging Face Spaces: Add these as Repository Secrets or Space Variables
+
+# =============================================================================
+# LLM Configuration (Model-Agnostic)
+# =============================================================================
+
+# LLM Provider: gemini (default), openai, anthropic, groq, ollama, etc.
+# Leave empty to use default: "gemini"
+LLM_PROVIDER=gemini
+
+# LLM Model identifier
+# For Gemini: gemini-2.5-flash-lite, gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash
+# For OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo
+# For Anthropic: claude-3-opus, claude-3-sonnet
+# For Groq: llama-3-70b-versatile, mixtral-8x7b-32768
+# For Ollama: mistral, neural-chat, starling-lm (local models)
+# Leave empty to use default: "gemini-2.5-flash-lite"
+LLM_MODEL=gemini-2.5-flash-lite
+
+# =============================================================================
+# API Keys (Provider-Specific)
+# =============================================================================
+
+# Google Gemini API Key (required for LLM_PROVIDER=gemini)
+# Get from: https://aistudio.google.com/app/apikey
+GOOGLE_API_KEY=your-gemini-api-key-here
+
+# Alternative Gemini API Key (fallback if GOOGLE_API_KEY not set)
+GENAI_API_KEY=
+
+# OpenAI API Key (required for LLM_PROVIDER=openai)
+OPENAI_API_KEY=sk-...
+
+# Anthropic API Key (required for LLM_PROVIDER=anthropic)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Groq API Key (required for LLM_PROVIDER=groq)
+GROQ_API_KEY=gsk_...
+
+# Note: Ollama (LLM_PROVIDER=ollama) requires no API key - runs locally
+
+# =============================================================================
+# MCP Server Configuration (QuantumArchitect-MCP)
+# =============================================================================
+
+# MCP Server Base URL
+# Local: http://127.0.0.1:7861
+# Remote (ngrok example): https://your-ngrok-url.ngrok.io
+# Leave empty to use default: http://127.0.0.1:7861
+MCP_SERVER_URL=http://127.0.0.1:7861
+
+# =============================================================================
+# Optional: Cost Tracking and Evaluation
+# =============================================================================
+
+# Cost tracking can be enabled/disabled
+# TRACK_COSTS=true
+
+# =============================================================================
+# Notes for Hugging Face Spaces
+# =============================================================================
+
+# 1. Upload this file as .env to your Space (or use Space Settings UI)
+# 2. Go to Space Settings > Secrets > Add Secret
+# 3. Add each variable:
+#    - Name: LLM_PROVIDER, Value: gemini
+#    - Name: LLM_MODEL, Value: gemini-2.5-flash-lite
+#    - Name: GOOGLE_API_KEY, Value: your-key
+#    - Name: MCP_SERVER_URL, Value: https://your-backend-url.ngrok.io
+#
+# 4. Restart the Space for changes to take effect
+#
+# Alternative: Use Space Variables (visible in Space info) instead of Secrets
+# This is useful for non-sensitive settings like LLM_PROVIDER and MCP_SERVER_URL

.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv
+venv/
+ENV/
+env/
+
+# Environment Variables
+.env  # Actual secrets - never commit
+# .env.example IS committed as a template - do not exclude it
+
+# Database and Logs
+*.db
+*.sqlite3
+database/data/
+database/logs/
+database/memory/
+*.log
+
+# IDEs
+.vscode/
+.idea/
+
+# Project specific
+research/
+
+# Legacy/Backup files
+*_old.py
+*.bak
+
+# Documentation work
+.docs/

AGENTS.md

@@ -0,0 +1,64 @@
+project current structure :"""
+QAgents-workflos\__pycache__
+QAgents-workflos\agents
+QAgents-workflos\agents\__pycache__
+QAgents-workflos\agents\__init__.py
+QAgents-workflos\agents\base_agent.py
+QAgents-workflos\agents\llm_adapter.py
+QAgents-workflos\agents\specialized_agents.py
+QAgents-workflos\client
+QAgents-workflos\client\__pycache__
+QAgents-workflos\client\__init__.py
+QAgents-workflos\client\mcp_client.py
+QAgents-workflos\database
+QAgents-workflos\database\__pycache__
+QAgents-workflos\database\data
+QAgents-workflos\database\logs
+QAgents-workflos\database\memory
+QAgents-workflos\database\__init__.py
+QAgents-workflos\database\storage.py
+QAgents-workflos\orchestrators
+QAgents-workflos\orchestrators\__pycache__
+QAgents-workflos\orchestrators\__init__.py
+QAgents-workflos\orchestrators\orchestrator.py
+QAgents-workflos\prompts
+QAgents-workflos\prompts\__init__.py
+QAgents-workflos\prompts\agent_prompts.py
+QAgents-workflos\tests
+QAgents-workflos\tests\__pycache__
+QAgents-workflos\tests\__init__.py
+QAgents-workflos\tests\evaluation_harness.py
+QAgents-workflos\tests\test_problems.py
+QAgents-workflos\tools
+QAgents-workflos\tools\__pycache__
+QAgents-workflos\tools\__init__.py
+QAgents-workflos\tools\quantum_tools.py
+QAgents-workflos\tools\tool_registry.py
+QAgents-workflos\workflows
+QAgents-workflos\workflows\__pycache__
+QAgents-workflos\workflows\__init__.py
+QAgents-workflos\workflows\workflow_definitions.py
+QAgents-workflos\__init__.py
+QAgents-workflos\AGENTS.md
+QAgents-workflos\config.py
+QAgents-workflos\DEPLOYMENT_CHECKLIST.md
+QAgents-workflos\IMPLEMENTATION_CHECKLIST.md
+QAgents-workflos\LLM_SYSTEM_SUMMARY.md
+QAgents-workflos\QUICKREF.md
+QAgents-workflos\README.md
+QAgents-workflos\requirements.txt
+QAgents-workflos\run_evaluation.py
+QAgents-workflos\SETUP.md
+QAgents-workflos\tasks-project-state.json
+"""
+
+before work, on same terminal:"""
+1 activate .venv: 
+& D:\teach\quantum-circuits\.venv\Scripts\Activate.ps1
+
+2 activate app: 
+python QuantumArchitect-MCP\app.py
+"""
+
+
+if any new data it must be writed on tasks-project-state.json root file or a folder module tasks-project-state.json file that detail the module file

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicolas Ivan Larenas Bustamante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,265 @@
+---
+title: QAgents Quantum Circuit Orchestrator
+emoji: ⚛️
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: Multi-agent quantum circuit generation with Gemini/LLMs
+---
+
+# QAgents-Workflows: Quantum Circuit Optimization Agent System
+
+A professional multi-agent system for autonomous quantum circuit optimization, featuring multiple architectural approaches and **model-agnostic LLM support** (Gemini, OpenAI, Anthropic, Groq, Ollama, and any LiteLLM provider).
+
+## 🏗️ Architectures
+
+### 1. Blackboard System (Free/Emergent)
+- Agents communicate through a shared blackboard
+- Decoupled, event-driven activation
+- Emergent workflow based on data availability
+- Maximum flexibility and adaptability
+
+### 2. Guided System (Strict Orchestration)
+- Explicit state machine with defined transitions
+- Central orchestrator controls workflow
+- Predictable, auditable execution path
+- Maximum reliability and control
+
+### 3. Naked System (Baseline)
+- Single agent with direct MCP access
+- No framework overhead
+- Baseline for comparison
+
+## 🤖 Model-Agnostic LLM Support
+
+The system works with **any LLM provider**:
+
+| Provider | Setup | Models |
+|----------|-------|--------|
+| **Gemini** (Default) | `GOOGLE_API_KEY` | `gemini-2.5-flash-lite` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o`, `gpt-4o-mini` |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-opus`, `claude-3-sonnet` |
+| Groq | `GROQ_API_KEY` | `llama-3-70b`, `mixtral-8x7b` |
+| Ollama (Local) | No key needed | Any local model |
+
+**See [SETUP.md](SETUP.md) for detailed configuration.**
+
+## 📊 Evaluation Metrics
+
+| Metric | Description |
+|--------|-------------|
+| **Time** | Total execution time in seconds |
+| **Quality** | Circuit depth, gate count, hardware fitness score |
+| **Effectiveness** | Did the circuit achieve the goal? |
+| **Reliability** | Success rate across multiple runs |
+
+## 🚀 Quick Start
+
+```bash
+# 1. Ensure QuantumArchitect-MCP is running
+python QuantumArchitect-MCP/app.py
+
+# 2. Set your API key (for Gemini by default)
+set GOOGLE_API_KEY=your-key-here
+# OR for OpenAI:
+set OPENAI_API_KEY=your-key-here
+
+# 3. Run the evaluation
+python QAgents-workflos/run_evaluation.py
+
+# For quick test (no LLM needed):
+python QAgents-workflos/run_evaluation.py --quick
+
+# Test specific mode:
+python QAgents-workflos/run_evaluation.py --mode guided
+python QAgents-workflos/run_evaluation.py --mode blackboard
+python QAgents-workflos/run_evaluation.py --mode naked
+```
+
+## 🔧 Switching LLM Providers
+
+### Using Gemini (Default)
+```bash
+set GOOGLE_API_KEY=your-gemini-key
+# Models: gemini-2.5-flash-lite, gemini-2.5-pro
+```
+
+### Using OpenAI
+Edit `config.py`:
+```python
+provider: str = "openai"
+model: str = "gpt-4o-mini"
+```
+```bash
+set OPENAI_API_KEY=sk-...
+```
+
+### Using Anthropic
+```python
+provider: str = "anthropic"
+model: str = "claude-3-sonnet-20240229"
+```
+```bash
+set ANTHROPIC_API_KEY=your-key
+```
+
+### Using Groq
+```python
+provider: str = "groq"
+model: str = "llama-3-70b-versatile"
+```
+```bash
+set GROQ_API_KEY=your-key
+```
+
+### Using Local Ollama
+```python
+provider: str = "ollama"
+model: str = "mistral"
+```
+No API key needed - runs locally on `http://localhost:11434`
+
+## 📁 Project Structure
+
+```
+QAgents-workflos/
+├── agents/                    # Agent implementations (Architect, Builder, etc.)
+├── client/                    # MCP client for QuantumArchitect-MCP
+├── database/                  # Storage layer (logs, memory, circuits)
+├── orchestrators/             # Orchestration modes (Naked, Guided, Blackboard, QUASAR, Hybrid)
+├── prompts/                   # System prompts for agents and optimized LLM prompts
+├── tools/                     # Tool registry and MCP endpoint wrappers
+├── workflows/                 # Workflow definitions
+├── tests/                     # Evaluation harnesses and test problems
+├── app.py                     # Gradio UI entry point (Hugging Face Space)
+├── config.py                  # Configuration with env var support
+├── requirements.txt           # Python dependencies
+├── .env.example               # Environment variable template
+└── README.md                  # This file
+```
+
+## 🚀 Deployment to Hugging Face Spaces
+
+### Prerequisites
+1. Create a Hugging Face Space: https://huggingface.co/new-space
+2. Select **Gradio** as the SDK
+3. Push this repository to your Space
+
+### Environment Variables Configuration
+
+The system reads configuration from **environment variables**, making it compatible with Hugging Face Spaces.
+
+#### Critical Variables
+
+| Variable | Purpose | Default | Example |
+|----------|---------|---------|---------|
+| `LLM_PROVIDER` | LLM provider to use | `gemini` | `gemini`, `openai`, `anthropic` |
+| `LLM_MODEL` | Model identifier | `gemini-2.5-flash-lite` | `gpt-4o-mini`, `claude-3-sonnet` |
+| `GOOGLE_API_KEY` | Gemini API key | (none) | Your API key from aistudio.google.com |
+| `MCP_SERVER_URL` | Backend URL | `http://127.0.0.1:7861` | `https://your-backend.ngrok.io` |
+
+#### Setting Variables in Hugging Face Space
+
+**Option 1: Via Space Settings (Recommended)**
+1. Go to your Space settings
+2. Click **"Secrets and variables"** > **"New secret"**
+3. Add each variable:
+   - **Secret Name**: `GOOGLE_API_KEY` | **Value**: Your API key
+   - **Secret Name**: `MCP_SERVER_URL` | **Value**: Backend URL
+4. Add variables (non-sensitive):
+   - **Variable Name**: `LLM_PROVIDER` | **Value**: `gemini`
+   - **Variable Name**: `LLM_MODEL` | **Value**: `gemini-2.5-flash-lite`
+
+**Option 2: Via .env File**
+```bash
+# Copy .env.example to .env and fill in values
+cp .env.example .env
+
+# Commit and push to your Space
+git add .env
+git commit -m "Add environment configuration"
+git push
+```
+
+**⚠️ Important**: Never commit sensitive API keys directly. Use Space Secrets instead.
+
+### LLM Provider Configuration
+
+#### Using Gemini (Default)
+```
+LLM_PROVIDER=gemini
+LLM_MODEL=gemini-2.5-flash-lite
+GOOGLE_API_KEY=your-key-from-https://aistudio.google.com/app/apikey
+```
+
+#### Using OpenAI
+```
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o-mini
+OPENAI_API_KEY=sk-...
+```
+
+#### Using Anthropic
+```
+LLM_PROVIDER=anthropic
+LLM_MODEL=claude-3-sonnet-20240229
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+#### Using Groq
+```
+LLM_PROVIDER=groq
+LLM_MODEL=llama-3-70b-versatile
+GROQ_API_KEY=gsk_...
+```
+
+#### Using Local Ollama
+```
+LLM_PROVIDER=ollama
+LLM_MODEL=mistral
+# No API key needed - runs locally on http://localhost:11434
+```
+
+### Backend Connection (MCP Server)
+
+The Space communicates with the QuantumArchitect-MCP backend via `MCP_SERVER_URL`.
+
+**Options:**
+
+1. **Local Development** (both running on your machine):
+   ```
+   MCP_SERVER_URL=http://127.0.0.1:7861
+   ```
+
+2. **Public Backend with ngrok** (tunnel remote server):
+   ```bash
+   # On your backend server:
+   ngrok http 7861
+   ```
+   Then set:
+   ```
+   MCP_SERVER_URL=https://your-ngrok-url.ngrok.io
+   ```
+
+3. **Deployed Backend** (your own server):
+   ```
+   MCP_SERVER_URL=https://your-quantum-api.example.com
+   ```
+
+If `MCP_SERVER_URL` is not set or unreachable, the Space will still work but with local-only features.
+
+## 📁 Project Structure (Previous)
+├── agents/           # Agent definitions (types, behaviors)
+├── prompts/          # System prompts for each agent
+├── tools/            # MCP tool wrappers
+├── workflows/        # Workflow definitions
+├── orchestrators/    # Workflow orchestration logic
+├── client/           # MCP client connection
+├── database/         # Memory, logs, results storage
+├── tests/            # Evaluation framework
+└── config.py         # Global configuration
+```

__init__.py

@@ -0,0 +1,6 @@
+"""QAgents-Workflows: Multi-agent quantum circuit optimization system."""
+
+from .config import config, set_mode, get_mode, SystemConfig
+
+__version__ = "0.1.0"
+__all__ = ["config", "set_mode", "get_mode", "SystemConfig"]

agents/__init__.py

@@ -0,0 +1,44 @@
+"""Agents module: Base and specialized agent implementations."""
+
+from .base_agent import (
+    BaseAgent,
+    LLMAgent,
+    RuleBasedAgent,
+    AgentRole,
+    AgentState,
+    AgentContext,
+    AgentAction,
+    AgentResult
+)
+
+from .specialized_agents import (
+    ArchitectAgent,
+    BuilderAgent,
+    ValidatorAgent,
+    OptimizerAgent,
+    AnalyzerAgent,
+    ScorerAgent,
+    SimulatorAgent,
+    create_all_agents
+)
+
+__all__ = [
+    # Base classes
+    "BaseAgent",
+    "LLMAgent", 
+    "RuleBasedAgent",
+    "AgentRole",
+    "AgentState",
+    "AgentContext",
+    "AgentAction",
+    "AgentResult",
+    # Specialized agents
+    "ArchitectAgent",
+    "BuilderAgent",
+    "ValidatorAgent",
+    "OptimizerAgent",
+    "AnalyzerAgent",
+    "ScorerAgent",
+    "SimulatorAgent",
+    "create_all_agents"
+]

agents/base_agent.py

@@ -0,0 +1,302 @@
+"""
+Agents Module: Base agent classes and specialized agents.
+Supports both Blackboard (free) and Guided (strict) architectures.
+Model-agnostic: Works with Gemini, OpenAI, Anthropic, Groq, Ollama, etc.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Callable
+from enum import Enum
+from datetime import datetime
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRole(Enum):
+    """Roles agents can take in the system."""
+    ARCHITECT = "architect"
+    BUILDER = "builder"
+    VALIDATOR = "validator"
+    OPTIMIZER = "optimizer"
+    ANALYZER = "analyzer"
+    SCORER = "scorer"
+    COORDINATOR = "coordinator"
+
+
+class AgentState(Enum):
+    """Agent execution states."""
+    IDLE = "idle"
+    THINKING = "thinking"
+    EXECUTING = "executing"
+    WAITING = "waiting"
+    COMPLETED = "completed"
+    ERROR = "error"
+
+
+@dataclass
+class AgentContext:
+    """Context passed to agents for decision making."""
+    goal: str
+    current_circuit: Optional[str] = None
+    history: List[Dict] = field(default_factory=list)
+    constraints: Dict = field(default_factory=dict)
+    shared_data: Dict = field(default_factory=dict)
+    
+    def add_to_history(self, action: str, result: Any):
+        self.history.append({
+            "action": action,
+            "result": result,
+            "timestamp": datetime.now().isoformat()
+        })
+
+
+@dataclass
+class AgentAction:
+    """An action an agent wants to take."""
+    tool_name: str
+    arguments: Dict
+    reasoning: str
+    priority: float = 1.0
+
+
+@dataclass
+class AgentResult:
+    """Result of an agent's execution."""
+    success: bool
+    data: Any
+    message: str
+    actions_taken: List[str] = field(default_factory=list)
+    execution_time_ms: float = 0.0
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all agents.
+    Provides common interface for both Blackboard and Guided architectures.
+    """
+    
+    def __init__(self,
+                 agent_id: str,
+                 role: AgentRole,
+                 tools: List[str] = None,
+                 llm_config: Dict = None):
+        self.agent_id = agent_id
+        self.role = role
+        self.tools = tools or []
+        self.llm_config = llm_config or {}
+        self.state = AgentState.IDLE
+        self.memory: Dict = {}
+        self._callbacks: List[Callable] = []
+        
+    @abstractmethod
+    def decide(self, context: AgentContext) -> Optional[AgentAction]:
+        """Decide what action to take given the context."""
+        pass
+        
+    @abstractmethod
+    def execute(self, action: AgentAction, context: AgentContext) -> AgentResult:
+        """Execute the decided action."""
+        pass
+        
+    def can_handle(self, context: AgentContext) -> bool:
+        """Check if this agent can handle the current context."""
+        return True
+        
+    def on_state_change(self, callback: Callable):
+        """Register callback for state changes."""
+        self._callbacks.append(callback)
+        
+    def _set_state(self, new_state: AgentState):
+        """Update state and notify callbacks."""
+        old_state = self.state
+        self.state = new_state
+        for cb in self._callbacks:
+            cb(self.agent_id, old_state, new_state)
+            
+    def reset(self):
+        """Reset agent to initial state."""
+        self.state = AgentState.IDLE
+        self.memory.clear()
+
+
+class LLMAgent(BaseAgent):
+    """
+    Agent that uses an LLM for decision making.
+    Model-agnostic: Supports Gemini, OpenAI, Anthropic, Groq, Ollama, etc.
+    Can be used in both Blackboard and Guided modes.
+    """
+    
+    def __init__(self,
+                 agent_id: str,
+                 role: AgentRole,
+                 system_prompt: str,
+                 tools: List[str] = None,
+                 llm_config: Dict = None):
+        super().__init__(agent_id, role, tools, llm_config)
+        self.system_prompt = system_prompt
+        self._adapter = None
+        
+    def _get_adapter(self):
+        """Get the LLM adapter (lazy init)."""
+        if self._adapter is None:
+            from config import config
+            from agents.llm_adapter import get_llm_adapter
+            
+            self._adapter = get_llm_adapter(
+                provider=config.llm.provider,
+                model=config.llm.model,
+                api_key=config.llm.api_key
+            )
+        return self._adapter
+        
+    def _build_messages(self, context: AgentContext) -> List[Dict]:
+        """Build message list for LLM."""
+        messages = [{"role": "system", "content": self.system_prompt}]
+        
+        context_msg = f"""
+Goal: {context.goal}
+
+Current Circuit:
+{context.current_circuit or 'None yet'}
+
+Constraints:
+{json.dumps(context.constraints, indent=2)}
+
+History (last 5 actions):
+{json.dumps(context.history[-5:], indent=2)}
+"""
+        messages.append({"role": "user", "content": context_msg})
+        return messages
+        
+    def decide(self, context: AgentContext) -> Optional[AgentAction]:
+        """Use LLM to decide on action."""
+        self._set_state(AgentState.THINKING)
+        
+        try:
+            from config import config
+            from tools import registry
+            
+            tool_schemas = [
+                registry.get(name).to_llm_schema()
+                for name in self.tools
+                if registry.get(name)
+            ]
+            
+            messages = self._build_messages(context)
+            adapter = self._get_adapter()
+            
+            llm_response = adapter.generate(
+                messages=messages,
+                tools=tool_schemas if tool_schemas else None,
+                temperature=self.llm_config.get("temperature", config.llm.temperature),
+                max_tokens=self.llm_config.get("max_tokens", config.llm.max_tokens)
+            )
+            
+            if llm_response.tool_calls:
+                tool_call = llm_response.tool_calls[0]
+                return AgentAction(
+                    tool_name=tool_call.tool_name,
+                    arguments=tool_call.arguments,
+                    reasoning=tool_call.reasoning
+                )
+            
+            return None
+            
+        except Exception as e:
+            logger.error(f"Agent {self.agent_id} decision failed: {e}")
+            self._set_state(AgentState.ERROR)
+            return None
+            
+    def execute(self, action: AgentAction, context: AgentContext) -> AgentResult:
+        """Execute tool action."""
+        self._set_state(AgentState.EXECUTING)
+        
+        import time
+        start = time.perf_counter()
+        
+        try:
+            from tools import invoke_tool
+            
+            result = invoke_tool(action.tool_name, **action.arguments)
+            elapsed = (time.perf_counter() - start) * 1000
+            
+            context.add_to_history(action.tool_name, result)
+            
+            self._set_state(AgentState.COMPLETED)
+            return AgentResult(
+                success=result.get("success", False),
+                data=result,
+                message=f"Executed {action.tool_name}",
+                actions_taken=[action.tool_name],
+                execution_time_ms=elapsed
+            )
+            
+        except Exception as e:
+            logger.error(f"Agent {self.agent_id} execution failed: {e}")
+            self._set_state(AgentState.ERROR)
+            return AgentResult(
+                success=False,
+                data=None,
+                message=str(e)
+            )
+
+
+class RuleBasedAgent(BaseAgent):
+    """
+    Agent that uses predefined rules for decision making.
+    Useful for deterministic behavior in Guided mode.
+    """
+    
+    def __init__(self,
+                 agent_id: str,
+                 role: AgentRole,
+                 rules: List[Callable[[AgentContext], Optional[AgentAction]]],
+                 tools: List[str] = None):
+        super().__init__(agent_id, role, tools)
+        self.rules = rules
+        
+    def decide(self, context: AgentContext) -> Optional[AgentAction]:
+        """Apply rules to decide action."""
+        self._set_state(AgentState.THINKING)
+        
+        for rule in self.rules:
+            action = rule(context)
+            if action is not None:
+                return action
+                
+        return None
+        
+    def execute(self, action: AgentAction, context: AgentContext) -> AgentResult:
+        """Execute action using tools."""
+        self._set_state(AgentState.EXECUTING)
+        
+        import time
+        start = time.perf_counter()
+        
+        try:
+            from tools import invoke_tool
+            
+            result = invoke_tool(action.tool_name, **action.arguments)
+            elapsed = (time.perf_counter() - start) * 1000
+            
+            context.add_to_history(action.tool_name, result)
+            
+            self._set_state(AgentState.COMPLETED)
+            return AgentResult(
+                success=result.get("success", False),
+                data=result,
+                message=f"Executed {action.tool_name}",
+                actions_taken=[action.tool_name],
+                execution_time_ms=elapsed
+            )
+            
+        except Exception as e:
+            self._set_state(AgentState.ERROR)
+            return AgentResult(
+                success=False,
+                data=None,
+                message=str(e)
+            )

agents/llm_adapter.py

@@ -0,0 +1,676 @@
+"""
+LLM Adapter: Model-agnostic LLM interface with multi-model fallback.
+Supports Gemini (native), OpenAI, Anthropic, Groq, Ollama, and any LiteLLM provider.
+
+Path: QAgents-workflos/agents/llm_adapter.py
+Related: config.py (GEMINI_MODELS cascade, CostTrackingConfig)
+         orchestrators/orchestrator.py (uses get_llm_adapter)
+         specialized_agents.py (agents use LLM adapters)
+
+Multi-Model Fallback System with Recovery:
+==========================================
+When a model hits rate limits (429) or errors, automatically falls back to next model.
+RECOVERY: When preferred model cooldown expires, automatically rotates back.
+
+Cascade order (by RPD - highest to lowest):
+  1. gemma-3-27b-it (14,400 RPD) - Highest availability
+  2. gemini-2.5-flash-lite (1,000 RPD) - DEFAULT PREFERRED
+  3. gemini-2.5-flash (250 RPD)
+  4. gemini-2.0-flash (200 RPD)
+  5. gemini-2.0-flash-lite (200 RPD)
+  6. gemini-2.5-pro (50 RPD) - Last resort
+
+Model Recovery Timer:
+=====================
+- Tracks when each model was rate-limited
+- Calculates recovery time (RPM cooldown: 60s, RPD cooldown: reset at midnight)
+- Automatically returns to preferred model when recovered
+- Preferred model index configurable (default: 1 = gemini-2.5-flash-lite)
+"""
+
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+from collections import deque
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# MULTI-MODEL RATE LIMITER
+# =============================================================================
+
+class ModelRateLimiter:
+    """
+    Rate limiter with per-model tracking, automatic fallback, and recovery.
+
+    Tracks:
+    - RPM: Requests per minute (sliding window)
+    - RPD: Requests per day (counter reset at midnight or manually)
+    - Recovery: When rate-limited models become available again
+
+    When current model exceeds limits, suggests next model in cascade.
+    When preferred model recovers, automatically rotates back.
+    """
+
+    def __init__(self, models: List[Dict] = None, preferred_model_idx: int = 1):
+        """
+        Initialize with model cascade from config.
+
+        Args:
+            models: List of model configs with rpm, rpd limits
+            preferred_model_idx: Index of preferred model (default: 1 = gemini-2.5-flash-lite)
+        """
+        from config import GEMINI_MODELS
+        self.models = models or GEMINI_MODELS
+        self.preferred_model_idx = preferred_model_idx  # Model to return to after recovery
+        self.current_model_idx = preferred_model_idx  # Start with preferred model
+
+        # Per-model tracking
+        self.model_usage: Dict[str, Dict] = {}
+        for model in self.models:
+            self.model_usage[model["name"]] = {
+                "rpm_window": deque(maxlen=model["rpm"]),  # Sliding window
+                "rpd_count": 0,
+                "rpd_reset_time": datetime.now().replace(hour=0, minute=0, second=0) + timedelta(days=1),
+                "last_request_time": 0,
+                "total_tokens": 0,
+                "total_time_ms": 0.0,
+                # Recovery tracking
+                "rate_limited_at": None,  # Timestamp when rate limited
+                "rpm_recovery_time": None,  # When RPM limit recovers
+                "rpd_recovery_time": None,  # When RPD limit recovers (midnight)
+            }
+
+    @property
+    def current_model(self) -> Dict:
+        """Get current model config."""
+        return self.models[self.current_model_idx]
+
+    @property
+    def current_model_name(self) -> str:
+        """Get current model name."""
+        return self.current_model["name"]
+
+    @property
+    def preferred_model_name(self) -> str:
+        """Get preferred model name."""
+        return self.models[self.preferred_model_idx]["name"]
+
+    def get_min_interval(self, model_name: str = None) -> float:
+        """Get minimum interval between requests for model (with 80% buffer)."""
+        if model_name is None:
+            model_name = self.current_model_name
+
+        for model in self.models:
+            if model["name"] == model_name:
+                # 80% buffer: 60s / (rpm * 0.8)
+                return 60.0 / (model["rpm"] * 0.8)
+        return 5.0  # Default 5 seconds
+
+    def check_preferred_model_recovery(self) -> bool:
+        """
+        Check if preferred model has recovered from rate limiting.
+        If recovered, automatically switch back to it.
+        
+        Returns:
+            True if switched back to preferred model
+        """
+        if self.current_model_idx == self.preferred_model_idx:
+            return False  # Already on preferred model
+
+        preferred_name = self.preferred_model_name
+        usage = self.model_usage.get(preferred_name)
+        if not usage:
+            return False
+
+        current_time = datetime.now()
+
+        # Check RPD recovery (resets at midnight)
+        if usage.get("rpd_recovery_time") and current_time >= usage["rpd_recovery_time"]:
+            usage["rpd_count"] = 0
+            usage["rpd_recovery_time"] = None
+            usage["rate_limited_at"] = None
+            logger.info(f"Preferred model {preferred_name} RPD limit reset - switching back")
+            self.current_model_idx = self.preferred_model_idx
+            return True
+
+        # Check RPM recovery (60 seconds)
+        if usage.get("rpm_recovery_time") and current_time >= usage["rpm_recovery_time"]:
+            usage["rpm_recovery_time"] = None
+            # Check if we can make a request now
+            can_req, _ = self.can_request(preferred_name)
+            if can_req:
+                logger.info(f"Preferred model {preferred_name} RPM recovered - switching back")
+                self.current_model_idx = self.preferred_model_idx
+                return True
+
+        return False
+
+    def can_request(self, model_name: str = None) -> tuple[bool, str]:
+        """
+        Check if we can make a request with current/specified model.
+        
+        Returns:
+            (can_request: bool, reason: str)
+        """
+        if model_name is None:
+            model_name = self.current_model_name
+        
+        if model_name not in self.model_usage:
+            return False, f"Unknown model: {model_name}"
+        
+        usage = self.model_usage[model_name]
+        model_config = None
+        for m in self.models:
+            if m["name"] == model_name:
+                model_config = m
+                break
+        
+        if not model_config:
+            return False, f"Model config not found: {model_name}"
+        
+        # Check RPD (reset if new day)
+        if datetime.now() >= usage["rpd_reset_time"]:
+            usage["rpd_count"] = 0
+            usage["rpd_reset_time"] = datetime.now().replace(hour=0, minute=0, second=0) + timedelta(days=1)
+        
+        if usage["rpd_count"] >= model_config["rpd"]:
+            return False, f"RPD limit reached ({model_config['rpd']}/day)"
+        
+        # Check RPM (sliding window)
+        current_time = time.time()
+        window = usage["rpm_window"]
+        
+        # Remove old entries (>60s ago)
+        while window and (current_time - window[0]) > 60:
+            window.popleft()
+        
+        if len(window) >= model_config["rpm"]:
+            return False, f"RPM limit reached ({model_config['rpm']}/min)"
+        
+        return True, "OK"
+    
+    def wait_if_needed(self, model_name: str = None) -> float:
+        """
+        Wait if necessary to respect rate limits.
+        
+        Returns:
+            Time waited in seconds
+        """
+        if model_name is None:
+            model_name = self.current_model_name
+        
+        if model_name not in self.model_usage:
+            return 0.0
+        
+        usage = self.model_usage[model_name]
+        current_time = time.time()
+        min_interval = self.get_min_interval(model_name)
+        
+        time_since_last = current_time - usage["last_request_time"]
+        
+        if time_since_last < min_interval:
+            sleep_time = min_interval - time_since_last
+            logger.info(f"Rate limiting [{model_name}]: waiting {sleep_time:.2f}s")
+            time.sleep(sleep_time)
+            return sleep_time
+        
+        return 0.0
+    
+    def record_request(self, model_name: str = None, tokens: int = 0, time_ms: float = 0):
+        """Record a successful request."""
+        if model_name is None:
+            model_name = self.current_model_name
+        
+        if model_name not in self.model_usage:
+            return
+        
+        usage = self.model_usage[model_name]
+        current_time = time.time()
+        
+        usage["rpm_window"].append(current_time)
+        usage["rpd_count"] += 1
+        usage["last_request_time"] = current_time
+        usage["total_tokens"] += tokens
+        usage["total_time_ms"] += time_ms
+        
+        logger.debug(f"Request recorded [{model_name}]: RPD {usage['rpd_count']}, tokens {tokens}")
+
+    def fallback_to_next(self, reason: str = "unknown") -> Optional[str]:
+        """
+        Switch to next model in cascade and record recovery time.
+
+        Args:
+            reason: Why fallback is needed ("rpm", "rpd", or "error")
+
+        Returns:
+            New model name or None if no more models available
+        """
+        current_model_name = self.current_model_name
+        usage = self.model_usage.get(current_model_name, {})
+        
+        # Record when this model was rate limited and set recovery time
+        now = datetime.now()
+        usage["rate_limited_at"] = now
+        
+        if "rpm" in reason.lower() or "429" in reason:
+            # RPM recovery: 60 seconds from now
+            usage["rpm_recovery_time"] = now + timedelta(seconds=60)
+            logger.info(f"Model {current_model_name} RPM limited - recovery at {usage['rpm_recovery_time']}")
+        elif "rpd" in reason.lower() or "quota" in reason.lower():
+            # RPD recovery: midnight tonight
+            usage["rpd_recovery_time"] = now.replace(hour=0, minute=0, second=0) + timedelta(days=1)
+            logger.info(f"Model {current_model_name} RPD limited - recovery at {usage['rpd_recovery_time']}")
+        
+        if self.current_model_idx + 1 < len(self.models):
+            self.current_model_idx += 1
+            new_model = self.current_model_name
+            logger.warning(f"Falling back to model: {new_model}")
+            return new_model
+        else:
+            logger.error("No more models available in fallback cascade!")
+            return None
+
+    def reset_to_preferred(self):
+        """Reset to preferred model (default: gemini-2.5-flash-lite)."""
+        self.current_model_idx = self.preferred_model_idx
+        logger.info(f"Reset to preferred model: {self.preferred_model_name}")
+
+    def get_usage_summary(self) -> Dict:
+        """Get usage summary for all models."""
+        summary = {}
+        for model in self.models:
+            name = model["name"]
+            usage = self.model_usage[name]
+            summary[name] = {
+                "rpm_used": len(usage["rpm_window"]),
+                "rpm_limit": model["rpm"],
+                "rpd_used": usage["rpd_count"],
+                "rpd_limit": model["rpd"],
+                "total_tokens": usage["total_tokens"],
+                "total_time_ms": usage["total_time_ms"]
+            }
+        return summary
+
+
+# Global rate limiter instance
+_global_rate_limiter: Optional[ModelRateLimiter] = None
+
+def get_rate_limiter() -> ModelRateLimiter:
+    """Get or create global rate limiter."""
+    global _global_rate_limiter
+    if _global_rate_limiter is None:
+        _global_rate_limiter = ModelRateLimiter()
+    return _global_rate_limiter
+
+
+# =============================================================================
+# LLM RESPONSE TYPES
+# =============================================================================
+
+@dataclass
+class LLMToolCall:
+    """Standardized tool call across all providers."""
+    tool_name: str
+    arguments: Dict[str, Any]
+    reasoning: str
+
+
+@dataclass
+class LLMResponse:
+    """Standardized response across all providers."""
+    text: str
+    tool_calls: List[LLMToolCall]
+    finish_reason: str
+    model_used: str = ""  # Track which model was actually used
+    tokens_used: int = 0  # Track token usage if available
+    time_ms: float = 0.0  # Track response time
+
+
+# =============================================================================
+# BASE ADAPTER
+# =============================================================================
+
+class BaseLLMAdapter(ABC):
+    """Abstract base for LLM adapters."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key
+
+    @abstractmethod
+    def generate(self,
+                 messages: List[Dict[str, str]],
+                 tools: Optional[List[Dict[str, Any]]] = None,
+                 temperature: float = 0.2,
+                 max_tokens: int = 2000) -> LLMResponse:
+        """Generate a response from the LLM."""
+        pass
+
+
+# =============================================================================
+# GEMINI ADAPTER WITH FALLBACK
+# =============================================================================
+
+class GeminiAdapter(BaseLLMAdapter):
+    """
+    Google Gemini API adapter with multi-model fallback.
+    
+    Automatically falls back to next model when:
+    - Rate limit exceeded (429)
+    - API error occurs (if fallback_on_error=True)
+    - Model unavailable
+    """
+
+    def __init__(self, 
+                 model: str = "gemini-2.5-flash-lite", 
+                 api_key: Optional[str] = None,
+                 enable_fallback: bool = True):
+        super().__init__(api_key)
+        self.model = model
+        self.enable_fallback = enable_fallback
+        self._client = None
+        self.rate_limiter = get_rate_limiter()
+
+    def _get_client(self):
+        """Lazy load Gemini client."""
+        if self._client is None:
+            try:
+                import google.genai
+                self._client = google.genai.Client(api_key=self.api_key)
+            except ImportError:
+                raise ImportError("google-genai not installed. Install with: pip install google-genai")
+        return self._client
+
+    def generate(self,
+                 messages: List[Dict[str, str]],
+                 tools: Optional[List[Dict[str, Any]]] = None,
+                 temperature: float = 0.2,
+                 max_tokens: int = 2000) -> LLMResponse:
+        """
+        Generate content using Gemini with automatic fallback.
+        
+        Will try current model first, then fall back through cascade on errors.
+        """
+        start_time = time.time()
+        last_error = None
+        attempts = 0
+        max_attempts = len(self.rate_limiter.models)
+        
+        while attempts < max_attempts:
+            current_model = self.rate_limiter.current_model_name
+            attempts += 1
+            
+            try:
+                # Check if preferred model has recovered
+                self.rate_limiter.check_preferred_model_recovery()
+
+                # Check if we can make a request
+                can_request, reason = self.rate_limiter.can_request(current_model)
+
+                if not can_request:
+                    logger.warning(f"Cannot request from {current_model}: {reason}")
+                    if self.enable_fallback:
+                        next_model = self.rate_limiter.fallback_to_next(reason)
+                        if next_model:
+                            continue
+                    raise Exception(f"Rate limit exceeded: {reason}")                # Wait if needed for RPM
+                self.rate_limiter.wait_if_needed(current_model)
+                
+                # Make the actual API call
+                response = self._call_gemini(current_model, messages, tools, temperature, max_tokens)
+                
+                # Record successful request
+                elapsed_ms = (time.time() - start_time) * 1000
+                tokens = self._estimate_tokens(messages, response.text)
+                self.rate_limiter.record_request(current_model, tokens, elapsed_ms)
+                
+                # Update response metadata
+                response.model_used = current_model
+                response.tokens_used = tokens
+                response.time_ms = elapsed_ms
+                
+                # Record in global cost tracking
+                try:
+                    from config import config
+                    config.evaluation.cost_tracking.record_request(current_model, tokens, elapsed_ms)
+                except Exception:
+                    pass  # Config might not be available
+                
+                return response
+                
+            except Exception as e:
+                last_error = e
+                error_str = str(e).lower()
+                
+                # Check if it's a rate limit error
+                is_rate_limit = "429" in str(e) or "rate" in error_str or "quota" in error_str
+                
+                if is_rate_limit or (self.enable_fallback and "error" in error_str):
+                    logger.warning(f"Error with {current_model}: {e}")
+                    next_model = self.rate_limiter.fallback_to_next(error_str)
+                    if next_model:
+                        logger.info(f"Retrying with fallback model: {next_model}")
+                        continue
+                
+                # Non-recoverable error or no fallback
+                raise
+        
+        # Exhausted all models
+        raise Exception(f"All models exhausted. Last error: {last_error}")
+    
+    def _call_gemini(self,
+                     model: str,
+                     messages: List[Dict[str, str]],
+                     tools: Optional[List[Dict[str, Any]]],
+                     temperature: float,
+                     max_tokens: int) -> LLMResponse:
+        """Make actual Gemini API call."""
+        client = self._get_client()
+        
+        # Convert messages to Gemini format
+        contents = []
+        for msg in messages:
+            role = "user" if msg["role"] in ["user", "system"] else "model"
+            contents.append({
+                "role": role,
+                "parts": [{"text": msg["content"]}]
+            })
+        
+        # Build tools for Gemini
+        gemini_tools = None
+        if tools:
+            gemini_tools = [{
+                "function_declarations": [t["function"] for t in tools]
+            }]
+        
+        # Call Gemini - tools go in config
+        config = {
+            "temperature": temperature,
+            "max_output_tokens": max_tokens
+        }
+        if gemini_tools:
+            config["tools"] = gemini_tools
+        
+        response = client.models.generate_content(
+            model=model,
+            contents=contents,
+            config=config
+        )
+        
+        # Extract response
+        text = response.text if hasattr(response, 'text') and response.text else ""
+        tool_calls = []
+
+        if hasattr(response, 'function_calls') and response.function_calls:
+            for func_call in response.function_calls:
+                args = func_call.args if isinstance(func_call.args, dict) else json.loads(str(func_call.args))
+                tool_calls.append(LLMToolCall(
+                    tool_name=func_call.name,
+                    arguments=args,
+                    reasoning=text or "Tool selected by Gemini"
+                ))
+
+        return LLMResponse(
+            text=text,
+            tool_calls=tool_calls,
+            finish_reason=str(response.finish_reason) if hasattr(response, 'finish_reason') else "STOP"
+        )
+    
+    def _estimate_tokens(self, messages: List[Dict], response_text: str) -> int:
+        """Estimate token count (rough: 4 chars = 1 token)."""
+        input_chars = sum(len(m.get("content", "") or "") for m in messages)
+        output_chars = len(response_text or "")
+        return (input_chars + output_chars) // 4
+
+
+# =============================================================================
+# LITELLM ADAPTER
+# =============================================================================
+
+class LiteLLMAdapter(BaseLLMAdapter):
+    """LiteLLM adapter for OpenAI, Anthropic, Groq, Ollama, and others."""
+
+    def __init__(self, model: str = "gpt-4o-mini", provider: str = "openai", api_key: Optional[str] = None):
+        super().__init__(api_key)
+        self.provider = provider
+        self.model_string = f"{provider}/{model}" if provider else model
+        self._client = None
+
+    def _get_client(self):
+        """Lazy load LiteLLM client."""
+        if self._client is None:
+            try:
+                import litellm
+                if self.api_key:
+                    litellm.api_key = self.api_key
+                self._client = litellm
+            except ImportError:
+                raise ImportError("litellm not installed. Install with: pip install litellm")
+        return self._client
+
+    def generate(self,
+                 messages: List[Dict[str, str]],
+                 tools: Optional[List[Dict[str, Any]]] = None,
+                 temperature: float = 0.2,
+                 max_tokens: int = 2000) -> LLMResponse:
+        """Generate content using LiteLLM."""
+        try:
+            start_time = time.time()
+            client = self._get_client()
+
+            # Call LiteLLM
+            response = client.completion(
+                model=self.model_string,
+                messages=messages,
+                tools=tools,
+                temperature=temperature,
+                max_tokens=max_tokens
+            )
+
+            # Extract response
+            choice = response.choices[0]
+            text = choice.message.content or ""
+            tool_calls = []
+
+            if hasattr(choice.message, 'tool_calls') and choice.message.tool_calls:
+                for tool_call in choice.message.tool_calls:
+                    args = json.loads(tool_call.function.arguments)
+                    tool_calls.append(LLMToolCall(
+                        tool_name=tool_call.function.name,
+                        arguments=args,
+                        reasoning=text or "Tool selected by LLM"
+                    ))
+
+            elapsed_ms = (time.time() - start_time) * 1000
+            tokens = response.usage.total_tokens if hasattr(response, 'usage') else 0
+            
+            return LLMResponse(
+                text=text,
+                tool_calls=tool_calls,
+                finish_reason=choice.finish_reason,
+                model_used=self.model_string,
+                tokens_used=tokens,
+                time_ms=elapsed_ms
+            )
+
+        except Exception as e:
+            logger.error(f"LiteLLM generation failed: {e}")
+            raise
+
+
+# =============================================================================
+# MOCK ADAPTER FOR TESTING
+# =============================================================================
+
+class MockLLMAdapter(BaseLLMAdapter):
+    """Mock LLM for testing without API keys."""
+
+    def generate(self,
+                 messages: List[Dict[str, str]],
+                 tools: Optional[List[Dict[str, Any]]] = None,
+                 temperature: float = 0.2,
+                 max_tokens: int = 2000) -> LLMResponse:
+        """Return a mock response."""
+        return LLMResponse(
+            text="Mock LLM response",
+            tool_calls=[],
+            finish_reason="stop",
+            model_used="mock",
+            tokens_used=10,
+            time_ms=1.0
+        )
+
+
+# =============================================================================
+# FACTORY FUNCTION
+# =============================================================================
+
+def get_llm_adapter(provider: str = "gemini",
+                    model: str = "gemini-2.5-flash-lite",
+                    api_key: Optional[str] = None,
+                    enable_fallback: bool = True) -> BaseLLMAdapter:
+    """
+    Factory function to get the appropriate LLM adapter.
+    
+    Args:
+        provider: LLM provider (gemini, openai, anthropic, etc.)
+        model: Model name
+        api_key: API key for authentication
+        enable_fallback: Enable automatic model fallback on rate limits
+    
+    Returns:
+        Configured LLM adapter
+    """
+    if provider == "gemini":
+        try:
+            return GeminiAdapter(model=model, api_key=api_key, enable_fallback=enable_fallback)
+        except ImportError:
+            logger.warning("Gemini not available, trying LiteLLM")
+            return LiteLLMAdapter(model=model, provider="gemini", api_key=api_key)
+
+    elif provider in ["openai", "anthropic", "groq", "ollama", "cohere", "mistral"]:
+        return LiteLLMAdapter(model=model, provider=provider, api_key=api_key)
+
+    elif provider == "mock":
+        return MockLLMAdapter(api_key=api_key)
+
+    else:
+        # Try LiteLLM for unknown providers
+        logger.warning(f"Unknown provider {provider}, attempting LiteLLM")
+        return LiteLLMAdapter(model=model, provider=provider, api_key=api_key)
+
+
+def get_usage_summary() -> Dict:
+    """Get usage summary from global rate limiter."""
+    return get_rate_limiter().get_usage_summary()
+
+
+def reset_rate_limiter():
+    """Reset rate limiter to default state."""
+    global _global_rate_limiter
+    _global_rate_limiter = None

agents/specialized_agents.py

@@ -0,0 +1,223 @@
+# Path: QAgents-workflos/agents/specialized_agents.py
+# Relations: Uses base_agent.py, prompts/agent_prompts.py
+# Description: Domain-specific agents for quantum circuit optimization
+"""
+Specialized Quantum Agents: Domain-specific agents for circuit optimization.
+"""
+
+from typing import Optional, List, Dict, Any
+from .base_agent import (
+    LLMAgent, RuleBasedAgent, AgentRole,
+    AgentContext, AgentAction, AgentResult
+)
+
+
+def _goal_to_string(context: AgentContext) -> str:
+    """Safely extract goal as string from context."""
+    goal = context.goal
+    if isinstance(goal, list):
+        goal = goal[0] if goal else ""
+    return str(goal).lower() if goal else ""
+
+
+class ArchitectAgent(LLMAgent):
+    """
+    Plans the overall circuit structure.
+    Decides what type of circuit to build and the high-level approach.
+    """
+
+    def __init__(self, agent_id: str = "architect"):
+        from prompts import ARCHITECT_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.ARCHITECT,
+            system_prompt=ARCHITECT_PROMPT,
+            tools=[
+                "create_from_template",
+                "generate_from_description",
+                "analyze_circuit"
+            ]
+        )
+
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when no circuit exists or replanning needed."""
+        goal = _goal_to_string(context)
+        return context.current_circuit is None or "replan" in goal
+
+
+class BuilderAgent(LLMAgent):
+    """
+    Builds and modifies circuits based on plans.
+    Handles the actual circuit construction.
+    """
+
+    def __init__(self, agent_id: str = "builder"):
+        from prompts import BUILDER_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.BUILDER,
+            system_prompt=BUILDER_PROMPT,
+            tools=[
+                "create_from_template",
+                "generate_random_circuit",
+                "generate_from_description",
+                "compose_circuits",
+                "tensor_circuits",
+                "repeat_circuit"
+            ]
+        )
+
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when we need to build a circuit."""
+        has_plan = any("plan" in str(h.get("action", "")).lower() for h in context.history)
+        no_circuit = context.current_circuit is None
+        return has_plan or no_circuit
+
+
+class ValidatorAgent(LLMAgent):
+    """
+    Validates circuits for correctness and hardware compatibility.
+    """
+
+    def __init__(self, agent_id: str = "validator"):
+        from prompts import VALIDATOR_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.VALIDATOR,
+            system_prompt=VALIDATOR_PROMPT,
+            tools=[
+                "validate_syntax",
+                "check_connectivity",
+                "verify_unitary"
+            ]
+        )
+
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when there's a circuit to validate."""
+        return context.current_circuit is not None
+
+
+class OptimizerAgent(LLMAgent):
+    """
+    Optimizes circuits for depth, gate count, and hardware fitness.
+    """
+
+    def __init__(self, agent_id: str = "optimizer"):
+        from prompts import OPTIMIZER_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.OPTIMIZER,
+            system_prompt=OPTIMIZER_PROMPT,
+            tools=[
+                "generate_inverse",
+                "compose_circuits",
+                "analyze_circuit",
+                "calculate_complexity",
+                "calculate_hardware_fitness"
+            ]
+        )
+
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when circuit exists and optimization is needed."""
+        if context.current_circuit is None:
+            return False
+        goal = _goal_to_string(context)
+        return "optimize" in goal or "improve" in goal
+
+
+class AnalyzerAgent(LLMAgent):
+    """
+    Analyzes circuit properties and provides insights.
+    """
+
+    def __init__(self, agent_id: str = "analyzer"):
+        from prompts import ANALYZER_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.ANALYZER,
+            system_prompt=ANALYZER_PROMPT,
+            tools=[
+                "parse_qasm",
+                "analyze_circuit",
+                "get_circuit_depth",
+                "get_statevector",
+                "get_probabilities",
+                "estimate_resources",
+                "estimate_noise"
+            ]
+        )
+        
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when circuit exists and analysis is needed."""
+        return context.current_circuit is not None
+
+
+class ScorerAgent(LLMAgent):
+    """
+    Scores circuits on various metrics.
+    """
+
+    def __init__(self, agent_id: str = "scorer"):
+        from prompts import SCORER_PROMPT
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.SCORER,
+            system_prompt=SCORER_PROMPT,
+            tools=[
+                "calculate_complexity",
+                "calculate_hardware_fitness",
+                "calculate_expressibility",
+                "simulate_circuit"
+            ]
+        )
+
+    def can_handle(self, context: AgentContext) -> bool:
+        """Can handle when circuit exists and scoring is requested."""
+        if context.current_circuit is None:
+            return False
+        goal = _goal_to_string(context)
+        return "score" in goal or "evaluate" in goal
+
+
+class SimulatorAgent(RuleBasedAgent):
+    """
+    Rule-based agent for circuit simulation.
+    Deterministic - always simulates when circuit is ready.
+    """
+
+    def __init__(self, agent_id: str = "simulator"):
+        def simulate_rule(context: AgentContext) -> Optional[AgentAction]:
+            if context.current_circuit:
+                return AgentAction(
+                    tool_name="simulate_circuit",
+                    arguments={"qasm": context.current_circuit, "shots": 1024},
+                    reasoning="Circuit ready for simulation"
+                )
+            return None
+
+        super().__init__(
+            agent_id=agent_id,
+            role=AgentRole.ANALYZER,
+            rules=[simulate_rule],
+            tools=["simulate_circuit", "get_statevector", "get_probabilities"]
+        )
+
+
+# Factory function to create all specialized agents
+def create_all_agents() -> Dict[str, LLMAgent]:
+    """Create instances of all specialized agents."""
+    return {
+        "architect": ArchitectAgent(),
+        "builder": BuilderAgent(),
+        "validator": ValidatorAgent(),
+        "optimizer": OptimizerAgent(),
+        "analyzer": AnalyzerAgent(),
+        "scorer": ScorerAgent(),
+        "simulator": SimulatorAgent()
+    }

app.py

@@ -0,0 +1,120 @@
+"""
+QAgents-Workflows: Hugging Face Space Entry Point
+Provides a Gradio interface for the Quantum Circuit Orchestrator.
+Reads all configuration from environment variables for HF Space deployment.
+"""
+
+import os
+import gradio as gr
+import logging
+from config import LLMConfig
+from orchestrators import create_orchestrator
+from client.mcp_client import get_client
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Log environment configuration at startup
+logger.info("=" * 70)
+logger.info("QAgents Quantum Circuit Orchestrator - Initialization")
+logger.info("=" * 70)
+logger.info(f"LLM Provider: {os.getenv('LLM_PROVIDER', 'gemini (default)')}")
+logger.info(f"LLM Model: {os.getenv('LLM_MODEL', 'gemini-2.5-flash-lite (default)')}")
+logger.info(f"MCP Server URL: {os.getenv('MCP_SERVER_URL', 'http://127.0.0.1:7861 (default)')}")
+logger.info(f"Google API Key configured: {bool(os.getenv('GOOGLE_API_KEY') or os.getenv('GENAI_API_KEY'))}")
+logger.info("=" * 70)
+
+# Initialize MCP client (will use MCP_SERVER_URL env var if set)
+mcp_client = get_client()
+
+def generate_circuit(prompt, mode, difficulty):
+    """Generate a quantum circuit based on the prompt and mode."""
+    try:
+        logger.info(f"Generating circuit: mode={mode}, difficulty={difficulty}")
+        logger.info(f"Prompt: {prompt}")
+        
+        # Create orchestrator
+        orch = create_orchestrator(mode.lower())
+        
+        # Run generation
+        # Note: In a real deployment, we might want to map difficulty to specific constraints
+        # For now, we pass the prompt directly
+        result = orch.run(prompt)
+        
+        if result.success:
+            output = f"✅ Success ({result.execution_time_ms:.0f}ms)\n\n"
+            if result.final_output:
+                output += result.final_output
+            else:
+                output += "No QASM generated."
+                
+            # Add metrics if available
+            metrics = f"LLM Calls: {result.steps_completed}\n"
+            if hasattr(result, 'tokens_used'):
+                metrics += f"Tokens: {result.tokens_used}\n"
+                
+            return output, metrics
+        else:
+            error_msg = "\n".join(result.errors)
+            return f"❌ Failed ({result.execution_time_ms:.0f}ms)\n\nErrors:\n{error_msg}", "N/A"
+            
+    except Exception as e:
+        logger.error(f"Error generating circuit: {e}")
+        return f"❌ System Error: {str(e)}", "Error"
+
+def check_mcp_status():
+    """Check connection to MCP server."""
+    try:
+        is_healthy = mcp_client.health_check()
+        status = "🟢 Connected" if is_healthy else "🔴 Disconnected"
+        url = os.environ.get("MCP_SERVER_URL", "http://127.0.0.1:7861")
+        return f"{status} ({url})"
+    except Exception as e:
+        return f"🔴 Error: {str(e)}"
+
+# Create Gradio Interface
+with gr.Blocks(title="Quantum Circuit Orchestrator") as demo:
+    gr.Markdown("# ⚛️ QAgents: Quantum Circuit Orchestrator")
+    gr.Markdown("Multi-agent system for generating optimized quantum circuits.")
+    
+    with gr.Row():
+        with gr.Column(scale=2):
+            prompt_input = gr.Textbox(
+                label="Circuit Description",
+                placeholder="e.g., Create a 3-qubit GHZ state",
+                lines=3
+            )
+            with gr.Row():
+                mode_select = gr.Dropdown(
+                    choices=["naked", "quasar", "hybrid", "blackboard"],
+                    value="naked",
+                    label="Orchestration Mode"
+                )
+                difficulty_select = gr.Dropdown(
+                    choices=["EASY", "MEDIUM", "HARD", "VERY_HARD"],
+                    value="EASY",
+                    label="Estimated Difficulty"
+                )
+            
+            generate_btn = gr.Button("Generate Circuit", variant="primary")
+            
+        with gr.Column(scale=1):
+            mcp_status = gr.Textbox(label="MCP Server Status", value=check_mcp_status, interactive=False)
+            metrics_output = gr.Textbox(label="Execution Metrics", lines=4)
+    
+    with gr.Row():
+        qasm_output = gr.Code(label="Generated QASM", language="qasm", lines=15)
+
+    # Event handlers
+    generate_btn.click(
+        fn=generate_circuit,
+        inputs=[prompt_input, mode_select, difficulty_select],
+        outputs=[qasm_output, metrics_output]
+    )
+    
+    # Refresh status on load
+    demo.load(fn=check_mcp_status, outputs=[mcp_status])
+
+if __name__ == "__main__":
+    demo.launch()

client/__init__.py

@@ -0,0 +1,5 @@
+"""MCP Client module."""
+
+from .mcp_client import MCPClient, MCPResponse, get_client
+
+__all__ = ["MCPClient", "MCPResponse", "get_client"]

client/mcp_client.py

@@ -0,0 +1,698 @@
+# Path: QAgents-workflos/client/mcp_client.py
+# Relations: Uses QuantumArchitect-MCP Gradio server
+# Description: MCP client with fallback local implementations for missing endpoints
+"""
+MCP Client: Connection to QuantumArchitect-MCP endpoints.
+Provides both synchronous and async interfaces.
+
+Available Gradio endpoints (as of latest scan):
+- ui_create_circuit: Create circuit from template
+- ui_validate_circuit: Validate QASM syntax
+- ui_simulate_circuit: Simulate circuit
+- ui_score_circuit: Score circuit complexity/fitness
+
+Missing endpoints use local fallback implementations.
+"""
+
+import requests
+from typing import Any, Dict, Optional, List
+from dataclasses import dataclass, field
+from datetime import datetime
+import json
+import logging
+import re
+import time
+import random
+import math
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MCPResponse:
+    """Standardized response from MCP endpoints."""
+    success: bool
+    data: Any
+    endpoint: str
+    timestamp: datetime = field(default_factory=datetime.now)
+    error: Optional[str] = None
+    execution_time_ms: float = 0.0
+    is_fallback: bool = False  # True if using local fallback
+
+
+class QASMLocalAnalyzer:
+    """Local QASM analysis for fallback when MCP endpoints unavailable."""
+    
+    GATE_PATTERN = re.compile(
+        r'^(h|x|y|z|s|t|sdg|tdg|cx|cz|cy|swap|ccx|rz|rx|ry|u1|u2|u3|p|measure|barrier)\b', 
+        re.IGNORECASE
+    )
+    
+    @staticmethod
+    def parse_qasm(qasm_code: str) -> Dict[str, Any]:
+        """Parse QASM code and extract structure."""
+        lines = [l.strip() for l in qasm_code.strip().split('\n') 
+                 if l.strip() and not l.strip().startswith('//')]
+        
+        result = {
+            'openqasm_version': '2.0',
+            'includes': [],
+            'qregs': [],
+            'cregs': [],
+            'gates': [],
+            'num_qubits': 0,
+            'num_classical': 0
+        }
+        
+        for line in lines:
+            if line.startswith('OPENQASM'):
+                result['openqasm_version'] = line.split()[1].rstrip(';')
+            elif line.startswith('include'):
+                result['includes'].append(line.split('"')[1] if '"' in line else line.split()[1])
+            elif line.startswith('qreg'):
+                match = re.search(r'qreg\s+(\w+)\[(\d+)\]', line)
+                if match:
+                    result['qregs'].append({'name': match.group(1), 'size': int(match.group(2))})
+                    result['num_qubits'] += int(match.group(2))
+            elif line.startswith('creg'):
+                match = re.search(r'creg\s+(\w+)\[(\d+)\]', line)
+                if match:
+                    result['cregs'].append({'name': match.group(1), 'size': int(match.group(2))})
+                    result['num_classical'] += int(match.group(2))
+            elif QASMLocalAnalyzer.GATE_PATTERN.match(line):
+                gate_name = line.split()[0].split('(')[0]
+                result['gates'].append({'gate': gate_name, 'raw': line.rstrip(';')})
+        
+        return result
+    
+    @staticmethod
+    def analyze_circuit(qasm_code: str) -> Dict[str, Any]:
+        """Analyze circuit properties."""
+        parsed = QASMLocalAnalyzer.parse_qasm(qasm_code)
+        gates = parsed['gates']
+        
+        gate_counts = {}
+        single_qubit_gates = 0
+        two_qubit_gates = 0
+        multi_qubit_gates = 0
+        measurement_count = 0
+        
+        for g in gates:
+            gate = g['gate'].lower()
+            gate_counts[gate] = gate_counts.get(gate, 0) + 1
+            
+            if gate == 'measure':
+                measurement_count += 1
+            elif gate in ['cx', 'cz', 'cy', 'swap']:
+                two_qubit_gates += 1
+            elif gate in ['ccx', 'cswap']:
+                multi_qubit_gates += 1
+            else:
+                single_qubit_gates += 1
+        
+        # Estimate depth (simplified: assume all gates sequential)
+        depth = len([g for g in gates if g['gate'].lower() != 'measure'])
+        
+        return {
+            'num_qubits': parsed['num_qubits'],
+            'num_classical_bits': parsed['num_classical'],
+            'depth': depth,
+            'gate_count': len(gates),
+            'gate_breakdown': gate_counts,
+            'single_qubit_gates': single_qubit_gates,
+            'two_qubit_gates': two_qubit_gates,
+            'multi_qubit_gates': multi_qubit_gates,
+            'measurements': measurement_count
+        }
+    
+    @staticmethod
+    def get_depth(qasm_code: str) -> int:
+        """Get circuit depth."""
+        analysis = QASMLocalAnalyzer.analyze_circuit(qasm_code)
+        return analysis['depth']
+    
+    @staticmethod  
+    def calculate_complexity(qasm_code: str) -> Dict[str, Any]:
+        """Calculate complexity score."""
+        analysis = QASMLocalAnalyzer.analyze_circuit(qasm_code)
+        
+        # Scoring formula
+        depth_score = min(analysis['depth'] / 50.0, 1.0) * 30
+        gate_score = min(analysis['gate_count'] / 100.0, 1.0) * 30
+        two_q_score = min(analysis['two_qubit_gates'] / 20.0, 1.0) * 25
+        qubit_score = min(analysis['num_qubits'] / 10.0, 1.0) * 15
+        
+        total = depth_score + gate_score + two_q_score + qubit_score
+        
+        return {
+            'complexity_score': round(total, 2),
+            'depth_contribution': round(depth_score, 2),
+            'gate_contribution': round(gate_score, 2),
+            'entanglement_contribution': round(two_q_score, 2),
+            'qubit_contribution': round(qubit_score, 2),
+            'raw_metrics': analysis
+        }
+    
+    @staticmethod
+    def validate_syntax(qasm_code: str) -> Dict[str, Any]:
+        """Validate QASM syntax."""
+        errors = []
+        warnings = []
+        
+        lines = qasm_code.strip().split('\n')
+        
+        has_openqasm = False
+        has_qreg = False
+        
+        for i, line in enumerate(lines, 1):
+            line = line.strip()
+            if not line or line.startswith('//'):
+                continue
+                
+            if line.startswith('OPENQASM'):
+                has_openqasm = True
+            elif line.startswith('qreg'):
+                has_qreg = True
+            elif not line.startswith(('include', 'creg', 'barrier', 'measure', 'OPENQASM', 'qreg')):
+                # Check for valid gate
+                if not QASMLocalAnalyzer.GATE_PATTERN.match(line):
+                    if line and not line.endswith(';'):
+                        warnings.append(f"Line {i}: Missing semicolon")
+        
+        if not has_openqasm:
+            errors.append("Missing OPENQASM version declaration")
+        if not has_qreg:
+            errors.append("No quantum register (qreg) defined")
+        
+        return {
+            'valid': len(errors) == 0,
+            'errors': errors,
+            'warnings': warnings,
+            'line_count': len(lines)
+        }
+    
+    @staticmethod
+    def calculate_hardware_fitness(qasm_code: str, hardware: str = "ibm_brisbane") -> Dict[str, Any]:
+        """Calculate hardware fitness score."""
+        analysis = QASMLocalAnalyzer.analyze_circuit(qasm_code)
+        
+        # Hardware profiles (simplified)
+        profiles = {
+            'ibm_brisbane': {'max_qubits': 127, 'connectivity': 'heavy-hex', 'two_q_error': 0.01},
+            'ibm_sherbrooke': {'max_qubits': 127, 'connectivity': 'heavy-hex', 'two_q_error': 0.008},
+            'rigetti_aspen': {'max_qubits': 80, 'connectivity': 'octagonal', 'two_q_error': 0.02},
+            'ionq_harmony': {'max_qubits': 11, 'connectivity': 'all-to-all', 'two_q_error': 0.005}
+        }
+        
+        profile = profiles.get(hardware, profiles['ibm_brisbane'])
+        
+        # Calculate fitness
+        qubit_fit = 100 if analysis['num_qubits'] <= profile['max_qubits'] else 50
+        depth_penalty = min(analysis['depth'] * 2, 30)
+        two_q_penalty = analysis['two_qubit_gates'] * profile['two_q_error'] * 100
+        
+        fitness = max(0, qubit_fit - depth_penalty - two_q_penalty)
+        
+        return {
+            'fitness_score': round(fitness, 2),
+            'hardware': hardware,
+            'qubit_fit': qubit_fit,
+            'depth_penalty': round(depth_penalty, 2),
+            'error_penalty': round(two_q_penalty, 2),
+            'recommendation': 'suitable' if fitness > 70 else 'marginal' if fitness > 40 else 'poor'
+        }
+
+
+class MCPClient:
+    """
+    Client for QuantumArchitect-MCP server.
+    Wraps MCP endpoints with fallback to local implementations.
+    
+    Primary endpoints (from Gradio):
+    - ui_create_circuit
+    - ui_validate_circuit
+    - ui_simulate_circuit
+    - ui_score_circuit
+    
+    Missing endpoints use QASMLocalAnalyzer for fallback.
+    """
+
+    def __init__(self, base_url: str = "http://127.0.0.1:7861"):
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        self._connected = False
+        self._analyzer = QASMLocalAnalyzer()
+
+    def _call(self, endpoint: str, **kwargs) -> MCPResponse:
+        """Internal method to call MCP endpoints."""
+        start = time.perf_counter()
+
+        try:
+            url = f"{self.base_url}/gradio_api/call/{endpoint}"
+            payload = {"data": list(kwargs.values()) if kwargs else []}
+            
+            response = self.session.post(url, json=payload, timeout=30)
+            response.raise_for_status()
+
+            result = response.json()
+            event_id = result.get("event_id")
+
+            if event_id:
+                result_url = f"{self.base_url}/gradio_api/call/{endpoint}/{event_id}"
+                result_response = self.session.get(result_url, timeout=30)
+
+                lines = result_response.text.strip().split("\n")
+                for line in lines:
+                    if line.startswith("data:"):
+                        data = json.loads(line[5:].strip())
+                        elapsed = (time.perf_counter() - start) * 1000
+                        return MCPResponse(
+                            success=True,
+                            data=data[0] if isinstance(data, list) and len(data) == 1 else data,
+                            endpoint=endpoint,
+                            execution_time_ms=elapsed
+                        )
+
+            elapsed = (time.perf_counter() - start) * 1000
+            return MCPResponse(
+                success=True,
+                data=result,
+                endpoint=endpoint,
+                execution_time_ms=elapsed
+            )
+
+        except Exception as e:
+            elapsed = (time.perf_counter() - start) * 1000
+            logger.warning(f"MCP call failed: {endpoint} - {e}")
+            return MCPResponse(
+                success=False,
+                data=None,
+                endpoint=endpoint,
+                error=str(e),
+                execution_time_ms=elapsed
+            )
+
+    def _fallback_response(self, endpoint: str, data: Any, start_time: float) -> MCPResponse:
+        """Create a fallback response using local implementation."""
+        elapsed = (time.perf_counter() - start_time) * 1000
+        return MCPResponse(
+            success=True,
+            data=data,
+            endpoint=f"{endpoint}(fallback)",
+            execution_time_ms=elapsed,
+            is_fallback=True
+        )
+
+    def health_check(self) -> bool:
+        """Check if MCP server is reachable."""
+        try:
+            response = self.session.get(f"{self.base_url}/", timeout=5)
+            self._connected = response.status_code == 200
+            return self._connected
+        except:
+            self._connected = False
+            return False
+
+    # ===== Circuit Creation Endpoints =====
+    
+    def create_circuit_from_template(self, template_name: str, num_qubits: int = 2) -> MCPResponse:
+        """Create a circuit from a predefined template.
+        Maps to ui_create_circuit endpoint in Gradio."""
+        return self._call("ui_create_circuit", template=template_name, qubits=num_qubits, params="{}")
+
+    def generate_random_circuit(self, num_qubits: int = 3, depth: int = 5,
+                                gate_set: str = "h,cx,rz") -> MCPResponse:
+        """Generate a random quantum circuit. Uses local fallback."""
+        start = time.perf_counter()
+        gates = gate_set.split(',')
+        
+        qasm_lines = [
+            'OPENQASM 2.0;',
+            'include "qelib1.inc";',
+            f'qreg q[{num_qubits}];',
+            f'creg c[{num_qubits}];'
+        ]
+        
+        for _ in range(depth):
+            gate = random.choice(gates)
+            if gate in ['h', 'x', 'y', 'z', 's', 't']:
+                q = random.randint(0, num_qubits - 1)
+                qasm_lines.append(f'{gate} q[{q}];')
+            elif gate in ['cx', 'cz']:
+                if num_qubits >= 2:
+                    q1 = random.randint(0, num_qubits - 1)
+                    q2 = random.randint(0, num_qubits - 1)
+                    while q2 == q1:
+                        q2 = random.randint(0, num_qubits - 1)
+                    qasm_lines.append(f'{gate} q[{q1}], q[{q2}];')
+            elif gate in ['rz', 'rx', 'ry']:
+                q = random.randint(0, num_qubits - 1)
+                angle = round(random.uniform(0, 2 * math.pi), 4)
+                qasm_lines.append(f'{gate}({angle}) q[{q}];')
+        
+        qasm_lines.append(f'measure q -> c;')
+        qasm_code = '\n'.join(qasm_lines)
+        
+        return self._fallback_response("generate_random_circuit", {'qasm': qasm_code}, start)
+
+    def generate_circuit_from_description(self, description: str) -> MCPResponse:
+        """Generate circuit from natural language description.
+        Uses ui_create_circuit with best-matching template."""
+        desc_lower = description.lower()
+        
+        if 'entangle' in desc_lower or 'bell' in desc_lower:
+            template = 'bell_state'
+        elif 'ghz' in desc_lower:
+            template = 'ghz_state'
+        elif 'superposition' in desc_lower:
+            template = 'superposition'
+        elif 'qft' in desc_lower or 'fourier' in desc_lower:
+            template = 'qft'
+        elif 'grover' in desc_lower or 'search' in desc_lower:
+            template = 'grover'
+        elif 'vqe' in desc_lower or 'variational' in desc_lower:
+            template = 'vqe'
+        else:
+            template = 'bell_state'
+        
+        return self._call("ui_create_circuit", template=template, qubits=2, params="{}")
+
+    # ===== Parsing & Analysis Endpoints (Fallback) =====
+
+    def parse_qasm(self, qasm_code: str) -> MCPResponse:
+        """Parse OpenQASM code into circuit structure. Uses local fallback."""
+        start = time.perf_counter()
+        parsed = self._analyzer.parse_qasm(qasm_code)
+        return self._fallback_response("parse_qasm", parsed, start)
+
+    def analyze_circuit(self, qasm_code: str) -> MCPResponse:
+        """Analyze circuit properties (depth, gates, etc.). Uses local fallback."""
+        start = time.perf_counter()
+        analysis = self._analyzer.analyze_circuit(qasm_code)
+        return self._fallback_response("analyze_circuit", analysis, start)
+
+    def get_circuit_depth(self, qasm_code: str) -> MCPResponse:
+        """Get the depth of a circuit. Uses local fallback."""
+        start = time.perf_counter()
+        depth = self._analyzer.get_depth(qasm_code)
+        return self._fallback_response("get_circuit_depth", {'depth': depth}, start)
+
+    # ===== Validation Endpoints =====
+
+    def validate_syntax(self, qasm_code: str) -> MCPResponse:
+        """Validate QASM syntax. Maps to ui_validate_circuit."""
+        return self._call("ui_validate_circuit", qasm=qasm_code, hardware="")
+
+    def check_connectivity(self, qasm_code: str, hardware: str = "ibm_brisbane") -> MCPResponse:
+        """Check if circuit respects hardware connectivity. Uses ui_validate_circuit."""
+        return self._call("ui_validate_circuit", qasm=qasm_code, hardware=hardware)
+
+    def verify_unitary(self, qasm_code: str) -> MCPResponse:
+        """Verify circuit produces valid unitary. Uses local fallback."""
+        start = time.perf_counter()
+        validation = self._analyzer.validate_syntax(qasm_code)
+        result = {
+            'is_unitary': validation['valid'],
+            'errors': validation['errors'],
+            'note': 'Local validation - full unitary check requires simulation'
+        }
+        return self._fallback_response("verify_unitary", result, start)
+
+    # ===== Simulation Endpoints =====
+
+    def simulate_circuit(self, qasm_code: str, shots: int = 1024) -> MCPResponse:
+        """Simulate circuit and get measurement results. Maps to ui_simulate_circuit."""
+        return self._call("ui_simulate_circuit", qasm=qasm_code, shots=shots)
+
+    def get_statevector(self, qasm_code: str) -> MCPResponse:
+        """Get the statevector of a circuit. Uses ui_simulate_circuit."""
+        result = self._call("ui_simulate_circuit", qasm=qasm_code, shots=1)
+        if result.success and result.data:
+            result.data = {'statevector_hint': 'Use simulation results for state info'}
+        return result
+
+    def get_probabilities(self, qasm_code: str) -> MCPResponse:
+        """Get probability distribution from circuit. Uses ui_simulate_circuit."""
+        result = self._call("ui_simulate_circuit", qasm=qasm_code, shots=1024)
+        if result.success and result.data:
+            # Extract probabilities from histogram
+            result.endpoint = "get_probabilities"
+        return result
+
+    # ===== Scoring Endpoints =====
+
+    def calculate_complexity_score(self, qasm_code: str) -> MCPResponse:
+        """Calculate circuit complexity score. Tries ui_score_circuit then fallback."""
+        result = self._call("ui_score_circuit", qasm=qasm_code, hardware="ibm_brisbane")
+        if result.success:
+            return result
+        
+        # Fallback to local
+        start = time.perf_counter()
+        complexity = self._analyzer.calculate_complexity(qasm_code)
+        return self._fallback_response("calculate_complexity_score", complexity, start)
+
+    def calculate_hardware_fitness(self, qasm_code: str, hardware: str = "ibm_brisbane") -> MCPResponse:
+        """Calculate hardware fitness score. Tries ui_score_circuit then fallback."""
+        result = self._call("ui_score_circuit", qasm=qasm_code, hardware=hardware)
+        if result.success:
+            return result
+            
+        # Fallback to local
+        start = time.perf_counter()
+        fitness = self._analyzer.calculate_hardware_fitness(qasm_code, hardware)
+        return self._fallback_response("calculate_hardware_fitness", fitness, start)
+
+    def calculate_expressibility(self, qasm_code: str) -> MCPResponse:
+        """Calculate circuit expressibility. Uses local fallback."""
+        start = time.perf_counter()
+        analysis = self._analyzer.analyze_circuit(qasm_code)
+        
+        # Expressibility heuristic based on gate diversity and depth
+        gate_types = len(analysis['gate_breakdown'])
+        depth_factor = min(analysis['depth'] / 20.0, 1.0)
+        entangle_factor = min(analysis['two_qubit_gates'] / 5.0, 1.0)
+        
+        expressibility = (gate_types * 0.3 + depth_factor * 0.35 + entangle_factor * 0.35) * 100
+        
+        result = {
+            'expressibility_score': round(expressibility, 2),
+            'gate_diversity': gate_types,
+            'depth_factor': round(depth_factor, 2),
+            'entanglement_factor': round(entangle_factor, 2)
+        }
+        return self._fallback_response("calculate_expressibility", result, start)
+
+    # ===== Resource Estimation Endpoints (Fallback) =====
+
+    def estimate_resources(self, qasm_code: str) -> MCPResponse:
+        """Estimate resource requirements. Uses local fallback."""
+        start = time.perf_counter()
+        analysis = self._analyzer.analyze_circuit(qasm_code)
+        
+        result = {
+            'qubits_required': analysis['num_qubits'],
+            'classical_bits': analysis['num_classical_bits'],
+            'gate_count': analysis['gate_count'],
+            'depth': analysis['depth'],
+            'estimated_runtime_ms': analysis['depth'] * 0.1,  # Rough estimate
+            'memory_footprint_bytes': analysis['num_qubits'] * 16 * (2 ** analysis['num_qubits'])
+        }
+        return self._fallback_response("estimate_resources", result, start)
+
+    def estimate_noise(self, qasm_code: str, hardware: str = "ibm_brisbane") -> MCPResponse:
+        """Estimate noise impact on circuit. Uses local fallback."""
+        start = time.perf_counter()
+        analysis = self._analyzer.analyze_circuit(qasm_code)
+        
+        # Noise profiles (simplified)
+        noise_rates = {
+            'ibm_brisbane': {'single_q': 0.001, 'two_q': 0.01, 'readout': 0.02},
+            'ibm_sherbrooke': {'single_q': 0.0008, 'two_q': 0.008, 'readout': 0.015},
+            'rigetti_aspen': {'single_q': 0.002, 'two_q': 0.02, 'readout': 0.03},
+            'ionq_harmony': {'single_q': 0.0003, 'two_q': 0.005, 'readout': 0.01}
+        }
+        
+        rates = noise_rates.get(hardware, noise_rates['ibm_brisbane'])
+        
+        single_q_error = analysis['single_qubit_gates'] * rates['single_q']
+        two_q_error = analysis['two_qubit_gates'] * rates['two_q']
+        readout_error = analysis['measurements'] * rates['readout']
+        total_error = 1 - (1 - single_q_error) * (1 - two_q_error) * (1 - readout_error)
+        
+        result = {
+            'estimated_fidelity': round(1 - total_error, 4),
+            'single_qubit_error': round(single_q_error, 4),
+            'two_qubit_error': round(two_q_error, 4),
+            'readout_error': round(readout_error, 4),
+            'total_error_probability': round(total_error, 4),
+            'hardware': hardware
+        }
+        return self._fallback_response("estimate_noise", result, start)
+
+    # ===== Composition Endpoints (Fallback) =====
+
+    def compose_circuits(self, qasm1: str, qasm2: str, qubit_mapping: str = "") -> MCPResponse:
+        """Compose two circuits sequentially. Uses local fallback."""
+        start = time.perf_counter()
+        
+        # Parse both circuits
+        parsed1 = self._analyzer.parse_qasm(qasm1)
+        parsed2 = self._analyzer.parse_qasm(qasm2)
+        
+        # Simple sequential composition
+        num_qubits = max(parsed1['num_qubits'], parsed2['num_qubits'])
+        
+        lines = [
+            'OPENQASM 2.0;',
+            'include "qelib1.inc";',
+            f'qreg q[{num_qubits}];',
+            f'creg c[{num_qubits}];'
+        ]
+        
+        # Add gates from both circuits
+        for g in parsed1['gates']:
+            if g['gate'].lower() != 'measure':
+                lines.append(f"{g['raw']};")
+        for g in parsed2['gates']:
+            lines.append(f"{g['raw']};")
+        
+        result = {'qasm': '\n'.join(lines)}
+        return self._fallback_response("compose_circuits", result, start)
+
+    def generate_inverse_circuit(self, qasm_code: str) -> MCPResponse:
+        """Generate the inverse of a circuit. Uses local fallback."""
+        start = time.perf_counter()
+        parsed = self._analyzer.parse_qasm(qasm_code)
+        
+        # Inverse gate mappings
+        inverse_map = {
+            'h': 'h', 'x': 'x', 'y': 'y', 'z': 'z',
+            's': 'sdg', 'sdg': 's', 't': 'tdg', 'tdg': 't',
+            'cx': 'cx', 'cz': 'cz', 'swap': 'swap'
+        }
+        
+        lines = [
+            'OPENQASM 2.0;',
+            'include "qelib1.inc";',
+            f'qreg q[{parsed["num_qubits"]}];',
+            f'creg c[{parsed["num_classical"]}];'
+        ]
+        
+        # Reverse and invert gates
+        for g in reversed(parsed['gates']):
+            gate = g['gate'].lower()
+            if gate == 'measure':
+                continue
+            inv_gate = inverse_map.get(gate, gate)
+            # Handle parametric gates
+            if '(' in g['raw']:
+                # Negate angle for rotation gates
+                raw = g['raw'].replace(gate, inv_gate)
+                if 'rz' in gate or 'rx' in gate or 'ry' in gate:
+                    # Simple negation (not perfect)
+                    pass
+                lines.append(f"{raw};")
+            else:
+                raw = g['raw'].replace(gate, inv_gate)
+                lines.append(f"{raw};")
+        
+        result = {'qasm': '\n'.join(lines)}
+        return self._fallback_response("generate_inverse_circuit", result, start)
+
+    def tensor_circuits(self, qasm1: str, qasm2: str) -> MCPResponse:
+        """Tensor product of two circuits. Uses local fallback."""
+        start = time.perf_counter()
+        
+        parsed1 = self._analyzer.parse_qasm(qasm1)
+        parsed2 = self._analyzer.parse_qasm(qasm2)
+        
+        total_qubits = parsed1['num_qubits'] + parsed2['num_qubits']
+        offset = parsed1['num_qubits']
+        
+        lines = [
+            'OPENQASM 2.0;',
+            'include "qelib1.inc";',
+            f'qreg q[{total_qubits}];',
+            f'creg c[{total_qubits}];'
+        ]
+        
+        # Add gates from first circuit
+        for g in parsed1['gates']:
+            lines.append(f"{g['raw']};")
+        
+        # Add gates from second circuit with offset
+        for g in parsed2['gates']:
+            raw = g['raw']
+            # Offset qubit indices
+            for i in range(parsed2['num_qubits'] - 1, -1, -1):
+                raw = raw.replace(f'q[{i}]', f'q[{i + offset}]')
+            lines.append(f"{raw};")
+        
+        result = {'qasm': '\n'.join(lines)}
+        return self._fallback_response("tensor_circuits", result, start)
+
+    def repeat_circuit(self, qasm_code: str, n: int) -> MCPResponse:
+        """Repeat a circuit n times. Uses local fallback."""
+        start = time.perf_counter()
+        parsed = self._analyzer.parse_qasm(qasm_code)
+        
+        lines = [
+            'OPENQASM 2.0;',
+            'include "qelib1.inc";',
+            f'qreg q[{parsed["num_qubits"]}];',
+            f'creg c[{parsed["num_classical"]}];'
+        ]
+        
+        # Repeat non-measure gates n times
+        for _ in range(n):
+            for g in parsed['gates']:
+                if g['gate'].lower() != 'measure':
+                    lines.append(f"{g['raw']};")
+        
+        # Add measurements at end
+        for g in parsed['gates']:
+            if g['gate'].lower() == 'measure':
+                lines.append(f"{g['raw']};")
+                break
+        
+        result = {'qasm': '\n'.join(lines)}
+        return self._fallback_response("repeat_circuit", result, start)
+
+    # ===== Utility Endpoints =====
+
+    def list_templates(self) -> MCPResponse:
+        """List available circuit templates."""
+        start = time.perf_counter()
+        templates = [
+            'bell_state', 'ghz_state', 'w_state', 'superposition',
+            'qft', 'grover', 'vqe', 'qaoa'
+        ]
+        return self._fallback_response("list_templates", {'templates': templates}, start)
+
+    def list_hardware_profiles(self) -> MCPResponse:
+        """List available hardware profiles."""
+        start = time.perf_counter()
+        profiles = ['ibm_brisbane', 'ibm_sherbrooke', 'rigetti_aspen', 'ionq_harmony']
+        return self._fallback_response("list_hardware_profiles", {'profiles': profiles}, start)
+
+
+# Singleton client instance
+_client: Optional[MCPClient] = None
+
+
+def get_client(base_url: Optional[str] = None) -> MCPClient:
+    """
+    Get or create the MCP client singleton.
+    
+    Args:
+        base_url: Optional URL override. If None, checks MCP_SERVER_URL env var,
+                 then defaults to http://127.0.0.1:7861
+    """
+    global _client
+    if _client is None:
+        if base_url is None:
+            import os
+            base_url = os.environ.get("MCP_SERVER_URL", "http://127.0.0.1:7861")
+        _client = MCPClient(base_url)
+    return _client

config.py

@@ -0,0 +1,305 @@
+"""
+QAgents-Workflows: Configuration
+Central configuration for the multi-agent quantum circuit optimization system.
+
+Path: QAgents-workflos/config.py
+Related: agents/llm_adapter.py (uses GEMINI_MODELS for fallback cascade)
+         run_evaluation.py (uses config for evaluation settings)
+         workflows/workflow_definitions.py (references rate limits)
+"""
+
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict
+import os
+
+# Paths
+PROJECT_ROOT = Path(__file__).parent
+QUANTUM_MCP_ROOT = PROJECT_ROOT.parent / "QuantumArchitect-MCP"
+
+# =============================================================================
+# GEMINI MODEL CASCADE (sorted by RPD - highest to lowest for optimal fallback)
+# =============================================================================
+# When a model hits rate limits (RPM/RPD), fallback to next model in list.
+# Free tier limits (as of 2025):
+#   - Gemma 3:             30 RPM, 15K TPM, 14,400 RPD (HIGHEST availability)
+#   - Flash-Lite:          15 RPM, 250K TPM, 1,000 RPD
+#   - Flash 2.5:           10 RPM, 250K TPM, 250 RPD
+#   - Flash 2.0:           15 RPM, 1M TPM, 200 RPD
+#   - Flash 2.0 Lite:      30 RPM, 1M TPM, 200 RPD
+#   - Pro 2.5:             2 RPM, 125K TPM, 50 RPD (LOWEST availability)
+#
+# EXPECTED REQUESTS PER EVALUATION (9 problems):
+#   - Naked mode:     0 LLM calls (direct MCP only)
+#   - Guided mode:    ~36 LLM calls (4 per problem)
+#   - Blackboard:     ~72-108 LLM calls (8-12 per problem)
+# =============================================================================
+
+GEMINI_MODELS: List[Dict] = [
+    # Highest RPD - most available (14,400/day = 10/min continuously)
+    {
+        "name": "gemma-3-27b-it",
+        "rpm": 30,
+        "tpm": 15_000,
+        "rpd": 14_400,
+        "priority": 1,
+        "notes": "Best for high-volume, may have lower quality than Flash"
+    },
+    # Good balance - default model (1,000/day)
+    {
+        "name": "gemini-2.5-flash-lite",
+        "rpm": 15,
+        "tpm": 250_000,
+        "rpd": 1_000,
+        "priority": 2,
+        "notes": "Good balance of quality and availability - DEFAULT"
+    },
+    # Higher quality - moderate availability (250/day)
+    {
+        "name": "gemini-2.5-flash",
+        "rpm": 10,
+        "tpm": 250_000,
+        "rpd": 250,
+        "priority": 3,
+        "notes": "Better quality, lower availability"
+    },
+    # High TPM for long contexts (200/day)
+    {
+        "name": "gemini-2.0-flash",
+        "rpm": 15,
+        "tpm": 1_000_000,
+        "rpd": 200,
+        "priority": 4,
+        "notes": "Good for long contexts, moderate availability"
+    },
+    # Fast variant (200/day)
+    {
+        "name": "gemini-2.0-flash-lite",
+        "rpm": 30,
+        "tpm": 1_000_000,
+        "rpd": 200,
+        "priority": 5,
+        "notes": "Fast responses, lower availability"
+    },
+    # Lowest RPD - highest quality, use sparingly (50/day)
+    {
+        "name": "gemini-2.5-pro",
+        "rpm": 2,
+        "tpm": 125_000,
+        "rpd": 50,
+        "priority": 6,
+        "notes": "Highest quality, use sparingly - LAST RESORT"
+    },
+]
+
+def get_model_by_priority(priority: int = 1) -> Optional[Dict]:
+    """Get model config by priority (1=highest RPD)."""
+    for model in GEMINI_MODELS:
+        if model["priority"] == priority:
+            return model
+    return None
+
+def get_next_model(current_name: str) -> Optional[Dict]:
+    """Get next model in fallback chain."""
+    for i, model in enumerate(GEMINI_MODELS):
+        if model["name"] == current_name:
+            if i + 1 < len(GEMINI_MODELS):
+                return GEMINI_MODELS[i + 1]
+    return None
+
+def get_model_config(model_name: str) -> Optional[Dict]:
+    """Get model config by name."""
+    for model in GEMINI_MODELS:
+        if model["name"] == model_name:
+            return model
+    return None
+
+
+@dataclass
+class MCPConfig:
+    """MCP Server configuration."""
+    host: str = "127.0.0.1"
+    port: int = 7861
+    base_url: str = field(init=False)
+
+    def __post_init__(self):
+        self.base_url = f"http://{self.host}:{self.port}"
+
+
+@dataclass
+class RateLimitConfig:
+    """Rate limiting based on Gemini API free tier limits."""
+    # Default to gemini-2.5-flash-lite limits
+    rpm_limit: int = 15  # Requests per minute
+    tpm_limit: int = 250_000  # Tokens per minute
+    rpd_limit: int = 1_000  # Requests per day
+
+    # Conservative buffer (80% of limit = 12 RPM effective)
+    rpm_buffer: float = 0.8
+
+    @property
+    def min_request_interval(self) -> float:
+        """Minimum seconds between requests: 60 / (15 * 0.8) = 5 seconds."""
+        return 60.0 / (self.rpm_limit * self.rpm_buffer)
+
+
+@dataclass
+class LLMConfig:
+    """LLM configuration for agents - model agnostic via Gemini and LiteLLM.
+    
+    Environment Variables (HuggingFace Space compatible):
+    - LLM_PROVIDER: Provider name (gemini, openai, anthropic, groq, ollama). Default: "gemini"
+    - LLM_MODEL: Model identifier. Default: "gemini-2.5-flash-lite"
+    - GOOGLE_API_KEY: Gemini API key (Gemini provider)
+    - GENAI_API_KEY: Alternative Gemini API key (fallback)
+    - OPENAI_API_KEY: OpenAI API key (OpenAI provider)
+    - ANTHROPIC_API_KEY: Anthropic API key (Anthropic provider)
+    - GROQ_API_KEY: Groq API key (Groq provider)
+    """
+    # Provider options: gemini, openai, anthropic, groq, ollama, etc.
+    # Reads from LLM_PROVIDER env var, falls back to "gemini"
+    provider: str = field(default_factory=lambda: os.getenv("LLM_PROVIDER", "gemini"))
+    # Model identifier - reads from LLM_MODEL env var, falls back to "gemini-2.5-flash-lite"
+    model: str = field(default_factory=lambda: os.getenv("LLM_MODEL", "gemini-2.5-flash-lite"))
+    # API key - tries GOOGLE_API_KEY first (Gemini), then GENAI_API_KEY as fallback
+    api_key: Optional[str] = field(default_factory=lambda: os.getenv("GOOGLE_API_KEY") or os.getenv("GENAI_API_KEY"))
+    temperature: float = 0.2
+    max_tokens: int = 2000
+
+    # Rate limiting
+    rate_limit: RateLimitConfig = field(default_factory=RateLimitConfig)
+    enable_rate_limiting: bool = True  # Set to False to disable
+    
+    # Multi-model fallback
+    enable_fallback: bool = True  # Enable automatic model switching on rate limit
+    fallback_on_error: bool = True  # Also fallback on API errors
+
+    @property
+    def model_string(self) -> str:
+        """Get full model string for API calls."""
+        if self.provider in ["gemini"]:
+            return self.model
+        else:
+            # LiteLLM format: provider/model
+            return f"{self.provider}/{self.model}"
+
+
+@dataclass
+class DatabaseConfig:
+    """Database/storage configuration."""
+    db_path: Path = field(default_factory=lambda: PROJECT_ROOT / "database" / "data")
+    log_path: Path = field(default_factory=lambda: PROJECT_ROOT / "database" / "logs")
+    memory_path: Path = field(default_factory=lambda: PROJECT_ROOT / "database" / "memory")
+
+    def __post_init__(self):
+        # Ensure directories exist
+        for path in [self.db_path, self.log_path, self.memory_path]:
+            path.mkdir(parents=True, exist_ok=True)
+
+
+@dataclass
+class CostTrackingConfig:
+    """Cost and usage tracking configuration."""
+    enabled: bool = True
+    track_requests: bool = True
+    track_tokens: bool = True
+    track_time: bool = True
+    
+    # Usage counters (reset daily in production)
+    total_requests: int = 0
+    total_tokens: int = 0
+    total_time_ms: float = 0.0
+    
+    # Per-model tracking
+    model_usage: Dict[str, Dict] = field(default_factory=dict)
+    
+    def record_request(self, model: str, tokens: int, time_ms: float):
+        """Record a request for cost tracking."""
+        if not self.enabled:
+            return
+        
+        self.total_requests += 1
+        self.total_tokens += tokens
+        self.total_time_ms += time_ms
+        
+        if model not in self.model_usage:
+            self.model_usage[model] = {"requests": 0, "tokens": 0, "time_ms": 0.0}
+        
+        self.model_usage[model]["requests"] += 1
+        self.model_usage[model]["tokens"] += tokens
+        self.model_usage[model]["time_ms"] += time_ms
+    
+    def get_summary(self) -> Dict:
+        """Get cost tracking summary."""
+        return {
+            "total_requests": self.total_requests,
+            "total_tokens": self.total_tokens,
+            "total_time_ms": self.total_time_ms,
+            "avg_time_per_request": self.total_time_ms / max(1, self.total_requests),
+            "model_breakdown": self.model_usage.copy()
+        }
+    
+    def reset(self):
+        """Reset all counters."""
+        self.total_requests = 0
+        self.total_tokens = 0
+        self.total_time_ms = 0.0
+        self.model_usage = {}
+
+
+@dataclass
+class EvaluationConfig:
+    """Evaluation settings."""
+    num_runs: int = 5  # Number of runs per problem for reliability
+    timeout_seconds: float = 120.0  # Max time per problem
+    save_results: bool = True
+    
+    # Cost tracking for evaluation
+    cost_tracking: CostTrackingConfig = field(default_factory=CostTrackingConfig)
+
+
+@dataclass
+class SystemConfig:
+    """Master configuration."""
+    mcp: MCPConfig = field(default_factory=MCPConfig)
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    database: DatabaseConfig = field(default_factory=DatabaseConfig)
+    evaluation: EvaluationConfig = field(default_factory=EvaluationConfig)
+
+    # System mode: "blackboard", "guided", or "naked"
+    active_mode: str = "guided"
+
+    # Debug settings
+    verbose: bool = True
+    log_level: str = "INFO"
+
+
+# Global config instance
+config = SystemConfig()
+
+
+def set_mode(mode: str):
+    """Switch between blackboard, guided, and naked modes."""
+    if mode not in ("blackboard", "guided", "naked"):
+        raise ValueError(f"Invalid mode: {mode}. Use 'blackboard', 'guided', or 'naked'")
+    config.active_mode = mode
+
+
+def get_mode() -> str:
+    """Get current system mode."""
+    return config.active_mode
+
+
+def set_api_key(api_key: str):
+    """Set the API key for LLM calls."""
+    config.llm.api_key = api_key
+
+
+def get_cost_summary() -> Dict:
+    """Get the current cost tracking summary."""
+    return config.evaluation.cost_tracking.get_summary()
+
+
+def reset_cost_tracking():
+    """Reset cost tracking counters."""
+    config.evaluation.cost_tracking.reset()

database/__init__.py

@@ -0,0 +1,36 @@
+# Path: QAgents-workflos/database/__init__.py
+# Purpose: Database module exports for storage, logging, memory, and circuit quality
+# Relations: Provides unified access to all database functionality
+
+"""Database module for storage, logging, memory, and circuit quality tracking."""
+
+from .storage import (
+    Database,
+    MemoryType,
+    MemoryEntry,
+    LogEntry,
+    ResultEntry,
+    get_database
+)
+
+from .circuit_quality_db import (
+    CircuitQualityDB,
+    CircuitEvaluation,
+    QualityMetrics,
+    get_quality_db
+)
+
+__all__ = [
+    # Original storage
+    "Database",
+    "MemoryType",
+    "MemoryEntry",
+    "LogEntry",
+    "ResultEntry",
+    "get_database",
+    # Quality tracking (NEW)
+    "CircuitQualityDB",
+    "CircuitEvaluation",
+    "QualityMetrics",
+    "get_quality_db"
+]

database/circuit_quality_db.py

@@ -0,0 +1,414 @@
+# Path: QAgents-workflos/database/circuit_quality_db.py
+# Relations: Uses database/storage.py pattern, connects to MCP via client/
+# Description: SQLite database for storing QASM circuits and quality metrics
+#              Enables circuit comparison across orchestration modes
+#              Tracks circuit_qasm text + all quality measurements
+
+"""
+Circuit Quality Database: Store and compare quantum circuits with quality metrics.
+Stores actual QASM code for later analysis and comparison between modes.
+"""
+
+import sqlite3
+import json
+from pathlib import Path
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+from dataclasses import dataclass, field, asdict
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class QualityMetrics:
+    """Quality metrics for a circuit."""
+    depth: int = 0
+    gate_count: int = 0
+    cx_count: int = 0
+    single_qubit_count: int = 0
+    hardware_fitness: float = 0.0
+    syntax_valid: bool = False
+    state_correctness: float = 0.0
+    complexity_score: float = 0.0
+    noise_estimate: float = 0.0
+    
+    def overall_score(self) -> float:
+        """Calculate overall quality score (higher is better, 0-100)."""
+        score = 0.0
+        # Syntax: 20 points
+        score += 20.0 if self.syntax_valid else 0.0
+        # Hardware fitness: 20 points
+        score += 20.0 * min(self.hardware_fitness, 1.0)
+        # State correctness: 30 points
+        score += 30.0 * self.state_correctness
+        # Efficiency (lower depth/gates better): 15 points
+        if self.gate_count > 0:
+            efficiency = max(0, 1 - (self.depth / max(self.gate_count, 1)) / 10)
+            score += 15.0 * efficiency
+        # Lower CX count bonus: 15 points
+        if self.gate_count > 0:
+            cx_ratio = self.cx_count / max(self.gate_count, 1)
+            score += 15.0 * (1 - min(cx_ratio, 1.0))
+        return round(score, 2)
+
+
+@dataclass
+class CircuitEvaluation:
+    """Complete evaluation record with QASM and quality."""
+    id: Optional[int] = None
+    run_id: str = ""
+    timestamp: str = ""
+    problem_id: str = ""
+    problem_goal: str = ""
+    mode: str = ""  # naked, guided, blackboard
+    qasm_code: str = ""  # FULL QASM text stored
+    success: bool = False
+    execution_time_ms: float = 0.0
+    llm_requests: int = 0
+    tokens_used: int = 0
+    quality_metrics: QualityMetrics = field(default_factory=QualityMetrics)
+    errors: List[str] = field(default_factory=list)
+
+
+class CircuitQualityDB:
+    """
+    SQLite database for storing circuits and quality metrics.
+    Primary purpose: Enable quality comparison across modes.
+    """
+
+    def __init__(self, db_path: Optional[Path] = None):
+        if db_path is None:
+            db_path = Path(__file__).parent / "data"
+        self.db_path = Path(db_path)
+        self.db_path.mkdir(parents=True, exist_ok=True)
+        self.db_file = self.db_path / "circuit_quality.db"
+        self._init_db()
+    
+    def _init_db(self):
+        """Initialize database tables."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.executescript("""
+                -- Main table: stores full QASM and evaluation metadata
+                CREATE TABLE IF NOT EXISTS circuit_evaluations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    run_id TEXT NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    problem_id TEXT NOT NULL,
+                    problem_goal TEXT,
+                    mode TEXT NOT NULL,
+                    qasm_code TEXT,
+                    success INTEGER NOT NULL,
+                    execution_time_ms REAL,
+                    llm_requests INTEGER DEFAULT 0,
+                    tokens_used INTEGER DEFAULT 0,
+                    errors TEXT
+                );
+                
+                -- Quality metrics table: detailed quality measurements
+                CREATE TABLE IF NOT EXISTS quality_metrics (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    eval_id INTEGER NOT NULL,
+                    depth INTEGER DEFAULT 0,
+                    gate_count INTEGER DEFAULT 0,
+                    cx_count INTEGER DEFAULT 0,
+                    single_qubit_count INTEGER DEFAULT 0,
+                    hardware_fitness REAL DEFAULT 0.0,
+                    syntax_valid INTEGER DEFAULT 0,
+                    state_correctness REAL DEFAULT 0.0,
+                    complexity_score REAL DEFAULT 0.0,
+                    noise_estimate REAL DEFAULT 0.0,
+                    overall_score REAL DEFAULT 0.0,
+                    FOREIGN KEY (eval_id) REFERENCES circuit_evaluations(id)
+                );
+                
+                -- Comparison runs: group multiple evaluations
+                CREATE TABLE IF NOT EXISTS comparison_runs (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    run_id TEXT UNIQUE NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    description TEXT,
+                    num_problems INTEGER DEFAULT 0,
+                    modes_tested TEXT,
+                    summary TEXT
+                );
+                
+                -- Create indexes for fast queries
+                CREATE INDEX IF NOT EXISTS idx_eval_run_id ON circuit_evaluations(run_id);
+                CREATE INDEX IF NOT EXISTS idx_eval_problem ON circuit_evaluations(problem_id);
+                CREATE INDEX IF NOT EXISTS idx_eval_mode ON circuit_evaluations(mode);
+            """)
+            conn.commit()
+    
+    def save_evaluation(self, eval: CircuitEvaluation) -> int:
+        """Save a circuit evaluation with quality metrics. Returns eval ID."""
+        with sqlite3.connect(self.db_file) as conn:
+            cursor = conn.cursor()
+            
+            # Insert main evaluation record
+            cursor.execute("""
+                INSERT INTO circuit_evaluations 
+                (run_id, timestamp, problem_id, problem_goal, mode, qasm_code,
+                 success, execution_time_ms, llm_requests, tokens_used, errors)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                eval.run_id,
+                eval.timestamp or datetime.now().isoformat(),
+                eval.problem_id,
+                eval.problem_goal,
+                eval.mode,
+                eval.qasm_code,  # FULL QASM stored here
+                1 if eval.success else 0,
+                eval.execution_time_ms,
+                eval.llm_requests,
+                eval.tokens_used,
+                json.dumps(eval.errors)
+            ))
+            eval_id = cursor.lastrowid
+            
+            # Insert quality metrics
+            metrics = eval.quality_metrics
+            cursor.execute("""
+                INSERT INTO quality_metrics
+                (eval_id, depth, gate_count, cx_count, single_qubit_count,
+                 hardware_fitness, syntax_valid, state_correctness,
+                 complexity_score, noise_estimate, overall_score)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                eval_id,
+                metrics.depth,
+                metrics.gate_count,
+                metrics.cx_count,
+                metrics.single_qubit_count,
+                metrics.hardware_fitness,
+                1 if metrics.syntax_valid else 0,
+                metrics.state_correctness,
+                metrics.complexity_score,
+                metrics.noise_estimate,
+                metrics.overall_score()
+            ))
+            
+            conn.commit()
+            logger.info(f"Saved evaluation {eval_id} for {eval.problem_id}/{eval.mode}")
+            return eval_id
+    
+    def save_comparison_run(self, run_id: str, description: str, 
+                           num_problems: int, modes: List[str], summary: Dict) -> None:
+        """Save a comparison run record."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.execute("""
+                INSERT OR REPLACE INTO comparison_runs
+                (run_id, timestamp, description, num_problems, modes_tested, summary)
+                VALUES (?, ?, ?, ?, ?, ?)
+            """, (
+                run_id,
+                datetime.now().isoformat(),
+                description,
+                num_problems,
+                json.dumps(modes),
+                json.dumps(summary)
+            ))
+            conn.commit()
+    
+    def get_evaluations(self, problem_id: Optional[str] = None, 
+                       mode: Optional[str] = None,
+                       run_id: Optional[str] = None,
+                       limit: int = 100) -> List[CircuitEvaluation]:
+        """Get evaluations with optional filters."""
+        query = """
+            SELECT e.*, q.depth, q.gate_count, q.cx_count, q.single_qubit_count,
+                   q.hardware_fitness, q.syntax_valid, q.state_correctness,
+                   q.complexity_score, q.noise_estimate, q.overall_score
+            FROM circuit_evaluations e
+            LEFT JOIN quality_metrics q ON e.id = q.eval_id
+            WHERE 1=1
+        """
+        params = []
+        
+        if problem_id:
+            query += " AND e.problem_id = ?"
+            params.append(problem_id)
+        if mode:
+            query += " AND e.mode = ?"
+            params.append(mode)
+        if run_id:
+            query += " AND e.run_id = ?"
+            params.append(run_id)
+        
+        query += " ORDER BY e.timestamp DESC LIMIT ?"
+        params.append(limit)
+        
+        evaluations = []
+        with sqlite3.connect(self.db_file) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.execute(query, params)
+            
+            for row in cursor:
+                metrics = QualityMetrics(
+                    depth=row['depth'] or 0,
+                    gate_count=row['gate_count'] or 0,
+                    cx_count=row['cx_count'] or 0,
+                    single_qubit_count=row['single_qubit_count'] or 0,
+                    hardware_fitness=row['hardware_fitness'] or 0.0,
+                    syntax_valid=bool(row['syntax_valid']),
+                    state_correctness=row['state_correctness'] or 0.0,
+                    complexity_score=row['complexity_score'] or 0.0,
+                    noise_estimate=row['noise_estimate'] or 0.0
+                )
+                
+                eval = CircuitEvaluation(
+                    id=row['id'],
+                    run_id=row['run_id'],
+                    timestamp=row['timestamp'],
+                    problem_id=row['problem_id'],
+                    problem_goal=row['problem_goal'] or "",
+                    mode=row['mode'],
+                    qasm_code=row['qasm_code'] or "",
+                    success=bool(row['success']),
+                    execution_time_ms=row['execution_time_ms'] or 0.0,
+                    llm_requests=row['llm_requests'] or 0,
+                    tokens_used=row['tokens_used'] or 0,
+                    quality_metrics=metrics,
+                    errors=json.loads(row['errors']) if row['errors'] else []
+                )
+                evaluations.append(eval)
+        
+        return evaluations
+    
+    def get_circuit_by_id(self, eval_id: int) -> Optional[CircuitEvaluation]:
+        """Get a single evaluation by ID."""
+        evals = self.get_evaluations(limit=1)
+        for e in self.get_evaluations(limit=1000):
+            if e.id == eval_id:
+                return e
+        return None
+    
+    def compare_modes_for_problem(self, problem_id: str, run_id: Optional[str] = None) -> Dict:
+        """Compare all modes for a specific problem."""
+        modes = ['naked', 'guided', 'blackboard']
+        comparison = {
+            "problem_id": problem_id,
+            "modes": {}
+        }
+        
+        for mode in modes:
+            evals = self.get_evaluations(problem_id=problem_id, mode=mode, run_id=run_id)
+            if evals:
+                latest = evals[0]
+                comparison["modes"][mode] = {
+                    "success": latest.success,
+                    "qasm_code": latest.qasm_code,
+                    "depth": latest.quality_metrics.depth,
+                    "gate_count": latest.quality_metrics.gate_count,
+                    "cx_count": latest.quality_metrics.cx_count,
+                    "hardware_fitness": latest.quality_metrics.hardware_fitness,
+                    "overall_score": latest.quality_metrics.overall_score(),
+                    "execution_time_ms": latest.execution_time_ms,
+                    "llm_requests": latest.llm_requests
+                }
+        
+        return comparison
+    
+    def get_quality_summary(self, run_id: Optional[str] = None) -> Dict:
+        """Get quality summary across all modes."""
+        query = """
+            SELECT e.mode, 
+                   COUNT(*) as count,
+                   SUM(e.success) as successes,
+                   AVG(q.overall_score) as avg_score,
+                   AVG(q.depth) as avg_depth,
+                   AVG(q.gate_count) as avg_gates,
+                   AVG(q.cx_count) as avg_cx,
+                   AVG(q.hardware_fitness) as avg_fitness,
+                   AVG(e.execution_time_ms) as avg_time,
+                   SUM(e.llm_requests) as total_llm,
+                   SUM(e.tokens_used) as total_tokens
+            FROM circuit_evaluations e
+            LEFT JOIN quality_metrics q ON e.id = q.eval_id
+        """
+        params = []
+        if run_id:
+            query += " WHERE e.run_id = ?"
+            params.append(run_id)
+        query += " GROUP BY e.mode"
+        
+        summary = {"modes": {}}
+        with sqlite3.connect(self.db_file) as conn:
+            conn.row_factory = sqlite3.Row
+            for row in conn.execute(query, params):
+                mode = row['mode']
+                count = row['count']
+                summary["modes"][mode] = {
+                    "count": count,
+                    "success_rate": row['successes'] / count if count > 0 else 0,
+                    "avg_quality_score": round(row['avg_score'] or 0, 2),
+                    "avg_depth": round(row['avg_depth'] or 0, 1),
+                    "avg_gates": round(row['avg_gates'] or 0, 1),
+                    "avg_cx_count": round(row['avg_cx'] or 0, 1),
+                    "avg_hardware_fitness": round(row['avg_fitness'] or 0, 3),
+                    "avg_time_ms": round(row['avg_time'] or 0, 1),
+                    "total_llm_requests": row['total_llm'] or 0,
+                    "total_tokens": row['total_tokens'] or 0
+                }
+        
+        return summary
+    
+    def export_circuits_markdown(self, run_id: Optional[str] = None) -> str:
+        """Export all circuits as markdown for comparison."""
+        evals = self.get_evaluations(run_id=run_id, limit=1000)
+        
+        # Group by problem
+        by_problem: Dict[str, Dict[str, CircuitEvaluation]] = {}
+        for e in evals:
+            if e.problem_id not in by_problem:
+                by_problem[e.problem_id] = {}
+            by_problem[e.problem_id][e.mode] = e
+        
+        md = ["# Circuit Quality Comparison Report\n"]
+        md.append(f"Generated: {datetime.now().isoformat()}\n")
+        if run_id:
+            md.append(f"Run ID: {run_id}\n")
+        md.append("\n---\n")
+        
+        for problem_id, modes in sorted(by_problem.items()):
+            md.append(f"\n## Problem: {problem_id}\n")
+            
+            for mode in ['naked', 'guided', 'blackboard']:
+                if mode not in modes:
+                    md.append(f"\n### {mode.upper()}: NOT RUN\n")
+                    continue
+                
+                e = modes[mode]
+                q = e.quality_metrics
+                
+                md.append(f"\n### {mode.upper()}\n")
+                md.append(f"- **Success**: {'✅' if e.success else '❌'}\n")
+                md.append(f"- **Quality Score**: {q.overall_score()}/100\n")
+                md.append(f"- **Depth**: {q.depth}\n")
+                md.append(f"- **Gate Count**: {q.gate_count}\n")
+                md.append(f"- **CX Count**: {q.cx_count}\n")
+                md.append(f"- **Hardware Fitness**: {q.hardware_fitness:.3f}\n")
+                md.append(f"- **Time**: {e.execution_time_ms:.0f}ms\n")
+                md.append(f"- **LLM Requests**: {e.llm_requests}\n")
+                
+                if e.qasm_code:
+                    md.append("\n```qasm\n")
+                    md.append(e.qasm_code)
+                    if not e.qasm_code.endswith('\n'):
+                        md.append('\n')
+                    md.append("```\n")
+                else:
+                    md.append("\n*No circuit generated*\n")
+        
+        return "".join(md)
+
+
+# Singleton instance
+_quality_db: Optional[CircuitQualityDB] = None
+
+def get_quality_db() -> CircuitQualityDB:
+    """Get the global quality database instance."""
+    global _quality_db
+    if _quality_db is None:
+        _quality_db = CircuitQualityDB()
+    return _quality_db

database/storage.py

@@ -0,0 +1,278 @@
+"""
+Database Module: Storage for logs, results, memory, and context.
+Provides both shared and per-agent storage with short/long-term memory.
+"""
+
+import json
+import sqlite3
+from pathlib import Path
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+import logging
+
+logger = logging.getLogger(__name__)
+
+class MemoryType(Enum):
+    """Types of memory storage."""
+    SHORT_TERM = "short_term"  # Session-based, cleared on restart
+    LONG_TERM = "long_term"    # Persistent across sessions
+    SHARED = "shared"          # Shared between agents (blackboard)
+    
+@dataclass
+class MemoryEntry:
+    """A single memory entry."""
+    key: str
+    value: Any
+    agent_id: Optional[str]
+    memory_type: MemoryType
+    timestamp: datetime = field(default_factory=datetime.now)
+    metadata: Dict = field(default_factory=dict)
+    
+@dataclass
+class LogEntry:
+    """A log entry for audit trail."""
+    level: str
+    message: str
+    agent_id: Optional[str]
+    workflow_id: Optional[str]
+    timestamp: datetime = field(default_factory=datetime.now)
+    data: Dict = field(default_factory=dict)
+
+@dataclass
+class ResultEntry:
+    """A result from an evaluation run."""
+    run_id: str
+    system_mode: str  # blackboard, guided, naked
+    problem_id: str
+    success: bool
+    execution_time_ms: float
+    circuit_qasm: Optional[str]
+    metrics: Dict = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class Database:
+    """
+    SQLite-based storage for all system data.
+    Manages logs, results, and agent memory.
+    """
+    
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self.db_path.mkdir(parents=True, exist_ok=True)
+        self.db_file = self.db_path / "qagents.db"
+        self._init_db()
+        
+    def _init_db(self):
+        """Initialize database tables."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS memory (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    agent_id TEXT,
+                    memory_type TEXT NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    metadata TEXT
+                );
+                
+                CREATE TABLE IF NOT EXISTS logs (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    level TEXT NOT NULL,
+                    message TEXT NOT NULL,
+                    agent_id TEXT,
+                    workflow_id TEXT,
+                    timestamp TEXT NOT NULL,
+                    data TEXT
+                );
+                
+                CREATE TABLE IF NOT EXISTS results (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    run_id TEXT NOT NULL,
+                    system_mode TEXT NOT NULL,
+                    problem_id TEXT NOT NULL,
+                    success INTEGER NOT NULL,
+                    execution_time_ms REAL NOT NULL,
+                    circuit_qasm TEXT,
+                    metrics TEXT,
+                    timestamp TEXT NOT NULL
+                );
+                
+                CREATE INDEX IF NOT EXISTS idx_memory_key ON memory(key);
+                CREATE INDEX IF NOT EXISTS idx_memory_agent ON memory(agent_id);
+                CREATE INDEX IF NOT EXISTS idx_results_mode ON results(system_mode);
+                CREATE INDEX IF NOT EXISTS idx_results_problem ON results(problem_id);
+            """)
+            
+    # ===== Memory Operations =====
+    
+    def store_memory(self, entry: MemoryEntry):
+        """Store a memory entry."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.execute(
+                """INSERT INTO memory (key, value, agent_id, memory_type, timestamp, metadata)
+                   VALUES (?, ?, ?, ?, ?, ?)""",
+                (entry.key, json.dumps(entry.value), entry.agent_id,
+                 entry.memory_type.value, entry.timestamp.isoformat(),
+                 json.dumps(entry.metadata))
+            )
+            
+    def get_memory(self, key: str, agent_id: Optional[str] = None,
+                   memory_type: Optional[MemoryType] = None) -> Optional[Any]:
+        """Retrieve a memory value."""
+        with sqlite3.connect(self.db_file) as conn:
+            query = "SELECT value FROM memory WHERE key = ?"
+            params = [key]
+            
+            if agent_id:
+                query += " AND agent_id = ?"
+                params.append(agent_id)
+            if memory_type:
+                query += " AND memory_type = ?"
+                params.append(memory_type.value)
+                
+            query += " ORDER BY timestamp DESC LIMIT 1"
+            
+            result = conn.execute(query, params).fetchone()
+            return json.loads(result[0]) if result else None
+            
+    def get_shared_memory(self, key: str) -> Optional[Any]:
+        """Get from shared blackboard memory."""
+        return self.get_memory(key, memory_type=MemoryType.SHARED)
+        
+    def set_shared_memory(self, key: str, value: Any, agent_id: Optional[str] = None):
+        """Set shared blackboard memory."""
+        entry = MemoryEntry(
+            key=key,
+            value=value,
+            agent_id=agent_id,
+            memory_type=MemoryType.SHARED
+        )
+        self.store_memory(entry)
+        
+    def clear_short_term_memory(self, agent_id: Optional[str] = None):
+        """Clear short-term memory (session reset)."""
+        with sqlite3.connect(self.db_file) as conn:
+            if agent_id:
+                conn.execute(
+                    "DELETE FROM memory WHERE memory_type = ? AND agent_id = ?",
+                    (MemoryType.SHORT_TERM.value, agent_id)
+                )
+            else:
+                conn.execute(
+                    "DELETE FROM memory WHERE memory_type = ?",
+                    (MemoryType.SHORT_TERM.value,)
+                )
+                
+    # ===== Logging Operations =====
+    
+    def log(self, entry: LogEntry):
+        """Store a log entry."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.execute(
+                """INSERT INTO logs (level, message, agent_id, workflow_id, timestamp, data)
+                   VALUES (?, ?, ?, ?, ?, ?)""",
+                (entry.level, entry.message, entry.agent_id, entry.workflow_id,
+                 entry.timestamp.isoformat(), json.dumps(entry.data))
+            )
+            
+    def get_logs(self, agent_id: Optional[str] = None, 
+                 workflow_id: Optional[str] = None,
+                 limit: int = 100) -> List[Dict]:
+        """Retrieve log entries."""
+        with sqlite3.connect(self.db_file) as conn:
+            query = "SELECT * FROM logs WHERE 1=1"
+            params = []
+            
+            if agent_id:
+                query += " AND agent_id = ?"
+                params.append(agent_id)
+            if workflow_id:
+                query += " AND workflow_id = ?"
+                params.append(workflow_id)
+                
+            query += f" ORDER BY timestamp DESC LIMIT {limit}"
+            
+            rows = conn.execute(query, params).fetchall()
+            return [
+                {"level": r[1], "message": r[2], "agent_id": r[3],
+                 "workflow_id": r[4], "timestamp": r[5], "data": json.loads(r[6] or "{}")}
+                for r in rows
+            ]
+            
+    # ===== Results Operations =====
+    
+    def store_result(self, entry: ResultEntry):
+        """Store an evaluation result."""
+        with sqlite3.connect(self.db_file) as conn:
+            conn.execute(
+                """INSERT INTO results (run_id, system_mode, problem_id, success, 
+                   execution_time_ms, circuit_qasm, metrics, timestamp)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                (entry.run_id, entry.system_mode, entry.problem_id,
+                 1 if entry.success else 0, entry.execution_time_ms,
+                 entry.circuit_qasm, json.dumps(entry.metrics),
+                 entry.timestamp.isoformat())
+            )
+            
+    def get_results(self, system_mode: Optional[str] = None,
+                    problem_id: Optional[str] = None) -> List[ResultEntry]:
+        """Retrieve results for analysis."""
+        with sqlite3.connect(self.db_file) as conn:
+            query = "SELECT * FROM results WHERE 1=1"
+            params = []
+            
+            if system_mode:
+                query += " AND system_mode = ?"
+                params.append(system_mode)
+            if problem_id:
+                query += " AND problem_id = ?"
+                params.append(problem_id)
+                
+            query += " ORDER BY timestamp DESC"
+            
+            rows = conn.execute(query, params).fetchall()
+            return [
+                ResultEntry(
+                    run_id=r[1], system_mode=r[2], problem_id=r[3],
+                    success=bool(r[4]), execution_time_ms=r[5],
+                    circuit_qasm=r[6], metrics=json.loads(r[7] or "{}"),
+                    timestamp=datetime.fromisoformat(r[8])
+                )
+                for r in rows
+            ]
+            
+    def get_summary_stats(self) -> Dict:
+        """Get summary statistics across all runs."""
+        with sqlite3.connect(self.db_file) as conn:
+            stats = {}
+            for mode in ["blackboard", "guided", "naked"]:
+                rows = conn.execute(
+                    """SELECT COUNT(*), AVG(execution_time_ms), 
+                       SUM(success) * 100.0 / COUNT(*)
+                       FROM results WHERE system_mode = ?""",
+                    (mode,)
+                ).fetchone()
+                
+                stats[mode] = {
+                    "total_runs": rows[0] or 0,
+                    "avg_time_ms": rows[1] or 0,
+                    "success_rate": rows[2] or 0
+                }
+            return stats
+
+
+# Singleton instance
+_db: Optional[Database] = None
+
+def get_database(db_path: Optional[Path] = None) -> Database:
+    """Get or create the database singleton."""
+    global _db
+    if _db is None:
+        from config import config
+        path = db_path or config.database.db_path
+        _db = Database(path)
+    return _db

orchestrators/__init__.py

@@ -0,0 +1,30 @@
+"""Orchestrators module: Workflow orchestration for different modes."""
+
+from .orchestrator import (
+    OrchestratorResult,
+    BaseOrchestrator,
+    BlackboardOrchestrator,
+    GuidedOrchestrator,
+    NakedOrchestrator,
+    create_orchestrator
+)
+
+from .quasar_orchestrator import (
+    QuasarOrchestrator,
+    HybridOrchestrator,
+    QuasarResult,
+    ValidationTier
+)
+
+__all__ = [
+    "OrchestratorResult",
+    "BaseOrchestrator",
+    "BlackboardOrchestrator",
+    "GuidedOrchestrator",
+    "NakedOrchestrator",
+    "QuasarOrchestrator",
+    "HybridOrchestrator",
+    "QuasarResult",
+    "ValidationTier",
+    "create_orchestrator"
+]

orchestrators/orchestrator.py

@@ -0,0 +1,541 @@
+# Path: QAgents-workflos/orchestrators/orchestrator.py
+# Relations: Uses agents, workflows, database modules
+# Description: Orchestrators for Blackboard, Guided, and Naked execution modes
+"""
+Orchestrators Module: Workflow orchestration and execution.
+Contains both Blackboard (free) and Guided (strict) orchestrators.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+import logging
+import time
+
+from agents import (
+    BaseAgent, AgentContext, AgentResult,
+    AgentState, create_all_agents
+)
+from workflows import (
+    WorkflowDefinition, WorkflowExecution,
+    WorkflowStatus, get_workflow
+)
+from database import get_database, LogEntry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class OrchestratorResult:
+    """Result from orchestrator execution."""
+    success: bool
+    final_output: Any
+    execution_time_ms: float
+    steps_completed: int
+    total_steps: int
+    agent_results: Dict[str, AgentResult] = field(default_factory=dict)
+    errors: List[str] = field(default_factory=list)
+
+
+class BaseOrchestrator(ABC):
+    """Abstract base class for orchestrators."""
+
+    def __init__(self, name: str):
+        self.name = name
+        self.agents: Dict[str, BaseAgent] = {}
+        self.db = get_database()
+
+    def register_agent(self, agent: BaseAgent):
+        """Register an agent with the orchestrator."""
+        self.agents[agent.agent_id] = agent
+
+    def log(self, level: str, message: str, workflow_id: str = None, data: Dict = None):
+        """Log orchestrator activity."""
+        entry = LogEntry(
+            level=level,
+            message=message,
+            agent_id=self.name,
+            workflow_id=workflow_id,
+            data=data or {}
+        )
+        self.db.log(entry)
+
+    @abstractmethod
+    def run(self, goal: str, initial_context: Dict = None) -> OrchestratorResult:
+        """Run the orchestrator to achieve the goal."""
+        pass
+
+
+class BlackboardOrchestrator(BaseOrchestrator):
+    """
+    Blackboard (Free) Orchestrator.
+
+    Uses a shared blackboard for agent communication.
+    Agents opportunistically activate when they can contribute.
+    Emergent workflow based on data availability.
+    """
+
+    def __init__(self):
+        super().__init__("blackboard")
+        self.blackboard: Dict[str, Any] = {}
+        self.max_iterations = 20
+
+    def _reset_blackboard(self, goal: str, initial_context: Dict = None):
+        """Initialize the blackboard with goal and context."""
+        # Ensure goal is a string
+        if isinstance(goal, list):
+            goal = goal[0] if goal else ""
+        goal = str(goal) if goal else ""
+        
+        self.blackboard = {
+            "goal": goal,
+            "current_circuit": None,
+            "validation_passed": False,
+            "scores": None,
+            "completed": False,
+            **(initial_context or {})
+        }
+
+    def _build_context(self) -> AgentContext:
+        """Build agent context from blackboard."""
+        return AgentContext(
+            goal=self.blackboard.get("goal", ""),
+            current_circuit=self.blackboard.get("current_circuit"),
+            history=self.blackboard.get("history", []),
+            constraints=self.blackboard.get("constraints", {}),
+            shared_data=self.blackboard
+        )
+
+    def _find_active_agent(self, context: AgentContext) -> Optional[BaseAgent]:
+        """Find an agent that can handle the current state."""
+        # Priority order for agent selection - simplified for reliability
+        # First: generate circuit, then validate
+        priority_order = ["builder", "architect", "validator"]
+
+        for agent_id in priority_order:
+            agent = self.agents.get(agent_id)
+            if agent and agent.can_handle(context):
+                if agent.state == AgentState.IDLE:
+                    return agent
+
+        return None
+
+    def _update_blackboard(self, agent_id: str, result: AgentResult):
+        """Update blackboard with agent results."""
+        if not result.success:
+            return
+
+        data = result.data
+        if isinstance(data, dict):
+            # Extract QASM if present
+            if "qasm" in data:
+                qasm = data["qasm"]
+                # Handle list responses
+                if isinstance(qasm, list):
+                    qasm = qasm[0] if qasm else None
+                self.blackboard["current_circuit"] = qasm
+
+            # Update validation status
+            if "valid" in data:
+                self.blackboard["validation_passed"] = data["valid"]
+
+            # Update scores
+            if "score" in data:
+                self.blackboard["scores"] = data["score"]
+
+        # Track history
+        if "history" not in self.blackboard:
+            self.blackboard["history"] = []
+        self.blackboard["history"].append({
+            "agent": agent_id,
+            "action": result.actions_taken,
+            "success": result.success,
+            "timestamp": datetime.now().isoformat()
+        })
+
+    def _check_completion(self) -> bool:
+        """Check if the goal has been achieved."""
+        # Simple completion: we have a validated circuit
+        has_circuit = self.blackboard.get("current_circuit") is not None
+        is_validated = self.blackboard.get("validation_passed", False)
+        return has_circuit and is_validated
+
+    def run(self, goal: str, initial_context: Dict = None) -> OrchestratorResult:
+        """Run blackboard orchestration."""
+        start_time = time.perf_counter()
+
+        self.log("INFO", f"Starting blackboard orchestration for: {goal}")
+        self._reset_blackboard(goal, initial_context)
+
+        # Ensure we have agents
+        if not self.agents:
+            self.agents = create_all_agents()
+
+        agent_results = {}
+        steps_completed = 0
+        errors = []
+
+        for iteration in range(self.max_iterations):
+            context = self._build_context()
+
+            # Find an agent that can work
+            agent = self._find_active_agent(context)
+
+            if agent is None:
+                self.log("INFO", "No active agent found, checking completion")
+                if self._check_completion():
+                    break
+                # No agent and not complete - might be stuck
+                if iteration > 5:  # Give it a few tries
+                    errors.append("No agent could make progress")
+                    break
+                continue
+
+            self.log("INFO", f"Activating agent: {agent.agent_id}")
+
+            # Agent decides and executes - with null safety
+            try:
+                action = agent.decide(context)
+                if action is None:
+                    self.log("WARN", f"Agent {agent.agent_id} returned no action, continuing")
+                    agent.reset()
+                    continue
+
+                result = agent.execute(action, context)
+                if result is None:
+                    self.log("WARN", f"Agent {agent.agent_id} returned no result, continuing")
+                    agent.reset()
+                    continue
+                    
+                agent_results[agent.agent_id] = result
+                steps_completed += 1
+
+                # Update blackboard
+                self._update_blackboard(agent.agent_id, result)
+                
+            except Exception as e:
+                self.log("ERROR", f"Agent {agent.agent_id} failed: {e}")
+                errors.append(f"Agent {agent.agent_id} error: {str(e)}")
+                agent.reset()
+                continue
+
+            # Reset agent for next potential activation
+            agent.reset()
+
+            # Check completion
+            if self._check_completion():
+                self.log("INFO", "Goal achieved!")
+                break
+
+        elapsed = (time.perf_counter() - start_time) * 1000
+
+        return OrchestratorResult(
+            success=self._check_completion(),
+            final_output=self.blackboard.get("current_circuit"),
+            execution_time_ms=elapsed,
+            steps_completed=steps_completed,
+            total_steps=self.max_iterations,
+            agent_results=agent_results,
+            errors=errors
+        )
+
+
+class GuidedOrchestrator(BaseOrchestrator):
+    """
+    Guided (Strict) Orchestrator.
+
+    Follows a predefined workflow with explicit steps.
+    Central control over agent execution order.
+    Predictable, auditable execution path.
+    """
+
+    def __init__(self, workflow_name: str = "build"):
+        super().__init__("guided")
+        self.workflow = get_workflow(workflow_name)
+        if self.workflow is None:
+            raise ValueError(f"Unknown workflow: {workflow_name}")
+        self.execution: Optional[WorkflowExecution] = None
+
+    def set_workflow(self, workflow_name: str):
+        """Change the workflow."""
+        self.workflow = get_workflow(workflow_name)
+        if self.workflow is None:
+            raise ValueError(f"Unknown workflow: {workflow_name}")
+
+    def run(self, goal: str, initial_context: Dict = None) -> OrchestratorResult:
+        """Run guided workflow orchestration."""
+        start_time = time.perf_counter()
+
+        # Ensure goal is a string
+        if isinstance(goal, list):
+            goal = goal[0] if goal else ""
+        goal = str(goal) if goal else ""
+
+        self.log("INFO", f"Starting guided workflow '{self.workflow.name}' for: {goal}")
+
+        # Initialize execution state
+        self.execution = WorkflowExecution(
+            workflow=self.workflow,
+            context={"goal": goal, **(initial_context or {})}
+        )
+        self.execution.status = WorkflowStatus.IN_PROGRESS
+
+        # Ensure we have agents
+        if not self.agents:
+            self.agents = create_all_agents()
+
+        agent_results = {}
+
+        # Execute each step in order
+        while self.execution.current_step is not None:
+            step = self.execution.current_step
+            self.log("INFO", f"Executing step: {step.name} ({step.agent_type})")
+
+            # Get the agent for this step
+            agent = self.agents.get(step.agent_type)
+            if agent is None:
+                if step.required:
+                    self.execution.fail(f"Missing agent: {step.agent_type}")
+                    break
+                else:
+                    self.log("WARN", f"Skipping optional step: {step.name}")
+                    self.execution.advance()
+                    continue
+
+            # Build context for agent
+            context = AgentContext(
+                goal=self.execution.context.get("goal", ""),
+                current_circuit=self.execution.context.get("circuit_qasm"),
+                history=[],
+                constraints={},
+                shared_data=self.execution.context
+            )
+
+            # Agent decides and executes
+            action = agent.decide(context)
+            if action is None:
+                # Agent has nothing to do - might be okay for some steps
+                self.log("WARN", f"Agent {step.agent_type} returned no action")
+                self.execution.advance()
+                continue
+
+            result = agent.execute(action, context)
+            agent_results[step.name] = result
+
+            # Store outputs in execution context
+            if result.success and result.data:
+                for output_key in step.outputs:
+                    if isinstance(result.data, dict):
+                        if output_key in result.data:
+                            self.execution.context[output_key] = result.data[output_key]
+                        elif "qasm" in result.data:
+                            qasm = result.data["qasm"]
+                            # Handle list responses
+                            if isinstance(qasm, list):
+                                qasm = qasm[0] if qasm else None
+                            self.execution.context["circuit_qasm"] = qasm
+
+            # Handle failure
+            if not result.success and step.required:
+                self.execution.fail(f"Step {step.name} failed: {result.message}")
+                break
+
+            # Reset agent and advance
+            agent.reset()
+            self.execution.advance()
+
+        elapsed = (time.perf_counter() - start_time) * 1000
+
+        return OrchestratorResult(
+            success=self.execution.status == WorkflowStatus.COMPLETED,
+            final_output=self.execution.context.get(self.workflow.final_output),
+            execution_time_ms=elapsed,
+            steps_completed=self.execution.current_step_index,
+            total_steps=len(self.workflow.steps),
+            agent_results=agent_results,
+            errors=self.execution.errors
+        )
+
+
+class NakedOrchestrator(BaseOrchestrator):
+    """
+    Naked (Baseline) Orchestrator.
+
+    Direct LLM-to-QASM generation with single call.
+    No multi-agent coordination, no structured workflow.
+    Uses ONE LLM call per problem for baseline comparison.
+    
+    Purpose: Measure raw LLM capability at quantum circuit generation
+    without agentic overhead.
+    """
+
+    def __init__(self):
+        super().__init__("naked")
+        self._llm = None
+
+    def _get_llm(self):
+        """Lazy load LLM adapter."""
+        if self._llm is None:
+            from agents.llm_adapter import get_llm_adapter
+            from config import config
+            self._llm = get_llm_adapter(
+                provider="gemini",
+                api_key=config.llm.api_key,
+                enable_fallback=True
+            )
+        return self._llm
+
+    def run(self, goal: str, initial_context: Dict = None) -> OrchestratorResult:
+        """
+        Run naked LLM execution - ONE LLM call per problem.
+        
+        This is the baseline test: can a single LLM call generate
+        valid QASM for a quantum computing problem?
+        """
+        start_time = time.perf_counter()
+
+        # Ensure goal is a string
+        if isinstance(goal, list):
+            goal = goal[0] if goal else ""
+        goal = str(goal) if goal else ""
+
+        self.log("INFO", f"Starting naked LLM execution for: {goal}")
+
+        from tools import invoke_tool
+
+        errors = []
+        circuit_qasm = None
+        llm_requests = 0
+        tokens_used = 0
+
+        # System prompt for direct QASM generation
+        system_prompt = """You are an expert quantum computing engineer.
+Your task is to generate valid OpenQASM 2.0 code for the given quantum circuit problem.
+
+RULES:
+1. Output ONLY valid OpenQASM 2.0 code
+2. Start with: OPENQASM 2.0; include "qelib1.inc";
+3. Declare qubits with: qreg q[N];
+4. Declare classical bits with: creg c[N];
+5. Use standard gates: h, x, y, z, cx, cz, ccx, swap, t, s, rx, ry, rz
+6. Add measurements with: measure q[i] -> c[i];
+7. NO explanations, NO markdown, ONLY QASM code
+
+EXAMPLE OUTPUT:
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2];
+creg c[2];
+h q[0];
+cx q[0], q[1];
+measure q[0] -> c[0];
+measure q[1] -> c[1];
+"""
+
+        user_prompt = f"""Generate the OpenQASM 2.0 code for this quantum circuit problem:
+
+{goal}
+
+Output ONLY the QASM code, nothing else."""
+
+        try:
+            # Single LLM call - the naked baseline test
+            llm = self._get_llm()
+            response = llm.generate(
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ],
+                temperature=0.1,  # Low temperature for deterministic output
+                max_tokens=1000
+            )
+            llm_requests = 1
+            tokens_used = response.tokens_used
+
+            # Extract QASM from response
+            raw_output = response.text.strip()
+            
+            # Clean up common LLM artifacts
+            if "```" in raw_output:
+                # Extract from code block
+                lines = raw_output.split("\n")
+                in_block = False
+                qasm_lines = []
+                for line in lines:
+                    if line.strip().startswith("```"):
+                        if in_block:
+                            break
+                        in_block = True
+                        continue
+                    if in_block:
+                        qasm_lines.append(line)
+                raw_output = "\n".join(qasm_lines)
+            
+            # Ensure it starts with OPENQASM declaration
+            if "OPENQASM" in raw_output:
+                # Find the start of QASM
+                idx = raw_output.find("OPENQASM")
+                circuit_qasm = raw_output[idx:]
+            else:
+                # Try to use as-is if it looks like QASM
+                if "qreg" in raw_output or "include" in raw_output:
+                    circuit_qasm = "OPENQASM 2.0;\ninclude \"qelib1.inc\";\n" + raw_output
+                else:
+                    errors.append(f"LLM did not produce valid QASM: {raw_output[:100]}")
+
+            # Validate the generated QASM
+            if circuit_qasm:
+                validation = invoke_tool("validate_syntax", qasm=circuit_qasm)
+                if not validation.get("success") or not validation.get("valid", False):
+                    error_msg = validation.get("error", "Unknown validation error")
+                    errors.append(f"QASM validation failed: {error_msg}")
+                    # Still keep the circuit for analysis
+                    self.log("WARN", f"Generated QASM failed validation: {error_msg}")
+
+        except Exception as e:
+            errors.append(str(e))
+            self.log("ERROR", f"Naked LLM execution failed: {e}")
+
+        elapsed = (time.perf_counter() - start_time) * 1000
+
+        # Create a simple AgentResult-like dict for compatibility
+        from agents import AgentResult
+        naked_result = AgentResult(
+            success=circuit_qasm is not None and len(errors) == 0,
+            data={
+                "qasm": circuit_qasm,
+                "llm_requests": llm_requests,
+                "tokens_used": tokens_used
+            },
+            message=f"Generated QASM via naked LLM ({llm_requests} request, {tokens_used} tokens)"
+        )
+
+        return OrchestratorResult(
+            success=circuit_qasm is not None and len(errors) == 0,
+            final_output=circuit_qasm,
+            execution_time_ms=elapsed,
+            steps_completed=1 if llm_requests > 0 else 0,
+            total_steps=1,
+            agent_results={"naked_llm": naked_result},
+            errors=errors
+        )
+
+
+# Factory function
+def create_orchestrator(mode: str) -> BaseOrchestrator:
+    """Create an orchestrator based on mode."""
+    if mode == "blackboard":
+        return BlackboardOrchestrator()
+    elif mode == "guided":
+        return GuidedOrchestrator()
+    elif mode == "naked":
+        return NakedOrchestrator()
+    elif mode == "quasar":
+        from .quasar_orchestrator import QuasarOrchestrator
+        return QuasarOrchestrator()
+    elif mode == "hybrid":
+        from .quasar_orchestrator import HybridOrchestrator
+        return HybridOrchestrator()
+    else:
+        raise ValueError(f"Unknown mode: {mode}. Use 'blackboard', 'guided', 'naked', 'quasar', or 'hybrid'")

orchestrators/quasar_orchestrator.py

@@ -0,0 +1,563 @@
+# Path: QAgents-workflos/orchestrators/quasar_orchestrator.py
+# Relations: Uses agents/llm_adapter.py, tools/quantum_tools.py, client/mcp_client.py
+# Description: QUASAR-lite orchestrator implementing Tool-Augmented LLM with hierarchical rewards
+"""
+QUASAR-Lite Orchestrator: Tool-Augmented LLM with Hierarchical Verification
+
+Based on the QUASAR framework (2025) for quantum circuit generation:
+- Tier 1: Syntax validation (compile check)
+- Tier 2: Semantic validation (unitarity, qubit count)  
+- Tier 3: Correctness validation (expected states)
+- Tier 4: Optimization (depth/gate count)
+
+Key Innovation: LLM generates → Tool validates → Feedback loop until success
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+import logging
+import time
+import re
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ValidationTier:
+    """Result from a validation tier."""
+    tier: int
+    name: str
+    passed: bool
+    message: str
+    details: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class QuasarResult:
+    """Result from QUASAR orchestration."""
+    success: bool
+    final_qasm: Optional[str]
+    execution_time_ms: float
+    llm_calls: int
+    tokens_used: int
+    tiers_passed: List[int]
+    validation_history: List[ValidationTier] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+    iterations: int = 0
+
+    @property
+    def final_output(self) -> Optional[str]:
+        """Alias for compatibility with OrchestratorResult."""
+        return self.final_qasm
+class QuasarOrchestrator:
+    """
+    QUASAR-Lite: Tool-Augmented LLM for Quantum Circuit Generation
+    
+    Key differences from NAKED mode:
+    1. Validates after each generation attempt
+    2. Provides error feedback to LLM for self-correction
+    3. Uses hierarchical reward tiers
+    4. Supports circuit partitioning for complex problems
+    
+    Key differences from GUIDED mode:
+    1. Single LLM with tool access (not multi-agent)
+    2. External validation (not self-reflection)
+    3. Iterative refinement with ground-truth feedback
+    """
+    
+    def __init__(self, max_iterations: int = 3):
+        self.max_iterations = max_iterations
+        self._llm = None
+        self._mcp_client = None
+        
+    def _get_llm(self):
+        """Lazy load LLM adapter."""
+        if self._llm is None:
+            from agents.llm_adapter import get_llm_adapter
+            from config import config
+            self._llm = get_llm_adapter(
+                provider="gemini",
+                api_key=config.llm.api_key,
+                enable_fallback=True
+            )
+        return self._llm
+    
+    def _get_mcp(self):
+        """Lazy load MCP client for validation."""
+        if self._mcp_client is None:
+            from client.mcp_client import get_client
+            self._mcp_client = get_client()
+        return self._mcp_client
+    
+    def _extract_qasm(self, text: str) -> Optional[str]:
+        """Extract QASM code from LLM response."""
+        if not text:
+            return None
+            
+        # Clean up common LLM artifacts
+        if "```" in text:
+            lines = text.split("\n")
+            in_block = False
+            qasm_lines = []
+            for line in lines:
+                if line.strip().startswith("```"):
+                    if in_block:
+                        break
+                    in_block = True
+                    continue
+                if in_block:
+                    qasm_lines.append(line)
+            text = "\n".join(qasm_lines)
+        
+        # Find OPENQASM declaration
+        if "OPENQASM" in text:
+            idx = text.find("OPENQASM")
+            return text[idx:].strip()
+        
+        # Try to construct valid QASM
+        if "qreg" in text or "include" in text:
+            return "OPENQASM 2.0;\ninclude \"qelib1.inc\";\n" + text.strip()
+            
+        return None
+    
+    def _validate_tier1_syntax(self, qasm: str) -> ValidationTier:
+        """Tier 1: Syntax validation - does it compile?"""
+        try:
+            mcp = self._get_mcp()
+            result = mcp.validate_syntax(qasm)
+            
+            if result.success and result.data:
+                is_valid = result.data.get("valid", False)
+                errors = result.data.get("errors", [])
+                
+                if is_valid:
+                    return ValidationTier(
+                        tier=1, name="Syntax", passed=True,
+                        message="QASM syntax is valid",
+                        details={"valid": True}
+                    )
+                else:
+                    return ValidationTier(
+                        tier=1, name="Syntax", passed=False,
+                        message=f"Syntax errors: {errors}",
+                        details={"errors": errors}
+                    )
+            
+            return ValidationTier(
+                tier=1, name="Syntax", passed=False,
+                message="Validation failed",
+                details={"error": "MCP validation failed"}
+            )
+            
+        except Exception as e:
+            # Fallback: basic regex validation
+            has_header = "OPENQASM" in qasm and "include" in qasm
+            has_qreg = "qreg" in qasm
+            has_creg = "creg" in qasm
+            
+            if has_header and has_qreg:
+                return ValidationTier(
+                    tier=1, name="Syntax", passed=True,
+                    message="Basic syntax check passed (fallback)",
+                    details={"fallback": True}
+                )
+            return ValidationTier(
+                tier=1, name="Syntax", passed=False,
+                message=f"Basic syntax check failed: {e}",
+                details={"error": str(e)}
+            )
+    
+    def _validate_tier2_semantic(self, qasm: str, expected_qubits: int = None) -> ValidationTier:
+        """Tier 2: Semantic validation - qubit count, gate validity."""
+        try:
+            mcp = self._get_mcp()
+            result = mcp.analyze_circuit(qasm)
+            
+            if result.success and result.data:
+                num_qubits = result.data.get("num_qubits", 0)
+                gate_count = result.data.get("gate_count", 0)
+                
+                issues = []
+                
+                # Check qubit count if expected
+                if expected_qubits and num_qubits != expected_qubits:
+                    issues.append(f"Expected {expected_qubits} qubits, got {num_qubits}")
+                
+                # Check for at least one gate
+                if gate_count == 0:
+                    issues.append("No gates in circuit")
+                
+                if issues:
+                    return ValidationTier(
+                        tier=2, name="Semantic", passed=False,
+                        message="; ".join(issues),
+                        details={"num_qubits": num_qubits, "gate_count": gate_count}
+                    )
+                
+                return ValidationTier(
+                    tier=2, name="Semantic", passed=True,
+                    message=f"Valid circuit: {num_qubits} qubits, {gate_count} gates",
+                    details={"num_qubits": num_qubits, "gate_count": gate_count}
+                )
+                
+        except Exception as e:
+            # Fallback: regex-based analysis
+            qreg_match = re.search(r'qreg\s+\w+\[(\d+)\]', qasm)
+            num_qubits = int(qreg_match.group(1)) if qreg_match else 0
+            
+            gate_pattern = r'\b(h|x|y|z|s|t|cx|cz|cy|swap|ccx|rz|rx|ry)\b'
+            gates = re.findall(gate_pattern, qasm, re.IGNORECASE)
+            
+            return ValidationTier(
+                tier=2, name="Semantic", passed=len(gates) > 0,
+                message=f"Fallback analysis: {num_qubits} qubits, {len(gates)} gates",
+                details={"fallback": True, "num_qubits": num_qubits, "gate_count": len(gates)}
+            )
+    
+    def _validate_tier3_correctness(self, qasm: str, expected_states: Dict[str, float] = None) -> ValidationTier:
+        """Tier 3: Correctness validation - expected output states."""
+        if not expected_states:
+            return ValidationTier(
+                tier=3, name="Correctness", passed=True,
+                message="No expected states specified, skipping",
+                details={"skipped": True}
+            )
+        
+        try:
+            mcp = self._get_mcp()
+            result = mcp.simulate_circuit(qasm, shots=1024)
+            
+            if result.success and result.data:
+                probs = result.data.get("probabilities", {})
+                
+                # Check if expected states match
+                tolerance = 0.15
+                matches = []
+                mismatches = []
+                
+                for state, expected_prob in expected_states.items():
+                    actual_prob = probs.get(state, 0.0)
+                    if abs(actual_prob - expected_prob) <= tolerance:
+                        matches.append(f"|{state}⟩: {actual_prob:.3f} ≈ {expected_prob}")
+                    else:
+                        mismatches.append(f"|{state}⟩: got {actual_prob:.3f}, expected {expected_prob}")
+                
+                if mismatches:
+                    return ValidationTier(
+                        tier=3, name="Correctness", passed=False,
+                        message=f"State mismatches: {mismatches}",
+                        details={"expected": expected_states, "actual": probs}
+                    )
+                
+                return ValidationTier(
+                    tier=3, name="Correctness", passed=True,
+                    message=f"States match: {matches}",
+                    details={"matches": matches}
+                )
+                
+        except Exception as e:
+            return ValidationTier(
+                tier=3, name="Correctness", passed=False,
+                message=f"Simulation failed: {e}",
+                details={"error": str(e)}
+            )
+    
+    def _validate_tier4_optimization(self, qasm: str, max_depth: int = None) -> ValidationTier:
+        """Tier 4: Optimization - circuit depth and gate count."""
+        try:
+            mcp = self._get_mcp()
+            result = mcp.analyze_circuit(qasm)
+            
+            if result.success and result.data:
+                depth = result.data.get("depth", 0)
+                gate_count = result.data.get("gate_count", 0)
+                cx_count = result.data.get("cx_count", 0)
+                
+                details = {"depth": depth, "gate_count": gate_count, "cx_count": cx_count}
+                
+                if max_depth and depth > max_depth:
+                    return ValidationTier(
+                        tier=4, name="Optimization", passed=False,
+                        message=f"Depth {depth} exceeds max {max_depth}",
+                        details=details
+                    )
+                
+                return ValidationTier(
+                    tier=4, name="Optimization", passed=True,
+                    message=f"Depth: {depth}, Gates: {gate_count}, CX: {cx_count}",
+                    details=details
+                )
+                
+        except Exception as e:
+            return ValidationTier(
+                tier=4, name="Optimization", passed=True,
+                message=f"Optimization check skipped: {e}",
+                details={"error": str(e)}
+            )
+    
+    def _build_feedback_prompt(self, goal: str, previous_qasm: str, 
+                               failed_tier: ValidationTier, iteration: int) -> str:
+        """Build prompt with feedback for LLM self-correction."""
+        return f"""Your previous attempt to generate a quantum circuit had an error.
+
+ORIGINAL TASK:
+{goal}
+
+YOUR PREVIOUS OUTPUT:
+```qasm
+{previous_qasm or "(no valid QASM generated)"}
+```
+
+VALIDATION ERROR (Tier {failed_tier.tier} - {failed_tier.name}):
+{failed_tier.message}
+
+Details: {failed_tier.details}
+
+INSTRUCTIONS:
+1. Analyze the error carefully
+2. Fix the issue in your QASM code
+3. Output ONLY valid OpenQASM 2.0 code
+4. Start with: OPENQASM 2.0; include "qelib1.inc";
+
+Generate the CORRECTED QASM code:"""
+
+    def _build_initial_prompt(self, goal: str, expected_qubits: int = None, 
+                              expected_states: Dict[str, float] = None) -> str:
+        """Build the initial generation prompt."""
+        constraints = []
+        if expected_qubits:
+            constraints.append(f"- Use exactly {expected_qubits} qubit(s)")
+        if expected_states:
+            states_str = ", ".join([f"|{s}⟩: {p}" for s, p in expected_states.items()])
+            constraints.append(f"- Expected measurement probabilities: {states_str}")
+        
+        constraints_section = "\n".join(constraints) if constraints else "- No specific constraints"
+        
+        return f"""Generate a quantum circuit for the following task:
+
+TASK:
+{goal}
+
+CONSTRAINTS:
+{constraints_section}
+
+RULES:
+1. Output ONLY valid OpenQASM 2.0 code
+2. Start with: OPENQASM 2.0; include "qelib1.inc";
+3. Declare qubits with: qreg q[N];
+4. Declare classical bits with: creg c[N];
+5. Use standard gates: h, x, y, z, cx, cz, ccx, swap, t, s, rx, ry, rz
+6. Add measurements with: measure q[i] -> c[i];
+7. NO explanations, NO markdown, ONLY QASM code
+
+Generate the OpenQASM 2.0 circuit:"""
+
+    def run(self, goal: str, 
+            expected_qubits: int = None,
+            expected_states: Dict[str, float] = None,
+            max_depth: int = None) -> QuasarResult:
+        """
+        Run QUASAR-lite orchestration with hierarchical validation.
+        
+        Args:
+            goal: The problem description
+            expected_qubits: Expected number of qubits (for Tier 2)
+            expected_states: Expected output states (for Tier 3)
+            max_depth: Maximum circuit depth (for Tier 4)
+            
+        Returns:
+            QuasarResult with final QASM and validation history
+        """
+        start_time = time.perf_counter()
+        
+        llm = self._get_llm()
+        llm_calls = 0
+        tokens_used = 0
+        validation_history = []
+        errors = []
+        current_qasm = None
+        tiers_passed = []
+        
+        system_prompt = """You are an expert quantum computing engineer.
+Your task is to generate valid OpenQASM 2.0 code for quantum circuits.
+You will receive feedback if your code has errors and must correct them.
+Always output ONLY valid QASM code, no explanations."""
+
+        # Initial prompt
+        user_prompt = self._build_initial_prompt(goal, expected_qubits, expected_states)
+        
+        for iteration in range(self.max_iterations):
+            # Generate QASM
+            try:
+                response = llm.generate(
+                    messages=[
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt}
+                    ],
+                    temperature=0.1 + (iteration * 0.1),  # Increase temperature on retries
+                    max_tokens=1500
+                )
+                llm_calls += 1
+                tokens_used += response.tokens_used
+                
+                current_qasm = self._extract_qasm(response.text)
+                
+                if not current_qasm:
+                    errors.append(f"Iteration {iteration+1}: Failed to extract QASM")
+                    user_prompt = self._build_feedback_prompt(
+                        goal, response.text,
+                        ValidationTier(0, "Extraction", False, "No valid QASM found in response"),
+                        iteration
+                    )
+                    continue
+                    
+            except KeyboardInterrupt:
+                raise  # Re-raise keyboard interrupt
+            except Exception as e:
+                errors.append(f"Iteration {iteration+1}: LLM error - {e}")
+                logger.error(f"QUASAR LLM error: {e}")
+                # Don't continue retrying on LLM errors, they'll likely fail again
+                break
+            
+            # Run hierarchical validation
+            all_passed = True
+            tiers_passed = []
+            
+            # Tier 1: Syntax
+            tier1 = self._validate_tier1_syntax(current_qasm)
+            validation_history.append(tier1)
+            if not tier1.passed:
+                all_passed = False
+                user_prompt = self._build_feedback_prompt(goal, current_qasm, tier1, iteration)
+                continue
+            tiers_passed.append(1)
+            
+            # Tier 2: Semantic
+            tier2 = self._validate_tier2_semantic(current_qasm, expected_qubits)
+            validation_history.append(tier2)
+            if not tier2.passed:
+                all_passed = False
+                user_prompt = self._build_feedback_prompt(goal, current_qasm, tier2, iteration)
+                continue
+            tiers_passed.append(2)
+            
+            # Tier 3: Correctness (if expected states provided)
+            if expected_states:
+                tier3 = self._validate_tier3_correctness(current_qasm, expected_states)
+                validation_history.append(tier3)
+                if not tier3.passed:
+                    all_passed = False
+                    user_prompt = self._build_feedback_prompt(goal, current_qasm, tier3, iteration)
+                    continue
+                tiers_passed.append(3)
+            
+            # Tier 4: Optimization (informational, doesn't fail)
+            tier4 = self._validate_tier4_optimization(current_qasm, max_depth)
+            validation_history.append(tier4)
+            if tier4.passed:
+                tiers_passed.append(4)
+            
+            # All validations passed!
+            if all_passed:
+                elapsed = (time.perf_counter() - start_time) * 1000
+                return QuasarResult(
+                    success=True,
+                    final_qasm=current_qasm,
+                    execution_time_ms=elapsed,
+                    llm_calls=llm_calls,
+                    tokens_used=tokens_used,
+                    tiers_passed=tiers_passed,
+                    validation_history=validation_history,
+                    errors=errors,
+                    iterations=iteration + 1
+                )
+        
+        # Max iterations reached
+        elapsed = (time.perf_counter() - start_time) * 1000
+        return QuasarResult(
+            success=current_qasm is not None and len(tiers_passed) >= 2,
+            final_qasm=current_qasm,
+            execution_time_ms=elapsed,
+            llm_calls=llm_calls,
+            tokens_used=tokens_used,
+            tiers_passed=tiers_passed,
+            validation_history=validation_history,
+            errors=errors,
+            iterations=self.max_iterations
+        )
+
+
+class HybridOrchestrator:
+    """
+    Hybrid Orchestrator: NAKED speed + QUASAR reliability
+    
+    Strategy:
+    1. Try NAKED mode first (fast, cheap)
+    2. If NAKED fails validation, fall back to QUASAR (reliable, more expensive)
+    
+    This gives best of both worlds:
+    - Easy problems: solved in 1 LLM call via NAKED
+    - Hard problems: solved via QUASAR with feedback loops
+    """
+    
+    def __init__(self):
+        self._naked = None
+        self._quasar = None
+        
+    def _get_naked(self):
+        """Lazy load NAKED orchestrator."""
+        if self._naked is None:
+            from orchestrators.orchestrator import NakedOrchestrator
+            self._naked = NakedOrchestrator()
+        return self._naked
+    
+    def _get_quasar(self):
+        """Lazy load QUASAR orchestrator."""
+        if self._quasar is None:
+            self._quasar = QuasarOrchestrator(max_iterations=3)
+        return self._quasar
+    
+    def run(self, goal: str, 
+            expected_qubits: int = None,
+            expected_states: Dict[str, float] = None,
+            max_depth: int = None) -> QuasarResult:
+        """
+        Run hybrid orchestration: NAKED first, QUASAR on failure.
+        
+        Returns:
+            QuasarResult for compatibility with comprehensive tests
+        """
+        start_time = time.perf_counter()
+        
+        # Step 1: Try NAKED mode
+        naked = self._get_naked()
+        naked_result = naked.run(goal)
+        
+        if naked_result.success and naked_result.final_output:
+            # Validate NAKED output
+            quasar = self._get_quasar()
+            qasm = naked_result.final_output
+            
+            tier1 = quasar._validate_tier1_syntax(qasm)
+            tier2 = quasar._validate_tier2_semantic(qasm, expected_qubits)
+            
+            if tier1.passed and tier2.passed:
+                # NAKED succeeded!
+                elapsed = (time.perf_counter() - start_time) * 1000
+                return QuasarResult(
+                    success=True,
+                    final_qasm=qasm,
+                    execution_time_ms=elapsed,
+                    llm_calls=1,
+                    tokens_used=naked_result.agent_results.get("naked_llm", {}).data.get("tokens_used", 0) if naked_result.agent_results else 0,
+                    tiers_passed=[1, 2],
+                    validation_history=[tier1, tier2],
+                    errors=[],
+                    iterations=1
+                )
+        
+        # Step 2: NAKED failed, use QUASAR
+        logger.info(f"NAKED failed, falling back to QUASAR for: {goal[:50]}...")
+        quasar = self._get_quasar()
+        return quasar.run(goal, expected_qubits, expected_states, max_depth)

orchestrators/router.py

@@ -0,0 +1,188 @@
+# Path: QAgents-workflos/orchestrators/router.py
+# Relations: Used by orchestrators/orchestrator.py, run_quality_eval.py
+# Description: Difficulty-aware orchestrator selection based on problem complexity
+#              Routes easy problems to NAKED (fastest, best quality)
+#              Routes medium to NAKED+optimization, hard to GUIDED
+
+"""
+Difficulty-Aware Router: Selects optimal orchestration mode based on problem complexity.
+
+Based on quality evaluation findings:
+- NAKED mode: Best for easy problems (47.9/100 quality, 3.7s)
+- NAKED+Optimizer: Best for medium (post-generation refinement)
+- GUIDED: For hard problems (agents may add value for complex algorithms)
+
+This router balances quality, cost, and execution time.
+"""
+
+from typing import Optional, Dict, Literal
+from dataclasses import dataclass
+from tests.test_problems import TestProblem, ProblemDifficulty
+
+
+@dataclass
+class RoutingDecision:
+    """Result of routing decision."""
+    mode: Literal["naked", "guided", "blackboard"]
+    reason: str
+    expected_quality: float
+    expected_llm_calls: int
+    expected_time_ms: int
+    use_optimizer: bool = False
+
+
+class DifficultyAwareRouter:
+    """
+    Routes problems to optimal orchestrators based on difficulty and characteristics.
+    
+    Strategy:
+    - EASY: Use NAKED (proven best)
+    - MEDIUM: Use NAKED + post-optimization
+    - HARD: Use GUIDED if agents help, NAKED+optimizer as fallback
+    
+    Can be configured for experimentation.
+    """
+    
+    # Routing configuration (can be tuned)
+    ROUTING_CONFIG = {
+        "easy": {
+            "primary_mode": "naked",
+            "use_optimizer": False,
+            "fallback_mode": "guided",
+            "expected_quality": 47.9,
+            "expected_llm_calls": 3,
+            "expected_time_ms": 3700,
+        },
+        "medium": {
+            "primary_mode": "naked",
+            "use_optimizer": True,  # Add post-generation optimization
+            "fallback_mode": "guided",
+            "expected_quality": 50.0,  # Estimated with optimizer
+            "expected_llm_calls": 3,
+            "expected_time_ms": 5000,
+        },
+        "hard": {
+            "primary_mode": "guided",  # Agents might help for complex algorithms
+            "use_optimizer": True,
+            "fallback_mode": "naked",
+            "expected_quality": 55.0,  # Estimated
+            "expected_llm_calls": 7,
+            "expected_time_ms": 25000,
+        }
+    }
+    
+    @classmethod
+    def route(cls, problem: TestProblem, 
+              prefer_naked: bool = False,
+              prefer_guided: bool = False) -> RoutingDecision:
+        """
+        Route a problem to the optimal orchestrator.
+        
+        Args:
+            problem: The quantum circuit problem to solve
+            prefer_naked: Force NAKED mode (for testing)
+            prefer_guided: Force GUIDED mode (for testing)
+            
+        Returns:
+            RoutingDecision with selected mode and metadata
+        """
+        
+        # Handle overrides
+        if prefer_naked:
+            return cls._make_decision("naked", problem, "User override")
+        if prefer_guided:
+            return cls._make_decision("guided", problem, "User override")
+        
+        # Get difficulty level
+        difficulty = problem.difficulty.value if hasattr(problem.difficulty, 'value') else str(problem.difficulty)
+        
+        # Get routing config for difficulty
+        config = cls.ROUTING_CONFIG.get(difficulty)
+        if not config:
+            # Default to guided for unknown difficulties
+            return cls._make_decision("guided", problem, f"Unknown difficulty: {difficulty}")
+        
+        # Route based on difficulty
+        return cls._make_decision(
+            config["primary_mode"],
+            problem,
+            f"Routed based on difficulty: {difficulty}",
+            use_optimizer=config.get("use_optimizer", False),
+            expected_quality=config["expected_quality"],
+            expected_llm_calls=config["expected_llm_calls"],
+            expected_time_ms=config["expected_time_ms"],
+        )
+    
+    @classmethod
+    def route_batch(cls, problems: list) -> Dict[str, RoutingDecision]:
+        """Route multiple problems."""
+        return {p.id: cls.route(p) for p in problems}
+    
+    @classmethod
+    def _make_decision(cls, mode: str, problem: TestProblem, reason: str,
+                      use_optimizer: bool = False,
+                      expected_quality: float = 45.0,
+                      expected_llm_calls: int = 3,
+                      expected_time_ms: int = 5000) -> RoutingDecision:
+        """Create a routing decision."""
+        return RoutingDecision(
+            mode=mode,
+            reason=reason,
+            expected_quality=expected_quality,
+            expected_llm_calls=expected_llm_calls,
+            expected_time_ms=expected_time_ms,
+            use_optimizer=use_optimizer,
+        )
+    
+    @classmethod
+    def print_strategy(cls):
+        """Print routing strategy."""
+        print("\n" + "="*80)
+        print("DIFFICULTY-AWARE ROUTING STRATEGY")
+        print("="*80)
+        
+        for difficulty in ["easy", "medium", "hard"]:
+            config = cls.ROUTING_CONFIG[difficulty]
+            print(f"\n{difficulty.upper()}:")
+            print(f"  Primary Mode: {config['primary_mode']}")
+            print(f"  Use Optimizer: {config['use_optimizer']}")
+            print(f"  Fallback: {config['fallback_mode']}")
+            print(f"  Expected Quality: {config['expected_quality']:.1f}/100")
+            print(f"  Expected LLM Calls: {config['expected_llm_calls']}")
+            print(f"  Expected Time: {config['expected_time_ms']}ms")
+        
+        print("\n" + "="*80)
+
+
+def select_orchestrator_mode(problem: TestProblem) -> str:
+    """
+    Convenience function: Get orchestrator mode for a problem.
+    
+    Usage:
+        mode = select_orchestrator_mode(problem)
+        orchestrator = create_orchestrator(mode)
+    """
+    decision = DifficultyAwareRouter.route(problem)
+    return decision.mode
+
+
+def should_use_optimizer(problem: TestProblem) -> bool:
+    """Check if optimization should be applied after generation."""
+    decision = DifficultyAwareRouter.route(problem)
+    return decision.use_optimizer
+
+
+# Example usage
+if __name__ == "__main__":
+    from tests.test_problems import EASY_PROBLEMS, MEDIUM_PROBLEMS, HARD_PROBLEMS
+    
+    print("\nExample: Routing all problems")
+    print("-" * 80)
+    
+    all_problems = EASY_PROBLEMS + MEDIUM_PROBLEMS + HARD_PROBLEMS
+    
+    for problem in all_problems:
+        decision = DifficultyAwareRouter.route(problem)
+        print(f"{problem.id:15} -> {decision.mode:10} ({decision.reason})")
+    
+    DifficultyAwareRouter.print_strategy()

prompts/__init__.py

@@ -0,0 +1,25 @@
+"""Prompts module: System prompts for all agents."""
+
+from .agent_prompts import (
+    ARCHITECT_PROMPT,
+    BUILDER_PROMPT,
+    VALIDATOR_PROMPT,
+    OPTIMIZER_PROMPT,
+    ANALYZER_PROMPT,
+    SCORER_PROMPT,
+    COORDINATOR_PROMPT,
+    ALL_PROMPTS,
+    get_prompt
+)
+
+__all__ = [
+    "ARCHITECT_PROMPT",
+    "BUILDER_PROMPT", 
+    "VALIDATOR_PROMPT",
+    "OPTIMIZER_PROMPT",
+    "ANALYZER_PROMPT",
+    "SCORER_PROMPT",
+    "COORDINATOR_PROMPT",
+    "ALL_PROMPTS",
+    "get_prompt"
+]

prompts/agent_prompts.py

@@ -0,0 +1,276 @@
+"""
+Prompts Module: System prompts for all agents.
+Each prompt defines the agent's behavior, constraints, and expertise.
+"""
+
+# ============================================================
+# ARCHITECT AGENT PROMPT
+# ============================================================
+
+ARCHITECT_PROMPT = """You are a Quantum Circuit Architect agent. Your role is to plan and design quantum circuits at a high level.
+
+## Your Responsibilities:
+1. Understand the user's goal and translate it into a circuit design plan
+2. Choose appropriate circuit templates or patterns
+3. Determine the number of qubits and overall structure needed
+4. Consider hardware constraints when planning
+
+## Your Tools:
+- create_from_template: Use predefined templates (bell_state, ghz, qft, grover)
+- generate_from_description: Create circuits from natural language
+- analyze_circuit: Analyze existing circuits to understand their structure
+
+## Guidelines:
+- Start simple - prefer smaller circuits when possible
+- Consider the target hardware's qubit count and connectivity
+- Break complex goals into simpler sub-circuits that can be composed
+- Document your reasoning for the chosen approach
+
+## Output Format:
+When you select a tool, explain your reasoning briefly. Focus on:
+1. Why this approach fits the goal
+2. What the expected circuit structure will be
+3. Any constraints or considerations for the next steps
+
+Be concise and action-oriented. Your job is to get a working circuit started."""
+
+
+# ============================================================
+# BUILDER AGENT PROMPT
+# ============================================================
+
+BUILDER_PROMPT = """You are a Quantum Circuit Builder agent. Your role is to construct and modify quantum circuits.
+
+## Your Responsibilities:
+1. Build circuits based on architectural plans
+2. Compose multiple circuits together
+3. Apply circuit transformations (tensor, repeat)
+4. Ensure the circuit syntax is correct
+
+## Your Tools:
+- create_from_template: Build from predefined templates
+- generate_random_circuit: Create random circuits for testing
+- generate_from_description: Build from natural language
+- compose_circuits: Combine circuits sequentially
+- tensor_circuits: Combine circuits in parallel
+- repeat_circuit: Repeat a circuit pattern
+
+## Guidelines:
+- Follow the architect's plan closely
+- Use compose_circuits to chain operations
+- Use tensor_circuits when operations should be parallel
+- Start with simple building blocks and combine them
+- Check that qubit counts match when composing
+
+## Output Format:
+Produce valid OpenQASM 2.0 circuits. When using tools:
+1. Specify exact parameters
+2. Explain how this builds toward the goal
+3. Note any assumptions about qubit ordering"""
+
+
+# ============================================================
+# VALIDATOR AGENT PROMPT  
+# ============================================================
+
+VALIDATOR_PROMPT = """You are a Quantum Circuit Validator agent. Your role is to ensure circuits are correct and executable.
+
+## Your Responsibilities:
+1. Validate circuit syntax
+2. Check hardware connectivity compliance
+3. Verify unitary correctness
+4. Report any issues clearly
+
+## Your Tools:
+- validate_syntax: Check QASM syntax for errors
+- check_connectivity: Verify circuit works on target hardware
+- verify_unitary: Confirm circuit produces valid unitary
+
+## Validation Order:
+1. ALWAYS start with syntax validation
+2. Then check connectivity for the target hardware
+3. Finally verify unitary correctness
+
+## Guidelines:
+- Be thorough - check all aspects
+- Report specific line numbers and gates for errors
+- Suggest fixes when possible
+- Hardware profiles available: ibm_eagle, ionq_aria, rigetti_aspen
+
+## Output Format:
+Provide clear validation results:
+- PASS/FAIL for each check
+- Specific error locations if failed
+- Suggestions for fixing issues"""
+
+
+# ============================================================
+# OPTIMIZER AGENT PROMPT
+# ============================================================
+
+OPTIMIZER_PROMPT = """You are a Quantum Circuit Optimizer agent. Your role is to improve circuit efficiency.
+
+## Your Responsibilities:
+1. Reduce circuit depth
+2. Minimize gate count
+3. Improve hardware fitness
+4. Apply optimization strategies
+
+## Your Tools:
+- generate_inverse: Create inverse for identity elimination
+- compose_circuits: Restructure by recomposing
+- analyze_circuit: Check current metrics
+- calculate_complexity: Get complexity score
+- calculate_hardware_fitness: Check hardware compatibility
+
+## Optimization Strategies:
+1. Gate cancellation: U * U† = I
+2. Gate commutation: Reorder for parallel execution
+3. Decomposition: Break complex gates into native gates
+4. Depth reduction: Maximize parallelism
+
+## Guidelines:
+- Always measure before and after optimization
+- Target specific metrics (depth, gates, or fitness)
+- Small improvements compound - iterate if needed
+- Don't sacrifice correctness for speed
+
+## Output Format:
+Report optimization results:
+- Before/after metrics
+- Techniques applied
+- Improvement percentage"""
+
+
+# ============================================================
+# ANALYZER AGENT PROMPT
+# ============================================================
+
+ANALYZER_PROMPT = """You are a Quantum Circuit Analyzer agent. Your role is to extract insights from circuits.
+
+## Your Responsibilities:
+1. Parse and understand circuit structure
+2. Measure circuit properties (depth, gates, etc.)
+3. Simulate and get state/probability information
+4. Estimate resource requirements
+
+## Your Tools:
+- parse_qasm: Extract circuit structure
+- analyze_circuit: Get comprehensive analysis
+- get_circuit_depth: Measure depth
+- get_statevector: Get quantum state
+- get_probabilities: Get measurement probabilities
+- estimate_resources: Resource estimation
+- estimate_noise: Noise impact estimation
+
+## Guidelines:
+- Start with structural analysis (parse, analyze)
+- Then get simulation results if needed
+- Consider noise for realistic assessment
+- Report findings clearly and completely
+
+## Analysis Areas:
+1. Structure: qubits, gates, depth, connectivity
+2. State: amplitudes, probabilities, entanglement
+3. Resources: execution time, error rates
+4. Comparison: vs ideal, vs other circuits
+
+## Output Format:
+Provide structured analysis:
+- Circuit summary (qubits, gates, depth)
+- Key observations
+- Recommendations if applicable"""
+
+
+# ============================================================
+# SCORER AGENT PROMPT
+# ============================================================
+
+SCORER_PROMPT = """You are a Quantum Circuit Scorer agent. Your role is to evaluate circuit quality.
+
+## Your Responsibilities:
+1. Calculate complexity scores
+2. Assess hardware fitness
+3. Measure expressibility
+4. Provide overall quality assessment
+
+## Your Tools:
+- calculate_complexity: Lower is better (simpler circuit)
+- calculate_hardware_fitness: Higher is better (easier to run)
+- calculate_expressibility: How much state space coverage
+- simulate_circuit: Verify functionality via simulation
+
+## Scoring Framework:
+1. Complexity (weight: 30%): Gate count, depth
+2. Hardware Fitness (weight: 40%): Connectivity, native gates
+3. Expressibility (weight: 20%): State space coverage
+4. Correctness (weight: 10%): Simulation accuracy
+
+## Guidelines:
+- Always get all relevant scores
+- Consider the specific use case when weighting
+- Compare against reference circuits when available
+- Provide actionable feedback
+
+## Output Format:
+Provide comprehensive scoring:
+- Individual scores with explanations
+- Weighted overall score
+- Strengths and weaknesses
+- Improvement suggestions"""
+
+
+# ============================================================
+# COORDINATOR AGENT PROMPT (for Guided mode)
+# ============================================================
+
+COORDINATOR_PROMPT = """You are a Workflow Coordinator agent. Your role is to orchestrate other agents in a structured workflow.
+
+## Your Responsibilities:
+1. Parse the user's goal
+2. Determine the workflow sequence
+3. Dispatch tasks to specialized agents
+4. Collect and synthesize results
+
+## Workflow Templates:
+1. BUILD: Architect → Builder → Validator → Scorer
+2. OPTIMIZE: Analyzer → Optimizer → Validator → Scorer
+3. EVALUATE: Analyzer → Scorer
+4. FULL: Architect → Builder → Validator → Optimizer → Analyzer → Scorer
+
+## Guidelines:
+- Choose the appropriate workflow for the goal
+- Monitor agent progress and handle failures
+- Aggregate results for final report
+- Ensure each step completes before proceeding
+
+## State Machine:
+- PLANNING: Determine workflow
+- DISPATCHING: Assign task to agent
+- WAITING: Wait for agent completion
+- COLLECTING: Gather results
+- COMPLETED: Final synthesis
+
+## Output Format:
+Report workflow execution:
+- Workflow chosen and why
+- Each step's outcome
+- Final aggregated results
+- Any issues encountered"""
+
+
+# Dictionary for easy access
+ALL_PROMPTS = {
+    "architect": ARCHITECT_PROMPT,
+    "builder": BUILDER_PROMPT,
+    "validator": VALIDATOR_PROMPT,
+    "optimizer": OPTIMIZER_PROMPT,
+    "analyzer": ANALYZER_PROMPT,
+    "scorer": SCORER_PROMPT,
+    "coordinator": COORDINATOR_PROMPT
+}
+
+
+def get_prompt(agent_type: str) -> str:
+    """Get prompt for a specific agent type."""
+    return ALL_PROMPTS.get(agent_type, "")

prompts/optimized_prompts.py

@@ -0,0 +1,289 @@
+# Path: QAgents-workflos/prompts/optimized_prompts.py
+# Relations: Used by orchestrators/orchestrator.py (NakedOrchestrator)
+# Description: Enhanced prompts for NAKED mode with quantum optimization guidance
+#              These prompts achieve 47.9/100 quality and can be further improved
+#              by adding explicit optimization constraints
+
+"""
+Optimized Prompts: Direct LLM prompts for quantum circuit generation
+
+Based on quality evaluation findings:
+- NAKED mode outperforms multi-agent approaches
+- Direct prompts with explicit constraints improve quality
+- Avoids hallucinated measurements and unnecessary operations
+"""
+
+# =============================================================================
+# QUANTUM CIRCUIT GENERATION PROMPT (NAKED MODE - OPTIMIZED)
+# =============================================================================
+
+QUANTUM_CIRCUIT_OPTIMIZED = """You are an expert quantum circuit designer. Generate OpenQASM 2.0 circuits that are:
+1. MINIMAL - use fewest possible gates
+2. CORRECT - solve the specific problem
+3. OPTIMAL - prefer lower depth and fewer two-qubit gates
+
+CRITICAL CONSTRAINTS:
+- Do NOT add measurement operations unless explicitly requested
+- Do NOT use extra qubits beyond what the problem requires
+- Do NOT add arbitrary gates (be precise)
+- Prefer single-qubit gates over two-qubit gates
+- Minimize circuit depth
+
+PROBLEM: {problem_statement}
+
+EXPECTED OUTPUT:
+- Exactly {min_qubits} qubits (may use up to {max_qubits} if needed, but justify)
+- Maximum {max_depth} gate depth {if max_depth else "(if applicable)"}
+- Only gates in: {required_gates}
+- Avoid gates: {forbidden_gates if forbidden_gates else "none"}
+
+SOLUTION APPROACH:
+1. Understand what quantum state/operation is needed
+2. Choose the minimal gate sequence
+3. Verify the gates are available
+4. Return ONLY the QASM code
+
+Return the complete OpenQASM 2.0 circuit wrapped in code blocks.
+Format:
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+[Your circuit here]
+```
+
+Remember: Simplicity and correctness first, optimization second."""
+
+# =============================================================================
+# ENHANCED QUANTUM CIRCUIT GENERATION (WITH OPTIMIZATION HINTS)
+# =============================================================================
+
+QUANTUM_CIRCUIT_OPTIMIZED_V2 = """You are an expert quantum circuit designer with deep knowledge of quantum gate theory and optimization.
+
+TASK: Generate an OpenQASM 2.0 quantum circuit that solves the following problem.
+
+PROBLEM: {problem_statement}
+
+DESIGN REQUIREMENTS:
+✓ Use exactly {min_qubits} qubit(s)
+✓ Keep depth ≤ {max_depth if max_depth else "minimal"}
+✓ Only use these gates: {required_gates}
+✓ Do NOT use: {forbidden_gates if forbidden_gates else "none"}
+
+CRITICAL RULES (must follow):
+1. NO measurement operations unless explicitly required
+2. NO extra qubits - use only what's needed
+3. NO unnecessary gates - every gate serves a purpose
+4. Prefer H, X, Z, CX over complex multi-qubit gates
+5. Gate cancellations (e.g., X·X = I) are encouraged
+
+OPTIMIZATION GUIDANCE:
+- Minimize depth: Each qubit layer should have parallel operations where possible
+- Minimize two-qubit gates: These are most expensive
+- Look for identities: XX=I, ZZ=I, HZH=X, HXH=Z, etc.
+- Consider what state you're creating, not just what gates to apply
+
+SOLUTION CHECKLIST:
+Before generating the circuit, think through:
+1. What is the target quantum state? (e.g., |+⟩, |Φ+⟩, etc.)
+2. What's the minimal gate sequence to create it?
+3. Can any gates be combined or cancelled?
+4. Is the depth truly minimal?
+
+OUTPUT FORMAT:
+Return ONLY the OpenQASM 2.0 code in a code block:
+
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[{min_qubits}];
+[Your gates here]
+```
+
+Do NOT include explanations, do NOT include measurements, do NOT use extra qubits."""
+
+# =============================================================================
+# SPECIALIZED PROMPTS FOR PROBLEM CATEGORIES
+# =============================================================================
+
+STATE_PREPARATION_PROMPT = """You are designing a quantum state preparation circuit.
+
+PROBLEM: {problem_statement}
+
+Your goal is to transform the initial state |0...0⟩ into the target quantum state.
+
+TARGET STATE: {expected_states}
+
+GATES AVAILABLE: {required_gates}
+
+KEY INSIGHTS FOR STATE PREP:
+- Hadamard (H) creates superposition: H|0⟩ = (|0⟩ + |1⟩)/√2
+- Pauli-X flips: X|0⟩ = |1⟩, X|1⟩ = |0⟩
+- Pauli-Z adds phase: Z|1⟩ = -|1⟩
+- Phase flip: |−⟩ = (|0⟩ - |1⟩)/√2 requires X then H
+- Bell states need H on first qubit, then CX
+
+SOLUTION:
+Return the minimal OpenQASM circuit:
+
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[{min_qubits}];
+[Your gates here]
+```"""
+
+ENTANGLEMENT_PROMPT = """You are designing an entanglement circuit.
+
+PROBLEM: {problem_statement}
+
+Your goal is to create entanglement between qubits.
+
+TARGET: {expected_states}
+
+ENTANGLEMENT FACTS:
+- Bell state |Φ+�� = (|00⟩ + |11⟩)/√2 requires: H on qubit 0, CX from 0→1
+- Bell state |Φ-⟩ = (|00⟩ - |11⟩)/√2 requires: X on qubit 0, H on qubit 0, CX from 0→1
+- GHZ state |GHZ⟩ = (|000⟩ + |111⟩)/√2 needs H on first, two CXs
+- Entanglement requires multi-qubit gates (CX/CNOT)
+
+SOLUTION:
+Return the minimal OpenQASM circuit:
+
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[{min_qubits}];
+[Your gates here]
+```"""
+
+ALGORITHM_PROMPT = """You are implementing a quantum algorithm.
+
+PROBLEM: {problem_statement}
+
+ALGORITHM STRUCTURE:
+{problem_statement}
+
+KEY ALGORITHM COMPONENTS:
+- Prepare superposition (usually with Hadamard)
+- Apply oracle (function evaluation)
+- Apply diffusion/phase flip (algorithm-specific)
+- Measure result
+
+SOLUTION:
+Return the complete OpenQASM circuit:
+
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[{min_qubits}];
+[Your gates here]
+```
+
+Focus on correctness of the algorithm structure over minimal gate count."""
+
+# =============================================================================
+# GATE SYNTHESIS / DECOMPOSITION
+# =============================================================================
+
+GATE_SYNTHESIS_PROMPT = """You are decomposing a complex quantum gate into basic gates.
+
+PROBLEM: {problem_statement}
+
+TARGET GATE: {goal}
+
+DECOMPOSITION FACTS:
+- SWAP gate = 3 CX gates (CX a→b, CX b→a, CX a→b)
+- CZ gate = H on target, CX, H on target
+- Y gate = S·X·S†
+- T gate = rotation by π/8 around Z-axis
+- Rx(θ) = H·Rz(θ)·H (where applicable)
+
+CONSTRAINTS:
+- Only use: {required_gates}
+- Avoid: {forbidden_gates if forbidden_gates else "none"}
+- Minimize gate count and depth
+
+SOLUTION:
+Return the decomposed OpenQASM circuit:
+
+```qasm
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[{min_qubits}];
+[Your decomposition here]
+```"""
+
+# =============================================================================
+# HELPER FUNCTION: FORMAT PROMPT FOR PROBLEM
+# =============================================================================
+
+def get_optimized_prompt(problem, use_advanced=True):
+    """Generate optimized prompt for a problem.
+    
+    Args:
+        problem: TestProblem instance
+        use_advanced: Use advanced V2 prompt with optimization hints
+        
+    Returns:
+        Formatted prompt string
+    """
+    template = QUANTUM_CIRCUIT_OPTIMIZED_V2 if use_advanced else QUANTUM_CIRCUIT_OPTIMIZED
+    
+    expected = problem.expected
+    
+    # Determine required and forbidden gates
+    required_gates = expected.required_gates if expected.required_gates else ["h", "x", "z", "cx", "measure"]
+    forbidden_gates = expected.forbidden_gates if expected.forbidden_gates else []
+    
+    # Format the prompt
+    prompt = template.format(
+        problem_statement=problem.prompt,
+        min_qubits=expected.min_qubits,
+        max_qubits=expected.max_qubits,
+        max_depth=expected.max_depth or "minimal",
+        required_gates=", ".join(required_gates),
+        forbidden_gates=", ".join(forbidden_gates) if forbidden_gates else "none",
+        expected_states=problem.expected.expected_states if hasattr(problem.expected, 'expected_states') else "N/A"
+    )
+    
+    return prompt
+
+
+def get_specialized_prompt(problem, use_advanced=True):
+    """Generate specialized prompt based on problem category.
+    
+    Args:
+        problem: TestProblem instance
+        use_advanced: Use advanced optimization hints
+        
+    Returns:
+        Formatted prompt string
+    """
+    from tests.test_problems import ProblemCategory
+    
+    category_prompts = {
+        ProblemCategory.STATE_PREPARATION: STATE_PREPARATION_PROMPT,
+        ProblemCategory.GATE_SYNTHESIS: GATE_SYNTHESIS_PROMPT,
+        ProblemCategory.ALGORITHM: ALGORITHM_PROMPT,
+        ProblemCategory.ERROR_CORRECTION: QUANTUM_CIRCUIT_OPTIMIZED_V2,
+        ProblemCategory.OPTIMIZATION: QUANTUM_CIRCUIT_OPTIMIZED_V2,
+    }
+    
+    template = category_prompts.get(problem.category, QUANTUM_CIRCUIT_OPTIMIZED_V2)
+    
+    expected = problem.expected
+    required_gates = expected.required_gates if expected.required_gates else ["h", "x", "z", "cx"]
+    forbidden_gates = expected.forbidden_gates if expected.forbidden_gates else []
+    
+    prompt = template.format(
+        problem_statement=problem.prompt,
+        goal=problem.name,
+        min_qubits=expected.min_qubits,
+        max_qubits=expected.max_qubits,
+        max_depth=expected.max_depth or "minimal",
+        required_gates=", ".join(required_gates),
+        forbidden_gates=", ".join(forbidden_gates) if forbidden_gates else "none",
+        expected_states=problem.expected.expected_states if hasattr(problem.expected, 'expected_states') else "N/A"
+    )
+    
+    return prompt

requirements.txt

@@ -0,0 +1,6 @@
+google-genai>=0.6.0
+litellm>=1.42.0
+requests>=2.31.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0
+gradio>=4.0.0

tasks-project-state.json

@@ -0,0 +1,149 @@
+{
+  "project": "QAgents-Workflows",
+  "version": "0.8.0",
+  "description": "Multi-agent quantum circuit optimization system with multi-model fallback",
+  "last_updated": "2024-11-28",
+  "status": "BLACKBOARD_FIXED_QUASAR_ADDED",
+  "notes": "Fixed BLACKBOARD NoneType errors. Added QUASAR orchestrator with tiered verification. Added VERY_HARD problems. Mini test shows NAKED 3.3s and BLACKBOARD 15s both pass EASY.",
+
+  "comprehensive_test_results": {
+    "test_date": "2024-11-29",
+    "previous_results": {
+      "naked": {"success": "9/9 (100%)", "avg_time_ms": 3929},
+      "guided": {"success": "7/9 (78%)", "avg_time_ms": 23120},
+      "blackboard": {"success": "2/9 (22%)", "avg_time_ms": 13507}
+    },
+    "latest_test_20241129": {
+      "problem": "HARD - Deutsch Algorithm",
+      "naked": {"success": true, "time_ms": 3914, "gates": 5},
+      "quasar": {"success": true, "time_ms": 7254, "gates": 5},
+      "hybrid": {"success": true, "time_ms": 7181, "gates": 5},
+      "blackboard": {"success": true, "time_ms": 20915, "gates": 2},
+      "result": "ALL 4 MODES PASSED"
+    },
+    "very_hard_test": {
+      "problem": "VERY_HARD - 4-Qubit QFT",
+      "naked": {"success": true, "time_ms": 4473, "gates": 12},
+      "quasar": {"success": true, "time_ms": 7811, "gates": 12},
+      "hybrid": "interrupted - rate limiting",
+      "blackboard": "interrupted - rate limiting"
+    }
+  },
+
+  "fixes_applied_20241128": {
+    "blackboard_null_safety": {
+      "file": "orchestrators/orchestrator.py",
+      "changes": ["Added try/except in agent execution loop", "Added null-checking for action and result"]
+    },
+    "llm_adapter_null_safety": {
+      "file": "agents/llm_adapter.py",
+      "changes": ["Fixed response.text None handling", "Fixed _estimate_tokens with null-safe len()"]
+    }
+  },
+
+  "new_orchestrators": {
+    "quasar": {
+      "file": "orchestrators/quasar_orchestrator.py",
+      "description": "Tiered verification orchestrator (QUASAR-lite)",
+      "tiers": [
+        "Tier 1: Syntax validation via MCP",
+        "Tier 2: Circuit analysis (depth, gates)",
+        "Tier 3: Simulation verification",
+        "Tier 4: Semantic correctness"
+      ]
+    },
+    "hybrid": {
+      "description": "NAKED first, QUASAR fallback on failure"
+    }
+  },
+
+  "new_problems": {
+    "very_hard_difficulty": [
+      "4-Qubit QFT",
+      "5-Qubit Entanglement Chain",
+      "Simon's Algorithm (2-bit)",
+      "Quantum Adder (1+1=10)"
+    ]
+  },
+
+  "model_cascade": {
+    "preferred_model": "gemini-2.5-flash-lite",
+    "models": [
+      {"name": "gemma-3-27b-it", "rpd": 14400, "priority": 1},
+      {"name": "gemini-2.5-flash-lite", "rpd": 1000, "priority": 2, "default": true},
+      {"name": "gemini-2.5-flash", "rpd": 250, "priority": 3},
+      {"name": "gemini-2.0-flash", "rpd": 200, "priority": 4},
+      {"name": "gemini-2.5-pro", "rpd": 50, "priority": 5}
+    ]
+  },
+
+  "architectures": {
+    "naked": {
+      "description": "Direct LLM-to-QASM generation",
+      "status": "PRODUCTION_READY",
+      "success_rate": "100%",
+      "recommended": true
+    },
+    "guided": {
+      "description": "4-agent pipeline (Analyzer, Designer, Generator, Validator)",
+      "status": "DEPRECATED",
+      "success_rate": "78%",
+      "note": "Replaced by QUASAR"
+    },
+    "blackboard": {
+      "description": "Event-driven multi-agent blackboard",
+      "status": "FIXED",
+      "success_rate": "~100% (needs full retest)",
+      "note": "NoneType errors fixed, ~5x slower than NAKED"
+    },
+    "quasar": {
+      "description": "Tiered verification with MCP tools",
+      "status": "NEW",
+      "file": "orchestrators/quasar_orchestrator.py"
+    },
+    "hybrid": {
+      "description": "NAKED first, QUASAR fallback",
+      "status": "NEW"
+    }
+  },
+
+  "new_files_created": [
+    {"file": "prompts/optimized_prompts.py", "purpose": "Enhanced prompts for NAKED mode"},
+    {"file": "orchestrators/router.py", "purpose": "Difficulty-aware orchestrator selection"},
+    {"file": "tests/comprehensive_test.py", "purpose": "Full diagnostic test script"},
+    {"file": "docs/COMPREHENSIVE_TEST_ANALYSIS.md", "purpose": "Analysis of all test results"},
+    {"file": "docs/STRATEGIC_IMPROVEMENTS.md", "purpose": "Improvement roadmap based on findings"},
+    {"file": "docs/PROJECT_ANALYSIS_20251128.md", "purpose": "Deep project analysis"}
+  ],
+
+  "recommendations": {
+    "immediate": [
+      "Adopt NAKED mode for production - 100% success, fastest, most efficient",
+      "Fix BLACKBOARD null-checking or deprecate entirely",
+      "Integrate optimized_prompts.py into NAKED orchestrator"
+    ],
+    "short_term": [
+      "Add circuit quality scoring beyond gate count",
+      "Improve GUIDED generator for hard problems",
+      "Implement hybrid: NAKED first, GUIDED on failure"
+    ],
+    "long_term": [
+      "Auto-select mode based on problem difficulty",
+      "MCP validation integration for correctness verification",
+      "Cost-aware orchestrator selection"
+    ]
+  },
+
+  "usage": {
+    "prerequisites": [
+      "Start MCP server: python QuantumArchitect-MCP/app.py",
+      "Set GOOGLE_API_KEY environment variable",
+      "Activate venv: & .venv/Scripts/Activate.ps1"
+    ],
+    "commands": {
+      "comprehensive_test": "python tests/comprehensive_test.py",
+      "quality_eval": "python tests/run_quality_eval.py --mode all --difficulty all",
+      "quick_test": "python tests/run_quality_eval.py --quick"
+    }
+  }
+}

tests/__init__.py

@@ -0,0 +1,87 @@
+"""Tests module: Test problems and evaluation harness."""
+
+from .test_problems import (
+    ProblemDifficulty,
+    ProblemCategory,
+    ExpectedOutput,
+    TestProblem,
+    # Problems by ID naming
+    PROBLEM_E1_PHASE_FLIP,
+    PROBLEM_E2_CONTROLLED_NOT,
+    PROBLEM_E3_MEASUREMENT_BASIS,
+    PROBLEM_M1_SWAP_DECOMPOSITION,
+    PROBLEM_M2_CONTROLLED_Z,
+    PROBLEM_M3_PHASE_ESTIMATION_PREP,
+    PROBLEM_H1_DEUTSCH,
+    PROBLEM_H2_GROVER_2QUBIT,
+    PROBLEM_H3_TELEPORTATION_PREP,
+    # Collections
+    EASY_PROBLEMS,
+    MEDIUM_PROBLEMS,
+    HARD_PROBLEMS,
+    ALL_PROBLEMS,
+    get_problem,
+    get_problems_by_difficulty,
+    get_problems_by_category,
+    get_problems_by_tag,
+    get_research_problem_set
+)
+
+from .evaluation_harness import (
+    MetricResult,
+    CostMetrics,
+    EvaluationResult,
+    AggregatedResults,
+    EvaluationHarness
+)
+
+from .circuit_quality_analyzer import (
+    CircuitQualityAnalyzer,
+    AnalysisResult,
+    get_analyzer
+)
+
+from .quality_evaluation_harness import (
+    QualityEvaluationHarness,
+    run_quick_quality_test
+)
+
+# Backward compatibility aliases
+BELL_STATE_PROBLEM = PROBLEM_E2_CONTROLLED_NOT  # Bell state is easy_002
+
+__all__ = [
+    "ProblemDifficulty",
+    "ProblemCategory",
+    "ExpectedOutput",
+    "TestProblem",
+    "PROBLEM_E1_PHASE_FLIP",
+    "PROBLEM_E2_CONTROLLED_NOT",
+    "PROBLEM_E3_MEASUREMENT_BASIS",
+    "PROBLEM_M1_SWAP_DECOMPOSITION",
+    "PROBLEM_M2_CONTROLLED_Z",
+    "PROBLEM_M3_PHASE_ESTIMATION_PREP",
+    "PROBLEM_H1_DEUTSCH",
+    "PROBLEM_H2_GROVER_2QUBIT",
+    "PROBLEM_H3_TELEPORTATION_PREP",
+    "EASY_PROBLEMS",
+    "MEDIUM_PROBLEMS",
+    "HARD_PROBLEMS",
+    "ALL_PROBLEMS",
+    "get_problem",
+    "get_problems_by_difficulty",
+    "get_problems_by_category",
+    "get_problems_by_tag",
+    "get_research_problem_set",
+    "MetricResult",
+    "CostMetrics",
+    "EvaluationResult",
+    "AggregatedResults",
+    "EvaluationHarness",
+    "BELL_STATE_PROBLEM",
+    # Quality analysis
+    "CircuitQualityAnalyzer",
+    "AnalysisResult",
+    "get_analyzer",
+    "QualityEvaluationHarness",
+    "run_quick_quality_test"
+]

tests/circuit_quality_analyzer.py

@@ -0,0 +1,351 @@
+# Path: QAgents-workflos/tests/circuit_quality_analyzer.py
+# Relations: Uses client/mcp_client.py for MCP calls, database/circuit_quality_db.py for storage
+# Description: Analyzes circuit quality using MCP endpoints
+#              Extracts: depth, gate_count, cx_count, hardware_fitness, validation, simulation
+#              Returns QualityMetrics for storage in database
+
+"""
+Circuit Quality Analyzer: Use MCP endpoints to measure circuit quality.
+This module connects to the MCP server and extracts quality metrics.
+"""
+
+import re
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AnalysisResult:
+    """Result from analyzing a circuit."""
+    depth: int = 0
+    gate_count: int = 0
+    cx_count: int = 0
+    single_qubit_count: int = 0
+    hardware_fitness: float = 0.0
+    syntax_valid: bool = False
+    complexity_score: float = 0.0
+    state_correctness: float = 0.0
+    noise_estimate: float = 0.0
+    probabilities: Dict[str, float] = None
+    errors: List[str] = None
+    
+    def __post_init__(self):
+        if self.probabilities is None:
+            self.probabilities = {}
+        if self.errors is None:
+            self.errors = []
+
+
+class CircuitQualityAnalyzer:
+    """
+    Analyzes circuit quality using MCP endpoints.
+    Connects to the running MCP server to get quality metrics.
+    """
+    
+    def __init__(self, mcp_url: str = "http://127.0.0.1:7861"):
+        self.mcp_url = mcp_url
+        self._client = None
+    
+    def _get_client(self):
+        """Get or create MCP client."""
+        if self._client is None:
+            try:
+                from client import get_client
+                self._client = get_client(self.mcp_url)
+            except Exception as e:
+                logger.error(f"Failed to get MCP client: {e}")
+                return None
+        return self._client
+    
+    def _extract_value(self, result: Any, keys: List[str], default: Any = 0) -> Any:
+        """Safely extract value from nested result."""
+        if result is None:
+            return default
+        
+        if isinstance(result, (int, float, bool)):
+            return result
+        
+        if isinstance(result, list):
+            return result[0] if result else default
+        
+        if isinstance(result, dict):
+            for key in keys:
+                if key in result:
+                    val = result[key]
+                    if isinstance(val, (int, float)):
+                        return val
+                    elif isinstance(val, dict):
+                        # Try common nested keys
+                        for subkey in ['value', 'score', 'depth', 'count', 'result']:
+                            if subkey in val:
+                                return val[subkey]
+                    elif isinstance(val, list):
+                        return val[0] if val else default
+                    return val
+            # Try first value in dict
+            for v in result.values():
+                if isinstance(v, (int, float)):
+                    return v
+        
+        return default
+    
+    def analyze_circuit(self, qasm_code: str, expected_states: Dict[str, float] = None) -> AnalysisResult:
+        """
+        Analyze a circuit using MCP endpoints.
+        
+        Args:
+            qasm_code: The QASM code to analyze
+            expected_states: Expected probability distribution for correctness check
+        
+        Returns:
+            AnalysisResult with all quality metrics
+        """
+        result = AnalysisResult()
+        
+        if not qasm_code or not qasm_code.strip():
+            result.errors.append("Empty QASM code")
+            return result
+        
+        client = self._get_client()
+        if client is None:
+            # Fallback to local analysis
+            return self._analyze_locally(qasm_code, expected_states)
+        
+        # 1. Validate syntax
+        try:
+            resp = client.validate_syntax(qasm_code)
+            if resp.success:
+                valid = resp.data
+                if isinstance(valid, dict):
+                    result.syntax_valid = valid.get('valid', False) or valid.get('is_valid', False)
+                elif isinstance(valid, bool):
+                    result.syntax_valid = valid
+                elif isinstance(valid, list):
+                    result.syntax_valid = "valid" in str(valid).lower()
+                else:
+                    result.syntax_valid = bool(valid)
+            else:
+                result.errors.append(f"Validation error: {resp.error}")
+        except Exception as e:
+            result.errors.append(f"Validation failed: {e}")
+            # Still try to parse locally
+            result.syntax_valid = "OPENQASM" in qasm_code and "qreg" in qasm_code
+        
+        # 2. Analyze circuit structure
+        try:
+            resp = client.analyze_circuit(qasm_code)
+            if resp.success and resp.data:
+                data = resp.data
+                if isinstance(data, dict):
+                    result.depth = self._extract_value(data, ['depth', 'circuit_depth'], 0)
+                    result.gate_count = self._extract_value(data, ['gate_count', 'gates', 'num_gates', 'total_gates'], 0)
+                    result.cx_count = self._extract_value(data, ['cx_count', 'cnot_count', 'two_qubit_gates'], 0)
+                    result.single_qubit_count = self._extract_value(data, ['single_qubit_count', 'single_qubit_gates', 'one_qubit_gates'], 0)
+        except Exception as e:
+            result.errors.append(f"Analysis failed: {e}")
+            # Fallback to local parsing
+            local = self._parse_qasm_locally(qasm_code)
+            result.depth = local.get('depth', 0)
+            result.gate_count = local.get('gate_count', 0)
+            result.cx_count = local.get('cx_count', 0)
+            result.single_qubit_count = local.get('single_qubit_count', 0)
+        
+        # 3. Get circuit depth if not already set
+        if result.depth == 0:
+            try:
+                resp = client.get_circuit_depth(qasm_code)
+                if resp.success:
+                    result.depth = self._extract_value(resp.data, ['depth', 'value'], 0)
+            except Exception as e:
+                result.errors.append(f"Depth check failed: {e}")
+        
+        # 4. Calculate hardware fitness
+        try:
+            resp = client.calculate_hardware_fitness(qasm_code, "ibm_brisbane")
+            if resp.success:
+                result.hardware_fitness = self._extract_value(resp.data, 
+                    ['fitness', 'fitness_score', 'hardware_fitness', 'score'], 0.0)
+                if result.hardware_fitness > 1.0:
+                    result.hardware_fitness = result.hardware_fitness / 100.0
+        except Exception as e:
+            result.errors.append(f"Hardware fitness failed: {e}")
+        
+        # 5. Calculate complexity
+        try:
+            resp = client.calculate_complexity_score(qasm_code)
+            if resp.success:
+                result.complexity_score = self._extract_value(resp.data,
+                    ['complexity', 'complexity_score', 'score', 'total'], 0.0)
+        except Exception as e:
+            result.errors.append(f"Complexity check failed: {e}")
+        
+        # 6. Get probabilities and check correctness
+        try:
+            resp = client.get_probabilities(qasm_code)
+            if resp.success and resp.data:
+                probs = resp.data
+                if isinstance(probs, dict):
+                    result.probabilities = probs
+                    if expected_states:
+                        result.state_correctness = self._check_correctness(probs, expected_states)
+                    else:
+                        # No expected states - assume 100% if circuit runs
+                        result.state_correctness = 1.0
+        except Exception as e:
+            result.errors.append(f"Probability check failed: {e}")
+            if expected_states is None:
+                result.state_correctness = 0.8  # Partial credit if other metrics pass
+        
+        # 7. Estimate noise
+        try:
+            resp = client.estimate_noise(qasm_code, "ibm_brisbane")
+            if resp.success:
+                result.noise_estimate = self._extract_value(resp.data,
+                    ['noise', 'noise_estimate', 'error_rate', 'fidelity'], 0.0)
+        except Exception as e:
+            result.errors.append(f"Noise estimation failed: {e}")
+        
+        return result
+    
+    def _analyze_locally(self, qasm_code: str, expected_states: Dict[str, float] = None) -> AnalysisResult:
+        """Fallback local analysis when MCP is unavailable."""
+        result = AnalysisResult()
+        
+        # Basic syntax check
+        result.syntax_valid = "OPENQASM" in qasm_code and "qreg" in qasm_code
+        
+        # Parse gates
+        local = self._parse_qasm_locally(qasm_code)
+        result.depth = local.get('depth', 0)
+        result.gate_count = local.get('gate_count', 0)
+        result.cx_count = local.get('cx_count', 0)
+        result.single_qubit_count = local.get('single_qubit_count', 0)
+        
+        # Estimate hardware fitness based on structure
+        if result.gate_count > 0:
+            # Penalize high CX ratio
+            cx_ratio = result.cx_count / result.gate_count
+            result.hardware_fitness = max(0.0, 1.0 - cx_ratio * 0.5)
+        
+        # Complexity estimate
+        result.complexity_score = result.depth + result.cx_count * 2
+        
+        # State correctness if syntax valid
+        if result.syntax_valid:
+            result.state_correctness = 0.7  # Partial credit
+        
+        result.errors.append("Used local fallback analysis")
+        return result
+    
+    def _parse_qasm_locally(self, qasm_code: str) -> Dict[str, int]:
+        """Parse QASM locally to extract gate counts."""
+        result = {
+            'depth': 0,
+            'gate_count': 0,
+            'cx_count': 0,
+            'single_qubit_count': 0
+        }
+        
+        lines = qasm_code.strip().split('\n')
+        gate_depth_map = {}  # qubit -> current depth
+        
+        single_qubit_gates = ['h', 'x', 'y', 'z', 's', 't', 'sdg', 'tdg', 'rx', 'ry', 'rz', 'u1', 'u2', 'u3']
+        two_qubit_gates = ['cx', 'cz', 'swap', 'cp', 'crz', 'cnot']
+        
+        for line in lines:
+            line = line.strip().lower()
+            if not line or line.startswith('//') or line.startswith('openqasm') or line.startswith('include'):
+                continue
+            if line.startswith('qreg') or line.startswith('creg') or line.startswith('measure') or line.startswith('barrier'):
+                continue
+            
+            # Check for gates
+            for gate in single_qubit_gates:
+                if line.startswith(gate + ' ') or line.startswith(gate + '('):
+                    result['single_qubit_count'] += 1
+                    result['gate_count'] += 1
+                    # Extract qubit
+                    match = re.search(r'q\[(\d+)\]', line)
+                    if match:
+                        q = int(match.group(1))
+                        gate_depth_map[q] = gate_depth_map.get(q, 0) + 1
+                    break
+            
+            for gate in two_qubit_gates:
+                if line.startswith(gate + ' '):
+                    result['cx_count'] += 1
+                    result['gate_count'] += 1
+                    # Extract qubits
+                    matches = re.findall(r'q\[(\d+)\]', line)
+                    if matches:
+                        for q in matches:
+                            q = int(q)
+                            gate_depth_map[q] = gate_depth_map.get(q, 0) + 1
+                    break
+        
+        if gate_depth_map:
+            result['depth'] = max(gate_depth_map.values())
+        
+        return result
+    
+    def _check_correctness(self, actual: Dict[str, float], expected: Dict[str, float]) -> float:
+        """Check how close actual probabilities are to expected."""
+        if not expected:
+            return 1.0
+        
+        total_error = 0.0
+        for state, exp_prob in expected.items():
+            act_prob = actual.get(state, 0.0)
+            total_error += abs(exp_prob - act_prob)
+        
+        # Also check for unexpected states
+        for state, act_prob in actual.items():
+            if state not in expected and act_prob > 0.01:
+                total_error += act_prob
+        
+        # Normalize (max error = 2.0)
+        correctness = max(0.0, 1.0 - total_error / 2.0)
+        return correctness
+    
+    def compare_circuits(self, qasm1: str, qasm2: str) -> Dict[str, Any]:
+        """Compare two circuits and return quality differences."""
+        result1 = self.analyze_circuit(qasm1)
+        result2 = self.analyze_circuit(qasm2)
+        
+        return {
+            "circuit1": {
+                "depth": result1.depth,
+                "gate_count": result1.gate_count,
+                "cx_count": result1.cx_count,
+                "hardware_fitness": result1.hardware_fitness,
+                "syntax_valid": result1.syntax_valid
+            },
+            "circuit2": {
+                "depth": result2.depth,
+                "gate_count": result2.gate_count,
+                "cx_count": result2.cx_count,
+                "hardware_fitness": result2.hardware_fitness,
+                "syntax_valid": result2.syntax_valid
+            },
+            "comparison": {
+                "depth_diff": result2.depth - result1.depth,
+                "gate_diff": result2.gate_count - result1.gate_count,
+                "cx_diff": result2.cx_count - result1.cx_count,
+                "fitness_diff": result2.hardware_fitness - result1.hardware_fitness,
+                "circuit1_better": result1.depth < result2.depth or result1.hardware_fitness > result2.hardware_fitness
+            }
+        }
+
+
+# Module-level singleton
+_analyzer: Optional[CircuitQualityAnalyzer] = None
+
+def get_analyzer(mcp_url: str = "http://127.0.0.1:7861") -> CircuitQualityAnalyzer:
+    """Get or create the quality analyzer."""
+    global _analyzer
+    if _analyzer is None:
+        _analyzer = CircuitQualityAnalyzer(mcp_url)
+    return _analyzer

tests/comprehensive_test.py

@@ -0,0 +1,287 @@
+# Path: QAgents-workflos/tests/comprehensive_test.py
+# Relations: Uses orchestrators/, tests/test_problems.py, config.py
+# Description: Comprehensive test across all difficulties with detailed diagnostics
+#              Run with: python tests/comprehensive_test.py
+
+"""
+Comprehensive Circuit Generation Test
+
+Tests all 9 problems (easy, medium, hard) with all 3 modes (naked, guided, blackboard).
+Provides detailed diagnostics on where each mode succeeds/fails.
+"""
+
+import sys
+import time
+import os
+from datetime import datetime
+from pathlib import Path
+
+# Setup paths
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from tests.test_problems import ALL_PROBLEMS, ProblemDifficulty
+from orchestrators import create_orchestrator
+from config import reset_cost_tracking, get_cost_summary, set_api_key
+
+
+def extract_qasm(result):
+    """Extract QASM from orchestrator result."""
+    if not result or not result.final_output:
+        return None
+    
+    qasm = result.final_output
+    if isinstance(qasm, list):
+        qasm = qasm[0] if qasm else None
+    
+    return str(qasm) if qasm else None
+
+
+def validate_qasm(qasm):
+    """Validate QASM structure and count gates."""
+    if not qasm:
+        return {"valid": False, "has_qreg": False, "gate_count": 0, "depth": 0}
+    
+    valid = "OPENQASM" in qasm
+    has_qreg = "qreg" in qasm
+    
+    # Count gates
+    gate_count = 0
+    for gate in ['h ', 'h(', 'x ', 'x(', 'z ', 'z(', 'cx ', 'cx(', 'cz ', 
+                 'swap ', 't ', 's ', 'ry(', 'rz(', 'rx(', 'u1(', 'u2(', 'u3(']:
+        gate_count += qasm.lower().count(gate)
+    
+    # Estimate depth (simplified)
+    lines = [l for l in qasm.split('\n') if l.strip() and not l.strip().startswith('//')]
+    depth = len([l for l in lines if any(g in l.lower() for g in ['h ', 'x ', 'cx ', 'cz ', 'swap'])])
+    
+    return {"valid": valid, "has_qreg": has_qreg, "gate_count": gate_count, "depth": depth}
+
+
+def run_comprehensive_test():
+    """Run comprehensive test across all problems and modes."""
+    
+    # Set API key
+    api_key = os.getenv('GOOGLE_API_KEY') or os.getenv('GENAI_API_KEY')
+    if api_key:
+        set_api_key(api_key)
+    else:
+        print("ERROR: No API key found. Set GOOGLE_API_KEY environment variable.")
+        return
+    
+    print("=" * 100)
+    print("COMPREHENSIVE CIRCUIT GENERATION TEST - ALL DIFFICULTIES")
+    print("=" * 100)
+    print(f"Date: {datetime.now().isoformat()}")
+    print(f"Problems: {len(ALL_PROBLEMS)} total (3 easy, 3 medium, 3 hard)")
+    print(f"Modes: naked, guided, blackboard")
+    print("=" * 100)
+    
+    # Store all results
+    all_results = []
+    
+    # Test each problem with each mode
+    for problem in ALL_PROBLEMS:
+        print(f"\n\n{'=' * 100}")
+        print(f"PROBLEM: {problem.id} - {problem.name}")
+        print(f"Difficulty: {problem.difficulty.value.upper()}")
+        print(f"Category: {problem.category.value}")
+        print(f"Expected qubits: {problem.expected.min_qubits}-{problem.expected.max_qubits}")
+        print(f"Required gates: {problem.expected.required_gates}")
+        print(f"Expected states: {problem.expected.expected_states}")
+        print("=" * 100)
+        
+        for mode in ['naked', 'guided', 'blackboard']:
+            print(f"\n--- {mode.upper()} MODE ---")
+            reset_cost_tracking()
+            
+            start = time.perf_counter()
+            result = None
+            qasm = None
+            
+            try:
+                orchestrator = create_orchestrator(mode)
+                result = orchestrator.run(problem.goal)
+                
+                elapsed = (time.perf_counter() - start) * 1000
+                cost = get_cost_summary()
+                
+                # Extract and validate QASM
+                qasm = extract_qasm(result)
+                validation = validate_qasm(qasm)
+                
+                success = result.success if result else False
+                errors = result.errors if result else []
+                
+                # Print detailed results
+                status = '✅' if success and validation['valid'] else '❌'
+                print(f"{status} Success: {success}")
+                print(f"   Time: {elapsed:.0f}ms")
+                print(f"   LLM Calls: {cost.get('total_requests', 0)}")
+                print(f"   Tokens: {cost.get('total_tokens', 0)}")
+                print(f"   QASM Valid: {validation['valid']}")
+                print(f"   Has qreg: {validation['has_qreg']}")
+                print(f"   Gate Count: {validation['gate_count']}")
+                print(f"   Est. Depth: {validation['depth']}")
+                
+                if errors:
+                    print(f"   ⚠️  Errors: {errors[:2]}")
+                
+                if qasm:
+                    # Show first few lines of QASM
+                    lines = qasm.split('\n')[:8]
+                    print("   QASM:")
+                    for line in lines:
+                        print(f"      {line}")
+                    if len(qasm.split('\n')) > 8:
+                        print("      ...")
+                else:
+                    print("   QASM: None generated")
+                
+                all_results.append({
+                    'problem_id': problem.id,
+                    'problem_name': problem.name,
+                    'difficulty': problem.difficulty.value,
+                    'category': problem.category.value,
+                    'mode': mode,
+                    'success': success and validation['valid'],
+                    'qasm_valid': validation['valid'],
+                    'time_ms': elapsed,
+                    'llm_calls': cost.get('total_requests', 0),
+                    'tokens': cost.get('total_tokens', 0),
+                    'gate_count': validation['gate_count'],
+                    'depth': validation['depth'],
+                    'qasm': qasm[:500] if qasm else None,
+                    'error': str(errors[0])[:100] if errors else None
+                })
+                
+            except Exception as e:
+                elapsed = (time.perf_counter() - start) * 1000
+                error_msg = f"{type(e).__name__}: {str(e)[:200]}"
+                print(f"❌ EXCEPTION: {error_msg}")
+                
+                import traceback
+                traceback.print_exc()
+                
+                all_results.append({
+                    'problem_id': problem.id,
+                    'problem_name': problem.name,
+                    'difficulty': problem.difficulty.value,
+                    'category': problem.category.value,
+                    'mode': mode,
+                    'success': False,
+                    'qasm_valid': False,
+                    'time_ms': elapsed,
+                    'llm_calls': 0,
+                    'tokens': 0,
+                    'gate_count': 0,
+                    'depth': 0,
+                    'qasm': None,
+                    'error': error_msg[:100]
+                })
+    
+    # Print final summary
+    print_summary(all_results)
+    
+    # Save results to JSON
+    output_path = Path(__file__).parent.parent / f"research/comprehensive_test_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+    output_path.parent.mkdir(exist_ok=True)
+    
+    import json
+    with open(output_path, 'w') as f:
+        json.dump(all_results, f, indent=2)
+    print(f"\n\nResults saved to: {output_path}")
+    
+    return all_results
+
+
+def print_summary(all_results):
+    """Print summary by difficulty and mode."""
+    
+    print("\n\n" + "=" * 100)
+    print("FINAL SUMMARY BY DIFFICULTY AND MODE")
+    print("=" * 100)
+    
+    for diff in ['easy', 'medium', 'hard']:
+        print(f"\n{diff.upper()} PROBLEMS:")
+        print("-" * 80)
+        
+        for mode in ['naked', 'guided', 'blackboard']:
+            mode_results = [r for r in all_results if r['difficulty'] == diff and r['mode'] == mode]
+            if mode_results:
+                successes = sum(1 for r in mode_results if r['success'])
+                total = len(mode_results)
+                avg_time = sum(r['time_ms'] for r in mode_results) / total
+                total_llm = sum(r['llm_calls'] for r in mode_results)
+                avg_gates = sum(r['gate_count'] for r in mode_results) / total
+                
+                status = '✅' if successes == total else '⚠️ ' if successes > 0 else '❌'
+                print(f"{status} {mode:12} | Success: {successes}/{total} | Time: {avg_time:>6.0f}ms | LLM: {total_llm:>2} | Avg Gates: {avg_gates:.1f}")
+                
+                # Show failures
+                failures = [r for r in mode_results if not r['success']]
+                for f in failures:
+                    error_msg = f['error'][:60] if f['error'] else 'No QASM generated'
+                    print(f"      ❌ {f['problem_id']}: {error_msg}")
+    
+    # Calculate winners
+    print("\n\n" + "=" * 100)
+    print("🏆 WINNER BY DIFFICULTY (Score = Success*100 - Time/1000 - LLM*0.5)")
+    print("=" * 100)
+    
+    for diff in ['easy', 'medium', 'hard']:
+        print(f"\n{diff.upper()}:")
+        best_mode = None
+        best_score = -999
+        
+        for mode in ['naked', 'guided', 'blackboard']:
+            mode_results = [r for r in all_results if r['difficulty'] == diff and r['mode'] == mode]
+            if mode_results:
+                successes = sum(1 for r in mode_results if r['success'])
+                total = len(mode_results)
+                avg_time = sum(r['time_ms'] for r in mode_results) / total
+                total_llm = sum(r['llm_calls'] for r in mode_results)
+                
+                success_rate = successes / total
+                time_penalty = avg_time / 1000
+                llm_penalty = total_llm * 0.5
+                score = success_rate * 100 - time_penalty - llm_penalty
+                
+                print(f"  {mode:12}: Score={score:>6.1f} (Success={success_rate*100:.0f}%, Time={avg_time:.0f}ms, LLM={total_llm})")
+                
+                if score > best_score:
+                    best_score = score
+                    best_mode = mode
+        
+        print(f"  🏆 WINNER: {best_mode.upper() if best_mode else 'NONE'}")
+    
+    # Overall recommendation
+    print("\n\n" + "=" * 100)
+    print("OVERALL RECOMMENDATIONS")
+    print("=" * 100)
+    
+    # Calculate overall stats per mode
+    for mode in ['naked', 'guided', 'blackboard']:
+        mode_results = [r for r in all_results if r['mode'] == mode]
+        if mode_results:
+            successes = sum(1 for r in mode_results if r['success'])
+            total = len(mode_results)
+            avg_time = sum(r['time_ms'] for r in mode_results) / total
+            total_llm = sum(r['llm_calls'] for r in mode_results)
+            avg_gates = sum(r['gate_count'] for r in mode_results) / total
+            
+            print(f"\n{mode.upper()}:")
+            print(f"  Overall Success: {successes}/{total} ({100*successes/total:.0f}%)")
+            print(f"  Average Time: {avg_time:.0f}ms")
+            print(f"  Total LLM Calls: {total_llm}")
+            print(f"  Average Gates: {avg_gates:.1f}")
+            
+            # List failures
+            failures = [r for r in mode_results if not r['success']]
+            if failures:
+                print(f"  Failures ({len(failures)}):")
+                for f in failures:
+                    print(f"    - {f['problem_id']} ({f['difficulty']}): {f['error'][:50] if f['error'] else 'Unknown'}")
+
+
+if __name__ == "__main__":
+    run_comprehensive_test()

tests/comprehensive_test_v2.py

@@ -0,0 +1,299 @@
+# Path: QAgents-workflos/tests/comprehensive_test_v2.py
+# Relations: Uses orchestrators, test_problems, client/mcp_client
+# Description: Full diagnostic test comparing all 5 modes including QUASAR and HYBRID
+"""
+Comprehensive Test V2: Compare all orchestration modes
+
+Modes tested:
+1. NAKED - Direct LLM (baseline)
+2. GUIDED - Multi-agent pipeline  
+3. BLACKBOARD - Event-driven agents
+4. QUASAR - Tool-augmented LLM with hierarchical validation
+5. HYBRID - NAKED first, QUASAR fallback
+
+Problems:
+- 3 EASY
+- 3 MEDIUM  
+- 3 HARD
+- 4 VERY_HARD (new - to find NAKED limits)
+"""
+
+import sys
+import os
+import json
+import time
+from datetime import datetime
+from pathlib import Path
+
+# Setup paths
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+# Set API key BEFORE any imports
+api_key = os.getenv('GOOGLE_API_KEY')
+if not api_key:
+    api_key = "$env:GOOGLE_API_KEY"
+    os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import (
+    ALL_PROBLEMS, EASY_PROBLEMS, MEDIUM_PROBLEMS, 
+    HARD_PROBLEMS, VERY_HARD_PROBLEMS,
+    ProblemDifficulty
+)
+from orchestrators import create_orchestrator
+from orchestrators.quasar_orchestrator import QuasarOrchestrator, HybridOrchestrator
+from config import reset_cost_tracking, get_cost_summary, set_api_key
+from client.mcp_client import get_client
+
+# Set API key in config
+set_api_key(api_key)
+
+
+def extract_qasm_metrics(qasm: str) -> dict:
+    """Extract metrics from QASM code."""
+    if not qasm:
+        return {"gate_count": 0, "depth": 0, "qubits": 0}
+    
+    import re
+    
+    # Count qubits
+    qreg_match = re.search(r'qreg\s+\w+\[(\d+)\]', qasm)
+    qubits = int(qreg_match.group(1)) if qreg_match else 0
+    
+    # Count gates (excluding declarations and measurements)
+    gate_pattern = r'\b(h|x|y|z|s|t|sdg|tdg|cx|cz|cy|swap|ccx|rz|rx|ry|u1|u2|u3|p|cp)\b'
+    gates = re.findall(gate_pattern, qasm, re.IGNORECASE)
+    
+    # Estimate depth (simplified)
+    lines = [l.strip() for l in qasm.split('\n') if l.strip() and not l.strip().startswith(('OPENQASM', 'include', 'qreg', 'creg', '//'))]
+    depth = len([l for l in lines if any(g in l.lower() for g in ['h ', 'x ', 'y ', 'z ', 'cx', 'cz', 'swap', 'rx', 'ry', 'rz', 'ccx'])])
+    
+    return {"gate_count": len(gates), "depth": depth, "qubits": qubits}
+
+
+def run_test(problem, mode: str) -> dict:
+    """Run a single test and return results."""
+    result = {
+        "problem_id": problem.id,
+        "problem_name": problem.name,
+        "difficulty": problem.difficulty.value,
+        "category": problem.category.value,
+        "mode": mode,
+        "success": False,
+        "qasm_valid": False,
+        "time_ms": 0,
+        "llm_calls": 0,
+        "tokens": 0,
+        "gate_count": 0,
+        "depth": 0,
+        "qasm": None,
+        "error": None,
+        "tiers_passed": [],
+        "iterations": 0
+    }
+    
+    start = time.perf_counter()
+    reset_cost_tracking()
+    
+    try:
+        if mode in ["quasar", "hybrid"]:
+            # Use new orchestrators with expected values
+            if mode == "quasar":
+                orchestrator = QuasarOrchestrator(max_iterations=3)
+            else:
+                orchestrator = HybridOrchestrator()
+            
+            quasar_result = orchestrator.run(
+                goal=problem.prompt,
+                expected_qubits=problem.expected.min_qubits,
+                expected_states=problem.expected.expected_states if problem.expected.expected_states else None,
+                max_depth=problem.expected.max_depth
+            )
+            
+            result["success"] = quasar_result.success
+            result["qasm"] = quasar_result.final_qasm
+            result["llm_calls"] = quasar_result.llm_calls
+            result["tokens"] = quasar_result.tokens_used
+            result["tiers_passed"] = quasar_result.tiers_passed
+            result["iterations"] = quasar_result.iterations
+            
+            if quasar_result.final_qasm:
+                result["qasm_valid"] = True
+                metrics = extract_qasm_metrics(quasar_result.final_qasm)
+                result["gate_count"] = metrics["gate_count"]
+                result["depth"] = metrics["depth"]
+            
+            if quasar_result.errors:
+                result["error"] = "; ".join(quasar_result.errors)
+                
+        else:
+            # Use standard orchestrators
+            orchestrator = create_orchestrator(mode)
+            orch_result = orchestrator.run(problem.prompt)
+            
+            result["success"] = orch_result.success
+            result["qasm"] = orch_result.final_output
+            
+            # Get LLM stats
+            cost = get_cost_summary()
+            result["llm_calls"] = cost.get("llm_requests", 0)
+            result["tokens"] = cost.get("total_tokens", 0)
+            
+            if orch_result.final_output:
+                result["qasm_valid"] = True
+                metrics = extract_qasm_metrics(orch_result.final_output)
+                result["gate_count"] = metrics["gate_count"]
+                result["depth"] = metrics["depth"]
+            
+            if orch_result.errors:
+                result["error"] = "; ".join(orch_result.errors)
+                
+    except Exception as e:
+        result["error"] = str(e)
+        
+    result["time_ms"] = (time.perf_counter() - start) * 1000
+    return result
+
+
+def main():
+    print("=" * 100)
+    print("COMPREHENSIVE TEST V2 - ALL MODES INCLUDING QUASAR & HYBRID")
+    print("=" * 100)
+    print(f"Date: {datetime.now().isoformat()}")
+    print(f"Problems: {len(ALL_PROBLEMS)} total")
+    print(f"  - Easy: {len(EASY_PROBLEMS)}")
+    print(f"  - Medium: {len(MEDIUM_PROBLEMS)}")
+    print(f"  - Hard: {len(HARD_PROBLEMS)}")
+    print(f"  - Very Hard: {len(VERY_HARD_PROBLEMS)}")
+    print(f"Modes: naked, guided, blackboard, quasar, hybrid")
+    print("=" * 100)
+    
+    # Check MCP server
+    try:
+        client = get_client()
+        if client.health_check():
+            print("✅ MCP Server connected")
+        else:
+            print("⚠️ MCP Server not responding - some validations may use fallback")
+    except:
+        print("⚠️ MCP Server not available")
+    
+    all_results = []
+    modes = ["naked", "quasar", "hybrid", "guided", "blackboard"]  # Order: fastest to slowest
+    
+    # Group problems by difficulty
+    problem_groups = [
+        ("EASY", EASY_PROBLEMS),
+        ("MEDIUM", MEDIUM_PROBLEMS),
+        ("HARD", HARD_PROBLEMS),
+        ("VERY_HARD", VERY_HARD_PROBLEMS)
+    ]
+    
+    for diff_name, problems in problem_groups:
+        print(f"\n{'='*100}")
+        print(f"DIFFICULTY: {diff_name}")
+        print("=" * 100)
+        
+        for problem in problems:
+            print(f"\n--- Problem: {problem.id} - {problem.name} ---")
+            
+            for mode in modes:
+                print(f"  Testing {mode}...", end=" ", flush=True)
+                
+                result = run_test(problem, mode)
+                all_results.append(result)
+                
+                status = "✅" if result["success"] else "❌"
+                time_str = f"{result['time_ms']:.0f}ms"
+                llm_str = f"LLM:{result['llm_calls']}"
+                gates_str = f"Gates:{result['gate_count']}"
+                
+                extra = ""
+                if mode in ["quasar", "hybrid"]:
+                    tiers = result.get("tiers_passed", [])
+                    extra = f" Tiers:{tiers}"
+                
+                print(f"{status} {time_str} {llm_str} {gates_str}{extra}")
+                
+                if result["error"] and not result["success"]:
+                    print(f"    Error: {result['error'][:80]}...")
+                
+                # Rate limiting
+                time.sleep(5)
+    
+    # Summary
+    print("\n\n" + "=" * 100)
+    print("FINAL SUMMARY BY MODE")
+    print("=" * 100)
+    
+    for mode in modes:
+        mode_results = [r for r in all_results if r["mode"] == mode]
+        successes = sum(1 for r in mode_results if r["success"])
+        total = len(mode_results)
+        total_time = sum(r["time_ms"] for r in mode_results)
+        total_llm = sum(r["llm_calls"] for r in mode_results)
+        avg_gates = sum(r["gate_count"] for r in mode_results if r["success"]) / max(successes, 1)
+        
+        print(f"\n{mode.upper()}:")
+        print(f"  Success: {successes}/{total} ({100*successes/total:.1f}%)")
+        print(f"  Total Time: {total_time:.0f}ms ({total_time/total:.0f}ms avg)")
+        print(f"  LLM Calls: {total_llm} ({total_llm/total:.1f} avg)")
+        print(f"  Avg Gates (success): {avg_gates:.1f}")
+        
+        # Per difficulty
+        for diff in ["easy", "medium", "hard", "very_hard"]:
+            diff_results = [r for r in mode_results if r["difficulty"] == diff]
+            if diff_results:
+                diff_success = sum(1 for r in diff_results if r["success"])
+                print(f"    {diff}: {diff_success}/{len(diff_results)}")
+    
+    # Efficiency comparison
+    print("\n" + "=" * 100)
+    print("EFFICIENCY COMPARISON (Success per LLM call)")
+    print("=" * 100)
+    
+    for mode in modes:
+        mode_results = [r for r in all_results if r["mode"] == mode]
+        successes = sum(1 for r in mode_results if r["success"])
+        total_llm = sum(r["llm_calls"] for r in mode_results)
+        efficiency = successes / max(total_llm, 1)
+        print(f"  {mode}: {efficiency:.3f} successes per LLM call")
+    
+    # Winner determination
+    print("\n" + "=" * 100)
+    print("WINNER BY DIFFICULTY")
+    print("=" * 100)
+    
+    for diff in ["easy", "medium", "hard", "very_hard"]:
+        print(f"\n{diff.upper()}:")
+        best_mode = None
+        best_success = -1
+        best_efficiency = -1
+        
+        for mode in modes:
+            mode_results = [r for r in all_results if r["mode"] == mode and r["difficulty"] == diff]
+            if mode_results:
+                successes = sum(1 for r in mode_results if r["success"])
+                total_llm = sum(r["llm_calls"] for r in mode_results)
+                efficiency = successes / max(total_llm, 1)
+                
+                if successes > best_success or (successes == best_success and efficiency > best_efficiency):
+                    best_success = successes
+                    best_efficiency = efficiency
+                    best_mode = mode
+        
+        if best_mode:
+            print(f"  🏆 Winner: {best_mode.upper()} ({best_success} successes)")
+    
+    # Save results
+    output_path = Path(__file__).parent.parent / "research" / f"comprehensive_test_v2_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(output_path, 'w') as f:
+        json.dump(all_results, f, indent=2)
+    
+    print(f"\n\nResults saved to: {output_path}")
+    print("=" * 100)
+
+
+if __name__ == "__main__":
+    main()

tests/evaluation_harness.py

@@ -0,0 +1,748 @@
+# Path: QAgents-workflos/tests/evaluation_harness.py
+# Relations: Uses orchestrators, tools, database, config modules
+#            Uses agents/llm_adapter.py for LLM usage tracking
+# Description: Evaluation harness for comparative testing of Blackboard, Guided, and Naked modes
+#              Includes cost tracking (requests, tokens, time) for each mode
+#              Exports results to CSV for research analysis
+"""
+Evaluation Harness: Measure time, quality, effectiveness, reliability.
+Runs comparative tests across Blackboard, Guided, and Naked modes.
+
+COST TRACKING METRICS:
+======================
+For each mode, tracks:
+  - LLM requests: Number of calls to LLM API
+  - Tokens used: Total tokens consumed (input + output)
+  - Time: Total execution time
+  - Quality: Circuit correctness and complexity scores
+  
+MODES:
+======
+  - Naked: Direct LLM (1 call/problem) - baseline test
+  - Guided: Structured workflow (4 LLM calls/problem)
+  - Blackboard: Free-form collaboration (8-12 LLM calls/problem)
+
+OUTPUT FORMATS:
+===============
+  - TXT: Human-readable report
+  - CSV: Research data for longitudinal analysis
+"""
+
+import time
+import json
+import csv
+import statistics
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+from pathlib import Path
+import logging
+
+from .test_problems import TestProblem, ALL_PROBLEMS, get_problem
+from database import get_database, ResultEntry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MetricResult:
+    """Result for a single metric."""
+    name: str
+    value: float
+    unit: str
+    passed: bool = True
+    details: str = ""
+
+
+@dataclass
+class CostMetrics:
+    """Cost metrics for a single run."""
+    llm_requests: int = 0
+    mcp_requests: int = 0
+    tokens_used: int = 0
+    time_ms: float = 0.0
+    models_used: List[str] = field(default_factory=list)
+    
+    def cost_per_quality(self, quality_score: float) -> float:
+        """Calculate cost-per-quality ratio (lower is better)."""
+        if quality_score <= 0:
+            return float('inf')
+        # Cost = (requests * 1) + (tokens / 1000) + (time_ms / 1000)
+        cost = self.llm_requests + (self.tokens_used / 1000) + (self.time_ms / 1000)
+        return cost / quality_score
+
+
+@dataclass
+class EvaluationResult:
+    """Result of evaluating a single run."""
+    problem_id: str
+    system_mode: str
+    run_number: int
+    success: bool
+    execution_time_ms: float
+    circuit_qasm: Optional[str]
+    metrics: Dict[str, MetricResult] = field(default_factory=dict)
+    cost_metrics: CostMetrics = field(default_factory=CostMetrics)
+    errors: List[str] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class AggregatedResults:
+    """Aggregated results for a problem across all runs."""
+    problem_id: str
+    system_mode: str
+    num_runs: int
+    success_rate: float
+    avg_time_ms: float
+    std_time_ms: float
+    avg_quality_score: float
+    effectiveness: float
+    reliability: float
+    # Cost aggregates
+    total_llm_requests: int = 0
+    total_mcp_requests: int = 0
+    total_tokens: int = 0
+    avg_cost_per_quality: float = 0.0
+    all_results: List[EvaluationResult] = field(default_factory=list)
+
+
+class EvaluationHarness:
+    """
+    Runs comparative evaluations across different orchestration modes.
+    Measures: Time, Quality, Effectiveness, Reliability, Cost
+    """
+
+    def __init__(self, num_runs: int = 5, timeout_seconds: float = 120.0):
+        self.num_runs = num_runs
+        self.timeout_seconds = timeout_seconds
+        self.db = get_database()
+        self.results: Dict[str, Dict[str, AggregatedResults]] = {}
+        
+        # Track MCP requests per run
+        self._mcp_request_count = 0
+
+    def _reset_cost_tracking(self):
+        """Reset cost tracking before a run."""
+        try:
+            from config import reset_cost_tracking
+            reset_cost_tracking()
+        except Exception:
+            pass
+        self._mcp_request_count = 0
+    
+    def _get_cost_summary(self) -> Dict:
+        """Get cost tracking summary after a run."""
+        try:
+            from config import get_cost_summary
+            return get_cost_summary()
+        except Exception:
+            return {"total_requests": 0, "total_tokens": 0, "total_time_ms": 0.0}
+    
+    def _get_llm_usage_summary(self) -> Dict:
+        """Get LLM usage from rate limiter."""
+        try:
+            from agents.llm_adapter import get_usage_summary
+            return get_usage_summary()
+        except Exception:
+            return {}
+
+    def evaluate_single_run(self, problem: TestProblem, mode: str,
+                            run_number: int) -> EvaluationResult:
+        """Run a single evaluation with cost tracking."""
+        from orchestrators import create_orchestrator
+        from tools import invoke_tool
+
+        logger.info(f"Running {mode} on {problem.id}, run {run_number}")
+
+        # Reset cost tracking
+        self._reset_cost_tracking()
+        
+        errors = []
+        circuit_qasm = None
+        metrics = {}
+        success = False
+        cost_metrics = CostMetrics()
+
+        start_time = time.perf_counter()
+
+        try:
+            # Create and run orchestrator
+            orchestrator = create_orchestrator(mode)
+            result = orchestrator.run(problem.goal)
+
+            circuit_qasm = result.final_output
+
+            # Handle list responses from MCP
+            if isinstance(circuit_qasm, list):
+                circuit_qasm = circuit_qasm[0] if circuit_qasm else None
+
+            # Ensure it's a string or None
+            if circuit_qasm is not None:
+                circuit_qasm = str(circuit_qasm) if not isinstance(circuit_qasm, str) else circuit_qasm
+
+            success = result.success and circuit_qasm is not None
+
+            if not success:
+                errors.extend(result.errors)
+
+        except Exception as e:
+            success = False
+            errors.append(str(e))
+            logger.error(f"Evaluation failed: {e}")
+
+        elapsed_ms = (time.perf_counter() - start_time) * 1000
+
+        # Collect cost metrics
+        cost_summary = self._get_cost_summary()
+        llm_usage = self._get_llm_usage_summary()
+        
+        cost_metrics = CostMetrics(
+            llm_requests=cost_summary.get("total_requests", 0),
+            mcp_requests=self._mcp_request_count,
+            tokens_used=cost_summary.get("total_tokens", 0),
+            time_ms=elapsed_ms,
+            models_used=list(cost_summary.get("model_breakdown", {}).keys())
+        )
+
+        # Calculate metrics if we have a circuit
+        if circuit_qasm:
+            metrics = self._calculate_metrics(circuit_qasm, problem)
+
+        return EvaluationResult(
+            problem_id=problem.id,
+            system_mode=mode,
+            run_number=run_number,
+            success=success,
+            execution_time_ms=elapsed_ms,
+            circuit_qasm=circuit_qasm,
+            metrics=metrics,
+            cost_metrics=cost_metrics,
+            errors=errors
+        )
+
+    def _calculate_metrics(self, qasm: str, problem: TestProblem) -> Dict[str, MetricResult]:
+        """Calculate quality metrics for a circuit."""
+        from tools import invoke_tool
+
+        metrics = {}
+
+        try:
+            # Helper to extract value from potentially nested result
+            def extract_value(result, key, default=0):
+                val = result.get(key, default)
+                if isinstance(val, dict):
+                    return val.get('depth', val.get('value', val.get('score', default)))
+                elif isinstance(val, list):
+                    return val[0] if val else default
+                return val
+
+            # 1. Depth metric
+            self._mcp_request_count += 1
+            depth_result = invoke_tool("get_circuit_depth", qasm=qasm)
+            if depth_result.get("success"):
+                depth = extract_value(depth_result, "depth", 0)
+                if isinstance(depth, dict):
+                    depth = depth.get('depth', 0)
+                max_depth = problem.expected.max_depth or 100
+                passed = depth <= max_depth if max_depth else True
+                metrics["depth"] = MetricResult(
+                    name="Circuit Depth",
+                    value=float(depth) if depth else 0,
+                    unit="layers",
+                    passed=passed,
+                    details=f"Expected max: {max_depth}"
+                )
+
+            # 2. Complexity score
+            self._mcp_request_count += 1
+            complexity_result = invoke_tool("calculate_complexity", qasm=qasm)
+            if complexity_result.get("success"):
+                score = complexity_result.get("score", {})
+                if isinstance(score, dict):
+                    complexity_value = score.get("complexity_score", score.get("total", 0))
+                elif isinstance(score, list):
+                    complexity_value = 0
+                else:
+                    complexity_value = float(score) if score else 0
+                metrics["complexity"] = MetricResult(
+                    name="Complexity Score",
+                    value=float(complexity_value) if complexity_value else 0,
+                    unit="score",
+                    passed=True
+                )
+
+            # 3. Hardware fitness
+            self._mcp_request_count += 1
+            fitness_result = invoke_tool("calculate_hardware_fitness", qasm=qasm)
+            if fitness_result.get("success"):
+                score = fitness_result.get("score", {})
+                if isinstance(score, dict):
+                    fitness_value = score.get("fitness_score", score.get("fitness", 0))
+                elif isinstance(score, list):
+                    fitness_value = 0
+                else:
+                    fitness_value = float(score) if score else 0
+                metrics["hardware_fitness"] = MetricResult(
+                    name="Hardware Fitness",
+                    value=float(fitness_value) if fitness_value else 0,
+                    unit="score",
+                    passed=fitness_value > 0.5 if fitness_value else False
+                )
+
+            # 4. Validation
+            self._mcp_request_count += 1
+            validation_result = invoke_tool("validate_syntax", qasm=qasm)
+            valid_data = validation_result.get("valid", False)
+            # Handle list or complex response
+            if isinstance(valid_data, list):
+                valid = "valid" in str(valid_data).lower() or "✅" in str(valid_data)
+            elif isinstance(valid_data, dict):
+                valid = valid_data.get("valid", False)
+            else:
+                valid = bool(valid_data) and validation_result.get("success", False)
+            metrics["syntax_valid"] = MetricResult(
+                name="Syntax Validation",
+                value=1.0 if valid else 0.0,
+                unit="boolean",
+                passed=valid
+            )
+
+            # 5. Simulation correctness (if expected states defined)
+            if problem.expected.expected_states:
+                self._mcp_request_count += 1
+                prob_result = invoke_tool("get_probabilities", qasm=qasm)
+                if prob_result.get("success"):
+                    probs = prob_result.get("probabilities", {})
+                    if isinstance(probs, dict):
+                        correctness = self._check_state_correctness(probs, problem.expected.expected_states)
+                    else:
+                        correctness = 0.5  # Default if can't parse
+                    metrics["state_correctness"] = MetricResult(
+                        name="State Correctness",
+                        value=correctness,
+                        unit="ratio",
+                        passed=correctness > 0.9
+                    )
+
+        except Exception as e:
+            logger.error(f"Metric calculation failed: {e}")
+
+        return metrics
+
+    def _check_state_correctness(self, actual: Dict[str, float],
+                                 expected: Dict[str, float]) -> float:
+        """Check how close actual probabilities are to expected."""
+        if not expected:
+            return 1.0
+
+        total_error = 0.0
+        for state, expected_prob in expected.items():
+            actual_prob = actual.get(state, 0.0)
+            total_error += abs(expected_prob - actual_prob)
+
+        # Normalize to 0-1 range (0 = perfect, 1 = worst)
+        max_error = 2.0  # Maximum possible error
+        correctness = 1.0 - (total_error / max_error)
+        return max(0.0, correctness)
+
+    def aggregate_results(self, results: List[EvaluationResult]) -> AggregatedResults:
+        """Aggregate multiple run results with cost metrics."""
+        if not results:
+            return AggregatedResults(
+                problem_id="",
+                system_mode="",
+                num_runs=0,
+                success_rate=0.0,
+                avg_time_ms=0.0,
+                std_time_ms=0.0,
+                avg_quality_score=0.0,
+                effectiveness=0.0,
+                reliability=0.0
+            )
+
+        problem_id = results[0].problem_id
+        system_mode = results[0].system_mode
+        num_runs = len(results)
+
+        # Success rate
+        successes = sum(1 for r in results if r.success)
+        success_rate = successes / num_runs
+
+        # Time statistics
+        times = [r.execution_time_ms for r in results]
+        avg_time = statistics.mean(times)
+        std_time = statistics.stdev(times) if len(times) > 1 else 0.0
+
+        # Cost aggregates
+        total_llm = sum(r.cost_metrics.llm_requests for r in results)
+        total_mcp = sum(r.cost_metrics.mcp_requests for r in results)
+        total_tokens = sum(r.cost_metrics.tokens_used for r in results)
+
+        # Quality score (average of metric scores for successful runs)
+        quality_scores = []
+        cost_per_quality_scores = []
+        for r in results:
+            if r.success and r.metrics:
+                # Combine relevant metrics
+                scores = []
+                if "complexity" in r.metrics:
+                    # Invert complexity (lower is better)
+                    scores.append(1.0 - min(r.metrics["complexity"].value / 100, 1.0))
+                if "hardware_fitness" in r.metrics:
+                    scores.append(r.metrics["hardware_fitness"].value)
+                if "state_correctness" in r.metrics:
+                    scores.append(r.metrics["state_correctness"].value)
+                if scores:
+                    q_score = statistics.mean(scores)
+                    quality_scores.append(q_score)
+                    cost_per_quality_scores.append(r.cost_metrics.cost_per_quality(q_score))
+
+        avg_quality = statistics.mean(quality_scores) if quality_scores else 0.0
+        avg_cpq = statistics.mean(cost_per_quality_scores) if cost_per_quality_scores else float('inf')
+
+        # Effectiveness: Did we achieve the goal?
+        effective_runs = sum(
+            1 for r in results
+            if r.success and r.metrics.get("state_correctness", MetricResult("", 0, "")).value > 0.8
+        )
+        effectiveness = effective_runs / num_runs if num_runs > 0 else 0.0
+
+        # Reliability: Consistency of results (based on variance of success and quality)
+        reliability = success_rate * (1.0 - std_time / max(avg_time, 1.0))
+        reliability = max(0.0, min(1.0, reliability))
+
+        return AggregatedResults(
+            problem_id=problem_id,
+            system_mode=system_mode,
+            num_runs=num_runs,
+            success_rate=success_rate,
+            avg_time_ms=avg_time,
+            std_time_ms=std_time,
+            avg_quality_score=avg_quality,
+            effectiveness=effectiveness,
+            reliability=reliability,
+            total_llm_requests=total_llm,
+            total_mcp_requests=total_mcp,
+            total_tokens=total_tokens,
+            avg_cost_per_quality=avg_cpq,
+            all_results=results
+        )
+
+    def evaluate_problem(self, problem: TestProblem,
+                         modes: List[str] = None) -> Dict[str, AggregatedResults]:
+        """Evaluate a problem across all modes."""
+        if modes is None:
+            modes = ["blackboard", "guided", "naked"]
+
+        results_by_mode = {}
+
+        for mode in modes:
+            run_results = []
+
+            for run_num in range(1, self.num_runs + 1):
+                result = self.evaluate_single_run(problem, mode, run_num)
+                run_results.append(result)
+
+                # Store in database
+                self.db.store_result(ResultEntry(
+                    run_id=f"{problem.id}_{mode}_{run_num}",
+                    system_mode=mode,
+                    problem_id=problem.id,
+                    success=result.success,
+                    execution_time_ms=result.execution_time_ms,
+                    circuit_qasm=result.circuit_qasm,
+                    metrics={k: asdict(v) for k, v in result.metrics.items()}
+                ))
+
+            aggregated = self.aggregate_results(run_results)
+            results_by_mode[mode] = aggregated
+
+        return results_by_mode
+
+    def evaluate_all(self, problems: List[TestProblem] = None,
+                     modes: List[str] = None) -> Dict[str, Dict[str, AggregatedResults]]:
+        """Evaluate all problems across all modes."""
+        if problems is None:
+            problems = ALL_PROBLEMS
+        if modes is None:
+            modes = ["blackboard", "guided", "naked"]
+
+        all_results = {}
+
+        for problem in problems:
+            logger.info(f"Evaluating problem: {problem.name}")
+            all_results[problem.id] = self.evaluate_problem(problem, modes)
+
+        self.results = all_results
+        return all_results
+
+    def generate_report(self, output_path: Optional[Path] = None) -> str:
+        """Generate a comparison report with cost analysis."""
+        if not self.results:
+            return "No results to report. Run evaluate_all() first."
+
+        lines = [
+            "=" * 100,
+            "QUANTUM AGENT SYSTEM COMPARATIVE EVALUATION REPORT",
+            f"Generated: {datetime.now().isoformat()}",
+            f"Number of runs per problem: {self.num_runs}",
+            "=" * 100,
+            ""
+        ]
+
+        # Summary table with cost metrics
+        lines.append("SUMMARY BY MODE (with Cost Analysis)")
+        lines.append("-" * 100)
+        lines.append(f"{'Mode':<12} {'Success%':>9} {'Time(ms)':>10} {'Quality':>8} {'LLM Req':>8} {'Tokens':>10} {'Cost/Qual':>10}")
+        lines.append("-" * 100)
+
+        mode_totals = {
+            mode: {
+                "success": 0, "total": 0, "times": [], "quality": [],
+                "llm_req": 0, "mcp_req": 0, "tokens": 0, "cpq": []
+            }
+            for mode in ["blackboard", "guided", "naked"]
+        }
+
+        for problem_id, mode_results in self.results.items():
+            for mode, agg in mode_results.items():
+                mode_totals[mode]["success"] += agg.success_rate * agg.num_runs
+                mode_totals[mode]["total"] += agg.num_runs
+                mode_totals[mode]["times"].append(agg.avg_time_ms)
+                mode_totals[mode]["quality"].append(agg.avg_quality_score)
+                mode_totals[mode]["llm_req"] += agg.total_llm_requests
+                mode_totals[mode]["mcp_req"] += agg.total_mcp_requests
+                mode_totals[mode]["tokens"] += agg.total_tokens
+                if agg.avg_cost_per_quality != float('inf'):
+                    mode_totals[mode]["cpq"].append(agg.avg_cost_per_quality)
+
+        for mode, totals in mode_totals.items():
+            if totals["total"] > 0:
+                success_pct = (totals["success"] / totals["total"]) * 100
+                avg_time = statistics.mean(totals["times"]) if totals["times"] else 0
+                avg_quality = statistics.mean(totals["quality"]) if totals["quality"] else 0
+                avg_cpq = statistics.mean(totals["cpq"]) if totals["cpq"] else float('inf')
+                cpq_str = f"{avg_cpq:.2f}" if avg_cpq != float('inf') else "N/A"
+
+                lines.append(
+                    f"{mode:<12} {success_pct:>8.1f}% {avg_time:>9.0f} {avg_quality:>8.2f} "
+                    f"{totals['llm_req']:>8} {totals['tokens']:>10} {cpq_str:>10}"
+                )
+
+        lines.append("")
+        lines.append("")
+
+        # Cost efficiency analysis
+        lines.append("COST EFFICIENCY ANALYSIS")
+        lines.append("-" * 60)
+        lines.append("")
+        lines.append("Expected LLM Requests per problem:")
+        lines.append("  - Naked:      1 (single direct LLM call)")
+        lines.append("  - Guided:     4 (one per agent: Architect, Builder, Validator, Scorer)")
+        lines.append("  - Blackboard: 8-12 (multiple collaborative rounds)")
+        lines.append("")
+        lines.append("Cost-per-Quality interpretation:")
+        lines.append("  - Lower is better (less resources for same quality)")
+        lines.append("  - Naked has lowest cost but tests raw LLM capability")
+        lines.append("  - Blackboard has highest cost but best quality potential")
+        lines.append("")
+
+        # Detailed results per problem
+        lines.append("DETAILED RESULTS BY PROBLEM")
+        lines.append("-" * 100)
+
+        for problem_id, mode_results in self.results.items():
+            problem = get_problem(problem_id)
+            problem_name = problem.name if problem else problem_id
+
+            lines.append(f"\n{problem_name} ({problem_id})")
+            lines.append("-" * 50)
+            lines.append(f"{'Mode':<12} {'Success':>8} {'Time(ms)':>10} {'Quality':>8} {'LLM':>6} {'Tokens':>8}")
+
+            for mode, agg in mode_results.items():
+                lines.append(
+                    f"{mode:<12} "
+                    f"{agg.success_rate*100:>7.0f}% "
+                    f"{agg.avg_time_ms:>9.0f} "
+                    f"{agg.avg_quality_score:>8.2f} "
+                    f"{agg.total_llm_requests:>6} "
+                    f"{agg.total_tokens:>8}"
+                )
+
+        lines.append("")
+        lines.append("=" * 100)
+        lines.append("END OF REPORT")
+
+        report = "\n".join(lines)
+
+        if output_path:
+            output_path.write_text(report)
+            logger.info(f"Report saved to: {output_path}")
+
+        return report
+
+    def export_csv(self, output_path: Optional[Path] = None) -> str:
+        """
+        Export results to CSV for research analysis.
+        
+        CSV Columns:
+        - timestamp: When the evaluation was run
+        - problem_id: Unique problem identifier
+        - problem_name: Human-readable problem name
+        - difficulty: Problem difficulty (easy, medium, hard)
+        - mode: Execution mode (naked, guided, blackboard)
+        - run_number: Run iteration (1 to num_runs)
+        - success: Whether the run succeeded (True/False)
+        - time_ms: Execution time in milliseconds
+        - llm_requests: Number of LLM API calls
+        - tokens_used: Total tokens consumed
+        - mcp_requests: Number of MCP tool calls
+        - quality_score: Combined quality score (0-1)
+        - depth: Circuit depth
+        - complexity: Circuit complexity score
+        - hardware_fitness: Hardware compatibility score
+        - syntax_valid: Whether QASM syntax is valid
+        - state_correctness: Probability distribution correctness
+        - cost_per_quality: Cost efficiency ratio
+        - model_used: Primary LLM model used
+        - qasm_length: Length of generated QASM code
+        """
+        if not self.results:
+            return "No results to export. Run evaluate_all() first."
+
+        timestamp = datetime.now().isoformat()
+        
+        # Default output path
+        if output_path is None:
+            output_dir = Path(__file__).parent.parent / "research"
+            output_dir.mkdir(exist_ok=True)
+            output_path = output_dir / f"evaluation_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+
+        # CSV header
+        fieldnames = [
+            'timestamp', 'problem_id', 'problem_name', 'difficulty',
+            'mode', 'run_number', 'success', 'time_ms',
+            'llm_requests', 'tokens_used', 'mcp_requests',
+            'quality_score', 'depth', 'complexity', 'hardware_fitness',
+            'syntax_valid', 'state_correctness', 'cost_per_quality',
+            'model_used', 'qasm_length', 'errors'
+        ]
+
+        rows = []
+        
+        for problem_id, mode_results in self.results.items():
+            problem = get_problem(problem_id)
+            problem_name = problem.name if problem else problem_id
+            difficulty = problem.difficulty if problem else "unknown"
+            
+            for mode, agg in mode_results.items():
+                for result in agg.all_results:
+                    # Extract metric values safely
+                    def get_metric(name, default=0.0):
+                        if name in result.metrics:
+                            return result.metrics[name].value
+                        return default
+                    
+                    # Calculate quality score
+                    quality_components = []
+                    if "complexity" in result.metrics:
+                        quality_components.append(1.0 - min(get_metric("complexity") / 100, 1.0))
+                    if "hardware_fitness" in result.metrics:
+                        quality_components.append(get_metric("hardware_fitness"))
+                    if "state_correctness" in result.metrics:
+                        quality_components.append(get_metric("state_correctness"))
+                    quality_score = statistics.mean(quality_components) if quality_components else 0.0
+                    
+                    # Cost per quality
+                    cpq = result.cost_metrics.cost_per_quality(quality_score) if quality_score > 0 else float('inf')
+                    cpq_str = f"{cpq:.4f}" if cpq != float('inf') else "inf"
+                    
+                    # Model used
+                    models = result.cost_metrics.models_used
+                    model_used = models[0] if models else "unknown"
+                    
+                    # QASM length
+                    qasm_len = len(result.circuit_qasm) if result.circuit_qasm else 0
+                    
+                    row = {
+                        'timestamp': timestamp,
+                        'problem_id': problem_id,
+                        'problem_name': problem_name,
+                        'difficulty': difficulty,
+                        'mode': mode,
+                        'run_number': result.run_number,
+                        'success': result.success,
+                        'time_ms': f"{result.execution_time_ms:.2f}",
+                        'llm_requests': result.cost_metrics.llm_requests,
+                        'tokens_used': result.cost_metrics.tokens_used,
+                        'mcp_requests': result.cost_metrics.mcp_requests,
+                        'quality_score': f"{quality_score:.4f}",
+                        'depth': get_metric("depth"),
+                        'complexity': f"{get_metric('complexity'):.2f}",
+                        'hardware_fitness': f"{get_metric('hardware_fitness'):.4f}",
+                        'syntax_valid': get_metric("syntax_valid") == 1.0,
+                        'state_correctness': f"{get_metric('state_correctness'):.4f}",
+                        'cost_per_quality': cpq_str,
+                        'model_used': model_used,
+                        'qasm_length': qasm_len,
+                        'errors': "; ".join(result.errors) if result.errors else ""
+                    }
+                    rows.append(row)
+
+        # Write CSV
+        with open(output_path, 'w', newline='', encoding='utf-8') as f:
+            writer = csv.DictWriter(f, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(rows)
+
+        logger.info(f"CSV exported to: {output_path}")
+        return str(output_path)
+
+    def get_summary_stats(self) -> Dict[str, Any]:
+        """
+        Get summary statistics for the evaluation run.
+        Useful for programmatic access to results.
+        """
+        if not self.results:
+            return {}
+
+        stats = {
+            'timestamp': datetime.now().isoformat(),
+            'num_problems': len(self.results),
+            'runs_per_problem': self.num_runs,
+            'modes': {}
+        }
+
+        for mode in ['naked', 'guided', 'blackboard']:
+            mode_stats = {
+                'success_rate': 0.0,
+                'avg_time_ms': 0.0,
+                'total_llm_requests': 0,
+                'total_tokens': 0,
+                'avg_quality': 0.0
+            }
+            
+            times = []
+            qualities = []
+            total_runs = 0
+            successes = 0
+            
+            for problem_id, mode_results in self.results.items():
+                if mode in mode_results:
+                    agg = mode_results[mode]
+                    total_runs += agg.num_runs
+                    successes += agg.success_rate * agg.num_runs
+                    times.append(agg.avg_time_ms)
+                    qualities.append(agg.avg_quality_score)
+                    mode_stats['total_llm_requests'] += agg.total_llm_requests
+                    mode_stats['total_tokens'] += agg.total_tokens
+            
+            if total_runs > 0:
+                mode_stats['success_rate'] = successes / total_runs
+                mode_stats['avg_time_ms'] = statistics.mean(times) if times else 0
+                mode_stats['avg_quality'] = statistics.mean(qualities) if qualities else 0
+            
+            stats['modes'][mode] = mode_stats
+
+        return stats

tests/evaluation_report.txt

@@ -0,0 +1,54 @@
+====================================================================================================
+QUANTUM AGENT SYSTEM COMPARATIVE EVALUATION REPORT
+Generated: 2025-11-28T18:38:30.068424
+Number of runs per problem: 1
+====================================================================================================
+
+SUMMARY BY MODE (with Cost Analysis)
+----------------------------------------------------------------------------------------------------
+Mode          Success%   Time(ms)  Quality  LLM Req     Tokens  Cost/Qual
+----------------------------------------------------------------------------------------------------
+blackboard       66.7%     14612     0.00        5       2709        N/A
+guided          100.0%     23975     0.00        8       4481        N/A
+naked           100.0%      5251     0.00        3        901        N/A
+
+
+COST EFFICIENCY ANALYSIS
+------------------------------------------------------------
+
+Expected LLM Requests per problem:
+  - Naked:      1 (single direct LLM call)
+  - Guided:     4 (one per agent: Architect, Builder, Validator, Scorer)
+  - Blackboard: 8-12 (multiple collaborative rounds)
+
+Cost-per-Quality interpretation:
+  - Lower is better (less resources for same quality)
+  - Naked has lowest cost but tests raw LLM capability
+  - Blackboard has highest cost but best quality potential
+
+DETAILED RESULTS BY PROBLEM
+----------------------------------------------------------------------------------------------------
+
+Phase Flip State (easy_001)
+--------------------------------------------------
+Mode          Success   Time(ms)  Quality    LLM   Tokens
+blackboard       100%     11292     0.00      2      955
+guided           100%     31284     0.00      4     2177
+naked            100%      6894     0.00      1      293
+
+Entanglement Generation (easy_002)
+--------------------------------------------------
+Mode          Success   Time(ms)  Quality    LLM   Tokens
+blackboard         0%     16832     0.00      1      529
+guided           100%     20431     0.00      2     1046
+naked            100%      1929     0.00      1      305
+
+X-Basis Measurement Prep (easy_003)
+--------------------------------------------------
+Mode          Success   Time(ms)  Quality    LLM   Tokens
+blackboard       100%     15713     0.00      2     1225
+guided           100%     20209     0.00      2     1258
+naked            100%      6930     0.00      1      303
+
+====================================================================================================
+END OF REPORT

tests/fast_eval.py

@@ -0,0 +1,115 @@
+# Path: QAgents-workflos/tests/fast_eval.py
+# Fast evaluation - one problem per difficulty, all modes
+"""Fast mode evaluation."""
+
+import sys
+import os
+import time
+import json
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+api_key = "$env:GOOGLE_API_KEY"
+os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import (
+    PROBLEM_E1_PHASE_FLIP,
+    PROBLEM_M1_SWAP_DECOMPOSITION,
+    PROBLEM_H1_DEUTSCH,
+    PROBLEM_VH4_BERNSTEIN_VAZIRANI
+)
+from orchestrators import create_orchestrator
+from orchestrators.quasar_orchestrator import QuasarOrchestrator, HybridOrchestrator
+from config import set_api_key
+import re
+
+set_api_key(api_key)
+
+
+def extract_gates(qasm):
+    if not qasm:
+        return 0
+    gate_pattern = r'\b(h|x|y|z|s|t|cx|cz|swap|ccx|rz|rx|ry|cp)\b'
+    return len(re.findall(gate_pattern, qasm, re.IGNORECASE))
+
+
+def test_problem(problem, mode, timeout=60):
+    start = time.perf_counter()
+    
+    try:
+        if mode == "quasar":
+            orch = QuasarOrchestrator(max_iterations=3)
+            result = orch.run(problem.prompt, problem.expected.min_qubits)
+            return {"success": result.success, "time_ms": (time.perf_counter()-start)*1000, 
+                    "llm": result.llm_calls, "gates": extract_gates(result.final_qasm), "error": None}
+            
+        elif mode == "hybrid":
+            orch = HybridOrchestrator()
+            result = orch.run(problem.prompt, problem.expected.min_qubits)
+            return {"success": result.success, "time_ms": (time.perf_counter()-start)*1000,
+                    "llm": result.llm_calls, "gates": extract_gates(result.final_qasm), "error": None}
+            
+        else:
+            orch = create_orchestrator(mode)
+            result = orch.run(problem.prompt)
+            llm = 1 if mode == "naked" else len(result.agent_results) if result.agent_results else 0
+            return {"success": result.success, "time_ms": (time.perf_counter()-start)*1000,
+                    "llm": llm, "gates": extract_gates(result.final_output), "error": "; ".join(result.errors) if result.errors else None}
+            
+    except Exception as e:
+        return {"success": False, "time_ms": (time.perf_counter()-start)*1000, 
+                "llm": 0, "gates": 0, "error": str(e)[:60]}
+
+
+print("=" * 70)
+print("FAST MODE EVALUATION")
+print("=" * 70)
+print(f"Date: {datetime.now().isoformat()}")
+
+problems = [
+    ("EASY", PROBLEM_E1_PHASE_FLIP),
+    ("MEDIUM", PROBLEM_M1_SWAP_DECOMPOSITION),
+    ("HARD", PROBLEM_H1_DEUTSCH),
+    ("VERY_HARD", PROBLEM_VH4_BERNSTEIN_VAZIRANI)
+]
+
+modes = ["naked", "quasar", "hybrid", "blackboard"]
+all_results = {}
+
+for diff, problem in problems:
+    print(f"\n{diff}: {problem.name}")
+    print("-" * 50)
+    all_results[diff] = {}
+    
+    for mode in modes:
+        print(f"  {mode:12}", end=" ", flush=True)
+        result = test_problem(problem, mode)
+        all_results[diff][mode] = result
+        
+        status = "✅" if result["success"] else "❌"
+        print(f"{status} {result['time_ms']:5.0f}ms LLM:{result['llm']} Gates:{result['gates']}")
+        
+        if result["error"]:
+            print(f"             ⚠️ {result['error'][:40]}...")
+        
+        time.sleep(5)
+
+# Summary
+print("\n" + "=" * 70)
+print("SUMMARY")
+print("=" * 70)
+
+for mode in modes:
+    successes = sum(1 for diff in all_results if all_results[diff][mode]["success"])
+    total_time = sum(all_results[diff][mode]["time_ms"] for diff in all_results)
+    total_llm = sum(all_results[diff][mode]["llm"] for diff in all_results)
+    print(f"\n{mode.upper():12} {successes}/4 ({25*successes}%) | {total_time:.0f}ms | {total_llm} LLM calls")
+    for diff in all_results:
+        r = all_results[diff][mode]
+        status = "✅" if r["success"] else "❌"
+        print(f"  {diff:10} {status}")
+
+print("\n" + "=" * 70)
+print("DONE")

tests/final_eval.py

@@ -0,0 +1,137 @@
+# Path: QAgents-workflos/tests/final_eval.py
+# Final evaluation - NAKED vs BLACKBOARD on all difficulties
+"""Final mode evaluation: NAKED vs fixed BLACKBOARD."""
+
+import sys
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+api_key = "$env:GOOGLE_API_KEY"
+os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import ALL_PROBLEMS
+from orchestrators import create_orchestrator
+from config import set_api_key
+import re
+
+set_api_key(api_key)
+
+
+def extract_gates(qasm):
+    if not qasm:
+        return 0
+    gate_pattern = r'\b(h|x|y|z|s|t|cx|cz|swap|ccx|rz|rx|ry|cp)\b'
+    return len(re.findall(gate_pattern, qasm, re.IGNORECASE))
+
+
+def test_problem(problem, mode):
+    start = time.perf_counter()
+    
+    try:
+        orch = create_orchestrator(mode)
+        result = orch.run(problem.prompt)
+        
+        llm = 1 if mode == "naked" else len(result.agent_results) if result.agent_results else 0
+        
+        return {
+            "success": result.success, 
+            "time_ms": (time.perf_counter()-start)*1000,
+            "llm": llm, 
+            "gates": extract_gates(result.final_output),
+            "error": "; ".join(result.errors[:2]) if result.errors else None
+        }
+            
+    except Exception as e:
+        return {
+            "success": False, 
+            "time_ms": (time.perf_counter()-start)*1000, 
+            "llm": 0, 
+            "gates": 0, 
+            "error": str(e)[:60]
+        }
+
+
+print("=" * 80)
+print("FINAL MODE EVALUATION: NAKED vs BLACKBOARD")
+print("=" * 80)
+print(f"Date: {datetime.now().isoformat()}")
+print(f"Problems: {len(ALL_PROBLEMS)}")
+print()
+
+modes = ["naked", "blackboard"]
+results_by_difficulty = {"easy": {}, "medium": {}, "hard": {}, "very_hard": {}}
+
+for problem in ALL_PROBLEMS:
+    diff = problem.difficulty.value
+    print(f"\n{diff.upper()}: {problem.name}")
+    
+    if diff not in results_by_difficulty:
+        results_by_difficulty[diff] = {}
+    
+    for mode in modes:
+        print(f"  {mode:12}", end=" ", flush=True)
+        result = test_problem(problem, mode)
+        
+        if mode not in results_by_difficulty[diff]:
+            results_by_difficulty[diff][mode] = []
+        results_by_difficulty[diff][mode].append(result)
+        
+        status = "✅" if result["success"] else "❌"
+        print(f"{status} {result['time_ms']:5.0f}ms LLM:{result['llm']} Gates:{result['gates']}")
+        
+        if result["error"] and not result["success"]:
+            print(f"             ⚠️ {result['error'][:50]}...")
+        
+        time.sleep(4)
+
+# Summary
+print("\n\n" + "=" * 80)
+print("FINAL SUMMARY")
+print("=" * 80)
+
+for mode in modes:
+    print(f"\n{mode.upper()}")
+    print("-" * 40)
+    
+    total_success = 0
+    total_problems = 0
+    total_time = 0
+    total_llm = 0
+    
+    for diff in ["easy", "medium", "hard", "very_hard"]:
+        if diff in results_by_difficulty and mode in results_by_difficulty[diff]:
+            results = results_by_difficulty[diff][mode]
+            successes = sum(1 for r in results if r["success"])
+            total_success += successes
+            total_problems += len(results)
+            total_time += sum(r["time_ms"] for r in results)
+            total_llm += sum(r["llm"] for r in results)
+            
+            print(f"  {diff:10}: {successes}/{len(results)}")
+    
+    print(f"\n  TOTAL: {total_success}/{total_problems} ({100*total_success/total_problems:.0f}%)")
+    print(f"  Time: {total_time:.0f}ms total ({total_time/total_problems:.0f}ms avg)")
+    print(f"  LLM calls: {total_llm}")
+
+print("\n" + "=" * 80)
+print("WINNER DETERMINATION")
+print("=" * 80)
+
+for diff in ["easy", "medium", "hard", "very_hard"]:
+    if diff not in results_by_difficulty:
+        continue
+        
+    print(f"\n{diff.upper()}:")
+    for mode in modes:
+        if mode in results_by_difficulty[diff]:
+            results = results_by_difficulty[diff][mode]
+            successes = sum(1 for r in results if r["success"])
+            avg_time = sum(r["time_ms"] for r in results) / len(results)
+            print(f"  {mode}: {successes}/{len(results)} ({avg_time:.0f}ms avg)")
+
+print("\n" + "=" * 80)
+print("DONE")

tests/full_comparison.py

@@ -0,0 +1,214 @@
+# Path: QAgents-workflos/tests/full_comparison.py
+# Full comparison test across all modes and difficulties
+"""Full mode comparison test."""
+
+import sys
+import os
+import time
+import json
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+api_key = "$env:GOOGLE_API_KEY"
+os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import ALL_PROBLEMS, ProblemDifficulty
+from orchestrators import create_orchestrator
+from orchestrators.quasar_orchestrator import QuasarOrchestrator, HybridOrchestrator
+from config import set_api_key
+import re
+
+set_api_key(api_key)
+
+
+def extract_gates(qasm):
+    """Count gates in QASM."""
+    if not qasm:
+        return 0
+    gate_pattern = r'\b(h|x|y|z|s|t|cx|cz|swap|ccx|rz|rx|ry|cp)\b'
+    return len(re.findall(gate_pattern, qasm, re.IGNORECASE))
+
+
+def test_problem(problem, mode):
+    """Test a single problem."""
+    start = time.perf_counter()
+    
+    try:
+        if mode == "quasar":
+            orch = QuasarOrchestrator(max_iterations=3)
+            result = orch.run(
+                problem.prompt, 
+                problem.expected.min_qubits,
+                problem.expected.expected_states if problem.expected.expected_states else None
+            )
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+            iterations = result.iterations
+            tiers = result.tiers_passed
+            
+        elif mode == "hybrid":
+            orch = HybridOrchestrator()
+            result = orch.run(
+                problem.prompt, 
+                problem.expected.min_qubits,
+                problem.expected.expected_states if problem.expected.expected_states else None
+            )
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+            iterations = result.iterations
+            tiers = result.tiers_passed
+            
+        else:
+            orch = create_orchestrator(mode)
+            result = orch.run(problem.prompt)
+            success = result.success
+            qasm = result.final_output
+            llm = 1 if mode == "naked" else len(result.agent_results) if result.agent_results else 0
+            iterations = 1
+            tiers = []
+            
+        elapsed = (time.perf_counter() - start) * 1000
+        gates = extract_gates(qasm)
+        
+        return {
+            "success": success, 
+            "time_ms": elapsed, 
+            "llm": llm, 
+            "gates": gates,
+            "iterations": iterations,
+            "tiers": tiers,
+            "qasm": qasm,
+            "error": None
+        }
+        
+    except Exception as e:
+        elapsed = (time.perf_counter() - start) * 1000
+        return {
+            "success": False, 
+            "time_ms": elapsed, 
+            "llm": 0, 
+            "gates": 0,
+            "iterations": 0,
+            "tiers": [],
+            "qasm": None,
+            "error": str(e)[:100]
+        }
+
+
+def main():
+    print("=" * 100)
+    print("FULL MODE COMPARISON TEST")
+    print("=" * 100)
+    print(f"Date: {datetime.now().isoformat()}")
+    print(f"Total problems: {len(ALL_PROBLEMS)}")
+    print()
+    
+    # Modes to test - focus on the key ones
+    modes = ["naked", "quasar", "hybrid", "blackboard"]
+    
+    all_results = []
+    
+    # Group by difficulty
+    for difficulty in [ProblemDifficulty.EASY, ProblemDifficulty.MEDIUM, ProblemDifficulty.HARD, ProblemDifficulty.VERY_HARD]:
+        problems = [p for p in ALL_PROBLEMS if p.difficulty == difficulty]
+        
+        print(f"\n{'='*100}")
+        print(f"DIFFICULTY: {difficulty.value.upper()} ({len(problems)} problems)")
+        print("=" * 100)
+        
+        for problem in problems:
+            print(f"\n  {problem.id}: {problem.name}")
+            
+            for mode in modes:
+                print(f"    {mode:12}", end=" ", flush=True)
+                
+                result = test_problem(problem, mode)
+                result["problem_id"] = problem.id
+                result["difficulty"] = difficulty.value
+                result["mode"] = mode
+                all_results.append(result)
+                
+                status = "✅" if result["success"] else "❌"
+                time_str = f"{result['time_ms']:6.0f}ms"
+                llm_str = f"LLM:{result['llm']}"
+                gates_str = f"Gates:{result['gates']:2}"
+                
+                extra = ""
+                if result["tiers"]:
+                    extra = f" Tiers:{result['tiers']}"
+                
+                print(f"{status} {time_str} {llm_str:6} {gates_str}{extra}")
+                
+                if result["error"]:
+                    print(f"           ❌ Error: {result['error'][:60]}...")
+                
+                time.sleep(5)
+    
+    # Summary
+    print("\n\n" + "=" * 100)
+    print("SUMMARY BY MODE")
+    print("=" * 100)
+    
+    for mode in modes:
+        mode_results = [r for r in all_results if r["mode"] == mode]
+        successes = sum(1 for r in mode_results if r["success"])
+        total = len(mode_results)
+        total_time = sum(r["time_ms"] for r in mode_results)
+        total_llm = sum(r["llm"] for r in mode_results)
+        avg_gates = sum(r["gates"] for r in mode_results if r["success"]) / max(successes, 1)
+        
+        print(f"\n{mode.upper():12}")
+        print(f"  Overall: {successes}/{total} ({100*successes/total:.0f}%)")
+        print(f"  Time: {total_time/1000:.1f}s total, {total_time/total:.0f}ms avg")
+        print(f"  LLM: {total_llm} calls ({total_llm/total:.1f} avg)")
+        print(f"  Gates: {avg_gates:.1f} avg")
+        
+        # By difficulty
+        for diff in ["easy", "medium", "hard", "very_hard"]:
+            diff_results = [r for r in mode_results if r["difficulty"] == diff]
+            if diff_results:
+                diff_success = sum(1 for r in diff_results if r["success"])
+                print(f"    {diff:10}: {diff_success}/{len(diff_results)}")
+    
+    # Save results
+    output_path = Path(__file__).parent.parent / "research" / f"full_comparison_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Clean QASM for JSON (can be long)
+    for r in all_results:
+        if r["qasm"]:
+            r["qasm"] = r["qasm"][:500]  # Truncate for storage
+    
+    with open(output_path, 'w') as f:
+        json.dump(all_results, f, indent=2)
+    
+    print(f"\n\nResults saved to: {output_path}")
+    
+    # Winner determination
+    print("\n" + "=" * 100)
+    print("🏆 WINNER BY DIFFICULTY")
+    print("=" * 100)
+    
+    for diff in ["easy", "medium", "hard", "very_hard"]:
+        print(f"\n{diff.upper()}:")
+        best_mode = None
+        best_success = -1
+        
+        for mode in modes:
+            mode_results = [r for r in all_results if r["mode"] == mode and r["difficulty"] == diff]
+            if mode_results:
+                successes = sum(1 for r in mode_results if r["success"])
+                if successes > best_success:
+                    best_success = successes
+                    best_mode = mode
+        
+        if best_mode:
+            print(f"  🏆 {best_mode.upper()} ({best_success}/{len([r for r in all_results if r['difficulty']==diff and r['mode']==best_mode])})")
+
+
+if __name__ == "__main__":
+    main()

tests/mini_test.py

@@ -0,0 +1,75 @@
+# Path: QAgents-workflos/tests/mini_test.py
+# Description: Test all 4 modes on problems of each difficulty
+"""
+Mini Test: Comparison of NAKED, BLACKBOARD, GUIDED, HYBRID on 4 problems.
+"""
+
+import sys
+import os
+import warnings
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Suppress Gemini function_call warning (it's informational, not an error)
+warnings.filterwarnings("ignore", message=".*non-text parts.*")
+
+from orchestrators import create_orchestrator
+from tests.test_problems import get_problems_by_difficulty, ProblemDifficulty as Difficulty
+
+def test_one(problem, mode):
+    """Test a single problem with a mode."""
+    orch = create_orchestrator(mode)
+    import time
+    start = time.perf_counter()
+    result = orch.run(problem.prompt)
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    # Count gates
+    gates = 0
+    if result.final_output:
+        gates = len([l for l in result.final_output.split('\n') 
+                    if l.strip() and not l.startswith(('OPENQASM', 'include', 'qreg', 'creg', 'measure', '//'))])
+    
+    return result.success, elapsed, gates
+
+def main():
+    print("=" * 70)
+    print("COMPREHENSIVE TEST: NAKED vs BLACKBOARD vs GUIDED vs HYBRID")
+    print("=" * 70)
+    
+    # Test HARD problems to see where modes fail
+    modes = ["naked", "blackboard", "guided", "hybrid"]
+    
+    # One problem per difficulty
+    test_problems = [
+        ("EASY", get_problems_by_difficulty(Difficulty.EASY)[0]),
+        ("HARD", get_problems_by_difficulty(Difficulty.HARD)[0]),
+        ("VERY_HARD", get_problems_by_difficulty(Difficulty.VERY_HARD)[0]),
+    ]
+    
+    results = {mode: [] for mode in modes}
+    
+    for diff_name, problem in test_problems:
+        print(f"\n{diff_name}: {problem.name}")
+        print("-" * 50)
+        
+        for mode in modes:
+            try:
+                ok, ms, gates = test_one(problem, mode)
+                status = "✅" if ok else "❌"
+                print(f"  {mode:12} {status} {ms:6.0f}ms {gates:2} gates")
+                results[mode].append(ok)
+            except Exception as e:
+                print(f"  {mode:12} ❌ Error: {str(e)[:50]}")
+                results[mode].append(False)
+    
+    print("\n" + "=" * 70)
+    print("SUMMARY")
+    print("=" * 70)
+    for mode in modes:
+        passed = sum(results[mode])
+        total = len(results[mode])
+        pct = 100*passed/total if total > 0 else 0
+        print(f"  {mode:12}: {passed}/{total} passed ({pct:.0f}%)")
+
+if __name__ == "__main__":
+    main()

tests/mode_evaluation.py

@@ -0,0 +1,202 @@
+# Path: QAgents-workflos/tests/mode_evaluation.py
+# Evaluate all modes on representative problems from each difficulty
+"""Mode Evaluation: Test all modes on key problems from each difficulty level."""
+
+import sys
+import os
+import time
+import json
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+api_key = "$env:GOOGLE_API_KEY"
+os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import (
+    PROBLEM_E1_PHASE_FLIP, PROBLEM_E2_CONTROLLED_NOT,
+    PROBLEM_M1_SWAP_DECOMPOSITION, PROBLEM_M2_CONTROLLED_Z,
+    PROBLEM_H1_DEUTSCH, PROBLEM_H2_GROVER_2QUBIT,
+    PROBLEM_VH1_QFT_4QUBIT, PROBLEM_VH2_GROVER_3QUBIT, PROBLEM_VH4_BERNSTEIN_VAZIRANI
+)
+from orchestrators import create_orchestrator
+from orchestrators.quasar_orchestrator import QuasarOrchestrator, HybridOrchestrator
+from config import set_api_key
+import re
+
+set_api_key(api_key)
+
+
+def extract_gates(qasm):
+    """Count gates in QASM."""
+    if not qasm:
+        return 0
+    gate_pattern = r'\b(h|x|y|z|s|t|cx|cz|swap|ccx|rz|rx|ry|cp)\b'
+    return len(re.findall(gate_pattern, qasm, re.IGNORECASE))
+
+
+def test_problem(problem, mode):
+    """Test a single problem."""
+    start = time.perf_counter()
+    
+    try:
+        if mode == "quasar":
+            orch = QuasarOrchestrator(max_iterations=3)
+            result = orch.run(
+                problem.prompt, 
+                problem.expected.min_qubits,
+                problem.expected.expected_states if problem.expected.expected_states else None
+            )
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+            iterations = result.iterations
+            
+        elif mode == "hybrid":
+            orch = HybridOrchestrator()
+            result = orch.run(
+                problem.prompt, 
+                problem.expected.min_qubits,
+                problem.expected.expected_states if problem.expected.expected_states else None
+            )
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+            iterations = result.iterations
+            
+        else:
+            orch = create_orchestrator(mode)
+            result = orch.run(problem.prompt)
+            success = result.success
+            qasm = result.final_output
+            llm = 1 if mode == "naked" else len(result.agent_results) if result.agent_results else 0
+            iterations = 1
+            
+        elapsed = (time.perf_counter() - start) * 1000
+        gates = extract_gates(qasm)
+        
+        return {
+            "success": success, 
+            "time_ms": elapsed, 
+            "llm": llm, 
+            "gates": gates,
+            "iterations": iterations,
+            "error": None
+        }
+        
+    except Exception as e:
+        elapsed = (time.perf_counter() - start) * 1000
+        return {
+            "success": False, 
+            "time_ms": elapsed, 
+            "llm": 0, 
+            "gates": 0,
+            "error": str(e)[:80]
+        }
+
+
+def main():
+    print("=" * 80)
+    print("MODE EVALUATION - KEY PROBLEMS FROM EACH DIFFICULTY")
+    print("=" * 80)
+    print(f"Date: {datetime.now().isoformat()}")
+    print()
+    
+    # Key problems to test (2 per difficulty)
+    test_problems = [
+        ("EASY", [PROBLEM_E1_PHASE_FLIP, PROBLEM_E2_CONTROLLED_NOT]),
+        ("MEDIUM", [PROBLEM_M1_SWAP_DECOMPOSITION, PROBLEM_M2_CONTROLLED_Z]),
+        ("HARD", [PROBLEM_H1_DEUTSCH, PROBLEM_H2_GROVER_2QUBIT]),
+        ("VERY_HARD", [PROBLEM_VH1_QFT_4QUBIT, PROBLEM_VH2_GROVER_3QUBIT, PROBLEM_VH4_BERNSTEIN_VAZIRANI])
+    ]
+    
+    # Modes to test - focus on working ones
+    modes = ["naked", "quasar", "hybrid", "blackboard"]
+    
+    all_results = []
+    
+    for diff_name, problems in test_problems:
+        print(f"\n{'='*80}")
+        print(f"{diff_name} PROBLEMS")
+        print("=" * 80)
+        
+        for problem in problems:
+            print(f"\n  {problem.id}: {problem.name}")
+            
+            for mode in modes:
+                print(f"    {mode:12}", end=" ", flush=True)
+                
+                result = test_problem(problem, mode)
+                result["problem_id"] = problem.id
+                result["difficulty"] = diff_name.lower()
+                result["mode"] = mode
+                all_results.append(result)
+                
+                status = "✅" if result["success"] else "❌"
+                time_str = f"{result['time_ms']:6.0f}ms"
+                llm_str = f"LLM:{result['llm']}"
+                gates_str = f"Gates:{result['gates']:2}"
+                
+                print(f"{status} {time_str} {llm_str:6} {gates_str}")
+                
+                if result["error"]:
+                    print(f"           ⚠️ {result['error'][:50]}...")
+                
+                time.sleep(5)  # Rate limiting
+    
+    # Summary
+    print("\n\n" + "=" * 80)
+    print("SUMMARY BY MODE")
+    print("=" * 80)
+    
+    for mode in modes:
+        mode_results = [r for r in all_results if r["mode"] == mode]
+        successes = sum(1 for r in mode_results if r["success"])
+        total = len(mode_results)
+        total_time = sum(r["time_ms"] for r in mode_results)
+        total_llm = sum(r["llm"] for r in mode_results)
+        avg_gates = sum(r["gates"] for r in mode_results if r["success"]) / max(successes, 1)
+        
+        print(f"\n{mode.upper():12}")
+        print(f"  Success: {successes}/{total} ({100*successes/total:.0f}%)")
+        print(f"  Time: {total_time:.0f}ms total, {total_time/total:.0f}ms avg")
+        print(f"  LLM: {total_llm} calls")
+        print(f"  Gates: {avg_gates:.1f} avg")
+        
+        # By difficulty
+        for diff in ["easy", "medium", "hard", "very_hard"]:
+            diff_results = [r for r in mode_results if r["difficulty"] == diff]
+            if diff_results:
+                diff_success = sum(1 for r in diff_results if r["success"])
+                print(f"    {diff:10}: {diff_success}/{len(diff_results)}")
+    
+    # Winner by difficulty
+    print("\n" + "=" * 80)
+    print("🏆 WINNER BY DIFFICULTY")
+    print("=" * 80)
+    
+    for diff in ["easy", "medium", "hard", "very_hard"]:
+        diff_results = [r for r in all_results if r["difficulty"] == diff]
+        
+        print(f"\n{diff.upper()}:")
+        for mode in modes:
+            mode_diff_results = [r for r in diff_results if r["mode"] == mode]
+            if mode_diff_results:
+                successes = sum(1 for r in mode_diff_results if r["success"])
+                total_time = sum(r["time_ms"] for r in mode_diff_results)
+                avg_time = total_time / len(mode_diff_results)
+                print(f"  {mode:12} {successes}/{len(mode_diff_results)} ({avg_time:.0f}ms avg)")
+    
+    # Save results
+    output_path = Path(__file__).parent.parent / "research" / f"mode_evaluation_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(output_path, 'w') as f:
+        json.dump(all_results, f, indent=2)
+    
+    print(f"\n\nResults saved to: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

tests/quality_evaluation_harness.py

@@ -0,0 +1,314 @@
+# Path: QAgents-workflos/tests/quality_evaluation_harness.py
+# Relations: Uses orchestrators/, tests/circuit_quality_analyzer.py, database/circuit_quality_db.py
+# Description: Quality-focused evaluation harness that stores QASM circuits
+#              Runs all 3 modes, measures quality via MCP, stores in database
+#              Generates comparison reports with actual circuit outputs
+
+"""
+Quality Evaluation Harness: Run evaluations focused on CIRCUIT QUALITY.
+Key difference from regular harness: stores actual QASM and measures quality.
+"""
+
+import time
+import json
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+from pathlib import Path
+import uuid
+
+from .test_problems import TestProblem, ALL_PROBLEMS, get_problem, get_problems_by_difficulty, ProblemDifficulty
+from .circuit_quality_analyzer import CircuitQualityAnalyzer, AnalysisResult
+from database.circuit_quality_db import (
+    CircuitQualityDB, CircuitEvaluation, QualityMetrics, get_quality_db
+)
+
+logger = logging.getLogger(__name__)
+
+
+class QualityEvaluationHarness:
+    """
+    Runs quality-focused evaluations across all orchestration modes.
+    PRIMARY FOCUS: Circuit quality, not just success rate.
+    STORES: Full QASM code in database for later analysis.
+    """
+    
+    def __init__(self, mcp_url: str = "http://127.0.0.1:7861"):
+        self.mcp_url = mcp_url
+        self.analyzer = CircuitQualityAnalyzer(mcp_url)
+        self.db = get_quality_db()
+        self.run_id = f"quality_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    
+    def evaluate_single(self, problem: TestProblem, mode: str) -> CircuitEvaluation:
+        """
+        Run a single evaluation and return full CircuitEvaluation with QASM.
+        
+        Args:
+            problem: The test problem to solve
+            mode: 'naked', 'guided', or 'blackboard'
+        
+        Returns:
+            CircuitEvaluation with full QASM and quality metrics
+        """
+        from orchestrators import create_orchestrator
+        
+        logger.info(f"Evaluating {problem.id} with {mode} mode")
+        
+        # Reset cost tracking
+        try:
+            from config import reset_cost_tracking, get_cost_summary
+            reset_cost_tracking()
+        except ImportError:
+            get_cost_summary = lambda: {}
+        
+        # Initialize result
+        eval_result = CircuitEvaluation(
+            run_id=self.run_id,
+            timestamp=datetime.now().isoformat(),
+            problem_id=problem.id,
+            problem_goal=problem.goal,
+            mode=mode
+        )
+        
+        start_time = time.perf_counter()
+        
+        try:
+            # Create and run orchestrator
+            orchestrator = create_orchestrator(mode)
+            result = orchestrator.run(problem.goal)
+            
+            elapsed_ms = (time.perf_counter() - start_time) * 1000
+            eval_result.execution_time_ms = elapsed_ms
+            
+            # Extract QASM
+            qasm = result.final_output
+            if isinstance(qasm, list):
+                qasm = qasm[0] if qasm else None
+            if qasm is not None:
+                qasm = str(qasm) if not isinstance(qasm, str) else qasm
+            
+            eval_result.qasm_code = qasm or ""
+            eval_result.success = result.success and bool(qasm)
+            
+            if not eval_result.success:
+                eval_result.errors = result.errors
+            
+        except Exception as e:
+            elapsed_ms = (time.perf_counter() - start_time) * 1000
+            eval_result.execution_time_ms = elapsed_ms
+            eval_result.success = False
+            eval_result.errors = [str(e)]
+            logger.error(f"Evaluation failed for {problem.id}/{mode}: {e}")
+        
+        # Get cost metrics
+        try:
+            cost = get_cost_summary()
+            eval_result.llm_requests = cost.get('total_requests', 0)
+            eval_result.tokens_used = cost.get('total_tokens', 0)
+        except Exception:
+            pass
+        
+        # Analyze quality if we have QASM
+        if eval_result.qasm_code:
+            expected = problem.expected.expected_states if problem.expected else None
+            analysis = self.analyzer.analyze_circuit(eval_result.qasm_code, expected)
+            
+            eval_result.quality_metrics = QualityMetrics(
+                depth=analysis.depth,
+                gate_count=analysis.gate_count,
+                cx_count=analysis.cx_count,
+                single_qubit_count=analysis.single_qubit_count,
+                hardware_fitness=analysis.hardware_fitness,
+                syntax_valid=analysis.syntax_valid,
+                state_correctness=analysis.state_correctness,
+                complexity_score=analysis.complexity_score,
+                noise_estimate=analysis.noise_estimate
+            )
+            
+            if analysis.errors:
+                eval_result.errors.extend(analysis.errors)
+        
+        # Store in database
+        eval_id = self.db.save_evaluation(eval_result)
+        eval_result.id = eval_id
+        
+        logger.info(f"Stored evaluation {eval_id}: {problem.id}/{mode} - "
+                   f"success={eval_result.success}, score={eval_result.quality_metrics.overall_score()}")
+        
+        return eval_result
+    
+    def evaluate_problem_all_modes(self, problem: TestProblem, 
+                                   modes: List[str] = None) -> Dict[str, CircuitEvaluation]:
+        """Evaluate a single problem with all modes."""
+        if modes is None:
+            modes = ['naked', 'guided', 'blackboard']
+        
+        results = {}
+        for mode in modes:
+            results[mode] = self.evaluate_single(problem, mode)
+        
+        return results
+    
+    def run_full_evaluation(self, 
+                           difficulties: List[str] = None,
+                           modes: List[str] = None,
+                           max_problems: int = None) -> str:
+        """
+        Run full evaluation across problems and modes.
+        
+        Args:
+            difficulties: List of difficulties to test ('easy', 'medium', 'hard')
+            modes: List of modes to test ('naked', 'guided', 'blackboard')
+            max_problems: Maximum number of problems to test (for quick runs)
+        
+        Returns:
+            run_id for this evaluation run
+        """
+        if difficulties is None:
+            difficulties = ['easy', 'medium', 'hard']
+        if modes is None:
+            modes = ['naked', 'guided', 'blackboard']
+        
+        # Gather problems
+        all_probs = []
+        for diff in difficulties:
+            # Convert string to enum if needed
+            if isinstance(diff, str):
+                try:
+                    diff_enum = ProblemDifficulty(diff)
+                except ValueError:
+                    logger.warning(f"Invalid difficulty: {diff}")
+                    continue
+            else:
+                diff_enum = diff
+                
+            probs = get_problems_by_difficulty(diff_enum)
+            all_probs.extend(probs)
+        
+        if max_problems:
+            all_probs = all_probs[:max_problems]
+        
+        logger.info(f"Starting quality evaluation run {self.run_id}")
+        logger.info(f"Problems: {len(all_probs)}, Modes: {modes}")
+        
+        # Run evaluations
+        total = len(all_probs) * len(modes)
+        completed = 0
+        
+        for problem in all_probs:
+            for mode in modes:
+                try:
+                    self.evaluate_single(problem, mode)
+                    completed += 1
+                    logger.info(f"Progress: {completed}/{total}")
+                except Exception as e:
+                    logger.error(f"Failed {problem.id}/{mode}: {e}")
+                    completed += 1
+        
+        # Save run summary
+        summary = self.db.get_quality_summary(self.run_id)
+        self.db.save_comparison_run(
+            run_id=self.run_id,
+            description=f"Quality evaluation: {len(all_probs)} problems, {modes}",
+            num_problems=len(all_probs),
+            modes=modes,
+            summary=summary
+        )
+        
+        return self.run_id
+    
+    def generate_report(self, run_id: Optional[str] = None) -> str:
+        """Generate a comprehensive quality comparison report."""
+        if run_id is None:
+            run_id = self.run_id
+        
+        # Get summary
+        summary = self.db.get_quality_summary(run_id)
+        
+        # Get full circuit export
+        circuits_md = self.db.export_circuits_markdown(run_id)
+        
+        # Build report
+        report = []
+        report.append("# CIRCUIT QUALITY EVALUATION REPORT\n")
+        report.append(f"Run ID: {run_id}\n")
+        report.append(f"Generated: {datetime.now().isoformat()}\n\n")
+        
+        report.append("## EXECUTIVE SUMMARY\n\n")
+        
+        # Summary table
+        report.append("| Mode | Success Rate | Quality Score | Avg Depth | Avg Gates | Avg CX | HW Fitness | LLM Calls |\n")
+        report.append("|------|-------------|---------------|-----------|-----------|--------|------------|----------|\n")
+        
+        for mode in ['naked', 'guided', 'blackboard']:
+            if mode in summary.get('modes', {}):
+                m = summary['modes'][mode]
+                report.append(
+                    f"| {mode.upper()} | {m['success_rate']*100:.0f}% | "
+                    f"{m['avg_quality_score']:.1f}/100 | {m['avg_depth']:.1f} | "
+                    f"{m['avg_gates']:.1f} | {m['avg_cx_count']:.1f} | "
+                    f"{m['avg_hardware_fitness']:.3f} | {m['total_llm_requests']} |\n"
+                )
+        
+        report.append("\n## KEY FINDINGS\n\n")
+        
+        # Determine winner
+        modes_data = summary.get('modes', {})
+        if modes_data:
+            best_quality = max(modes_data.items(), key=lambda x: x[1].get('avg_quality_score', 0))
+            best_success = max(modes_data.items(), key=lambda x: x[1].get('success_rate', 0))
+            lowest_cost = min(modes_data.items(), key=lambda x: x[1].get('total_llm_requests', float('inf')))
+            
+            report.append(f"- **Best Quality**: {best_quality[0].upper()} ({best_quality[1]['avg_quality_score']:.1f}/100)\n")
+            report.append(f"- **Best Success Rate**: {best_success[0].upper()} ({best_success[1]['success_rate']*100:.0f}%)\n")
+            report.append(f"- **Lowest Cost**: {lowest_cost[0].upper()} ({lowest_cost[1]['total_llm_requests']} LLM calls)\n")
+            
+            # Quality per LLM call
+            report.append("\n### Quality Efficiency (Quality Score per LLM Call)\n\n")
+            for mode, data in modes_data.items():
+                llm_calls = data.get('total_llm_requests', 1) or 1
+                quality = data.get('avg_quality_score', 0)
+                efficiency = quality / llm_calls
+                report.append(f"- {mode.upper()}: {efficiency:.2f} quality points per LLM call\n")
+        
+        report.append("\n---\n")
+        report.append("\n## DETAILED CIRCUIT COMPARISONS\n")
+        report.append(circuits_md)
+        
+        return "".join(report)
+    
+    def print_summary(self, run_id: Optional[str] = None):
+        """Print a quick summary to console."""
+        if run_id is None:
+            run_id = self.run_id
+        
+        summary = self.db.get_quality_summary(run_id)
+        
+        print("\n" + "="*70)
+        print("QUALITY EVALUATION SUMMARY")
+        print("="*70)
+        
+        modes = summary.get('modes', {})
+        for mode in ['naked', 'guided', 'blackboard']:
+            if mode in modes:
+                m = modes[mode]
+                print(f"\n{mode.upper()}:")
+                print(f"  Success Rate:    {m['success_rate']*100:.0f}%")
+                print(f"  Quality Score:   {m['avg_quality_score']:.1f}/100")
+                print(f"  Avg Depth:       {m['avg_depth']:.1f}")
+                print(f"  Avg Gates:       {m['avg_gates']:.1f}")
+                print(f"  Avg CX Count:    {m['avg_cx_count']:.1f}")
+                print(f"  HW Fitness:      {m['avg_hardware_fitness']:.3f}")
+                print(f"  LLM Requests:    {m['total_llm_requests']}")
+        
+        print("\n" + "="*70)
+
+
+def run_quick_quality_test(mode: str = 'naked', problem_id: str = 'bell_state') -> CircuitEvaluation:
+    """Quick test function to verify system works."""
+    problem = get_problem(problem_id)
+    if not problem:
+        raise ValueError(f"Problem not found: {problem_id}")
+    
+    harness = QualityEvaluationHarness()
+    return harness.evaluate_single(problem, mode)

tests/quick_mode_test.py

@@ -0,0 +1,81 @@
+# Path: QAgents-workflos/tests/quick_mode_test.py
+# Description: Quick test of all modes on one HARD problem
+"""
+Quick Mode Test: Test all 4 modes on 1 problem each difficulty
+Designed to be fast by testing only essential combinations.
+"""
+
+import sys
+import os
+import warnings
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Suppress warnings
+warnings.filterwarnings("ignore", message=".*non-text parts.*")
+warnings.filterwarnings("ignore", message=".*GOOGLE_API_KEY.*")
+
+import time
+from orchestrators import create_orchestrator
+from tests.test_problems import get_problems_by_difficulty, ProblemDifficulty
+
+def test_mode(mode, problem):
+    """Test a single mode on a problem."""
+    try:
+        orch = create_orchestrator(mode)
+        start = time.perf_counter()
+        result = orch.run(problem.prompt)
+        elapsed = (time.perf_counter() - start) * 1000
+        
+        gates = 0
+        if result.final_output:
+            gates = len([l for l in result.final_output.split('\n') 
+                        if l.strip() and not l.startswith(('OPENQASM', 'include', 'qreg', 'creg', 'measure', '//'))])
+        
+        return result.success, elapsed, gates, None
+    except Exception as e:
+        return False, 0, 0, str(e)[:50]
+
+def main():
+    print("=" * 60)
+    print("QUICK MODE TEST: All 4 modes on HARD problem")
+    print("=" * 60)
+    
+    # Get one VERY_HARD problem - this will show where modes struggle
+    very_hard_problems = get_problems_by_difficulty(ProblemDifficulty.VERY_HARD)
+    problem = very_hard_problems[0]  # 4-Qubit QFT
+    
+    print(f"\nProblem: {problem.name}")
+    print(f"Difficulty: VERY_HARD")
+    print(f"Description: {problem.prompt[:80]}...")
+    print("-" * 60)
+    
+    modes = ["naked", "quasar", "hybrid", "blackboard"]
+    results = []
+    
+    for mode in modes:
+        print(f"\nTesting {mode}...", end=" ", flush=True)
+        ok, ms, gates, error = test_mode(mode, problem)
+        
+        if ok:
+            print(f"✅ {ms:.0f}ms, {gates} gates")
+            results.append((mode, True, ms, gates))
+        elif error:
+            print(f"❌ Error: {error}")
+            results.append((mode, False, 0, 0))
+        else:
+            print(f"❌ Failed ({ms:.0f}ms)")
+            results.append((mode, False, ms, gates))
+    
+    print("\n" + "=" * 60)
+    print("RESULTS SUMMARY")
+    print("=" * 60)
+    
+    for mode, ok, ms, gates in results:
+        status = "✅ PASS" if ok else "❌ FAIL"
+        print(f"  {mode:12}: {status:10} {ms:6.0f}ms  {gates:2} gates")
+    
+    passed = sum(1 for r in results if r[1])
+    print(f"\nTotal: {passed}/{len(results)} modes passed")
+
+if __name__ == "__main__":
+    main()

tests/quick_test.py

@@ -0,0 +1,85 @@
+# Path: QAgents-workflos/tests/quick_test.py
+# Quick test to compare modes on easy problems only
+"""Quick test for mode comparison."""
+
+import sys
+import os
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+api_key = "$env:GOOGLE_API_KEY"
+os.environ['GOOGLE_API_KEY'] = api_key
+
+from tests.test_problems import EASY_PROBLEMS, VERY_HARD_PROBLEMS
+from orchestrators import create_orchestrator
+from orchestrators.quasar_orchestrator import QuasarOrchestrator, HybridOrchestrator
+from config import set_api_key
+
+set_api_key(api_key)
+
+def test_problem(problem, mode):
+    """Test a single problem."""
+    start = time.perf_counter()
+    
+    try:
+        if mode == "quasar":
+            orch = QuasarOrchestrator(max_iterations=3)
+            result = orch.run(problem.prompt, problem.expected.min_qubits)
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+        elif mode == "hybrid":
+            orch = HybridOrchestrator()
+            result = orch.run(problem.prompt, problem.expected.min_qubits)
+            success = result.success
+            qasm = result.final_qasm
+            llm = result.llm_calls
+        else:
+            orch = create_orchestrator(mode)
+            result = orch.run(problem.prompt)
+            success = result.success
+            qasm = result.final_output
+            llm = len([k for k in result.agent_results.keys()]) if result.agent_results else 1
+            
+        elapsed = (time.perf_counter() - start) * 1000
+        return {"success": success, "time_ms": elapsed, "llm": llm, "qasm": qasm[:100] if qasm else None}
+        
+    except Exception as e:
+        elapsed = (time.perf_counter() - start) * 1000
+        return {"success": False, "time_ms": elapsed, "llm": 0, "error": str(e)[:50]}
+
+print("=" * 80)
+print("QUICK MODE COMPARISON TEST")
+print("=" * 80)
+
+# Test only first easy and first very_hard problem with all modes
+test_cases = [
+    ("EASY", EASY_PROBLEMS[0]),
+    ("VERY_HARD", VERY_HARD_PROBLEMS[0])
+]
+
+modes = ["naked", "quasar", "hybrid"]  # Skip slow modes
+
+for diff, problem in test_cases:
+    print(f"\n{diff}: {problem.name}")
+    print("-" * 60)
+    
+    for mode in modes:
+        print(f"  {mode}...", end=" ", flush=True)
+        result = test_problem(problem, mode)
+        
+        status = "✅" if result["success"] else "❌"
+        time_str = f"{result['time_ms']:.0f}ms"
+        llm_str = f"LLM:{result.get('llm', '?')}"
+        
+        print(f"{status} {time_str} {llm_str}")
+        
+        if not result["success"] and "error" in result:
+            print(f"    Error: {result['error']}")
+            
+        time.sleep(5)  # Rate limiting
+
+print("\n" + "=" * 80)
+print("DONE")

tests/run_evaluation.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python
+"""
+QAgents-Workflows: Main Evaluation Runner
+Runs comparative tests between Blackboard, Guided, and Naked modes.
+
+Usage:
+    python run_evaluation.py                    # Run all tests
+    python run_evaluation.py --mode naked       # Test specific mode
+    python run_evaluation.py --problem easy_001 # Test specific problem
+    python run_evaluation.py --quick            # Quick test (1 run per problem)
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+# Add parent to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from config import config, set_mode
+from client import get_client
+from tests import (
+    EvaluationHarness, 
+    ALL_PROBLEMS, 
+    EASY_PROBLEMS,
+    get_problem
+)
+
+
+def setup_logging(verbose: bool = True):
+    """Configure logging."""
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%H:%M:%S"
+    )
+
+
+def check_mcp_server():
+    """Check if MCP server is running."""
+    client = get_client()
+    if not client.health_check():
+        print("\n❌ ERROR: QuantumArchitect-MCP server is not running!")
+        print("\nPlease start it with:")
+        print("  cd D:\\teach\\quantum-circuits")
+        print("  & .venv\\Scripts\\Activate.ps1")
+        print("  python QuantumArchitect-MCP\\app.py")
+        print()
+        return False
+    print("✅ MCP server is running")
+    return True
+
+
+def run_quick_test():
+    """Run a quick sanity test."""
+    print("\n Running Quick Test (Naked mode, Bell State)")
+    print("-" * 50)
+    
+    from orchestrators import create_orchestrator
+    from tests import BELL_STATE_PROBLEM
+    
+    orchestrator = create_orchestrator("naked")
+    result = orchestrator.run(BELL_STATE_PROBLEM.goal)
+    
+    print(f"Success: {result.success}")
+    print(f"Time: {result.execution_time_ms:.1f}ms")
+    print(f"Steps: {result.steps_completed}")
+    
+    if result.final_output:
+        print(f"\nGenerated Circuit:")
+        print(result.final_output[:500] if len(result.final_output) > 500 else result.final_output)
+        
+    if result.errors:
+        print(f"\nErrors: {result.errors}")
+        
+    return result.success
+
+
+def run_full_evaluation(problems=None, modes=None, num_runs=3):
+    """Run full comparative evaluation."""
+    print("\n Starting Full Evaluation")
+    print("=" * 60)
+
+    if problems is None:
+        problems = EASY_PROBLEMS  # Start with easy problems
+    if modes is None:
+        modes = ["blackboard", "guided", "naked"]
+
+    print(f"Problems: {len(problems)}")
+    print(f"Modes: {modes}")
+    print(f"Runs per problem: {num_runs}")
+    print()
+
+    harness = EvaluationHarness(num_runs=num_runs)
+
+    try:
+        results = harness.evaluate_all(problems=problems, modes=modes)
+
+        # Generate and print report
+        report = harness.generate_report()
+        print("\n" + report)
+
+        # Save report to file
+        report_path = Path(__file__).parent / "evaluation_report.txt"
+        report_path.write_text(report)
+        print(f"\n Report saved to: {report_path}")
+
+        # Export CSV for research
+        csv_path = harness.export_csv()
+        print(f" CSV exported to: {csv_path}")
+
+        # Print summary stats
+        stats = harness.get_summary_stats()
+        print("\n Summary Statistics:")
+        for mode, mode_stats in stats.get('modes', {}).items():
+            print(f"  {mode}: {mode_stats['success_rate']*100:.1f}% success, "
+                  f"{mode_stats['total_llm_requests']} LLM calls, "
+                  f"{mode_stats['total_tokens']} tokens")
+
+        return True
+
+    except Exception as e:
+        logging.exception(f"Evaluation failed: {e}")
+        return False
+def main():
+    parser = argparse.ArgumentParser(
+        description="QAgents Comparative Evaluation Runner",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python run_evaluation.py                    # Full evaluation
+  python run_evaluation.py --quick            # Quick sanity test
+  python run_evaluation.py --mode naked       # Test naked mode only
+  python run_evaluation.py --easy             # Only easy problems
+  python run_evaluation.py --runs 10          # 10 runs per problem
+        """
+    )
+    
+    parser.add_argument("--quick", action="store_true",
+                        help="Run quick sanity test only")
+    parser.add_argument("--mode", choices=["blackboard", "guided", "naked"],
+                        help="Test specific mode only")
+    parser.add_argument("--problem", type=str,
+                        help="Test specific problem by ID")
+    parser.add_argument("--easy", action="store_true",
+                        help="Only easy problems")
+    parser.add_argument("--runs", type=int, default=3,
+                        help="Number of runs per problem (default: 3)")
+    parser.add_argument("--verbose", "-v", action="store_true",
+                        help="Verbose output")
+    
+    args = parser.parse_args()
+    
+    setup_logging(args.verbose)
+    
+    print("=" * 60)
+    print("[EVALUATION] QAgents-Workflows Comparative Evaluation")
+    print("=" * 60)
+    
+    # Check MCP server
+    if not check_mcp_server():
+        sys.exit(1)
+        
+    # Quick test mode
+    if args.quick:
+        success = run_quick_test()
+        sys.exit(0 if success else 1)
+        
+    # Determine problems to run
+    if args.problem:
+        problem = get_problem(args.problem)
+        if not problem:
+            print(f"❌ Unknown problem: {args.problem}")
+            sys.exit(1)
+        problems = [problem]
+    elif args.easy:
+        problems = EASY_PROBLEMS
+    else:
+        problems = ALL_PROBLEMS
+        
+    # Determine modes to test
+    modes = [args.mode] if args.mode else None
+    
+    # Run evaluation
+    success = run_full_evaluation(
+        problems=problems,
+        modes=modes,
+        num_runs=args.runs
+    )
+    
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

tests/run_quality_eval.py

@@ -0,0 +1,217 @@
+# Path: QAgents-workflos/run_quality_eval.py
+# Relations: Uses tests/quality_evaluation_harness.py, database/circuit_quality_db.py
+# Description: CLI entry point for quality-focused evaluation
+#              Run with: python run_quality_eval.py --mode all --difficulty easy
+#              Generates quality comparison report with actual QASM circuits
+
+"""
+Quality Evaluation Runner: CLI entry point for circuit quality comparison.
+
+Usage:
+    python run_quality_eval.py --mode all --difficulty easy
+    python run_quality_eval.py --mode naked --problem easy_001
+    python run_quality_eval.py --report RUN_ID
+"""
+
+import argparse
+import logging
+import sys
+import os
+from pathlib import Path
+from datetime import datetime
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+# Ensure API key is set BEFORE importing config
+api_key = os.getenv("GOOGLE_API_KEY") or os.getenv("GENAI_API_KEY")
+if api_key:
+    os.environ["GOOGLE_API_KEY"] = api_key
+
+from tests.quality_evaluation_harness import QualityEvaluationHarness, run_quick_quality_test
+from tests.test_problems import get_problem, get_problems_by_difficulty
+from database.circuit_quality_db import get_quality_db
+from config import set_api_key
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Explicitly set API key in config after logging is ready
+if api_key:
+    set_api_key(api_key)
+    logger.info(f"API Key configured: {api_key[:10]}...")
+else:
+    logger.warning("No GOOGLE_API_KEY or GENAI_API_KEY found in environment")
+
+
+def run_evaluation(args):
+    """Run quality evaluation based on arguments."""
+    harness = QualityEvaluationHarness()
+
+    # Parse modes
+    if args.mode == 'all':
+        modes = ['naked', 'guided', 'blackboard']
+    else:
+        modes = [args.mode]
+
+    # Parse difficulties
+    if args.difficulty == 'all':
+        difficulties = ['easy', 'medium', 'hard']
+    else:
+        difficulties = [args.difficulty]
+
+    # Check if specific problem
+    if args.problem:
+        problem = get_problem(args.problem)
+        if not problem:
+            print(f"ERROR: Problem not found: {args.problem}")
+            return
+
+        print(f"\n{'='*60}")
+        print(f"Running quality evaluation for: {args.problem}")
+        print(f"Modes: {modes}")
+        print(f"{'='*60}\n")
+
+        results = harness.evaluate_problem_all_modes(problem, modes)
+
+        # Print results
+        for mode, result in results.items():
+            print(f"\n{mode.upper()}:")
+            print(f"  Success: {'✅' if result.success else '❌'}")
+            print(f"  Quality Score: {result.quality_metrics.overall_score()}/100")
+            print(f"  Depth: {result.quality_metrics.depth}")
+            print(f"  Gates: {result.quality_metrics.gate_count}")
+            print(f"  CX: {result.quality_metrics.cx_count}")
+            print(f"  Time: {result.execution_time_ms:.0f}ms")
+            print(f"  LLM Calls: {result.llm_requests}")
+            if result.qasm_code:
+                print(f"  QASM ({len(result.qasm_code)} chars):")
+                lines = result.qasm_code.split('\n')[:10]
+                for line in lines:
+                    print(f"    {line}")
+                if len(result.qasm_code.split('\n')) > 10:
+                    print("    ...")
+    else:
+        # Full evaluation
+        print(f"\n{'='*60}")
+        print(f"Running full quality evaluation")
+        print(f"Difficulties: {difficulties}")
+        print(f"Modes: {modes}")
+        print(f"Max problems: {args.max_problems or 'all'}")
+        print(f"{'='*60}\n")
+
+        run_id = harness.run_full_evaluation(
+            difficulties=difficulties,
+            modes=modes,
+            max_problems=args.max_problems
+        )
+
+        # Print summary
+        harness.print_summary(run_id)
+
+        # Generate report file
+        report = harness.generate_report(run_id)
+        report_path = Path(__file__).parent / f"QUALITY_REPORT_{run_id}.md"
+        report_path.write_text(report, encoding='utf-8')
+        print(f"\nFull report saved to: {report_path}")
+
+        print(f"\nRun ID: {run_id}")
+        print("Use --report <run_id> to regenerate report later")
+
+
+def show_report(run_id: str):
+    """Show report for a specific run."""
+    harness = QualityEvaluationHarness()
+    harness.run_id = run_id  # Set to existing run
+
+    report = harness.generate_report(run_id)
+    print(report)
+
+
+def list_runs():
+    """List all evaluation runs."""
+    db = get_quality_db()
+
+    query = "SELECT run_id, timestamp, description, num_problems FROM comparison_runs ORDER BY timestamp DESC LIMIT 20"
+    import sqlite3
+    with sqlite3.connect(db.db_file) as conn:
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(query).fetchall()
+
+    if not rows:
+        print("No evaluation runs found.")
+        return
+
+    print("\nRecent Evaluation Runs:")
+    print("-" * 80)
+    for row in rows:
+        print(f"{row['run_id']} | {row['timestamp']} | {row['num_problems']} problems | {row['description'] or 'N/A'}")
+    print("-" * 80)
+
+
+def quick_test(args):
+    """Run a quick single test."""
+    mode = args.mode if args.mode != 'all' else 'naked'
+    problem_id = args.problem or 'easy_001'
+
+    print(f"\nQuick test: {problem_id} with {mode} mode")
+    print("-" * 40)
+
+    try:
+        result = run_quick_quality_test(mode, problem_id)
+        print(f"Success: {'✅' if result.success else '❌'}")
+        print(f"Quality Score: {result.quality_metrics.overall_score()}/100")
+        print(f"Depth: {result.quality_metrics.depth}")
+        print(f"Gates: {result.quality_metrics.gate_count}")
+        if result.qasm_code:
+            print(f"\nQASM:\n{result.qasm_code[:500]}")
+        if result.errors:
+            print(f"\nErrors: {result.errors}")
+    except Exception as e:
+        print(f"ERROR: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Quality-focused quantum circuit evaluation",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python run_quality_eval.py --quick                     # Quick test
+  python run_quality_eval.py --mode all --difficulty easy
+  python run_quality_eval.py --problem easy_001 --mode all
+  python run_quality_eval.py --list                      # List previous runs
+  python run_quality_eval.py --report quality_20241128_120000
+"""
+    )
+
+    parser.add_argument('--mode', choices=['naked', 'guided', 'blackboard', 'all'],
+                        default='all', help='Orchestration mode(s) to test')
+    parser.add_argument('--difficulty', choices=['easy', 'medium', 'hard', 'all'],
+                        default='easy', help='Problem difficulty level(s)')
+    parser.add_argument('--problem', type=str, help='Specific problem ID to test')
+    parser.add_argument('--max-problems', type=int, help='Maximum problems to test')
+    parser.add_argument('--quick', action='store_true', help='Run quick single test')
+    parser.add_argument('--report', type=str, help='Generate report for run ID')
+    parser.add_argument('--list', action='store_true', help='List previous runs')
+
+    args = parser.parse_args()
+
+    if args.list:
+        list_runs()
+    elif args.report:
+        show_report(args.report)
+    elif args.quick:
+        quick_test(args)
+    else:
+        run_evaluation(args)
+
+
+if __name__ == "__main__":
+    main()

tests/test_db_storage.py

@@ -0,0 +1,59 @@
+# Path: QAgents-workflos/test_db_storage.py
+# Description: Quick test to verify database storage works
+"""Test that database can store and retrieve circuits."""
+
+from database.circuit_quality_db import CircuitQualityDB, CircuitEvaluation, QualityMetrics, get_quality_db
+from datetime import datetime
+
+def test_db():
+    # Test database
+    db = get_quality_db()
+    print(f'Database file: {db.db_file}')
+
+    # Create a test evaluation with sample QASM
+    test_qasm = """OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2];
+creg c[2];
+h q[0];
+cx q[0], q[1];
+measure q -> c;
+"""
+
+    test_eval = CircuitEvaluation(
+        run_id='test_manual_001',
+        timestamp=datetime.now().isoformat(),
+        problem_id='test_bell_state',
+        problem_goal='Create Bell state',
+        mode='manual_test',
+        qasm_code=test_qasm,
+        success=True,
+        execution_time_ms=0,
+        llm_requests=0,
+        tokens_used=0,
+        quality_metrics=QualityMetrics(
+            depth=2,
+            gate_count=3,
+            cx_count=1,
+            single_qubit_count=1,
+            hardware_fitness=0.95,
+            syntax_valid=True,
+            state_correctness=1.0
+        )
+    )
+
+    # Save to database
+    eval_id = db.save_evaluation(test_eval)
+    print(f'Saved evaluation ID: {eval_id}')
+
+    # Retrieve and verify
+    evals = db.get_evaluations(problem_id='test_bell_state')
+    print(f'Retrieved {len(evals)} evaluations')
+    if evals:
+        e = evals[0]
+        print(f'QASM stored ({len(e.qasm_code)} chars):')
+        print(e.qasm_code)
+        print(f'Quality score: {e.quality_metrics.overall_score()}/100')
+
+if __name__ == "__main__":
+    test_db()

tests/test_mcp_client.py

@@ -0,0 +1,181 @@
+# Path: QAgents-workflos/tests/test_mcp_client.py
+# Relations: Tests client/mcp_client.py
+# Description: Comprehensive tests for MCP client with Gradio and fallback implementations
+
+"""
+Test suite for MCP client functionality.
+Tests both Gradio-based endpoints and local fallback implementations.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from client.mcp_client import get_client, MCPClient, QASMLocalAnalyzer
+
+# Sample QASM for testing
+BELL_STATE_QASM = '''OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2];
+creg c[2];
+h q[0];
+cx q[0], q[1];
+measure q -> c;'''
+
+
+def test_health_check():
+    """Test server health check."""
+    client = get_client()
+    result = client.health_check()
+    print(f"Health Check: {'OK' if result else 'FAILED'}")
+    return result
+
+
+def test_create_circuit():
+    """Test circuit creation from template (uses Gradio)."""
+    client = get_client()
+    result = client.create_circuit_from_template('bell_state', 2)
+    
+    print(f"Create Circuit:")
+    print(f"  Success: {result.success}")
+    print(f"  Endpoint: {result.endpoint}")
+    print(f"  Time: {result.execution_time_ms:.2f}ms")
+    if result.success and result.data:
+        print(f"  Data preview: {str(result.data)[:80]}...")
+    return result.success
+
+
+def test_analyze_circuit():
+    """Test circuit analysis (uses fallback)."""
+    client = get_client()
+    result = client.analyze_circuit(BELL_STATE_QASM)
+    
+    print(f"Analyze Circuit:")
+    print(f"  Success: {result.success}")
+    print(f"  Is Fallback: {result.is_fallback}")
+    if result.success:
+        print(f"  Depth: {result.data.get('depth')}")
+        print(f"  Gate Count: {result.data.get('gate_count')}")
+        print(f"  Two-qubit Gates: {result.data.get('two_qubit_gates')}")
+    return result.success
+
+
+def test_validate_syntax():
+    """Test syntax validation (uses Gradio)."""
+    client = get_client()
+    result = client.validate_syntax(BELL_STATE_QASM)
+    
+    print(f"Validate Syntax:")
+    print(f"  Success: {result.success}")
+    print(f"  Endpoint: {result.endpoint}")
+    print(f"  Time: {result.execution_time_ms:.2f}ms")
+    return result.success
+
+
+def test_simulate_circuit():
+    """Test circuit simulation (uses Gradio)."""
+    client = get_client()
+    result = client.simulate_circuit(BELL_STATE_QASM, shots=100)
+    
+    print(f"Simulate Circuit:")
+    print(f"  Success: {result.success}")
+    print(f"  Endpoint: {result.endpoint}")
+    print(f"  Time: {result.execution_time_ms:.2f}ms")
+    if result.success and result.data:
+        print(f"  Data preview: {str(result.data)[:80]}...")
+    return result.success
+
+
+def test_complexity_score():
+    """Test complexity scoring (uses Gradio or fallback)."""
+    client = get_client()
+    result = client.calculate_complexity_score(BELL_STATE_QASM)
+    
+    print(f"Complexity Score:")
+    print(f"  Success: {result.success}")
+    print(f"  Is Fallback: {result.is_fallback}")
+    if result.success and result.data:
+        if isinstance(result.data, dict):
+            print(f"  Score: {result.data.get('complexity_score', 'N/A')}")
+    return result.success
+
+
+def test_estimate_noise():
+    """Test noise estimation (uses fallback)."""
+    client = get_client()
+    result = client.estimate_noise(BELL_STATE_QASM, hardware='ibm_brisbane')
+    
+    print(f"Estimate Noise:")
+    print(f"  Success: {result.success}")
+    print(f"  Is Fallback: {result.is_fallback}")
+    if result.success:
+        print(f"  Fidelity: {result.data.get('estimated_fidelity')}")
+        print(f"  Total Error: {result.data.get('total_error_probability')}")
+    return result.success
+
+
+def test_local_analyzer():
+    """Test QASMLocalAnalyzer directly."""
+    analyzer = QASMLocalAnalyzer()
+    
+    # Parse
+    parsed = analyzer.parse_qasm(BELL_STATE_QASM)
+    print(f"Local Parser:")
+    print(f"  Qubits: {parsed['num_qubits']}")
+    print(f"  Gates: {len(parsed['gates'])}")
+    
+    # Analyze
+    analysis = analyzer.analyze_circuit(BELL_STATE_QASM)
+    print(f"Local Analyzer:")
+    print(f"  Depth: {analysis['depth']}")
+    print(f"  Gate breakdown: {analysis['gate_breakdown']}")
+    
+    # Complexity
+    complexity = analyzer.calculate_complexity(BELL_STATE_QASM)
+    print(f"Local Complexity:")
+    print(f"  Score: {complexity['complexity_score']}")
+    
+    return True
+
+
+def run_all_tests():
+    """Run all MCP client tests."""
+    print("=" * 50)
+    print("MCP Client Test Suite")
+    print("=" * 50)
+    
+    tests = [
+        ("Health Check", test_health_check),
+        ("Create Circuit", test_create_circuit),
+        ("Analyze Circuit", test_analyze_circuit),
+        ("Validate Syntax", test_validate_syntax),
+        ("Simulate Circuit", test_simulate_circuit),
+        ("Complexity Score", test_complexity_score),
+        ("Estimate Noise", test_estimate_noise),
+        ("Local Analyzer", test_local_analyzer),
+    ]
+    
+    results = []
+    for name, test_func in tests:
+        print(f"\n--- {name} ---")
+        try:
+            passed = test_func()
+            results.append((name, passed))
+        except Exception as e:
+            print(f"ERROR: {e}")
+            results.append((name, False))
+    
+    print("\n" + "=" * 50)
+    print("Summary")
+    print("=" * 50)
+    passed = sum(1 for _, p in results if p)
+    print(f"Passed: {passed}/{len(results)}")
+    for name, p in results:
+        status = "✓" if p else "✗"
+        print(f"  {status} {name}")
+    
+    return all(p for _, p in results)
+
+
+if __name__ == "__main__":
+    run_all_tests()

tests/test_problems.py

@@ -0,0 +1,709 @@
+# Path: QAgents-workflos/tests/test_problems.py
+# Relations: Used by evaluation_harness.py, run_evaluation.py
+# Description: Real quantum computing problems requiring LLM reasoning
+#              Each problem has increasing complexity and real-world relevance
+"""
+Test Problems Module: Real Quantum Computing Challenges
+
+TESTING FRAMEWORK DESIGN:
+=========================
+
+Each problem requires actual LLM reasoning to solve - no hardcoded templates.
+The LLM must understand the quantum mechanics and generate appropriate QASM.
+
+EVALUATION MODES:
+-----------------
+1. NAKED: 1 LLM call per problem (direct reasoning, no agents)
+2. GUIDED: 1 + 4 LLM calls (initial + architect/builder/validator/scorer agents)  
+3. BLACKBOARD: 1 + 8-12 LLM calls (initial + collaborative agent rounds)
+
+PROBLEM CATEGORIES:
+-------------------
+EASY (1-2 qubits, 1-3 gates):
+  - Fundamental single/two-qubit operations
+  - Direct QASM generation possible
+
+MEDIUM (2-3 qubits, 4-8 gates):
+  - Require understanding of gate decomposition
+  - Multiple valid solutions possible
+
+HARD (3+ qubits, 8+ gates):
+  - Algorithm implementation
+  - Optimization considerations
+  - Real-world applications
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+from enum import Enum
+
+
+class ProblemDifficulty(Enum):
+    """Problem difficulty levels."""
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+    VERY_HARD = "very_hard"  # New: Push NAKED to its limits
+
+
+class ProblemCategory(Enum):
+    """Problem categories for research tracking."""
+    STATE_PREPARATION = "state_prep"
+    GATE_SYNTHESIS = "gate_synthesis"
+    ALGORITHM = "algorithm"
+    ERROR_CORRECTION = "error_correction"
+    OPTIMIZATION = "optimization"
+
+
+@dataclass
+class ExpectedOutput:
+    """Expected output for validation."""
+    min_qubits: int
+    max_qubits: int = 10
+    max_depth: Optional[int] = None
+    required_gates: List[str] = field(default_factory=list)
+    forbidden_gates: List[str] = field(default_factory=list)
+    expected_states: Dict[str, float] = field(default_factory=dict)
+    tolerance: float = 0.1  # Probability tolerance for state matching
+    must_be_unitary: bool = True
+    hardware_compatible: bool = True
+
+
+@dataclass
+class TestProblem:
+    """A quantum circuit test problem for LLM evaluation."""
+    id: str
+    name: str
+    description: str
+
+    # The prompt sent to the LLM - must require reasoning
+    prompt: str
+
+    # Category and difficulty for analysis
+    difficulty: ProblemDifficulty
+    category: ProblemCategory
+
+    # Validation criteria
+    expected: ExpectedOutput
+
+    # Metadata for research tracking
+    tags: List[str] = field(default_factory=list)
+    reference_solution: Optional[str] = None  # Known optimal QASM
+    optimal_depth: Optional[int] = None
+    optimal_gate_count: Optional[int] = None
+
+    # Research tracking
+    requires_understanding: List[str] = field(default_factory=list)
+    common_mistakes: List[str] = field(default_factory=list)
+
+    @property
+    def goal(self) -> str:
+        """Alias for prompt - used by orchestrators."""
+        return self.prompt
+# =============================================================================
+# EASY PROBLEMS: Fundamental Quantum Operations
+# =============================================================================
+
+PROBLEM_E1_PHASE_FLIP = TestProblem(
+    id="easy_001",
+    name="Phase Flip State",
+    description="Create the |−⟩ state (phase-flipped superposition)",
+    prompt="""Create a quantum circuit that prepares the |−⟩ state.
+
+The |−⟩ state is defined as: (|0⟩ - |1⟩)/√2
+
+This is different from the |+⟩ state which is (|0⟩ + |1⟩)/√2.
+
+Requirements:
+- Use a single qubit
+- The final state should have equal probability of 0 and 1
+- But the relative phase between them should be π (negative)
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.EASY,
+    category=ProblemCategory.STATE_PREPARATION,
+    expected=ExpectedOutput(
+        min_qubits=1,
+        max_qubits=1,
+        max_depth=2,
+        required_gates=["h", "z"],  # or x then h
+        expected_states={"0": 0.5, "1": 0.5}
+    ),
+    tags=["superposition", "phase", "single-qubit"],
+    requires_understanding=["Hadamard gate", "Z gate", "quantum phases"],
+    common_mistakes=["Using only H (creates |+⟩ not |−⟩)", "Wrong gate order"],
+    optimal_depth=2,
+    optimal_gate_count=2
+)
+
+PROBLEM_E2_CONTROLLED_NOT = TestProblem(
+    id="easy_002",
+    name="Entanglement Generation",
+    description="Create maximal entanglement between two qubits",
+    prompt="""Create a quantum circuit that maximally entangles two qubits.
+
+Starting from |00⟩, create the Bell state |Φ+⟩ = (|00⟩ + |11⟩)/√2
+
+Requirements:
+- Use exactly 2 qubits
+- Measuring both qubits should give 00 or 11 with equal probability
+- The qubits must be entangled (not just in superposition)
+
+Think about what gates create entanglement.
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.EASY,
+    category=ProblemCategory.STATE_PREPARATION,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=3,
+        required_gates=["h", "cx"],
+        expected_states={"00": 0.5, "11": 0.5}
+    ),
+    tags=["entanglement", "bell", "cnot"],
+    requires_understanding=["Hadamard gate", "CNOT gate", "entanglement"],
+    common_mistakes=["Applying H to both qubits (no entanglement)", "Wrong CNOT direction"],
+    optimal_depth=2,
+    optimal_gate_count=2
+)
+
+PROBLEM_E3_MEASUREMENT_BASIS = TestProblem(
+    id="easy_003", 
+    name="X-Basis Measurement Prep",
+    description="Prepare a state for X-basis measurement",
+    prompt="""Create a circuit that transforms a Z-basis state into X-basis.
+
+Starting with |0⟩, prepare the state so that if we were to measure in the 
+X-basis (instead of Z-basis), we would get |+⟩ deterministically.
+
+In other words: Transform |0⟩ → |+⟩ where |+⟩ = (|0⟩ + |1⟩)/√2
+
+Requirements:
+- Single qubit circuit
+- The state should be the +1 eigenstate of the X operator
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.EASY,
+    category=ProblemCategory.STATE_PREPARATION,
+    expected=ExpectedOutput(
+        min_qubits=1,
+        max_qubits=1,
+        max_depth=1,
+        required_gates=["h"],
+        expected_states={"0": 0.5, "1": 0.5}
+    ),
+    tags=["basis-change", "hadamard", "measurement"],
+    requires_understanding=["Measurement bases", "Hadamard as basis change"],
+    common_mistakes=["Not understanding basis transformation"],
+    optimal_depth=1,
+    optimal_gate_count=1
+)
+
+
+# =============================================================================
+# MEDIUM PROBLEMS: Gate Decomposition and Multi-Qubit Operations
+# =============================================================================
+
+PROBLEM_M1_SWAP_DECOMPOSITION = TestProblem(
+    id="medium_001",
+    name="SWAP from CNOTs",
+    description="Implement SWAP gate using only CNOT gates",
+    prompt="""Decompose the SWAP gate into basic gates.
+
+The SWAP gate exchanges the states of two qubits:
+SWAP|ab⟩ = |ba⟩
+
+You must implement SWAP using only CNOT gates (no native SWAP allowed).
+
+Requirements:
+- Use exactly 2 qubits
+- Only use CNOT (cx) gates - no other two-qubit gates
+- The circuit should swap the state of qubit 0 and qubit 1
+- Test: if input is |01⟩, output should be |10⟩
+
+Hint: CNOT can be thought of as conditional bit flip.
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.MEDIUM,
+    category=ProblemCategory.GATE_SYNTHESIS,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=6,
+        required_gates=["cx"],
+        forbidden_gates=["swap"]
+    ),
+    tags=["decomposition", "swap", "cnot-only"],
+    requires_understanding=["CNOT behavior", "Gate decomposition"],
+    common_mistakes=["Wrong number of CNOTs", "Wrong CNOT directions"],
+    reference_solution="OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncx q[0],q[1];\ncx q[1],q[0];\ncx q[0],q[1];",
+    optimal_depth=3,
+    optimal_gate_count=3
+)
+
+PROBLEM_M2_CONTROLLED_Z = TestProblem(
+    id="medium_002",
+    name="CZ from Basic Gates",
+    description="Build Controlled-Z using H and CNOT",
+    prompt="""Implement the Controlled-Z (CZ) gate using only Hadamard and CNOT gates.
+
+The CZ gate applies a Z gate to the target qubit when the control is |1⟩:
+CZ|00⟩ = |00⟩
+CZ|01⟩ = |01⟩  
+CZ|10⟩ = |10⟩
+CZ|11⟩ = -|11⟩  (note the phase flip!)
+
+Requirements:
+- Use only H and CNOT gates
+- No native CZ gate allowed
+- 2 qubits
+
+Hint: Think about how H transforms Z operations.
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.MEDIUM,
+    category=ProblemCategory.GATE_SYNTHESIS,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=5,
+        required_gates=["h", "cx"],
+        forbidden_gates=["cz"]
+    ),
+    tags=["decomposition", "controlled-z", "phase"],
+    requires_understanding=["CZ gate definition", "H-Z-H = X identity"],
+    common_mistakes=["Forgetting H gates", "Wrong qubit as target"],
+    reference_solution="OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\nh q[1];\ncx q[0],q[1];\nh q[1];",
+    optimal_depth=3,
+    optimal_gate_count=3
+)
+
+PROBLEM_M3_PHASE_ESTIMATION_PREP = TestProblem(
+    id="medium_003",
+    name="Phase Kickback Setup",
+    description="Create the phase kickback configuration",
+    prompt="""Create a circuit demonstrating quantum phase kickback.
+
+Phase kickback is a key concept where applying a controlled-U gate
+causes the control qubit to acquire the eigenvalue phase.
+
+Setup:
+1. Prepare control qubit in |+⟩ superposition
+2. Prepare target qubit in |1⟩ (eigenstate of Z with eigenvalue -1)
+3. Apply CZ gate
+4. The control qubit should now be in |−⟩ state
+
+The final state of the control qubit (q[0]) should show the phase kickback.
+
+Requirements:
+- 2 qubits
+- Control in superposition, target in |1⟩
+- Apply controlled operation
+- Use only basic gates (H, X, CX, CZ allowed)
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.MEDIUM,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=5,
+        required_gates=["h", "x"],
+        expected_states={"01": 0.5, "11": 0.5}  # After kickback
+    ),
+    tags=["phase-kickback", "algorithm-primitive", "phase-estimation"],
+    requires_understanding=["Phase kickback", "Eigenstates", "Controlled operations"],
+    common_mistakes=["Target not in eigenstate", "Missing superposition"],
+    optimal_depth=4,
+    optimal_gate_count=4
+)
+
+
+# =============================================================================
+# HARD PROBLEMS: Algorithm Implementation
+# =============================================================================
+
+PROBLEM_H1_DEUTSCH = TestProblem(
+    id="hard_001",
+    name="Deutsch Algorithm",
+    description="Implement Deutsch's algorithm for function type detection",
+    prompt="""Implement Deutsch's algorithm to determine if a function is constant or balanced.
+
+Deutsch's algorithm determines whether a black-box function f:{0,1}→{0,1} is:
+- Constant: f(0)=f(1) (always 0 or always 1)
+- Balanced: f(0)≠f(1) (different outputs)
+
+For this problem, implement the oracle for the BALANCED function f(x) = x.
+
+Algorithm structure:
+1. Initialize |01⟩ (input qubit |0⟩, ancilla qubit |1⟩)
+2. Apply H to both qubits
+3. Apply the oracle Uf: |x,y⟩ → |x, y⊕f(x)⟩
+4. Apply H to the input qubit
+5. Measure input qubit: |1⟩ means balanced
+
+For f(x)=x, the oracle is just a CNOT.
+
+Requirements:
+- 2 qubits
+- Implement full Deutsch circuit with f(x)=x oracle
+- After measurement, input qubit should be in |1⟩
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=8,
+        required_gates=["h", "x", "cx"],
+        expected_states={"11": 1.0}  # Input qubit is 1 (balanced), ancilla is 1
+    ),
+    tags=["algorithm", "deutsch", "oracle"],
+    requires_understanding=["Deutsch algorithm", "Oracle construction", "Interference"],
+    common_mistakes=["Wrong initial state", "Missing ancilla preparation", "Oracle errors"],
+    optimal_depth=5,
+    optimal_gate_count=6
+)
+
+PROBLEM_H2_GROVER_2QUBIT = TestProblem(
+    id="hard_002",
+    name="Grover Search (2-qubit)",
+    description="Find marked state |11⟩ using Grover's algorithm",
+    prompt="""Implement 2-qubit Grover's search algorithm to find the state |11⟩.
+
+Grover's algorithm amplifies the probability of the marked state.
+
+For 2 qubits with 1 marked state, we need exactly 1 iteration:
+
+1. Initialize: H⊗H on |00⟩ → equal superposition
+2. Oracle: Mark |11⟩ with a phase flip (multiply by -1)
+3. Diffusion: Reflect about the average amplitude
+
+Oracle for |11⟩: Apply CZ (or equivalent)
+Diffusion operator: H⊗H · (2|00⟩⟨00| - I) · H⊗H
+
+Requirements:
+- 2 qubits
+- After 1 Grover iteration, |11⟩ should have probability ≈ 1
+- Use only basic gates
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=2,
+        max_qubits=2,
+        max_depth=12,
+        required_gates=["h", "x", "cx"],
+        expected_states={"11": 1.0},
+        tolerance=0.1
+    ),
+    tags=["algorithm", "grover", "search", "amplitude-amplification"],
+    requires_understanding=["Grover's algorithm", "Oracle design", "Diffusion operator"],
+    common_mistakes=["Wrong oracle phase", "Missing diffusion", "Too many/few iterations"],
+    optimal_depth=8,
+    optimal_gate_count=10
+)
+
+PROBLEM_H3_TELEPORTATION_PREP = TestProblem(
+    id="hard_003",
+    name="Quantum Teleportation Setup",
+    description="Prepare the entangled resource state for teleportation",
+    prompt="""Create the initial setup for quantum teleportation.
+
+Quantum teleportation requires:
+1. The state to teleport |ψ⟩ on qubit 0
+2. A shared Bell pair between qubits 1 and 2
+
+For this problem:
+- Prepare qubit 0 in state |+⟩ (the state we'll "teleport")
+- Prepare qubits 1 and 2 in the Bell state (|00⟩ + |11⟩)/√2
+- Qubit 1 goes to Alice (sender), qubit 2 to Bob (receiver)
+
+Requirements:
+- 3 qubits
+- q[0]: |+⟩ state (to be teleported)
+- q[1], q[2]: Bell pair (shared entanglement)
+
+After this setup, Alice has q[0] and q[1], Bob has q[2].
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=3,
+        max_qubits=3,
+        max_depth=4,
+        required_gates=["h", "cx"]
+    ),
+    tags=["algorithm", "teleportation", "entanglement", "bell-state"],
+    requires_understanding=["Quantum teleportation", "Bell states", "Entanglement as resource"],
+    common_mistakes=["Wrong qubits entangled", "State to teleport not prepared"],
+    optimal_depth=3,
+    optimal_gate_count=4
+)
+
+
+# =============================================================================
+# PROBLEM SETS
+# =============================================================================
+
+EASY_PROBLEMS = [
+    PROBLEM_E1_PHASE_FLIP,
+    PROBLEM_E2_CONTROLLED_NOT,
+    PROBLEM_E3_MEASUREMENT_BASIS
+]
+
+MEDIUM_PROBLEMS = [
+    PROBLEM_M1_SWAP_DECOMPOSITION,
+    PROBLEM_M2_CONTROLLED_Z,
+    PROBLEM_M3_PHASE_ESTIMATION_PREP
+]
+
+HARD_PROBLEMS = [
+    PROBLEM_H1_DEUTSCH,
+    PROBLEM_H2_GROVER_2QUBIT,
+    PROBLEM_H3_TELEPORTATION_PREP
+]
+
+
+# ============================================================================
+# VERY_HARD PROBLEMS: Push NAKED to its limits
+# ============================================================================
+
+PROBLEM_VH1_QFT_4QUBIT = TestProblem(
+    id="very_hard_001",
+    name="4-Qubit QFT",
+    description="Implement full Quantum Fourier Transform on 4 qubits",
+    prompt="""Implement the complete Quantum Fourier Transform (QFT) on 4 qubits.
+
+The QFT transforms computational basis states into Fourier basis:
+QFT|x⟩ = (1/√N) Σ_{k=0}^{N-1} e^{2πixk/N} |k⟩
+
+For 4 qubits (N=16), the circuit requires:
+1. Apply Hadamard to each qubit in sequence
+2. Apply controlled phase rotations (CR_k) between qubits
+3. SWAP qubits to correct bit ordering (optional for some conventions)
+
+Phase rotation angles: R_k = rotation by π/2^(k-1)
+- R_2 = π/2 (S gate or cp(π/2))
+- R_3 = π/4 (T gate or cp(π/4))
+- R_4 = π/8 (cp(π/8))
+
+Requirements:
+- Use exactly 4 qubits
+- Must use H, controlled-phase (cp or crz), and optionally SWAP gates
+- Do NOT use QFT as a black box - implement the full decomposition
+- Include proper phase rotations between all qubit pairs
+
+The output should show interference patterns in the Fourier basis.
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.VERY_HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=4,
+        max_qubits=4,
+        max_depth=20,
+        required_gates=["h"]
+    ),
+    tags=["qft", "fourier", "phase-rotation", "multi-qubit"],
+    requires_understanding=["QFT algorithm", "Controlled phase gates", "Bit reversal"],
+    common_mistakes=["Wrong phase angles", "Missing controlled rotations", "Forgetting bit reversal"],
+    optimal_depth=12,
+    optimal_gate_count=16
+)
+
+PROBLEM_VH2_GROVER_3QUBIT = TestProblem(
+    id="very_hard_002",
+    name="Grover 3-Qubit Search",
+    description="Implement Grover's search on 3 qubits with 2 iterations",
+    prompt="""Implement 3-qubit Grover's search algorithm to find the marked state |101⟩.
+
+For 3 qubits (N=8 states), the optimal number of iterations is approximately π√N/4 ≈ 2.
+
+Algorithm structure (repeat 2 times):
+1. Initial superposition: H⊗H⊗H on |000⟩
+
+For EACH Grover iteration:
+2. Oracle: Mark |101⟩ with phase flip (multiply amplitude by -1)
+   - Oracle for |101⟩: X on q[1], then CCZ (or Toffoli+phase), then X on q[1]
+   - Alternative: use multi-controlled Z gate
+   
+3. Diffusion operator (Grover diffuser):
+   - Apply H to all qubits
+   - Apply X to all qubits  
+   - Apply multi-controlled Z (CCZ or decomposition)
+   - Apply X to all qubits
+   - Apply H to all qubits
+
+Requirements:
+- Use exactly 3 qubits
+- Implement BOTH oracle and diffusion operator
+- Perform exactly 2 Grover iterations
+- After 2 iterations, |101⟩ should have probability > 0.9
+- Use basic gates: H, X, CX, CCX (Toffoli), CZ, or their equivalents
+
+IMPORTANT: You must implement CCZ using either:
+- ccx followed by cz and ccx (Toffoli-based)
+- h on target, ccx, h on target (standard decomposition)
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.VERY_HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=3,
+        max_qubits=3,
+        max_depth=30,
+        required_gates=["h", "x", "cx"],
+        expected_states={"101": 0.9},
+        tolerance=0.15
+    ),
+    tags=["grover", "search", "oracle", "diffusion", "multi-iteration"],
+    requires_understanding=["Grover's algorithm", "Multi-controlled gates", "Oracle design", "Diffusion operator"],
+    common_mistakes=["Wrong oracle", "Single iteration only", "Incorrect diffusion", "Missing CCZ decomposition"],
+    optimal_depth=24,
+    optimal_gate_count=40
+)
+
+PROBLEM_VH3_VQE_ANSATZ = TestProblem(
+    id="very_hard_003",
+    name="VQE Hardware-Efficient Ansatz",
+    description="Construct a 4-qubit hardware-efficient ansatz for VQE",
+    prompt="""Construct a 4-qubit hardware-efficient variational ansatz for VQE.
+
+A hardware-efficient ansatz is a parameterized quantum circuit used in VQE
+(Variational Quantum Eigensolver) to prepare trial wavefunctions.
+
+Structure (2 layers):
+
+LAYER 1:
+1. Apply Ry(θ) rotations to all 4 qubits (use ry gate with parameter, e.g., ry(pi/4))
+2. Apply Rz(φ) rotations to all 4 qubits (use rz gate with parameter, e.g., rz(pi/4))
+3. Apply entangling CNOT ladder: cx q[0],q[1]; cx q[1],q[2]; cx q[2],q[3];
+
+LAYER 2:
+4. Apply Ry(θ') rotations to all 4 qubits
+5. Apply Rz(φ') rotations to all 4 qubits
+6. Apply entangling CNOT ladder again
+
+For this implementation, use fixed angles:
+- Layer 1: ry(0.5) and rz(0.3) on all qubits
+- Layer 2: ry(0.7) and rz(0.2) on all qubits
+
+Requirements:
+- Use exactly 4 qubits
+- Implement 2 full layers (rotation + entanglement each)
+- Use ry, rz, and cx gates
+- Linear entanglement pattern (nearest-neighbor CNOTs)
+
+This circuit structure is used on real quantum hardware (IBM, Google) for
+quantum chemistry and optimization problems.
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.VERY_HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=4,
+        max_qubits=4,
+        max_depth=16,
+        required_gates=["ry", "rz", "cx"]
+    ),
+    tags=["vqe", "ansatz", "variational", "quantum-chemistry", "hardware-efficient"],
+    requires_understanding=["VQE algorithm", "Parameterized circuits", "Hardware constraints", "Entanglement layers"],
+    common_mistakes=["Missing rotation layers", "Wrong entanglement pattern", "Incorrect parameter format"],
+    optimal_depth=12,
+    optimal_gate_count=22
+)
+
+PROBLEM_VH4_BERNSTEIN_VAZIRANI = TestProblem(
+    id="very_hard_004",
+    name="Bernstein-Vazirani 4-bit",
+    description="Implement Bernstein-Vazirani algorithm to find hidden string s=1011",
+    prompt="""Implement the Bernstein-Vazirani algorithm to find the hidden string s=1011.
+
+The Bernstein-Vazirani algorithm finds a hidden n-bit string s in ONE query.
+Given a function f(x) = s·x mod 2 (bitwise dot product), find s.
+
+For s=1011 (4 bits), we need 5 qubits (4 input + 1 ancilla):
+
+Algorithm:
+1. Initialize all input qubits to |0⟩, ancilla to |1⟩
+2. Apply H to all 5 qubits (creates superposition + phase kickback setup)
+3. Apply Oracle U_f: For each bit s_i=1, apply CNOT from q[i] to ancilla
+   - s=1011 means: CNOT from q[0] to q[4], q[2] to q[4], q[3] to q[4]
+   - (s[0]=1, s[1]=0, s[2]=1, s[3]=1 → control qubits 0, 2, 3)
+4. Apply H to all input qubits (NOT the ancilla)
+5. Measure input qubits → reveals s directly
+
+Requirements:
+- Use 5 qubits (q[0-3] for input, q[4] for ancilla)
+- Prepare ancilla in |1⟩ state before Hadamards
+- Oracle: CNOT from q[0], q[2], q[3] to q[4] (positions where s has 1)
+- Apply final Hadamards only to input qubits
+- Measure input qubits → should give |1011⟩
+
+After measurement, the input register should read 1011 with probability 1.0.
+
+Provide the OpenQASM 2.0 circuit.""",
+    difficulty=ProblemDifficulty.VERY_HARD,
+    category=ProblemCategory.ALGORITHM,
+    expected=ExpectedOutput(
+        min_qubits=5,
+        max_qubits=5,
+        max_depth=10,
+        required_gates=["h", "x", "cx"],
+        expected_states={"10111": 1.0},  # 1011 in input register, 1 in ancilla
+        tolerance=0.05
+    ),
+    tags=["bernstein-vazirani", "oracle", "hidden-string", "query-complexity"],
+    requires_understanding=["Bernstein-Vazirani algorithm", "Oracle construction", "Phase kickback"],
+    common_mistakes=["Wrong oracle CNOTs", "Missing ancilla preparation", "Hadamards on ancilla"],
+    optimal_depth=6,
+    optimal_gate_count=15
+)
+
+VERY_HARD_PROBLEMS = [
+    PROBLEM_VH1_QFT_4QUBIT,
+    PROBLEM_VH2_GROVER_3QUBIT,
+    PROBLEM_VH3_VQE_ANSATZ,
+    PROBLEM_VH4_BERNSTEIN_VAZIRANI
+]
+
+ALL_PROBLEMS = EASY_PROBLEMS + MEDIUM_PROBLEMS + HARD_PROBLEMS + VERY_HARD_PROBLEMS
+
+# Problem registry by ID
+PROBLEMS_BY_ID = {p.id: p for p in ALL_PROBLEMS}
+
+
+def get_problem(problem_id: str) -> Optional[TestProblem]:
+    """Get a problem by ID."""
+    return PROBLEMS_BY_ID.get(problem_id)
+
+
+def get_problems_by_difficulty(difficulty: ProblemDifficulty) -> List[TestProblem]:
+    """Get all problems of a specific difficulty."""
+    # Handle string input
+    if isinstance(difficulty, str):
+        difficulty = ProblemDifficulty(difficulty.lower())
+    return [p for p in ALL_PROBLEMS if p.difficulty == difficulty]
+
+
+def get_problems_by_category(category: ProblemCategory) -> List[TestProblem]:
+    """Get all problems of a specific category."""
+    return [p for p in ALL_PROBLEMS if p.category == category]
+
+
+def get_problems_by_tag(tag: str) -> List[TestProblem]:
+    """Get all problems with a specific tag."""
+    return [p for p in ALL_PROBLEMS if tag in p.tags]
+
+
+def get_research_problem_set() -> List[TestProblem]:
+    """Get the standard research evaluation set (3 problems, one per difficulty)."""
+    return [
+        PROBLEM_E1_PHASE_FLIP,      # Easy: Phase flip state
+        PROBLEM_M1_SWAP_DECOMPOSITION,  # Medium: SWAP decomposition
+        PROBLEM_H1_DEUTSCH          # Hard: Deutsch algorithm
+    ]

tests/test_quality_analyzer.py

@@ -0,0 +1,42 @@
+# Path: QAgents-workflos/test_quality_analyzer.py
+# Description: Test the circuit quality analyzer
+"""Test that quality analyzer works with MCP endpoints."""
+
+from tests.circuit_quality_analyzer import CircuitQualityAnalyzer, get_analyzer
+
+def test_analyzer():
+    analyzer = get_analyzer()
+    
+    # Test with a Bell state circuit
+    test_qasm = """OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2];
+creg c[2];
+h q[0];
+cx q[0], q[1];
+measure q -> c;
+"""
+
+    print("Analyzing Bell state circuit...")
+    print("-" * 40)
+    
+    result = analyzer.analyze_circuit(test_qasm)
+    
+    print(f"Syntax Valid: {result.syntax_valid}")
+    print(f"Depth: {result.depth}")
+    print(f"Gate Count: {result.gate_count}")
+    print(f"CX Count: {result.cx_count}")
+    print(f"Single Qubit Count: {result.single_qubit_count}")
+    print(f"Hardware Fitness: {result.hardware_fitness}")
+    print(f"Complexity Score: {result.complexity_score}")
+    print(f"State Correctness: {result.state_correctness}")
+    print(f"Noise Estimate: {result.noise_estimate}")
+    print(f"Probabilities: {result.probabilities}")
+    
+    if result.errors:
+        print(f"\nErrors/Warnings:")
+        for err in result.errors:
+            print(f"  - {err}")
+
+if __name__ == "__main__":
+    test_analyzer()

tests/test_ratelimited.py

@@ -0,0 +1,37 @@
+"""
+Quick test of rate-limited evaluation on easy problems.
+"""
+import os
+from tests.evaluation_harness import EvaluationHarness
+from tests.test_problems import EASY_PROBLEMS, MEDIUM_PROBLEMS, HARD_PROBLEMS
+
+# Combine all problems
+TEST_PROBLEMS = EASY_PROBLEMS + MEDIUM_PROBLEMS + HARD_PROBLEMS
+
+# Ensure API key is set
+os.environ["GOOGLE_API_KEY"] = "$env:GOOGLE_API_KEY"
+
+print("=== RATE-LIMITED EVALUATION TEST ===")
+print("Testing Guided mode (4 LLM calls per problem)")
+print("Rate limit: 5 seconds between requests")
+print("")
+
+# Run only 3 easy problems with guided mode
+harness = EvaluationHarness()
+easy_problems = [p for p in TEST_PROBLEMS if p.id.startswith('easy')][:3]
+
+print(f"Testing {len(easy_problems)} problems with Guided orchestration\n")
+results = []
+
+for problem in easy_problems:
+    print(f"Problem: {problem.name}")
+    result = harness.evaluate_single_run(problem, mode='guided', run_number=1)
+    results.append(result)
+    print(f"  Success: {result.success}, Time: {result.execution_time_ms:.1f}ms\n")
+
+# Summary
+successes = sum(1 for r in results if r.success)
+print("=== SUMMARY ===")
+print(f"Success rate: {successes}/{len(results)} ({100*successes/len(results):.0f}%)")
+print(f"Total API calls: ~{len(results) * 4} LLM requests")
+print(f"Expected time with rate limiting: ~{len(results) * 4 * 5 / 60:.1f} minutes")

tools/__init__.py

@@ -0,0 +1,54 @@
+"""Tools module: MCP endpoint wrappers as callable tools."""
+
+from .tool_registry import (
+    ToolDefinition,
+    ToolCategory,
+    ToolRegistry,
+    registry,
+    register_tool
+)
+
+from .quantum_tools import (
+    get_all_tools,
+    get_tools_by_category,
+    invoke_tool,
+    # Creation tools
+    create_from_template,
+    generate_random_circuit,
+    generate_from_description,
+    # Analysis tools
+    parse_qasm,
+    analyze_circuit,
+    get_circuit_depth,
+    # Validation tools
+    validate_syntax,
+    check_connectivity,
+    verify_unitary,
+    # Simulation tools
+    simulate_circuit,
+    get_statevector,
+    get_probabilities,
+    # Scoring tools
+    calculate_complexity,
+    calculate_hardware_fitness,
+    calculate_expressibility,
+    # Resource tools
+    estimate_resources,
+    estimate_noise,
+    # Composition tools
+    compose_circuits,
+    generate_inverse,
+    tensor_circuits,
+    repeat_circuit
+)
+
+__all__ = [
+    "ToolDefinition",
+    "ToolCategory", 
+    "ToolRegistry",
+    "registry",
+    "register_tool",
+    "get_all_tools",
+    "get_tools_by_category",
+    "invoke_tool"
+]

tools/quantum_tools.py

@@ -0,0 +1,346 @@
+"""
+Quantum Tools: MCP endpoint wrappers registered as tools.
+All 23 MCP endpoints wrapped as callable tools for agents.
+"""
+
+from typing import Any, Dict, Optional
+from .tool_registry import register_tool, ToolCategory, registry
+
+# Import client lazily to avoid circular imports
+def _get_client():
+    from client import get_client
+    return get_client()
+
+
+# ===== CREATION TOOLS =====
+
+@register_tool(
+    name="create_from_template",
+    description="Create a quantum circuit from a predefined template (bell_state, ghz, qft, grover, etc.)",
+    category=ToolCategory.CREATION,
+    parameters={
+        "template": {"type": "string", "description": "Template name", "required": True},
+        "num_qubits": {"type": "integer", "description": "Number of qubits", "required": False}
+    },
+    returns="QASM code of the created circuit"
+)
+def create_from_template(template: str, num_qubits: int = 2) -> Dict:
+    response = _get_client().create_circuit_from_template(template, num_qubits)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+@register_tool(
+    name="generate_random_circuit",
+    description="Generate a random quantum circuit with specified parameters",
+    category=ToolCategory.CREATION,
+    parameters={
+        "num_qubits": {"type": "integer", "description": "Number of qubits", "required": True},
+        "depth": {"type": "integer", "description": "Circuit depth", "required": True},
+        "gate_set": {"type": "string", "description": "Comma-separated gates (h,cx,rz)", "required": False}
+    },
+    returns="QASM code of the random circuit"
+)
+def generate_random_circuit(num_qubits: int, depth: int, gate_set: str = "h,cx,rz") -> Dict:
+    response = _get_client().generate_random_circuit(num_qubits, depth, gate_set)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+@register_tool(
+    name="generate_from_description",
+    description="Generate a circuit from natural language description",
+    category=ToolCategory.CREATION,
+    parameters={
+        "description": {"type": "string", "description": "Natural language description of the circuit", "required": True}
+    },
+    returns="QASM code of the generated circuit"
+)
+def generate_from_description(description: str) -> Dict:
+    response = _get_client().generate_circuit_from_description(description)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+# ===== ANALYSIS TOOLS =====
+
+@register_tool(
+    name="parse_qasm",
+    description="Parse OpenQASM code and extract circuit structure",
+    category=ToolCategory.ANALYSIS,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Parsed circuit structure with gates, qubits, etc."
+)
+def parse_qasm(qasm: str) -> Dict:
+    response = _get_client().parse_qasm(qasm)
+    return {"success": response.success, "structure": response.data, "error": response.error}
+
+
+@register_tool(
+    name="analyze_circuit",
+    description="Analyze circuit properties: depth, gate count, qubit usage",
+    category=ToolCategory.ANALYSIS,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Circuit analysis with depth, gate counts, etc."
+)
+def analyze_circuit(qasm: str) -> Dict:
+    response = _get_client().analyze_circuit(qasm)
+    return {"success": response.success, "analysis": response.data, "error": response.error}
+
+
+@register_tool(
+    name="get_circuit_depth",
+    description="Get the depth of a quantum circuit",
+    category=ToolCategory.ANALYSIS,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Integer depth value"
+)
+def get_circuit_depth(qasm: str) -> Dict:
+    response = _get_client().get_circuit_depth(qasm)
+    return {"success": response.success, "depth": response.data, "error": response.error}
+
+
+# ===== VALIDATION TOOLS =====
+
+@register_tool(
+    name="validate_syntax",
+    description="Validate QASM syntax for correctness",
+    category=ToolCategory.VALIDATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Validation result with any syntax errors"
+)
+def validate_syntax(qasm: str) -> Dict:
+    response = _get_client().validate_syntax(qasm)
+    return {"success": response.success, "valid": response.data, "error": response.error}
+
+
+@register_tool(
+    name="check_connectivity",
+    description="Check if circuit respects hardware qubit connectivity",
+    category=ToolCategory.VALIDATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True},
+        "hardware": {"type": "string", "description": "Hardware profile (ibm_eagle, ionq_aria, rigetti_aspen)", "required": False}
+    },
+    returns="Connectivity check result"
+)
+def check_connectivity(qasm: str, hardware: str = "ibm_eagle") -> Dict:
+    response = _get_client().check_connectivity(qasm, hardware)
+    return {"success": response.success, "result": response.data, "error": response.error}
+
+
+@register_tool(
+    name="verify_unitary",
+    description="Verify that circuit produces a valid unitary matrix",
+    category=ToolCategory.VALIDATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Unitary verification result"
+)
+def verify_unitary(qasm: str) -> Dict:
+    response = _get_client().verify_unitary(qasm)
+    return {"success": response.success, "result": response.data, "error": response.error}
+
+
+# ===== SIMULATION TOOLS =====
+
+@register_tool(
+    name="simulate_circuit",
+    description="Simulate circuit execution and get measurement results",
+    category=ToolCategory.SIMULATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True},
+        "shots": {"type": "integer", "description": "Number of measurement shots", "required": False}
+    },
+    returns="Measurement results with counts"
+)
+def simulate_circuit(qasm: str, shots: int = 1024) -> Dict:
+    response = _get_client().simulate_circuit(qasm, shots)
+    return {"success": response.success, "results": response.data, "error": response.error}
+
+
+@register_tool(
+    name="get_statevector",
+    description="Get the statevector of a circuit (no measurement)",
+    category=ToolCategory.SIMULATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Statevector as complex amplitudes"
+)
+def get_statevector(qasm: str) -> Dict:
+    response = _get_client().get_statevector(qasm)
+    return {"success": response.success, "statevector": response.data, "error": response.error}
+
+
+@register_tool(
+    name="get_probabilities",
+    description="Get probability distribution from circuit",
+    category=ToolCategory.SIMULATION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Probability distribution over computational basis states"
+)
+def get_probabilities(qasm: str) -> Dict:
+    response = _get_client().get_probabilities(qasm)
+    return {"success": response.success, "probabilities": response.data, "error": response.error}
+
+
+# ===== SCORING TOOLS =====
+
+@register_tool(
+    name="calculate_complexity",
+    description="Calculate circuit complexity score (lower is better)",
+    category=ToolCategory.SCORING,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Complexity score and breakdown"
+)
+def calculate_complexity(qasm: str) -> Dict:
+    response = _get_client().calculate_complexity_score(qasm)
+    return {"success": response.success, "score": response.data, "error": response.error}
+
+
+@register_tool(
+    name="calculate_hardware_fitness",
+    description="Calculate how well circuit fits target hardware",
+    category=ToolCategory.SCORING,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True},
+        "hardware": {"type": "string", "description": "Hardware profile", "required": False}
+    },
+    returns="Hardware fitness score (higher is better)"
+)
+def calculate_hardware_fitness(qasm: str, hardware: str = "ibm_eagle") -> Dict:
+    response = _get_client().calculate_hardware_fitness(qasm, hardware)
+    return {"success": response.success, "score": response.data, "error": response.error}
+
+
+@register_tool(
+    name="calculate_expressibility",
+    description="Calculate circuit expressibility (ability to explore state space)",
+    category=ToolCategory.SCORING,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Expressibility score"
+)
+def calculate_expressibility(qasm: str) -> Dict:
+    response = _get_client().calculate_expressibility(qasm)
+    return {"success": response.success, "score": response.data, "error": response.error}
+
+
+# ===== RESOURCE TOOLS =====
+
+@register_tool(
+    name="estimate_resources",
+    description="Estimate resource requirements (qubits, gates, depth)",
+    category=ToolCategory.RESOURCE,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Resource estimation breakdown"
+)
+def estimate_resources(qasm: str) -> Dict:
+    response = _get_client().estimate_resources(qasm)
+    return {"success": response.success, "resources": response.data, "error": response.error}
+
+
+@register_tool(
+    name="estimate_noise",
+    description="Estimate noise impact on circuit execution",
+    category=ToolCategory.RESOURCE,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True},
+        "hardware": {"type": "string", "description": "Hardware profile", "required": False}
+    },
+    returns="Noise estimation"
+)
+def estimate_noise(qasm: str, hardware: str = "ibm_eagle") -> Dict:
+    response = _get_client().estimate_noise(qasm, hardware)
+    return {"success": response.success, "noise": response.data, "error": response.error}
+
+
+# ===== COMPOSITION TOOLS =====
+
+@register_tool(
+    name="compose_circuits",
+    description="Compose two circuits sequentially",
+    category=ToolCategory.COMPOSITION,
+    parameters={
+        "qasm1": {"type": "string", "description": "First circuit QASM", "required": True},
+        "qasm2": {"type": "string", "description": "Second circuit QASM", "required": True},
+        "qubit_mapping": {"type": "string", "description": "Qubit mapping (e.g., '0:1,1:0')", "required": False}
+    },
+    returns="Composed circuit QASM"
+)
+def compose_circuits(qasm1: str, qasm2: str, qubit_mapping: str = "") -> Dict:
+    response = _get_client().compose_circuits(qasm1, qasm2, qubit_mapping)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+@register_tool(
+    name="generate_inverse",
+    description="Generate the inverse (adjoint) of a circuit",
+    category=ToolCategory.COMPOSITION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True}
+    },
+    returns="Inverse circuit QASM"
+)
+def generate_inverse(qasm: str) -> Dict:
+    response = _get_client().generate_inverse_circuit(qasm)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+@register_tool(
+    name="tensor_circuits",
+    description="Create tensor product of two circuits (parallel composition)",
+    category=ToolCategory.COMPOSITION,
+    parameters={
+        "qasm1": {"type": "string", "description": "First circuit QASM", "required": True},
+        "qasm2": {"type": "string", "description": "Second circuit QASM", "required": True}
+    },
+    returns="Tensored circuit QASM"
+)
+def tensor_circuits(qasm1: str, qasm2: str) -> Dict:
+    response = _get_client().tensor_circuits(qasm1, qasm2)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+@register_tool(
+    name="repeat_circuit",
+    description="Repeat a circuit n times",
+    category=ToolCategory.COMPOSITION,
+    parameters={
+        "qasm": {"type": "string", "description": "OpenQASM code", "required": True},
+        "n": {"type": "integer", "description": "Number of repetitions", "required": True}
+    },
+    returns="Repeated circuit QASM"
+)
+def repeat_circuit(qasm: str, n: int) -> Dict:
+    response = _get_client().repeat_circuit(qasm, n)
+    return {"success": response.success, "qasm": response.data, "error": response.error}
+
+
+# ===== UTILITY FUNCTIONS =====
+
+def get_all_tools():
+    """Get all registered tools."""
+    return registry.get_all()
+
+def get_tools_by_category(category: ToolCategory):
+    """Get tools by category."""
+    return registry.get_by_category(category)
+
+def invoke_tool(name: str, **kwargs):
+    """Invoke a tool by name."""
+    return registry.invoke(name, **kwargs)

tools/tool_registry.py

@@ -0,0 +1,118 @@
+"""
+Tools Module: Wrapped MCP endpoints as callable tools for agents.
+Each tool is a self-contained function that can be invoked by agents.
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+import json
+
+class ToolCategory(Enum):
+    """Categories of tools for agent specialization."""
+    CREATION = "creation"
+    ANALYSIS = "analysis" 
+    VALIDATION = "validation"
+    SIMULATION = "simulation"
+    SCORING = "scoring"
+    COMPOSITION = "composition"
+    RESOURCE = "resource"
+
+@dataclass
+class ToolDefinition:
+    """Definition of a tool that agents can use."""
+    name: str
+    description: str
+    category: ToolCategory
+    parameters: Dict[str, Dict]  # name -> {type, description, required}
+    function: Callable
+    returns: str
+    
+    def to_llm_schema(self) -> Dict:
+        """Convert to OpenAI function calling format."""
+        properties = {}
+        required = []
+        
+        for name, info in self.parameters.items():
+            properties[name] = {
+                "type": info.get("type", "string"),
+                "description": info.get("description", "")
+            }
+            if info.get("required", False):
+                required.append(name)
+                
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required
+                }
+            }
+        }
+
+
+class ToolRegistry:
+    """Registry of all available tools."""
+    
+    def __init__(self):
+        self._tools: Dict[str, ToolDefinition] = {}
+        self._by_category: Dict[ToolCategory, List[str]] = {cat: [] for cat in ToolCategory}
+        
+    def register(self, tool: ToolDefinition):
+        """Register a tool."""
+        self._tools[tool.name] = tool
+        self._by_category[tool.category].append(tool.name)
+        
+    def get(self, name: str) -> Optional[ToolDefinition]:
+        """Get a tool by name."""
+        return self._tools.get(name)
+        
+    def get_by_category(self, category: ToolCategory) -> List[ToolDefinition]:
+        """Get all tools in a category."""
+        return [self._tools[name] for name in self._by_category[category]]
+        
+    def get_all(self) -> List[ToolDefinition]:
+        """Get all registered tools."""
+        return list(self._tools.values())
+        
+    def get_llm_schemas(self, categories: Optional[List[ToolCategory]] = None) -> List[Dict]:
+        """Get OpenAI function schemas for specified categories."""
+        if categories is None:
+            tools = self.get_all()
+        else:
+            tools = []
+            for cat in categories:
+                tools.extend(self.get_by_category(cat))
+        return [t.to_llm_schema() for t in tools]
+        
+    def invoke(self, name: str, **kwargs) -> Any:
+        """Invoke a tool by name with arguments."""
+        tool = self.get(name)
+        if tool is None:
+            raise ValueError(f"Unknown tool: {name}")
+        return tool.function(**kwargs)
+
+
+# Global registry
+registry = ToolRegistry()
+
+
+def register_tool(name: str, description: str, category: ToolCategory,
+                  parameters: Dict, returns: str):
+    """Decorator to register a function as a tool."""
+    def decorator(func: Callable):
+        tool = ToolDefinition(
+            name=name,
+            description=description,
+            category=category,
+            parameters=parameters,
+            function=func,
+            returns=returns
+        )
+        registry.register(tool)
+        return func
+    return decorator