maria-epe 0.5.1

Maria library for the EPE structural analysis and governance framework.

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:

python -m pip install maria-epe

Or install from source while developing:

python -m pip install -e .

Current package version: 0.5.1

The import surface is:

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

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

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:

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:

from maria import struct_index_from_runtime_path

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

CLI:

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.

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:

python -m pip install maria-epe

Then your external file can simply do:

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:

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.

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:

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:

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.