svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/mcp/svc_infra_mcp.py

@@ -1,58 +1,113 @@
 from __future__ import annotations
 
 from enum import Enum
+from typing import Any, cast
 
 from ai_infra.llm.tools.custom.cli import cli_cmd_help, cli_subcmd_help
 from ai_infra.mcp.server.tools import mcp_from_functions
 
+from svc_infra.app.env import prepare_env
+from svc_infra.cli.foundation.runner import run_from_root
+
 CLI_PROG = "svc-infra"
 
 
-async def svc_infra_cmd_help() -> dict:
+async def svc_infra_cmd_help() -> dict[Any, Any]:
     """
     Get help text for svc-infra CLI.
     - Prepares project env without chdir (so we can 'cd' in the command itself).
     - Tries poetry → console script → python -m svc_infra.cli_shim.
     """
-    return await cli_cmd_help(CLI_PROG)
+    return cast("dict[Any, Any]", await cli_cmd_help(CLI_PROG))
+
+
+# No dedicated 'docs list' function — users can use 'docs --help' to discover topics.
+
+
+async def svc_infra_docs_help() -> dict:
+    """
+    Run 'svc-infra docs --help' and return its output.
+    Prepares the project environment and executes from the repo root so
+    environment-provided docs directories and local topics are discoverable.
+    """
+    root = prepare_env()
+    text = await run_from_root(root, CLI_PROG, ["docs", "--help"])
+    return {
+        "ok": True,
+        "action": "docs_help",
+        "project_root": str(root),
+        "help": text,
+    }
 
 
 class Subcommand(str, Enum):
-    # SQL commands
-    sql_init = "sql-init"
-    sql_revision = "sql-revision"
-    sql_upgrade = "sql-upgrade"
-    sql_downgrade = "sql-downgrade"
-    sql_current = "sql-current"
-    sql_history = "sql-history"
-    sql_stamp = "sql-stamp"
-    sql_merge_heads = "sql-merge-heads"
-    sql_setup_and_migrate = "sql-setup-and-migrate"
-    sql_scaffold = "sql-scaffold"
-    sql_scaffold_models = "sql-scaffold-models"
-    sql_scaffold_schemas = "sql-scaffold-schemas"
-
-    # Mongo commands
-    mongo_prepare = "mongo-prepare"
-    mongo_setup_and_prepare = "mongo-setup-and-prepare"
-    mongo_ping = "mongo-ping"
-    mongo_scaffold = "mongo-scaffold"
-    mongo_scaffold_documents = "mongo-scaffold-documents"
-    mongo_scaffold_schemas = "mongo-scaffold-schemas"
-    mongo_scaffold_resources = "mongo-scaffold-resources"
-
-    # Observability commands
-    obs_up = "obs-up"
-    obs_down = "obs-down"
-    obs_scaffold = "obs-scaffold"
-
-
-async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict:
+    # SQL group commands
+    sql_init = "sql init"
+    sql_revision = "sql revision"
+    sql_upgrade = "sql upgrade"
+    sql_downgrade = "sql downgrade"
+    sql_current = "sql current"
+    sql_history = "sql history"
+    sql_stamp = "sql stamp"
+    sql_merge_heads = "sql merge-heads"
+    sql_setup_and_migrate = "sql setup-and-migrate"
+    sql_scaffold = "sql scaffold"
+    sql_scaffold_models = "sql scaffold-models"
+    sql_scaffold_schemas = "sql scaffold-schemas"
+    sql_export_tenant = "sql export-tenant"
+    sql_seed = "sql seed"
+
+    # Mongo group commands
+    mongo_prepare = "mongo prepare"
+    mongo_setup_and_prepare = "mongo setup-and-prepare"
+    mongo_ping = "mongo ping"
+    mongo_scaffold = "mongo scaffold"
+    mongo_scaffold_documents = "mongo scaffold-documents"
+    mongo_scaffold_schemas = "mongo scaffold-schemas"
+    mongo_scaffold_resources = "mongo scaffold-resources"
+
+    # Observability group commands
+    obs_up = "obs up"
+    obs_down = "obs down"
+    obs_scaffold = "obs scaffold"
+
+    # Docs group
+    docs_help = "docs --help"
+    docs_show = "docs show"
+
+    # DX group
+    dx_openapi = "dx openapi"
+    dx_migrations = "dx migrations"
+    dx_changelog = "dx changelog"
+    dx_ci = "dx ci"
+
+    # Jobs group
+    jobs_run = "jobs run"
+
+    # SDK group
+    sdk_ts = "sdk ts"
+    sdk_py = "sdk py"
+    sdk_postman = "sdk postman"
+
+
+async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict[Any, Any]:
     """
     Get help text for a specific subcommand of svc-infra CLI.
     (Enum keeps a tight schema; function signature remains simple.)
     """
-    return await cli_subcmd_help(CLI_PROG, subcommand)
+    tokens = subcommand.value.split()
+    if len(tokens) == 1:
+        return cast("dict[Any, Any]", await cli_subcmd_help(CLI_PROG, subcommand))
+
+    root = prepare_env()
+    text = await run_from_root(root, CLI_PROG, [*tokens, "--help"])
+    return {
+        "ok": True,
+        "action": "subcommand_help",
+        "subcommand": subcommand.value,
+        "project_root": str(root),
+        "help": text,
+    }
 
 
 mcp = mcp_from_functions(
@@ -60,8 +115,11 @@ mcp = mcp_from_functions(
     functions=[
         svc_infra_cmd_help,
         svc_infra_subcmd_help,
+        svc_infra_docs_help,
+        # Docs listing is available via 'docs --help'; no separate MCP function needed.
     ],
 )
 
+
 if __name__ == "__main__":
     mcp.run(transport="stdio")

svc_infra/obs/README.md

@@ -8,6 +8,8 @@ This guide shows you how to turn on metrics + dashboards in three easy modes:
 
 It's "one button": run `svc-infra obs-up` and you're good. The CLI will read your `.env` automatically and do the right thing.
 
+> ℹ️ A complete list of observability-related environment variables lives in [Environment Reference](../../../docs/environment.md).
+
 ---
 
 ## 0) Install & instrument your app (once)

svc_infra/obs/add.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Iterable, Optional
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol
 
 from svc_infra.obs.settings import ObservabilitySettings
 
@@ -9,12 +10,20 @@ def _want_metrics(cfg: ObservabilitySettings) -> bool:
     return bool(cfg.METRICS_ENABLED)
 
 
+class RouteClassifier(Protocol):
+    def __call__(
+        self, route_path: str, method: str
+    ) -> str:  # e.g., returns "public|internal|admin"
+        ...
+
+
 def add_observability(
     app: Any | None = None,
     *,
-    db_engines: Optional[Iterable[Any]] = None,
+    db_engines: Iterable[Any] | None = None,
     metrics_path: str | None = None,
-    skip_metric_paths: Optional[Iterable[str]] = None,
+    skip_metric_paths: Iterable[str] | None = None,
+    route_classifier: RouteClassifier | None = None,
 ) -> Callable[[], None]:
     """
     Enable Prometheus metrics for the ASGI app and optional SQLAlchemy pool metrics.
@@ -25,21 +34,66 @@ def add_observability(
     # --- Metrics (Prometheus) — import lazily so CLIs/tests don’t require prometheus_client
     if app is not None and _want_metrics(cfg):
         try:
-            from svc_infra.obs.metrics.asgi import add_prometheus  # lazy
+            from svc_infra.obs.metrics.asgi import (  # lazy
+                PrometheusMiddleware,
+                add_prometheus,
+                metrics_endpoint,
+            )
 
             path = metrics_path or cfg.METRICS_PATH
-            add_prometheus(
-                app,
-                path=path,
-                skip_paths=tuple(skip_metric_paths or (path, "/health", "/healthz")),
-            )
+            skip_paths = tuple(skip_metric_paths or (path, "/health", "/healthz"))
+            # If a route_classifier is provided, use a custom route_resolver to append class label
+            if route_classifier is None:
+                add_prometheus(
+                    app,
+                    path=path,
+                    skip_paths=skip_paths,
+                )
+            else:
+                # Install middleware manually to pass route_resolver
+                def _resolver(req):
+                    # Base template
+                    from svc_infra.obs.metrics.asgi import _route_template
+
+                    base = _route_template(req)
+                    method = getattr(req, "method", "GET")
+                    cls = route_classifier(base, method)
+                    # Encode as base|class for downstream label splitting in dashboards
+                    return f"{base}|{cls}"
+
+                app.add_middleware(
+                    PrometheusMiddleware,
+                    skip_paths=skip_paths,
+                    route_resolver=_resolver,
+                )
+                # Mount /metrics endpoint without re-adding middleware
+                try:
+                    from svc_infra.api.fastapi.dual.public import public_router
+                    from svc_infra.app.env import (
+                        CURRENT_ENVIRONMENT,
+                        DEV_ENV,
+                        LOCAL_ENV,
+                    )
+
+                    router = public_router()
+                    router.add_api_route(
+                        path,
+                        endpoint=metrics_endpoint(),
+                        include_in_schema=CURRENT_ENVIRONMENT in (LOCAL_ENV, DEV_ENV),
+                        tags=["observability"],
+                    )
+                    app.include_router(router)
+                except Exception:
+                    app.add_route(path, metrics_endpoint())
         except Exception:
             pass
 
     # --- DB pool metrics (best effort) — also lazy
     if db_engines:
         try:
-            from svc_infra.obs.metrics.sqlalchemy import bind_sqlalchemy_pool_metrics  # lazy
+            from svc_infra.obs.metrics.sqlalchemy import (
+                bind_sqlalchemy_pool_metrics,
+            )  # lazy
 
             for eng in db_engines:
                 try:
@@ -51,7 +105,10 @@ def add_observability(
 
     # --- HTTP client metrics (best effort) — import lazily
     try:
-        from svc_infra.obs.metrics.http import instrument_httpx, instrument_requests  # lazy
+        from svc_infra.obs.metrics.http import (
+            instrument_httpx,
+            instrument_requests,
+        )  # lazy
 
         try:
             instrument_requests()

svc_infra/obs/cloud_dash.py

@@ -5,6 +5,7 @@ import os
 import re
 import urllib.request
 from importlib.resources import files
+from typing import Any, cast
 
 # ---------------- helpers ----------------
 
@@ -86,7 +87,7 @@ def _rewrite_rate_windows(d: dict) -> dict:
     if not win:
         return d
 
-    dd = json.loads(json.dumps(d))
+    dd = cast("dict[Any, Any]", json.loads(json.dumps(d)))
     for p in dd.get("panels", []) or []:
         targets = p.get("targets") or []
         for t in targets:

svc_infra/obs/grafana/dashboards/http-overview.json

@@ -0,0 +1,45 @@
+{
+  "title": "Service HTTP Overview",
+  "tags": ["svc-infra", "http"],
+  "timezone": "browser",
+  "panels": [
+    {
+      "type": "timeseries",
+      "title": "Success Rate (5m)",
+      "targets": [
+        {
+          "expr": "sum(rate(http_server_requests_total{code!~\"5..\"}[5m])) / sum(rate(http_server_requests_total[5m]))",
+          "legendFormat": "success_rate"
+        }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Latency p99",
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(http_server_request_duration_seconds_bucket[5m])) by (le))",
+          "legendFormat": "p99"
+        }
+      ]
+    },
+    {
+      "type": "table",
+      "title": "Top Routes by Error (5m)",
+      "targets": [
+        {
+          "expr": "topk(10, sum(rate(http_server_requests_total{code=~\"5..\"}[5m])) by (route))",
+          "legendFormat": "{{route}}"
+        }
+      ]
+    }
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "refresh": "30s"
+}

svc_infra/obs/metrics/__init__.py

@@ -1,13 +1,12 @@
-from __future__ import annotations
-
-"""
-Metrics package public API.
+"""Metrics package public API.
 
 Provides lightweight, overridable hooks for abuse heuristics so callers can
 plug in logging or a metrics backend without a hard dependency.
 """
 
-from typing import Callable, Optional
+from __future__ import annotations
+
+from collections.abc import Callable
 
 # Function variables so applications/tests can replace them at runtime.
 on_rate_limit_exceeded: Callable[[str, int, int], None] | None = None
@@ -19,7 +18,7 @@ Args:
     retry_after: seconds until next allowed attempt
 """
 
-on_suspect_payload: Callable[[Optional[str], int], None] | None = None
+on_suspect_payload: Callable[[str | None, int], None] | None = None
 """
 Called when a request exceeds the configured size limit.
 Args:
@@ -37,7 +36,7 @@ def emit_rate_limited(key: str, limit: int, retry_after: int) -> None:
             pass
 
 
-def emit_suspect_payload(path: Optional[str], size: int) -> None:
+def emit_suspect_payload(path: str | None, size: int) -> None:
     if on_suspect_payload:
         try:
             on_suspect_payload(path, size)

svc_infra/obs/metrics/asgi.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import os
 import time
-from typing import Any, Callable, Iterable, Optional
+from collections.abc import Callable, Iterable
+from typing import Any, cast
 
 from starlette.requests import Request
 from starlette.responses import PlainTextResponse, Response
@@ -34,7 +35,7 @@ def _register_default_collectors_once() -> None:
     try:
         # These imports are no-ops if already registered by the client,
         # but GCCollector typically needs explicit instantiation.
-        from prometheus_client import GCCollector  # type: ignore
+        from prometheus_client import GCCollector
 
         GCCollector()  # registers GC metrics
         _default_collectors_ready = True
@@ -97,9 +98,9 @@ def _init_metrics() -> None:
 def _route_template(req: Request) -> str:
     route = getattr(req, "scope", {}).get("route")
     if route and hasattr(route, "path_format"):
-        return route.path_format
+        return cast("str", route.path_format)
     if route and hasattr(route, "path"):
-        return route.path
+        return cast("str", route.path)
     return req.url.path or "/*unmatched*"
 
 
@@ -115,8 +116,8 @@ class PrometheusMiddleware:
         self,
         app: ASGIApp,
         *,
-        skip_paths: Optional[Iterable[str]] = None,
-        route_resolver: Optional[Callable[[Request], str]] = None,
+        skip_paths: Iterable[str] | None = None,
+        route_resolver: Callable[[Request], str] | None = None,
     ):
         self.app = app
         self.skip_paths = tuple(skip_paths or ("/metrics",))
@@ -237,7 +238,7 @@ def metrics_endpoint():
         return handler
 
 
-def add_prometheus(app, *, path: str = "/metrics", skip_paths: Optional[Iterable[str]] = None):
+def add_prometheus(app, *, path: str = "/metrics", skip_paths: Iterable[str] | None = None):
     """Convenience for FastAPI/Starlette apps."""
     # Add middleware
     app.add_middleware(

svc_infra/obs/metrics/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import importlib
-from typing import Iterable, Optional
+from collections.abc import Iterable
 
 
 class _MissingPrometheus(Exception):
@@ -31,8 +31,8 @@ def registry():
     import os
 
     prom = _prom_mod()
-    REGISTRY = getattr(prom, "REGISTRY")
-    CollectorRegistry = getattr(prom, "CollectorRegistry")
+    REGISTRY = prom.REGISTRY
+    CollectorRegistry = prom.CollectorRegistry
     multiprocess = getattr(prom, "multiprocess", None)
 
     if os.environ.get("PROMETHEUS_MULTIPROC_DIR") and multiprocess is not None:
@@ -46,14 +46,14 @@ def _mk_metric(
     ctor_name: str,
     name: str,
     doc: str,
-    labels: Optional[Iterable[str]] = None,
+    labels: Iterable[str] | None = None,
     **kwargs,
 ):
     prom = _prom_mod()
-    Counter = getattr(prom, "Counter")
-    Gauge = getattr(prom, "Gauge")
-    Histogram = getattr(prom, "Histogram")
-    Summary = getattr(prom, "Summary")
+    Counter = prom.Counter
+    Gauge = prom.Gauge
+    Histogram = prom.Histogram
+    Summary = prom.Summary
 
     ctors = {
         "Counter": Counter,
@@ -67,11 +67,11 @@ def _mk_metric(
     return metric
 
 
-def counter(name: str, doc: str, labels: Optional[Iterable[str]] = None):
+def counter(name: str, doc: str, labels: Iterable[str] | None = None):
     return _mk_metric("Counter", name, doc, labels)
 
 
-def gauge(name: str, doc: str, labels: Optional[Iterable[str]] = None, **kw):
+def gauge(name: str, doc: str, labels: Iterable[str] | None = None, **kw):
     # e.g. gauge(..., multiprocess_mode="livesum")
     return _mk_metric("Gauge", name, doc, labels, **kw)
 
@@ -79,8 +79,8 @@ def gauge(name: str, doc: str, labels: Optional[Iterable[str]] = None, **kw):
 def histogram(
     name: str,
     doc: str,
-    labels: Optional[Iterable[str]] = None,
-    buckets: Optional[Iterable[float]] = None,
+    labels: Iterable[str] | None = None,
+    buckets: Iterable[float] | None = None,
 ):
     kwargs = {"buckets": list(buckets) if buckets else None}
     # Remove None so prometheus-client uses its defaults
@@ -88,5 +88,5 @@ def histogram(
     return _mk_metric("Histogram", name, doc, labels, **kwargs)
 
 
-def summary(name: str, doc: str, labels: Optional[Iterable[str]] = None):
+def summary(name: str, doc: str, labels: Iterable[str] | None = None):
     return _mk_metric("Summary", name, doc, labels)

svc_infra/obs/metrics/http.py

@@ -51,7 +51,7 @@ def instrument_requests():
             _http_client_total.labels(host, method_u, code).inc()
             _http_client_duration.labels(host, method_u).observe(elapsed)
 
-    requests.sessions.Session.request = _wrapped  # type: ignore[attr-defined]
+    requests.sessions.Session.request = _wrapped  # type: ignore[method-assign]
 
 
 def instrument_httpx():
@@ -93,5 +93,5 @@ def instrument_httpx():
             _http_client_total.labels(host, method, code).inc()
             _http_client_duration.labels(host, method).observe(time.perf_counter() - start)
 
-    httpx.Client.send = _wrap_sync_send(_orig_sync)  # type: ignore[assignment]
-    httpx.AsyncClient.send = _wrapped_async  # type: ignore[assignment]
+    httpx.Client.send = _wrap_sync_send(_orig_sync)  # type: ignore[method-assign]
+    httpx.AsyncClient.send = _wrapped_async  # type: ignore[method-assign]

svc_infra/obs/metrics/sqlalchemy.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from sqlalchemy.engine import Engine
 
 try:
     from sqlalchemy.ext.asyncio import AsyncEngine
 except Exception:  # optional
-    AsyncEngine = None  # type: ignore
+    AsyncEngine = None  # type: ignore[misc,assignment]
 
 from .base import counter, gauge
 
@@ -27,12 +28,12 @@ _pool_checked_out_total = counter("db_pool_checkedout_total", "Total checkouts",
 _pool_checked_in_total = counter("db_pool_checkedin_total", "Total checkins", labels=["db"])
 
 
-def _label(labels: Optional[Mapping[str, str]]) -> str:
+def _label(labels: Mapping[str, str] | None) -> str:
     return (labels or {}).get("db", "default")
 
 
 def bind_sqlalchemy_pool_metrics(
-    engine: Engine | Any, labels: Optional[Mapping[str, str]] = None
+    engine: Engine | Any, labels: Mapping[str, str] | None = None
 ) -> None:
     """Bind event listeners for pool metrics. Works for sync Engine.
     For AsyncEngine pass engine.sync_engine."""
@@ -42,31 +43,31 @@ def bind_sqlalchemy_pool_metrics(
     from sqlalchemy import event
 
     @event.listens_for(sync_engine, "engine_connect")
-    def _(conn, branch):  # noqa
+    def _(conn, branch):
         # Update gauges on engine_connect as a cheap heartbeat
         pool = sync_engine.pool
         try:
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass
 
     @event.listens_for(sync_engine, "checkout")
-    def _checkout(dbapi_con, con_record, con_proxy):  # noqa
+    def _checkout(dbapi_con, con_record, con_proxy):
         _pool_checked_out_total.labels(label).inc()
         try:
             pool = sync_engine.pool
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass
 
     @event.listens_for(sync_engine, "checkin")
-    def _checkin(dbapi_con, con_record):  # noqa
+    def _checkin(dbapi_con, con_record):
         _pool_checked_in_total.labels(label).inc()
         try:
             pool = sync_engine.pool
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass

svc_infra/obs/metrics.py

@@ -1,12 +1,13 @@
-from __future__ import annotations
+"""Lightweight metrics hooks for abuse heuristics.
 
+Intentionally minimal to avoid pulling full metrics stacks; these are no-ops by
+default but can be swapped in tests or wired to a metrics backend by overriding the
+functions.
 """
-Lightweight metrics hooks for abuse heuristics. Intentionally minimal to avoid pulling
-full metrics stacks; these are no-ops by default but can be swapped in tests or wired
-to a metrics backend by overriding the functions.
-"""
 
-from typing import Callable, Optional
+from __future__ import annotations
+
+from collections.abc import Callable
 
 # Function variables so applications/tests can replace them at runtime.
 on_rate_limit_exceeded: Callable[[str, int, int], None] | None = None
@@ -18,7 +19,7 @@ Args:
     retry_after: seconds until next allowed attempt
 """
 
-on_suspect_payload: Callable[[Optional[str], int], None] | None = None
+on_suspect_payload: Callable[[str | None, int], None] | None = None
 """
 Called when a request exceeds the configured size limit.
 Args:
@@ -36,7 +37,7 @@ def emit_rate_limited(key: str, limit: int, retry_after: int) -> None:
             pass
 
 
-def emit_suspect_payload(path: Optional[str], size: int) -> None:
+def emit_suspect_payload(path: str | None, size: int) -> None:
     if on_suspect_payload:
         try:
             on_suspect_payload(path, size)