mgf-common 0.40.0

Shared infrastructure (typed exceptions, central config, structured logging + tracing) for MGF projects

mgf-common

The cornerstone library for the Magogi ecosystem. Typed exceptions + layered configuration + structured logging + OTel + crash reporting + vault + process management — the pure-Python infrastructure every Magogi project needs, in one PEP 561 typed package. Framework adapters (FastAPI, Django, SQLAlchemy, Alembic, HTTP) ship as separate mgf-* sibling packages that depend on this cornerstone — see FEDERATION.md and docs/design/federation.md.

Status: pre-1.0 (current 0.38.0). API stable enough that four real consumers (VManager Qt desktop, inthewords Django, PlasmaMapper FastAPI, iosRecovery CLI) ship with it. Public names are experimental per AP-11; promoted to stable after one full MINOR cycle without a 🔴 Blocker filed against them.

If you depend on mgf-common, read FEDERATION.md first. It is the canonical contract — required docs layout, standards-conformance levels, federation-first principle, catch-up cadence, and feedback discipline. One page; you'll be aligned with the federation by the end of it.

---

Pick your starting point

The docs are organised by audience. Pick one:

If you are…	Read
Evaluating mgf-common (right library for me?)	docs/audience/shoppers.md
Building with it (already adopted)	docs/audience/users.md
Contributing or designing alongside	docs/audience/developers.md
A test/QA engineer	docs/audience/qa.md
Cutting releases / running CI	docs/audience/release.md
Doing a security review	docs/audience/security.md
An AI agent (Claude or other)	Run mgf-common agents — the canonical briefing (also in STARTHERE.md §"For the AI agent") — then docs/audience/ai-agents.md for the feedback-relay protocol

If you don't fit any of these neatly: docs/audience/README.md is the meta-routing index.

If you just want to try it: see docs/tutorial.md (zero → working app in ~30 minutes).

---

At a glance

import mgf.common as mc

with mc.bootstrap(app_name="myapp", app_version="1.0") as ctx:
    # identity + logging + OTel + excepthooks all wired transactionally
    do_work()
# Clean shutdown on context-exit; LIFO rollback on any startup failure.

from mgf.common.process import Service, AllOf, PortReady, LogLineReady

with Service(
    ["postgres", "-D", str(db_dir), "-p", str(port)],
    ready=AllOf([
        PortReady("127.0.0.1", port),
        LogLineReady(r"database system is ready"),
    ]),
    timeout_s=20.0,
) as svc:
    run_my_integration_tests(port=port)
# Service stopped + process group cascaded on context-exit.

More: docs/recipes/ (cookbook patterns) and PUBLIC_API.md (full surface).

---

Top-level files

File	Purpose
STARTHERE.md	Two-flow navigation hub (new project vs catching up an existing one)
FEEDBACK.md	Living queue of consumer-filed feedback (the relay process driver)
CHANGELOG.md	Per-release short-form (Keep-a-Changelog format)
PUBLIC_API.md	Full public surface, table-form
PUBLIC_API.json	Auto-generated machine-readable surface
SECURITY.md	Vulnerability reporting policy (per SC-12)
CONTRIBUTING.md	Dev setup + the four green gates + PR process

---

Consumers using it today

• VManager — Qt desktop, libvirt VM toolkit (reference consumer; co-designed)
• inthewords — Django web app (canonical web consumer)
• PlasmaMapper — FastAPI multi-tenant platform (heaviest sibling adopter)
• iosRecovery — CLI recovery tool (greenfield canary consumer)

See USERS.md §2 for the full federation roster, and FEDERATION.md for the cornerstone / sibling / consumer model.

---

License

MIT. See LICENSE.