chore: Updated README.

chore: Organised environment variables.

Author: anirbanbasu

README.md

@@ -9,10 +9,12 @@
 
 The DQA aka _difficult questions attempted_ project utilises large language model (LLM) agent(s) to perform _multi-hop question answering_ (MHQA).
 
-**Note that this repository is undergoing a complete overhaul of the [older, now obsolete, version of DQA](https://github.com/anirbanbasu/dqa-obsolete). The purpose of this overhaul is to standardise agent communication using the A2A protocol and to use the Dapr virtual actors to manage the backend logic.**
+_Note that this repository is undergoing a complete overhaul of the [older, now obsolete, version of DQA](https://github.com/anirbanbasu/dqa-obsolete). The purpose of this overhaul is to standardise agent communication using the A2A protocol and to use the Dapr virtual actors to manage the backend logic._
 
 ## Overview
-TBA
+DQA - Difficult Questions Attempted - is an agentic chatbot that attempts to answer non-trivial multi-hop questions using (large) language models (LLM) and tools available over the Model Context Protocol (MCP). The functionality of DQA is basic. As of late 2025, the functionality of DQA is available in most commercial chatbots.
+
+However, DQA is experimental with the emphasis on standardising agentic communication and managing backend functionality using Dapr-managed virtual actors. Although the instructions below explain the deployment of DQA on a single machine, it can be deployed and run on a Kubernetes cluster, with minimal modifications to the configuration.
 
 ## Installation
 
@@ -21,9 +23,36 @@ TBA
 - Configure Dapr to run [with docker](https://docs.dapr.io/operations/hosting/self-hosted/self-hosted-with-docker/).
 - Run `dapr init` to initialise `daprd` and the relevant containers.
 
+_If deployment over Kubernetes is desired then check [these deployment instructions](https://docs.dapr.io/operations/hosting/kubernetes/kubernetes-deploy/)_.
+
+## Configuration and environment variables
+
+There are two main configuration files.
+ - LLM configuration at `conf/llm.json`.
+ - MCP configuration at `conf/mcp.json`.
+
+There is already a default configuration provided for either of these.
+
+There are Dapr related configuration files too.
+ - The main Dapr application configuration at `dapr.yaml`. Change the various hosts and ports in this configuration if you want to use ports that are not the default ones.
+ - Dapr telemetry configuration at `.dapr/config.yaml`.
+ - Dapr hot-swappable component configuration files at `.dapr/components/`.
+
+The following environment variables are also relevant but not essential, except for `OLLAMA_API_KEY`.
+ - `OLLAMA_API_KEY`: The Ollama API key is required for MCP-based web-search and cloud hosted models on Ollama.
+ - `APP_LOG_LEVEL`: The general log level of the DQA app. Defaults to `INFO`.
+ - `DQA_MCP_SERVER_TRANSPORT`, `FASTMCP_HOST` and `FASTMCP_PORT`: These specify the transport type, the host and port for the built-in MCP server of DQA. The default values are `stdio`, `localhost` and `8000` respectively.
+ - `LLM_CONFIG_FILE` and `MCP_CONFIG_FILE`: These specify where the LLM and MCP configurations These default to `conf/llm.json` and `conf/mcp.json` respectively.
+ - [Gradio environment variables](https://www.gradio.app/guides/environment-variables) to configure the DQA web app. However, MCP server (not to be confused with DQA's built-in MCP server), SSR mode, API and public sharing will be disabled, irrespective of what is specified through the environment variables.
+ - `BROWSER_STATE_SECRET`: This is the secret used by Gradio to encrypt the browser state data. The default value is `a2a_dapr_bstate_secret`.
+ - `BROWSER_STATE_CHAT_HISTORIES`: This is the key in browser state used by Gradio to store the chat histories (local values).
+ - `APP_DAPR_SVC_HOST` and `APP_DAPR_SVC_PORT`: The host and port at which Dapr actor service will listen on. These default to `127.0.0.1` and `32768`. Should you change these, you must change the corresponding information in `dapr.yaml`.
+ - `DAPR_PUBSUB_NAME`: The configured name of the publish-subscribe component at `.dapr/components/pubsub.yaml`. Change this environment variable only if you change the corresponding pub-sub component configuration.
+ - `APP_A2A_SRV_HOST` and `APP_MHQA_A2A_SRV_PORT`: The host and port at which A2A endpoint will be available. These default to `127.0.0.1` and `32770`. Should you change these, you must change the corresponding information in `dapr.yaml`.
+
 ## Usage
 
-- Start the Dapr actor service and the A2A endpoints by running `./start_dapr_multi.sh`. (This will send the dapr sidecar processes in the background.)
+- Start the Dapr actor service and the A2A endpoints by running `./start_dapr_multi.sh`. (This will send the Dapr sidecar processes in the background.)
 - Invoke the A2A agent using JSON-RPC by calling `uv run dqa-cli --help` to learn about the various skills-based A2A endpoint invocations.
 - Or, start the Gradio web app by running `uv run dqa-web-app` and then browse to http://localhost:7860.
 - Once done, stop the dapr sidecars by running `./stop_dapr_multi.sh`.

src/dqa/__init__.py

@@ -1,7 +1,10 @@
 import logging
+from typing import ClassVar
 from rich.logging import RichHandler
 from environs import Env
 
+from marshmallow.validate import OneOf
+
 try:
     from icecream import ic
 
@@ -13,8 +16,45 @@
 env = Env()
 env.read_env()
 
+
+class ParsedEnvVars:
+    APP_LOG_LEVEL: str = env.str("APP_LOG_LEVEL", default="INFO").upper()
+    DQA_MCP_SERVER_TRANSPORT: str = env.str(
+        "DQA_MCP_SERVER_TRANSPORT",
+        default="stdio",
+        validate=OneOf(["stdio", "sse", "streamable-http"]),
+    )
+    FASTMCP_HOST: str = env.str("FASTMCP_HOST", default="localhost")
+    FASTMCP_PORT: int = env.int("FASTMCP_PORT", default=8000)
+    LLM_CONFIG_FILE: str = env.str("LLM_CONFIG_FILE", default="conf/llm.json")
+    MCP_CONFIG_FILE: str = env.str("MCP_CONFIG_FILE", default="conf/mcp.json")
+    APP_DAPR_SVC_HOST: str = env.str("APP_DAPR_SVC_HOST", default="127.0.0.1")
+    APP_DAPR_SVC_PORT: int = env.int("APP_DAPR_SVC_PORT", default=32768)
+    APP_A2A_SRV_HOST: str = env.str("APP_A2A_SRV_HOST", default="127.0.0.1")
+    APP_MHQA_A2A_SRV_PORT: int = env.int("APP_MHQA_A2A_SRV_PORT", default=32770)
+    APP_ECHO_A2A_SRV_PORT: int = env.int("APP_ECHO_A2A_SRV_PORT", default=32769)
+    DAPR_PUBSUB_NAME: str = env.str("DAPR_PUBSUB_NAME", default="pubsub")
+    MCP_SERVER_HOST: str = env.str("FASTMCP_HOST", default="localhost")
+    MCP_SERVER_PORT: int = env.int("FASTMCP_PORT", default=8000)
+    BROWSER_STATE_SECRET: str = env.str(
+        "BROWSER_STATE_SECRET", default="a2a_dapr_bstate_secret"
+    )
+    BROWSER_STATE_CHAT_HISTORIES: str = env.str(
+        "BROWSER_STATE_CHAT_HISTORIES", default="a2a_dapr_chat_histories"
+    )
+
+    _instance: ClassVar = None
+
+    def __new__(cls: type["ParsedEnvVars"]) -> "ParsedEnvVars":
+        if cls._instance is None:
+            # Create instance using super().__new__ to bypass any recursion
+            instance = super().__new__(cls)
+            cls._instance = instance
+        return cls._instance
+
+
 logging.basicConfig(
-    level=env.str("APP_LOG_LEVEL", default="INFO").upper(),
+    level=ParsedEnvVars().APP_LOG_LEVEL,
     format="%(message)s",
     datefmt="[%X]",
     handlers=[RichHandler()],

src/dqa/actor/mhqa.py

@@ -26,7 +26,7 @@
 from dapr.clients import DaprClient
 from pydantic import TypeAdapter
 
-from dqa import env
+from dqa import ParsedEnvVars
 from dqa.actor import MHQAActorMethods
 from dqa.model.mhqa import MCPToolInvocation, MHQAResponse
 
@@ -124,7 +124,7 @@ def __init__(self, ctx, actor_id):
     async def _on_activate(self) -> None:
         if not hasattr(self, "llm_config"):
             self.llm_config = {}
-            llm_config_file = env.str("LLM_CONFIG_FILE", default="conf/llm.json")
+            llm_config_file = ParsedEnvVars().LLM_CONFIG_FILE
             if os.path.exists(llm_config_file):
                 with open(llm_config_file, "r") as f:
                     self.llm_config = json.load(f)
@@ -133,7 +133,7 @@ async def _on_activate(self) -> None:
             self.mcp_features = []
             self.mcp_config = {}
             try:
-                mcp_config_file = env.str("MCP_CONFIG_FILE", default="conf/mcp.json")
+                mcp_config_file = ParsedEnvVars().MCP_CONFIG_FILE
                 if os.path.exists(mcp_config_file):
                     with open(mcp_config_file, "r") as f:
                         self.mcp_config = json.load(f)
@@ -261,7 +261,7 @@ async def respond(self, data: dict) -> dict:
                     tool_invocations=tool_invocations,
                 )
                 dc.publish_event(
-                    pubsub_name=env.str("DAPR_PUBSUB_NAME", default="pubsub"),
+                    pubsub_name=ParsedEnvVars().DAPR_PUBSUB_NAME,
                     topic_name=f"topic-{self.__class__.__name__}-{self.id}-respond",
                     data=response.model_dump_json().encode(),
                 )

src/dqa/cli/a2a.py

@@ -14,7 +14,7 @@
 
 import httpx
 
-from dqa import env
+from dqa import ParsedEnvVars
 
 from a2a.types import Message
 
@@ -68,11 +68,11 @@ def _interrupt_handler(self, signum: int, frame: FrameType | None):
 
     def _initialize(self):
         logger.debug("Initialising A2A server URLs...")
-        a2a_asgi_host = env.str("APP_A2A_SRV_HOST", "127.0.0.1")
-        echo_a2a_asgi_port = env.int("APP_ECHO_A2A_SRV_PORT", 32769)
+        a2a_asgi_host = ParsedEnvVars().APP_A2A_SRV_HOST
+        echo_a2a_asgi_port = ParsedEnvVars().APP_ECHO_A2A_SRV_PORT
         self.echo_base_url = f"http://{a2a_asgi_host}:{echo_a2a_asgi_port}"
 
-        mhqa_a2a_asgi_port = env.int("APP_ECHO_A2A_SRV_PORT", 32770)
+        mhqa_a2a_asgi_port = ParsedEnvVars().APP_MHQA_A2A_SRV_PORT
         self.mhqa_base_url = f"http://{a2a_asgi_host}:{mhqa_a2a_asgi_port}"
         logger.debug(f"Echo A2A base URL: {self.echo_base_url}")
         logger.debug(f"MHQA A2A base URL: {self.mhqa_base_url}")

src/dqa/mcp/primary.py

@@ -3,8 +3,7 @@
 import sys
 
 from fastmcp import FastMCP
-from dqa import env
-from marshmallow.validate import OneOf
+from dqa import ParsedEnvVars
 
 from dqa.mcp.ollama import app as ollama_mcp
 from dqa.mcp.datetime import app as datetime_mcp
@@ -36,16 +35,6 @@ def server():
 
 
 def main():  # pragma: no cover
-    MCP_SERVER_TRANSPORT = "DQA_MCP_SERVER_TRANSPORT"
-    DEFAULT__MCP_SERVER_TRANSPORT = "streamable-http"
-    ALLOWED__MCP_SERVER_TRANSPORT = ["stdio", "sse", "streamable-http"]
-
-    MCP_SERVER_HOST = "FASTMCP_HOST"
-    DEFAULT__MCP_SERVER_HOST = "localhost"
-
-    MCP_SERVER_PORT = "FASTMCP_PORT"
-    DEFAULT__MCP_SERVER_PORT = 8000
-
     def sigint_handler(signal, frame):
         """
         Signal handler to shut down the server gracefully.
@@ -56,11 +45,7 @@ def sigint_handler(signal, frame):
 
     signal.signal(signal.SIGINT, sigint_handler)
 
-    transport_type = env.str(
-        MCP_SERVER_TRANSPORT,
-        default=DEFAULT__MCP_SERVER_TRANSPORT,
-        validate=OneOf(ALLOWED__MCP_SERVER_TRANSPORT),
-    )
+    transport_type = ParsedEnvVars().DQA_MCP_SERVER_TRANSPORT
 
     app = server()
 
@@ -72,14 +57,8 @@ def sigint_handler(signal, frame):
     else:
         app.run(
             transport=transport_type,
-            host=env.str(
-                MCP_SERVER_HOST,
-                default=DEFAULT__MCP_SERVER_HOST,
-            ),
-            port=env.int(
-                MCP_SERVER_PORT,
-                default=DEFAULT__MCP_SERVER_PORT,
-            ),
+            host=ParsedEnvVars().MCP_SERVER_HOST,
+            port=ParsedEnvVars().MCP_SERVER_PORT,
             uvicorn_config={
                 "timeout_graceful_shutdown": 5,  # seconds
             },

src/dqa/server/dapr.py

@@ -12,7 +12,7 @@
 
 from contextlib import asynccontextmanager
 
-from dqa import env
+from dqa import ParsedEnvVars
 
 
 @asynccontextmanager
@@ -48,8 +48,8 @@ async def lifespan(app: FastAPI):
 def main():
     uvicorn.run(
         app,
-        host=env.str("APP_HOST", "127.0.0.1"),
-        port=env.int("APP_DAPR_SVC_PORT", 32768),
+        host=ParsedEnvVars().APP_DAPR_SVC_HOST,
+        port=ParsedEnvVars().APP_DAPR_SVC_PORT,
     )
 
 

src/dqa/server/echo_a2a.py

@@ -13,7 +13,7 @@
     AgentSkill,
 )
 
-from dqa import env
+from dqa import ParsedEnvVars
 from dqa.executor.echo_task import EchoAgentExecutor
 from dqa.model.echo_task import EchoAgentSkills
 
@@ -27,8 +27,8 @@ def sigint_handler(signal, frame):
         # This is absolutely necessary to exit the program
         sys.exit(0)
 
-    _a2a_uvicorn_host = env.str("APP_A2A_SRV_HOST", "127.0.0.1")
-    _a2a_uvicorn_port = env.int("APP_ECHO_A2A_SRV_PORT", 32769)
+    _a2a_uvicorn_host = ParsedEnvVars().APP_A2A_SRV_HOST
+    _a2a_uvicorn_port = ParsedEnvVars().APP_ECHO_A2A_SRV_PORT
     signal.signal(signal.SIGINT, sigint_handler)
 
     echo_skill = AgentSkill(

src/dqa/server/mhqa_a2a.py

@@ -13,7 +13,7 @@
     AgentSkill,
 )
 
-from dqa import env
+from dqa import ParsedEnvVars
 from dqa.executor.mhqa import MHQAAgentExecutor
 from dqa.model.mhqa import MHQAAgentSkills
 
@@ -27,8 +27,8 @@ def sigint_handler(signal, frame):
         # This is absolutely necessary to exit the program
         sys.exit(0)
 
-    _a2a_uvicorn_host = env.str("APP_A2A_SRV_HOST", "127.0.0.1")
-    _a2a_uvicorn_port = env.int("APP_MHQA_A2A_SRV_PORT", 32770)
+    _a2a_uvicorn_host = ParsedEnvVars().APP_A2A_SRV_HOST
+    _a2a_uvicorn_port = ParsedEnvVars().APP_MHQA_A2A_SRV_PORT
     signal.signal(signal.SIGINT, sigint_handler)
 
     respond_skill = AgentSkill(

src/dqa/web/gradio.py

@@ -12,7 +12,7 @@
 
 import httpx
 from pydantic import TypeAdapter
-from dqa import env
+from dqa import ParsedEnvVars
 import gradio as gr
 
 from dqa.client.a2a_mixin import A2AClientMixin
@@ -47,8 +47,8 @@ class GradioApp(A2AClientMixin):
 
     def __init__(self):
         # self.ui = None
-        self._mhqa_a2a_uvicorn_host = env.str("APP_A2A_SRV_HOST", "127.0.0.1")
-        self._mhqa_a2a_uvicorn_port = env.int("APP_ECHO_A2A_SRV_PORT", 32770)
+        self._mhqa_a2a_uvicorn_host = ParsedEnvVars().APP_A2A_SRV_HOST
+        self._mhqa_a2a_uvicorn_port = ParsedEnvVars().APP_MHQA_A2A_SRV_PORT
         self._mhqa_a2a_base_url = (
             f"http://{self._mhqa_a2a_uvicorn_host}:{self._mhqa_a2a_uvicorn_port}"
         )
@@ -82,7 +82,7 @@ def convert_mhqa_response_to_chat_messages(self, response: MHQAResponse):
                         content=f"Inputs: {tool_invocation.input}\nOutputs: {tool_invocation.output}\nMetadata: {tool_invocation.metadata}",
                         metadata={
                             "parent_id": message_id,
-                            "title": f"Tool used: {tool_invocation.name}",
+                            "title": f"⚙️ Tool used: {tool_invocation.name}",
                         },
                     )
                 )
@@ -129,8 +129,8 @@ def component_main_content(self):
                     gr.Markdown(GradioApp._MD_EU_AI_ACT_TRANSPARENCY)
                 with gr.Column(scale=3):
                     bstate_chat_histories = gr.BrowserState(
-                        storage_key="a2a_dapr_chat_histories",
-                        secret="a2a_dapr_bstate_secret",
+                        storage_key=ParsedEnvVars().BROWSER_STATE_CHAT_HISTORIES,
+                        secret=ParsedEnvVars().BROWSER_STATE_SECRET,
                     )
                     chatbot = gr.Chatbot(
                         type="messages",
@@ -375,7 +375,7 @@ async def btn_echo_clicked(
                                     MHQAResponse(
                                         thread_id=selected_chat_id,
                                         user_input=txt_input,
-                                        agent_output="...",
+                                        agent_output="🤔 thinking, please wait...",
                                     )
                                 )
                             )
@@ -445,7 +445,11 @@ async def btn_echo_clicked(
             return component
 
     def construct_ui(self):
-        with gr.Blocks(fill_width=True, fill_height=True) as self.ui:
+        with gr.Blocks(
+            fill_width=True,
+            fill_height=True,
+            theme=gr.themes.Monochrome(font="ui-sans-serif"),
+        ) as self.ui:
             gr.set_static_paths(
                 paths=[
                     GradioApp._APP_LOGO_PATH,
@@ -482,7 +486,12 @@ def sigint_handler(signal, frame):
     signal.signal(signal.SIGINT, sigint_handler)
 
     try:
-        app.construct_ui().queue().launch(share=False, ssr_mode=False, show_api=False)
+        app.construct_ui().queue().launch(
+            share=False,
+            ssr_mode=False,
+            show_api=False,
+            mcp_server=False,
+        )
     except InterruptedError:
         logger.warning("Gradio server interrupted, shutting down...")
     except Exception as e: