axis-synome 0.1.0.dev76

Axis specification modules (entities, formulas, validators)

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:

pip install axis-synome

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

pip install axis-synome[runtime]

Or install from a private registry:

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

Usage

ASC Entities

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

ASC Formulas

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

Opaque Operations in Specs

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

Specs are validated by two complementary gates:

1. Static gate — the spec_validator flake8 plugin enforces the declarative Python subset specs are written in (no mutation, no imperative control flow, restricted imports, …).
2. Semantic gate — the parser (python -m axis_synome.parser) round-trips every spec module into a SymPy expression graph and identity records. If a spec uses a construct the parser cannot lower, parsing fails — even if it would lint clean. Run via make parse-specs (also part of make check-all).

See ADR-0002 for the rationale behind co-locating the parser with the specs.

from axis_synome.spec_validator import validate_file

validate_file("my_spec.py")

Or use as a flake8 plugin:

flake8 --select=AXS your_spec.py

Examples

Runnable examples that show how to navigate the entity graph (assets, tokens, networks, protocols of a prime) live under examples/. Run any of them with:

uv run python examples/02_assets_and_tokens_of_a_prime.py

Highlights:

• 01_prime_basics.py — basic facts about each PrimeAgent.
• 02_assets_and_tokens_of_a_prime.py — list assets, tokens, underlying tokens, and group by network/protocol.
• 03_inverse_lookups.py — which primes hold token X?, which primes are on network Y?, which prime owns this address?
• 04_atlas_provenance.py — trace each asset back to its Atlas document.
• 05_feeding_a_formula.py — bridge external records into Positions and call asc(...).

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.

Requirements

• Python >= 3.11
• pydantic >= 2.0.0