maria-epe 0.5.0

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.

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.

Repository Layout

docs/
  spec/        Canonical framework specification
  sources/     Archived original source documents
examples/      Runnable demos
src/
  epe_framework/  Compatibility package and core primitives
  maria/          Whole-library public API
tests/         Unit tests
julia/         Optional Julia backend

Core Components

• Omega: structural signature extraction
• varpi: structural divergence
• delta_varpi: rate divergence
• varpi_star: fused divergence metric
• E = (B, T): Eel-Structured Entity
• alpha(B, T): admissibility predicate
• AuditPolicy: deterministic mapping from findings to decisions

Install

Local editable install while developing:

python -m pip install -e .

Then use the whole library through maria:

import maria

Current package version: 0.5.0

Formal package installs supported today:

python -m pip install .
python -m pip install dist/maria_epe-0.5.0-py3-none-any.whl

For pip install maria-epe from anywhere on the internet, the package still needs to be published to PyPI. The repository is now set up for that release step through GitHub Actions once credentials are configured.

Quick Start

from maria import (
    AuditPolicy,
    LogisticModel,
    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)

Developer Workflow

Run the demo:

python examples/credit_audit_demo.py

Run the Maria multitunnel demo:

python examples/maria_multitunnel_demo.py

Run the exchange demo:

python examples/maria_exchange_demo.py

Run the runtime connector demo:

python examples/runtime_connector_demo.py

Run the external-style CZVS test script:

python examples/test_czvs.py

Generate the live StructIndex inspector:

python examples/structindex_live_viewer.py

Generate the appendix-structure visuals:

python examples/appendix_structures_visuals.py

Run tests:

python -m unittest discover -s tests -v

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.

Runtime And Compiler Connectors

Maria can now ingest real runtime or compiler exports and turn them into a Piancé-aware StructIndex.

Supported starter formats:

• JSON bundles with entities
• JSONL event streams

Python API:

from maria import RuntimeImportConfig, struct_index_from_runtime_path

config = RuntimeImportConfig(embedding_fields=["latency", "error_rate", "memory_delta"])
index, bundle = struct_index_from_runtime_path(
    "runtime_events.jsonl",
    config=config,
    czvs_target=[0.0, 0.0, 0.0],
    graph_threshold=0.9,
)

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

Starter template:

maria-inspect-runtime --write-template examples/runtime_template.json

Generated example inputs:

• examples/runtime_sample.json
• examples/runtime_events.jsonl

Outside The Repo

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

python -m pip install dist/maria_epe-0.5.0-py3-none-any.whl

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

You can copy that file anywhere after installing the package.

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 generated plots are written into examples/plots/.

The interactive StructIndex inspector is written to:

• examples/plots/structindex_live_viewer.html

That viewer lets you inspect:

• Piancé 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)

CI And Releases

GitHub Actions workflows are included for:

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

Release tags also support publishing 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.

Roadmap

• Add visualization helpers for border and tunnel audits
• Expand the Julia backend beyond selected high-performance computations