mgf-common 0.38.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 + FastAPI/Django/ alembic adapters — bundled into one PEP 561 typed package so every Magogi project (and any compatible consumer) inherits the same shape.

Status: pre-1.0 (current 0.37.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)	docs/audience/ai-agents.md

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/ (17 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 scientific platform ("small consumer" scope discipline)

---

License

MIT. See LICENSE.