feat: add json tools output

app.py

@@ -5,25 +5,27 @@ from theory_tools import get_theory, get_theory_topics
 try:
     topics = get_theory_topics()
     topic_choices = list(topics.keys())
-except Exception as e:
+except Exception:
     topic_choices = ["Error loading topics"]
 
 # Create the Gradio interface with tabs
 with gr.Blocks(title="Quantum Circuits Learning Programme") as demo:
     gr.Markdown("# Quantum Circuits Learning Programme")
-    gr.Markdown("Learn about quantum circuits through interactive content from the Qiskit textbook.")
-    
+    gr.Markdown(
+        "Learn about quantum circuits through interactive content from the Qiskit textbook."
+    )
+
     with gr.Tabs():
         with gr.TabItem("Browse Topics"):
             topics_output = gr.JSON(label="Available Topics")
             topics_btn = gr.Button("Load Available Topics")
             topics_btn.click(fn=get_theory_topics, outputs=topics_output)
-            
+
         with gr.TabItem("Learn Theory"):
             topic_input = gr.Textbox(
                 label="Enter a Quantum Topic",
                 placeholder="e.g., teleportation, superdense coding, what is quantum",
-                info="Enter the name of a quantum topic to learn about"
+                info="Enter the name of a quantum topic to learn about",
             )
             theory_output = gr.Markdown(label="Theory Content")
             theory_btn = gr.Button("Get Theory Content")
@@ -31,4 +33,4 @@ with gr.Blocks(title="Quantum Circuits Learning Programme") as demo:
 
 # Launch the interface
 if __name__ == "__main__":
-    demo.launch(mcp_server=True)
+    demo.launch(mcp_server=True)

theory_tools.py

@@ -1,17 +1,19 @@
 import re
 import requests
 import nbformat
+import json
 
 
 RAW_ROOT = "https://raw.githubusercontent.com/Qiskit/textbook/main/notebooks/"
 # README locations we now support
 _SECTIONS: dict[str, str] = {
-    "intro":        "intro/README.md",
-    "ch-states":    "ch-states/README.md",
-    "ch-gates":     "ch-gates/README.md",
-    "ch-algorithms":"ch-algorithms/README.md",
+    "intro": "intro/README.md",
+    "ch-states": "ch-states/README.md",
+    "ch-gates": "ch-gates/README.md",
+    "ch-algorithms": "ch-algorithms/README.md",
 }
 
+
 # ───────────────────────────────────────────────────────────────────
 # internals
 # ───────────────────────────────────────────────────────────────────
@@ -33,9 +35,7 @@ def _discover_files() -> list[str]:
     for dir_key, readme in _SECTIONS.items():
         found = _scrape_readme(readme)
         # Prepend the directory path if the README gives bare filenames
-        prefixed = [
-            name if "/" in name else f"{dir_key}/{name}" for name in found
-        ]
+        prefixed = [name if "/" in name else f"{dir_key}/{name}" for name in found]
         files.extend(prefixed)
     return files
 
@@ -49,31 +49,45 @@ def _pretty(path: str) -> str:
 # ───────────────────────────────────────────────────────────────────
 # public tools
 # ───────────────────────────────────────────────────────────────────
-def get_theory_topics() -> dict[str, str]:
-    """Return a mapping of friendly topic names to notebook file paths.
-    
+def get_theory_topics() -> str:
+    """Return a structured list of available quantum theory topics.
+
     Discovers available Jupyter notebooks from the Qiskit textbook across all
     four main chapters (intro, ch-states, ch-gates, ch-algorithms) by scraping
     their respective README files.
-    
+
     Returns:
-        dict[str, str]: A dictionary mapping human-readable topic names to their
-            corresponding notebook file paths. For example:
-            {'What Is Quantum': 'intro/what-is-quantum.ipynb',
-            'Bloch Sphere': 'ch-states/bloch_sphere.ipynb'}
-            Returns an empty dictionary if network requests fail.
-    
+        str: JSON string containing a structured list of topics with title, slug, and path.
+            For example:
+            '{
+              "topics": [
+                {
+                  "title": "What Is Quantum?",
+                  "slug": "what-is-quantum",
+                  "path": "intro/what-is-quantum.ipynb"
+                }
+              ]
+            }'
+            Returns JSON with empty topics array if network requests fail.
+
     Note:
-        If network requests fail, returns an empty dictionary instead of
+        If network requests fail, returns JSON with empty topics array instead of
         falling back to hardcoded content.
     """
     try:
         discovered_files = _discover_files()
         if not discovered_files:
-            return {}
-        return {_pretty(p): p for p in discovered_files}
+            return json.dumps({"topics": []})
+
+        topics = []
+        for path in discovered_files:
+            title = _pretty(path)
+            slug = path.rsplit("/", 1)[-1].removesuffix(".ipynb")
+            topics.append({"title": title, "slug": slug, "path": path})
+
+        return json.dumps({"topics": topics}, indent=2)
     except Exception:
-        return {}
+        return json.dumps({"topics": []})
 
 
 def get_theory(
@@ -82,62 +96,87 @@ def get_theory(
     include_headers: bool = True,
 ) -> str:
     """Download and parse a Qiskit textbook notebook, returning its content as text.
-    
-    Accepts flexible topic identification: pretty names ("Teleportation"), 
+
+    Accepts flexible topic identification: pretty names ("Teleportation"),
     slugs ("teleportation"), or full paths ("intro/teleportation.ipynb").
     Downloads the notebook from GitHub and extracts its content.
-    
+
     Args:
         topic (str): The quantum topic to fetch. Can be:
             - Pretty name: "Teleportation", "What Is Quantum"
-            - Slug: "teleportation", "what-is-quantum"  
+            - Slug: "teleportation", "what-is-quantum"
             - Full path: "intro/teleportation.ipynb"
         markdown_only (bool, optional): If True, include only markdown cells.
             If False, also include code cells wrapped in ```python blocks.
             Defaults to True.
         include_headers (bool, optional): If True, prepend an H1 header with
             the topic name for better readability. Defaults to True.
-    
+
     Returns:
-        str: The concatenated content of the notebook as formatted text,
-            with cells separated by double newlines. Returns error messages
-            if the topic is not found or if network requests fail.
-    
+        str: JSON string containing the topic name and notebook content.
+            For example:
+            '{
+              "topic": "Teleportation",
+              "content": "# Teleportation\\n\\nQuantum teleportation is a process..."
+            }'
+            Returns JSON with error message in content field if topic not found
+            or network requests fail.
+
     Example:
-        >>> content = get_theory("teleportation")
-        >>> print(content[:100])
-        # Teleportation
-        
-        Quantum teleportation is a process by which quantum information...
+        >>> result = get_theory("teleportation")
+        >>> data = json.loads(result)
+        >>> print(data["topic"])
+        Teleportation
     """
-    topics = get_theory_topics()
+    topics_json = get_theory_topics()
+    topics_data = json.loads(topics_json)
+    topics = topics_data.get("topics", [])
 
     # Build lenient lookup table
     lookup: dict[str, str] = {}
-    for nice, path in topics.items():
-        slug = path.rsplit("/", 1)[-1].removesuffix(".ipynb")
-        lookup[nice.lower()] = path
+    for topic_info in topics:
+        title = topic_info["title"]
+        slug = topic_info["slug"]
+        path = topic_info["path"]
+
+        lookup[title.lower()] = path
         lookup[slug.lower()] = path
         lookup[path.lower()] = path
 
     key = topic.lower()
     if key not in lookup:
         if not topics:
-            return "Unable to get theory - no topics available (network may be down)"
-        available_topics = ', '.join(topics.keys())
-        return f"Topic unknown: '{topic}'. Available topics: {available_topics}"
+            return json.dumps(
+                {
+                    "topic": topic,
+                    "content": "Unable to get theory - no topics available (network may be down)",
+                }
+            )
+        available_topics = ", ".join([t["title"] for t in topics])
+        return json.dumps(
+            {
+                "topic": topic,
+                "content": f"Topic unknown: '{topic}'. Available topics: {available_topics}",
+            }
+        )
 
     path = lookup[key]
-    
+    topic_title = _pretty(path)
+
     try:
         raw_json = requests.get(f"{RAW_ROOT}{path}", timeout=20).text
         nb = nbformat.reads(raw_json, as_version=4)
     except Exception:
-        return "Unable to get theory - failed to download or parse notebook content"
+        return json.dumps(
+            {
+                "topic": topic_title,
+                "content": "Unable to get theory - failed to download or parse notebook content",
+            }
+        )
 
     chunks: list[str] = []
     if include_headers:
-        chunks.append(f"# {_pretty(path)}\n")
+        chunks.append(f"# {topic_title}\n")
 
     for cell in nb.cells:
         if cell.cell_type == "markdown":
@@ -145,4 +184,5 @@ def get_theory(
         elif cell.cell_type == "code" and not markdown_only:
             chunks.append(f"```python\n{cell.source}\n```")
 
-    return "\n\n".join(chunks)
+    content = "\n\n".join(chunks)
+    return json.dumps({"topic": topic_title, "content": content}, indent=2)