mgf-common 0.1.0

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

mgf-common

Shared infrastructure for MGF projects: typed exceptions, central configuration (pydantic-settings), and a structured-logging + OpenTelemetry-tracing stack. One implementation, lifted out of VManager so other projects can consume it directly instead of copy-pasting.

Status

Phase 2 complete (bootstrapped 2026-04-22). The three core subpackages — exceptions, observability, config — are lifted and tested in place; VManager cutover (Phase 3) is next. See COMMON.md (lands in Phase 5) or ../VManager/docs/COMMON.md for the extraction plan.

Install

Once published:

pip install mgf-common
# Optional Tier C observability (OpenTelemetry SDK + Sentry):
pip install 'mgf-common[observability]'

For local development (the Phase 5 default until PyPI publish):

# In a consumer project's pyproject.toml:
dependencies = ["mgf-common"]

[tool.uv.sources]
mgf-common = { path = "../mgf_common", editable = true }

Use

import mgf.common

# Once at startup — establishes app identity for logging, crash
# reports, OTel resource attributes.
mgf.common.configure(app_name="myapp", app_version="1.0.0")

from mgf.common.observability import setup_logging, setup_otel
setup_logging(level="INFO")            # console + rotating file + opt-in journald/OTLP
setup_otel()                           # no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set

from mgf.common.exceptions import AppError
class MyAppError(AppError):
    pass

from mgf.common.config import BaseAppSettings, load_settings, make_settings_config
class Settings(BaseAppSettings):
    model_config = make_settings_config(env_prefix="MYAPP_")
    backend_uri: str = "..."
    # ... your fields

Standards

The cross-project engineering standards are at docs/standards/ (land in Phase 4). They cover error handling, logging, configuration, and design principles — what every MGF-family project commits to.

Development

uv venv
uv sync --extra dev --extra observability

# Tests + lint + types + layering
pytest --tb=short -q
ruff check src tests
mypy src
lint-imports

Layout

mgf_common/
├── pyproject.toml
├── COMMON.md                      extraction plan + path to PyPI
├── docs/
│   └── standards/                 cross-project engineering standards
├── src/
│   └── mgf/                       PEP 420 namespace package (no __init__.py)
│       └── common/
│           ├── exceptions/
│           ├── config/
│           └── observability/
└── tests/

License

MIT — see LICENSE.