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.45.tar.gz (156.5 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.45-py3-none-any.whl (138.4 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: matrx_connect-0.1.45.tar.gz
  • Upload date:
  • Size: 156.5 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.45.tar.gz
Algorithm Hash digest
SHA256 e141f14d5c000921ff67cdeefde036818b665534a3b72228708977fa91066a2e
MD5 6ba922d2928a07b7a2b823ef4ba1d6a0
BLAKE2b-256 9892c8a4678cb65999624358b04c9d3fd5483ca00940d441dabb02fd26ad4461

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: matrx_connect-0.1.45-py3-none-any.whl
  • Upload date:
  • Size: 138.4 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.45-py3-none-any.whl
Algorithm Hash digest
SHA256 4ca2bc8b9a6a35365db41232d94aab2fed45b036df0cb29a44e2bd7aaa6385b9
MD5 c8180a2ca4ffff7eb02b976dd161be46
BLAKE2b-256 0ea10fb28fdcd97732eb75c925ede7bb2d0e15268ffd903cf0f989d7952f1331

See more details on using hashes here.

Provenance

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

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

This release

0.1.45 This release

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