Hugging Face's logo

Spaces:
build-small-hackathon
/
HearthNet-Nemotron
Running on Zero

App Files Community
HearthNet-Nemotron / docs /impl_ref.md
GitHub Actions
feat: Phase 2 (M14-M25, X05-X07) + Phase 3 experimental (M26-M31) + E2E tests + docs
4cd8837
preview code
|
Raw
History Blame
72.2 kB

HearthNet — Implementation Reference

Purpose: complete inventory of every file, class, method, and function across the spec set. Use this as a coding checklist. For why and behaviour → follow the spec link on each entry. For what to call it and what it returns → this document is normative.

Spec set: see 00-OVERVIEW.md, GLOSSARY.md, CAPABILITY_CONTRACT.md.

0. Conventions (read first)

0.1 Type aliases — hearthnet/types.py

Re-exported by every module that uses them. Never invent synonyms. — 00-OVERVIEW §4.1

Alias Underlying Example
NodeID str "ed25519:7H4G-Y9KL-2P3M-X8QR" (short) or full base64-url
CommunityID str full base64-url
CapabilityName str "llm.chat"
Version tuple[int, int] (1, 0)
Lamport int monotonic per community
CID str "blake3:<hex>"
EventID str ULID
TraceID str ULID
SchemaHash str "blake3:<hex>"
WallClock str "2026-05-26T08:14:22Z"
Signature str "ed25519:<base64-url-nopad>"
Topic str "marketplace.post.created"
ErrorCode Literal[...] see CONTRACT §9
TrustLevel Literal["unknown","member","trusted","anchor"]
Profile Literal["anchor","hearth","spark","bridge"]
Stability Literal["experimental","beta","stable"]
Mode Literal["online","degraded","offline"] emergency state
Category Literal["offer","request","info","emergency"] marketplace post
EventType Literal[...] 19 values; see X02 §3.1

0.2 Constants — hearthnet/constants.py

Hardcoded; never configurable. Complete list in GLOSSARY.md §Defaults.

MANIFEST_TTL_SECONDS=30, MANIFEST_REPUBLISH_INTERVAL_SECONDS=20, DISCOVERY_UDP_INTERVAL_SECONDS (5 active / 30 stable), EMERGENCY_PROBE_INTERVAL_ONLINE=10, EMERGENCY_PROBE_INTERVAL_OFFLINE=2, EMERGENCY_PROBE_TIMEOUT_SECONDS=2, EMERGENCY_TRANSITION_DEBOUNCE_SECONDS=30, CONNECTION_IDLE_SECONDS=60, RECONNECT_BACKOFF_CAP_SECONDS=30, STREAM_WINDOW_FRAMES=16, STREAM_ACK_INTERVAL_FRAMES=8, STREAM_ACK_TIMEOUT_SECONDS=5, RPC_DEFAULT_TIMEOUT_SECONDS=30, LLM_GENERATION_DEFAULT_TIMEOUT_SECONDS=120, CHUNK_SIZE_BYTES=262144, BLOB_GC_DISK_THRESHOLD=0.80, RAG_CHUNK_TOKENS=1000, RAG_CHUNK_OVERLAP_TOKENS=200, RAG_DEFAULT_K=5, RAG_MAX_K=20, HEALTH_WINDOW_CALLS=100, HEALTH_QUARANTINE_THRESHOLD=0.5, HEALTH_QUARANTINE_SECONDS=60, RATE_LIMIT_SOFT_RPS_PER_CAP=10, RATE_LIMIT_HARD_RPS_PER_CAP=100, RATE_LIMIT_SOFT_RPS_TOTAL=100, RATE_LIMIT_HARD_RPS_TOTAL=1000, EVENT_LOG_RETENTION_DAYS=30, SNAPSHOT_LAG_LAMPORT=1000, TRACE_RING_BUFFER=10000, LOG_RETENTION_DAYS=14.

0.3 Naming rules

  • Functions: snake_case, verb-first
  • Classes: PascalCase, noun
  • Constants: SCREAMING_SNAKE
  • Async I/O: async def; no async_ prefix on names
  • Protocols: PascalCase ending in capability noun (LlmBackend, Service)
  • Private: leading underscore (_compute_canonical_json)

0.4 Universal error code → wire code mapping

Domain exception Wire ErrorCode HTTP
IdentityError("invalid_signature") invalid_signature 401
IdentityError("expired") expired 410
BusError("schema_mismatch") schema_mismatch 400
BusError("not_found") not_found 404
BusError("capacity_exceeded") capacity_exceeded 429
BusError("quarantined" / "partition") partition 503
BusError("timeout") timeout 408
EventLogError("invalid_signature") invalid_signature — (internal)
BlobError("not_found") not_found 404
BlobError("hash_mismatch") bad_request 400
BlobError("disk_full") capacity_exceeded 429
OnboardingError(*) — (local UI only) —
ConfigError(*) — (startup) —

1. X04 — Configuration

Spec: cross-cutting/X04-config.md · Path: hearthnet/config.py + hearthnet/constants.py

hearthnet/config.py

Dataclasses (all @dataclass(frozen=True))

IdentityConfig — §3:

  • keys_dir: Path
  • auto_generate: bool = True

CommunityConfig — §3:

  • community_id: Optional[str] = None
  • state_dir: Path = Path()

TransportConfig — §3:

  • host: str = "0.0.0.0"
  • port: int = 7080
  • tls_cert: Optional[Path] = None
  • tls_key: Optional[Path] = None

DiscoveryConfig — §3:

  • mdns_enabled: bool = True
  • udp_enabled: bool = True
  • udp_multicast_group: str = "239.255.42.42"
  • udp_port: int = 42424
  • relay_urls: list[str] = []

BusConfig — §3:

  • prefer_local: bool = True
  • local_load_threshold: float = 0.80

LlmBackendConfig — §3:

  • name: str — one of "llama_cpp" | "ollama" | "lmstudio" | "vllm" | "hf_api" | "anthropic_api" | "nemotron" | "openbmb"
  • url: Optional[str] = None
  • model: Optional[str] = None
  • api_key_env: Optional[str] = None

LlmConfig — §3:

  • backends: list[LlmBackendConfig] = []

EmbeddingConfig — §3:

  • model: str = "BAAI/bge-small-en-v1.5"
  • device: str = "auto"

RagConfig — §3:

  • enabled: bool = True
  • corpora_dir: Path = Path()

FileConfig — §3:

  • blobs_dir: Path = Path()
  • gc_threshold: float = 0.80

MarketConfig — §3:

  • enabled: bool = True
  • default_ttl_seconds: int = 604800
  • max_ttl_seconds: int = 2592000

ChatConfig — §3:

  • enabled: bool = True
  • store_and_forward: bool = True

EmergencyConfig — §3:

  • probe_targets: list[str] = ["1.1.1.1","8.8.8.8","cloudflare.com","quad9.net"]

UiConfig — §3:

  • host: str = "127.0.0.1"
  • port: int = 7860
  • launch_browser: bool = True

ObservabilityConfig — §3 (+ trackio addition):

  • log_level: str = "info"
  • log_dir: Path = Path()
  • metrics_enabled: bool = True
  • otlp_endpoint: Optional[str] = None
  • trackio_project: Optional[str] = None — local trackio project name; enables trackio exporter when set
  • trackio_space: Optional[str] = None — HF Space URL to mirror trackio runs to; optional

Config — §3:

  • holds one of each of the above as named attributes

Functions

  • load(path: Path | None = None) -> Config — §4. Read TOML, apply defaults, resolve paths, validate. Raises ConfigError.
  • default_config() -> Config — §4. All-defaults Config.
  • save(config: Config, path: Path | None = None) -> None — §4. Atomic TOML write.
  • resolve_paths(config: Config) -> Config — §4. Resolve empty Path() to XDG locations. Idempotent.
  • validate(config: Config) -> None — §4. Cross-field checks; raises ConfigError.

Exception

ConfigError(Exception) — §4:

  • __init__(code: str, **details)
  • code: str
  • details: dict

hearthnet/constants.py

Module-level constants from GLOSSARY.md §Defaults. No classes; just NAME = value lines.

2. X03 — Observability

Spec: cross-cutting/X03-observability.md · Path: hearthnet/observability/

hearthnet/observability/logging.py — §3

Functions

  • configure(config: ObservabilityConfig) -> None — install handlers + rotation; idempotent.
  • get_logger(name: str) -> logging.Logger — JSON-formatted logger.

Class

JsonFormatter(logging.Formatter) — §3.1:

  • format(record: LogRecord) -> str — emit {"ts","level","logger","msg",**extras}.

RateLimitedLogger — §3.2 (internal wrapper):

  • __init__(logger: Logger, per_key_seconds: float = 1.0)
  • info(msg: str, key: str, **extras) -> None
  • warning(msg: str, key: str, **extras) -> None

hearthnet/observability/metrics.py — §4

Functions

  • configure(config: ObservabilityConfig) -> None — set up registries, start /metrics endpoint.
  • counter(name: str, doc: str, labels: list[str] = []) -> Counter
  • histogram(name: str, doc: str, labels: list[str] = [], buckets: list[float] | None = None) -> Histogram
  • gauge(name: str, doc: str, labels: list[str] = []) -> Gauge
  • disabled() -> bool — true when metrics are off.

Standard metric set — §4.2

Pre-registered at startup with these exact names: hearthnet_requests_total{capability,result}, hearthnet_request_duration_ms{capability,quantile}, hearthnet_active_streams{capability}, hearthnet_nodes_online{community}, hearthnet_event_log_size{community}, hearthnet_event_log_lamport_head{community}, hearthnet_emergency_mode{state}, hearthnet_blob_storage_bytes, hearthnet_llm_tokens_generated_total{model,backend}, hearthnet_llm_concurrent{model}, hearthnet_capability_health_success_rate{capability,node}, hearthnet_rate_limited_total{capability,reason}, hearthnet_signature_failures_total{reason}, hearthnet_quarantines_total.

Trackio integration (new) — §4.4

TrackioExporter — optional. Activated when config.observability.trackio_project is set.

  • __init__(project: str, space: str | None = None) — opens a trackio run.
  • record_call(capability: str, model: str | None, latency_ms: float, tokens_in: int | None, tokens_out: int | None, result: str) -> None — logs one inference call as a step in the run.
  • record_topology_snapshot(snapshot: TopologySnapshot) -> None — periodic mesh health log.
  • close() -> None

Use trackio when you want a Gradio-native dashboard for run/inference history (alternative or complement to Prometheus). Bridged into TraceHook.on_call_end when active.

hearthnet/observability/tracing.py — §5

Dataclasses

Trace — §5.1:

  • trace_id: str (ULID)
  • capability: str
  • started_at: float
  • spans: list[Span]

Span — §5.1:

  • name: str
  • started_at: float
  • ended_at: float | None
  • extras: dict

Functions

  • new_trace(capability: str) -> Trace — open a new trace, attach to current task.
  • current_trace() -> Trace | None
  • attach(trace: Trace) -> None
  • detach() -> None — close the current trace, push to ring buffer.
  • span(name: str, **extras) -> AbstractAsyncContextManager[Span] — open a sub-span.
  • get_recent(n: int = 100) -> list[Trace] — read from ring buffer (size TRACE_RING_BUFFER).

hearthnet/observability/doctor.py — §6

Dataclass

CheckResult — §6.1:

  • name: str
  • ok: bool
  • detail: str
  • fix: str | None

Functions

  • register(name: str, check: Callable[[Config, CapabilityBus], CheckResult]) -> None
  • run_all(config: Config, bus: CapabilityBus) -> list[CheckResult]
  • run_one(name: str, config: Config, bus: CapabilityBus) -> CheckResult

Standard checks (registered at startup) — §6.2

keys_present, keys_loadable, community_present, event_log_writable, mdns_socket, udp_multicast, transport_port, at_least_one_capability, disk_space, clock_sanity, llm_backend_reachable, recent_error_rate.

3. X02 — Events

Spec: cross-cutting/X02-events.md · Path: hearthnet/events/

hearthnet/events/types.py — §3.1

EventType — Literal of 19 strings, exactly: community.created, community.member.invited, community.member.joined, community.member.revoked, community.member.promoted, community.member.demoted, community.policy.updated, node.manifest.updated, market.post.created, market.post.updated, market.post.expired, chat.message.sent, chat.message.delivered, chat.message.read, file.cid.advertised, file.cid.unpinned, rag.document.ingested, federation.peer.added, federation.peer.removed.

Event (frozen dataclass):

  • schema_version: int
  • event_id: str
  • lamport: int
  • wall_clock: str
  • community_id: str
  • author: str
  • event_type: EventType
  • data: dict
  • signature: str

hearthnet/events/lamport.py — §3.2

LamportClock:

  • __init__(conn: sqlite3.Connection, community_id: str) — load current value.
  • current: int (property)
  • tick_for_send() -> int — increment + persist; returns new value.
  • observe(received_lamport: int) -> None — max(current, received) + 1.

hearthnet/events/log.py — §3.3

EventLog:

  • __init__(db_path: Path, community_id: str) — open/create SQLite (WAL); apply schema.
  • append_local(event_type: EventType, data: dict, author_kp: KeyPair) -> Event — mint, sign, persist, fan out.
  • append_received(event: Event) -> bool — verify, persist if new. Returns True if new.
  • head() -> int — highest Lamport.
  • get(event_id: str) -> Event | None
  • replay(*, since_lamport: int = 0, event_types: list[EventType] | None = None, limit: int | None = None) -> Iterator[Event]
  • heads_by_type() -> dict[EventType, int]
  • subscribe(event_types: list[EventType] | None = None) -> AsyncIterator[Event]

EventLogError(Exception):

  • code in {"invalid_signature","out_of_order","unknown_author","revoked_author","schema_unknown","db_corrupt"}

hearthnet/events/replay.py — §3.4

MaterialisedView (Protocol):

  • reset() -> None
  • apply(event: Event) -> None
  • snapshot_state() -> dict
  • restore_state(state: dict) -> None

ReplayEngine:

  • __init__(log: EventLog)
  • register(name: str, view: MaterialisedView, event_types: list[EventType]) -> None
  • rebuild(view_name: str, from_lamport: int = 0) -> None
  • rebuild_all() -> None
  • on_event(event: Event) -> None — wired from EventLog.

hearthnet/events/snapshot.py — §3.5

Snapshot (frozen dataclass):

  • schema_version: int
  • community_id: str
  • lamport: int
  • wall_clock: str
  • state: dict
  • covers_events_up_to: int
  • signature: str

SnapshotStore:

  • __init__(dir_path: Path, community_id: str)
  • latest() -> Snapshot | None
  • write(snap: Snapshot) -> None — atomic.
  • list() -> list[int]
  • prune(keep_last_n: int = 7) -> None

Free functions:

  • build_snapshot(log: EventLog, engine: ReplayEngine, signing_kp: KeyPair, at_lamport: int | None = None) -> Snapshot
  • restore_from_snapshot(snap: Snapshot, engine: ReplayEngine, log: EventLog) -> None

hearthnet/events/sync.py — §3.6

HeadsReport (frozen dataclass):

  • community_id: str
  • heads_by_type: dict[EventType, int]
  • head: int

SyncResult (frozen dataclass):

  • sent_count: int
  • received_count: int
  • duration_ms: int

SyncClient:

  • __init__(log: EventLog, transport_client: HttpClient)
  • sync_with(peer_endpoint: Endpoint) -> SyncResult (async)
  • run_round(peer_registry: PeerRegistry) -> list[SyncResult] (async) — sync against all known peers.

SyncServer:

  • __init__(log: EventLog)
  • serve_heads() -> HeadsReport (async)
  • serve_events(events: list[Event]) -> dict (async)

4. X01 — Transport

Spec: cross-cutting/X01-transport.md · Path: hearthnet/transport/

hearthnet/transport/server.py — §3

HttpServer:

  • __init__(config: TransportConfig, kp: KeyPair, bus: CapabilityBus, event_sync: SyncServer, community_manifest_provider: Callable[[], CommunityManifest])
  • app() -> FastAPI — for tests.
  • run() -> None (async) — block, serve.
  • shutdown() -> None (async)

Mounted endpoints — §3.2

POST /bus/v1/call, GET /manifest, GET /community/manifest, GET /sync/v1/heads, POST /sync/v1/events, GET /pubsub/v1/subscribe, GET /health, GET /ready, GET /metrics, GET /trace/recent.

PubSubServer — §8:

  • publish(topic: str, payload: dict) -> None (async)
  • subscribe(topic: str, *, last_seq: int = 0, timeout_seconds: float = 30) -> dict (async) — long-poll.

hearthnet/transport/client.py — §5

HttpClient:

  • __init__(kp: KeyPair, node_id: str, community_id: str, pinned_certs: PinnedCerts, timeout_default_seconds: float = RPC_DEFAULT_TIMEOUT_SECONDS)
  • call(peer: Endpoint, capability: str, version: str, body: dict, *, trace_id: str | None = None, timeout_seconds: float | None = None) -> dict (async) — signed RPC.
  • stream(peer: Endpoint, capability: str, version: str, body: dict, *, trace_id: str | None = None, cancel: asyncio.Event | None = None) -> AsyncIterator[Frame] — signed stream.
  • close() -> None (async)

CallError(Exception):

  • code: ErrorCode
  • message: str
  • retry_after_ms: int | None
  • alt_capabilities: list[str]
  • alt_nodes: list[str]

hearthnet/transport/streams.py — §6

Frame (frozen dataclass):

  • event: str — "token" | "chunk" | "progress" | "ack" | "done" | "error" | "manifest" | "ready" | "tool_call_delta"
  • data: dict
  • seq: int

SseWriter:

  • __init__(response: StreamingResponse)
  • emit(event: str, data: dict) -> None (async)
  • emit_token(token: dict) -> None (async)
  • emit_progress(current: int, total: int, stage: str) -> None (async)
  • emit_error(code: ErrorCode, **kwargs) -> None (async)
  • emit_done(**meta) -> None (async)
  • emit_ack(upto: int) -> None (async)
  • cancelled: bool (property)

SseReader:

  • __aiter__() -> AsyncIterator[Frame]
  • cancel() -> None (async)

hearthnet/transport/backpressure.py — §6.3

FlowControl:

  • __init__(window: int = STREAM_WINDOW_FRAMES, ack_interval: int = STREAM_ACK_INTERVAL_FRAMES)
  • window_used: int (property)
  • send() -> None (async) — await if window full.
  • ack(upto: int) -> None
  • needs_ack: bool (property)

hearthnet/transport/tls.py — §4

PinnedCerts:

  • __init__(db_path: Path)
  • record(node_id: str, fingerprint: bytes) -> None
  • expected(node_id: str) -> bytes | None
  • verify(node_id: str, presented: bytes) -> bool

hearthnet/transport/__init__.py — §7

RateCheck (frozen dataclass):

  • allowed: bool
  • soft_exceeded: bool
  • retry_after_ms: int

RateLimiter:

  • __init__(config: TransportConfig)
  • check(peer_node_id: str, capability: str) -> RateCheck

5. M01 — Identity & Manifests

Spec: modules/M01-identity.md · Path: hearthnet/identity/

hearthnet/identity/keys.py — §3.1

Class

KeyPair (frozen dataclass):

  • signing_key: nacl.signing.SigningKey
  • verify_key: nacl.signing.VerifyKey
  • node_id_full: str
  • node_id_short: str
  • sign(payload: dict) -> dict — returns payload + signature field.
  • sign_bytes(data: bytes) -> Signature

Functions

  • generate() -> KeyPair
  • load(keys_dir: Path) -> KeyPair — raises IdentityError("keys_missing"|"keys_invalid"|"keys_permissions").
  • load_or_generate(keys_dir: Path) -> KeyPair
  • save(kp: KeyPair, keys_dir: Path) -> None — 0600 perms.
  • short_node_id(verify_key_bytes: bytes) -> str — "ed25519:XXXX-XXXX-XXXX-XXXX".
  • full_node_id(verify_key_bytes: bytes) -> str — "ed25519:<base64-url-nopad>".
  • parse_node_id(node_id: str) -> bytes — accepts only full form.
  • verify_key_from_full(node_id_full: str) -> VerifyKey
  • canonical_json(obj: Any) -> bytes — sorted, no whitespace, no trailing zeros, UTF-8.
  • sign_payload(payload: dict, kp: KeyPair) -> dict
  • verify_payload(payload: dict, vk: VerifyKey) -> bool
  • verify_payload_with_node_id(payload: dict, expected_node_id_full: str) -> bool
  • generate_self_signed_cert(kp: KeyPair, host: str = "0.0.0.0") -> tuple[bytes, bytes] — (cert_pem, key_pem), 10-year validity.

Exception

IdentityError(Exception):

  • code in {"keys_missing","keys_invalid","keys_permissions","bad_node_id","sign_failed","verify_failed","bad_manifest","expired","invalid_signature"}

hearthnet/identity/manifest.py — §3.2

Dataclasses

Endpoint (frozen): transport: str, host: str, port: int.

HardwareSpec (frozen): gpu: str | None, vram_gb: float, ram_gb: float, cpu_cores: int, disk_free_gb: float.

CapabilitySpec (frozen) — subset of CapabilityDescriptor for manifest embedding:

  • name: str, version: str, stability: str, schema_hash: str, params: dict, max_concurrent: int.

NodeManifest (frozen):

  • version: int, contract_version: str, node_id: str, display_name: str, community_id: str, profile: str, endpoints: list[Endpoint], hardware: HardwareSpec, capabilities: list[CapabilitySpec], uptime_seconds: int, load: dict, issued_at: str, expires_at: str, signature: str.
  • as_dict() -> dict
  • is_expired(now: datetime | None = None) -> bool

CommunityPolicy (frozen):

  • min_signatures_to_invite: int
  • min_signatures_to_demote: int
  • min_signatures_to_revoke: int
  • capability_token_ttl_seconds: int
  • federation_enabled: bool
  • default_member_can_invite: bool

CommunityMember (frozen): node_id: str, level: TrustLevel, added_at: str, added_by: str.

RevokedEntry (frozen): node_id: str, revoked_at: str.

CommunityManifest (frozen):

  • version: int, community_id: str, name: str, root_key: str, created_at: str, lamport_at_creation: int, policy: CommunityPolicy, members: list[CommunityMember], revoked: list[RevokedEntry], head_lamport: int, signature: str.
  • is_member(node_id: str) -> bool
  • level_of(node_id: str) -> TrustLevel | None
  • is_revoked(node_id: str) -> bool

Functions

  • build_node_manifest(kp: KeyPair, community_id: str, display_name: str, profile: str, endpoints: list[Endpoint], hardware: HardwareSpec, capabilities: list[CapabilitySpec], uptime_seconds: int, load: dict) -> NodeManifest
  • parse_node_manifest(blob: bytes | dict) -> NodeManifest
  • verify_node_manifest(manifest: NodeManifest, *, now: datetime | None = None) -> None
  • build_community_manifest(root_kp: KeyPair, name: str, policy: CommunityPolicy) -> CommunityManifest
  • regenerate_community_manifest_from_state(materialised_state: dict, signing_kp: KeyPair) -> CommunityManifest
  • parse_community_manifest(blob: bytes | dict) -> CommunityManifest
  • verify_community_manifest(cm: CommunityManifest) -> None
  • load_or_regenerate(state_dir: Path, signing_kp: KeyPair | None = None) -> CommunityManifest — convenience used by node.py.

hearthnet/identity/tokens.py — §3.3 (Phase 2; stub in MVP)

CapabilityToken (frozen): issuer: str, subject: str, capability: str, issued_at: str, expires_at: str, nonce: str, signature: str.

Functions (stubs):

  • issue_token(issuer_kp: KeyPair, subject_node_id: str, capability: str, ttl_seconds: int = 86400) -> CapabilityToken
  • verify_token(token: CapabilityToken, expected_issuer: str) -> None

6. M02 — Discovery

Spec: modules/M02-discovery.md · Path: hearthnet/discovery/

hearthnet/discovery/peers.py — §3.1

PeerRecord (dataclass):

  • node_id: str (short), node_id_full: str, display_name: str, community_id: str, profile: Profile, endpoints: list[Endpoint], manifest: NodeManifest | None, last_seen: float, rtt_ms: float | None, source: str ("mdns"|"udp"|"relay").

PeerEvent (frozen): kind: str ("added"|"removed"|"updated"), peer: PeerRecord.

PeerRegistry:

  • __init__(our_node_id_full: str, community_id: str)
  • upsert(record: PeerRecord) -> bool — True if new.
  • remove(node_id_full: str) -> bool
  • get(node_id_full: str) -> PeerRecord | None
  • all() -> list[PeerRecord]
  • for_community(community_id: str) -> list[PeerRecord]
  • prune_stale(max_age_seconds: int = 90) -> int
  • subscribe() -> AsyncIterator[PeerEvent]
  • set_pruning_aggressive(enabled: bool) -> None — toggled by M09; uses 30s when on, 90s when off.

hearthnet/discovery/mdns.py — §3.2

MdnsAnnouncer:

  • __init__(kp: KeyPair, node_id_short: str, display_name: str, community_id_short: str, profile: Profile, port: int, capabilities_names: list[str], manifest_url: str)
  • start() -> None (async)
  • stop() -> None (async)
  • update(*, capabilities_names: list[str] | None = None) -> None

MdnsBrowser:

  • __init__(registry: PeerRegistry, our_community_id: str)
  • start() -> None (async)
  • stop() -> None (async)

hearthnet/discovery/udp.py — §3.4

UdpAnnouncer:

  • __init__(kp: KeyPair, registry: PeerRegistry, node_id_short: str, community_id_short: str, port: int, capabilities_names: list[str], multicast_group: str = "239.255.42.42", multicast_port: int = 42424)
  • run() -> None (async)

UdpListener:

  • __init__(registry: PeerRegistry, our_community_id: str)
  • run() -> None (async)

hearthnet/discovery/relay.py (Phase 2 stub)

InternetRelayClient — not implemented in MVP. Reserved.

Exception

DiscoveryError(Exception):

  • code in {"socket_in_use","mdns_unavailable","manifest_fetch_failed","manifest_invalid"}

7. M03 — Capability Bus

Spec: modules/M03-bus.md · Path: hearthnet/bus/

hearthnet/bus/capability.py — §3.1

CapabilityDescriptor (frozen dataclass):

  • name: CapabilityName, version: Version, stability: Stability, request_schema: dict, response_schema: dict | None, stream_schema: dict | None, params: dict, max_concurrent: int, trust_required: str ("member"|"trusted"|"anchor"|"self"), timeout_seconds: int, idempotent: bool.
  • version_str -> str (property)
  • schema_hash() -> str — BLAKE3 of canonical-JSON of {name, version, request_schema, response_schema, stream_schema}.

CapabilityEntry (dataclass):

  • node_id: str, descriptor: CapabilityDescriptor, is_local: bool, handler: Callable | None, endpoint: Endpoint | None, in_flight: int, last_seen: float, p50_latency_ms: float, p99_latency_ms: float, success_rate: float, quarantined_until: float, sticky_sessions: set[str].

RouteRequest (frozen dataclass):

  • capability: CapabilityName, version_req: Version, body: dict, caller: str, trace_id: str, session_id: str | None, deadline_ms: int, stream: bool.

ParamsPredicate — type alias: Callable[[dict, dict], bool].

hearthnet/bus/registry.py — §3.2

Diff (frozen dataclass): added, removed, updated — each list[CapabilityEntry].

RegistryEvent (frozen dataclass): kind: str ("added"|"removed"|"updated"), entry: CapabilityEntry.

Registry:

  • __init__(our_node_id: str)
  • register_local(descriptor: CapabilityDescriptor, handler: Callable, params_compatible: ParamsPredicate | None = None) -> None
  • deregister_local(name: CapabilityName, version: Version) -> None
  • update_from_peer_manifest(peer: PeerRecord, manifest: NodeManifest) -> Diff
  • remove_peer(node_id: str) -> int
  • find(name: CapabilityName, version_req: Version, params_filter: Callable[[dict], bool] | None = None) -> list[CapabilityEntry]
  • entry(node_id: str, name: CapabilityName, version: Version) -> CapabilityEntry | None
  • all_local() -> list[CapabilityEntry]
  • all() -> list[CapabilityEntry]
  • subscribe() -> AsyncIterator[RegistryEvent]

hearthnet/bus/health.py — §3.3

HealthTracker:

  • __init__(window: int = HEALTH_WINDOW_CALLS)
  • record(entry: CapabilityEntry, *, success: bool, latency_ms: float) -> None
  • is_quarantined(entry: CapabilityEntry) -> bool
  • reset(entry: CapabilityEntry) -> None

hearthnet/bus/schema.py — §3.4

SchemaValidator:

  • __init__()
  • validate_request(descriptor: CapabilityDescriptor, body: dict) -> None
  • validate_response(descriptor: CapabilityDescriptor, body: dict) -> None
  • validate_stream_frame(descriptor: CapabilityDescriptor, frame: dict) -> None

Free function:

  • compute_schema_hash(descriptor_partial: dict) -> str — "blake3:<hex>". See CONTRACT §11.

hearthnet/bus/router.py — §3.5

Router:

  • __init__(registry: Registry, config: BusConfig, our_node_id: str)
  • route(req: RouteRequest) -> CapabilityEntry | None — scoring algorithm; see §5.4.
  • route_sticky(req: RouteRequest) -> CapabilityEntry | None
  • release_session(session_id: str) -> None

hearthnet/bus/trace.py — §3.6

CallTraceEvent (frozen dataclass):

  • ts: str, trace_id: str, capability: CapabilityName, version: str, from_node: str, to_node: str, is_local: bool, result: str, ms: float, tokens_in: int | None, tokens_out: int | None, bytes_in: int, bytes_out: int.

TraceHook:

  • __init__()
  • on_call_start(req: RouteRequest, entry: CapabilityEntry) -> None
  • on_call_end(req: RouteRequest, entry: CapabilityEntry, *, result: str, latency_ms: float, bytes_in: int, bytes_out: int, tokens_in: int | None = None, tokens_out: int | None = None) -> None

hearthnet/bus/__init__.py — §3.7

TopologySnapshot (frozen dataclass):

  • our_node_id: str, peers: list[PeerRecord], capabilities_local: list[CapabilityEntry], capabilities_remote: list[CapabilityEntry], in_flight_total: int.

CapabilityBus:

  • __init__(node_id_full: str, community_id: str, config: BusConfig, transport_client: HttpClient, community_manifest_provider: Callable[[], CommunityManifest])
  • attributes: registry, health, schema, router, trace
  • register_service(service: Service) -> None
  • register_capability(descriptor: CapabilityDescriptor, handler: Callable, params_compatible: ParamsPredicate | None = None) -> None
  • handle_call(req: RouteRequest) -> dict | AsyncIterator[dict] (async)
  • call(capability: CapabilityName, version_req: Version, body: dict, *, session_id: str | None = None, timeout_seconds: float | None = None) -> dict (async)
  • stream(capability: CapabilityName, version_req: Version, body: dict, *, session_id: str | None = None) -> AsyncIterator[Frame]
  • on_peer_added(peer: PeerRecord) -> None
  • on_peer_updated(peer: PeerRecord) -> None
  • on_peer_removed(node_id: str) -> None
  • topology_snapshot() -> TopologySnapshot
  • recent_traces(n: int = 50) -> list[CallTraceEvent]
  • stats() -> dict

BusError(Exception):

  • code in {"schema_invalid","namespace_violation","schema_mismatch","not_found","capacity_exceeded","quarantined","partition","timeout","internal_error"}

hearthnet/services/base.py — M03 §4

Service (Protocol):

  • name: str
  • version: str
  • capabilities() -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]
  • start() -> None (async)
  • stop() -> None (async)
  • health() -> dict

8. M11 — Embedding Service

Spec: modules/M11-embedding.md · Path: hearthnet/services/embedding/

hearthnet/services/embedding/backends.py — §3.1

EmbeddingBackend (Protocol):

  • attrs: name: str, model: str, dim: int, max_input: int
  • embed(texts: list[str], *, normalize: bool = True) -> list[list[float]] (async)
  • warm() -> None (async)
  • close() -> None (async)
  • health() -> dict

SentenceTransformerBackend:

  • __init__(model: str, device: str = "auto") — device ∈ {"auto","cpu","cuda"}.
  • all EmbeddingBackend methods.

hearthnet/services/embedding/service.py — §3.2

EmbeddingService (implements Service):

  • name = "embedding", version = "1.0"
  • __init__(config: EmbeddingConfig)
  • capabilities() -> [...] — registers embed.text@1.0.
  • start(), stop(), health() (async)
  • handle_embed_text(req: RouteRequest) -> dict (async) — implements CONTRACT §4.3.

Capability params predicate 

def params_compatible(offered: dict, requested: dict) -> bool:
    return requested.get("model") == offered.get("model")

9. M04 — LLM Service

Spec: modules/M04-llm.md · Path: hearthnet/services/llm/

hearthnet/services/llm/backends/base.py — §3.1

Token (frozen dataclass): text: str, logprob: float | None, stop: bool.

ChatResult (frozen dataclass): text: str, tokens_in: int, tokens_out: int, stop_reason: str, ms: int.

BackendModel (frozen dataclass): name: str, quant: str, ctx_max: int, modalities: list[str], requires_internet: bool.

LlmBackend (Protocol):

  • attrs: name: str, models: list[BackendModel]
  • warm(model: str) -> None (async)
  • close() -> None (async)
  • chat(*, model: str, messages: list[dict], max_tokens: int = 1024, temperature: float = 0.7, top_p: float = 0.95, stop: list[str] | None = None, seed: int | None = None, stream: bool = True) -> AsyncIterator[Token]
  • complete(*, model: str, prompt: str, max_tokens: int = 256, temperature: float = 0.7, top_p: float = 0.95, stop: list[str] | None = None, seed: int | None = None, stream: bool = True) -> AsyncIterator[Token]
  • count_tokens(model: str, text: str) -> int
  • max_concurrent(model: str) -> int
  • health() -> dict

Concrete backends — §3.2

Each implements LlmBackend. Same method set; only constructor varies.

File Class Constructor signature
backends/llama_cpp.py LlamaCppBackend __init__(model_path: Path, model_meta: BackendModel, gpu_layers: int = -1)
backends/ollama.py OllamaBackend `init(base_url: str = "http://localhost:11434", models: list[str]
backends/lmstudio.py LmStudioBackend __init__(base_url: str, default_model: str) — OpenAI-compatible HTTP
backends/hf_api.py HfApiBackend __init__(model: str, token_env: str = "HF_TOKEN") — requires_internet=True
backends/anthropic_api.py AnthropicApiBackend __init__(model: str = "claude-sonnet-4-6", token_env: str = "ANTHROPIC_API_KEY") — requires_internet=True
backends/nemotron.py (new) NemotronBackend __init__(base_url: str = "https://integrate.api.nvidia.com/v1", model: str = "nvidia/llama-3.1-nemotron-70b-instruct", token_env: str = "NVIDIA_API_KEY", local: bool = False) — OpenAI-compatible; requires_internet=True unless local=True (locally-hosted NIM endpoint)
backends/openbmb.py (new) OpenBmbBackend `init(base_url: str = "http://localhost:8000", model: str = "openbmb/MiniCPM4-8B", token_env: str

All backends declare their models: list[BackendModel] so the service can enumerate (backend, model) pairs at registration time.

hearthnet/services/llm/tokenizers.py — §3.3

  • count_tokens_approx(model_family: str, text: str) -> int
  • model_family(model_name: str) -> str — e.g. "qwen2.5-7b-instruct" → "qwen", "nemotron-70b" → "nemotron", "MiniCPM4-8B" → "minicpm".

hearthnet/services/llm/service.py — §3.4

LlmService (implements Service):

  • name = "llm", version = "1.0"
  • __init__(config: LlmConfig)
  • _build_backends(config: LlmConfig) -> list[LlmBackend]
  • capabilities() -> [...] — emits one descriptor per (backend, model) × {llm.chat, llm.complete}.
  • start(), stop(), health() (async)
  • handle_chat(req: RouteRequest) -> AsyncIterator[dict] (async) — implements CONTRACT §4.1.
  • handle_complete(req: RouteRequest) -> AsyncIterator[dict] (async) — implements CONTRACT §4.2.

Capability params predicate — §3.6 

def params_compatible(offered: dict, requested: dict) -> bool:
    if requested.get("model") != offered.get("model"):
        return False
    if "ctx" in requested and requested["ctx"] > offered["ctx"]:
        return False
    return True

10. M05 — RAG Service

Spec: modules/M05-rag.md · Path: hearthnet/services/rag/

hearthnet/services/rag/chunker.py — §3.1

Chunk (frozen dataclass): text: str, metadata: dict.

Functions:

  • chunk_text(text: str, *, tokens_per_chunk: int = RAG_CHUNK_TOKENS, overlap_tokens: int = RAG_CHUNK_OVERLAP_TOKENS, metadata: dict | None = None) -> list[Chunk]
  • chunk_pdf(pdf_bytes: bytes, *, doc_metadata: dict) -> list[Chunk]

hearthnet/services/rag/store.py — §3.2

ScoredChunk (frozen dataclass): chunk: Chunk, score: float.

CorpusStore:

  • __init__(corpora_dir: Path, corpus: str, embedding_dim: int)
  • add_chunks(chunks: list[Chunk], embeddings: list[list[float]]) -> None
  • has_document(doc_cid: str) -> bool
  • query(embedding: list[float], *, k: int, filter: dict | None = None) -> list[ScoredChunk]
  • count() -> int
  • size_bytes() -> int
  • language_majority() -> str | None

Free functions:

  • list_corpora(corpora_dir: Path) -> list[str]
  • corpus_info(corpora_dir: Path, corpus: str) -> dict

hearthnet/services/rag/ingest.py — §3.3

IngestResult (frozen dataclass): doc_cid: str, chunks_indexed: int, tokens_indexed: int, ingest_event_id: str, ms: int.

IngestPipeline:

  • __init__(bus: CapabilityBus, blob_store: BlobStore, corpora_dir: Path, event_log: EventLog)
  • ingest_document(doc_cid: str, corpus: str, title: str, language: str, metadata: dict, author_kp: KeyPair) -> IngestResult (async)

hearthnet/services/rag/service.py — §3.4

RagService (implements Service):

  • name = "rag", version = "1.0"
  • __init__(config: RagConfig, bus: CapabilityBus, blob_store: BlobStore, event_log: EventLog, community_manifest_provider: Callable[[], CommunityManifest])
  • capabilities() -> [...] — rag.query@1.0 per corpus, rag.ingest@1.0 once, rag.list_corpora@1.0 once.
  • start(), stop(), health() (async)
  • handle_query(req: RouteRequest) -> dict (async) — CONTRACT §4.4.
  • handle_ingest(req: RouteRequest) -> dict (async) — CONTRACT §4.5.
  • handle_list_corpora(req: RouteRequest) -> dict (async) — CONTRACT §4.6.

Capability params predicate — §3.5 

def query_params_compatible(offered: dict, requested: dict) -> bool:
    return requested.get("corpus") == offered.get("corpus")

11. M07 — File & Blobs

Spec: modules/M07-file-blobs.md · Paths: hearthnet/blobs/ + hearthnet/services/file/

hearthnet/blobs/chunker.py — §3.1

ChunkRef (frozen): index: int, cid: str, size_bytes: int.

BlobManifest (frozen): cid: str, size_bytes: int, chunk_size_bytes: int, chunks: list[ChunkRef], mime_type: str | None, filename: str | None.

Functions:

  • hash_bytes(data: bytes) -> str — "blake3:<hex>".
  • chunk_blob(data: bytes, *, chunk_size: int = CHUNK_SIZE_BYTES) -> tuple[BlobManifest, list[bytes]]
  • manifest_cid(manifest: BlobManifest) -> str
  • reassemble(chunks: list[bytes]) -> bytes
  • verify_chunk(data: bytes, expected_cid: str) -> None — raises BlobError("hash_mismatch").

hearthnet/blobs/store.py — §3.2

BlobStore:

  • __init__(dir_path: Path, gc_threshold: float = BLOB_GC_DISK_THRESHOLD)
  • has(cid: str) -> bool
  • read_chunk(cid: str) -> bytes
  • write_chunk(cid: str, data: bytes) -> None
  • delete_chunk(cid: str) -> bool
  • has_blob(manifest_cid: str) -> bool
  • read_manifest(manifest_cid: str) -> BlobManifest
  • write_blob(manifest: BlobManifest, chunks: list[bytes]) -> None
  • read_blob_bytes(manifest_cid: str) -> bytes
  • read_blob_stream(manifest_cid: str) -> AsyncIterator[tuple[ChunkRef, bytes]] (async)
  • list_cids(prefix: str | None = None) -> list[str]
  • total_bytes() -> int
  • pin(cid: str) -> None
  • unpin(cid: str) -> None
  • is_pinned(cid: str) -> bool
  • gc(target_fraction: float = 0.7) -> int — bytes freed.

BlobError(Exception):

  • code in {"not_found","hash_mismatch","io_error","disk_full","manifest_invalid"}

hearthnet/blobs/transfer.py — §3.3

TransferManager:

  • __init__(store: BlobStore, bus: CapabilityBus, concurrency: int = 4)
  • fetch_blob(manifest_cid: str, *, sources: list[str] | None = None) -> BlobManifest (async)
  • advertise(cids: list[str]) -> None (async)

hearthnet/services/file/service.py — §4.1

FileService (implements Service):

  • name = "file", version = "1.0"
  • __init__(config: FileConfig, store: BlobStore, event_log: EventLog)
  • capabilities() -> [...] — file.read, file.list, file.advertise, file.put (all @1.0).
  • start(), stop(), health() (async)
  • handle_read(req: RouteRequest) -> AsyncIterator[dict] | dict (async) — CONTRACT §4.7.
  • handle_list(req: RouteRequest) -> dict (async) — CONTRACT §4.8.
  • handle_advertise(req: RouteRequest) -> dict (async) — CONTRACT §4.9.
  • handle_put(req: RouteRequest) -> AsyncIterator[dict] (async) — CONTRACT §4.10.

All four file.* use default lambda offered, requested: True as params predicate.

12. M06 — Marketplace Service

Spec: modules/M06-marketplace.md · Path: hearthnet/services/marketplace/

hearthnet/services/marketplace/post.py — §3.1

Location (frozen dataclass): lat: float, lng: float, label: str.

Post (frozen dataclass):

  • event_id: str, lamport: int, author: str, category: Category, title: str, body: str, location: Location | None, tags: list[str], created_at: str, expires_at: str, expired_via_event_id: str | None, expiry_reason: str | None.
  • is_expired(now: datetime | None = None) -> bool

hearthnet/services/marketplace/views.py — §3.2

MarketplaceView (implements MaterialisedView from X02):

  • __init__()
  • reset() -> None
  • apply(event: Event) -> None
  • snapshot_state() -> dict
  • restore_state(state: dict) -> None
  • list(*, category: Category | None = None, tags: list[str] | None = None, since_lamport: int = 0, limit: int = 50) -> list[Post]
  • get(event_id: str) -> Post | None
  • max_lamport() -> int
  • all_active() -> list[Post]

hearthnet/services/marketplace/service.py — §3.3

MarketplaceService (implements Service):

  • name = "marketplace", version = "1.0"
  • __init__(config: MarketConfig, bus: CapabilityBus, event_log: EventLog, replay_engine: ReplayEngine, author_kp: KeyPair, community_manifest_provider: Callable[[], CommunityManifest])
  • capabilities() -> [...] — market.list, market.post, market.expire, market.search (all @1.0).
  • start(), stop(), health() (async) — start replays events and installs auto-expiry sweeper.
  • handle_list(req) -> dict (async) — CONTRACT §4.11.
  • handle_post(req) -> dict (async) — CONTRACT §4.12.
  • handle_expire(req) -> dict (async) — CONTRACT §4.13.
  • handle_search(req) -> dict (async) — CONTRACT §4.14.
  • _auto_expire_sweep() -> None (async) — internal background task.

All four use default lambda offered, requested: True predicate.

13. M10 — Chat Service

Spec: modules/M10-chat.md · Path: hearthnet/services/chat/

hearthnet/services/chat/views.py — §3.1

ChatMessage (frozen dataclass):

  • event_id: str, lamport: int, sender: str, recipient: str, body: str, attachments: list[dict], created_at: str, delivered_at: str | None, read_at: str | None.

ChatView (implements MaterialisedView):

  • __init__(our_node_id_full: str)
  • reset(), apply(event), snapshot_state(), restore_state(state)
  • history_with(peer: str | None = None, *, since_lamport: int = 0, limit: int = 200) -> list[ChatMessage]
  • peers() -> list[str]
  • unread_count(peer: str) -> int

hearthnet/services/chat/delivery.py — §3.2

DeliveryManager:

  • __init__(bus: CapabilityBus, event_log: EventLog, author_kp: KeyPair, peer_registry: PeerRegistry, config: ChatConfig)
  • deliver(message_event: Event) -> str (async) — returns "direct"|"forwarded"|"queued".
  • on_local_message_arrived(message_event: Event) -> None (async)
  • on_pubsub_message(payload: dict) -> None (async)

hearthnet/services/chat/service.py — §3.3

ChatService (implements Service):

  • name = "chat", version = "1.0"
  • __init__(config: ChatConfig, bus: CapabilityBus, event_log: EventLog, replay_engine: ReplayEngine, peer_registry: PeerRegistry, author_kp: KeyPair, our_node_id_full: str)
  • capabilities() -> [...] — chat.send@1.0 (member trust), chat.history@1.0 (self trust).
  • start(), stop(), health() (async)
  • handle_send(req) -> dict (async) — CONTRACT §4.15.
  • handle_history(req) -> dict (async) — CONTRACT §4.16. Enforces caller == our_node_id_full.

14. M09 — Emergency Mode Detector

Spec: modules/M09-emergency.md · Path: hearthnet/emergency/

hearthnet/emergency/state.py — §3.1

EmergencyState (frozen dataclass):

  • mode: Mode, since: WallClock, last_probe: WallClock, probe_results: dict[str, bool].

StateBus:

  • __init__()
  • current() -> EmergencyState
  • subscribe() -> AsyncIterator[EmergencyState]
  • _emit(state: EmergencyState) -> None (internal)

hearthnet/emergency/detector.py — §3.2

Detector:

  • __init__(config: EmergencyConfig, bus: CapabilityBus, state_bus: StateBus)
  • run() -> None (async)
  • shutdown() -> None (async)
  • _probe_dns(host: str) -> bool (async, internal)
  • _probe_http(url: str) -> bool (async, internal)

State-transition effects (§5.2):

  • entering offline → deregister local capabilities whose descriptor params.requires_internet == True
  • entering online → re-register those backends
  • offline ↔ online → flip peer_registry.set_pruning_aggressive(...) (M02)

15. M08 — UI

Spec: modules/M08-ui.md · Path: hearthnet/ui/

hearthnet/ui/app.py — §3.1

UiApp:

  • __init__(bus: CapabilityBus, state_bus: StateBus, config: UiConfig, node_id_short: str, community_name: str)
  • build() -> gr.Blocks
  • launch_async() -> None (async)
  • shutdown() -> None (async)

Free function:

  • build_ui(bus: CapabilityBus, state_bus: StateBus, config: UiConfig, **meta) -> UiApp

hearthnet/ui/topology.py — §3.2

TopologyComponent:

  • __init__(bus: CapabilityBus)
  • render() -> gr.HTML
  • push_trace(event: CallTraceEvent) -> None
  • push_topology(snapshot: TopologySnapshot) -> None

hearthnet/ui/theme.py — §7

  • hearthnet_theme: gr.Theme (module-level constant)
  • emergency_theme: gr.Theme (module-level constant)
  • CSS variables documented in spec §7

hearthnet/ui/tabs/

Each file exports a builder function returning a gr.Tab or gr.Blocks fragment.

File Function Spec
tabs/ask.py build_ask_tab(bus: CapabilityBus) -> gr.Tab §5.1
tabs/chat.py build_chat_tab(bus: CapabilityBus, our_node_id_full: str) -> gr.Tab §5.3
tabs/marketplace.py build_marketplace_tab(bus: CapabilityBus) -> gr.Tab §5.4
tabs/files.py build_files_tab(bus: CapabilityBus) -> gr.Tab §5.5
tabs/emergency.py build_emergency_tab(bus: CapabilityBus, state_bus: StateBus) -> gr.Tab §5.6
tabs/settings.py build_settings_tab(bus: CapabilityBus, config: Config) -> gr.Tab §5.2

hearthnet/ui/mobile/ — §6

Static assets served at /mobile/* by X01:

  • index.html — single-page app
  • app.js — same bus API; uses signed requests via WebCrypto
  • style.css

16. M13 — Onboarding

Spec: modules/M13-onboarding.md · Path: hearthnet/ui/onboarding.py

hearthnet/ui/onboarding.py — §3.1

InviteBlob (frozen dataclass):

  • schema_version: int, community_id: str, community_name: str, inviter_node_id: str, invitee_node_id: str, initial_level: str, bootstrap_endpoints: list[Endpoint], expires_at: str, signature: str.

Functions

  • encode_invite(blob: InviteBlob) -> str — "hearthnet://v1/<base64>".
  • decode_invite(text: str) -> InviteBlob
  • invite_to_qr_png(blob: InviteBlob, *, box_size: int = 8) -> bytes
  • create_community(name: str, policy: CommunityPolicy, kp: KeyPair, state_dir: Path, event_log: EventLog) -> CommunityManifest
  • make_invite(invitee_node_id_full: str, inviter_kp: KeyPair, community_manifest: CommunityManifest, bootstrap_endpoints: list[Endpoint], initial_level: str = "member", ttl_seconds: int = 86400) -> InviteBlob
  • redeem_invite(blob: InviteBlob, our_kp: KeyPair, transport_client: HttpClient, event_log: EventLog) -> CommunityManifest (async)
  • build_onboarding(config: Config, kp_provider: Callable[[], KeyPair]) -> gr.Blocks

Exception: OnboardingError(Exception):

  • code in {"invite_invalid","invite_expired","invitee_mismatch","bootstrap_unreachable","community_manifest_invalid","sync_failed","already_member"}

17. M12 — CLI & Orchestrator

Spec: modules/M12-cli.md · Paths: hearthnet/cli.py + hearthnet/node.py

hearthnet/cli.py — §3

Click group + subcommands. Each is a top-level function decorated with @main.command().

Command Function Spec
(root) main(ctx, config) §4
init init(name: str, profile: str, non_interactive: bool) §3.1
run run(config: str, no_ui: bool, debug: bool) §3.2
status status(json_output: bool) §3.3
caps caps(remote_only: bool, local_only: bool, name: str) §3.4
call call(name_at_version: str, body: str, stream: bool) §3.5
log log(follow: bool, level: str, component: str) §3.6
trace trace_recent(n: int, capability: str) §3.7
doctor doctor(check: str) §3.8
export export(out: str) §3.9
erase erase(keep_keys: bool, yes: bool) §3.10
rag list rag_list() §3.11
rag ingest rag_ingest(path: str, corpus: str) §3.11
rag reindex rag_reindex(corpus: str, embedding_model: str) §3.11
invite create invite_create(node_id: str, level: str, ttl: int) §3.12
invite redeem invite_redeem(text_or_path: str) §3.12
version version_cmd() §3.13

Exit codes — §6: 0 success, 1 generic error, 2 user abort / bad usage, 3 no running node, 4 auth, 5 capacity.

hearthnet/node.py — §5

Single function — the canonical wiring:

async def start(config: Config) -> None:
    """The 15-step composition. Do not deviate."""

Sequence (each numbered in spec §5):

  1. observability configure
  2. identity load_or_generate
  3. community check / onboarding redirect
  4. event log + snapshot store + replay engine + community manifest
  5. blob store
  6. pinned-certs + transport client + bus
  7. peer registry + mdns/udp announcer + listener
  8. instantiate services (Embedding, Llm, Rag, File, Marketplace, Chat) and register with bus
  9. state bus + Detector
  10. http server
  11. UI app
  12. wire peer events → bus
  13. ManifestPublisher
  14. SyncClient periodic loop
  15. asyncio.gather(...) — block until shutdown

Auxiliary class declared inline in this module:

ManifestPublisher:

  • __init__(kp: KeyPair, community_manifest_provider: Callable, bus: CapabilityBus, peer_registry: PeerRegistry, interval_seconds: int = MANIFEST_REPUBLISH_INTERVAL_SECONDS)
  • run() -> None (async)
  • Publishes the freshly-built node manifest to mDNS + UDP every interval_seconds. Triggered also on bus.registry change events (capability added/removed).

PeriodicTask (helper):

  • __init__(fn: Callable[[], Awaitable], interval_seconds: int)
  • run() -> None (async)

hearthnet/__main__.py

Single line: from hearthnet.cli import main; main()

18. Cross-module symbol index (alphabetical)

For "where is X declared?"

Symbol Module File
AnthropicApiBackend M04 services/llm/backends/anthropic_api.py
BackendModel M04 services/llm/backends/base.py
BlobError M07 blobs/store.py
BlobManifest M07 blobs/chunker.py
BlobStore M07 blobs/store.py
BusConfig X04 config.py
BusError M03 bus/__init__.py
CallError X01 transport/client.py
CallTraceEvent M03 bus/trace.py
CapabilityBus M03 bus/__init__.py
CapabilityDescriptor M03 bus/capability.py
CapabilityEntry M03 bus/capability.py
CapabilitySpec M01 identity/manifest.py
CapabilityToken M01 identity/tokens.py
Category M06 services/marketplace/post.py (Literal alias)
ChatConfig X04 config.py
ChatMessage M10 services/chat/views.py
ChatService M10 services/chat/service.py
ChatView M10 services/chat/views.py
CheckResult X03 observability/doctor.py
Chunk M05 services/rag/chunker.py
ChunkRef M07 blobs/chunker.py
CommunityConfig X04 config.py
CommunityManifest M01 identity/manifest.py
CommunityMember M01 identity/manifest.py
CommunityPolicy M01 identity/manifest.py
Config X04 config.py
ConfigError X04 config.py
CorpusStore M05 services/rag/store.py
DeliveryManager M10 services/chat/delivery.py
Detector M09 emergency/detector.py
Diff M03 bus/registry.py
DiscoveryConfig X04 config.py
DiscoveryError M02 discovery/__init__.py
EmbeddingBackend M11 services/embedding/backends.py
EmbeddingConfig X04 config.py
EmbeddingService M11 services/embedding/service.py
EmergencyConfig X04 config.py
EmergencyState M09 emergency/state.py
Endpoint M01 identity/manifest.py
Event X02 events/types.py
EventLog X02 events/log.py
EventLogError X02 events/log.py
EventType X02 events/types.py
FileConfig X04 config.py
FileService M07 services/file/service.py
FlowControl X01 transport/backpressure.py
Frame X01 transport/streams.py
HardwareSpec M01 identity/manifest.py
HeadsReport X02 events/sync.py
HealthTracker M03 bus/health.py
HfApiBackend M04 services/llm/backends/hf_api.py
HttpClient X01 transport/client.py
HttpServer X01 transport/server.py
IdentityConfig X04 config.py
IdentityError M01 identity/keys.py
IngestPipeline M05 services/rag/ingest.py
IngestResult M05 services/rag/ingest.py
InviteBlob M13 ui/onboarding.py
JsonFormatter X03 observability/logging.py
KeyPair M01 identity/keys.py
LamportClock X02 events/lamport.py
LlamaCppBackend M04 services/llm/backends/llama_cpp.py
LlmBackend M04 services/llm/backends/base.py
LlmBackendConfig X04 config.py
LlmConfig X04 config.py
LlmService M04 services/llm/service.py
LmStudioBackend M04 services/llm/backends/lmstudio.py
Location M06 services/marketplace/post.py
ManifestPublisher M12 node.py
MarketConfig X04 config.py
MarketplaceService M06 services/marketplace/service.py
MarketplaceView M06 services/marketplace/views.py
MaterialisedView X02 events/replay.py (Protocol)
MdnsAnnouncer M02 discovery/mdns.py
MdnsBrowser M02 discovery/mdns.py
Mode M09 emergency/state.py (Literal alias)
NemotronBackend (new) M04 services/llm/backends/nemotron.py
NodeManifest M01 identity/manifest.py
ObservabilityConfig X04 config.py
OllamaBackend M04 services/llm/backends/ollama.py
OnboardingError M13 ui/onboarding.py
OpenBmbBackend (new) M04 services/llm/backends/openbmb.py
ParamsPredicate M03 bus/capability.py (type alias)
PeerEvent M02 discovery/peers.py
PeerRecord M02 discovery/peers.py
PeerRegistry M02 discovery/peers.py
PeriodicTask M12 node.py
PinnedCerts X01 transport/tls.py
Post M06 services/marketplace/post.py
Profile (types) hearthnet/types.py (Literal alias)
PubSubServer X01 transport/server.py
RagConfig X04 config.py
RagService M05 services/rag/service.py
RateCheck X01 transport/__init__.py
RateLimiter X01 transport/__init__.py
RateLimitedLogger X03 observability/logging.py
Registry M03 bus/registry.py
RegistryEvent M03 bus/registry.py
ReplayEngine X02 events/replay.py
RevokedEntry M01 identity/manifest.py
RouteRequest M03 bus/capability.py
Router M03 bus/router.py
SchemaValidator M03 bus/schema.py
ScoredChunk M05 services/rag/store.py
SentenceTransformerBackend M11 services/embedding/backends.py
Service M03 services/base.py (Protocol)
Snapshot X02 events/snapshot.py
SnapshotStore X02 events/snapshot.py
Span X03 observability/tracing.py
SseReader X01 transport/streams.py
SseWriter X01 transport/streams.py
StateBus M09 emergency/state.py
SyncClient X02 events/sync.py
SyncResult X02 events/sync.py
SyncServer X02 events/sync.py
Token M04 services/llm/backends/base.py
TopologyComponent M08 ui/topology.py
TopologySnapshot M03 bus/__init__.py
Trace X03 observability/tracing.py
TraceHook M03 bus/trace.py
TrackioExporter (new) X03 observability/metrics.py
TransferManager M07 blobs/transfer.py
TransportConfig X04 config.py
UdpAnnouncer M02 discovery/udp.py
UdpListener M02 discovery/udp.py
UiApp M08 ui/app.py
UiConfig X04 config.py

19. Capability → handler index

For each capability in CONTRACT §3.2, where the handler lives:

Capability Service Handler Trust
llm.chat@1.0 M04 LlmService handle_chat member
llm.complete@1.0 M04 LlmService handle_complete member
embed.text@1.0 M11 EmbeddingService handle_embed_text member
rag.query@1.0 M05 RagService handle_query member
rag.ingest@1.0 M05 RagService handle_ingest trusted
rag.list_corpora@1.0 M05 RagService handle_list_corpora member
file.read@1.0 M07 FileService handle_read member
file.list@1.0 M07 FileService handle_list member
file.advertise@1.0 M07 FileService handle_advertise member
file.put@1.0 M07 FileService handle_put trusted
market.list@1.0 M06 MarketplaceService handle_list member
market.post@1.0 M06 MarketplaceService handle_post member
market.expire@1.0 M06 MarketplaceService handle_expire member
market.search@1.0 M06 MarketplaceService handle_search member
chat.send@1.0 M10 ChatService handle_send member
chat.history@1.0 M10 ChatService handle_history self
community.invite@1.0 M13 (handler via bus from make_invite) n/a member with can_invite
community.revoke@1.0 M13 / M01 helper n/a 3 trusted signatures

20. Event-type → producer/consumer index

For each CONTRACT §7.2 event type:

Event type Produced by View(s) consuming
community.created M13 create_community M01 community manifest builder
community.member.invited M13 make_invite M01
community.member.joined M13 redeem_invite M01
community.member.revoked M01 helper / community.revoke handler M01
community.member.promoted / .demoted M01 helpers M01
community.policy.updated M01 (root key only) M01
node.manifest.updated M12 ManifestPublisher optional audit views
market.post.created M06 handle_post M06 MarketplaceView
market.post.updated M06 (author only) M06 MarketplaceView
market.post.expired M06 (author or sweeper) M06 MarketplaceView
chat.message.sent M10 handle_send M10 ChatView
chat.message.delivered M10 DeliveryManager M10 ChatView
chat.message.read M10 (UI) M10 ChatView
file.cid.advertised M07 TransferManager.advertise local source index in FileService
file.cid.unpinned M07 BlobStore.unpin local source index
rag.document.ingested M05 IngestPipeline M05 (replicas may pre-fetch)
federation.peer.added / .removed reserved (Phase 2) —

21. Standard params for each capability descriptor

Used by CONTRACT §6.1 node manifest embedding and by the bus's params-compatibility check.

Capability params keys
llm.chat model, quant, ctx, backend, modalities, optionally requires_internet
llm.complete same as llm.chat
embed.text model
rag.query corpus, embedding_model, k_max
rag.ingest corpora_available (list)
rag.list_corpora {}
file.read {}
file.list {}
file.advertise {}
file.put {}
market.* {}
chat.send {}
chat.history {}

22. Implementation checklist (one row per implementable unit)

Tick these off as you build. Order: dependency-correct.

X04 Config (~6 dataclasses, ~5 functions, ~1 exception)

  • IdentityConfig, CommunityConfig, TransportConfig, DiscoveryConfig, BusConfig
  • LlmBackendConfig, LlmConfig
  • EmbeddingConfig, RagConfig, FileConfig, MarketConfig, ChatConfig
  • EmergencyConfig, UiConfig, ObservabilityConfig (incl. trackio_project/trackio_space)
  • Config (aggregate)
  • load, default_config, save, resolve_paths, validate
  • ConfigError
  • constants.py with all 31 named constants

X03 Observability (~6 classes, ~14 functions)

  • configure, get_logger, JsonFormatter, RateLimitedLogger
  • configure (metrics), counter, histogram, gauge, disabled
  • All 14 standard metrics pre-registered
  • TrackioExporter (new, optional)
  • Trace, Span, new_trace, current_trace, attach, detach, span, get_recent
  • CheckResult, register, run_all, run_one
  • 12 standard checks registered

X02 Events (~7 classes, ~3 functions)

  • EventType, Event
  • LamportClock
  • EventLog, EventLogError
  • MaterialisedView (Protocol), ReplayEngine
  • Snapshot, SnapshotStore, build_snapshot, restore_from_snapshot
  • HeadsReport, SyncResult, SyncClient, SyncServer

X01 Transport (~9 classes, ~1 exception)

  • HttpServer + 10 endpoints
  • HttpClient, CallError
  • Frame, SseWriter, SseReader
  • FlowControl
  • PinnedCerts
  • RateCheck, RateLimiter
  • PubSubServer

M01 Identity (~12 classes, ~16 functions, ~1 exception)

  • KeyPair, all keys.py functions, IdentityError
  • Endpoint, HardwareSpec, CapabilitySpec, NodeManifest
  • CommunityPolicy, CommunityMember, RevokedEntry, CommunityManifest
  • All builder/parser/verifier functions
  • CapabilityToken stub

M02 Discovery (~6 classes)

  • PeerRecord, PeerEvent, PeerRegistry
  • MdnsAnnouncer, MdnsBrowser
  • UdpAnnouncer, UdpListener
  • DiscoveryError

M03 Capability Bus (~10 classes, ~1 function, ~1 exception) — CRITICAL

  • CapabilityDescriptor, CapabilityEntry, RouteRequest
  • Diff, RegistryEvent, Registry
  • HealthTracker
  • SchemaValidator, compute_schema_hash
  • Router (with scoring algorithm from M03 §5.4)
  • CallTraceEvent, TraceHook
  • TopologySnapshot, CapabilityBus (facade), BusError
  • Service Protocol in services/base.py

M11 Embedding (~3 classes)

  • EmbeddingBackend Protocol
  • SentenceTransformerBackend
  • EmbeddingService + handle_embed_text + params predicate

M04 LLM (~6 backends + 3 base classes + 2 base functions + 1 service)

  • Token, ChatResult, BackendModel, LlmBackend Protocol
  • LlamaCppBackend
  • OllamaBackend
  • LmStudioBackend
  • HfApiBackend
  • AnthropicApiBackend
  • NemotronBackend (new — NVIDIA NIM / locally-hosted)
  • OpenBmbBackend (new — MiniCPM via vLLM/llama.cpp serve/SGLang)
  • count_tokens_approx, model_family
  • LlmService + handle_chat + handle_complete + params predicate

M05 RAG (~5 classes, ~4 functions)

  • Chunk, chunk_text, chunk_pdf
  • ScoredChunk, CorpusStore, list_corpora, corpus_info
  • IngestResult, IngestPipeline
  • RagService + 3 handlers + params predicate

M07 File & Blobs (~4 classes, ~5 functions, ~1 exception)

  • ChunkRef, BlobManifest
  • All chunker.py functions
  • BlobStore, BlobError
  • TransferManager
  • FileService + 4 handlers

M06 Marketplace (~3 classes)

  • Location, Post
  • MarketplaceView
  • MarketplaceService + 4 handlers + sweeper

M10 Chat (~3 classes)

  • ChatMessage, ChatView
  • DeliveryManager
  • ChatService + 2 handlers

M09 Emergency (~3 classes)

  • EmergencyState, StateBus
  • Detector (state machine + probe loop)

M08 UI (~2 classes + ~6 tab builders + theme + mobile assets)

  • UiApp, build_ui
  • TopologyComponent
  • hearthnet_theme, emergency_theme
  • 6 tab builders
  • Mobile static assets

M13 Onboarding (~1 class, ~7 functions, ~1 exception)

  • InviteBlob
  • All onboarding functions
  • build_onboarding
  • OnboardingError

M12 CLI & Orchestrator (~17 commands + ~2 helper classes + 1 function)

  • All 17 Click subcommands
  • ManifestPublisher, PeriodicTask
  • node.start() — the 15-step composition

23. Notes on the trackio integration

Trackio is HuggingFace's local-first experiment tracker built on Gradio. Optional in HearthNet; enable by setting config.observability.trackio_project.

Integration points:

  1. Activated by config. TrackioExporter is constructed only if trackio_project is set. Otherwise the class is unused; HearthNet runs Prometheus-only.

  2. Bridged from TraceHook. M03 §3.6 TraceHook.on_call_end checks for an active exporter and forwards. No service code calls trackio directly.

  3. Optional HF Spaces sync. If trackio_space is set, runs mirror to the named Space — handy for sharing demo telemetry. Off by default; the demo on Christof's machine logs locally.

  4. What gets logged. Each LLM call is one step with: latency_ms, tokens_in, tokens_out, model, backend, result. Topology snapshots logged every 60s with mesh size, online state, capability counts. Marketplace post counts and chat throughput as gauges.

  5. Why this fits HearthNet. Trackio is local-first (matches HearthNet's ethos), Gradio-native (matches the existing UI stack), and gives Christof a dashboard he already knows how to extend without adding Prometheus + Grafana.

24. Notes on the Nemotron and OpenBMB backends

Both register exactly like existing backends: as LlmBackend implementations producing BackendModel entries that the service enumerates as (backend, model) capability instances.

NemotronBackend

NVIDIA's Nemotron family (Llama-3.1-Nemotron-70B, Nemotron-mini, Nemotron-4-340B-instruct). Two modes:

  • Cloud (default): https://integrate.api.nvidia.com/v1, OpenAI-compatible. requires_internet=True. Free tier exists; bring an NVIDIA_API_KEY. M09 will deregister this backend automatically when offline.
  • Local (local=True): point at a self-hosted NIM endpoint or vLLM-served Nemotron model. requires_internet=False.

Models declared by models: list[BackendModel] at construction time. Use these typical entries:

BackendModel("nvidia/llama-3.1-nemotron-70b-instruct", quant="api", ctx_max=128000, modalities=["text"], requires_internet=True)
BackendModel("nvidia/nemotron-mini-4b-instruct", quant="api", ctx_max=4096, modalities=["text"], requires_internet=True)

OpenBmbBackend

OpenBMB's MiniCPM family — Christof's primary local-AI-workbench target. Typically served via vLLM, SGLang, or llama.cpp's HTTP server on http://localhost:8000 (or wherever the workbench binds). OpenAI-compatible HTTP. requires_internet=False (always local).

Models declared:

BackendModel("openbmb/MiniCPM4-8B", quant="fp16", ctx_max=32768, modalities=["text"], requires_internet=False)
BackendModel("openbmb/MiniCPM-V-2_6", quant="fp16", ctx_max=8192, modalities=["text","vision"], requires_internet=False)

Vision-capable MiniCPM-V variant is reserved for Phase 2 when CONTRACT §12 open question 1 lifts; vision messages stay text-only in MVP.

Config example 

[[llm.backends]]
name = "openbmb"
url  = "http://localhost:8000"
model = "openbmb/MiniCPM4-8B"

[[llm.backends]]
name = "nemotron"
url  = "https://integrate.api.nvidia.com/v1"
model = "nvidia/llama-3.1-nemotron-70b-instruct"
api_key_env = "NVIDIA_API_KEY"

[[llm.backends]]
name  = "lmstudio"
url   = "http://192.168.188.25:1234"
model = "qwen2.5-7b-instruct"

Three backends, four models if MiniCPM-V is later added → eight capability entries on the bus (two each for llm.chat and llm.complete × four models). The router picks among them at call time.

25. Coherence guarantees enforced by this reference

If you implement strictly against this document, the following hold automatically:

  • No symbol name appears in two different modules — see §18.
  • Every capability has exactly one handler — see §19.
  • Every event type has at least one producer — see §20.
  • Every constant is defined in constants.py and nowhere else — see §0.2.
  • The 15-step orchestration produces a runnable node — see §17 node.py.
  • Cross-references resolve — every M0N/X0N link points at an existing spec; every spec section number used here exists.

If you find a contradiction between this document and a spec, the spec wins by default — but file the discrepancy. The most common drift will be in field names of capability params (caught by the params predicate at registration time).

26. What is intentionally NOT in this document

  • Test code — see the tests/ section in each spec. Implement after the production code compiles.
  • Service-internal helpers that are pure implementation detail (private functions inside one file with leading underscore). Add as you need them.
  • Phase 2/3 modules — federation.*, ocr.*, tts.*, stt.*, trans.*, img.*, chat.thread.*, chat.forward.* are mentioned in specs but have no MVP symbols.
  • Vendor-specific tuning — llama.cpp n_threads, vLLM tensor parallel, Nemotron prompt prefixes. Decide per backend at integration time.

End of HearthNet Implementation Reference. Spec set version: v1.0 · this document touched: 2026-06-09.