matrx-utils
Foundation utilities for the Matrx ecosystem — cloud file handling (AWS S3 and local/server filesystems), a pluggable settings + request-context layer, and a set of developer helpers (fancy printing, data transforms, field-processing, code analysis).
matrx-utils is the bottom of the Matrx dependency graph. It has no sibling dependencies. Everything else (matrx-connect, matrx-orm, matrx-graph, matrx-scraper, matrx-ai) depends on it, directly or transitively.
Install
pip install matrx-utils
Python 3.13+ required.
What's in the box
| Module | What it does |
|---|---|
matrx_utils.conf |
configure_settings(obj) + a lazy settings proxy that falls back to env vars |
matrx_utils.ctx |
UserContext protocol, SimpleUserContext, configure_context(getter), get_active_context() |
matrx_utils.fancy_prints |
vcprint, vclist, print_link, MatrixPrintLog, to_matrx_json |
matrx_utils.data_handling |
DataTransformer, URL and value validators |
matrx_files |
FileManager, FileHandler, BatchHandler, open_any_file |
matrx_files.cloud_sync |
S3Backend, ServerBackend, CloudSyncConfig, SyncEngine + permissions and versioning |
matrx_utils.field_processing |
camel_to_snake, process_field_definitions, generate_complete_code |
matrx_utils.code_context, matrx_utils.package_analysis, matrx_utils.react_analysis |
Developer utilities for scanning codebases |
Usage — standalone
Out of the box, matrx-utils reads its configuration from environment variables via a lazy settings proxy, and returns a minimal SimpleUserContext when no request context is available:
from matrx_utils import vcprint, settings
from matrx_files.cloud_sync import S3Backend
vcprint("hello")
vcprint(settings.SUPABASE_URL) # read from env
backend = S3Backend() # credentials resolved from settings
backend.write("reports/today.json", b"{}")
Usage — inside a host application
A parent app (like aidream) can inject its own settings object and request-context resolver so every downstream helper picks up the right user/project/emitter automatically:
from matrx_utils import configure_settings, configure_context
from matrx_connect import try_get_app_context # optional, only if you use matrx-connect
from myapp.settings import settings
configure_settings(settings)
configure_context(try_get_app_context)
After configure_context(...), any code that calls get_active_context() inside a request will get the caller's UserContext without that code having to accept it as a parameter. This is the "capability-within, injection-without" pattern that the other Matrx packages follow.
Standalone-friendliness
This package is designed to work with zero Matrx siblings present. It references matrx-connect in exactly one place — the PDF handler — and that import is lazy with a dict fallback, so pip install matrx-utils followed by import matrx_utils works in any Python project.
Contributing
See CLAUDE.md for package-specific rules (import rules, configuration pattern, known issues). This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.
License
MIT.
1 maintainer
Release files for matrx-utils 2.0.51
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrx_utils-2.0.51.tar.gz | 300.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrx_utils-2.0.51-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 611.9 kB
Release files / matrx_utils-2.0.51.tar.gz
| Download URL | matrx_utils-2.0.51.tar.gz |
|---|---|
| Size | 300.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ab977691220b0ab7773b841eddc19681920fc57a7d8aabda98b9a5607ecdebc
|
|
BLAKE2b-256 checksum How to use checksums |
bcda825c04f91d2a8a2ee3886998f1de4ae057cf9e49d4b9be8e8d92dfe84ae9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logRelease files / matrx_utils-2.0.51-py3-none-any.whl
| Download URL | matrx_utils-2.0.51-py3-none-any.whl |
|---|---|
| Size | 311.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82709f1e8c5494c939c7e0176fae0fbd8c841b3d6a69305b4490a3477dff9d9f
|
|
BLAKE2b-256 checksum How to use checksums |
932e572a2d6798f58460caeb76f8737d17813a8129caa121fd29df9f1e29bfb9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency log
