First commit

.gitattributes

@@ -0,0 +1 @@
+assets/*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/sync-to-hf-space.yml

@@ -0,0 +1,53 @@
+# .github/workflows/sync-to-hf-space.yml
+name: Sync to Hugging Face Space (a2a-validator)
+
+on:
+  push:
+    branches: ["main", "master"]
+  workflow_dispatch: {}  # optional manual run
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: hf-space-sync-a2a-validator
+      cancel-in-progress: false
+
+    # Hard-wire your Space coordinates here
+    env:
+      HF_USERNAME: ruslanmv
+      SPACE_NAME: a2a-validator
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Prepare Git
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git lfs install --local
+
+      - name: Force push GitHub → Hugging Face Space (GitHub is source of truth)
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          set -e
+          if [ -z "$HF_TOKEN" ]; then
+            echo "❌ Missing HF_TOKEN secret. Add it under: Settings → Secrets and variables → Actions → New repository secret."
+            exit 1
+          fi
+
+          # Build the authenticated remote URL *inside* the step so the secret expands.
+          REMOTE_URL="https://${HF_USERNAME}:${HF_TOKEN}@huggingface.co/spaces/${HF_USERNAME}/${SPACE_NAME}"
+
+          echo "🔁 Forcing HEAD → Space main (GitHub is the source of truth)..."
+          git push --force "$REMOTE_URL" HEAD:main
+
+          # Best-effort push for LFS objects (won't fail the job if none)
+          git lfs push --all "$REMOTE_URL" main || true
+
+          echo "✅ Sync complete: GitHub HEAD is now Space main."

.gitignore

@@ -0,0 +1,37 @@
+# Python artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment files
+.env
+
+# Test & coverage reports
+.cache/
+.pytest_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# IDE & OS files
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# RAG index files
+.faiss/
+/backup
+ copy *.*
+* copy.* 
+* copy *.py 

Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim
+
+# --- base env ---
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+# --- system deps ---
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl \
+ && rm -rf /var/lib/apt/lists/*
+
+# --- app dir ---
+WORKDIR /app
+
+# --- python deps (cache friendly layer) ---
+COPY requirements.txt ./
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+# --- copy app ---
+COPY . .
+
+# Hugging Face sets $PORT at runtime; keep a sane default for local runs
+ENV PORT=7860
+EXPOSE 7860
+
+# Optional: run as non-root
+# RUN useradd -ms /bin/bash appuser && chown -R appuser:appuser /app
+# USER appuser
+
+# --- start (shell form so $PORT expands) ---
+# --proxy-headers is helpful behind HF’s proxy
+CMD uvicorn app.main:app --host 0.0.0.0 --port $PORT --proxy-headers

LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

Makefile

@@ -0,0 +1,124 @@
+# ====================================================================================
+#
+#   M A T R I X - A I  :::  C O N T R O L   P R O G R A M
+#   "Know thyself."
+#
+#   Access programs with:  make help
+#
+# ====================================================================================
+
+# System & Colors
+BRIGHT_GREEN  := $(shell tput -T screen setaf 10)
+DIM_GREEN     := $(shell tput -T screen setaf 2)
+RESET         := $(shell tput -T screen sgr0)
+
+# Python / Venv
+SYS_PYTHON := python3
+VENV_DIR   := .venv
+PYTHON     := $(VENV_DIR)/bin/python
+PIP        := $(PYTHON) -m pip
+
+# App
+APP_MODULE := app.main:app
+PORT       := 7860
+
+# Docker / HF Spaces
+IMG_NAME   := a2a-validator:local
+SPACE_URL  ?= https://huggingface.co/spaces/ruslanmv/a2a-validator
+
+# Files & Dirs
+REQ        := requirements.txt
+TEST_DIR   := tests
+
+.DEFAULT_GOAL := help
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+help:
+	@echo
+	@echo "$(BRIGHT_GREEN)M A T R I X - A I ::: C O N T R O L   P R O G R A M$(RESET)"
+	@echo
+	@printf "$(BRIGHT_GREEN)  %-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "PROGRAM" "DESCRIPTION"
+	@printf "$(BRIGHT_GREEN)  %-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "----------------------" "--------------------------------------------------------"
+	@echo
+	@echo "$(BRIGHT_GREEN)Environment$(RESET)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "venv" "Create virtualenv (.venv)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "install" "Install deps into venv (incremental)"
+	@echo
+	@echo "$(BRIGHT_GREEN)Quality$(RESET)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "lint" "ruff check"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "fmt" "black + ruff fix"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "test" "pytest"
+	@echo
+	@echo "$(BRIGHT_GREEN)Run$(RESET)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "run" "Run uvicorn (PORT=$(PORT))"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "run-hot" "Run with --reload"
+	@echo
+	@echo "$(BRIGHT_GREEN)Docker$(RESET)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "docker-build" "Build local image ($(IMG_NAME))"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "docker-run" "Run local container (maps $(PORT))"
+	@echo
+	@echo "$(BRIGHT_GREEN)HF Spaces helpers$(RESET)"
+	@printf "  $(BRIGHT_GREEN)%-22s$(RESET) $(DIM_GREEN)%s$(RESET)\n" "space-url" "Echo the Space URL (set SPACE_URL=...)"
+	@echo
+
+# ---------------------------------------------------------------------------
+# Env
+# ---------------------------------------------------------------------------
+$(VENV_DIR)/bin/activate:
+	@test -d $(VENV_DIR) || $(SYS_PYTHON) -m venv $(VENV_DIR)
+
+venv: $(VENV_DIR)/bin/activate
+	@echo "$(DIM_GREEN)-> Upgrading pip/setuptools/wheel$(RESET)"
+	@$(PIP) install -U pip setuptools wheel >/dev/null
+
+install: venv
+	@echo "$(DIM_GREEN)-> Installing deps$(RESET)"
+	@$(PIP) install -r $(REQ)
+	@echo "$(BRIGHT_GREEN)OK$(RESET)"
+
+# ---------------------------------------------------------------------------
+# Quality
+# ---------------------------------------------------------------------------
+lint: venv
+	@$(PYTHON) -m ruff check app tests || true
+
+fmt: venv
+	@$(PYTHON) -m black app tests || true
+	@$(PYTHON) -m ruff check --fix app tests || true
+
+test: venv
+	@$(PYTHON) -m pytest -q --disable-warnings --maxfail=1 || true
+
+# ---------------------------------------------------------------------------
+# Run
+# ---------------------------------------------------------------------------
+run: install
+	@PORT=$(PORT) $(VENV_DIR)/bin/uvicorn $(APP_MODULE) --host 0.0.0.0 --port $(PORT)
+
+run-hot: install
+	@PORT=$(PORT) $(VENV_DIR)/bin/uvicorn $(APP_MODULE) --host 0.0.0.0 --port $(PORT) --reload
+
+# ---------------------------------------------------------------------------
+# Docker
+# ---------------------------------------------------------------------------
+docker-build:
+	@docker build -t $(IMG_NAME) .
+
+docker-run:
+	@docker run --rm -it -p $(PORT):$(PORT) -e PORT=$(PORT) $(IMG_NAME)
+
+# ---------------------------------------------------------------------------
+# HF Helpers
+# ---------------------------------------------------------------------------
+space-url:
+	@echo "Space: $(SPACE_URL)"
+
+# ---------------------------------------------------------------------------
+# Clean
+# ---------------------------------------------------------------------------
+clean:
+	@rm -rf .venv __pycache__ .pytest_cache .ruff_cache .mypy_cache dist build *.egg-info
+
+.PHONY: help venv install lint fmt test run run-hot kb kb-force docker-build docker-run space-url clean

README.md

@@ -0,0 +1,140 @@
+---
+title: A2A Validator
+emoji: 🔬
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+---
+
+# A2A Validator 🔬
+![](assets/2025-10-05-00-49-00.png)
+**A2A Validator** is a focused web app for testing AI agents that speak the **A2A (Agent-to-Agent) protocol**. Paste an agent URL, connect, and the app will fetch the agent’s discovery document, validate it against the protocol, and provide a real-time message terminal. It’s a tool designed for the build/integration loop: tight feedback, zero ceremony.
+
+The backend runs on **FastAPI** and **Socket.IO**, with a lightweight HTML/JS frontend. The core validator checks both the static **Agent Card** and the live events an agent emits. If the optional `a2a-sdk` is present, it's used for card resolution and streaming; if not, the app gracefully falls back to a "plain HTTP" mode for basic card linting.
+
+---
+
+## ✨ Features
+
+* **Inspector UI**: A clean interface at `/validator` to enter an agent URL and optional custom HTTP headers for auth or tenancy.
+* **Smart Card Resolution**: Forgivingly handles root URLs by following redirects and probing common well-known paths (e.g., `/.well-known/agent.json`).
+* **Inline Validation**: Pretty-prints the agent's JSON card and displays any validation errors or warnings directly in the UI.
+* **Live Chat Terminal**: When the `a2a-sdk` is installed, a real-time terminal connects via Socket.IO to stream messages to and from the agent.
+* **Real-time Message Linting**: Live messages are marked with ✅ (compliant) or ⚠️ (non-compliant). Click any message to view the raw JSON.
+* **Integrated Debug Console**: A resizable console shows raw server-side request/response logs, minimizing the need for browser DevTools.
+
+---
+
+## 🚀 Quick Start
+
+Create a virtual environment, install dependencies, and run the server:
+
+```bash
+# 1. Create venv and activate
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 2. Install dependencies for editable mode
+pip install -e .
+
+# 3. Run the development server
+make run
+````
+
+or
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
+```
+
+Point your browser to the Inspector UI:
+
+➡️ **http://localhost:7860/validator**
+
+You can also test the card fetch endpoint directly from your terminal:
+
+```bash
+curl -s -X POST localhost:7860/agent-card \
+  -H 'content-type: application/json' \
+  -d '{"url":"http://localhost:8080/","sid":"test"}' | jq
+```
+
+-----
+
+## 🛠️ How It Works
+
+The validator checks for common issues that break interoperability.
+
+  * **Agent Card Validation**: It checks for required fields (`name`, `description`, `url`, `capabilities`, `skills`, etc.), correct types, a semver-like version string, and a valid absolute URL.
+  * **Message Validation**: During a live session, it validates incoming events based on their `kind`. For example, `task` events must have an `id` and `status.state`, while `message` events must have a `parts` array and the correct `role`.
+
+### Architecture
+
+```mermaid
+flowchart LR
+    subgraph Browser
+        UI[Inspector UI]
+    end
+
+    subgraph Server [FastAPI App]
+        API[/POST /agent-card<br/>GET /validator/]
+        WS[[Socket.IO]]
+    end
+
+    subgraph Agent [A2A Agent]
+        RPC[(JSON-RPC Endpoint)]
+    end
+
+    UI -- HTTP & WebSocket --> Server
+    Server -- HTTP & JSON-RPC --> Agent
+```
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant U as UI
+    participant S as Server
+    participant A as Agent
+
+    U->>S: POST /agent-card { url, sid }
+    S->>A: Resolve + GET card (follows redirects)
+    A-->>S: Card JSON
+    S->>S: Validate Card
+    S-->>U: { card, validation_errors }
+
+    U->>S: socket 'initialize_client'
+    S-->>U: 'client_initialized'
+    U->>S: socket 'send_message' { message }
+    S->>A: JSON-RPC call / stream
+    A-->>S: Agent responses
+    S->>S: Validate each response
+    S-->>U: 'agent_response' with validation notes
+```
+
+-----
+
+## ⚙️ Configuration & Endpoints
+
+The application is designed to work out of the box with minimal setup.
+
+  * `GET /validator`: Serves the Inspector UI.
+  * `POST /agent-card`: The API endpoint for fetching and validating an Agent Card.
+  * `/socket.io`: The path for real-time WebSocket connections.
+  * `/healthz` & `/readyz`: Standard health check endpoints.
+
+Static assets are served from `app/static` and templates from `app/templates`. The main UI is `validator.html`, which extends a base template. The server creates an alias for `/agent-card` at the root, so the frontend script works correctly even when the validator is embedded in a larger application.
+
+-----
+
+## 🔍 Troubleshooting
+
+  * **307 Temporary Redirect**: If you paste a root URL (e.g., `http://my-agent/`) and see this, it often means the agent is redirecting to a docs page. The validator will automatically try to find the card at common paths like `/.well-known/agent.json`. If it still fails, try pasting the direct URL to the agent card JSON file.
+  * **404 Not Found on `/agent-card`**: Ensure the API route alias is correctly configured in your `app/main.py` file. This is crucial if the `validator_service` router is mounted behind a prefix.
+  * **"A2A SDK not installed"**: This is not an error but a feature. The app is running in its lightweight, HTTP-only mode. To enable chat and streaming tests, install the `a2a-sdk` package (`pip install "a2a-sdk[http-server]"`).
+
+-----
+
+## 📜 License
+
+This project is licensed under the **Apache-2.0 License**. Use it, tweak it, ship it.

app/bootstrap.py

@@ -0,0 +1,22 @@
+# app/bootstrap.py
+"""
+App bootstrap: load .env and configure logging as early as possible.
+This module should be imported once at process start (import side-effects).
+"""
+from __future__ import annotations
+
+import os
+from dotenv import load_dotenv
+
+# Load environment from configs/.env if present (non-fatal if missing)
+load_dotenv(dotenv_path=os.path.join("configs", ".env"))
+
+# Configure logging after env is loaded so LOG_LEVEL is respected
+try:
+    from app.core.logging import setup_logging  # noqa: E402
+    setup_logging()
+except Exception as e:
+    # Fallback to a minimal logger if our setup helper isn't available for any reason
+    import logging as _logging
+    _logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO").upper())
+    _logging.getLogger(__name__).warning("Fallback logging configured: %s", e)

app/core/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import os, yaml
+from pydantic import BaseModel, AnyHttpUrl
+from typing import Optional, List
+
+class ModelCfg(BaseModel):
+    # HF Router defaults (used when we reach the router)
+    name: str = "HuggingFaceH4/zephyr-7b-beta"
+    fallback: str = "mistralai/Mistral-7B-Instruct-v0.2"
+    max_new_tokens: int = 256
+    temperature: float = 0.2
+    provider: Optional[str] = None  # HF Router provider tag (e.g., "featherless-ai")
+
+    # New: provider-specific default models
+    groq_model: str = "llama-3.1-8b-instant"
+    gemini_model: str = "gemini-2.5-flash"
+
+class LimitsCfg(BaseModel):
+    rate_per_min: int = 60
+    cache_size: int = 256
+
+class RagCfg(BaseModel):
+    index_dataset: Optional[str] = None
+    top_k: int = 4
+
+class MatrixHubCfg(BaseModel):
+    base_url: AnyHttpUrl = "https://api.matrixhub.io"
+
+class SecurityCfg(BaseModel):
+    admin_token: Optional[str] = None
+
+class Settings(BaseModel):
+    model: ModelCfg = ModelCfg()
+    limits: LimitsCfg = LimitsCfg()
+    rag: RagCfg = RagCfg()
+    matrixhub: MatrixHubCfg = MatrixHubCfg()
+    security: SecurityCfg = SecurityCfg()
+
+    # New
+    provider_order: List[str] = ["groq", "gemini", "router"]  # cascade order
+    chat_backend: str = "multi"   # was "router"; "multi" enables cascade
+    chat_stream: bool = True
+
+    @staticmethod
+    def load() -> "Settings":
+        path = os.getenv("SETTINGS_FILE", "configs/settings.yaml")
+        data = {}
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+        settings = Settings.model_validate(data)
+
+        # Existing env overrides
+        if "MODEL_NAME" in os.environ:
+            settings.model.name = os.environ["MODEL_NAME"]
+        if "MODEL_FALLBACK" in os.environ:
+            settings.model.fallback = os.environ["MODEL_FALLBACK"]
+        if "MODEL_PROVIDER" in os.environ:
+            settings.model.provider = os.environ["MODEL_PROVIDER"]
+        if "ADMIN_TOKEN" in os.environ:
+            settings.security.admin_token = os.environ["ADMIN_TOKEN"]
+        if "RATE_LIMITS" in os.environ:
+            settings.limits.rate_per_min = int(os.environ["RATE_LIMITS"])
+        if "HF_CHAT_BACKEND" in os.environ:
+            settings.chat_backend = os.environ["HF_CHAT_BACKEND"].strip().lower()
+        if "CHAT_STREAM" in os.environ:
+            settings.chat_stream = os.environ["CHAT_STREAM"].lower() in ("1","true","yes","on")
+
+        # New env overrides
+        if "GROQ_MODEL" in os.environ:
+            settings.model.groq_model = os.environ["GROQ_MODEL"]
+        if "GEMINI_MODEL" in os.environ:
+            settings.model.gemini_model = os.environ["GEMINI_MODEL"]
+        if "PROVIDER_ORDER" in os.environ:
+            settings.provider_order = [p.strip().lower() for p in os.environ["PROVIDER_ORDER"].split(",") if p.strip()]
+
+        # Default to cascade
+        if settings.chat_backend not in ("multi", "router"):
+            settings.chat_backend = "multi"
+
+        return settings

app/core/inference/__init__.py

@@ -0,0 +1,3 @@
+from .client import ChatClient, chat, get_client
+
+__all__ = ["ChatClient", "chat", "get_client"]

app/core/inference/client.py

@@ -0,0 +1,287 @@
+# app/core/inference/client.py
+from __future__ import annotations
+
+"""
+Unified chat client module.
+
+- Exposes a production-ready MultiProvider cascade client (GROQ → Gemini → HF Router),
+  via ChatClient / chat(...).
+- Keeps the legacy RouterRequestsClient for direct access to the HF Router compatible
+  /v1/chat/completions endpoint, preserving backward compatibility.
+
+This file assumes:
+  - app/bootstrap.py exists and loads configs/.env + sets up logging.
+  - app/core/config.py provides Settings (with provider_order, etc.).
+  - app/core/inference/providers.py implements MultiProviderChat orchestrator.
+"""
+
+import os
+import json
+import time
+import logging
+from typing import Dict, List, Optional, Iterator, Tuple, Iterable, Union, Generator
+
+# Ensure .env & logging before we load settings/providers
+import app.bootstrap  # noqa: F401
+
+import requests
+
+from app.core.config import Settings
+from app.core.inference.providers import MultiProviderChat
+
+logger = logging.getLogger(__name__)
+
+# -----------------------------
+# Multi-provider cascade client
+# -----------------------------
+
+Message = Dict[str, str]
+
+class ChatClient:
+    """
+    Unified chat client that executes the configured provider cascade.
+    Providers are tried in order (settings.provider_order). First success wins.
+    """
+    def __init__(self, settings: Settings | None = None):
+        self._settings = settings or Settings.load()
+        self._chain = MultiProviderChat(self._settings)
+
+    def chat(
+        self,
+        messages: Iterable[Message],
+        temperature: Optional[float] = None,
+        max_new_tokens: Optional[int] = None,
+        stream: Optional[bool] = None,
+    ) -> Union[str, Generator[str, None, None]]:
+        """
+        Execute a chat completion using the provider cascade.
+
+        Args:
+            messages: Iterable of {"role": "system|user|assistant", "content": "..."}
+            temperature: Optional override for sampling temperature.
+            max_new_tokens: Optional override for max tokens.
+            stream: If None, uses settings.chat_stream. If True, returns a generator of text chunks.
+
+        Returns:
+            str (non-stream) or generator[str] (stream)
+        """
+        use_stream = self._settings.chat_stream if stream is None else bool(stream)
+        return self._chain.chat(
+            messages,
+            temperature=temperature,
+            max_new_tokens=max_new_tokens,
+            stream=use_stream,
+        )
+
+# Backward-compatible helpers
+_default_client: ChatClient | None = None
+
+def _get_default() -> ChatClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = ChatClient()
+    return _default_client
+
+def chat(
+    messages: Iterable[Message],
+    temperature: Optional[float] = None,
+    max_new_tokens: Optional[int] = None,
+    stream: Optional[bool] = None,
+) -> Union[str, Generator[str, None, None]]:
+    """
+    Convenience function using a process-wide default ChatClient.
+    """
+    return _get_default().chat(messages, temperature=temperature, max_new_tokens=max_new_tokens, stream=stream)
+
+def get_client(settings: Settings | None = None) -> ChatClient:
+    """
+    Factory for an explicit ChatClient bound to provided settings.
+    """
+    return ChatClient(settings)
+
+
+# ------------------------------------------------------
+# Legacy HF Router client (kept for backward compatibility)
+# ------------------------------------------------------
+
+ROUTER_URL = "https://router.huggingface.co/v1/chat/completions"
+
+def _require_token() -> str:
+    tok = os.getenv("HF_TOKEN")
+    if not tok:
+        raise ValueError("HF_TOKEN is not set. Put it in .env or export it before starting.")
+    return tok
+
+def _model_with_provider(model: str, provider: Optional[str]) -> str:
+    if provider and ":" not in model:
+        return f"{model}:{provider}"
+    return model
+
+def _mk_messages(system_prompt: Optional[str], user_text: str) -> List[Dict[str, str]]:
+    msgs: List[Dict[str, str]] = []
+    if system_prompt:
+        msgs.append({"role": "system", "content": system_prompt})
+    msgs.append({"role": "user", "content": user_text})
+    return msgs
+
+def _timeout_tuple(connect: float = 10.0, read: float = 60.0) -> Tuple[float, float]:
+    return (connect, read)
+
+class RouterRequestsClient:
+    """
+    Simple requests-only client for HF Router Chat Completions.
+    Supports non-streaming (returns str) and streaming (yields token strings).
+
+    NOTE: New code should prefer ChatClient above. This class is preserved for any
+    legacy call sites that rely on direct HF Router access.
+    """
+    def __init__(
+        self,
+        model: str,
+        fallback: Optional[str] = None,
+        provider: Optional[str] = None,
+        max_retries: int = 2,
+        connect_timeout: float = 10.0,
+        read_timeout: float = 60.0
+    ):
+        self.model = model
+        self.fallback = fallback if fallback != model else None
+        self.provider = provider
+        self.headers = {"Authorization": f"Bearer {_require_token()}"}
+        self.max_retries = max(0, int(max_retries))
+        self.timeout = _timeout_tuple(connect_timeout, read_timeout)
+
+    # -------- Non-stream (single text) --------
+    def chat_nonstream(
+        self,
+        system_prompt: Optional[str],
+        user_text: str,
+        max_tokens: int,
+        temperature: float,
+        stop: Optional[List[str]] = None,
+        frequency_penalty: Optional[float] = None,
+        presence_penalty: Optional[float] = None,
+    ) -> str:
+        payload = {
+            "model": _model_with_provider(self.model, self.provider),
+            "messages": _mk_messages(system_prompt, user_text),
+            "temperature": float(max(0.0, temperature)),
+            "max_tokens": int(max_tokens),
+            "stream": False,
+        }
+        if stop:
+            payload["stop"] = stop
+        if frequency_penalty is not None:
+            payload["frequency_penalty"] = float(frequency_penalty)
+        if presence_penalty is not None:
+            payload["presence_penalty"] = float(presence_penalty)
+
+        text, ok = self._try_once(payload)
+        if ok:
+            return text
+
+        # fallback (if configured)
+        if self.fallback:
+            payload["model"] = _model_with_provider(self.fallback, self.provider)
+            text, ok = self._try_once(payload)
+            if ok:
+                return text
+
+        raise RuntimeError(f"Chat non-stream failed: model={self.model} fallback={self.fallback}")
+
+    def _try_once(self, payload: dict) -> Tuple[str, bool]:
+        last_err: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = requests.post(ROUTER_URL, headers=self.headers, json=payload, timeout=self.timeout)
+                if r.status_code >= 400:
+                    logger.error("Router error %s: %s", r.status_code, r.text)
+                    last_err = RuntimeError(f"{r.status_code}: {r.text}")
+                    time.sleep(min(1.5 * (attempt + 1), 3.0))
+                    continue
+                data = r.json()
+                return data["choices"][0]["message"]["content"], True
+            except Exception as e:
+                logger.error("Router request failure: %s", e)
+                last_err = e
+                time.sleep(min(1.5 * (attempt + 1), 3.0))
+        if last_err:
+            logger.error("Router exhausted retries: %s", last_err)
+        return "", False
+
+    # -------- Streaming (yield token deltas) --------
+    def chat_stream(
+        self,
+        system_prompt: Optional[str],
+        user_text: str,
+        max_tokens: int,
+        temperature: float,
+        stop: Optional[List[str]] = None,
+        frequency_penalty: Optional[float] = None,
+        presence_penalty: Optional[float] = None,
+    ) -> Iterator[str]:
+        payload = {
+            "model": _model_with_provider(self.model, self.provider),
+            "messages": _mk_messages(system_prompt, user_text),
+            "temperature": float(max(0.0, temperature)),
+            "max_tokens": int(max_tokens),
+            "stream": True,
+        }
+        if stop:
+            payload["stop"] = stop
+        if frequency_penalty is not None:
+            payload["frequency_penalty"] = float(frequency_penalty)
+        if presence_penalty is not None:
+            payload["presence_penalty"] = float(presence_penalty)
+
+        # primary
+        ok = False
+        for token in self._stream_once(payload):
+            ok = True
+            yield token
+        if ok:
+            return
+        # fallback stream if primary produced nothing (or died immediately)
+        if self.fallback:
+            payload["model"] = _model_with_provider(self.fallback, self.provider)
+            for token in self._stream_once(payload):
+                yield token
+
+    def _stream_once(self, payload: dict) -> Iterator[str]:
+        try:
+            with requests.post(ROUTER_URL, headers=self.headers, json=payload, stream=True, timeout=self.timeout) as r:
+                if r.status_code >= 400:
+                    logger.error("Router stream error %s: %s", r.status_code, r.text)
+                    return
+                for line in r.iter_lines(decode_unicode=True):
+                    if not line:
+                        continue
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[len("data:"):].strip()
+                    if data == "[DONE]":
+                        return
+                    try:
+                        obj = json.loads(data)
+                        delta = obj["choices"][0]["delta"].get("content", "")
+                        if delta:
+                            yield delta
+                    except Exception as e:
+                        logger.warning("Stream JSON parse issue: %s | line=%r", e, line)
+                        continue
+        except Exception as e:
+            logger.error("Stream request failure: %s", e)
+            return
+
+    # -------- Planning (non-stream) --------
+    def plan_nonstream(self, system_prompt: str, user_text: str,
+                       max_tokens: int, temperature: float) -> str:
+        return self.chat_nonstream(system_prompt, user_text, max_tokens, temperature)
+
+
+__all__ = [
+    "ChatClient",
+    "chat",
+    "get_client",
+    "RouterRequestsClient",
+]

app/core/inference/providers.py

@@ -0,0 +1,402 @@
+# app/core/inference/providers.py
+from __future__ import annotations
+
+"""
+Provider layer for multi-backend LLM chat with a production-ready cascade:
+
+GROQ → Gemini → Hugging Face Inference Router (Zephyr → Mistral)
+
+- Each provider implements a common .chat(...) interface that returns either:
+    * str (non-stream), or
+    * Generator[str, None, None] (streaming text chunks)
+
+- MultiProviderChat orchestrates providers in a user-configurable order (Settings.provider_order)
+  and returns the first successful response.
+
+- Robustness:
+    * .env + logging are loaded via app.bootstrap import side-effect
+    * Requests session has retries and timeouts
+    * Provider initialization gracefully skips when keys/SDKs are missing
+    * Streaming uses SSE for HF Router; Groq uses SDK streaming; Gemini yields one chunk
+"""
+
+from typing import Any, Dict, Generator, Iterable, List, Optional, Union
+import json
+import logging
+import os
+import time
+
+# Ensure .env + logging configured even if imported directly
+import app.bootstrap  # noqa: F401
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+# Optional SDKs; handled gracefully if absent
+try:
+    from groq import Groq
+except Exception:  # pragma: no cover
+    Groq = None  # type: ignore
+
+try:
+    from google import genai
+except Exception:  # pragma: no cover
+    genai = None  # type: ignore
+
+from app.core.config import Settings
+
+logger = logging.getLogger(__name__)
+
+Message = Dict[str, str]  # {"role": "system|user|assistant", "content": "..."}
+
+
+# ---------- Errors ----------
+class ProviderError(RuntimeError):
+    """Raised for provider-specific configuration/runtime errors."""
+
+
+# ---------- Helpers ----------
+def _ensure_messages(msgs: Iterable[Message]) -> List[Message]:
+    """
+    Normalize incoming messages to a strict [{"role": str, "content": str}, ...] list.
+    """
+    out: List[Message] = []
+    for m in msgs:
+        role = m.get("role", "user")
+        content = m.get("content", "")
+        out.append({"role": role, "content": content})
+    return out
+
+
+def _requests_session_with_retries(
+    total: int = 3,
+    backoff: float = 0.3,
+    status_forcelist: Optional[List[int]] = None,
+    timeout: float = 60.0,
+) -> requests.Session:
+    """
+    Return a requests.Session configured with retries, connection pooling, and default timeouts.
+    """
+    status_forcelist = status_forcelist or [408, 429, 500, 502, 503, 504]
+    retry = Retry(
+        total=total,
+        read=total,
+        connect=total,
+        backoff_factor=backoff,
+        status_forcelist=status_forcelist,
+        allowed_methods=frozenset(["GET", "POST"]),
+        raise_on_status=False,
+    )
+    adapter = HTTPAdapter(max_retries=retry, pool_connections=10, pool_maxsize=10)
+    session = requests.Session()
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    # Store default timeout on session via a patched request method
+    session.request = _patch_request_with_timeout(session.request, timeout)  # type: ignore
+    return session
+
+
+def _patch_request_with_timeout(fn, timeout: float):
+    def wrapper(method, url, **kwargs):
+        if "timeout" not in kwargs:
+            kwargs["timeout"] = timeout
+        return fn(method, url, **kwargs)
+
+    return wrapper
+
+
+# ---------- GROQ ----------
+class GroqProvider:
+    """
+    Groq Chat Completions (OpenAI-compatible).
+    Requires:
+        - env: GROQ_API_KEY
+        - package: groq
+    """
+    name = "groq"
+
+    def __init__(self, model: str):
+        self.model = model
+        self.api_key = os.getenv("GROQ_API_KEY")
+        if not self.api_key:
+            raise ProviderError("GROQ_API_KEY is not set")
+        if Groq is None:
+            raise ProviderError("groq SDK not installed; add 'groq' to requirements.txt and pip install.")
+        # SDK reads key from env
+        self.client = Groq()
+
+    def chat(
+        self,
+        messages: Iterable[Message],
+        temperature: float,
+        max_new_tokens: int,
+        stream: bool,
+    ) -> Union[str, Generator[str, None, None]]:
+        msgs = _ensure_messages(messages)
+        try:
+            completion = self.client.chat.completions.create(
+                model=self.model,
+                messages=msgs,
+                temperature=float(temperature),
+                max_tokens=int(max_new_tokens),
+                top_p=1,
+                stream=bool(stream),
+            )
+            if stream:
+                def gen():
+                    for chunk in completion:
+                        try:
+                            delta = chunk.choices[0].delta
+                            part = getattr(delta, "content", None)
+                            if part:
+                                yield part
+                        except Exception:
+                            continue
+                return gen()
+            else:
+                # Non-streaming: return final message content
+                return completion.choices[0].message.content or ""
+        except Exception as e:
+            raise ProviderError(f"GROQ error: {e}") from e
+
+
+# ---------- GEMINI ----------
+class GeminiProvider:
+    """
+    Google Gemini via google-genai.
+    Requires:
+        - env: GOOGLE_API_KEY
+        - package: google-genai
+
+    Role mapping:
+        - system → system_instruction (joined)
+        - user   → role 'user'
+        - assistant → role 'model'
+    """
+    name = "gemini"
+
+    def __init__(self, model: str):
+        self.model = model
+        self.api_key = os.getenv("GOOGLE_API_KEY")
+        if not self.api_key:
+            raise ProviderError("GOOGLE_API_KEY is not set")
+        if genai is None:
+            raise ProviderError("google-genai SDK not installed; add 'google-genai' to requirements.txt and pip install.")
+        self.client = genai.Client(api_key=self.api_key)
+
+    @staticmethod
+    def _split_system_and_messages(msgs: List[Message]) -> tuple[str, List[dict]]:
+        system_parts: List[str] = []
+        contents: List[dict] = []
+        for m in msgs:
+            role = m.get("role", "user")
+            text = m.get("content", "")
+            if role == "system":
+                system_parts.append(text)
+            else:
+                mapped = "user" if role == "user" else "model"
+                contents.append({"role": mapped, "parts": [{"text": text}]})
+        return ("\n".join(system_parts).strip(), contents)
+
+    def chat(
+        self,
+        messages: Iterable[Message],
+        temperature: float,
+        max_new_tokens: int,
+        stream: bool,
+    ) -> Union[str, Generator[str, None, None]]:
+        msgs = _ensure_messages(messages)
+        system_instruction, contents = self._split_system_and_messages(msgs)
+        try:
+            # Some versions of google-genai expose system_instruction; if not, we prepend.
+            kwargs: Dict[str, Any] = {
+                "model": self.model,
+                "contents": contents,
+                "generation_config": {
+                    "temperature": float(temperature),
+                    "max_output_tokens": int(max_new_tokens),
+                },
+            }
+            try:
+                resp = self.client.models.generate_content(system_instruction=system_instruction or None, **kwargs)
+            except TypeError:
+                # Fallback for older SDKs: inject system as first user turn
+                if system_instruction:
+                    contents = [{"role": "user", "parts": [{"text": f"System: {system_instruction}"}]}] + contents
+                    kwargs["contents"] = contents
+                resp = self.client.models.generate_content(**kwargs)
+
+            text = getattr(resp, "text", "") or ""
+
+            if stream:
+                # Fake streaming for API parity: one chunk
+                def gen():
+                    yield text
+                return gen()
+            return text
+        except Exception as e:
+            raise ProviderError(f"Gemini error: {e}") from e
+
+
+# ---------- HF Inference Router ----------
+class HfRouterProvider:
+    """
+    Hugging Face Inference Router (OpenAI-like /v1/chat/completions).
+    Tries primary -> fallback model (both can include optional provider tag, e.g., "model:featherless-ai").
+
+    Requires:
+        - env: HF_TOKEN
+        - package: requests
+    """
+    name = "router"
+    BASE_URL = "https://router.huggingface.co/v1/chat/completions"
+
+    def __init__(self, primary_model: str, fallback_model: Optional[str], provider_tag: Optional[str]):
+        self.primary = primary_model
+        self.fallback = fallback_model
+        self.provider_tag = provider_tag
+        self.token = os.getenv("HF_TOKEN")
+        if not self.token:
+            raise ProviderError("HF_TOKEN is not set")
+        self.session = _requests_session_with_retries(total=3, backoff=0.5, timeout=60.0)
+
+    def _fmt_model(self, model: str) -> str:
+        return model if not self.provider_tag else f"{model}:{self.provider_tag}"
+
+    def _sse_stream(self, resp: requests.Response) -> Generator[str, None, None]:
+        for raw in resp.iter_lines(decode_unicode=True):
+            if not raw:
+                continue
+            if not raw.startswith("data:"):
+                continue
+            data = raw[5:].strip()
+            if data == "[DONE]":
+                break
+            try:
+                obj = json.loads(data)
+            except Exception:
+                continue
+            try:
+                delta = obj["choices"][0].get("delta", {})
+                content = delta.get("content")
+                if content:
+                    yield content
+            except Exception:
+                continue
+
+    def _call_router(
+        self,
+        model: str,
+        messages: List[Message],
+        temperature: float,
+        max_new_tokens: int,
+        stream: bool,
+    ) -> Union[str, Generator[str, None, None]]:
+        headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+        payload: Dict[str, Any] = {
+            "model": self._fmt_model(model),
+            "messages": messages,
+            "temperature": float(temperature),
+            "max_tokens": int(max_new_tokens),
+            "stream": bool(stream),
+        }
+        if stream:
+            with self.session.post(self.BASE_URL, headers=headers, json=payload, stream=True) as r:
+                if r.status_code >= 400:
+                    raise ProviderError(f"HF Router HTTP {r.status_code}: {r.text[:300]}")
+                return self._sse_stream(r)
+        else:
+            r = self.session.post(self.BASE_URL, headers=headers, json=payload)
+            if r.status_code >= 400:
+                raise ProviderError(f"HF Router HTTP {r.status_code}: {r.text[:300]}")
+            obj = r.json()
+            try:
+                return obj["choices"][0]["message"]["content"]
+            except Exception as e:
+                raise ProviderError(f"HF Router response parsing error: {e}") from e
+
+    def chat(
+        self,
+        messages: Iterable[Message],
+        temperature: float,
+        max_new_tokens: int,
+        stream: bool,
+    ) -> Union[str, Generator[str, None, None]]:
+        msgs = _ensure_messages(messages)
+        try:
+            return self._call_router(self.primary, msgs, temperature, max_new_tokens, stream)
+        except Exception as e1:
+            logger.warning("HF primary model failed (%s): %s", self.primary, e1)
+            if self.fallback:
+                return self._call_router(self.fallback, msgs, temperature, max_new_tokens, stream)
+            raise
+
+
+# ---------- Orchestrator ----------
+class MultiProviderChat:
+    """
+    Tries providers in configured order. First success wins.
+    Skips misconfigured providers (missing key or SDK).
+    """
+    def __init__(self, settings: Settings):
+        m = settings.model
+        order = [p.strip().lower() for p in settings.provider_order]
+        self.providers: List[Any] = []
+
+        for p in order:
+            try:
+                if p == "groq":
+                    self.providers.append(GroqProvider(m.groq_model))
+                elif p == "gemini":
+                    self.providers.append(GeminiProvider(m.gemini_model))
+                elif p == "router":
+                    self.providers.append(HfRouterProvider(m.name, m.fallback, m.provider))
+                else:
+                    logger.warning("Unknown provider '%s' in provider_order; skipping.", p)
+            except ProviderError as e:
+                logger.warning("Provider '%s' not available: %s (will skip)", p, e)
+                continue
+
+        if not self.providers:
+            raise ProviderError("No providers are configured/available")
+
+        self.temperature = m.temperature
+        self.max_new_tokens = m.max_new_tokens
+
+    def chat(
+        self,
+        messages: Iterable[Message],
+        temperature: Optional[float] = None,
+        max_new_tokens: Optional[int] = None,
+        stream: bool = True,
+    ) -> Union[str, Generator[str, None, None]]:
+        temp = float(self.temperature if temperature is None else temperature)
+        mx = int(self.max_new_tokens if max_new_tokens is None else max_new_tokens)
+        last_err: Optional[Exception] = None
+
+        for provider in self.providers:
+            pname = getattr(provider, "name", provider.__class__.__name__)
+            t0 = time.time()
+            try:
+                result = provider.chat(messages, temp, mx, stream)
+                logger.info("Provider '%s' succeeded in %.2fs", pname, time.time() - t0)
+                return result
+            except Exception as e:
+                logger.warning("Provider '%s' failed: %s", pname, e)
+                last_err = e
+                continue
+
+        raise ProviderError(f"All providers failed. Last error: {last_err}")
+
+
+__all__ = [
+    "ProviderError",
+    "GroqProvider",
+    "GeminiProvider",
+    "HfRouterProvider",
+    "MultiProviderChat",
+]

app/core/logging.py

@@ -0,0 +1,57 @@
+# app/core/logging.py
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from typing import Optional
+
+_DEF_FORMAT = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+_DEF_DATEFMT = "%Y-%m-%dT%H:%M:%S%z"
+
+
+def setup_logging(level: Optional[str] = None) -> None:
+    """
+    Idempotent logging setup.
+    - Honors LOG_LEVEL env (default INFO) unless an explicit level is passed.
+    - Avoids duplicate handlers if called multiple times.
+    - Tames noisy third-party loggers by default.
+    """
+    root = logging.getLogger()
+    if root.handlers:
+        return  # already configured
+
+    log_level = (level or os.getenv("LOG_LEVEL", "INFO")).upper()
+    try:
+        parsed_level = getattr(logging, log_level)
+    except AttributeError:
+        parsed_level = logging.INFO
+
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(_DEF_FORMAT, datefmt=_DEF_DATEFMT)
+    handler.setFormatter(formatter)
+
+    root.setLevel(parsed_level)
+    root.addHandler(handler)
+
+    # Quiet noisy libs by default; adjust if you need more/less detail.
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("requests").setLevel(logging.WARNING)
+
+
+def add_trace_id(request) -> None:
+    """
+    Injects a unique `trace_id` into request.state (works with FastAPI-style objects).
+    Duck-typed to avoid importing FastAPI here.
+    """
+    try:
+        state = getattr(request, "state", None)
+        if state is None:
+            # Some frameworks may not have .state; just skip silently.
+            return
+        if not hasattr(state, "trace_id"):
+            state.trace_id = str(uuid.uuid4())
+    except Exception:
+        # Never let logging helpers break the app.
+        return

app/core/prompts/plan.txt

@@ -0,0 +1,17 @@
+You are MATRIX-AI Planner.
+
+Return ONLY a single JSON object. Do not include backticks, code fences, Markdown, or any prose.
+The JSON MUST match this schema exactly:
+
+{
+  "plan_id": "<string>",
+  "steps": ["<string>", "..."],
+  "risk": "low" | "medium" | "high",
+  "explanation": "<string>"
+}
+
+Rules:
+- Keep steps short, safe, and auditable (1–3 steps).
+- Prefer low risk actions.
+- Do not add any extra keys.
+- Start your reply with '{' and end with '}'.

app/core/rag/build.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+import json, os, re, time, math, logging
+from pathlib import Path
+from typing import Dict, List, Iterable, Tuple, Optional
+
+import yaml
+import requests
+
+log = logging.getLogger(__name__)
+
+# -------------------------
+# Text cleaning & chunking
+# -------------------------
+
+_MD_FRONTMATTER = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
+
+def normalize_text(text: str) -> str:
+    lines = [ln.strip() for ln in text.splitlines()]
+    cleaned = []
+    for ln in lines:
+        if not ln:
+            continue
+        if sum(ch.isalnum() for ch in ln) < 3:
+            continue
+        cleaned.append(ln)
+    s = "\n".join(cleaned)
+    s = re.sub(r"\n{3,}", "\n\n", s)
+    return s.strip()
+
+def md_to_text(md: str) -> str:
+    md = re.sub(_MD_FRONTMATTER, "", md)
+    md = re.sub(r"```.*?```", "", md, flags=re.DOTALL)  # drop fenced code
+    md = re.sub(r"!\[[^\]]*\]\([^)]+\)", "", md)        # drop images
+    md = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", md)    # links -> label
+    md = re.sub(r"^\s{0,3}#{1,6}\s*", "", md, flags=re.MULTILINE)
+    md = md.replace("`", "")
+    md = re.sub(r"^\s*[-*+]\s+", "• ", md, flags=re.MULTILINE)
+    md = re.sub(r"^\s*>\s?", "", md, flags=re.MULTILINE)
+    return normalize_text(md)
+
+def chunk_text(text: str, max_chars: int = 800, overlap: int = 120) -> List[str]:
+    paras = [p.strip() for p in text.split("\n\n") if p.strip()]
+    out: List[str] = []
+    buf = ""
+    for p in paras:
+        if len(p) > max_chars:
+            i = 0
+            while i < len(p):
+                j = min(i + max_chars, len(p))
+                out.append(p[i:j])
+                i = j - overlap if j - overlap > i else j
+            continue
+        if len(buf) + 2 + len(p) <= max_chars:
+            buf = (buf + "\n\n" + p) if buf else p
+        else:
+            if buf:
+                out.append(buf)
+            buf = p
+    if buf:
+        out.append(buf)
+    return out
+
+def write_jsonl(records: Iterable[Dict], out_path: Path) -> None:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with out_path.open("w", encoding="utf-8") as f:
+        for rec in records:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+
+# -------------------------
+# GitHub API helpers
+# -------------------------
+
+def gh_session() -> requests.Session:
+    s = requests.Session()
+    s.headers.update({
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "matrix-ai-rag-builder/1.0",
+    })
+    tok = os.getenv("GITHUB_TOKEN")
+    if tok:
+        s.headers["Authorization"] = f"Bearer {tok}"
+    return s
+
+def gh_get_json(url: str, sess: requests.Session, max_retries: int = 3) -> Dict | List:
+    backoff = 1.0
+    for attempt in range(max_retries):
+        r = sess.get(url, timeout=25)
+        if r.status_code == 403 and "rate limit" in r.text.lower():
+            log.warning("GitHub rate-limited; sleeping %.1fs", backoff)
+            time.sleep(backoff)
+            backoff = min(backoff * 2, 30)
+            continue
+        r.raise_for_status()
+        return r.json()
+    r.raise_for_status()
+    return {}
+
+def gh_list_org_repos(org: str, sess: requests.Session) -> List[Dict]:
+    repos: List[Dict] = []
+    page = 1
+    while True:
+        url = f"https://api.github.com/orgs/{org}/repos?per_page=100&page={page}"
+        js = gh_get_json(url, sess)
+        if not js:
+            break
+        repos.extend(js)
+        if len(js) < 100:
+            break
+        page += 1
+    return repos
+
+def gh_list_tree(owner: str, repo: str, branch: str, sess: requests.Session) -> List[Dict]:
+    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1"
+    js = gh_get_json(url, sess)
+    return js.get("tree", []) if isinstance(js, dict) else []
+
+def gh_fetch_raw(owner: str, repo: str, branch: str, path: str, sess: requests.Session) -> Optional[str]:
+    raw_url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}"
+    r = sess.get(raw_url, timeout=25)
+    if r.status_code == 404 and branch == "main":  # try master fallback
+        raw_url = f"https://raw.githubusercontent.com/{owner}/{repo}/master/{path}"
+        r = sess.get(raw_url, timeout=25)
+    if r.status_code == 200:
+        return r.text
+    return None
+
+# -------------------------
+# Builders
+# -------------------------
+
+def ingest_github_repo(owner: str, name: str, branch: str, docs_paths: List[str],
+                       include_readme: bool, exts: Tuple[str,...] = (".md",".mdx",".txt")) -> List[Tuple[str,str]]:
+    sess = gh_session()
+    out: List[Tuple[str,str]] = []
+
+    # README
+    if include_readme:
+        for candidate in ("README.md", "readme.md", "README.MD"):
+            t = gh_fetch_raw(owner, name, branch, candidate, sess)
+            if t:
+                out.append((f"github:{owner}/{name}/{candidate}", md_to_text(t)))
+                break
+
+    # Tree -> docs paths
+    tree = gh_list_tree(owner, name, branch, sess)
+    if not tree:
+        return out
+
+    wanted_dirs = [p.strip("/").lower() for p in docs_paths]
+    for entry in tree:
+        if entry.get("type") != "blob":
+            continue
+        path = entry.get("path", "")
+        lower = path.lower()
+        if not lower.endswith(exts):
+            continue
+        if any(lower.startswith(d + "/") for d in wanted_dirs):
+            t = gh_fetch_raw(owner, name, branch, path, sess)
+            if not t:
+                continue
+            txt = md_to_text(t) if lower.endswith((".md",".mdx")) else normalize_text(t)
+            if txt:
+                out.append((f"github:{owner}/{name}/{path}", txt))
+    return out
+
+def ingest_github_sources(cfg: Dict) -> List[Tuple[str,str]]:
+    out: List[Tuple[str,str]] = []
+    gh = cfg.get("github") or {}
+    sess = gh_session()
+
+    # explicit repos
+    for repo in (gh.get("repos") or []):
+        owner = repo["owner"]
+        name = repo["name"]
+        branch = repo.get("branch", "main")
+        docs_paths = repo.get("docs_paths", ["docs"])
+        include_readme = bool(repo.get("include_readme", True))
+        out.extend(ingest_github_repo(owner, name, branch, docs_paths, include_readme))
+
+    # whole org scan (README + docs/)
+    for org in (gh.get("orgs") or []):
+        try:
+            repos = gh_list_org_repos(org, sess)
+        except Exception as e:
+            log.warning("Failed to list org %s: %s", org, e)
+            continue
+        for r in repos:
+            owner = r["owner"]["login"]
+            name = r["name"]
+            default_branch = r.get("default_branch", "main")
+            # README + docs/
+            out.extend(ingest_github_repo(owner, name, default_branch, ["docs"], include_readme=True))
+    return out
+
+def ingest_local_sources(cfg: Dict) -> List[Tuple[str,str]]:
+    out: List[Tuple[str,str]] = []
+    local = cfg.get("local") or {}
+    paths = local.get("paths") or []
+    glob_pat = local.get("glob", "**/*.md")
+    for p in paths:
+        fp = Path(p)
+        if fp.is_file():
+            try:
+                raw = fp.read_text(encoding="utf-8", errors="ignore")
+                txt = md_to_text(raw) if fp.suffix.lower() in {".md",".mdx"} else normalize_text(raw)
+                if txt:
+                    out.append((str(fp), txt))
+            except Exception as e:
+                log.warning("Failed reading %s: %s", fp, e)
+        elif fp.is_dir():
+            for f in fp.rglob(glob_pat):
+                try:
+                    raw = f.read_text(encoding="utf-8", errors="ignore")
+                    txt = md_to_text(raw) if f.suffix.lower() in {".md",".mdx"} else normalize_text(raw)
+                    if txt:
+                        out.append((str(f), txt))
+                except Exception as e:
+                    log.warning("Failed reading %s: %s", f, e)
+    return out
+
+def build_kb_from_config(config_path: str = "configs/rag_sources.yaml",
+                         out_jsonl: str = "data/kb.jsonl",
+                         max_chars: int = 800,
+                         overlap: int = 120,
+                         minlen: int = 200,
+                         dedupe: bool = True) -> int:
+    cfg: Dict = {}
+    p = Path(config_path)
+    if p.exists():
+        cfg = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+    else:
+        log.warning("rag_sources.yaml not found at %s (using defaults)", p)
+
+    records: List[Dict] = []
+
+    # GitHub
+    try:
+        gh_docs = ingest_github_sources(cfg)
+        for src, text in gh_docs:
+            for chunk in chunk_text(text, max_chars, overlap):
+                if len(chunk) >= minlen:
+                    records.append({"text": chunk, "source": src})
+    except Exception as e:
+        log.warning("GitHub ingest failed: %s", e)
+
+    # Local
+    try:
+        loc_docs = ingest_local_sources(cfg)
+        for src, text in loc_docs:
+            for chunk in chunk_text(text, max_chars, overlap):
+                if len(chunk) >= minlen:
+                    records.append({"text": chunk, "source": src})
+    except Exception as e:
+        log.warning("Local ingest failed: %s", e)
+
+    # URLs (optional)
+    for url in (cfg.get("urls") or []):
+        try:
+            r = requests.get(url, timeout=25)
+            r.raise_for_status()
+            txt = normalize_text(r.text)
+            for chunk in chunk_text(txt, max_chars, overlap):
+                if len(chunk) >= minlen:
+                    records.append({"text": chunk, "source": url})
+        except Exception as e:
+            log.warning("URL ingest failed for %s: %s", url, e)
+
+    if dedupe:
+        seen = set()
+        deduped: List[Dict] = []
+        for rec in records:
+            h = hash(rec["text"])
+            if h in seen:
+                continue
+            seen.add(h)
+            deduped.append(rec)
+        records = deduped
+
+    if not records:
+        log.warning("No KB records produced.")
+        return 0
+
+    out_path = Path(out_jsonl)
+    write_jsonl(records, out_path)
+    log.info("Wrote %d chunks to %s", len(records), out_path)
+    return len(records)
+
+def ensure_kb(out_jsonl: str = "data/kb.jsonl",
+              config_path: str = "configs/rag_sources.yaml",
+              skip_if_exists: bool = True) -> bool:
+    """
+    If kb.jsonl exists -> return True.
+    Else -> build from config and return True on success.
+    """
+    out = Path(out_jsonl)
+    if skip_if_exists and out.exists() and out.stat().st_size > 0:
+        log.info("KB already present at %s (skipping build)", out)
+        return True
+    n = build_kb_from_config(config_path=config_path, out_jsonl=out_jsonl)
+    return n > 0

app/core/rag/retriever.py

@@ -0,0 +1,50 @@
+# app/core/rag/retriever.py
+from __future__ import annotations
+import json, logging, os
+from pathlib import Path
+from typing import List, Dict, Optional
+import numpy as np
+import faiss
+from sentence_transformers import SentenceTransformer
+
+log = logging.getLogger(__name__)
+
+class Retriever:
+    def __init__(self, kb_path: str = "data/kb.jsonl",
+                 model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+                 top_k: int = 4):
+        self.kb_path = Path(kb_path)
+        self.top_k = top_k
+        if not self.kb_path.exists():
+            raise FileNotFoundError(f"KB file not found: {self.kb_path} (jsonl with {{text,source}})")
+
+        # Use a project-local cache to avoid '/.cache' permission issues
+        cache_dir = Path(os.getenv("HF_HOME", "./.cache"))
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        self.model = SentenceTransformer(model_name, cache_folder=str(cache_dir))
+
+        self.docs: List[Dict[str, str]] = []
+        with self.kb_path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                self.docs.append(json.loads(line))
+        texts = [d["text"] for d in self.docs]
+        emb = self.model.encode(texts, convert_to_numpy=True, normalize_embeddings=True, show_progress_bar=False)
+        self.dim = int(emb.shape[1])
+        self.index = faiss.IndexFlatIP(self.dim)
+        self.index.add(emb.astype("float32"))
+
+    def retrieve(self, query: str, k: Optional[int] = None) -> List[Dict]:
+        k = k or self.top_k
+        vec = self.model.encode([query], convert_to_numpy=True, normalize_embeddings=True)
+        D, I = self.index.search(vec.astype("float32"), k)
+        out: List[Dict] = []
+        for idx, score in zip(I[0], D[0]):
+            if int(idx) < 0:
+                continue
+            d = self.docs[int(idx)]
+            out.append({"text": d["text"], "source": d.get("source", f"kb:{idx}"), "score": float(score)})
+        return out

app/core/rate_limit.py

@@ -0,0 +1,27 @@
+import time
+from collections import defaultdict
+
+class RateLimiter:
+    def __init__(self):
+        self.windows: dict[str, tuple[int, int]] = defaultdict(lambda: (0, 0))
+
+    def allow(self, ip: str, route: str, per_minute: int) -> bool:
+        """Checks if a request is allowed under a fixed-window rate limit."""
+        now = int(time.time())
+        current_window = now // 60
+        key = f"{ip}:{route}" # Simplified key for per-route limit
+
+        window_start, count = self.windows.get(key, (0, 0))
+
+        if window_start != current_window:
+            # New window, reset count
+            self.windows[key] = (current_window, 1)
+            return True
+
+        if count >= per_minute:
+            # Exceeded limit
+            return False
+
+        # Increment count in current window
+        self.windows[key] = (current_window, count + 1)
+        return True

app/core/redact.py

@@ -0,0 +1,10 @@
+import re
+
+SECRET_PATTERN = re.compile(r"(bearer\s+[a-z0-9\-.~+/]+=*|sk-[a-z0-9]{20,})", re.IGNORECASE)
+EMAIL_PATTERN = re.compile(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", re.IGNORECASE)
+
+def redact(text: str) -> str:
+    """Redacts sensitive information like API keys and emails from a string."""
+    text = SECRET_PATTERN.sub("[REDACTED_TOKEN]", text)
+    text = EMAIL_PATTERN.sub("[REDACTED_EMAIL]", text)
+    return text

app/core/schema.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Optional, List, Literal
+from pydantic import BaseModel, Field, ConfigDict
+
+# ---------------------------
+# Planning schema
+# ---------------------------
+
+class Health(BaseModel):
+    score: Optional[float] = None
+    status: Optional[str] = None
+    last_checked: Optional[str] = None  # or use datetime if preferred
+
+
+class RecentCheck(BaseModel):
+    check: str
+    result: str
+    latency_ms: Optional[float] = None
+    ts: Optional[str] = None  # or use datetime if preferred
+
+
+class PlanContext(BaseModel):
+    """
+    Context is permissive: accept any extra keys from Guardian (or future sources).
+    Known fields are typed below; unknown fields pass through.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    # Common identifiers
+    app_id: Optional[str] = None
+    entity_uid: Optional[str] = None
+
+    # Known structured bits
+    symptoms: Optional[List[str]] = None
+    lkg: Optional[str] = None
+    lkg_version: Optional[str] = None
+    health: Optional[Health] = None
+    recent_checks: Optional[List[RecentCheck]] = None
+
+
+class PlanConstraints(BaseModel):
+    max_steps: int = Field(default=3, ge=1, le=10)
+    risk: Literal["low", "medium", "high"] = "low"
+
+
+class PlanRequest(BaseModel):
+    # default to "plan" and only allow that value for now
+    mode: Literal["plan"] = "plan"
+    context: PlanContext
+    constraints: PlanConstraints = Field(default_factory=PlanConstraints)
+
+
+class PlanResponse(BaseModel):
+    plan_id: str
+    steps: List[str]
+    risk: str
+    explanation: str
+
+
+# ---------------------------
+# Chat (kept for compatibility; router uses its own flexible model)
+# ---------------------------
+
+class ChatRequest(BaseModel):
+    question: str = Field(..., min_length=3, max_length=512)
+
+
+class ChatResponse(BaseModel):
+    answer: str
+    sources: List[str] = Field(default_factory=list)

app/deps.py

@@ -0,0 +1,7 @@
+from functools import lru_cache
+from .core.config import Settings
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """FastAPI dependency to get application settings."""
+    return Settings.load()

app/main.py

@@ -0,0 +1,211 @@
+# app/main.py
+from __future__ import annotations
+
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, APIRouter, Request
+from fastapi.responses import RedirectResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+# ---- Early env load (HF_TOKEN, ADMIN_TOKEN, GITHUB_TOKEN, etc.) ----
+def _load_env_file(paths: list[str]) -> None:
+    logger = logging.getLogger("uvicorn.error")
+    try:
+        from dotenv import load_dotenv  # type: ignore
+        for p in paths:
+            if os.path.exists(p):
+                load_dotenv(dotenv_path=p, override=False)
+                logger.info("Loaded environment from %s", p)
+                return
+        logger.info("No .env file found in %s (skipping)", paths)
+    except Exception:
+        # Fallback, very small .env parser
+        for p in paths:
+            if not os.path.exists(p):
+                continue
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    for raw in f:
+                        line = raw.strip()
+                        if not line or line.startswith("#"):
+                            continue
+                        if line.startswith("export "):
+                            line = line[len("export "):].strip()
+                        if "=" not in line:
+                            continue
+                        key, val = line.split("=", 1)
+                        key, val = key.strip(), val.strip()
+                        if (val.startswith('"') and val.endswith('"')) or (
+                            val.startswith("'") and val.endswith("'")
+                        ):
+                            val = val[1:-1]
+                        os.environ.setdefault(key, val)
+                logger.info("Loaded environment from %s (fallback parser)", p)
+                return
+            except Exception as e:
+                logger.warning("Failed loading env from %s: %s", p, e)
+        logger.info("No .env loaded (none found / parsers failed)")
+
+_load_env_file([".env", "configs/.env", ".env.local", "configs/.env.local"])
+
+# ---- RAG DISABLED (commented out while debugging) ----
+# from .deps import get_settings
+# from .services.chat_service import get_retriever
+# from .core.rag.build import ensure_kb
+
+# ---- Middlewares ----
+try:
+    from .middleware import attach_middlewares  # type: ignore
+except Exception:
+    try:
+        from .middlewares import attach_middlewares  # type: ignore
+    except Exception:
+        def attach_middlewares(app: FastAPI) -> None:
+            logging.getLogger("uvicorn.error").warning(
+                "attach_middlewares not found; continuing without custom middlewares."
+            )
+
+# ---- Routers enabled ----
+from .routers import health
+from .ui import router as ui_router  # <-- mount UI so /home works
+
+# ---- Validator service integration ----
+VALIDATOR_TAG = {"name": "Validator", "description": "A2A Validator UI and endpoints (/validator)."}
+
+HAS_VALIDATOR = False
+HAS_SOCKETIO = False
+socketio_app = None  # type: ignore[assignment]
+
+try:
+    # Primary validator router + optional Socket.IO app
+    from .services.validator_service import router as validator_router  # type: ignore
+    HAS_VALIDATOR = True
+    try:
+        from .services.validator_service import socketio_app as _socketio_app  # type: ignore
+        socketio_app = _socketio_app
+        HAS_SOCKETIO = socketio_app is not None
+    except Exception:
+        socketio_app = None
+        HAS_SOCKETIO = False
+except Exception as e:
+    logging.getLogger("uvicorn.error").warning("validator_service import failed: %s", e)
+    # Fallback validator router if import fails
+    _templates = Jinja2Templates(directory="app/templates")
+    validator_router = APIRouter(prefix="/validator", tags=["Validator"])
+
+    @validator_router.get("", response_class=HTMLResponse)
+    @validator_router.get("/", response_class=HTMLResponse)
+    async def _validator_fallback_ui(request: Request) -> HTMLResponse:
+        # Try validator.hml first (project used this name), then validator.html
+        try:
+            return _templates.TemplateResponse("validator.hml", {"request": request})
+        except Exception:
+            return _templates.TemplateResponse(
+                "validator.html",
+                {"request": request, "warning": "validator service running in fallback mode"},
+            )
+
+TAGS_METADATA = [
+    {"name": "Health", "description": "Liveness / readiness probes and basic service metadata."},
+    VALIDATOR_TAG,
+    # UI tag is implicit; only /home (Info) and /validator are exposed
+]
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.started_at = time.time()
+    app.state.version = os.getenv("APP_VERSION", "1.0.0")
+    logger = logging.getLogger("uvicorn.error")
+
+    # ---- RAG INIT DISABLED ----
+    # try:
+    #     if ensure_kb(out_jsonl="data/kb.jsonl", config_path="configs/rag_sources.yaml", skip_if_exists=True):
+    #         logger.info("KB ready at data/kb.jsonl")
+    #     else:
+    #         logger.warning("KB build produced no records; running LLM-only.")
+    # except Exception as e:
+    #     logger.warning("KB build failed (%s); running LLM-only.", e)
+    # logger.info("Warming up RAG retriever...")
+    # get_retriever(get_settings())
+    # logger.info("RAG retriever is ready.")
+
+    hf_token_present = bool(os.getenv("HF_TOKEN"))
+    logger.info(
+        "matrix-ai starting (version=%s, port=%s, hf_token_present=%s)",
+        app.state.version,
+        os.getenv("PORT", "7860"),
+        "yes" if hf_token_present else "no",
+    )
+    try:
+        yield
+    finally:
+        uptime = time.time() - getattr(app.state, "started_at", time.time())
+        logger.info("matrix-ai shutting down (uptime=%.2fs)", uptime)
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="matrix-ai",
+        version=os.getenv("APP_VERSION", "1.0.0"),
+        description="Minimal service with A2A Validator and health endpoints",
+        openapi_tags=TAGS_METADATA,
+        docs_url="/docs",
+        redoc_url=None,
+        lifespan=lifespan,
+    )
+
+    # Static files (for validator UI assets, etc.)
+    try:
+        app.mount("/static", StaticFiles(directory="app/static"), name="static")
+    except Exception:
+        pass
+
+    # Middlewares (gzip, CORS, rate-limit, req-logs, etc.)
+    attach_middlewares(app)
+
+    # Core info/router pages
+    app.include_router(health.router, tags=["Health"])
+
+    # Validator router
+    app.include_router(validator_router, tags=["Validator"])
+
+    # UI router (enables /home "Info" page and "/" redirect defined in ui.py)
+    app.include_router(ui_router)
+
+    # Alias so the frontend can POST /agent-card (script.js default target)
+    try:
+        from .services.validator_service import get_agent_card as _get_agent_card  # type: ignore
+        app.add_api_route(
+            "/agent-card",
+            _get_agent_card,
+            methods=["POST"],
+            tags=["Validator"],
+            name="agent_card_alias",
+        )
+        logging.getLogger("uvicorn.error").info(
+            "Added alias: POST /agent-card → /validator/agent-card"
+        )
+    except Exception as e:
+        logging.getLogger("uvicorn.error").warning(
+            f"Failed to add /agent-card alias: {e}"
+        )
+
+    # Mount Socket.IO if available
+    if HAS_SOCKETIO and socketio_app is not None:
+        app.mount("/socket.io", socketio_app)
+        logging.getLogger("uvicorn.error").info("Mounted Socket.IO at /socket.io")
+
+    # IMPORTANT:
+    # Do NOT define extra "/" or "/home" handlers here.
+    # ui.py already defines:
+    #   - GET "/"  -> Redirect to /validator
+    #   - GET "/home" -> Render home.html (Info tab)
+    # Keeping only one definition avoids duplicate-route conflicts.
+
+    return app
+
+app = create_app()

app/middleware.py

@@ -0,0 +1,191 @@
+# app/middleware.py
+from __future__ import annotations
+
+import time
+import logging
+import json
+import asyncio  
+from typing import Callable, Optional
+
+from anyio import EndOfStream
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.responses import Response, JSONResponse
+from starlette.middleware.gzip import GZipMiddleware
+from starlette.exceptions import ClientDisconnect 
+
+# Optional: python-json-logger for structured logs; fallback to a minimal JSON formatter.
+try:
+    from pythonjsonlogger import jsonlogger  # type: ignore
+    _HAS_PY_JSON_LOGGER = True
+except Exception:
+    _HAS_PY_JSON_LOGGER = False
+
+from .deps import get_settings
+from .core.rate_limit import RateLimiter
+from .core.logging import add_trace_id
+
+class _SimpleJsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "asctime": self.formatTime(record, "%Y-%m-%d %H:%M:%S"),
+            "name": record.name,
+            "levelname": record.levelname,
+            "message": record.getMessage(),
+            "trace_id": getattr(record, "trace_id", None),
+        }
+        try:
+            return json.dumps(payload, ensure_ascii=False)
+        except Exception:
+            return (
+                f'{payload["asctime"]} {payload["name"]} {payload["levelname"]} '
+                f'{payload["message"]} trace_id={payload["trace_id"]}'
+            )
+
+_logger = logging.getLogger("matrix-ai")
+if not _logger.handlers:
+    _logger.setLevel(logging.INFO)
+    _handler = logging.StreamHandler()
+    if _HAS_PY_JSON_LOGGER:
+        _formatter = jsonlogger.JsonFormatter(
+            "%(asctime)s %(name)s %(levelname)s %(message)s %(trace_id)s"
+        )
+    else:
+        _formatter = _SimpleJsonFormatter()
+        logging.getLogger("uvicorn.error").warning(
+            "python-json-logger not found; using a minimal JSON formatter."
+        )
+    _handler.setFormatter(_formatter)
+    _logger.addHandler(_handler)
+
+_rate_limiter = RateLimiter()
+_SSE_PATH_SUFFIXES = ("/chat/stream", "/v1/chat/stream")
+_HEALTH_PATHS = ("/health", "/livez", "/readyz")
+
+def _client_ip(request: Request) -> str:
+    xff = request.headers.get("x-forwarded-for")
+    if xff:
+        return xff.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+def _is_sse(request: Request, response: Optional[Response] = None) -> bool:
+    path = request.url.path
+    if path.endswith(_SSE_PATH_SUFFIXES):
+        return True
+    if response is not None:
+        ctype = response.headers.get("content-type", "")
+        if ctype.startswith("text/event-stream"):
+            return True
+    accept = request.headers.get("accept", "")
+    return "text/event-stream" in accept
+
+def attach_middlewares(app: FastAPI) -> None:
+    app.add_middleware(GZipMiddleware, minimum_size=512)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        expose_headers=["X-Trace-Id", "X-Process-Time-Ms", "Server-Timing"],
+    )
+
+    @app.middleware("http")
+    async def rate_limit_and_log_middleware(request: Request, call_next: Callable):
+        add_trace_id(request)
+        trace_id = getattr(request.state, "trace_id", "N/A")
+
+        path = request.url.path
+        method = request.method
+        ua = request.headers.get("user-agent", "-")
+        ip = _client_ip(request)
+
+        if path in _HEALTH_PATHS:
+            try:
+                response = await call_next(request)
+            except Exception:
+                return JSONResponse({"status": "unhealthy"}, status_code=500)
+            response.headers.setdefault("X-Trace-Id", str(trace_id))
+            return response
+
+        settings = get_settings()
+        if not _rate_limiter.allow(ip, path, settings.limits.rate_per_min):
+            _logger.warning(
+                "429 Too Many Requests from %s on %s",
+                ip, path, extra={"trace_id": trace_id},
+            )
+            return JSONResponse({"detail": "Too Many Requests"}, status_code=429,
+                                headers={"X-Trace-Id": str(trace_id)})
+
+        t0 = time.time()
+        try:
+            response = await call_next(request)
+
+        # --- NEW: treat disconnects as benign (return 204) ---
+        except (EndOfStream, ClientDisconnect, asyncio.CancelledError):
+            _logger.info(
+                "Client disconnected from stream. Path: %s, IP: %s",
+                path, ip, extra={"trace_id": trace_id},
+            )
+            resp = Response(status_code=204)
+            resp.headers.setdefault("X-Trace-Id", str(trace_id))
+            return resp
+
+        except RuntimeError as e:
+            # Starlette sometimes wraps EndOfStream as this RuntimeError
+            if str(e) == "No response returned.":
+                _logger.info(
+                    "Downstream produced no response (likely streaming disconnect). "
+                    "Path: %s, IP: %s",
+                    path, ip, extra={"trace_id": trace_id},
+                )
+                resp = Response(status_code=204)
+                resp.headers.setdefault("X-Trace-Id", str(trace_id))
+                return resp
+            # not a disconnect case → re-raise to be handled below
+            raise
+
+        except Exception as e:
+            _logger.exception(
+                "Unhandled error while processing %s %s: %s",
+                method, path, e, extra={"trace_id": trace_id},
+            )
+            dur_ms = (time.time() - t0) * 1000.0
+            return JSONResponse(
+                {"detail": "Internal Server Error"},
+                status_code=500,
+                headers={
+                    "X-Trace-Id": str(trace_id),
+                    "X-Process-Time-Ms": f"{dur_ms:.2f}",
+                    "Server-Timing": f"app;dur={dur_ms:.2f}",
+                },
+            )
+
+        if not isinstance(response, Response):
+            _logger.error("Downstream returned no Response object for %s",
+                          path, extra={"trace_id": trace_id})
+            return JSONResponse({"detail": "Internal Server Error"},
+                                status_code=500,
+                                headers={"X-Trace-Id": str(trace_id)})
+
+        sse = _is_sse(request, response)
+        dur_ms = (time.time() - t0) * 1000.0
+        response.headers.setdefault("X-Trace-Id", str(trace_id))
+        response.headers.setdefault("X-Process-Time-Ms", f"{dur_ms:.2f}")
+        response.headers.setdefault("Server-Timing", f"app;dur={dur_ms:.2f}")
+
+        if sse:
+            response.headers.setdefault("Cache-Control", "no-cache")
+            _logger.info(
+                '"%s %s" %s (SSE) ip=%s ua="%s" %.2fms',
+                method, path, response.status_code, ip, ua, dur_ms,
+                extra={"trace_id": trace_id},
+            )
+            return response
+
+        _logger.info(
+            '"%s %s" %s ip=%s ua="%s" %.2fms',
+            method, path, response.status_code, ip, ua, dur_ms,
+            extra={"trace_id": trace_id},
+        )
+        return response

app/routers/health.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+@router.get("/healthz", summary="Liveness Probe")
+async def healthz():
+    """Checks if the service is running."""
+    return {"status": "ok"}
+
+@router.get("/readyz", summary="Readiness Probe")
+async def readyz():
+    """Checks if the service is ready to accept traffic."""
+    # In a real app, this would check dependencies like model loading status.
+    return {"ready": True}

app/services/validator_service.py

@@ -0,0 +1,358 @@
+# app/services/validator_service.py
+"""
+A2A Validator service.
+- Provides /validator (UI) + /validator/agent-card (HTTP) routes.
+- Defines all Socket.IO event handlers.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+from uuid import uuid4
+
+import bleach
+import httpx
+
+# Socket.IO is optional; create shims when missing
+try:
+    import socketio  # type: ignore
+    HAS_SOCKETIO = True
+except Exception:  # pragma: no cover
+    socketio = None  # type: ignore
+    HAS_SOCKETIO = False
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.templating import Jinja2Templates
+from jinja2 import TemplateNotFound
+
+# Conditional import for A2A SDK (optional)
+try:
+    from a2a.client import A2ACardResolver, A2AClient
+    from a2a.types import (
+        AgentCard,
+        JSONRPCErrorResponse,
+        Message,
+        MessageSendConfiguration,
+        MessageSendParams,
+        Role,
+        SendMessageRequest,
+        SendMessageResponse,
+        SendStreamingMessageRequest,
+        SendStreamingMessageResponse,
+        TextPart,
+    )
+    HAS_A2A = True
+except Exception:
+    HAS_A2A = False
+    # Dummy stand-ins so type hints won’t explode
+    AgentCard = JSONRPCErrorResponse = Message = MessageSendConfiguration = object  # type: ignore
+    MessageSendParams = Role = SendMessageRequest = SendMessageResponse = object  # type: ignore
+    SendStreamingMessageRequest = SendStreamingMessageResponse = TextPart = object  # type: ignore
+    A2ACardResolver = A2AClient = object  # type: ignore
+
+from app import validators  # local validators.py
+
+# ==============================================================================
+# Setup
+# ==============================================================================
+logger = logging.getLogger("uvicorn.error")
+
+if HAS_SOCKETIO:
+    sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*")
+    socketio_app = socketio.ASGIApp(sio)
+else:
+    class _SioShim:
+        async def emit(self, *a, **k):  # no-op
+            pass
+
+        def on(self, *a, **k):
+            def _wrap(f):
+                return f
+            return _wrap
+
+        event = on
+
+    sio = _SioShim()
+    socketio_app = None
+
+router = APIRouter(prefix="/validator", tags=["Validator"])
+templates = Jinja2Templates(directory="app/templates")
+
+STANDARD_HEADERS = {
+    "host",
+    "user-agent",
+    "accept",
+    "content-type",
+    "content-length",
+    "connection",
+    "accept-encoding",
+}
+
+# ==============================================================================
+# State Management
+# ==============================================================================
+clients: dict[str, tuple[httpx.AsyncClient, Any, Any]] = {}
+
+# ==============================================================================
+# Helpers
+# ==============================================================================
+async def _emit_debug_log(sid: str, event_id: str, log_type: str, data: Any) -> None:
+    await sio.emit("debug_log", {"type": log_type, "data": data, "id": event_id}, to=sid)
+
+
+async def _process_a2a_response(result: Any, sid: str, request_id: str) -> None:
+    if not HAS_A2A:
+        return
+
+    if isinstance(result.root, JSONRPCErrorResponse):
+        error_data = result.root.error.model_dump(exclude_none=True)
+        await _emit_debug_log(sid, request_id, "error", error_data)
+        await sio.emit(
+            "agent_response",
+            {"error": error_data.get("message", "Unknown error"), "id": request_id},
+            to=sid,
+        )
+        return
+
+    event = result.root.result
+    response_id = getattr(event, "id", request_id)
+    response_data = event.model_dump(exclude_none=True)
+    response_data["id"] = response_id
+    response_data["validation_errors"] = validators.validate_message(response_data)
+
+    await _emit_debug_log(sid, response_id, "response", response_data)
+    await sio.emit("agent_response", response_data, to=sid)
+
+
+def get_card_resolver(client: httpx.AsyncClient, agent_card_url: str) -> Any:
+    if not HAS_A2A:
+        return None
+    parsed_url = urlparse(agent_card_url)
+    base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+    path_with_query = urlunparse(("", "", parsed_url.path, "", parsed_url.query, ""))
+    card_path = path_with_query.lstrip("/")
+    if card_path:
+        return A2ACardResolver(client, base_url, agent_card_path=card_path)
+    return A2ACardResolver(client, base_url)
+
+# ==============================================================================
+# FastAPI Routes
+# ==============================================================================
+@router.get("/", response_class=HTMLResponse)
+async def validator_ui(request: Request) -> HTMLResponse:
+    # Prefer validator.hml (your current file), fallback to validator.html
+    for name in ("validator.hml", "validator.html"):
+        try:
+            return templates.TemplateResponse(name, {"request": request})
+        except TemplateNotFound:
+            continue
+    # If neither exists, return a minimal message
+    return HTMLResponse("<h3>Validator UI template not found.</h3>", status_code=500)
+
+
+@router.post("/agent-card")
+async def get_agent_card(request: Request) -> JSONResponse:
+    """
+    Fetch and validate an Agent Card from a URL.
+
+    If A2A SDK is installed, use its resolver.
+    Otherwise, be lenient: follow redirects and probe common well-known paths.
+    """
+    # Parse request body
+    try:
+        request_data = await request.json()
+        agent_url = (request_data.get("url") or "").strip()
+        sid = request_data.get("sid")
+        if not agent_url or not sid:
+            return JSONResponse({"error": "Agent URL and SID are required."}, status_code=400)
+    except Exception:
+        return JSONResponse({"error": "Invalid request body."}, status_code=400)
+
+    # Collect custom headers (forwarded to the target)
+    custom_headers = {
+        name: value
+        for name, value in request.headers.items()
+        if name.lower() not in STANDARD_HEADERS
+    }
+
+    await _emit_debug_log(
+        sid,
+        "http-agent-card",
+        "request",
+        {"endpoint": "/agent-card", "payload": request_data, "custom_headers": custom_headers},
+    )
+
+    # Fetch the agent card
+    try:
+        async with httpx.AsyncClient(
+            timeout=30.0,
+            headers=custom_headers,
+            follow_redirects=True,  # <<< important for 3xx like 307 to /docs
+        ) as client:
+            if HAS_A2A:
+                # Preferred path: let the resolver figure out the right card location
+                card_resolver = get_card_resolver(client, agent_url)
+                card = await card_resolver.get_agent_card()
+                card_data = card.model_dump(exclude_none=True)
+            else:
+                # Fallback: try what the user typed first; if non-JSON, probe common paths
+                tried: list[str] = []
+
+                async def _try(url: str) -> dict[str, Any]:
+                    r = await client.get(url)
+                    r.raise_for_status()
+                    ctype = (r.headers.get("content-type") or "").lower()
+                    if "application/json" in ctype or ctype.endswith("+json"):
+                        return r.json()
+                    # If we got HTML or something else, raise to trigger probing
+                    raise ValueError(f"Non-JSON response (content-type={ctype or 'unknown'}) at {url}")
+
+                try:
+                    card_data = await _try(agent_url)
+                except Exception:
+                    # If the user pasted a base/root URL, probe common Agent Card paths on same host
+                    parsed = urlparse(agent_url)
+                    base = f"{parsed.scheme}://{parsed.netloc}"
+                    candidates = [
+                        agent_url,  # original again (in case it became JSON after redirect)
+                        f"{base}/.well-known/agent.json",
+                        f"{base}/.well-known/ai-agent.json",
+                        f"{base}/agent-card",
+                        f"{base}/agent.json",
+                    ]
+                    err: Exception | None = None
+                    card_data = None
+                    for u in candidates:
+                        if u in tried:
+                            continue
+                        tried.append(u)
+                        try:
+                            card_data = await _try(u)
+                            agent_url = u  # record the working URL
+                            break
+                        except Exception as e:
+                            err = e
+                    if card_data is None:
+                        raise RuntimeError(
+                            f"Could not find a JSON Agent Card at {agent_url} (last error: {err})"
+                        )
+
+        # Validate locally
+        validation_errors = validators.validate_agent_card(card_data)  # type: ignore[arg-type]
+        response = {
+            "card": card_data,
+            "validation_errors": validation_errors,
+            "resolved_url": agent_url,
+        }
+        status = 200
+
+    except httpx.RequestError as e:
+        response = {"error": f"Failed to connect to agent: {e}"}
+        status = 502
+    except Exception as e:
+        response = {"error": f"An internal server error occurred: {e}"}
+        status = 500
+
+    await _emit_debug_log(sid, "http-agent-card", "response", {"status": status, "payload": response})
+    return JSONResponse(content=response, status_code=status)
+
+# ==============================================================================
+# Socket.IO Event Handlers
+# ==============================================================================
+@sio.on("connect")
+async def handle_connect(sid: str, environ: dict[str, Any]) -> None:  # type: ignore[misc]
+    logger.info(f"Client connected: {sid}")
+
+
+@sio.on("disconnect")
+async def handle_disconnect(sid: str) -> None:  # type: ignore[misc]
+    logger.info(f"Client disconnected: {sid}")
+    if sid in clients:
+        httpx_client, _, _ = clients.pop(sid)
+        await httpx_client.aclose()
+        logger.info(f"Cleaned up client for {sid}")
+
+
+@sio.on("initialize_client")
+async def handle_initialize_client(sid: str, data: dict[str, Any]) -> None:  # type: ignore[misc]
+    """
+    Prepare an A2A client for chat/streaming. If a2a is not installed, reply with a warning
+    so the UI still proceeds (card viewing still works via HTTP).
+    """
+    if not HAS_A2A:
+        await sio.emit(
+            "client_initialized",
+            {"status": "warning", "message": "A2A SDK not installed; chat/streaming disabled."},
+            to=sid,
+        )
+        return
+
+    agent_card_url = data.get("url")
+    custom_headers = data.get("customHeaders", {})
+    if not agent_card_url:
+        await sio.emit("client_initialized", {"status": "error", "message": "Agent URL is required."}, to=sid)
+        return
+
+    try:
+        httpx_client = httpx.AsyncClient(timeout=600.0, headers=custom_headers)
+        card_resolver = get_card_resolver(httpx_client, agent_card_url)
+        card = await card_resolver.get_agent_card()
+        a2a_client = A2AClient(httpx_client, agent_card=card)
+        clients[sid] = (httpx_client, a2a_client, card)
+        await sio.emit("client_initialized", {"status": "success"}, to=sid)
+    except Exception as e:
+        await sio.emit("client_initialized", {"status": "error", "message": str(e)}, to=sid)
+
+
+@sio.on("send_message")
+async def handle_send_message(sid: str, json_data: dict[str, Any]) -> None:  # type: ignore[misc]
+    if not HAS_A2A:
+        await sio.emit("agent_response", {"error": "A2A SDK not installed", "id": json_data.get("id")}, to=sid)
+        return
+
+    message_text = bleach.clean(json_data.get("message", ""))
+    message_id = json_data.get("id", str(uuid4()))
+    context_id = json_data.get("contextId")
+    metadata = json_data.get("metadata", {})
+
+    if sid not in clients:
+        await sio.emit("agent_response", {"error": "Client not initialized.", "id": message_id}, to=sid)
+        return
+
+    _, a2a_client, card = clients[sid]
+
+    message = Message(
+        role=Role.user,
+        parts=[TextPart(text=str(message_text))],  # type: ignore[list-item]
+        message_id=message_id,
+        context_id=context_id,
+        metadata=metadata,
+    )
+    payload = MessageSendParams(
+        message=message,
+        configuration=MessageSendConfiguration(accepted_output_modes=["text/plain", "video/mp4"]),
+    )
+    supports_streaming = hasattr(card.capabilities, "streaming") and card.capabilities.streaming is True
+
+    try:
+        if supports_streaming:
+            stream_request = SendStreamingMessageRequest(
+                id=message_id, method="message/stream", jsonrpc="2.0", params=payload
+            )
+            await _emit_debug_log(sid, message_id, "request", stream_request.model_dump(exclude_none=True))
+            response_stream = a2a_client.send_message_streaming(stream_request)
+            async for stream_result in response_stream:
+                await _process_a2a_response(stream_result, sid, message_id)
+        else:
+            send_message_request = SendMessageRequest(
+                id=message_id, method="message/send", jsonrpc="2.0", params=payload
+            )
+            await _emit_debug_log(sid, message_id, "request", send_message_request.model_dump(exclude_none=True))
+            send_result = await a2a_client.send_message(send_message_request)
+            await _process_a2a_response(send_result, sid, message_id)
+    except Exception as e:
+        await sio.emit("agent_response", {"error": f"Failed to send message: {e}", "id": message_id}, to=sid)
+
+__all__ = ["router", "socketio_app", "HAS_SOCKETIO"]

app/static/styles.css

@@ -0,0 +1,243 @@
+/* ================================
+   MatrixHub / A2A Validator Styles
+   (app/static/styles.css)
+   ================================ */
+
+/* Theme tokens (inherits nicely with base.html) */
+:root {
+  --bg: #020402;
+  --bg2: #071007;
+  --surface: #061006cc;
+  --text: #c8facc;
+  --muted: #9aa29a;
+  --matrix: #00ff9c;
+  --border: rgba(0,255,156,0.18);
+  --border-strong: #0d1e0f;
+  --code-bg: #020a04;         /* solid code background to stop canvas bleed */
+}
+
+/* Container (kept for compatibility with older markup) */
+.container {
+  max-width: 980px;
+  margin: 2rem auto;
+  font-family: "Share Tech Mono", monospace;
+  color: var(--text);
+}
+
+/* Simple spacing helpers used by script.js flows */
+.url-input-container,
+.connect-btn-container,
+.chat-input-container {
+  margin: 1rem 0;
+}
+
+/* Key-Value rows (HTTP headers / metadata rows) */
+.kv-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr auto;
+  gap: .5rem;
+  margin-bottom: .5rem;
+  align-items: center;
+}
+
+.kv-row input[type="text"],
+.kv-row input[type="search"],
+.kv-row input[type="url"] {
+  background: rgba(0,0,0,0.35);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  color: var(--text);
+  padding: 10px 12px;
+  outline: none;
+}
+
+.kv-row input:focus {
+  border-color: var(--matrix);
+  box-shadow: 0 0 0 3px rgba(0,255,156,0.08);
+}
+
+.kv-del {
+  padding: .45rem .7rem;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  color: var(--muted);
+  background: rgba(0,0,0,0.25);
+  cursor: pointer;
+  transition: filter .15s ease, box-shadow .15s ease, background .15s ease;
+}
+.kv-del:hover {
+  color: #032215;
+  background: linear-gradient(180deg, #00ff9c, #00c97e);
+  box-shadow: 0 8px 24px rgba(0,255,156,0.25);
+}
+
+/* Collapsible helpers */
+.collapsible-content.hidden,
+.hidden { display: none; }
+
+/* Chat bubbles (dark theme) */
+.chat-bubble {
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: .6rem .7rem;
+  margin: .5rem 0;
+  background: rgba(0,0,0,0.25);
+  cursor: pointer;
+  transition: box-shadow .15s ease, transform .05s ease, background .15s ease;
+}
+.chat-bubble:hover {
+  background: rgba(0,0,0,0.35);
+}
+.chat-bubble:active {
+  transform: translateY(1px);
+}
+.chat-bubble.ok {
+  box-shadow: 0 0 0 1px rgba(0,255,156,0.18);
+}
+.chat-bubble.warn {
+  box-shadow: 0 0 0 1px rgba(255,196,0,0.22);
+}
+
+/* Chat bubble header line */
+.chat-head {
+  font-weight: 700;
+  color: var(--matrix);
+  margin-bottom: .25rem;
+  letter-spacing: .02em;
+}
+
+/* Status colors used in various places */
+.ok   { color: #35d08c; }
+.warn { color: #e2a339; }
+
+/* Placeholder/aux text */
+.placeholder-text { color: var(--muted); }
+
+/* ===============================
+   Debug Console (dark, sticky)
+   =============================== */
+#debug-console {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  width: 460px;
+  max-height: 60vh;
+  background: #0a140a;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  box-shadow: 0 12px 36px rgba(0,0,0,.35), 0 0 0 1px rgba(0,255,156,.05);
+  z-index: 1000;
+}
+#debug-console.hidden { display: none; }
+
+#debug-handle {
+  background: #000;
+  color: var(--text);
+  padding: .6rem .8rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  letter-spacing: .08em;
+  border-bottom: 1px solid var(--border);
+}
+
+#debug-content {
+  padding: .6rem .8rem;
+  max-height: 48vh;
+  overflow: auto;
+  font-family: "Share Tech Mono", monospace;
+}
+
+/* Make logged JSON blocks readable and SOLID (no canvas bleed-through) */
+#debug-content pre {
+  background: var(--code-bg) !important;
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 10px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* ===============================
+   Code / Pre blocks — OPAQUE FIX
+   =============================== */
+
+/* Global default for code/pre used across validator */
+pre, code, pre code {
+  background: var(--code-bg) !important;  /* solid background */
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+}
+
+/* Specific areas we know render JSON (agent card, modal, chat bubbles) */
+#agent-card-content,
+.agent-card-display pre,
+.agent-card-display pre code,
+#modal-json-content,
+.chat-bubble pre {
+  background: var(--code-bg) !important;
+  backdrop-filter: none !important;
+}
+
+/* Highlight.js fallback (some themes force their own bg) */
+.hljs,
+code.hljs {
+  background: var(--code-bg) !important;
+  color: var(--text);
+  border-radius: 10px;
+  padding: 10px;
+}
+
+/* ===============================
+   Buttons (generic)
+   =============================== */
+button,
+.button {
+  background: linear-gradient(180deg, #00ff9c, #00c97e);
+  color: #032215;
+  border: 0;
+  padding: .6rem .9rem;
+  border-radius: 12px;
+  font-weight: 800;
+  font-family: "Share Tech Mono", monospace;
+  letter-spacing: .03em;
+  cursor: pointer;
+  box-shadow: 0 8px 24px rgba(0,255,156,0.25);
+  transition: transform .05s ease, box-shadow .15s ease, filter .15s ease;
+}
+button:hover,
+.button:hover { filter: brightness(1.05); box-shadow: 0 12px 36px rgba(0,255,156,0.35); }
+button:active,
+.button:active { transform: translateY(1px); }
+button:disabled {
+  background: #0b1a12;
+  color: var(--muted);
+  border: 1px solid var(--border);
+  box-shadow: none;
+  cursor: not-allowed;
+}
+
+/* Inputs (generic) */
+input[type="text"],
+input[type="search"],
+input[type="url"] {
+  width: 100%;
+  color: var(--text);
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 10px 12px;
+  font-size: 14px;
+  font-family: "Share Tech Mono", monospace;
+  outline: none;
+  transition: border-color .15s ease, box-shadow .15s ease;
+}
+input[type="text"]:focus,
+input[type="search"]:focus,
+input[type="url"]:focus {
+  border-color: var(--matrix);
+  box-shadow: 0 0 0 3px rgba(0,255,156,0.08), 0 0 12px rgba(0,255,156,0.25) inset;
+}

app/templates/base.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>matrix-ai</title>
+
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Share+Tech+Mono&family=Inter:wght@400;600&display=swap" rel="stylesheet">
+
+    <style>
+      :root {
+          --bg: #020402;
+          --bg2: #071007;
+          --text: #c8facc;
+          --muted: #7ef7a7;
+          --matrix: #00ff9c;
+          --card: #061006cc; /* translucent */
+          --border: #0d1e0f;
+      }
+      html, body { height: 100%; }
+      body {
+          margin: 0;
+          color: var(--text);
+          background:
+            radial-gradient(1200px 800px at 100% -10%, rgba(0,255,156,0.06), transparent 40%),
+            radial-gradient(1000px 600px at -10% 100%, rgba(0,255,156,0.05), transparent 40%),
+            linear-gradient(180deg, var(--bg), var(--bg2) 60%, var(--bg));
+          font-family: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+          overflow-y: auto;
+      }
+      body::after {
+          content: "";
+          position: fixed;
+          inset: 0;
+          pointer-events: none;
+          background: repeating-linear-gradient(to bottom, rgba(0,0,0,0.06) 0px, rgba(0,0,0,0.06) 1px, transparent 2px, transparent 3px);
+          mix-blend-mode: overlay;
+          opacity: 0.6;
+          z-index: 0;
+      }
+      #code-rain {
+          position: fixed;
+          inset: 0;
+          width: 100vw;
+          height: 100vh;
+          z-index: 0;
+          pointer-events: none;
+          opacity: 0.65;
+      }
+      header {
+          position: sticky; top: 0; z-index: 3;
+          display: flex; align-items: center; gap: 18px;
+          padding: 18px 22px;
+          background: linear-gradient(180deg, rgba(0,0,0,0.35), rgba(0,0,0,0));
+          border-bottom: 1px solid var(--border);
+          backdrop-filter: blur(4px);
+      }
+      .brand {
+          font-family: "Share Tech Mono", monospace;
+          color: var(--matrix);
+          text-shadow: 0 0 8px rgba(0,255,156,0.4);
+          letter-spacing: 0.04em;
+          font-size: 18px;
+      }
+      nav a {
+          color: var(--muted);
+          text-decoration: none;
+          margin-right: 16px;
+          transition: color .15s ease, text-shadow .15s ease;
+      }
+      nav a:hover {
+          color: var(--matrix);
+          text-shadow: 0 0 8px rgba(0,255,156,0.4);
+      }
+      .wrap { position: relative; z-index: 2; max-width: 980px; margin: 0 auto; padding: 26px 22px 60px; }
+      .card {
+          background: var(--card);
+          border: 1px solid var(--border);
+          border-radius: 16px;
+          box-shadow: 0 0 0 1px rgba(0,255,156,0.06), 0 8px 30px rgba(0,0,0,0.35);
+          padding: 20px;
+      }
+      h2, h3, h4 { font-family: "Share Tech Mono", monospace; color: var(--matrix); letter-spacing: .02em; }
+      p { color: var(--text); opacity: 0.95; }
+      input, textarea {
+          width: 100%;
+          color: var(--text);
+          background: #020a04;
+          border: 1px solid var(--border);
+          border-radius: 12px;
+          padding: 12px 12px;
+          font-size: 14px;
+          font-family: "Share Tech Mono", monospace;
+          outline: none;
+          transition: border-color .15s ease, box-shadow .15s ease;
+      }
+      input:focus, textarea:focus {
+          border-color: var(--matrix);
+          box-shadow: 0 0 0 3px rgba(0,255,156,0.08), 0 0 12px rgba(0,255,156,0.25) inset;
+      }
+      button {
+          background: linear-gradient(180deg, #00ff9c, #00c97e);
+          color: #002f1b;
+          border: 0;
+          padding: 10px 16px;
+          border-radius: 12px;
+          font-weight: 700;
+          font-family: "Share Tech Mono", monospace;
+          letter-spacing: 0.03em;
+          cursor: pointer;
+          box-shadow: 0 6px 20px rgba(0,255,156,0.25);
+          transition: transform .05s ease, box-shadow .15s ease, filter .15s ease;
+      }
+      button:hover { filter: brightness(1.05); box-shadow: 0 10px 30px rgba(0,255,156,0.35); }
+      button:active { transform: translateY(1px); }
+      pre, code {
+          font-family: "Share Tech Mono", monospace;
+          background: #020a04;
+          border: 1px solid var(--border);
+          border-radius: 12px;
+      }
+      pre { padding: 12px; overflow: auto; }
+      @keyframes glow {
+          0%, 100% { text-shadow: 0 0 10px rgba(0,255,156,0.12); }
+          50%      { text-shadow: 0 0 14px rgba(0,255,156,0.28); }
+      }
+      h3 { animation: glow 3.5s ease-in-out infinite; }
+    </style>
+</head>
+<body>
+    <canvas id="code-rain"></canvas>
+
+    <header>
+        <div class="brand">MATRIX-AI</div>
+        <nav>
+            <a href="/validator">Validator</a>
+            <a href="/home">Info</a>
+            <a href="https://github.com/agent-matrix/matrix-ai" target="_blank" rel="noreferrer" title="Give me a star on GitHub!">GitHub</a>
+        </nav>
+    </header>
+
+    <div class="wrap">
+        {% block body %}{% endblock %}
+    </div>
+
+    <script>
+      (function () {
+          const c = document.getElementById('code-rain');
+          if (!c) return;
+          const ctx = c.getContext('2d', { alpha: true });
+          let w, h, cols, drops;
+          const fontSize = 20;
+          const charSet = 'アァカサタナハマヤラワ0123456789アイウエオｱｲｳｴｵ01';
+
+          function resize() {
+              w = c.width = window.innerWidth;
+              h = c.height = window.innerHeight;
+              cols = Math.floor(w / fontSize);
+              drops = Array(cols).fill(0).map(() => Math.floor(Math.random() * -50));
+              ctx.font = fontSize + "px 'Share Tech Mono', monospace";
+          }
+
+          function draw() {
+              ctx.fillStyle = 'rgba(2, 10, 4, 0.10)';
+              ctx.fillRect(0, 0, w, h);
+              for (let i = 0; i < cols; i++) {
+                  const x = i * fontSize;
+                  const y = drops[i] * fontSize;
+                  const ch = charSet[Math.floor(Math.random() * charSet.length)];
+                  ctx.shadowColor = 'rgba(0,255,156,0.35)';
+                  ctx.shadowBlur = 8;
+                  ctx.fillStyle = '#00ff9c';
+                  ctx.fillText(ch, x, y);
+                  if (y > h && Math.random() > 0.975) drops[i] = 0;
+                  else drops[i]++;
+              }
+              setTimeout(draw, 70);
+          }
+
+          window.addEventListener('resize', resize);
+          resize();
+          draw();
+      })();
+    </script>
+</body>
+</html>

app/templates/home.html

@@ -0,0 +1,168 @@
+{% extends "base.html" %}
+{% block body %}
+  <div class="card" style="padding:28px">
+    <div class="hero" style="display:grid; gap:14px;">
+      <div class="badge">MatrixHub • A2A Verification</div>
+      <h1 style="margin:0">MatrixHub</h1>
+      <p class="lede">
+        MatrixHub uses <strong>A2A agents</strong> and <strong>MCP servers</strong> to deliver
+        plug-and-play building blocks for <em>multi-agent applications</em>. This instance ships
+        a compact <strong>A2A Validator</strong> UI so you can quickly connect to agents,
+        inspect their <em>Agent Card</em>, and validate protocol compliance.
+      </p>
+
+      <div class="cta">
+        <a class="btn" href="/validator">Open Validator</a>
+      </div>
+
+      <div class="meta">
+        <span class="chip">Product: MatrixHub Validator</span>
+        <span class="chip">Version: {{ request.app.version }}</span>
+        <span class="chip">Endpoints: /validator · /agent-card · /healthz · /readyz</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="grid">
+    <div class="card feature">
+      <div class="icon">🤝</div>
+      <h3>What is A2A?</h3>
+      <p>
+        <strong>A2A (Agent-to-Agent)</strong> is a simple, open protocol that lets independently
+        built AI agents talk to each other over the web. It standardizes three things:
+      </p>
+      <div class="list">
+        <div>• <strong>Discovery</strong> — every agent publishes an <em>Agent Card</em> (JSON) with
+          name/description/version, capabilities (e.g. streaming), skills, and default IO modes.
+          Think of it like “openapi.json” for agents.</div>
+        <div>• <strong>Messaging</strong> — structured events over HTTP/JSON-RPC (and optionally websockets):
+          <code>message</code>, <code>task</code>, <code>status-update</code>, <code>artifact-update</code>;
+          supports streaming; carries metadata for auth/tenancy.</div>
+        <div>• <strong>Interop rules</strong> — content types, IDs, correlation, and validation
+          so different frameworks can compose cleanly.</div>
+      </div>
+      <p style="margin-top:8px">
+        <strong>Why it matters:</strong> interoperability, discoverability, portability, safety/compliance,
+        and composability (fan-out, tools-as-agents) with consistent IDs and streaming.
+      </p>
+    </div>
+
+    <div class="card feature">
+      <div class="icon">🧭</div>
+      <h3>Where MatrixHub fits</h3>
+      <p>MatrixHub is the “registry + utilities” layer for A2A:</p>
+      <div class="list">
+        <div>• <strong>Directory/Catalog:</strong> publish & discover A2A-compatible agents by skill, version, trust.</div>
+        <div>• <strong>Validation & QA:</strong> lint Agent Cards and live endpoints (what this Validator UI does).</div>
+        <div>• <strong>Routing/Relay:</strong> optional proxy for CORS, auth, rate-limits, observability.</div>
+        <div>• <strong>Dev Experience:</strong> templates, SDKs, and “try it” UIs for quick local testing.</div>
+        <div>• <strong>Governance:</strong> versions, deprecation, and optional signing (provenance & trust).</div>
+      </div>
+      <p style="margin-top:8px">
+        Think of MatrixHub as the connective tissue that makes A2A practical at team/org scale.
+      </p>
+    </div>
+
+    <div class="card feature">
+      <div class="icon">🧩</div>
+      <h3>A2A on MCP servers</h3>
+      <p>
+        MCP is great for wiring <em>tools</em> to <em>clients</em> (e.g., editor ↔ tools). A2A complements MCP for
+        agent↔agent federation across domains:
+      </p>
+      <div class="list">
+        <div>• <strong>Expose MCP tools as A2A skills:</strong> publish an Agent Card; other agents can discover/call them.</div>
+        <div>• <strong>Cross-ecosystem calls:</strong> LLM agents, workflows, or other MCP servers invoke via A2A without speaking MCP.</div>
+        <div>• <strong>Uniform messaging:</strong> map MCP tool calls to A2A <code>message</code>/<code>task</code> and use A2A streaming.</div>
+        <div>• <strong>Catalog integration:</strong> MatrixHub indexes your MCP server by its Agent Card for discovery & testing.</div>
+      </div>
+      <p style="margin-top:8px">
+        Net effect: MCP stays your local tool bridge; A2A turns it into an internet-addressable agent other agents can compose with.
+      </p>
+    </div>
+  </div>
+
+  <div class="card arch">
+    <h3 style="margin-top:0">What this program does now</h3>
+    <div class="diagram">
+      <div class="lane">
+        <div class="box user">You</div>
+        <div class="arrow">/validator</div>
+        <div class="box ai">MatrixHub Validator</div>
+        <div class="arrow">/agent-card</div>
+        <div class="box svc">Target Agent (A2A)</div>
+      </div>
+    </div>
+
+    <div class="quick">
+      <p><strong>Summary:</strong> This instance exposes a lightweight A2A Validator:</p>
+      <div class="list" style="margin-top:6px">
+        <div>• <strong>Validator UI</strong> at <code>/validator</code> — connect to an agent URL, fetch & validate its Agent Card.</div>
+        <div>• <strong>Alias</strong> <code>POST /agent-card</code> → <code>/validator/agent-card</code> (frontend default).</div>
+        <div>• <strong>Health</strong> endpoints: <code>/healthz</code>, <code>/readyz</code>.</div>
+        <div>• <strong>Socket.IO</strong> mounted at <code>/socket.io</code> (used for debug logs & future streaming).</div>
+        <div>• RAG/Chat/Plan routes are disabled here to keep the focus on A2A verification.</div>
+      </div>
+
+      <details style="margin-top:10px">
+        <summary>Quick start (local)</summary>
+        <pre><code># Run the service
+uvicorn app.main:app --host 0.0.0.0 --port 7860
+
+# Open the Validator UI
+# → http://localhost:7860/validator
+
+# (Optional) Resolve an Agent Card directly (server alias)
+curl -s -X POST http://localhost:7860/agent-card \
+  -H 'content-type: application/json' \
+  -d '{"url":"https://example.com/.well-known/agent.json","sid":"debug"}' | jq</code></pre>
+      </details>
+    </div>
+  </div>
+
+  <style>
+    .hero .badge{
+      display:inline-block; font-size:12px; letter-spacing:.06em;
+      color:#002f1b; background:linear-gradient(180deg,#00ff9c,#00c97e);
+      border-radius:999px; padding:6px 10px; font-weight:700;
+      box-shadow:0 6px 24px rgba(0,255,156,.25);
+    }
+    h1 { font-family:"Share Tech Mono", monospace; color:var(--matrix); letter-spacing:.03em; }
+    .lede { font-size:16px; opacity:.95; max-width:64ch; }
+    .cta { display:flex; gap:10px; margin-top:4px; flex-wrap:wrap; }
+    .btn {
+      display:inline-block; text-decoration:none; padding:10px 14px; border-radius:12px;
+      font-weight:700; font-family:"Share Tech Mono", monospace; letter-spacing:.03em;
+      background:linear-gradient(180deg,#00ff9c,#00c97e); color:#032215;
+      box-shadow:0 6px 20px rgba(0,255,156,.25);
+    }
+    .btn.ghost { background:#0b1a12; color:var(--muted); border:1px solid var(--border); box-shadow:none; }
+    .btn:hover { filter:brightness(1.05); }
+    .meta { display:flex; gap:10px; flex-wrap:wrap; margin-top:6px; }
+    .chip {
+      font-size:12px; border:1px solid var(--border); border-radius:999px;
+      padding:4px 10px; background:#061006a6;
+    }
+    .grid {
+      margin:22px auto; display:grid; gap:16px;
+      grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+    }
+    .feature .icon { font-size:22px; margin-bottom:4px; }
+    .feature .list { margin-top:6px; opacity:.9; font-size:14px; display:grid; gap:4px; }
+    .arch { margin-top:18px; }
+    .diagram { margin-top:8px; display:grid; gap:8px; }
+    .lane { display:flex; gap:10px; align-items:center; flex-wrap:wrap; }
+    .box {
+      padding:8px 10px; border-radius:10px; border:1px solid var(--border);
+      background:#020a04; font-family:"Share Tech Mono", monospace; font-size:13px;
+    }
+    .svc { box-shadow:0 0 0 1px rgba(0,255,156,.08); }
+    .ai  { box-shadow:0 0 0 1px rgba(0,255,156,.12); }
+    .user{ box-shadow:0 0 0 1px rgba(0,255,156,.08); }
+    .arrow { opacity:.7; font-family:"Share Tech Mono", monospace; }
+    .quick { margin-top:8px; display:grid; gap:8px; }
+    details { border:1px solid var(--border); border-radius:12px; padding:8px 10px; background:#06100680; }
+    details summary { cursor:pointer; user-select:none; color:var(--muted); }
+    pre { margin:8px 0 0; }
+  </style>
+{% endblock %}

app/templates/validator.html

@@ -0,0 +1,208 @@
+{% extends "base.html" %}
+{% block body %}
+
+<div class="card">
+  <h3>A2A Validator /// MATRIX NODE</h3>
+
+  <div class="fieldset">
+    <div class="fieldset-head" id="connection-header">ESTABLISH CONNECTION</div>
+    <div class="fieldset-body" style="display:grid; gap:12px; margin-top:12px;">
+      <input type="text" id="agent-card-url" placeholder="Enter Agent Card URL" />
+      <div class="fieldset inner">
+        <div class="fieldset-head http-headers-header" id="http-headers-toggle">
+          <span class="chev">►</span> HTTP HEADERS
+        </div>
+        <div class="fieldset-body http-headers-content" id="http-headers-content" style="display:none;">
+          <div id="headers-list"></div>
+          <button id="add-header-btn" type="button">+ Add Header</button>
+        </div>
+      </div>
+      <div class="actions-row">
+        <button id="connect-btn" type="button">Connect</button>
+        <a class="link" href="https://a2a-protocol.org/latest/" target="_blank" rel="noreferrer">Protocol Docs ↗</a>
+      </div>
+    </div>
+  </div>
+
+  <div id="agent-card-section" class="fieldset" style="margin-top:16px;">
+    <h2 class="collapsible-header">
+      <span class="toggle-icon">▼</span> AGENT CARD
+    </h2>
+    <div class="collapsible-content">
+      <div id="validation-errors">
+        <p class="muted">Awaiting connection to view agent card...</p>
+      </div>
+      <div class="agent-card-display">
+          <pre><code id="agent-card-content" class="language-json"></code></pre>
+      </div>
+    </div>
+  </div>
+
+  <div id="chat-container" class="fieldset" style="margin-top:16px;">
+    <div class="fieldset-head chat-header">CHAT TERMINAL</div>
+    <div class="fieldset-body">
+      <p class="muted chat-info">Agent messages marked with ✅ (compliant) or ⚠️ (non-compliant). Click to view raw JSON.</p>
+      <div id="chat-messages" class="chat-list">
+        <p class="muted placeholder-text">Messages will appear here.</p>
+      </div>
+      <div class="fieldset inner message-metadata-container">
+        <div class="fieldset-head message-metadata-header" id="message-metadata-toggle">
+          <span class="chev">►</span> MESSAGE METADATA
+        </div>
+        <div class="fieldset-body message-metadata-content" id="message-metadata-content" style="display:none;">
+          <div id="metadata-list"></div>
+          <button id="add-metadata-btn" type="button">+ Add Metadata</button>
+        </div>
+      </div>
+      <div class="row chat-input-container" style="margin-top:10px;">
+        <input type="text" id="chat-input" placeholder="> Type a message…" disabled />
+        <button id="send-btn" type="button" disabled>Send</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div id="loader" class="loader-overlay" aria-hidden="true" style="display:none;">
+  <div class="loader-wrap">
+    <div class="loader-spinner"></div>
+    <div class="loader-text">CONNECTING…</div>
+  </div>
+</div>
+
+<div id="debug-console" class="hidden">
+  <div id="debug-handle">
+    <span>Debug Console</span>
+    <div class="debug-controls">
+      <button id="clear-console-btn">Clear</button>
+      <button id="toggle-console-btn">Show</button>
+    </div>
+  </div>
+  <div id="debug-content"></div>
+</div>
+
+<div id="json-modal" class="modal-overlay hidden">
+  <div class="modal-content">
+    <span class="modal-close-btn">&times;</span>
+    <h3>Raw JSON</h3>
+    <pre id="modal-json-content"></pre>
+  </div>
+</div>
+
+<style>
+  :root {
+    --matrix: #00ff9c;
+    --border: rgba(0, 255, 156, 0.2);
+    --background: #020a04;
+    --dark-surface: #0a140a;
+    --muted-2: #9aa29a;
+  }
+  body {
+    font-family: "Share Tech Mono", monospace;
+    background-color: var(--background);
+    color: #e0e0e0;
+    margin: 0;
+    padding: 2rem;
+  }
+  body::before{
+    content:"";
+    position: fixed;
+    inset:0;
+    z-index:-1;
+    background:
+      radial-gradient(800px 500px at 50% -20%, rgba(0,255,156,0.08), transparent 40%),
+      linear-gradient(180deg, rgba(0,0,0,0.72), rgba(0,0,0,0.65));
+  }
+
+  .card { position: relative; z-index: 1; max-width: 800px; margin: 0 auto; }
+  h1, h2, h3, .fieldset-head { text-transform: uppercase; }
+  h1 { color: var(--matrix); }
+  h2 { font-size: 1em; margin: 0; }
+  .muted { color: var(--muted-2, #9aa29a); }
+  .row { display:flex; gap:8px; align-items: center; }
+  .row input[type="text"] { flex:1; }
+  .actions-row { display: flex; gap: 12px; align-items: center; }
+  
+  .fieldset { border: 1px solid var(--border); border-radius: 12px; padding: 12px; background: rgba(2,10,4,0.35); backdrop-filter: blur(2px); }
+  .fieldset.inner { background: rgba(2,10,4,0.25); border-color: rgba(128, 128, 128, 0.3); }
+  .fieldset-head, .collapsible-header { font-weight: 600; letter-spacing: .02em; cursor: pointer; user-select:none; display:flex; align-items:center; gap:6px; color: var(--matrix); text-shadow: 0 0 5px var(--matrix); padding: 5px; }
+  .fieldset-body, .collapsible-content { padding-top: 4px; }
+  .fieldset-body pre { background: #020a04; border: 1px solid var(--border); border-radius: 8px; padding: 10px; margin: 8px 0 0 0; }
+  .chev, .toggle-icon { font-family: ui-monospace, "Share Tech Mono", monospace; }
+
+  input, button { font-family: inherit; }
+  input[type="text"] { background: rgba(0,0,0,0.3); border: 1px solid var(--border); border-radius: 8px; padding: 10px; color: #e0e0e0; }
+  button { background: transparent; border: 1px solid var(--matrix); color: var(--matrix); padding: 10px 15px; border-radius: 8px; cursor: pointer; transition: all 0.2s; }
+  button:hover:not(:disabled) { background: var(--matrix); color: var(--background); box-shadow: 0 0 10px var(--matrix); }
+  button:disabled { border-color: var(--muted-2); color: var(--muted-2); cursor: not-allowed; }
+
+  .chat-list { height: 300px; overflow-y: auto; background: rgba(0,0,0,0.3); border: 1px solid var(--border); border-radius: 8px; padding: 10px; }
+  .chat-info { font-size: 0.9em; }
+
+  /* Debug & Modal Styling (adapted for Matrix theme) */
+  #debug-console { position: fixed; bottom: 0; left: 0; right: 0; height: 200px; background: var(--dark-surface); border-top: 2px solid var(--matrix); display: flex; flex-direction: column; z-index: 100; }
+  #debug-console.hidden { display: none; }
+  #debug-handle { background: #000; padding: 5px 10px; cursor: ns-resize; display: flex; justify-content: space-between; align-items: center; text-transform: uppercase; letter-spacing: 0.1em; }
+  #debug-content { flex-grow: 1; overflow-y: auto; padding: 10px; font-size: 0.9em; }
+  .modal-overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.8); backdrop-filter: blur(5px); z-index: 1000; display: flex; align-items: center; justify-content: center; }
+  .modal-overlay.hidden { display: none; }
+  .modal-content { position: relative; background: var(--dark-surface); border: 1px solid var(--border); border-radius: 12px; padding: 20px; max-width: 800px; width: 90%; max-height: 80vh; display: flex; flex-direction: column; }
+  .modal-close-btn { position: absolute; top: 10px; right: 15px; font-size: 24px; cursor: pointer; color: var(--matrix); }
+
+  /* Loader Styling (same as before) */
+  .loader-overlay { position: fixed; inset: 0; z-index: 9999; display: none; align-items: center; justify-content: center; backdrop-filter: blur(3px); background: radial-gradient(800px 500px at 50% -20%, rgba(0,255,156,0.08), transparent 40%), linear-gradient(180deg, rgba(0,0,0,0.72), rgba(0,0,0,0.65)); }
+  .loader-wrap { display: flex; flex-direction: column; align-items: center; gap: 14px; padding: 22px 26px; border-radius: 16px; border: 1px solid var(--border); background: rgba(6,16,6,0.75); box-shadow: 0 10px 40px rgba(0,0,0,0.45), 0 0 0 1px rgba(0,255,156,0.06); }
+  .loader-spinner { width: 64px; height: 64px; border-radius: 50%; border: 3px solid rgba(0,255,156,0.15); border-top-color: var(--matrix); border-right-color: var(--matrix); box-shadow: 0 0 18px rgba(0,255,156,0.35); animation: spin 0.9s linear infinite; }
+  .loader-text { font-family: "Share Tech Mono", monospace; letter-spacing: 0.08em; color: var(--matrix); text-shadow: 0 0 8px rgba(0,255,156,0.35); opacity: 0.95; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+</style>
+
+<script src="https://cdn.socket.io/4.7.5/socket.io.min.js"></script>
+<script src="/static/script.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+
+<script>
+  // Raining Code Effect
+  const canvas = document.getElementById('matrix-canvas');
+  if (canvas) {
+    const ctx = canvas.getContext('2d');
+    canvas.width = window.innerWidth;
+    canvas.height = window.innerHeight;
+    const alphabet = 'アァカサタナハマヤャラワガザダバパイィキシチニヒミリヰギジヂビピウゥクスツヌフムユュルグズブプエェケセテネヘメレヱゲゼデベペオォコソトノホモヨョロヲゴゾドボポヴッンABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    const fontSize = 16;
+    const columns = canvas.width / fontSize;
+    const rainDrops = Array.from({ length: columns }).fill(1);
+    const draw = () => {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.05)';
+        ctx.fillRect(0, 0, canvas.width, canvas.height);
+        ctx.fillStyle = '#0F0';
+        ctx.font = fontSize + 'px monospace';
+        for (let i = 0; i < rainDrops.length; i++) {
+            const text = alphabet.charAt(Math.floor(Math.random() * alphabet.length));
+            ctx.fillText(text, i * fontSize, rainDrops[i] * fontSize);
+            if (rainDrops[i] * fontSize > canvas.height && Math.random() > 0.975) {
+                rainDrops[i] = 0;
+            }
+            rainDrops[i]++;
+        }
+    };
+    setInterval(draw, 33);
+  }
+
+  // The main script.js will handle its own toggles now that the HTML is correct.
+  // We only need to add listeners for the fieldsets that script.js doesn't know about.
+  (function () {
+      function setupToggle(toggleEl, contentEl) {
+          if (!toggleEl || !contentEl) return;
+          toggleEl.addEventListener('click', () => {
+              const isHidden = contentEl.style.display === 'none';
+              contentEl.style.display = isHidden ? 'block' : 'none';
+              const chev = toggleEl.querySelector('.chev');
+              if (chev) chev.textContent = isHidden ? '▼' : '►';
+          });
+      }
+      // script.js handles '.collapsible-header', so we only set up our custom fieldsets.
+      setupToggle(document.getElementById('http-headers-toggle'), document.getElementById('http-headers-content'));
+      setupToggle(document.getElementById('message-metadata-toggle'), document.getElementById('message-metadata-content'));
+  })();
+</script>
+{% endblock %}

app/ui.py

@@ -0,0 +1,55 @@
+# app/ui.py
+
+from fastapi import APIRouter, Request, Form
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+import httpx
+import os
+import json
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+# Tabs to render in the UI. "Info" is now the active tab for the /home route.
+NAV_TABS = [
+    {"href": "/validator", "label": "Validator"},
+    {"href": "/home", "label": "Info"},
+]
+templates.env.globals["NAV_TABS"] = NAV_TABS
+
+def _self_base_url() -> str:
+    port = os.getenv("PORT", "7860")
+    return f"http://127.0.0.1:{port}"
+
+@router.get("/", include_in_schema=False)
+async def root_redirect():
+    # Default to the Validator page
+    return RedirectResponse(url="/validator", status_code=302)
+
+@router.get("/home", response_class=HTMLResponse, include_in_schema=False)
+async def home_page(request: Request):
+    """
+    FIX: This route now correctly serves the home.html template
+    instead of getting caught in a redirect loop.
+    """
+    return templates.TemplateResponse(
+        "home.html",
+        # Pass the active tab name to the template
+        {"request": request, "tabs": NAV_TABS, "active": "home"},
+    )
+
+# The /chat and /dev routes are not needed based on your last request,
+# so they have been removed to simplify the file.
+# If you need them back, you can uncomment them.
+
+# @router.get("/chat", response_class=HTMLResponse)
+# async def chat_get(request: Request):
+#     return templates.TemplateResponse(
+#         "chat.html",
+#         {"request": request, "answer": None, "tabs": NAV_TABS, "active": "chat"},
+#     )
+
+# @router.get("/dev", response_class=HTMLResponse)
+# async def dev_get(request: Request):
+#     # ... dev page logic ...
+#     pass

app/validators.py

@@ -0,0 +1,226 @@
+# app/validators.py
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, Mapping, Sequence
+from urllib.parse import urlparse
+
+
+# -----------------------------
+# Helpers
+# -----------------------------
+
+_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-]+)?$")
+
+
+def _is_non_empty_str(val: Any) -> bool:
+    return isinstance(val, str) and val.strip() != ""
+
+
+def _is_list_of_str(val: Any) -> bool:
+    return isinstance(val, list) and all(isinstance(x, str) for x in val)
+
+
+def _as_mapping(val: Any) -> Mapping[str, Any] | None:
+    return val if isinstance(val, Mapping) else None
+
+
+def _as_sequence(val: Any) -> Sequence[Any] | None:
+    return val if isinstance(val, Sequence) and not isinstance(val, (str, bytes)) else None
+
+
+# -----------------------------
+# Agent Card Validation
+# -----------------------------
+
+_REQUIRED_AGENT_CARD_FIELDS = frozenset(
+    [
+        "name",
+        "description",
+        "url",
+        "version",
+        "capabilities",
+        "defaultInputModes",
+        "defaultOutputModes",
+        "skills",
+    ]
+)
+
+
+def validate_agent_card(card_data: dict[str, Any]) -> list[str]:
+    """
+    Validate the structure and fields of an agent card.
+
+    Contract (non-exhaustive, pragmatic checks):
+      - Required top-level fields must exist.
+      - url must be absolute (http/https) with a host.
+      - version should be semver-like (e.g., 1.2.3 or 1.2.3-alpha).
+      - capabilities must be an object/dict.
+      - defaultInputModes/defaultOutputModes must be non-empty arrays of strings.
+      - skills must be a non-empty array (objects or strings permitted); if objects, "name" should be string.
+
+    Returns:
+        A list of human-readable error strings. Empty list means "looks valid".
+    """
+    errors: list[str] = []
+    data = card_data or {}
+
+    # Presence of required fields
+    for field in _REQUIRED_AGENT_CARD_FIELDS:
+        if field not in data:
+            errors.append(f"Required field is missing: '{field}'.")
+
+    # Type/format checks (guard with `in` to avoid KeyErrors)
+    # name
+    if "name" in data and not _is_non_empty_str(data["name"]):
+        errors.append("Field 'name' must be a non-empty string.")
+
+    # description
+    if "description" in data and not _is_non_empty_str(data["description"]):
+        errors.append("Field 'description' must be a non-empty string.")
+
+    # url
+    if "url" in data:
+        url_val = data["url"]
+        if not _is_non_empty_str(url_val):
+            errors.append("Field 'url' must be a non-empty string.")
+        else:
+            parsed = urlparse(url_val)
+            if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+                errors.append(
+                    "Field 'url' must be an absolute URL with http(s) scheme and host."
+                )
+
+    # version (soft semver check; adjust if your ecosystem allows non-semver)
+    if "version" in data:
+        ver = data["version"]
+        if not _is_non_empty_str(ver):
+            errors.append("Field 'version' must be a non-empty string.")
+        elif not _SEMVER_RE.match(ver):
+            errors.append(
+                "Field 'version' should be semver-like (e.g., '1.2.3' or '1.2.3-alpha')."
+            )
+
+    # capabilities
+    if "capabilities" in data:
+        if not isinstance(data["capabilities"], dict):
+            errors.append("Field 'capabilities' must be an object.")
+        else:
+            # Optional: sanity checks for common capability fields
+            caps = data["capabilities"]
+            if "streaming" in caps and not isinstance(caps["streaming"], bool):
+                errors.append("Field 'capabilities.streaming' must be a boolean if present.")
+
+    # defaultInputModes / defaultOutputModes
+    for field in ("defaultInputModes", "defaultOutputModes"):
+        if field in data:
+            modes = data[field]
+            if not _is_list_of_str(modes):
+                errors.append(f"Field '{field}' must be an array of strings.")
+            elif len(modes) == 0:
+                errors.append(f"Field '{field}' must not be empty.")
+
+    # skills
+    if "skills" in data:
+        skills = _as_sequence(data["skills"])
+        if skills is None:
+            errors.append("Field 'skills' must be an array.")
+        elif len(skills) == 0:
+            errors.append(
+                "Field 'skills' must not be empty. Agent must have at least one skill if it performs actions."
+            )
+        else:
+            # If entries are objects, check they have a name
+            for i, s in enumerate(skills):
+                if isinstance(s, Mapping):
+                    if not _is_non_empty_str(s.get("name")):
+                        errors.append(f"skills[{i}].name is required and must be a non-empty string.")
+                elif not isinstance(s, str):
+                    errors.append(
+                        f"skills[{i}] must be either an object with 'name' or a string; found: {type(s).__name__}"
+                    )
+
+    return errors
+
+
+# -----------------------------
+# Agent Message/Event Validation
+# -----------------------------
+
+def _validate_task(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if "id" not in data:
+        errors.append("Task object missing required field: 'id'.")
+    status = _as_mapping(data.get("status"))
+    if status is None or "state" not in status:
+        errors.append("Task object missing required field: 'status.state'.")
+    return errors
+
+
+def _validate_status_update(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    status = _as_mapping(data.get("status"))
+    if status is None or "state" not in status:
+        errors.append("StatusUpdate object missing required field: 'status.state'.")
+    return errors
+
+
+def _validate_artifact_update(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    artifact = _as_mapping(data.get("artifact"))
+    if artifact is None:
+        errors.append("ArtifactUpdate object missing required field: 'artifact'.")
+        return errors
+
+    parts = artifact.get("parts")
+    if not isinstance(parts, list) or len(parts) == 0:
+        errors.append("Artifact object must have a non-empty 'parts' array.")
+    return errors
+
+
+def _validate_message(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    parts = data.get("parts")
+    if not isinstance(parts, list) or len(parts) == 0:
+        errors.append("Message object must have a non-empty 'parts' array.")
+    role = data.get("role")
+    if role != "agent":
+        errors.append("Message from agent must have 'role' set to 'agent'.")
+    # Optional: check text presence in at least one part if parts are objects
+    # (Leave relaxed to avoid false negatives if parts are other media-types)
+    return errors
+
+
+_KIND_VALIDATORS: dict[str, callable[[dict[str, Any]], list[str]]] = {
+    "task": _validate_task,
+    "status-update": _validate_status_update,
+    "artifact-update": _validate_artifact_update,
+    "message": _validate_message,
+}
+
+
+def validate_message(data: dict[str, Any]) -> list[str]:
+    """
+    Validate an incoming event/message coming from the agent according to its 'kind'.
+
+    Expected kinds: 'task', 'status-update', 'artifact-update', 'message'
+    Returns:
+        A list of human-readable error strings. Empty list means "looks valid".
+    """
+    if not isinstance(data, Mapping):
+        return ["Response from agent must be an object."]
+    if "kind" not in data:
+        return ["Response from agent is missing required 'kind' field."]
+
+    kind = str(data.get("kind"))
+    validator = _KIND_VALIDATORS.get(kind)
+    if validator:
+        return validator(dict(data))
+
+    return [f"Unknown message kind received: '{kind}'."]
+
+
+__all__ = [
+    "validate_agent_card",
+    "validate_message",
+]

configs/.env.example

@@ -0,0 +1,26 @@
+# === API Keys (DO NOT COMMIT REAL KEYS) ===
+GROQ_API_KEY=your_groq_key_here
+GOOGLE_API_KEY=your_google_gemini_key_here
+HF_TOKEN=your_huggingface_token_here
+
+# === Provider order ===
+# Comma-separated cascade, first working provider wins.
+# Options: groq, gemini, router
+PROVIDER_ORDER=groq,gemini,router
+
+# === Provider-default models (override if needed) ===
+GROQ_MODEL=llama-3.1-8b-instant
+GEMINI_MODEL=gemini-2.5-flash
+
+# === Logging ===
+LOG_LEVEL=INFO
+
+
+
+# For local development only. Use Space Secrets in production.
+ADMIN_TOKEN="a-secure-admin-token-for-index-refresh"
+
+# --- Optional Overrides ---
+# MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.2"
+# INDEX_DATASET="your-username/matrix-ai-index"
+# RATE_LIMITS="120" # requests per minute

configs/rag_sources.yaml

@@ -0,0 +1,41 @@
+# Where to pull documentation from when building the RAG knowledge base.
+# You can add/remove repos here; the builder will respect these sources.
+
+github:
+  # 1) Explicit repos (stable)
+  repos:
+    - owner: agent-matrix
+      name: matrix-cli
+      branch: master
+      docs_paths: ["docs"]      # folders to harvest (recursive)
+      include_readme: true
+    - owner: agent-matrix
+      name: matrix-python-sdk
+      branch: master
+      docs_paths: ["docs"]
+      include_readme: true
+    - owner: agent-matrix
+      name: matrixlink
+      branch: master
+      docs_paths: ["docs"]
+      include_readme: true
+    - owner: agent-matrix
+      name: matrix-hub
+      branch: master
+      docs_paths: ["docs"]
+      include_readme: true
+
+  # 2) Optionally scan an entire org for repos (README + docs/ if present)
+  #    Comment out if you want only the explicit list above.
+  orgs:
+    - agent-matrix
+
+# Local content in THIS repo (optional but recommended)
+local:
+  paths:
+    - docs           # everything under /docs
+    - README.md      # root readme
+  glob: "**/*.md"    # or "**/*.{md,mdx,txt}"
+
+# Extra public URLs to pull (optional)
+urls: []

configs/settings.yaml

@@ -0,0 +1,35 @@
+model:
+  # HF router defaults (used at the last step)
+  name: "HuggingFaceH4/zephyr-7b-beta"
+  fallback: "mistralai/Mistral-7B-Instruct-v0.2"
+  provider: "featherless-ai"
+  max_new_tokens: 256
+  temperature: 0.2
+
+  # Provider-specific defaults (free-tier friendly)
+  groq_model: "llama-3.1-8b-instant"
+  gemini_model: "gemini-2.5-flash"
+
+# Try providers in this order
+provider_order:
+  - groq
+  - gemini
+  - router
+
+# Switch to the multi-provider path
+chat_backend: "multi"
+chat_stream: true
+
+limits:
+  rate_per_min: 60
+  cache_size: 256
+
+rag:
+  index_dataset: ""
+  top_k: 4
+
+matrixhub:
+  base_url: "https://api.matrixhub.io"
+
+security:
+  admin_token: ""

pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a2a-validator"
+version = "0.1.0"
+description = "Agent validator Service for Matrix EcoSystem"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+
+dependencies = [
+    "fastapi==0.111.0",
+    "groq>=0.32.0",
+    "uvicorn[standard]==0.29.0",
+    "httpx==0.28.1",
+    "pydantic>=2.7.1",
+    "python-json-logger==2.0.7",
+    "cachetools==5.3.3",
+    "huggingface-hub==0.23.0",
+    "sentence-transformers==2.7.0",
+    "faiss-cpu==1.8.0",
+    "numpy==1.26.4",
+    "orjson==3.10.3",
+    "pyyaml==6.0.1",
+    "tenacity==8.2.3",
+    "python-dotenv==1.0.1",
+    "google-genai>=1.39.1",
+
+    # --- Added for a2a-validator ---
+    "a2a-sdk[http-server]>=0.3.0",
+    "httpx-sse>=0.4.0",
+    "jwcrypto>=1.5.6",
+    "pyjwt>=2.10.1",
+    "sse-starlette>=2.2.1",
+    "typing-extensions>=4.12.2",
+    # FIX: Ensure all standard websocket dependencies are included
+    "python-socketio[asyncio_standard]>=5.11.0",
+    "jinja2>=3.1.2",
+    "bleach>=6.2.0"
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501"]

requirements.txt

@@ -0,0 +1,33 @@
+fastapi==0.111.0
+uvicorn[standard]==0.29.0
+httpx>=0.28.1
+pydantic>=2.7.1
+python-json-logger==2.0.7
+cachetools==5.3.3
+huggingface-hub==0.23.0
+#sentence-transformers==2.7.0
+#faiss-cpu==1.8.0
+numpy==1.26.4
+orjson==3.10.3
+pyyaml==6.0.1
+tenacity==8.2.3
+jinja2==3.1.4
+a2a-sdk[http-server]>=0.3.0
+python-socketio[asyncio_standard]>=5.11.0
+bleach>=6.2.0
+jinja2>=3.1.2
+
+# Dev (optional)
+pytest
+ruff
+mypy
+pytest-asyncio
+
+# Additional libraries for extended functionality
+#groq>=0.32.0
+python-dotenv==1.0.1
+#google-genai>=1.39.1
+
+requests>=2.32.0
+#beautifulsoup4>=4.12.3   # only used if you later add generic HTML URLs
+PyYAML>=6.0.1