Metadata-Version: 2.4
Name: matrx-utils
Version: 1.1.2
Summary: Shared utilities for the Matrx ecosystem
Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
Project-URL: Issues, https://github.com/AI-Matrix-Engine/aidream-current/issues
Author-email: Matrx <admin@aimatrx.com>
Maintainer-email: Matrx <admin@aimatrx.com>
License: MIT
Keywords: data-transformation,file-handling,matrx,utilities
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: boto3-stubs[s3]>=1.42.59
Requires-Dist: boto3>=1.42.59
Requires-Dist: dotenv>=0.9.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: mozjpeg-lossless-optimization>=1.1.0
Requires-Dist: numpy>=1.26
Requires-Dist: onnxruntime>=1.16
Requires-Dist: opencv-python-headless>=4.9
Requires-Dist: pandas>=3.0.1
Requires-Dist: pillow-avif-plugin>=1.4.6
Requires-Dist: pillow-heif>=0.18.0
Requires-Dist: pillow>=11.2.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.27.0
Requires-Dist: pypdfium2>=4.30.0
Requires-Dist: pytesseract>=0.3.13
Requires-Dist: python-pptx>=1.0.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rembg>=2.0
Requires-Dist: requests>=2.32.5
Requires-Dist: supabase>=2.28.0
Provides-Extra: image-inpaint
Requires-Dist: numpy>=1.26; extra == 'image-inpaint'
Requires-Dist: opencv-python-headless>=4.9; extra == 'image-inpaint'
Provides-Extra: image-segmentation
Requires-Dist: onnxruntime>=1.16; extra == 'image-segmentation'
Requires-Dist: rembg>=2.0; extra == 'image-segmentation'
Provides-Extra: pdf-cloud-ocr
Requires-Dist: azure-ai-documentintelligence; extra == 'pdf-cloud-ocr'
Requires-Dist: boto3; extra == 'pdf-cloud-ocr'
Requires-Dist: google-cloud-documentai; extra == 'pdf-cloud-ocr'
Provides-Extra: pdf-forms
Requires-Dist: pypdfform>=1.4; extra == 'pdf-forms'
Provides-Extra: pdf-generate
Requires-Dist: reportlab>=4.0; extra == 'pdf-generate'
Provides-Extra: pdf-html
Requires-Dist: weasyprint>=60; extra == 'pdf-html'
Provides-Extra: pdf-ml-llm
Requires-Dist: pymupdf4llm>=0.0.30; extra == 'pdf-ml-llm'
Provides-Extra: pdf-ocr
Requires-Dist: ocrmypdf>=16; extra == 'pdf-ocr'
Provides-Extra: pdf-redact-ner
Requires-Dist: presidio-analyzer>=2.2; extra == 'pdf-redact-ner'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'pdf-redact-ner'
Requires-Dist: spacy>=3.7; extra == 'pdf-redact-ner'
Provides-Extra: pdf-signatures
Requires-Dist: pyhanko>=0.20; extra == 'pdf-signatures'
Provides-Extra: pdf-tables
Requires-Dist: tabula-py>=2.9; extra == 'pdf-tables'
Provides-Extra: pdf-tables-extra
Requires-Dist: camelot-py>=0.11; extra == 'pdf-tables-extra'
Description-Content-Type: text/markdown

# matrx-utils

Foundation utilities for the Matrx ecosystem — cloud file handling (AWS S3, Supabase Storage, 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

```bash
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_utils.file_handling` | `FileManager`, `FileHandler`, `BatchHandler`, `open_any_file` |
| `matrx_utils.file_handling.cloud_sync` | `S3Backend`, `SupabaseBackend`, `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:

```python
from matrx_utils import vcprint, settings
from matrx_utils.file_handling.cloud_sync import SupabaseBackend

vcprint("hello")
vcprint(settings.SUPABASE_URL)           # read from env
backend = SupabaseBackend()              # 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:

```python
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](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](https://github.com/AI-Matrix-Engine/aidream-current/tree/main/packages/matrx-utils).

## License

MIT.
