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.89.tar.gz (207.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.89-py3-none-any.whl (170.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: matrx_connect-0.1.89.tar.gz
  • Upload date:
  • Size: 207.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.89.tar.gz
Algorithm Hash digest
SHA256 82cf3e40e9f78aa15311dc614d34209302401d9b149aa700800ac9450e92f4f1
MD5 4866b74f912c574b92cfbbaffcf8e622
BLAKE2b-256 844c42e996ac2df01cd28271ba893a6dfca715159c2f2081cfafea8f251e7701

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: matrx_connect-0.1.89-py3-none-any.whl
  • Upload date:
  • Size: 170.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.89-py3-none-any.whl
Algorithm Hash digest
SHA256 83b38eb08d9552a797ed5882f812416ab3f0ec7183b6bc01c744ba410bde073a
MD5 aedd48b536ad2bb35b4949d89044fef6
BLAKE2b-256 b3a975ef74cbbf4339cc9bf769cbc7f67fc2f444eea4f13b675da72f6d0b8c2b

See more details on using hashes here.

Provenance

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

This release

0.1.89 This release

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