dreamverse-core

Shared backend infrastructure for Dreamverse FastAPI services.

Install

The package is published to PyPI. Install it directly with the extras your service needs:

pip install dreamverse-core
pip install "dreamverse-core[supertokens,sentry,postgres]"

Tagged releases also attach the built wheel and source distribution to GitHub Releases for pinned or offline installs.

Quickstart

from fastapi import APIRouter
from dreamverse.app import MiddlewareConfig, create_app
from dreamverse.config import BaseAppSettings

settings = BaseAppSettings()
router = APIRouter()

@router.get("/hello")
async def hello() -> dict[str, str]:
    return {"message": "hello"}

app = create_app(
    title="Example API",
    version="1.0.0",
    settings=settings,
    routers=[router],
    middleware_config=MiddlewareConfig(),
)

What it provides

• Config-driven settings with strict validation
• Unified API envelope and exception hierarchy
• Observability protocol/factory/manager stack
• Security, rate-limit, correlation, and logging middleware
• Provider-agnostic auth interfaces and dependencies
• SuperTokens signup lifecycle hooks for project role validation and bindings
• Database engine + session dependency helpers
• Event envelope + idempotency utilities
• Provider-neutral LLM interface for shared adapter contracts
• Reusable LLM adapter conformance suite with recorded fixture replay
• Shared LLM provider/model registry with packaged provider catalogs
• OpenAI Chat Completions compatible LLM adapter
• Audit-log sinks, explicit recording, replay, and FastAPI middleware
• Feature-flag provider contracts, targeting context, and config-driven factories
• Cached feature-flag fallback decorator with project-owned cache repositories
• Event bus with subscribe decorators, retries, and transport overrides
• Idempotency-key stores, FastAPI middleware, and dependency helpers
• Notification provider contracts, templated sends, and delivery audit records
• Email-template registry with project override hooks
• Server-side analytics capture with PostHog and custom provider support
• Payment provider contracts for Stripe, PayFast, in-memory tests, and project overrides
• Background-job queues with retry, DLQ, audit, and event hooks
• Search provider contracts for in-memory, Meilisearch, Typesense, and project overrides
• Media upload, storage, processing, and serve-policy helpers for S3/R2-style storage
• Image variant processing from a declared TOML profile, with focal crops and metadata stripping
• App factory and testing helpers

Media processing profiles

Install the media-processing extra and declare, in one TOML file per project, the variants every uploaded image is processed into:

schema_version = 1

[profiles.card_image]
purposes = ["category", "cover"]
max_input_pixels = 40_000_000

[profiles.card_image.variants.card]
width = 1200
aspect = "1.91:1"
crop = "focal"
format = "jpeg"
quality = 85
channels = ["whatsapp"]

[profiles.card_image.variants.thumb]
width = 320
crop = "fit"
format = "webp"
quality = 80
channels = ["web"]

from pathlib import Path
from dreamverse.media.processing import Focal, load_profiles, process_image

profile = load_profiles(Path("config/media-processing.toml")).profiles["card_image"]
result = process_image(upload_bytes, profile=profile, focal=Focal(0.5, 0.4))

load_profiles raises MediaProfileError listing every violation by TOML path, including any variant whose format a listed channel does not accept. process_image does no I/O: it applies EXIF orientation, converts to sRGB, crops focal variants around the focal point, never upscales, and re-encodes each variant from pixel data only, so no EXIF, GPS, XMP or ICC metadata survives. Its errors (ImageDecodeError, ImageTooLargeError, VariantTooLargeError) are permanent for the given bytes.

Verification

python -m build
pytest tests/ -q

Release

dreamverse-core uses a two-workflow release flow:

1. Run .github/workflows/release.yml from master with:
   • tag: vX.Y.Z
   • changelog: one bullet per line or a markdown bullet list
2. The workflow updates pyproject.toml and CHANGELOG.md, verifies the package, commits the release, and pushes the tag.
3. The tag triggers .github/workflows/publish.yml, which publishes to PyPI and updates the GitHub release with the built artifacts.