init

README.md

@@ -0,0 +1,19 @@
+---
+title: QThink Agentic POC
+emoji: ⚛️
+colorFrom: blue
+colorTo: indigo
+sdk: fastapi
+app_file: main.py
+---
+
+# QThink Agentic Proof-of-Concept API
+
+This repository contains the proof-of-concept (POC) API for the QThink hackathon project. This service is intended to be submitted as our "Inference Endpoint" link.
+
+It demonstrates the two core pillars of our project:
+
+1.  **`/tools/parse-quyaml-to-qasm`**: A tool endpoint that our agent uses. It accepts our novel, token-efficient QuYAML format and returns valid QASM 2.0. This proves our custom parser works.
+2.  **`/solve/agentic-trace`**: The **main demo endpoint**. This simulates our full agentic MCP (Multi-Context Protocol) workflow. It takes a user prompt and returns a complete "trace" of the conversation between our (mocked) Planner, Reasoner, and Verifier agents as they collaborate to solve the problem.
+
+This POC proves our architecture is sound and ready for the real K2 Think API in Stage 2. See the `/docs` endpoint for a full FastAPI interactive demo.

main.py

@@ -0,0 +1,88 @@
+from fastapi import FastAPI, Body, HTTPException
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any
+import time
+
+from mock_k2_api import call_mock_planner, call_mock_reasoner, call_mock_verifier
+from quyaml_parser import parse_quyaml_to_qiskit
+from qiskit.qasm2 import dumps as to_qasm2_str
+
+app = FastAPI(
+    title="QThink POC Demo - Agentic Workflow",
+    description="Proof-of-concept for the QThink Hackathon Project. This API demonstrates the full agentic MCP workflow.",
+    version="0.2.0"
+)
+
+# --- Pydantic Models ---
+class SimulationPrompt(BaseModel):
+    prompt: str
+
+class AgentStep(BaseModel):
+    agent: str
+    thought: str
+    output: Any = Field(..., description="The output of the agent, can be a string, list, or dict.")
+
+# --- Endpoints ---
+@app.post("/tools/parse-quyaml-to-qasm")
+async def parse_quyaml_endpoint(quyaml_body: str = Body(..., media_type="application/yaml",
+                                                      example="# QYAML v0.1: Bell State...")):
+    """
+    **TOOL ENDPOINT:** Proves the QuYAML parser (SDS) is realistic.
+    An agent would call this tool to convert QuYAML to QASM.
+    """
+    try:
+        quantum_circuit = parse_quyaml_to_qiskit(quyaml_body)
+        qasm_output = to_qasm2_str(quantum_circuit)
+        return {
+            "status": "success",
+            "qasm_2_0_output": qasm_output,
+            "text_diagram": str(quantum_circuit)
+        }
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Error parsing QuYAML: {str(e)}")
+
+@app.post("/solve/agentic-trace", response_model=Dict[str, Any])
+async def agentic_trace_endpoint(body: SimulationPrompt):
+    """
+    **MAIN ENDPOINT: Proves the Agentic MCP (SRS) is sound.**
+    
+    This endpoint simulates the full Orchestrator workflow, showing the
+    step-by-step 'trace' of agents (Planner, Reasoner, Verifier)
+    collaborating to solve the user's prompt.
+    """
+    start_time = time.time()
+    agent_trace: List[AgentStep] = []
+
+    try:
+        # --- Orchestrator: Step 1 - Call Planner Agent ---
+        agent_trace.append(AgentStep(agent="Orchestrator", thought="Prompt received. Sending to Planner Agent.", output=f"Prompt: {body.prompt}"))
+        plan = call_mock_planner(body.prompt)
+        agent_trace.append(AgentStep(agent="Planner", thought="I have analyzed the prompt and created a step-by-step plan.", output=plan))
+
+        # --- Orchestrator: Step 2 - Call Reasoner Agent in a loop ---
+        reasoner_results = []
+        for task in plan:
+            agent_trace.append(AgentStep(agent="Orchestrator", thought=f"Dispatching task to Reasoner Agent: {task}", output=""))
+            time.sleep(0.1) # Simulate network latency
+            result = call_mock_reasoner(task)
+            reasoner_results.append({"task": task, "result": result})
+            agent_trace.append(AgentStep(agent="Reasoner", thought=f"I have completed task: {task}", output=result))
+
+        # --- Orchestrator: Step 3 - Call Verifier Agent ---
+        agent_trace.append(AgentStep(agent="Orchestrator", thought="All reasoning steps complete. Sending full results to Verifier Agent.", output=reasoner_results))
+        verification = call_mock_verifier(agent_trace)
+        agent_trace.append(AgentStep(agent="Verifier", thought="I have analyzed the full trace for correctness.", output=verification))
+        
+        end_time = time.time()
+        
+        return {
+            "status": "success",
+            "total_time_seconds": round(end_time - start_time, 2),
+            "agent_trace": [step.dict() for step in agent_trace]
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/")
+async def root():
+    return {"message": "Welcome to the QThink Agentic POC API. See the /docs for interactive endpoints."}

mock_k2_api.py

@@ -0,0 +1,49 @@
+# This file simulates the K2 Think API for each agent in the MCP.
+
+MOCK_QFT_PLAN = [
+    "Task 1: Define initial 8D state vector for |101⟩.",
+    "Task 2: Apply Hadamard on qubit 0.",
+    "Task 3: Apply CPHASE(pi/2) from q[1] to q[0].",
+    "Task 4: Apply CPHASE(pi/4) from q[2] to q[0].",
+    "Task 5: Apply Hadamard on qubit 1.",
+    "Task 6: Apply CPHASE(pi/2) from q[2] to q[1].",
+    "Task 7: Apply Hadamard on qubit 2.",
+    "Task 8: Apply SWAP(0, 2).",
+    "Task 9: Consolidate and present final state vector."
+]
+
+MOCK_QFT_STEP_RESULTS = {
+    "Task 1": "Initial state |101⟩ is index 5. Vector: [0, 0, 0, 0, 0, 1, 0, 0]",
+    "Task 2": "Applying H(0). State becomes (1/sqrt(2)) * [0, 0, 0, 0, 1, -1, 0, 0]",
+    "Task 3": "Applying CPHASE(pi/2). Control q[1] is 0 for all non-zero states. Vector is unchanged.",
+    "Task 4": "Applying CPHASE(pi/4). Control q[2]=1, Target q[0]=1 for index 5. Phase e^(i*pi/4) is applied.",
+    "Task 5": "Applying H(1). Amplitudes for indices 4,5,6,7 are calculated.",
+    "Task 6": "Applying CPHASE(pi/2). Phase 'i' applied to indices 6 and 7.",
+    "Task 7": "Applying H(2). Final amplitudes calculated across all 8 indices.",
+    "Task 8": "Applying SWAP(0, 2). Indices [1,4], [3,6] are permuted.",
+    "Task 9": "Final state vector consolidated. Ready for verification."
+}
+
+MOCK_QFT_VERIFICATION = {
+    "status": "Verified",
+    "steps_checked": 9,
+    "mathematical_consistency": "High",
+    "final_state_hash": "a3f4b01e2c5d6f7a... (mock hash)",
+    "final_state_preview": "[0.353, -0.353, 0.353i, -0.353i, -0.25-0.25i, 0.25+0.25i, ...]"
+}
+
+def call_mock_planner(prompt: str) -> list:
+    """Simulates the Planner Agent."""
+    if "QFT" in prompt and "|101⟩" in prompt:
+        return MOCK_QFT_PLAN
+    return ["Task 1: Understand user prompt.", "Task 2: Formulate generic plan."]
+
+def call_mock_reasoner(task: str) -> str:
+    """Simulates the Reasoner Agent executing one task."""
+    return MOCK_QFT_STEP_RESULTS.get(task, f"Mock execution result for: {task}")
+
+def call_mock_verifier(full_trace: list) -> dict:
+    """Simulates the Verifier Agent checking the whole process."""
+    if len(full_trace) > 5:
+        return MOCK_QFT_VERIFICATION
+    return {"status": "Verification Failed", "reason": "Trace too short."}

quyaml_parser.py

@@ -0,0 +1,70 @@
+import yaml
+from qiskit import QuantumCircuit
+import re
+import numpy as np
+
+def parse_quyaml_to_qiskit(quyaml_string: str) -> QuantumCircuit:
+    """
+    Parses a QuYAML string into a Qiskit QuantumCircuit object.
+    """
+    try:
+        data = yaml.safe_load(quyaml_string)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid QuYAML format: {e}")
+
+    circuit_name = data.get('circuit', 'my_circuit')
+    
+    def get_reg_size(reg_str):
+        match = re.search(r'\[(\d+)\]', reg_str)
+        return int(match.group(1)) if match else 0
+        
+    q_size = get_reg_size(data.get('qreg', 'q[0]'))
+    c_size = get_reg_size(data.get('creg', 'c[0]'))
+    
+    if q_size == 0:
+        raise ValueError("QuYAML must define at least one quantum register (e.g., qreg: q[1])")
+        
+    qc = QuantumCircuit(q_size, c_size, name=circuit_name)
+
+    instructions = data.get('instructions', [])
+    for inst_str in instructions:
+        apply_instruction(qc, inst_str)
+        
+    return qc
+
+def apply_instruction(qc: QuantumCircuit, inst_str: str):
+    """
+    Parses a single QuYAML instruction string and applies it to the circuit.
+    """
+    parts = inst_str.split()
+    gate = parts[0].lower()
+    
+    def get_indices(target_strings):
+        indices = []
+        for s in target_strings:
+            match = re.search(r'\[(\d+)\]', s)
+            if match:
+                indices.append(int(match.group(1)))
+        return indices
+
+    targets = [p.replace(',', '') for p in parts[1:]]
+    q_indices = get_indices(targets)
+
+    try:
+        if gate == 'h':
+            qc.h(q_indices[0])
+        elif gate == 'x':
+            qc.x(q_indices[0])
+        elif gate == 'cx':
+            qc.cx(q_indices[0], q_indices[1])
+        elif gate == 'swap':
+            qc.swap(q_indices[0], q_indices[1])
+        elif gate.startswith('cphase'):
+            angle_str = re.search(r'\((.*?)\)', gate).group(1)
+            angle_map = {'pi/2': np.pi / 2, 'pi/4': np.pi / 4, 'pi': np.pi}
+            angle = angle_map.get(angle_str, float(angle_str))
+            qc.cp(angle, q_indices[0], q_indices[1])
+        elif gate == 'measure':
+            qc.measure(range(qc.num_qubits), range(qc.num_clbits))
+    except Exception as e:
+        raise ValueError(f"Could not parse instruction '{inst_str}'. Error: {e}")

requirements.txt

@@ -0,0 +1,6 @@
+fastapi
+uvicorn
+pyyaml
+qiskit
+pydantic
+numpy