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 + ContextVar + get_app_context / set_app_context / try_get_app_context / clear_app_context
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 — the FastAPI Depends() helper that pulls AppContext into a route handler

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.

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.52.tar.gz (158.8 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.52-py3-none-any.whl (139.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: matrx_connect-0.1.52.tar.gz
  • Upload date:
  • Size: 158.8 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.52.tar.gz
Algorithm Hash digest
SHA256 d4d15164d0d98170e291e28790f64e74088af3e62283725cf5140c27ea519e90
MD5 37f749ed5d28c50040fee8b3beaaa201
BLAKE2b-256 2927b5049a5fa6f3ac728c8f949059a8dec0eae5310b69d2288a17a7947bdeae

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_connect-0.1.52.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.52-py3-none-any.whl.

File metadata

  • Download URL: matrx_connect-0.1.52-py3-none-any.whl
  • Upload date:
  • Size: 139.9 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.52-py3-none-any.whl
Algorithm Hash digest
SHA256 5fe87e8c8acf4b73631fe3cdb5c0ebd48ae6994d5f90a4a8d2c8d9ef7d077a29
MD5 a36be2ad2fb832b7ad67f8978c1ed7fa
BLAKE2b-256 a0a7cc1f8304ecdc19cd6a9028030d3b7dfababf709c599f292df141a0538020

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_connect-0.1.52-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

0.1.101

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

This release

0.1.52 This release

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