Core framework

Install from PyPI as core-framework, import core_framework. MIT — LICENSE. Repository, PyPI.

Documentation

Install

uv add core-framework

Pin hosts to a locked version. On each bump, read CHANGELOG.md and the host-upgrade tables in package-api.md.

Local development

Use Python 3.14. Install uv and Docker.

Tracked config.toml at the repo root is the local-dev settings file (dummy values; no production secrets). Production renders from config.toml.template via deploy envsubst — see architecture decisions.

docker compose -f deploy/app/docker-compose.dev.yaml up -d
uv sync --locked --all-extras --dev
uv run cf-alembic
make run

Firebase: copy firebase_config.example.json to firebase_config.json at the repo root and replace with your Firebase project’s service account JSON from the console.

For make test, use the Firebase CLI (Auth emulator). Stop DB/Redis: docker compose -f deploy/app/docker-compose.dev.yaml down.

Pre-commit: uv sync --dev installs pre-commit. Enable hooks with uv run pre-commit install (ruff, mdformat, uv-lock, and other checks in .pre-commit-config.yaml).

Hosts

In your host app, load Settings or a Settings subclass from core_framework.core.settings, pass it to init_app from core_framework.main, then wire host-specific dependencies and routers. init_app already runs core exception handlers; host-only types use register_exception_handler.

from core_framework.main import init_app
from fastapi import FastAPI

from myapp.settings import HostSettings, load_default_settings


def build_app(settings: HostSettings | None = None) -> FastAPI:
    resolved = settings if settings is not None else load_default_settings()
    app = init_app(resolved)

    from myapp.bootstrap import configure_dependencies

    configure_dependencies(runtime=app.state.core_runtime)

    from myapp.api.router import router

    app.include_router(router)
    return app

From the host repository root, run uv run cf-alembic. See core-framework-migration.

Worker: production also runs the ARQ worker (arq core_framework.worker.main.WorkerSettings, or a host composition that calls the same startup path). Schedules and tasks: workers.md. Composition details: package-api.md (Default deployment entrypoints).

Observability: OpenTelemetry OTLP (not Logfire). Under [observability], set enabled and otlp_endpoint (required when enabled outside local); drop logfire_token / LOGFIRE_TOKEN. Same-host Grafana LGTM stack: deploy/observability/ and observability-lgtm-setup.md. Host upgrade table: package-api.md — observability OTLP.

Host pytest

In your host repository, add the core-framework[testing] extra to dev or test dependencies. In tests/conftest.py, register pytest_core_framework_config (returns TestConfig) and a session-scoped anyio_backend fixture that returns "asyncio". The extra also wraps tests with Blockbuster so core_framework cannot perform stdlib blocking I/O on the asyncio loop.

import pytest

from core_framework.testing import TestConfig

from myapp.settings import load_default_settings


def pytest_core_framework_config() -> TestConfig:
    from myapp.main import build_app

    return TestConfig(
        settings_loader=load_default_settings,
        app_factory=build_app,
    )


@pytest.fixture(scope="session")
def anyio_backend() -> str:
    return "asyncio"

See Package API — Testing and testing plugin design.