api-functions-return-dicts

IN premise

Every public API function returns a `dict` (or `str` for markdown/compact), never a `Network` or `Node` object, ensuring JSON-serializability at the boundary for CLI, HTTP, and tool-call consumers.

Summary

All public-facing functions in the API layer hand back plain dictionaries or strings rather than internal data structures. This guarantees that any consumer — whether a command-line tool, a web server, or an LLM tool call — can serialize the response to JSON without extra conversion steps, keeping the API boundary clean and integration-friendly.

Dependents

These beliefs depend on this one:

api-layer-ensures-atomic-isolated-mutations — The API layer enforces mutation safety through four mechanisms: context-managed load/save, per-function transaction scope, write-flag gating to prevent unintended persistence, and dict-only returns that prevent callers from holding live network references.

Details

Source

entries/2026/04/23/reasons_lib-api.md