Metadata-Version: 2.4
Name: maria-epe
Version: 0.5.0
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.

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

```text
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:

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

Then use the whole library through `maria`:

```python
import maria
```

Current package version: `0.5.0`

Formal package installs supported today:

```bash
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

```python
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:

```bash
python examples/credit_audit_demo.py
```

Run the Maria multitunnel demo:

```bash
python examples/maria_multitunnel_demo.py
```

Run the exchange demo:

```bash
python examples/maria_exchange_demo.py
```

Run the runtime connector demo:

```bash
python examples/runtime_connector_demo.py
```

Run the external-style CZVS test script:

```bash
python examples/test_czvs.py
```

Generate the live StructIndex inspector:

```bash
python examples/structindex_live_viewer.py
```

Generate the appendix-structure visuals:

```bash
python examples/appendix_structures_visuals.py
```

Run tests:

```bash
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.

```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.

## 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:

```python
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:

```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
```

Starter template:

```bash
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:

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

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`

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:

```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 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.

```python
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](.github/workflows/ci.yml)
- tagged releases: [.github/workflows/release.yml](.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](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](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
