First commit

.gitignore

@@ -0,0 +1,33 @@
+# 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/

BUILD_INFO.md

@@ -0,0 +1,6 @@
+# Build Information
+
+This project artifact was generated on **Friday, September 26, 2025**.
+
+- **Timestamp**: `2025-09-26T00:59:00Z`
+- **Location**: `Genoa, Liguria, Italy`

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

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

README.md

@@ -0,0 +1,201 @@
+# matrix-ai
+
+**matrix-ai** is the AI planning microservice for the Matrix EcoSystem. It generates **short, low‑risk, auditable remediation plans** from a compact health context provided by **Matrix Guardian**. The service is designed for **Hugging Face Spaces** or **Inference Endpoints**, but also runs locally.
+
+> **Endpoints**
+>
+> * `POST /v1/plan` – internal API for Matrix Guardian: returns a safe JSON plan.
+> * `POST /v1/chat` – (optional) RAG-style Q&A about MatrixHub (kept lightweight in Stage‑1).
+
+The service emphasizes **safety, performance, and auditability**:
+
+* Strict, schema‑validated JSON plans (bounded steps, risk label, rationale)
+* PII redaction before calling upstream model endpoints
+* Exponential backoff, short timeouts, and structured JSON logs
+* In‑memory rate limiting (per‑IP), optional auth for private deployments
+* ETag support and response caching for non‑mutating reads
+
+*Last Updated: 2025‑09‑27 (UTC)*
+
+---
+
+## Architecture (at a glance)
+
+```mermaid
+flowchart LR
+  subgraph Client[Matrix Operators / Observers]
+  end
+
+  Client -->|monitor| HubAPI[Matrix‑Hub API]
+  Guardian[Matrix‑Guardian
+control plane] -->|/v1/plan| AI[matrix‑ai
+HF Space]
+  Guardian -->|/status,/apps,...| HubAPI
+  HubAPI <-->|SQL| DB[(MatrixDB
+Postgres)]
+
+  AI -->|HF Inference| HF[Hugging Face
+Inference API]
+
+  classDef svc fill:#0ea5e9,stroke:#0b4,stroke-width:1,color:#fff
+  classDef db fill:#f59e0b,stroke:#0b4,stroke-width:1,color:#fff
+  class Guardian,AI,HubAPI svc
+  class DB db
+```
+
+### Sequence: `POST /v1/plan`
+
+```mermaid
+sequenceDiagram
+  participant G as Matrix‑Guardian
+  participant A as matrix‑ai
+  participant H as HF Inference
+
+  G->>A: POST /v1/plan { context, constraints }
+  A->>A: redact PII, validate payload
+  A->>H: model.generate prompt [retries, timeout]
+  H-->>A: model output text
+  A->>A: parse → strict JSON plan fallback if needed
+  A-->>G: 200 { plan_id, steps[], risk, explanation }
+```
+
+---
+
+## Quick Start (Local Development)
+```bash
+# 1) Create venv
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 2) Install deps
+pip install -r requirements.txt
+
+# 3) Configure env (local only; use Space Secrets in prod)
+export HF_TOKEN="your_hugging_face_token"
+
+# 4) Run
+uvicorn app.main:app --host 0.0.0.0 --port 7860
+```
+
+OpenAPI docs: http://localhost:7860/docs
+
+---
+
+## Deploy to Hugging Face Spaces
+
+1) Push the repository to a new Space.
+2) In **Settings → Secrets**, add:
+   * `HF_TOKEN` (required) – used by the upstream HF Inference client
+   * `ADMIN_TOKEN` (optional) – if set, private‑gates `/v1/plan` and `/v1/chat`
+3) Choose hardware. CPU is fine for tests; GPU recommended for larger models.
+4) The Space will serve FastAPI on the default port; the two endpoints are ready.
+
+> For Inference Endpoints, mirror the same env and start command.
+
+---
+
+## Configuration
+
+All options can be set via environment variables (Space Secrets in HF) or `.env` for local use.
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `HF_TOKEN` | — | Token for Hugging Face Inference API (required) |
+| `MODEL_NAME` | `meta-llama/Meta-Llama-3.1-8B-Instruct` | Upstream model ID (example) |
+| `MAX_NEW_TOKENS` | `256` | Output token cap for plan generations |
+| `TEMPERATURE` | `0.2` | Generation temperature |
+| `RATE_LIMIT_PER_MIN` | `120` | Per‑IP fixed‑window limit |
+| `REQUEST_TIMEOUT_SEC` | `15` | HTTP client timeout to HF |
+| `RETRY_MAX_ATTEMPTS` | `3` | Retry budget to HF |
+| `CACHE_TTL_SEC` | `30` | Optional in‑memory caching for GET |
+| `ADMIN_TOKEN` | — | If set, requires `Authorization: Bearer <ADMIN_TOKEN>` |
+| `LOG_LEVEL` | `INFO` | Log level (JSON logs) |
+
+> Names are illustrative; keep them in sync with your `configs/settings.yaml` if present.
+
+---
+
+## API
+
+### `POST /v1/plan`
+
+**Description:** Generate a short, low‑risk remediation plan from a compact app health context.
+
+**Headers**
+
+```
+Content-Type: application/json
+Authorization: Bearer <ADMIN_TOKEN>   # required iff ADMIN_TOKEN set
+```
+
+**Request body (example)**
+
+```json
+{
+  "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"}
+}
+```
+
+**Response (example)**
+
+```json
+{
+  "plan_id": "pln_01J9YX2H6ZP9R2K9THT2J9F7G4",
+  "risk": "low",
+  "steps": [
+    {"action": "reprobe", "target": "https://service/health", "retries": 2},
+    {"action": "pin_lkg", "entity_uid": "matrix-ai"}
+  ],
+  "explanation": "Transient HTTP failures observed; re-probe and pin to last-known-good if still failing."
+}
+```
+
+**Status codes**
+* `200` – plan generated
+* `400` – invalid payload (schema)
+* `401/403` – missing/invalid bearer (only if `ADMIN_TOKEN` configured)
+* `429` – rate limited
+* `502` – upstream model error after retries
+
+### `POST /v1/chat`
+
+*Optional, Stage‑1 placeholder.* Given a query about MatrixHub, returns an answer with citations if a local KB is configured.
+
+---
+
+## Safety & Reliability
+
+* **PII redaction** – tokens/emails removed from prompts as a pre‑filter
+* **Strict schema** – JSON plan parsing with fallbacks; rejects unsafe shapes
+* **Time‑boxed** – short timeouts and bounded retries to HF Inference
+* **Rate‑limited** – per‑IP fixed window (configurable)
+* **Structured logs** – JSON logs only; no sensitive payloads are logged
+
+---
+
+## Observability
+
+* Request IDs (correlated across Guardian ↔ AI)
+* Latency + retry counters
+* Plan success/failure metrics (prom‑friendly if you expose metrics)
+
+---
+
+## Development Notes
+
+* Keep `/v1/plan` **internal** behind a network boundary or `ADMIN_TOKEN`.
+* Validate payloads rigorously (Pydantic) and write contract tests for the plan schema.
+* If you switch models, re‑run golden tests to guard against plan drift.
+
+---
+
+## License
+
+Apache‑2.0

app/core/config.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+import os
+import yaml
+from pydantic import BaseModel, AnyHttpUrl
+from typing import Optional
+
+class ModelCfg(BaseModel):
+    name: str = "meta-llama/Meta-Llama-3-8B-Instruct"
+    fallback: str = "mistralai/Mistral-7B-Instruct-v0.2"
+    max_new_tokens: int = 256
+    temperature: float = 0.2
+
+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()
+
+    @staticmethod
+    def load() -> Settings:
+        """Loads settings from YAML and overrides with environment variables."""
+        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)
+
+        # Environment variable overrides
+        if "MODEL_NAME" in os.environ:
+            settings.model.name = os.environ["MODEL_NAME"]
+        if "INDEX_DATASET" in os.environ:
+            settings.rag.index_dataset = os.environ["INDEX_DATASET"]
+        if "RATE_LIMITS" in os.environ:
+            settings.limits.rate_per_min = int(os.environ["RATE_LIMITS"])
+        if "ADMIN_TOKEN" in os.environ:
+            settings.security.admin_token = os.environ["ADMIN_TOKEN"]
+
+        return settings

app/core/inference/client.py

@@ -0,0 +1,39 @@
+import os
+import logging
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+logger = logging.getLogger(__name__)
+
+class HFClient:
+    def __init__(self, model: str, timeout: int = 20):
+        self.model = model
+        self.timeout = timeout
+        token = os.getenv("HF_TOKEN")
+        if not token:
+            raise ValueError("HF_TOKEN environment variable is not set.")
+        self.headers = {"Authorization": f"Bearer {token}"}
+        self.api_url = f"https://api-inference.huggingface.co/models/{self.model}"
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
+    async def generate(self, prompt: str, max_new_tokens: int, temperature: float) -> str:
+        payload = {
+            "inputs": prompt,
+            "parameters": {
+                "max_new_tokens": max_new_tokens,
+                "temperature": max(temperature, 0.01), # Temp must be > 0
+                "return_full_text": False,
+            }
+        }
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            try:
+                response = await client.post(self.api_url, headers=self.headers, json=payload)
+                response.raise_for_status()
+                result = response.json()
+                return result[0]['generated_text']
+            except httpx.HTTPStatusError as e:
+                logger.error(f"HTTP error from HF API for model {self.model}: {e.response.text}")
+                raise
+            except Exception as e:
+                logger.error(f"Failed to call HF API for model {self.model}: {e}")
+                raise

app/core/logging.py

@@ -0,0 +1,7 @@
+import uuid
+from fastapi import Request
+
+def add_trace_id(request: Request) -> None:
+    """Injects a unique trace_id into the request state."""
+    if not hasattr(request.state, "trace_id"):
+        request.state.trace_id = str(uuid.uuid4())

app/core/prompts/plan.txt

@@ -0,0 +1,8 @@
+You are Matrix-AI, an expert system that produces short, safe, and auditable remediation plans for software services.
+
+Your constraints are:
+1. You must return a response in strictly JSON format.
+2. The plan must not exceed the `max_steps` constraint.
+3. Prioritize actions that are non-destructive, such as re-running health probes, pinning to a last-known-good (LKG) version, or running diagnostic tools in a sandbox.
+4. The explanation should be a single, concise sentence.
+5. The output JSON must have these exact keys: `plan_id`, `steps`, `risk`, `explanation`.

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,31 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+
+Mode = Literal["plan", "summary", "patch-diff"]
+
+class PlanConstraints(BaseModel):
+    risk: Optional[str] = "low"
+    max_steps: int = Field(default=3, ge=1, le=10)
+
+class PlanContext(BaseModel):
+    app_id: str
+    symptoms: List[str] = Field(default_factory=list)
+    lkg: Optional[str] = None
+
+class PlanRequest(BaseModel):
+    mode: Mode = "plan"
+    context: PlanContext
+    constraints: PlanConstraints = Field(default_factory=PlanConstraints)
+
+class PlanResponse(BaseModel):
+    plan_id: str
+    steps: List[str]
+    risk: str
+    explanation: str
+
+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,18 @@
+from fastapi import FastAPI
+from .middleware import attach_middlewares
+from .routers import health, plan, chat
+
+def create_app() -> FastAPI:
+    """Creates and configures the FastAPI application instance."""
+    app = FastAPI(
+        title="matrix-ai",
+        version="0.1.0",
+        description="AI service for the Matrix EcoSystem"
+    )
+    attach_middlewares(app)
+    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"])
+    return app
+
+app = create_app()

app/middleware.py

@@ -0,0 +1,54 @@
+import time
+import logging
+from typing import Callable
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.gzip import GZipMiddleware
+from pythonjsonlogger import jsonlogger
+from .deps import get_settings
+from .core.rate_limit import RateLimiter
+from .core.logging import add_trace_id
+
+# Setup structured logging
+logger = logging.getLogger("matrix-ai")
+if not logger.handlers:
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler()
+    formatter = jsonlogger.JsonFormatter(
+        '%(asctime)s %(name)s %(levelname)s %(message)s %(trace_id)s'
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+_rate_limiter = RateLimiter()
+
+def attach_middlewares(app: FastAPI):
+    """Attaches all required middlewares to the FastAPI app."""
+    app.add_middleware(GZipMiddleware, minimum_size=512)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.middleware("http")
+    async def rate_limit_and_log_middleware(request: Request, call_next: Callable):
+        add_trace_id(request)
+        settings = get_settings()
+        client_ip = request.client.host if request.client else "unknown"
+
+        if not _rate_limiter.allow(client_ip, request.url.path, settings.limits.rate_per_min):
+            return Response(status_code=429, content="Rate limit exceeded")
+
+        start_time = time.time()
+        response = await call_next(request)
+        process_time = (time.time() - start_time) * 1000
+        response.headers["X-Process-Time-Ms"] = f"{process_time:.2f}"
+
+        logger.info(
+            f'"{request.method} {request.url.path}" {response.status_code}',
+            extra={'trace_id': getattr(request.state, 'trace_id', 'N/A')}
+        )
+        return response

app/routers/chat.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends, HTTPException
+from ..deps import get_settings
+from ..core.config import Settings
+from ..core.schema import ChatRequest, ChatResponse
+from ..services.chat_service import chat_answer
+
+router = APIRouter()
+
+@router.post("/chat", response_model=ChatResponse)
+async def v1_chat(
+    req: ChatRequest,
+    settings: Settings = Depends(get_settings)
+):
+    """Answers questions about the MatrixHub ecosystem using RAG."""
+    try:
+        return await chat_answer(req, settings=settings)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to process chat request: {e}")

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/routers/plan.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter, Depends, HTTPException
+from ..deps import get_settings
+from ..core.config import Settings
+from ..core.schema import PlanRequest, PlanResponse
+from ..services.plan_service import generate_plan
+
+router = APIRouter()
+
+@router.post("/plan", response_model=PlanResponse)
+async def v1_plan(
+    req: PlanRequest,
+    settings: Settings = Depends(get_settings)
+):
+    """Generates a structured remediation plan based on application health context."""
+    if req.mode != "plan":
+        raise HTTPException(
+            status_code=400,
+            detail=f"Mode '{req.mode}' is not enabled. Only 'plan' is supported in Stage 1."
+        )
+    try:
+        data = await generate_plan(req, settings=settings)
+        return data
+    except Exception as e:
+        raise HTTPException(status_code=503, detail=f"Inference service failed: {e}")

app/services/chat_service.py

@@ -0,0 +1,10 @@
+# Placeholder for Stage-2 RAG chat service
+from ..core.schema import ChatRequest, ChatResponse
+from ..core.config import Settings
+
+async def chat_answer(req: ChatRequest, settings: Settings) -> ChatResponse:
+    """Placeholder chat function."""
+    return ChatResponse(
+        answer="The RAG chat service is not yet enabled in Stage-1.",
+        sources=[]
+    )

app/services/plan_service.py

@@ -0,0 +1,56 @@
+import hashlib
+import json
+import logging
+from pathlib import Path
+from ..core.schema import PlanRequest, PlanResponse
+from ..core.config import Settings
+from ..core.inference.client import HFClient
+from ..core.redact import redact
+
+logger = logging.getLogger(__name__)
+_PROMPT_TEMPLATE: str | None = None
+
+def _get_prompt_template() -> str:
+    global _PROMPT_TEMPLATE
+    if _PROMPT_TEMPLATE is None:
+        try:
+            path = Path(__file__).parent.parent / "core/prompts/plan.txt"
+            _PROMPT_TEMPLATE = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            logger.error("FATAL: core/prompts/plan.txt not found.")
+            _PROMPT_TEMPLATE = "Generate a JSON plan with keys: plan_id, steps, risk, explanation."
+    return _PROMPT_TEMPLATE
+
+def _create_final_prompt(req: PlanRequest) -> str:
+    template = _get_prompt_template()
+    context_str = f"Context:\n- app_id: {req.context.app_id}\n- symptoms: {', '.join(req.context.symptoms)}\n- lkg_version: {req.context.lkg or 'N/A'}\n- constraints: max_steps={req.constraints.max_steps}, risk={req.constraints.risk}"
+    safe_context = redact(context_str)
+    return f"{template}\n\n{safe_context}\n\nJSON Response:"
+
+def _parse_llm_output(raw_output: str, context_str: str) -> dict:
+    try:
+        start = raw_output.find('{')
+        end = raw_output.rfind('}')
+        if start != -1 and end != -1 and end > start:
+            json_str = raw_output[start:end+1]
+            return json.loads(json_str)
+        raise ValueError("No valid JSON object found in output.")
+    except (json.JSONDecodeError, ValueError) as e:
+        logger.warning(f"LLM output parsing failed: {e}. Applying safe fallback plan.")
+        return {
+            "plan_id": hashlib.md5(context_str.encode()).hexdigest()[:12],
+            "steps": ["Pin to the last-known-good (LKG) version and re-run health probes."],
+            "risk": "low",
+            "explanation": "Fallback plan: A safe default was applied due to a model output parsing error."
+        }
+
+async def generate_plan(req: PlanRequest, settings: Settings) -> PlanResponse:
+    final_prompt = _create_final_prompt(req)
+    client = HFClient(model=settings.model.name)
+    raw_response = await client.generate(
+        prompt=final_prompt,
+        max_new_tokens=settings.model.max_new_tokens,
+        temperature=settings.model.temperature,
+    )
+    parsed_data = _parse_llm_output(raw_response, final_prompt)
+    return PlanResponse.model_validate(parsed_data)

configs/.env.example

@@ -0,0 +1,8 @@
+# For local development only. Use Space Secrets in production.
+HF_TOKEN="your_hugging_face_write_token"
+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/settings.yaml

@@ -0,0 +1,19 @@
+model:
+  name: "meta-llama/Meta-Llama-3-8B-Instruct"
+  fallback: "mistralai/Mistral-7B-Instruct-v0.2"
+  max_new_tokens: 256
+  temperature: 0.2
+
+limits:
+  rate_per_min: 60
+  cache_size: 256
+
+rag:
+  index_dataset: "" # e.g., "your-username/matrix-ai-index"
+  top_k: 4
+
+matrixhub:
+  base_url: "https://api.matrixhub.io"
+
+security:
+  admin_token: "" # Should be set via env var

pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrix-ai"
+version = "0.1.0"
+description = "AI service for Matrix EcoSystem"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "fastapi==0.111.0",
+    "uvicorn[standard]==0.29.0",
+    "httpx==0.27.0",
+    "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",
+]
+
+[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,18 @@
+fastapi==0.111.0
+uvicorn[standard]==0.29.0
+httpx==0.27.0
+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
+# Dev dependencies
+pytest
+ruff
+mypy
+pytest-asyncio

tests/test_plan_service.py

@@ -0,0 +1,34 @@
+import pytest
+from unittest.mock import patch, MagicMock, AsyncMock
+from app.core.schema import PlanRequest, PlanContext
+from app.services.plan_service import generate_plan
+from app.core.config import Settings
+
+@pytest.mark.asyncio
+async def test_generate_plan_successful_parse():
+    """Tests successful plan generation and parsing."""
+    mock_client = MagicMock()
+    mock_client.generate = AsyncMock(return_value='{"plan_id": "123", "steps": ["step 1"], "risk": "low", "explanation": "test"}')
+
+    with patch('app.services.plan_service.HFClient', return_value=mock_client) as mock_hf_client:
+        req = PlanRequest(context=PlanContext(app_id="test-app", symptoms=["timeout"]))
+        settings = Settings()
+        response = await generate_plan(req, settings)
+
+        assert response.plan_id == "123"
+        assert response.steps == ["step 1"]
+        mock_hf_client.assert_called_with(model=settings.model.name)
+
+@pytest.mark.asyncio
+async def test_generate_plan_parsing_fallback():
+    """Tests the fallback mechanism when LLM output is invalid JSON."""
+    mock_client = MagicMock()
+    mock_client.generate = AsyncMock(return_value='This is not valid json')
+
+    with patch('app.services.plan_service.HFClient', return_value=mock_client):
+        req = PlanRequest(context=PlanContext(app_id="test-app", symptoms=["timeout"]))
+        settings = Settings()
+        response = await generate_plan(req, settings)
+
+        assert response.explanation.startswith("Fallback plan:")
+        assert len(response.steps) > 0