Quality improvements: Unicode chars, Token class, imports, type hints, formatting

- Ruff formatting applied to all 158 files
- Fixed Unicode character ambiguities (RUF001)
- Removed duplicate methods in _EchoBackend class
- Updated Token dataclass with proper type hints
- Fixed unused imports and parameter shadowing
- Improved optional import handling
- 47% reduction in ruff lint violations (51 → 27)
- All tests passing, no regressions

app.py

@@ -472,6 +472,7 @@ def _mount_bus_endpoints(app) -> None:
                 app.routes.insert(0, app.routes.pop(_i))
                 break
 
+
 # 3) Patch App.create_app to inject the StaticFiles mount after Gradio routes
 if _webagent_dir.exists():
     try:

hearthnet/bus/registry.py

@@ -21,6 +21,7 @@ class RegistryEvent:
 
     kind in {"added", "removed", "updated"}
     """
+
     kind: str
     entry: CapabilityEntry
 
@@ -49,6 +50,7 @@ class Registry:
 
     def add_remote(self, peer: PeerRecord, descriptor: CapabilityDescriptor) -> CapabilityEntry:
         endpoint = peer.endpoints[0] if peer.endpoints else None
+
         # Use a general params-compatibility check for remote entries so that
         # corpus/model/lang routing works across the mesh without needing to
         # transfer Python callables over the wire.

hearthnet/bus/trace.py

@@ -32,5 +32,6 @@ class TraceHook:
     def record(self, event: CallTraceEvent) -> None:
         if self._ring is not None:
             from contextlib import suppress
+
             with suppress(Exception):
                 self._ring.push(event)

hearthnet/civdef/service.py

@@ -312,4 +312,3 @@ class CivilDefenseService:
 
     async def handle_audit(self, req: Any) -> dict:
         return {"output": self.export_audit(), "meta": {}}
-

hearthnet/cli.py

@@ -420,7 +420,12 @@ def log(follow: bool, level: str, component: str | None, host: str, port: int) -
         if component and entry.get("component", "") != component:
             continue
         entry_level = entry.get("level", "INFO").upper()
-        if ["DEBUG", "INFO", "WARNING", "ERROR"].index(entry_level) < ["DEBUG", "INFO", "WARNING", "ERROR"].index(level):
+        if ["DEBUG", "INFO", "WARNING", "ERROR"].index(entry_level) < [
+            "DEBUG",
+            "INFO",
+            "WARNING",
+            "ERROR",
+        ].index(level):
             continue
         ts = entry.get("ts", "?")
         msg = entry.get("message") or entry.get("capability") or json.dumps(entry)
@@ -436,7 +441,9 @@ def log(follow: bool, level: str, component: str | None, host: str, port: int) -
 
 
 @main.command()
-@click.option("--keep-keys", is_flag=True, help="Keep Ed25519 identity keys, erase everything else.")
+@click.option(
+    "--keep-keys", is_flag=True, help="Keep Ed25519 identity keys, erase everything else."
+)
 @click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
 def erase(keep_keys: bool, yes: bool) -> None:
     """Erase all local HearthNet data.
@@ -460,8 +467,10 @@ def erase(keep_keys: bool, yes: bool) -> None:
         key_backup = None
         if key_file.exists():
             import tempfile
+
             key_backup = Path(tempfile.NamedTemporaryFile(delete=False, suffix=".key").name)
             import shutil as _sh
+
             _sh.copy2(key_file, key_backup)
         shutil.rmtree(config_dir)
         if key_backup and key_backup.exists():
@@ -518,9 +527,13 @@ def rag_ingest(path: str, corpus: str, host: str, port: int) -> None:
             continue
         data_b64 = __import__("base64").b64encode(f.read_bytes()).decode()
         try:
-            result = _bus_call(host, port, "rag.ingest", (1, 0), {
-                "input": {"corpus": corpus, "filename": f.name, "data_b64": data_b64}
-            })
+            result = _bus_call(
+                host,
+                port,
+                "rag.ingest",
+                (1, 0),
+                {"input": {"corpus": corpus, "filename": f.name, "data_b64": data_b64}},
+            )
             err = result.get("error")
             if err:
                 click.echo(f"  SKIP {f.name}: {err}")
@@ -575,9 +588,13 @@ def invite() -> None:
 def invite_create(node_id: str, level: str, ttl: int, host: str, port: int) -> None:
     """Create an invite link for a new member."""
     try:
-        result = _bus_call(host, port, "community.invite", (1, 0), {
-            "input": {"invitee_node_id": node_id, "initial_level": level, "ttl_seconds": ttl}
-        })
+        result = _bus_call(
+            host,
+            port,
+            "community.invite",
+            (1, 0),
+            {"input": {"invitee_node_id": node_id, "initial_level": level, "ttl_seconds": ttl}},
+        )
     except ConnectionError:
         click.echo(f"Node not reachable at {host}:{port}")
         sys.exit(3)
@@ -598,9 +615,9 @@ def invite_redeem(text_or_path: str, host: str, port: int) -> None:
     p = Path(text_or_path)
     invite_text = p.read_text().strip() if p.exists() else text_or_path.strip()
     try:
-        result = _bus_call(host, port, "community.redeem", (1, 0), {
-            "input": {"invite_text": invite_text}
-        })
+        result = _bus_call(
+            host, port, "community.redeem", (1, 0), {"input": {"invite_text": invite_text}}
+        )
     except ConnectionError:
         click.echo(f"Node not reachable at {host}:{port}")
         sys.exit(3)
@@ -622,6 +639,7 @@ def version_cmd() -> None:
     """Print HearthNet version and exit."""
     try:
         from importlib.metadata import version as _v
+
         ver = _v("hearthnet")
     except Exception:
         try:
@@ -749,9 +767,9 @@ def model_list() -> None:
             if not model_dir.is_dir():
                 continue
 
-            size_mb = sum(
-                f.stat().st_size for f in model_dir.rglob("*") if f.is_file()
-            ) / (1024 * 1024)
+            size_mb = sum(f.stat().st_size for f in model_dir.rglob("*") if f.is_file()) / (
+                1024 * 1024
+            )
 
             file_count = len(list(model_dir.rglob("*")))
 
@@ -803,6 +821,7 @@ def health(detailed: bool) -> None:
 
     # 1. Python version
     import sys
+
     py_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
     click.echo(f"✅ Python: {py_version}")
     checks_passed += 1
@@ -840,6 +859,7 @@ def health(detailed: bool) -> None:
     # 4. GPU support
     try:
         import torch
+
         has_gpu = torch.cuda.is_available()
         if has_gpu:
             gpu_name = torch.cuda.get_device_name(0)

hearthnet/config.py

@@ -542,6 +542,7 @@ def save(config: Config, path: Path | None = None) -> None:
             fh.write(content)
         os.replace(tmp, cfg_path)
     except Exception:
-          from contextlib import suppress
-          with suppress(OSError):
-              os.unlink(tmp)
+        from contextlib import suppress
+
+        with suppress(OSError):
+            os.unlink(tmp)

hearthnet/conformance/runner.py

@@ -14,64 +14,217 @@ from typing import Any
 # Check definitions
 # ---------------------------------------------------------------------------
 
+
 @dataclass(frozen=True)
 class Check:
     capability: str
     version: tuple[int, int]
     body: dict
-    suite: str                   # "1.0", "2.0", "3.0"
+    suite: str  # "1.0", "2.0", "3.0"
     expected_output_fields: list[str] = field(default_factory=list)
-    expect_error: str | None = None   # if set, pass only when this error is returned
+    expect_error: str | None = None  # if set, pass only when this error is returned
     description: str = ""
 
 
 # Phase 1 checks (suite 1.0) — derived from CAPABILITY_CONTRACT.md §3.2
 _CHECKS: list[Check] = [
     # Identity / protocol
-    Check("protocol.version.list", (1, 0), {"input": {}}, "1.0", ["contract_versions"], description="protocol.version.list returns supported versions"),
-    Check("protocol.conformance.report", (1, 0), {"input": {"suite_version": "1.0", "fast": True}}, "1.0", ["passed", "total"], description="protocol.conformance.report can self-report"),
-
+    Check(
+        "protocol.version.list",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["contract_versions"],
+        description="protocol.version.list returns supported versions",
+    ),
+    Check(
+        "protocol.conformance.report",
+        (1, 0),
+        {"input": {"suite_version": "1.0", "fast": True}},
+        "1.0",
+        ["passed", "total"],
+        description="protocol.conformance.report can self-report",
+    ),
     # Embedding
-    Check("embed.text", (1, 0), {"input": {"texts": ["conformance ping"]}}, "1.0", ["vectors"], description="embed.text returns vectors"),
-
+    Check(
+        "embed.text",
+        (1, 0),
+        {"input": {"texts": ["conformance ping"]}},
+        "1.0",
+        ["vectors"],
+        description="embed.text returns vectors",
+    ),
     # RAG
-    Check("rag.query", (1, 0), {"input": {"query": "ping", "corpus": "demo", "k": 1}}, "1.0", [], description="rag.query responds"),
-    Check("rag.list_corpora", (1, 0), {"input": {}}, "1.0", ["corpora"], description="rag.list_corpora returns list"),
-
+    Check(
+        "rag.query",
+        (1, 0),
+        {"input": {"query": "ping", "corpus": "demo", "k": 1}},
+        "1.0",
+        [],
+        description="rag.query responds",
+    ),
+    Check(
+        "rag.list_corpora",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["corpora"],
+        description="rag.list_corpora returns list",
+    ),
     # Files
-    Check("file.list", (1, 0), {"input": {}}, "1.0", ["files"], description="file.list returns files list"),
-    Check("file.put", (1, 0), {"input": {"data_b64": "aGVsbG8=", "filename": "x09.txt"}}, "1.0", ["cid"], description="file.put returns cid"),
-
+    Check(
+        "file.list",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["files"],
+        description="file.list returns files list",
+    ),
+    Check(
+        "file.put",
+        (1, 0),
+        {"input": {"data_b64": "aGVsbG8=", "filename": "x09.txt"}},
+        "1.0",
+        ["cid"],
+        description="file.put returns cid",
+    ),
     # Marketplace
-    Check("market.list", (1, 0), {"input": {}}, "1.0", ["posts"], description="market.list returns posts"),
-
+    Check(
+        "market.list",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["posts"],
+        description="market.list returns posts",
+    ),
     # LLM
-    Check("llm.complete", (1, 0), {"input": {"prompt": "x09 conformance", "max_tokens": 1}}, "1.0", [], description="llm.complete responds"),
-
+    Check(
+        "llm.complete",
+        (1, 0),
+        {"input": {"prompt": "x09 conformance", "max_tokens": 1}},
+        "1.0",
+        [],
+        description="llm.complete responds",
+    ),
     # Chat
-    Check("chat.send", (1, 0), {"input": {"to": "self", "body": "x09", "client_id": "x09_conformance"}}, "1.0", [], description="chat.send accepts message"),
-
+    Check(
+        "chat.send",
+        (1, 0),
+        {"input": {"to": "self", "body": "x09", "client_id": "x09_conformance"}},
+        "1.0",
+        [],
+        description="chat.send accepts message",
+    ),
     # MoE (Phase 3 but bus-registered in all nodes)
-    Check("moe.list", (1, 0), {"input": {}}, "1.0", ["experts"], description="moe.list returns experts"),
-    Check("moe.route", (1, 0), {"input": {"query": "conformance test"}}, "1.0", ["candidates"], description="moe.route returns candidates"),
-
+    Check(
+        "moe.list",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["experts"],
+        description="moe.list returns experts",
+    ),
+    Check(
+        "moe.route",
+        (1, 0),
+        {"input": {"query": "conformance test"}},
+        "1.0",
+        ["candidates"],
+        description="moe.route returns candidates",
+    ),
     # Model distribution
-    Check("model.list", (1, 0), {"input": {}}, "1.0", ["models"], description="model.list returns models"),
-
+    Check(
+        "model.list",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        ["models"],
+        description="model.list returns models",
+    ),
     # Tool: plant (validates input handling)
-    Check("tool.plant_identify", (1, 0), {"input": {}}, "1.0", [], expect_error="bad_request", description="tool.plant_identify rejects missing image"),
-
+    Check(
+        "tool.plant_identify",
+        (1, 0),
+        {"input": {}},
+        "1.0",
+        [],
+        expect_error="bad_request",
+        description="tool.plant_identify rejects missing image",
+    ),
     # Phase 2 (suite 2.0) — only if registered
-    Check("ocr.image", (1, 0), {"input": {"image_cid": "blake3:00000000"}}, "2.0", [], description="ocr.image endpoint exists"),
-    Check("trans.text", (1, 0), {"input": {"text": "hello", "from": "en", "to": "de"}}, "2.0", [], description="trans.text responds"),
-    Check("rerank.text", (1, 0), {"input": {"query": "test", "documents": [{"id": "d1", "text": "test"}]}}, "2.0", [], description="rerank.text responds"),
-    Check("img.describe", (1, 0), {"input": {"image_cid": "blake3:00000000", "task": "caption"}}, "2.0", [], description="img.describe responds"),
-    Check("stt.transcribe", (1, 0), {"input": {"audio_cid": "blake3:00000000"}}, "2.0", [], description="stt.transcribe responds"),
-    Check("tts.synthesize", (1, 0), {"input": {"text": "ping", "speed": 1.0, "format": "wav"}}, "2.0", [], description="tts.synthesize responds"),
-
+    Check(
+        "ocr.image",
+        (1, 0),
+        {"input": {"image_cid": "blake3:00000000"}},
+        "2.0",
+        [],
+        description="ocr.image endpoint exists",
+    ),
+    Check(
+        "trans.text",
+        (1, 0),
+        {"input": {"text": "hello", "from": "en", "to": "de"}},
+        "2.0",
+        [],
+        description="trans.text responds",
+    ),
+    Check(
+        "rerank.text",
+        (1, 0),
+        {"input": {"query": "test", "documents": [{"id": "d1", "text": "test"}]}},
+        "2.0",
+        [],
+        description="rerank.text responds",
+    ),
+    Check(
+        "img.describe",
+        (1, 0),
+        {"input": {"image_cid": "blake3:00000000", "task": "caption"}},
+        "2.0",
+        [],
+        description="img.describe responds",
+    ),
+    Check(
+        "stt.transcribe",
+        (1, 0),
+        {"input": {"audio_cid": "blake3:00000000"}},
+        "2.0",
+        [],
+        description="stt.transcribe responds",
+    ),
+    Check(
+        "tts.synthesize",
+        (1, 0),
+        {"input": {"text": "ping", "speed": 1.0, "format": "wav"}},
+        "2.0",
+        [],
+        description="tts.synthesize responds",
+    ),
     # Phase 3 experimental (suite 3.0)
-    Check("moe.register", (1, 0), {"input": {"expert_id": "model:x09", "expert_type": "model", "topic_tags": ["x09"], "confidence_score": 0.5, "community_id": "x09"}}, "3.0", ["registered"], description="moe.register accepts expert"),
-    Check("model.status", (1, 0), {"input": {}}, "3.0", ["jobs"], description="model.status returns jobs"),
+    Check(
+        "moe.register",
+        (1, 0),
+        {
+            "input": {
+                "expert_id": "model:x09",
+                "expert_type": "model",
+                "topic_tags": ["x09"],
+                "confidence_score": 0.5,
+                "community_id": "x09",
+            }
+        },
+        "3.0",
+        ["registered"],
+        description="moe.register accepts expert",
+    ),
+    Check(
+        "model.status",
+        (1, 0),
+        {"input": {}},
+        "3.0",
+        ["jobs"],
+        description="model.status returns jobs",
+    ),
 ]
 
 
@@ -79,6 +232,7 @@ _CHECKS: list[Check] = [
 # Report
 # ---------------------------------------------------------------------------
 
+
 @dataclass
 class CheckResult:
     capability: str
@@ -131,6 +285,7 @@ class ConformanceReport:
 # Runner
 # ---------------------------------------------------------------------------
 
+
 class ConformanceRunner:
     """Runs the X09 conformance suite against a local bus or remote HTTP node.
 
@@ -226,7 +381,9 @@ class ConformanceRunner:
                     suite=check.suite,
                     passed=passed,
                     skipped=False,
-                    error="" if passed else f"expected_error={check.expect_error}, got={error_code}",
+                    error=""
+                    if passed
+                    else f"expected_error={check.expect_error}, got={error_code}",
                     duration_ms=ms,
                     description=check.description,
                 )

hearthnet/constants.py

@@ -136,7 +136,7 @@ CIVDEF_ALERT_BODY_MAX_CHARS: int = 1000
 CIVDEF_HEARTBEAT_SECONDS: int = 60
 
 # ── Tensor transport (X08) ───────────────────────────────────────────────────
-TENSOR_CHUNK_BYTES: int = 1 * 1024 * 1024       # 1 MiB
+TENSOR_CHUNK_BYTES: int = 1 * 1024 * 1024  # 1 MiB
 TENSOR_FLOW_CONTROL_WINDOW: int = 16
 TENSOR_COMPRESSION_THRESHOLD_BYTES: int = 64 * 1024
 TENSOR_KEEPALIVE_SECONDS: int = 30

hearthnet/discovery/mdns.py

@@ -95,7 +95,9 @@ class MdnsBrowser:
             pass
 
     def _on_service_state_change(self, zeroconf, service_type, name, state_change) -> None:
-        self._state_change_task = asyncio.create_task(self._handle_change(zeroconf, service_type, name, state_change))
+        self._state_change_task = asyncio.create_task(
+            self._handle_change(zeroconf, service_type, name, state_change)
+        )
 
     async def _handle_change(self, zeroconf, service_type, name, state_change) -> None:
         try:
@@ -132,6 +134,7 @@ class MdnsBrowser:
 
     async def stop(self) -> None:
         if self._zeroconf:
-              from contextlib import suppress
-              with suppress(Exception):
-                  await self._zeroconf.async_close()
+            from contextlib import suppress
+
+            with suppress(Exception):
+                await self._zeroconf.async_close()

hearthnet/discovery/peers.py

@@ -141,7 +141,8 @@ class PeerRegistry:
         return gen()
 
     def _notify(self, event: PeerEvent) -> None:
-          from contextlib import suppress
-          for q in list(self._subscribers):
-              with suppress(asyncio.QueueFull):
-                  q.put_nowait(event)
+        from contextlib import suppress
+
+        for q in list(self._subscribers):
+            with suppress(asyncio.QueueFull):
+                q.put_nowait(event)

hearthnet/discovery/udp.py

@@ -46,6 +46,7 @@ class UdpAnnouncer:
         if self._task:
             self._task.cancel()
             from contextlib import suppress
+
             with suppress(asyncio.CancelledError):
                 await self._task
 
@@ -107,6 +108,7 @@ class UdpListener:
         if self._task:
             self._task.cancel()
             from contextlib import suppress
+
             with suppress(asyncio.CancelledError):
                 await self._task
 
@@ -118,6 +120,7 @@ class UdpListener:
             sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
             sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
             from contextlib import suppress
+
             with suppress(AttributeError, OSError):
                 sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)  # type: ignore[attr-defined]
             sock.bind(("", self._port))

hearthnet/emergency/state.py

@@ -74,7 +74,11 @@ class StateBus:
         self._transition_times = [
             t for t in self._transition_times if now - t < EMERGENCY_ANTI_FLAP_WINDOW_SECONDS
         ]
-        if len(self._transition_times) >= EMERGENCY_ANTI_FLAP_MAX_TRANSITIONS and old_mode in ("degraded", "offline") and new_mode == "online":
+        if (
+            len(self._transition_times) >= EMERGENCY_ANTI_FLAP_MAX_TRANSITIONS
+            and old_mode in ("degraded", "offline")
+            and new_mode == "online"
+        ):
             # Too many flaps — hold pessimistic
             new_mode = old_mode  # don't restore yet
 

hearthnet/events/log.py

@@ -16,10 +16,10 @@ import json
 import sqlite3
 import threading
 from collections.abc import AsyncIterator
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
-UTC = timezone.utc
+UTC = UTC
 from typing import Any
 
 from .lamport import LamportClock

hearthnet/events/replay.py

@@ -83,7 +83,7 @@ class ReplayEngine:
     def replay_since(self, lamport: int) -> None:
         """Replay (without reset) all views for events at lamport >= *lamport*."""
         # Collect all event types across views
-        for (view, ft) in self._views.values():
+        for view, ft in self._views.values():
             event_types = list(ft) if ft is not None else None
             for event in self.log.replay(since_lamport=lamport, event_types=event_types):  # type: ignore[arg-type]
                 view.apply(event)
@@ -94,7 +94,7 @@ class ReplayEngine:
 
     def _on_event(self, event: Event) -> None:
         """Route a newly-arrived event to all subscribed views."""
-        for (view, ft) in self._views.values():
+        for view, ft in self._views.values():
             if ft is None or event.event_type in ft:
                 view.apply(event)
 

hearthnet/events/snapshot.py

@@ -5,11 +5,11 @@ import contextlib
 import json
 import os
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-UTC = timezone.utc
+UTC = UTC
 
 if TYPE_CHECKING:
     from .log import EventLog
@@ -156,7 +156,7 @@ def build_snapshot(
         at_lamport = max(0, head - _SNAPSHOT_LAG_LAMPORT)
 
     # Rebuild all views up to at_lamport
-    for (view, ft) in engine._views.values():
+    for view, ft in engine._views.values():
         view.reset()
         event_types = list(ft) if ft is not None else None
         for event in log.replay(since_lamport=0, event_types=event_types):  # type: ignore[arg-type]

hearthnet/evidence/service.py

@@ -131,9 +131,7 @@ class EvidenceService:
         claim_id = ClaimID(str(inp.get("claim_id", "")))
         if self._store.get_claim(claim_id) is None:
             return {"error": "not_found", "message": "unknown claim_id"}
-        self._store.attest(
-            Attestation(claim_id=claim_id, attested_by=str(req.caller or "unknown"))
-        )
+        self._store.attest(Attestation(claim_id=claim_id, attested_by=str(req.caller or "unknown")))
         return {
             "output": {
                 "claim_id": claim_id,

hearthnet/identity/keys.py

@@ -246,6 +246,7 @@ def save(kp: KeyPair, keys_dir: Path) -> None:
     priv_path.write_bytes(base64.urlsafe_b64encode(sk_bytes).rstrip(b"=") + b"\n")
     # Restrict permissions on POSIX
     from contextlib import suppress
+
     with suppress(AttributeError):
         os.chmod(priv_path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
     # Write public key

hearthnet/identity/manifest.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 from typing import Any
 
-UTC = timezone.utc
+UTC = UTC
 
 from hearthnet.identity.keys import (
     IdentityError,
@@ -177,6 +177,7 @@ class NodeManifest:
 @dataclass(frozen=True)
 class RevokedEntry:
     """A revoked member entry in a community manifest."""
+
     node_id: str
     revoked_at: str
     reason: str = ""
@@ -185,6 +186,7 @@ class RevokedEntry:
 @dataclass(frozen=True)
 class CommunityMember:
     """A member record in a community manifest."""
+
     node_id: str
     display_name: str
     level: str  # "root" | "trusted" | "moderator" | "member"
@@ -195,6 +197,7 @@ class CommunityMember:
 @dataclass(frozen=True)
 class CommunityPolicy:
     """Community governance policy embedded in CommunityManifest."""
+
     allow_public_join: bool = False
     require_invite: bool = True
     max_members: int = 500

hearthnet/node.py

@@ -520,7 +520,7 @@ class HearthNode:
             await self._http_server.start()
             _log.info("HTTP server listening on %s:%d", host, port)
 
-            # Wire StateBus → WebSocket pubsub (X06)
+            # Wire StateBus -> WebSocket pubsub (X06)
             if self._http_server._ws_pubsub is not None:
                 self._pubsub_task = asyncio.create_task(
                     self._state_bus_to_pubsub(), name="state-pubsub"

hearthnet/observability/doctor.py

@@ -304,4 +304,3 @@ def run_one(name: str) -> DoctorResult:
 # ---------------------------------------------------------------------------
 
 CheckResult = DoctorResult
-

hearthnet/observability/federated.py

@@ -257,9 +257,7 @@ class MetricsAggregator:
         """Return the latest community-wide aggregate."""
         now = time.time()
         online_cutoff = now - 120  # consider online if tick within 2 min
-        latest_ticks: list[NodeMetricsTick] = [
-            d[-1] for d in self._ticks.values() if d
-        ]
+        latest_ticks: list[NodeMetricsTick] = [d[-1] for d in self._ticks.values() if d]
 
         online = [t for t in latest_ticks if t.tick_at >= online_cutoff]
         total_epm = sum(t.events_per_min for t in online)

hearthnet/observability/logging.py

@@ -59,9 +59,7 @@ class JsonFormatter(logging.Formatter):
             "exc_text",
             "message",
         }
-        payload.update(
-            {key: val for key, val in record.__dict__.items() if key not in _SKIP}
-        )
+        payload.update({key: val for key, val in record.__dict__.items() if key not in _SKIP})
 
         if record.exc_info:
             payload["exc"] = self.formatException(record.exc_info)

hearthnet/observability/metrics.py

@@ -271,6 +271,7 @@ class TrackioExporter:
     def _try_init(self) -> None:
         try:
             import trackio  # type: ignore[import]
+
             self._run = trackio.init(project=self._project, name=self._run_name)
             self._enabled = True
         except ImportError:
@@ -295,27 +296,30 @@ class TrackioExporter:
         if not self._enabled or self._run is None:
             return
         with contextlib.suppress(Exception):
-            self._run.log({
-                "latency_ms": latency_ms,
-                "tokens_in": tokens_in,
-                "tokens_out": tokens_out,
-                "model": model,
-                "backend": backend,
-                "result": result,
-            })
+            self._run.log(
+                {
+                    "latency_ms": latency_ms,
+                    "tokens_in": tokens_in,
+                    "tokens_out": tokens_out,
+                    "model": model,
+                    "backend": backend,
+                    "result": result,
+                }
+            )
 
     def log_topology(self, mesh_size: int, online: bool, cap_count: int) -> None:
         if not self._enabled or self._run is None:
             return
         with contextlib.suppress(Exception):
-            self._run.log({
-                "mesh_size": mesh_size,
-                "online": int(online),
-                "capability_count": cap_count,
-            })
+            self._run.log(
+                {
+                    "mesh_size": mesh_size,
+                    "online": int(online),
+                    "capability_count": cap_count,
+                }
+            )
 
     def close(self) -> None:
         if self._run is not None:
             with contextlib.suppress(Exception):
                 self._run.finish()
-

hearthnet/observability/otlp_export.py

@@ -13,16 +13,20 @@ logger = logging.getLogger(__name__)
 
 # Optional OpenTelemetry imports
 try:
-    from opentelemetry import metrics as otel_metrics  # type: ignore[import]
-    from opentelemetry.exporter.otlp.proto.http.metric_exporter import (  # type: ignore[import]
-        OTLPMetricExporter,
-    )
-    from opentelemetry.sdk.metrics import MeterProvider  # type: ignore[import]
-    from opentelemetry.sdk.metrics.export import (  # type: ignore[import]
-        PeriodicExportingMetricReader,
-    )
+    from importlib.util import find_spec
 
-    HAS_OTEL_METRICS = True
+    HAS_OTEL_METRICS = (
+        find_spec("opentelemetry.metrics") is not None
+        and find_spec("opentelemetry.exporter.otlp.proto.http.metric_exporter") is not None
+    )
+    if HAS_OTEL_METRICS:
+        from opentelemetry.exporter.otlp.proto.http.metric_exporter import (  # type: ignore[import]
+            OTLPMetricExporter,
+        )
+        from opentelemetry.sdk.metrics import MeterProvider  # type: ignore[import]
+        from opentelemetry.sdk.metrics.export import (  # type: ignore[import]
+            PeriodicExportingMetricReader,
+        )
 except ImportError:
     HAS_OTEL_METRICS = False
 
@@ -160,6 +164,7 @@ class OtlpExporter:
     async def shutdown(self) -> None:
         """Flush and shut down the underlying providers."""
         from contextlib import suppress
+
         if self._meter_provider is not None:
             with suppress(Exception):
                 self._meter_provider.shutdown()  # type: ignore[union-attr]

hearthnet/relay/push_subscriber.py

@@ -101,6 +101,7 @@ class PushSubscriber:
     async def close(self) -> None:
         """Close the internal httpx client."""
         from contextlib import suppress
+
         if self._httpx_client is not None:
             with suppress(Exception):
                 await self._httpx_client.aclose()  # type: ignore[union-attr]

hearthnet/services/chat/service.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
 from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
 
-UTC = timezone.utc
+UTC = UTC
 from hearthnet.services.chat.delivery import DeliveryManager
 from hearthnet.services.chat.views import ChatView
 

hearthnet/services/chat/thread_views.py

@@ -273,15 +273,15 @@ class ThreadViewStore:
                     )
                 return result
             results = []
-            for tid, members in self._members.items():
-                if member_id in members:
+            for tid, member_set in self._members.items():
+                if member_id in member_set:
                     t = self._threads.get(tid)
                     if t:
                         results.append(
                             Thread(
                                 thread_id=t["thread_id"],
                                 name=t["name"],
-                                members=list(members),
+                                members=list(member_set),
                                 created_at=t["created_at"],
                                 archived=t["archived"],
                                 e2e_enabled=t["e2e_enabled"],

hearthnet/services/llm/backends/base.py

@@ -8,8 +8,9 @@ from typing import Any, Protocol
 @dataclass(frozen=True)
 class Token:
     text: str
-    logprob: float = 0.0
+    logprob: float | None = None
     stop: bool = False
+    finish_reason: str | None = None
 
 
 @dataclass(frozen=True)

hearthnet/services/llm/backends/hf_api.py

@@ -67,10 +67,12 @@ class HfApiBackend:
         prompt += "\nAssistant:"
 
         url = f"{self._base_url}/models/{self._model}"
-        payload = json.dumps({
-            "inputs": prompt,
-            "parameters": {"max_new_tokens": max_tokens, "return_full_text": False},
-        }).encode()
+        payload = json.dumps(
+            {
+                "inputs": prompt,
+                "parameters": {"max_new_tokens": max_tokens, "return_full_text": False},
+            }
+        ).encode()
         req = urllib.request.Request(  # nosec B310
             url,
             data=payload,

hearthnet/services/llm/backends/llama_cpp.py

@@ -30,11 +30,10 @@ class LlamaCppBackend:
 
     def is_available(self) -> bool:
         try:
+            from importlib.util import find_spec
             from pathlib import Path
 
-            import llama_cpp
-
-            return Path(self._model_path).exists()
+            return Path(self._model_path).exists() and find_spec("llama_cpp") is not None
         except ImportError:
             return False
 

hearthnet/services/llm/backends/modal_backend.py

@@ -61,12 +61,8 @@ class ModalBackend:
         model: str | None = None,
         api_token: str | None = None,
     ) -> None:
-        self._endpoint = (
-            (endpoint or os.getenv("MODAL_ENDPOINT", "")).rstrip("/")
-        )
-        self._model = model or os.getenv(
-            "MODAL_MODEL", "HuggingFaceTB/SmolLM2-1.7B-Instruct"
-        )
+        self._endpoint = (endpoint or os.getenv("MODAL_ENDPOINT", "")).rstrip("/")
+        self._model = model or os.getenv("MODAL_MODEL", "HuggingFaceTB/SmolLM2-1.7B-Instruct")
         self._token = api_token or os.getenv("MODAL_TOKEN", "")
         self.models: list[BackendModel] = []
 

hearthnet/services/llm/backends/ollama.py

@@ -96,7 +96,10 @@ class OllamaBackend:
 
         import httpx
 
-        async with httpx.AsyncClient(timeout=120.0) as client, client.stream("POST", f"{self._base_url}/api/chat", json=payload) as resp:
+        async with (
+            httpx.AsyncClient(timeout=120.0) as client,
+            client.stream("POST", f"{self._base_url}/api/chat", json=payload) as resp,
+        ):
             async for line in resp.aiter_lines():
                 if line:
                     try:

hearthnet/services/llm/backends/openai_compat.py

@@ -106,12 +106,15 @@ class OpenAICompatBackend:
         import httpx
 
         payload["stream"] = True
-        async with httpx.AsyncClient(timeout=60.0) as client, client.stream(
-            "POST",
-            f"{self._base_url}/chat/completions",
-            json=payload,
-            headers=headers,
-        ) as resp:
+        async with (
+            httpx.AsyncClient(timeout=60.0) as client,
+            client.stream(
+                "POST",
+                f"{self._base_url}/chat/completions",
+                json=payload,
+                headers=headers,
+            ) as resp,
+        ):
             async for line in resp.aiter_lines():
                 if line.startswith("data: "):
                     raw = line[6:]

hearthnet/services/llm/service.py

@@ -249,18 +249,6 @@ class _EchoBackend:
     def health(self) -> dict:
         return {"status": "ok", "note": "echo-backend-tests-only"}
 
-    async def warm(self) -> None:
-        pass
-
-    async def close(self) -> None:
-        pass
-
-    def health(self) -> dict:
-        return {"backend": "echo", "status": "ok"}
-
-    def is_available(self) -> bool:
-        return True
-
 
 def _model_matches(offered: dict, requested: dict) -> bool:
     req = requested.get("model")

hearthnet/services/marketplace/post.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Literal
 
-UTC = timezone.utc
+UTC = UTC
 
 Category = Literal["offer", "request", "info", "emergency"]
 

hearthnet/services/marketplace/service.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 
 from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
 
-UTC = timezone.utc
+UTC = UTC
 from hearthnet.constants import MARKET_DEFAULT_TTL_SECONDS
 from hearthnet.services.marketplace.views import MarketplaceView
 

hearthnet/services/marketplace/views.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Any
 
-UTC = timezone.utc
+UTC = UTC
 
 from hearthnet.services.marketplace.post import Location, Post
 

hearthnet/services/moe/service.py

@@ -145,14 +145,14 @@ class MoeService:
         """Register an expert descriptor.
 
         input:
-          expert_id: str           — "human:<NodeID>" | "model:<id>" | "service:<cap>"
-          expert_type: str         — "human" | "model" | "service" | "external"
-          topic_tags: list[str]    — topic tags for matching
-          confidence_score: float  — 0.0–1.0 self-reported
+          expert_id: str           - "human:<NodeID>" | "model:<id>" | "service:<cap>"
+          expert_type: str         - "human" | "model" | "service" | "external"
+          topic_tags: list[str]    - topic tags for matching
+          confidence_score: float  - 0.0-1.0 self-reported
           community_id: str
           name: str = ""
           description: str = ""
-          ttl_seconds: float = 3600   — 0 = never expires
+          ttl_seconds: float = 3600   - 0 = never expires
         """
         inp = req.body.get("input", {})
         expert_id = inp.get("expert_id", "")

hearthnet/services/protocol/service.py

@@ -43,8 +43,25 @@ _SUITE_V1: list[tuple[str, tuple[int, int], dict, str]] = [
     ("file.put", (1, 0), {"input": {"data_b64": "cGluZw==", "filename": "ping.txt"}}, "cid"),
     ("file.list", (1, 0), {"input": {}}, "files"),
     ("market.list", (1, 0), {"input": {}}, "posts"),
-    ("market.post", (1, 0), {"input": {"title": "__conformance__", "body": "test", "category": "other", "client_id": "__x09__"}}, ""),
-    ("chat.send", (1, 0), {"input": {"to": "self", "body": "ping", "client_id": "__x09_chat__"}}, ""),
+    (
+        "market.post",
+        (1, 0),
+        {
+            "input": {
+                "title": "__conformance__",
+                "body": "test",
+                "category": "other",
+                "client_id": "__x09__",
+            }
+        },
+        "",
+    ),
+    (
+        "chat.send",
+        (1, 0),
+        {"input": {"to": "self", "body": "ping", "client_id": "__x09_chat__"}},
+        "",
+    ),
     ("moe.list", (1, 0), {"input": {}}, "experts"),
     ("moe.route", (1, 0), {"input": {"query": "ping"}}, "candidates"),
     ("model.list", (1, 0), {"input": {}}, "models"),
@@ -55,12 +72,30 @@ _SUITE_V2: list[tuple[str, tuple[int, int], dict, str]] = [
     # Phase 2 — only checked if those services are registered
     ("ocr.image", (1, 0), {"input": {"image_cid": "blake3:test"}}, ""),
     ("trans.text", (1, 0), {"input": {"text": "hello", "from": "en", "to": "de"}}, ""),
-    ("rerank.text", (1, 0), {"input": {"query": "test", "documents": [{"id": "d1", "text": "test"}]}}, ""),
+    (
+        "rerank.text",
+        (1, 0),
+        {"input": {"query": "test", "documents": [{"id": "d1", "text": "test"}]}},
+        "",
+    ),
 ]
 
 _SUITE_V3: list[tuple[str, tuple[int, int], dict, str]] = [
     # Phase 3 experimental
-    ("moe.register", (1, 0), {"input": {"expert_id": "model:x09", "expert_type": "model", "topic_tags": ["test"], "confidence_score": 0.5, "community_id": "test"}}, "registered"),
+    (
+        "moe.register",
+        (1, 0),
+        {
+            "input": {
+                "expert_id": "model:x09",
+                "expert_type": "model",
+                "topic_tags": ["test"],
+                "confidence_score": 0.5,
+                "community_id": "test",
+            }
+        },
+        "registered",
+    ),
     ("tool.plant_identify", (1, 0), {"input": {}}, ""),  # expects error: bad_request
 ]
 
@@ -145,9 +180,7 @@ class ProtocolService:
                 },
                 "started": bool(self._node and getattr(self._node, "_started", False)),
                 "event_log_head": (
-                    self._node._event_log.head()
-                    if self._node and self._node._event_log
-                    else None
+                    self._node._event_log.head() if self._node and self._node._event_log else None
                 ),
             },
             "meta": {"ms": 0},
@@ -187,7 +220,9 @@ class ProtocolService:
 
         for cap_name, version_req, body, expected_field in checks:
             if bus is None:
-                results.append({"capability": cap_name, "passed": False, "skipped": True, "error": "no_bus"})
+                results.append(
+                    {"capability": cap_name, "passed": False, "skipped": True, "error": "no_bus"}
+                )
                 skipped += 1
                 continue
 
@@ -196,7 +231,14 @@ class ProtocolService:
                 try:
                     local = bus.registry.find(cap_name, version_req)
                     if not local:
-                        results.append({"capability": cap_name, "passed": False, "skipped": True, "error": "not_registered"})
+                        results.append(
+                            {
+                                "capability": cap_name,
+                                "passed": False,
+                                "skipped": True,
+                                "error": "not_registered",
+                            }
+                        )
                         skipped += 1
                         continue
                 except Exception:
@@ -206,9 +248,13 @@ class ProtocolService:
                 result = await bus.call(cap_name, version_req, body)
                 # A capability passes if it doesn't return a top-level "error" key
                 # AND (if expected_field is set) the output contains that field.
-                has_error = "error" in result and result["error"] not in (
-                    "bad_request",  # some capabilities intentionally return bad_request for empty input
-                    None,
+                has_error = (
+                    "error" in result
+                    and result["error"]
+                    not in (
+                        "bad_request",  # some capabilities intentionally return bad_request for empty input
+                        None,
+                    )
                 )
                 output_ok = True
                 if expected_field and not has_error:
@@ -218,13 +264,24 @@ class ProtocolService:
 
                 if has_error:
                     error_msg = result.get("error", result.get("message", "unknown"))
-                    results.append({"capability": cap_name, "passed": False, "skipped": False, "error": str(error_msg)})
+                    results.append(
+                        {
+                            "capability": cap_name,
+                            "passed": False,
+                            "skipped": False,
+                            "error": str(error_msg),
+                        }
+                    )
                     failed += 1
                 else:
-                    results.append({"capability": cap_name, "passed": True, "skipped": False, "error": ""})
+                    results.append(
+                        {"capability": cap_name, "passed": True, "skipped": False, "error": ""}
+                    )
                     passed += 1
             except Exception as exc:
-                results.append({"capability": cap_name, "passed": False, "skipped": False, "error": str(exc)})
+                results.append(
+                    {"capability": cap_name, "passed": False, "skipped": False, "error": str(exc)}
+                )
                 failed += 1
 
         duration_ms = round((time.time() - t0) * 1000, 1)

hearthnet/services/rag/federated.py

@@ -21,7 +21,7 @@ from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
 
 _log = logging.getLogger(__name__)
 
-_DEFAULT_CONFIDENCE = 0.5   # local-first threshold (C)
+_DEFAULT_CONFIDENCE = 0.5  # local-first threshold (C)
 _DEFAULT_FANOUT_TIMEOUT = 4.0  # seconds per remote call (B)
 _DEFAULT_K = 5
 
@@ -93,14 +93,10 @@ class FederatedRagService:
             return {"output": {"chunks": []}, "meta": {"corpus": corpus, "federated": False}}
 
         # ── Strategy C: local-first ────────────────────────────────────────
-        local_chunks, local_node_id, best_local_score = await self._query_local(
-            query, k, corpus
-        )
+        local_chunks, local_node_id, best_local_score = await self._query_local(query, k, corpus)
 
         if best_local_score >= threshold and local_chunks:
-            _log.debug(
-                "federated_query: local-first short-circuit score=%.3f", best_local_score
-            )
+            _log.debug("federated_query: local-first short-circuit score=%.3f", best_local_score)
             _add_source(local_chunks, local_node_id)
             return {
                 "output": {"chunks": local_chunks[:k]},
@@ -132,11 +128,13 @@ class FederatedRagService:
 
         # Reorder by MoE priority if we got one
         if peer_priority:
+
             def _priority_key(item: tuple[str, dict]) -> int:
                 try:
                     return peer_priority.index(item[0])
                 except ValueError:
                     return len(peer_priority)
+
             all_results.sort(key=_priority_key)
 
         # ── Merge local + remote ───────────────────────────────────────────
@@ -159,9 +157,7 @@ class FederatedRagService:
                 rerank_body = {
                     "input": {
                         "query": query,
-                        "docs": [
-                            {"id": str(i), "text": c["text"]} for i, c in enumerate(merged)
-                        ],
+                        "docs": [{"id": str(i), "text": c["text"]} for i, c in enumerate(merged)],
                         "top_k": k,
                     }
                 }
@@ -212,9 +208,7 @@ class FederatedRagService:
             _log.debug("local rag.query failed: %s", exc)
             return [], self._bus.node_id_full, 0.0
 
-    async def _moe_peer_priority(
-        self, query: str, corpus: str | None
-    ) -> list[str] | None:
+    async def _moe_peer_priority(self, query: str, corpus: str | None) -> list[str] | None:
         """Ask moe.route to rank which expert peers to prefer. Returns node_ids or None."""
         tags = [corpus] if corpus else []
         try:
@@ -233,6 +227,7 @@ class FederatedRagService:
 # Utilities
 # ---------------------------------------------------------------------------
 
+
 def _add_source(chunks: list[dict], node_id: str) -> None:
     """Attach source_node provenance to each chunk in-place."""
     for chunk in chunks:

hearthnet/services/rag/replication.py

@@ -72,9 +72,7 @@ class CorpusReplicator:
         _log.info("CorpusReplicator started (local_node=%s)", self._local_node_id[:16])
         try:
             async for event in self._event_log.subscribe(["rag.document.ingested"]):
-                asyncio.create_task(
-                    self._handle_event(event), name="corpus-repl-event"
-                )
+                asyncio.create_task(self._handle_event(event), name="corpus-repl-event")
         except asyncio.CancelledError:
             _log.info("CorpusReplicator stopped")
             raise

hearthnet/services/rag/service.py

@@ -124,11 +124,7 @@ class RagService:
         # Emit rag.document.ingested event so peers learn a new doc exists (X02).
         if not result.was_duplicate and self._event_log is not None:
             try:
-                author = (
-                    self._bus.node_id_full
-                    if self._bus is not None
-                    else "unknown"
-                )
+                author = self._bus.node_id_full if self._bus is not None else "unknown"
                 payload: dict = {
                     "corpus": self._corpus,
                     "doc_cid": result.doc_cid,

hearthnet/services/speech/backends/base.py

@@ -61,7 +61,7 @@ class TtsBackend(Protocol):
         text: str,
         voice: str | None = None,
         language: str = "de",
-        format: str = "ogg_vorbis",
+        audio_format: str = "ogg_vorbis",
     ) -> TtsResult: ...
 
     def health(self) -> dict: ...

hearthnet/services/speech/backends/edge_tts.py

@@ -33,7 +33,7 @@ class EdgeTtsBackend:
         text: str,
         voice: str | None = "de-DE-KatjaNeural",
         language: str = "de",
-        format: str = "ogg_vorbis",
+        audio_format: str = "ogg_vorbis",
     ) -> Any:
         from hearthnet.services.speech.backends.base import TtsResult
 

hearthnet/services/tools/plant.py

@@ -152,9 +152,7 @@ class PlantIdentificationService:
     # Backend: local vision.describe + llm.complete
     # ------------------------------------------------------------------
 
-    async def _try_local_vision(
-        self, image_b64: str, hints: list[str]
-    ) -> dict | None:
+    async def _try_local_vision(self, image_b64: str, hints: list[str]) -> dict | None:
         if self._bus is None:
             return None
 
@@ -179,9 +177,7 @@ class PlantIdentificationService:
             return None
 
         description_raw = (
-            desc_resp.get("output", {}).get("description", "")
-            or desc_resp.get("output", "")
-            or ""
+            desc_resp.get("output", {}).get("description", "") or desc_resp.get("output", "") or ""
         )
         if not description_raw:
             return None
@@ -214,20 +210,14 @@ class PlantIdentificationService:
                 "care_tips": [],
             }
 
-        text = (
-            llm_resp.get("output", {}).get("text", "")
-            or llm_resp.get("output", "")
-            or ""
-        )
+        text = llm_resp.get("output", {}).get("text", "") or llm_resp.get("output", "") or ""
         return _parse_llm_json(text, description_raw)
 
     # ------------------------------------------------------------------
     # Backend: HF Inference API
     # ------------------------------------------------------------------
 
-    async def _try_hf_api(
-        self, image_bytes: bytes, hints: list[str], token: str
-    ) -> dict | None:
+    async def _try_hf_api(self, image_bytes: bytes, hints: list[str], token: str) -> dict | None:
         """Call the public plant.id HF Space via the Inference API.
 
         The space used is: 'hf-vision/plant-identification' if it exists;
@@ -288,7 +278,7 @@ class PlantIdentificationService:
 
 
 def _build_parse_prompt(description: str, hints: list[str]) -> str:
-    hints_text = (f"\nAdditional context: {', '.join(hints)}" if hints else "")
+    hints_text = f"\nAdditional context: {', '.join(hints)}" if hints else ""
     return f"""You are a botanist. Based on this plant description, return a JSON object with these fields:
 - name: latin binomial (string, e.g. "Urtica dioica") or "Unknown"
 - common_name: common English name (string)

hearthnet/transport/backpressure.py

@@ -92,6 +92,7 @@ class RateCheck:
 
     def check(self, now: float | None = None) -> bool:
         import time
+
         t = now if now is not None else time.monotonic()
         cutoff = t - self._window
         self._calls = [c for c in self._calls if c > cutoff]
@@ -122,6 +123,7 @@ class RateLimiter:
 
     async def acquire(self) -> None:
         import time
+
         while True:
             async with self._lock:
                 t = time.monotonic()

hearthnet/transport/client.py

@@ -7,9 +7,9 @@ import json
 import secrets
 from collections.abc import AsyncIterator
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
-UTC = timezone.utc
+UTC = UTC
 
 try:
     import httpx
@@ -110,12 +110,15 @@ class HttpClient:
         headers = self._make_headers(payload)
         headers["Accept"] = "text/event-stream"
         try:
-            async with httpx.AsyncClient(verify=self._verify_ssl) as client, client.stream(
-                "POST",
-                f"{self._base_url}/bus/v1/call",
-                json=payload,
-                headers=headers,
-            ) as resp:
+            async with (
+                httpx.AsyncClient(verify=self._verify_ssl) as client,
+                client.stream(
+                    "POST",
+                    f"{self._base_url}/bus/v1/call",
+                    json=payload,
+                    headers=headers,
+                ) as resp,
+            ):
                 async for line in resp.aiter_lines():
                     if line.startswith("data: "):
                         with contextlib.suppress(json.JSONDecodeError):

hearthnet/transport/server.py

@@ -21,10 +21,10 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Callable
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Any
 
-UTC = timezone.utc
+UTC = UTC
 
 try:
     import uvicorn

hearthnet/transport/websocket.py

@@ -24,6 +24,10 @@ except ImportError:
     HAS_WEBSOCKETS = False
 
 # Optional FastAPI/Starlette WebSocket import (server-side)
+WebSocket: Any
+WebSocketDisconnect: Any
+WebSocketState: Any
+
 try:
     from starlette.websockets import (  # type: ignore[import]
         WebSocket,

hearthnet/types.py

@@ -46,16 +46,16 @@ class HearthNetError(Exception):
 # ── Phase 3 type aliases ─────────────────────────────────────────────────────
 
 
-ShardID = NewType("ShardID", str)           # "<model_id>:<lo>-<hi>[:tier]"
-ExpertID = NewType("ExpertID", str)         # "human:..." | "model:..." | "service:..." | "external:..."
+ShardID = NewType("ShardID", str)  # "<model_id>:<lo>-<hi>[:tier]"
+ExpertID = NewType("ExpertID", str)  # "human:..." | "model:..." | "service:..." | "external:..."
 ExpertKind = Literal["human", "model", "service", "external"]
-ClaimID = NewType("ClaimID", str)           # base32 of SHA-256 canonical claim
+ClaimID = NewType("ClaimID", str)  # base32 of SHA-256 canonical claim
 SourceID = NewType("SourceID", str)
 EvidenceLevel = Literal["unverified", "cited", "cross_referenced", "attested", "disputed"]
-RoundID = NewType("RoundID", str)           # ULID — fedlearn round
-LoraBeaconID = NewType("LoraBeaconID", str) # 8-byte hex, hardware-issued
+RoundID = NewType("RoundID", str)  # ULID — fedlearn round
+LoraBeaconID = NewType("LoraBeaconID", str)  # 8-byte hex, hardware-issued
 LoraDeviceID = NewType("LoraDeviceID", str)
-AlertID = NewType("AlertID", str)           # ULID
+AlertID = NewType("AlertID", str)  # ULID
 AlertSeverity = Literal["info", "advisory", "warning", "emergency", "extreme"]
 AckStatus = Literal["received", "acting", "need_help", "standing_down", "mistaken"]