Metadata-Version: 2.4
Name: axis-synome
Version: 0.1.0.dev26
Summary: Axis specification modules (entities, formulas, validators)
Author-email: Archon Tech <hello@archontech.ai>
License: MIT
Project-URL: Repository, https://github.com/archon-research/next-gen-atlas
Project-URL: Documentation, https://github.com/archon-research/next-gen-atlas
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: eth-hash[pycryptodome]>=0.5.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: runtime
Requires-Dist: numpy>=1.26; extra == "runtime"

# axis-synome

A Python framework for defining and validating financial specifications, with a focus on DeFi primitives and risk calculations. Includes:

- **ASC Specifications** — Actively Stabilizing Capital entities (assets, tokens, networks, protocols) and formulas (collateral ratios, incentives, resting/latent ASC)
- **Spec Validator** — Flake8 plugin for enforcing Python subset constraints on spec files
- **Metadata & Utilities** — Support for spec documentation and validated dataclasses
- **SpecRuntime** — Pluggable runtime abstraction for opaque operations (linear interpolation, ...) that specs can call without depending on a specific implementation library

## Installation

Install from PyPI:

```bash
pip install axis-synome
```

To enable the built-in `ReferenceSpecRuntime` (numpy-backed), install with the `runtime` extra:

```bash
pip install axis-synome[runtime]
```

Or install from a private registry:

```bash
pip install axis-synome --index-url https://npm.pkg.github.com/archon-research
```

## Usage

### ASC Entities

```python
from axis_synome.spec.asc.entities import primes, tokens, networks, protocol_sets
```

### ASC Formulas

```python
from axis_synome.spec.asc.formulas import asc, asc_collateral_ratio, asc_incentive
```

### Opaque Operations in Specs

```python
from axis_synome.spec_support.runtime import math

values = math.linear_interp([1.5], [1.0, 2.0], [10.0, 20.0])  # -> [15.0]
```

The active runtime is selected once at import time. Resolution order:

1. `AXIS_SYNOME_SPEC_RUNTIME=module.path:ClassName` env var
2. A registered `axis_synome.spec_runtimes` entry point (declared by a consumer package's `pyproject.toml`)
3. The bundled `ReferenceSpecRuntime` (requires `axis-synome[runtime]`)

If none is available, importing `axis_synome.spec_support.runtime.math` raises `ImportError` — the runtime is required at import time, not on first call.

### Spec Validation

```python
from axis_synome.spec_validator import validate_file

validate_file("my_spec.py")
```

Or use as a flake8 plugin:

```bash
flake8 --select=AXS your_spec.py
```

## About

`axis-synome` is a specification framework for defining financial and risk calculations in DeFi, with emphasis on formalized, auditable spec files.

For more information on writing specifications, see [WRITING_SPECS.md](WRITING_SPECS.md).

## Requirements

- Python >= 3.11
- pydantic >= 2.0.0
