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
• App factory and testing helpers

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.