Metadata-Version: 2.4
Name: maria-epe
Version: 0.5.1
Summary: Maria library for the EPE structural analysis and governance framework.
Author: neido
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/neido/maria-epe
Project-URL: Repository, https://github.com/neido/maria-epe
Project-URL: Issues, https://github.com/neido/maria-epe/issues
Keywords: audit,governance,structural-analysis,ml,framework,maria,epe
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Provides-Extra: visuals
Requires-Dist: matplotlib>=3.8; extra == "visuals"

# Maria EPE Library

The Maria EPE Library is a developer-ready implementation of the Piance-Epe
structural analysis and governance methodology.

It is designed around one simple idea:

- compare systems by structure, not only by outputs
- constrain adaptive behavior inside explicit borders
- convert structural findings into auditable decisions

## Install

Install from PyPI:

```bash
python -m pip install maria-epe
```

Or install from source while developing:

```bash
python -m pip install -e .
```

Current package version: `0.5.1`

The import surface is:

```python
import maria
from maria import MariaLibrary
```

## Why Maria

Use Maria when you want to:

- compare systems by structure, not just outputs
- keep adaptive systems inside admissibility borders
- inspect drift, prototypes, CZVS distance, and audit decisions
- move structural entities between tools through a versioned exchange format
- inspect runtime/compiler outputs through a live HTML viewer

Python is the canonical implementation language for this repository.
Julia is included only as an optional acceleration backend for selected
high-performance computations, so the full framework stays usable for as many
developers as possible.

## Quick Start

```python
from maria import (
    AuditPolicy,
    MariaLibrary,
    build_credit_border,
)

library = MariaLibrary()
border = build_credit_border()

production = library.entity(
    border=border,
    tunnel=library.tensor_tunnel([[605.0, 28.0], [610.0, 29.0]], metadata={"name": "production-snapshot"}),
    context={"age": 28, "credit_score": 605, "credit_policy": "default"},
)

candidate = library.entity(
    border=border,
    tunnel=library.tensor_tunnel([[605.0, 28.0], [600.0, 35.0]], metadata={"name": "candidate-snapshot"}),
    context={"age": 28, "credit_score": 605, "credit_policy": "default"},
)

policy = AuditPolicy(
    warning_varpi=10.0,
    block_varpi=25.0,
    warning_delta_varpi=10.0,
    block_delta_varpi=25.0,
)

result = library.audit(candidate, production, policy=policy)
print(result.decision)
```

## CZVS Example

```python
from maria import MariaLibrary

library = MariaLibrary()
index = library.struct_index(czvs_target=[0.0, 0.0, 0.0], graph_threshold=0.9)

index.add_entity("sample-a", [0.05, 0.01, 0.08], metadata={"admissible": True, "border_region": "core"})
index.add_entity("sample-b", [0.14, 0.06, 0.17], metadata={"admissible": True, "border_region": "watch"})
index.add_entity("sample-c", [0.91, 0.78, 0.73], metadata={"admissible": False, "border_region": "warning"})
index.refresh_graph()

print(index.czvs_candidates(limit=3))
print(index.summary())
```

## Runtime And Compiler Connectors

Maria can ingest real runtime or compiler exports and turn them into a
Piance-aware `StructIndex`.

Supported formats:

- JSON bundles with `entities`
- JSONL event streams
- CSV and TSV metrics exports
- trace-event JSON exports
- OpenTelemetry span exports

Python API:

```python
from maria import RuntimeImportConfig, struct_index_from_runtime_path

config = RuntimeImportConfig(embedding_fields=["latency_ms", "error_rate", "memory_delta"])
index, bundle = struct_index_from_runtime_path(
    "runtime_metrics.csv",
    config=config,
    czvs_target=[0.0, 0.0, 0.0],
    graph_threshold=90.0,
)
```

Trace events:

```python
from maria import struct_index_from_runtime_path

index, bundle = struct_index_from_runtime_path(
    "trace_events_sample.json",
    graph_threshold=900.0,
)
```

CLI:

```bash
maria-inspect-runtime examples/runtime_sample.json --output examples/plots/runtime_sample_viewer.html
maria-inspect-runtime examples/runtime_events.jsonl --embedding-fields latency,error_rate,memory_delta --czvs-target 0,0,0 --output examples/plots/runtime_events_viewer.html
maria-inspect-runtime examples/runtime_metrics.csv --format csv --embedding-fields latency_ms,error_rate,memory_delta --czvs-target 0,0,0 --output examples/plots/runtime_metrics_viewer.html
maria-inspect-runtime examples/trace_events_sample.json --format trace-events --output examples/plots/trace_events_viewer.html
maria-inspect-runtime examples/otel_spans_sample.json --format otel --output examples/plots/otel_spans_viewer.html
```

Generated example inputs:

- `examples/runtime_sample.json`
- `examples/runtime_events.jsonl`
- `examples/runtime_metrics.csv`
- `examples/trace_events_sample.json`
- `examples/otel_spans_sample.json`

## Serialization And Exchange

Maria entities can be exported and imported through the versioned
`maria-entity-exchange` JSON schema.

```python
from maria import save_entity, load_entity

save_entity(entity, "candidate.maria.json")
restored = load_entity("candidate.maria.json")
```

This gives you a portable format for moving entities across tools, runtimes,
and future compiler integrations.

## Outside The Repo

If you want to create a `root_cell.py` or notebook outside this repository,
install Maria first:

```bash
python -m pip install maria-epe
```

Then your external file can simply do:

```python
from maria import MariaLibrary

library = MariaLibrary()
index = library.struct_index(czvs_target=[0.0, 0.0, 0.0])
```

There is a ready-made external example at:

- `examples/test_czvs.py`

## Appendix Structures

The six computational appendix structures are available directly from `maria`:

- `StructureTree`
- `StreamBuffer`
- `BasisProjector`
- `StructGraph`
- `TimeTrace`
- `StructIndex`

You can also create them through `MariaLibrary()` helper methods:

```python
from maria import MariaLibrary

library = MariaLibrary()
tree = library.structure_tree(leaf_size=4)
buffer = library.stream_buffer(dim=3)
projector = library.basis_projector(input_dim=16, basis_size=6)
graph = library.struct_graph()
trace = library.time_trace()
index = library.struct_index()
```

The interactive StructIndex inspector lets you inspect:

- Piance tree nodes
- representative prototypes
- admissibility and border regions
- CZVS candidates
- graph clusters
- query traces

## Julia Hooks

The Python library exposes a `JuliaBridge` for selected high-performance routines:

- `lp_distance`
- `tensor_signature`
- `alignment_similarity`
- `interaction_degree`
- `sbid_score`

If Julia is available on the host, the bridge can call the Julia backend.
If Julia is not installed, the bridge falls back to the Python implementation.

```python
from maria import JuliaBridge

bridge = JuliaBridge()
score = bridge.sbid_score([1.0, 2.0], [1.2, 1.9], variance=0.1)
```

## Developer Workflow

Run the demos:

```bash
python examples/credit_audit_demo.py
python examples/maria_multitunnel_demo.py
python examples/maria_exchange_demo.py
python examples/runtime_connector_demo.py
python examples/test_czvs.py
python examples/framework_smoke_test.py
python examples/structindex_live_viewer.py
python examples/appendix_structures_visuals.py
```

Run tests:

```bash
python -m unittest discover -s tests -v
```

## CI And Releases

GitHub Actions workflows are included for:

- continuous integration: `.github/workflows/ci.yml`
- tagged releases: `.github/workflows/release.yml`

Release tags can publish to PyPI when `PYPI_API_TOKEN` is configured in GitHub
repository secrets.

## Canonical Spec

The framework specification lives at `docs/spec/framework.md`.

That document is the language-independent reference.
The `maria` Python package is the whole-library public API.
The `epe_framework` package remains available as a compatibility layer around
the same core implementation.

## Archived Sources

The original documents that informed this framework are preserved in
`docs/sources`.

They are kept as archived source material, not as live spec files.
