matrx-connect

FastAPI connectivity layer for the Matrx ecosystem: auth middleware, streaming-response infrastructure, request-scoped AppContext, and the Emitter protocol. Despite the name, "connect" is about connecting a FastAPI app to the Matrx streaming + auth contract — not database connectivity.

Install

pip install matrx-connect

Python 3.12+ required. Depends only on matrx-utils from the Matrx family.

What's in the box

Module What it does
matrx_connect.context.app_context AppContext dataclass + sealed tenant factories (require_tenant_context, tenant_system_context, tenant_resource_context) + ContextVar helpers
matrx_connect.context.emitter_protocol Emitter protocol — every method any producer can call (send_chunk, send_reasoning, send_phase, send_data, send_info, send_warning, fatal_error, send_end, tool events, …)
matrx_connect.context.events Pydantic event payload schemas shared with the frontend
matrx_connect.emitters.stream_emitter StreamEmitter — the JSONL/NDJSON HTTP streaming implementation
matrx_connect.emitters.console_emitter ConsoleEmitter — dev/test implementation that prints to stdout
matrx_connect.middleware.auth AuthMiddleware — pluggable JWT + admin-token + fingerprint resolution, with a resolve_guest callback hook
matrx_connect.streaming.response create_streaming_response(ctx, task, *args, ...) — the ONLY public entry point for streaming endpoints
matrx_connect.dependencies context_dep reads AppContext; authenticated_resource_bootstrap authenticates a declared resource route and returns only its literal X-Organization-Id claim

The streaming endpoint pattern

Every streaming route follows this exact shape. It's enforced across every repo that uses matrx-connect, so that the behavior of heartbeats, client disconnects, and error handling stays consistent:

from fastapi import APIRouter, Depends
from matrx_connect import AppContext, context_dep
from matrx_connect.streaming import create_streaming_response

router = APIRouter()

@router.post("/topics/{topic_id}/search")
async def trigger_search(topic_id: str, ctx: AppContext = Depends(context_dep)):
    return create_streaming_response(
        ctx, _run_search, topic_id,
        initial_message="Starting search…", debug_label="ResearchSearch",
    )

async def _run_search(emitter, topic_id: str):
    # AppContext is already set on the ContextVar.
    # Cancellation + exception handling are done for you.
    result = await do_work(topic_id)
    await emitter.send_data(SearchResult(...).model_dump())
    await emitter.send_end()

What create_streaming_response does for you:

  • Creates the StreamEmitter, attaches it to AppContext, and pushes AppContext onto the ContextVar.
  • Spawns the task as a background asyncio.Task.
  • Catches CancelledError (client disconnect) and generic exceptions — the latter are surfaced via emitter.fatal_error(...).
  • Emits heartbeat keepalives while the task is running.
  • Clears the ContextVar on exit.

Your task function never touches set_app_context / clear_app_context / CancelledError. If you find yourself reaching for those symbols in application code, extend create_streaming_response instead.

Wiring the auth middleware

from fastapi import FastAPI
from matrx_connect.middleware.auth import AuthMiddleware

app = FastAPI()
app.add_middleware(
    AuthMiddleware,
    jwt_secret=settings.JWT_SECRET,
    admin_token=settings.ADMIN_TOKEN,
    admin_user_id=settings.ADMIN_USER_ID,
    resolve_guest=my_guest_resolver,   # optional callback for fingerprint-based guests
)

After this, every request has an AppContext on request.state.context and context_dep will hand it to any route handler that depends on it.

Resource handlers that authorize a named row after middleware admission use authenticated_resource_bootstrap. Pair it with the exact authenticated_resource_routes(app, authenticated_resource_bootstrap) output when configuring AuthMiddleware; it defers organization pre-refusal for those method/path declarations without creating an organization-free or tenant context. The handler still owns row authorization.

Standalone-friendliness

matrx-connect has a single sibling dependency (matrx-utils, for verbose-logging). It assumes no ORM, no database, no Supabase — wire those in from your app. The Emitter is a typing.Protocol, so you can hand create_streaming_response any object that satisfies the shape.

Contributing

See CLAUDE.md for package-specific import rules and conventions. This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.

License

MIT.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.102)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for armanisadeghi from gravatar.com armanisadeghi

Credits

Author/Maintainer: Matrx

License

MIT License (MIT)

Requires

Python >=3.12

Tags

auth fastapi matrx middleware sse streaming

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrx_connect-0.1.101.tar.gz (241.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

matrx_connect-0.1.101-py3-none-any.whl (192.7 kB view details)

Uploaded Python 3

File details

Details for the file matrx_connect-0.1.101.tar.gz.

File metadata

  • Download URL: matrx_connect-0.1.101.tar.gz
  • Upload date:
  • Size: 241.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrx_connect-0.1.101.tar.gz
Algorithm Hash digest
SHA256 a6cc10cddad3b2968b3c26306a861f6d59005d9185a95243ffb937c5fb5a93a6
MD5 16e9269129c324e70e99321a27ee1fe6
BLAKE2b-256 ba46740b9a10089974cbcf0c678d64e870c1deb28e5a93d48f82260f9086c51f

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_connect-0.1.101.tar.gz:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file matrx_connect-0.1.101-py3-none-any.whl.

File metadata

  • Download URL: matrx_connect-0.1.101-py3-none-any.whl
  • Upload date:
  • Size: 192.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrx_connect-0.1.101-py3-none-any.whl
Algorithm Hash digest
SHA256 2c70ec2ca7116a34e7b93be47b335b8580363892e40eb336864e3329268a5ce8
MD5 ebb68ebb984cb398cba9e813adb32774
BLAKE2b-256 4b8ea8b06a94b2398fbf736d4e97997bd0fddd8486812a4bcc57af28bde79179

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_connect-0.1.101-py3-none-any.whl:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.102

2 files

This release

0.1.101 This release

2 files

0.1.100

2 files

0.1.99

2 files

0.1.98

2 files

0.1.97

2 files

0.1.96

2 files

0.1.95

2 files

0.1.94

2 files

0.1.93

2 files

0.1.92

2 files

0.1.91

2 files

0.1.90

2 files

0.1.89

2 files

0.1.88

2 files

0.1.87

2 files

0.1.86

2 files

0.1.85

2 files

0.1.84

2 files

0.1.83

2 files

0.1.82

2 files

0.1.81

2 files

0.1.80

2 files

0.1.79

2 files

0.1.78

2 files

0.1.77

2 files

0.1.76

2 files

0.1.75

2 files

0.1.74

2 files

0.1.73

2 files

0.1.72

2 files

0.1.71

2 files

0.1.69

2 files

0.1.68

2 files

0.1.67

2 files

0.1.66

2 files

0.1.65

2 files

0.1.64

2 files

0.1.63

2 files

0.1.62

2 files

0.1.61

2 files

0.1.60

2 files

0.1.59

2 files

0.1.58

2 files

0.1.57

2 files

0.1.56

2 files

0.1.55

2 files

0.1.54

2 files

0.1.53

2 files

0.1.52

2 files

0.1.51

2 files

0.1.50

2 files

0.1.49

2 files

0.1.48

2 files

0.1.47

2 files

0.1.46

2 files

0.1.45

2 files

0.1.44

2 files

0.1.43

2 files

0.1.42

2 files

0.1.41

2 files

0.1.40

2 files

0.1.39

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page