First commit

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

@@ -0,0 +1,72 @@
+# .github/workflows/sync-to-hf-space.yml
+name: Sync to Hugging Face Space (matrix-ai)
+
+on:
+  push:
+    branches: ["main", "master"]
+  workflow_dispatch:
+    inputs:
+      force:
+        description: "Force push HEAD to Space main (use for first-time sync or non-fast-forward)"
+        type: boolean
+        default: false
+      ref:
+        description: "Git ref to push (defaults to current HEAD)"
+        type: string
+        default: ""
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: hf-space-sync-matrix-ai
+      cancel-in-progress: false
+
+    env:
+      # Hard-wired to your Space:
+      HF_SPACE_REMOTE: https://ruslanmv:${HF_TOKEN}@huggingface.co/spaces/ruslanmv/matrix-ai
+
+    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: Resolve ref to push
+        id: ref
+        run: |
+          REF="${{ inputs.ref }}"
+          if [ -z "$REF" ]; then
+            REF="${GITHUB_REF_NAME}"
+          fi
+          echo "ref=$REF" >> "$GITHUB_OUTPUT"
+
+      - name: Push to Hugging Face Space (normal)
+        if: ${{ inputs.force != true }}
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "❌ Missing HF_TOKEN secret. Add it under: Settings → Secrets and variables → Actions → New repository secret."
+            exit 1
+          fi
+          # Always push current HEAD to Space's main (handles master→main mapping)
+          git push "${HF_SPACE_REMOTE}" "HEAD:main"
+
+      - name: Push to Hugging Face Space (force)
+        if: ${{ inputs.force == true }}
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "❌ Missing HF_TOKEN secret. Add it under: Settings → Secrets and variables → Actions → New repository secret."
+            exit 1
+          fi
+          git push --force "${HF_SPACE_REMOTE}" "HEAD:main"

Dockerfile

@@ -1,19 +1,35 @@
+# syntax=docker/dockerfile:1
 FROM python:3.11-slim
 
-WORKDIR /app
-
+# --- base env ---
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1
+    PIP_NO_CACHE_DIR=1 \
+    UVICORN_WORKERS=2
+
+# --- 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
 
-RUN apt-get update && apt-get install -y --no-install-recommends build-essential && \
-    rm -rf /var/lib/apt/lists/*
+# --- python deps layer (better cache) ---
+COPY requirements.txt ./ 
+RUN pip install --upgrade pip && pip install -r requirements.txt
 
-COPY requirements.txt /app/requirements.txt
-RUN pip install --no-cache-dir -r /app/requirements.txt
+# --- copy app ---
+COPY . .
 
-COPY . /app
+# --- Spaces sets $PORT dynamically; honor it ---
+ARG PORT=7860
+ENV PORT=${PORT}
+EXPOSE ${PORT}
 
-EXPOSE 7860
+# Optional: run as non-root (safer)
+# RUN useradd -ms /bin/bash appuser && chown -R appuser:appuser /app
+# USER appuser
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]
+# --- start ---
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "${PORT}"]

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   := matrix-ai:local
+SPACE_URL  ?= https://huggingface.co/spaces/ruslanmv/matrix-ai
+
+# 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 docker-build docker-run space-url clean

app/main.py

@@ -1,18 +1,101 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+from typing import Any, Dict
+
 from fastapi import FastAPI
+from fastapi.responses import JSONResponse, RedirectResponse
+
+# Your existing middleware bundle (req id, rate limit, etag, etc.)
 from .middleware import attach_middlewares
+
+# Core API routers
 from .routers import health, plan, chat
 
+# Optional UI (Home/Chat/Dev). If missing, we gracefully fall back to a JSON root.
+try:
+    from .ui import router as ui_router  # type: ignore
+    HAS_UI = True
+except Exception:  # pragma: no cover
+    HAS_UI = False
+
+
+TAGS_METADATA = [
+    {"name": "Health", "description": "Liveness / readiness probes and basic service metadata."},
+    {"name": "Planning", "description": "AI plan generation for Matrix Guardian (/v1/plan)."},
+    {"name": "Chat", "description": "Lightweight RAG/Q&A about Matrix System (/v1/chat)."},
+    {"name": "UI", "description": "Minimal web UI (Home, Chat, Dev) if enabled."},
+]
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lightweight startup/shutdown hooks.
+    Stores process start time for basic diagnostics and logs boot/shutdown.
+    """
+    app.state.started_at = time.time()
+    app.state.version = os.getenv("APP_VERSION", "1.0.0")
+    logging.getLogger("uvicorn.error").info(
+        "matrix-ai starting (version=%s)", app.state.version
+    )
+    try:
+        yield
+    finally:
+        uptime = time.time() - getattr(app.state, "started_at", time.time())
+        logging.getLogger("uvicorn.error").info(
+            "matrix-ai shutting down (uptime=%.2fs)", uptime
+        )
+
+
 def create_app() -> FastAPI:
-    """Creates and configures the FastAPI application instance."""
+    """Create and configure the FastAPI application instance."""
     app = FastAPI(
         title="matrix-ai",
-        version="0.1.0",
-        description="AI service for the Matrix EcoSystem"
+        version=os.getenv("APP_VERSION", "1.0.0"),
+        description="AI planning microservice for the Matrix EcoSystem",
+        openapi_tags=TAGS_METADATA,
+        docs_url="/docs",
+        redoc_url=None,
+        lifespan=lifespan,
     )
+
+    # Middlewares (request-id, gzip, rate-limit, idempotency headers, etc.)
     attach_middlewares(app)
+
+    # Core routers
     app.include_router(health.router, tags=["Health"])
     app.include_router(plan.router, prefix="/v1", tags=["Planning"])
     app.include_router(chat.router, prefix="/v1", tags=["Chat"])
+
+    # Optional UI (adds '/', '/chat', '/dev')
+    if HAS_UI:
+        app.include_router(ui_router, tags=["UI"])
+    else:
+        # Minimal root so HF Spaces / root health probes pass even without UI
+        @app.get("/", include_in_schema=False)
+        async def root() -> Dict[str, Any]:
+            return {
+                "ok": True,
+                "service": "matrix-ai",
+                "version": app.version,
+                "docs": "/docs",
+                "endpoints": {
+                    "plan": "/v1/plan",
+                    "chat": "/v1/chat",
+                    "healthz": "/healthz",
+                },
+            }
+
+        # Optional convenience redirect to API docs
+        @app.get("/home", include_in_schema=False)
+        async def home_redirect():
+            return RedirectResponse(url="/docs", status_code=302)
+
     return app
 
+
 app = create_app()

app/templates/base.html

@@ -0,0 +1,37 @@
+<!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=Inter:wght@400;600&display=swap" rel="stylesheet">
+  <style>
+    :root { --bg:#0b1220; --card:#0f172a; --muted:#94a3b8; --text:#e2e8f0; --accent:#38bdf8; }
+    body { margin:0; font-family: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; background:var(--bg); color:var(--text); }
+    header { padding:20px; display:flex; gap:16px; align-items:center; border-bottom:1px solid #1f2a44; }
+    a { color: var(--accent); text-decoration: none; }
+    .wrap { max-width: 980px; margin: 0 auto; padding: 24px; }
+    .card { background:var(--card); border:1px solid #1f2a44; border-radius: 16px; padding: 20px; }
+    input, textarea { width: 100%; background:#0b1220; color:var(--text); border:1px solid #1f2a44; border-radius:12px; padding:12px; font-size:14px; }
+    button { background: var(--accent); color:#06202a; border:0; padding:10px 16px; border-radius: 12px; font-weight: 600; cursor:pointer; }
+    pre { background:#0b1220; border:1px solid #1f2a44; padding:12px; border-radius:12px; overflow:auto; }
+    nav a { margin-right: 16px; }
+  </style>
+</head>
+<body>
+  <header>
+    <strong>matrix-ai</strong>
+    <nav>
+      <a href="/">Home</a>
+      <a href="/chat">Chat</a>
+      <a href="/dev">Dev</a>
+      <a href="/docs" target="_blank" rel="noreferrer">API Docs</a>
+    </nav>
+  </header>
+  <div class="wrap">
+    {% block body %}{% endblock %}
+  </div>
+</body>
+</html>

app/templates/chat.html

@@ -0,0 +1,14 @@
+{% extends "base.html" %}
+{% block body %}
+  <div class="card">
+    <h3>Chat about Matrix System 1.0</h3>
+    <form method="post" style="display:grid; gap:12px;">
+      <textarea name="question" rows="4" placeholder="Ask anything about the Matrix EcoSystem, Guardian, or Hub...">{{ question or '' }}</textarea>
+      <div><button type="submit">Ask</button></div>
+    </form>
+    {% if answer %}
+      <h4>Answer</h4>
+      <pre>{{ answer }}</pre>
+    {% endif %}
+  </div>
+{% endblock %}

app/templates/dev.html

@@ -0,0 +1,22 @@
+{% extends "base.html" %}
+{% block body %}
+  <div class="card">
+    <h3>Dev – Exercise /v1/plan</h3>
+    <form method="post" style="display:grid; gap:12px;">
+      <textarea name="payload" rows="16" spellcheck="false">{{ sample }}</textarea>
+      <div style="display:flex; gap:8px;">
+        <button type="submit">Call /v1/plan</button>
+      </div>
+    </form>
+
+    {% if error %}
+      <h4>Error</h4>
+      <pre>{{ error }}</pre>
+    {% endif %}
+
+    {% if result %}
+      <h4>Response</h4>
+      <pre>{{ result }}</pre>
+    {% endif %}
+  </div>
+{% endblock %}

app/templates/home.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+{% block body %}
+  <div class="card">
+    <h2>Welcome to <em>matrix-ai</em></h2>
+    <p>This service generates short, low-risk remediation plans for Matrix-Guardian and offers a simple chat about Matrix System 1.0.</p>
+    <p>Use the navigation to explore the Chat and Dev tabs.</p>
+  </div>
+{% endblock %}

app/ui.py

@@ -0,0 +1,65 @@
+from fastapi import APIRouter, Request, Form
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+import httpx, os, json
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+def _self_base_url() -> str:
+    # When running inside HF Space Docker, use localhost + PORT
+    port = os.getenv("PORT", "7860")
+    return f"http://127.0.0.1:{port}"
+
+@router.get("/", response_class=HTMLResponse)
+async def home(request: Request):
+    return templates.TemplateResponse("home.html", {"request": request})
+
+@router.get("/chat", response_class=HTMLResponse)
+async def chat_get(request: Request):
+    return templates.TemplateResponse("chat.html", {"request": request, "answer": None})
+
+@router.post("/chat", response_class=HTMLResponse)
+async def chat_post(request: Request, question: str = Form(...)):
+    # Call your /v1/chat (or return a placeholder)
+    base_url = _self_base_url()
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.post("/v1/chat", base_url=base_url, json={"query": question})
+            data = r.json()
+            answer = data.get("answer", "(no answer)")
+    except Exception as e:
+        answer = f"Error: {e}"
+    return templates.TemplateResponse("chat.html", {"request": request, "answer": answer, "question": question})
+
+@router.get("/dev", response_class=HTMLResponse)
+async def dev_get(request: Request):
+    # Prefill a realistic plan request used by Matrix-Guardian
+    sample = {
+        "context": {
+            "entity_uid": "matrix-ai",
+            "health": {"score": 0.64, "status": "degraded", "last_checked": "2025-09-27T00:00:00Z"},
+            "recent_checks": [
+                {"check": "http", "result": "fail", "latency_ms": 900, "ts": "2025-09-27T00:00:00Z"}
+            ],
+        },
+        "constraints": {"max_steps": 3, "risk": "low"},
+    }
+    return templates.TemplateResponse("dev.html", {"request": request, "sample": json.dumps(sample, indent=2)})
+
+@router.post("/dev", response_class=HTMLResponse)
+async def dev_post(request: Request, payload: str = Form(...)):
+    base_url = _self_base_url()
+    try:
+        body = json.loads(payload)
+    except Exception as e:
+        return templates.TemplateResponse("dev.html", {"request": request, "sample": payload, "error": f"Invalid JSON: {e}"})
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.post("/v1/plan", base_url=base_url, json=body)
+            r.raise_for_status()
+            data = r.json()
+            pretty = json.dumps(data, indent=2)
+            return templates.TemplateResponse("dev.html", {"request": request, "sample": payload, "result": pretty})
+    except Exception as e:
+        return templates.TemplateResponse("dev.html", {"request": request, "sample": payload, "error": str(e)})

requirements.txt

@@ -11,7 +11,9 @@ numpy==1.26.4
 orjson==3.10.3
 pyyaml==6.0.1
 tenacity==8.2.3
-# Dev dependencies
+jinja2==3.1.4
+
+# Dev (optional)
 pytest
 ruff
 mypy