axis-synome 0.1.0.dev16__tar.gz → 0.1.0.dev26__tar.gz

{axis_synome-0.1.0.dev16/src/axis_synome.egg-info → axis_synome-0.1.0.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev16
+Version: 0.1.0.dev26
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT
@@ -10,6 +10,8 @@ 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
 
@@ -18,6 +20,7 @@ A Python framework for defining and validating financial specifications, with a
 - **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
 
@@ -27,6 +30,12 @@ Install from PyPI:
 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
@@ -47,6 +56,22 @@ from axis_synome.spec.asc.entities import primes, tokens, networks, protocol_set
 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

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/README.md

@@ -5,6 +5,7 @@ A Python framework for defining and validating financial specifications, with a
 - **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
 
@@ -14,6 +15,12 @@ Install from PyPI:
 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
@@ -34,6 +41,22 @@ from axis_synome.spec.asc.entities import primes, tokens, networks, protocol_set
 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

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/WRITING_SPECS.md

@@ -175,6 +175,34 @@ a fixed set instiantiated objects. `value_usd` is additionally restricted with a
 - Uplift to shared only when needed: introduce shared entities at top level (`axis/entities/`) when the same entities are used by multiple formulas and sharing materially reduces duplication. A pragmatic threshold is when a third, independent formula reuses the same entities.
 - Don’t add empty common folders: only create and populate shared folders when you actually have shared entities.
 - Moving entities is a breaking change: import paths change when uplifting to shared. Provide re‑exports where feasible during transitions and bump the major version when breaking import paths.
+
+### SpecRuntime (Opaque Functions)
+
+Use only when the operation cannot be expressed in the allowed, parser‑friendly subset, or is so complex (e.g., ARIMA/GARCH/ML/DNN) that a full mathematical spec is infeasible. Prefer parser‑friendly constructs first (comprehensions + sum/min/max/any/all, simple math.*, scalar per‑element helpers).
+
+- Use `axis_synome.spec_support.runtime` (Built‑in SpecRuntime)
+  - What: a small set of opaque primitives exposed as free functions under `axis_synome.spec_support.runtime.<domain>` (e.g. `runtime.math.linear_interp`). Calls are dispatched to a `SpecRuntime` resolved once at package import time. The parser treats these calls as uninterpreted; the runtime implementation can use NumPy/StatsModels/etc.
+  - When: the operation truly requires external libraries (e.g., interpolation, rolling_var, GARCH/ARIMA); you need production‑grade runtime while keeping the spec parseable.
+  - How (spec author):
+    - Import the relevant submodule and call the function directly:
+      - `from axis_synome.spec_support.runtime import math`
+      - `math.linear_interp(x, xp, fp)`
+    - Do not call `get_runtime()` directly from spec code; treat the `SpecRuntime` class as an internal extension point.
+  - How (runtime selection at deploy/test time): in priority order,
+    1. `AXIS_SYNOME_SPEC_RUNTIME=my_pkg.module:MyRuntime` env var.
+    2. Register an entry point in the consuming package's `pyproject.toml`:
+       ```toml
+       [project.entry-points."axis_synome.spec_runtimes"]
+       default = "my_pkg.module:MyRuntime"
+       ```
+    3. Otherwise, the bundled `ReferenceSpecRuntime` (numpy‑backed, requires the `[runtime]` extra) is used.
+  - Adding a new operation: extend `SpecRuntime` with a new abstract method, implement it in `ReferenceSpecRuntime`, and add a thin wrapper in `axis_synome/spec_support/runtime/<domain>.py` that simply calls `get_runtime().<op>(...)`.
+
+- Authoring Rules
+  - Keep wrappers zero‑logic (no exceptions/branching); just delegate to `get_runtime()`.
+  - Use precise, stable types and consistent snake_case names.
+  - Briefly document new opaque functions in `runtime/README.md` (purpose, signature, runtime notes).
+
 ### Formulas
 
 - Formula functions are pure: `(inputs) -> output`, but process inputs to intermediate values by calling other formula functions (or by utilizing a restricted set of built-in functions and external functions)
@@ -299,13 +327,6 @@ Assuming that `PrimeAgentAll` is an Enum consisting of prime agent instances, to
 - Location: keep tests under `python/axis_synome/tests/` organized by concept/module. Treat these as internal by default; they can be published later based on demand.
 - Declarative first: specs are declarative and amenable to static verification; tests complement by documenting usage and catching regressions in opaque integrations.
 
-#### Reference Implementations for Opaque Functions
-
-- Opaque functions (e.g., ARIMA) are too complex to fully specify as pure math. To execute happy‑path tests, provide a minimal “test math engine” or reference implementation used only by tests.
-- Do not publish as an official runtime dependency initially. If users request a ready‑made engine, consider publishing a separate package later.
-- Multiple valid approaches may exist; tests should pick one concrete implementation as an example without constraining others.
-
-
 ## Starter Template
 
 Start a new spec module with (simplified example; in real modules, entities typically live in their own package folder):
@@ -391,7 +412,7 @@ def threshold_satisfied(owner: EligibleOwner) -> bool:
   - Aggregators: `sum`, `min`, `max`, `any`, `all` over generator expressions.
   - Generator expressions and simple `range(...)` where needed.
   - Selected `math.*` (e.g., `log`, `exp`, `sqrt`, `pow`).
-  - Imports from `axis_synome.spec`, `synome`, `typing`, `dataclasses`, `enum`, `pydantic`, and bare `math`.
+  - Imports from `axis_synome.spec`, `axis_synome.spec_support`, `synome`, `typing`, `dataclasses`, `enum`, `pydantic`, and bare `math`.
 
 - Avoid / Disallowed
   - Mutation, I/O, networking, side effects; exceptions and `try/except`.
@@ -493,7 +514,7 @@ Use the Makefile targets to run checks consistently:
 
 - For-loops inside formulas → Replace with generator expressions plus `sum(...)`, `any(...)`, or `all(...)`.
 - Dict/set comprehensions → Move structure-building to entities or use lists/tuples; keep formula bodies expression-centric.
-- Unapproved builtins/imports → Use only builtins in the allowlist and imports under permitted prefixes (`axis_synome.spec`, `typing`, `dataclasses`, `enum`, `pydantic`, `synome`, or `math`).
+- Unapproved builtins/imports → Use only builtins in the allowlist and imports under permitted prefixes (`axis_synome.spec`, `axis_synome.spec_support`, `typing`, `dataclasses`, `enum`, `pydantic`, `synome`, or `math`).
 - Methods in dataclasses/Enums → Move logic into free functions; limit classes to annotated fields (dataclasses) or constant members (Enums).
 - Missing/loose types → Add precise argument and return annotations; prefer closed-world Enums where policy implies eligibility.
 
@@ -646,31 +667,6 @@ def all_positions_above(positions: list[float], threshold: float) -> bool:
     return all(p >= threshold for p in positions)
 ```
 
-## Opaque Functions (Use Sparingly)
-
-Use only when the operation cannot be expressed in the allowed, parser‑friendly subset, or is so complex (e.g., ARIMA/GARCH/ML/DNN) that a full mathematical spec is infeasible. Prefer parser‑friendly constructs first (comprehensions + sum/min/max/any/all, simple math.*, scalar per‑element helpers).
-
-- Approach 1 — PascalCase (Uninterpreted Function)
-  - What: a normal spec function that the parser represents as an uninterpreted SymPy function; prints clearly and composes symbolically.
-  - When: you need a symbolic placeholder; runtime can be pure‑Python or evaluation isn’t required in tests. Good for things like ArgMaxIndex(values).
-  - How: define a plain function in the spec with a pure‑Python implementation and precise types; try to keep it as declarative as possible even though it is not translated to math, i.e., it still should throw exceptions or have side-effects.
-
-- Approach 2 — Spec Wrapper + MathEngine (External Packages)
-  - What: a thin spec wrapper that delegates to a pluggable runtime engine (installed via `set_engine`). The parser treats the call as uninterpreted; runtime can use NumPy/StatsModels/etc.
-  - When: the operation truly requires external packages or model fitting (e.g., rolling_var, GARCH/ARIMA); you need production‑grade runtime while keeping the spec parseable.
-  - How:
-    - Define engine contract (add to your project’s `opaque/engine.py`):
-      - `class MathEngine(ABC):`
-        - `@abstractmethod`
-        - `def rolling_var(self, returns: list[float], window: int, confidence: float) -> list[float]: ...`
-    - Add thin wrapper in an opaque module (e.g., `axis/.../opaque/statistical.py`) that simply calls `get_engine().rolling_var(...)`.
-    - Provide/install an engine in tests/apps: `from axis_synome.spec.ima.opaque import set_engine; set_engine(ReferenceMathEngine())`.
-
-- Authoring Rules
-  - Keep wrappers zero‑logic (no exceptions/branching); just delegate to `get_engine()`.
-  - Use precise, stable types and consistent snake_case names.
-  - Briefly document new opaque functions in `opaque/README.md` (purpose, signature, runtime notes).
-
 ## Atlas Integration
 
 - Keep Atlas UUIDs in docstrings using `:source_uuid: ...` when available. If no Atlas section applies, omit the marker entirely.

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/pyproject.toml

@@ -15,6 +15,11 @@ dependencies = [
     "pydantic>=2.0.0",
 ]
 
+[project.optional-dependencies]
+runtime = [
+    "numpy>=1.26",
+]
+
 [project.urls]
 Repository = "https://github.com/archon-research/next-gen-atlas"
 Documentation = "https://github.com/archon-research/next-gen-atlas"
@@ -28,16 +33,17 @@ include = ["axis_synome*"]
 
 [tool.setuptools_scm]
 root = "../.."
-tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$'
+tag_regex = '^v(?P<version>\d+\.\d+(?:\.\d+)?)'
 version_file = "src/axis_synome/_version.py"
 
 [dependency-groups]
 dev = [
     "pytest>=9.0.0",
     "flake8>=7.0.0",
-    "ruff==0.15.11",
+    "ruff>=0.15",
     "ty>=0.0.16",
     "lefthook>=1.9.5",
+    "axis-synome[runtime]",
 ]
 
 [tool.pytest.ini_options]

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/src/axis_synome/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0.dev16'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev16')
+__version__ = version = '0.1.0.dev26'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev26')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev26/src/axis_synome/spec_support/runtime/base.py

@@ -0,0 +1,93 @@
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from importlib import import_module, metadata
+
+ENV_VAR = "AXIS_SYNOME_SPEC_RUNTIME"
+ENTRY_POINT_GROUP = "axis_synome.spec_runtimes"
+
+
+class SpecRuntime(ABC):
+    """Internal abstraction backing :mod:`axis_synome.spec_support.runtime`.
+
+    Spec authors should call the free functions in
+    ``axis_synome.spec_support.runtime.<domain>`` (e.g. ``runtime.math``)
+    rather than interacting with this class directly. Custom
+    implementations are selected at process start via the
+    ``AXIS_SYNOME_SPEC_RUNTIME`` env var or an
+    ``axis_synome.spec_runtimes`` entry point — see
+    :func:`_resolve_default_runtime`.
+    """
+
+    @abstractmethod
+    def linear_interp(
+        self,
+        x: Sequence[float],
+        xp: Sequence[float],
+        fp: Sequence[float],
+    ) -> list[float]:
+        """One-dimensional linear interpolation.
+
+        Mirrors ``numpy.interp`` semantics: for each value in ``x``, return the
+        linearly-interpolated value from the ``(xp, fp)`` table. ``xp`` must be
+        increasing; values of ``x`` outside ``[xp[0], xp[-1]]`` are clamped to
+        the corresponding boundary value of ``fp``.
+        """
+
+
+def _instantiate(target: object) -> "SpecRuntime":
+    instance = target() if isinstance(target, type) else target
+    if not isinstance(instance, SpecRuntime):
+        raise TypeError(f"Resolved object {target!r} is not a SpecRuntime instance or subclass.")
+    return instance
+
+
+def _load_from_env() -> "SpecRuntime | None":
+    spec = os.environ.get(ENV_VAR)
+    if not spec:
+        return None
+    if ":" not in spec:
+        raise RuntimeError(f"Invalid {ENV_VAR}={spec!r}: expected 'module.path:AttrName'.")
+    module_path, attr = spec.split(":", 1)
+    module = import_module(module_path)
+    return _instantiate(getattr(module, attr))
+
+
+def _load_from_entry_points() -> "SpecRuntime | None":
+    eps = list(metadata.entry_points(group=ENTRY_POINT_GROUP))
+    if not eps:
+        return None
+    if len(eps) > 1:
+        names = sorted(ep.name for ep in eps)
+        raise RuntimeError(
+            f"Multiple '{ENTRY_POINT_GROUP}' entry points registered: {names}. "
+            f"Set {ENV_VAR}=module:Class to disambiguate."
+        )
+    return _instantiate(eps[0].load())
+
+
+def _load_reference() -> "SpecRuntime | None":
+    try:
+        from axis_synome.spec_support.runtime.reference import ReferenceSpecRuntime
+    except ImportError:
+        return None
+    return ReferenceSpecRuntime()
+
+
+def _resolve_default_runtime() -> "SpecRuntime":
+    for loader in (_load_from_env, _load_from_entry_points, _load_reference):
+        runtime = loader()
+        if runtime is not None:
+            return runtime
+    raise ImportError(
+        f"No SpecRuntime available. Install with `pip install axis-synome[runtime]`, "
+        f"set {ENV_VAR}=module:Class, or register an entry point in group "
+        f"'{ENTRY_POINT_GROUP}'."
+    )
+
+
+_runtime: SpecRuntime = _resolve_default_runtime()
+
+
+def get_runtime() -> SpecRuntime:
+    return _runtime

axis_synome-0.1.0.dev26/src/axis_synome/spec_support/runtime/math.py

@@ -0,0 +1,32 @@
+"""Math operations available to spec authors.
+
+This is the preferred API: call these free functions directly
+(e.g. ``math.linear_interp(...)``) rather than going through the
+underlying :class:`~axis_synome.spec_support.runtime.base.SpecRuntime`.
+
+When ``axis-synome`` is installed with the ``[runtime]`` extra, calls are
+served by ``ReferenceSpecRuntime`` (numpy-backed) by default. To install
+a custom runtime, set ``AXIS_SYNOME_SPEC_RUNTIME=module:Class`` in the
+environment or declare an ``axis_synome.spec_runtimes`` entry point in
+the consuming package's ``pyproject.toml`` — both are resolved once at
+import time.
+"""
+
+from collections.abc import Sequence
+
+from axis_synome.spec_support.runtime.base import get_runtime
+
+
+def linear_interp(
+    x: Sequence[float],
+    xp: Sequence[float],
+    fp: Sequence[float],
+) -> list[float]:
+    """One-dimensional linear interpolation.
+
+    Mirrors ``numpy.interp`` semantics: for each value in ``x``, return the
+    linearly-interpolated value from the ``(xp, fp)`` table. ``xp`` must be
+    increasing; values of ``x`` outside ``[xp[0], xp[-1]]`` are clamped to
+    the corresponding boundary value of ``fp``.
+    """
+    return get_runtime().linear_interp(x, xp, fp)

axis_synome-0.1.0.dev26/src/axis_synome/spec_support/runtime/reference.py

@@ -0,0 +1,20 @@
+from collections.abc import Sequence
+
+import numpy as np
+
+from axis_synome.spec_support.runtime.base import SpecRuntime
+
+
+class ReferenceSpecRuntime(SpecRuntime):
+    """numpy-backed reference implementation of SpecRuntime.
+
+    Requires the ``runtime`` extra: ``pip install axis-synome[runtime]``.
+    """
+
+    def linear_interp(
+        self,
+        x: Sequence[float],
+        xp: Sequence[float],
+        fp: Sequence[float],
+    ) -> list[float]:
+        return np.interp(x, xp, fp).tolist()

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/src/axis_synome/spec_validator/checker.py

@@ -30,6 +30,10 @@ class SpecChecker(ast.NodeVisitor):
         self._in_function = False
         self._module_imported_names: set[str] = set()  # Track imports for shadowing detection
         self._function_assigned_names: set[str] = set()  # Track assignments for shadowing detection
+        # Local names bound to axis_synome.spec_support.runtime submodules
+        # (e.g. spec_support.runtime.math). Calls on these bypass the curated
+        # stdlib math-function allowlist.
+        self._opaque_module_names: set[str] = set()
 
     def _error(self, node: ast.AST, msg: str) -> None:
         lineno = getattr(node, "lineno", 0)
@@ -149,6 +153,23 @@ class SpecChecker(ast.NodeVisitor):
         top_level = module.split(".")[0]
         if top_level not in ALLOWED_FROM_IMPORT_PREFIXES:
             self._error(node, f'import from "{module}" is not allowed')
+            return
+        if module == "axis_synome.spec_support.runtime" or module.startswith(
+            "axis_synome.spec_support.runtime."
+        ):
+            for alias in node.names:
+                self._opaque_module_names.add(alias.asname or alias.name)
+        # Restrict math imports to the allowed function names only.
+        if top_level == "math":
+            for alias in node.names:
+                if alias.name == "*":
+                    self._error(node, 'wildcard import from "math" is not allowed')
+                elif alias.name not in ALLOWED_MATH_FUNCTION_NAMES:
+                    self._error(
+                        node,
+                        f'"{alias.name}" is not an allowed math import; '
+                        f"permitted: {sorted(ALLOWED_MATH_FUNCTION_NAMES)}",
+                    )
 
     # ------------------------------------------------------------------
     # Names
@@ -181,6 +202,10 @@ class SpecChecker(ast.NodeVisitor):
             and isinstance(func.value, ast.Name)
             and func.value.id in ALLOWED_MODULE_CALL_PREFIXES
         ):
+            # Calls on axis_synome.spec_support.runtime modules (e.g. runtime.math)
+            # are uninterpreted and not subject to the stdlib math allowlist.
+            if func.value.id in self._opaque_module_names:
+                return
             if func.attr not in ALLOWED_MATH_FUNCTION_NAMES:
                 self._error(
                     node,
@@ -214,9 +239,6 @@ class SpecChecker(ast.NodeVisitor):
     def visit_Lambda(self, node: ast.Lambda) -> None:
         self._error(node, "lambda expressions are not allowed")
 
-    def visit_ListComp(self, node: ast.ListComp) -> None:
-        self._error(node, "list comprehensions are not allowed (use generator expressions)")
-
     def visit_DictComp(self, node: ast.DictComp) -> None:
         self._error(node, "dict comprehensions are not allowed")
 
@@ -262,12 +284,20 @@ class SpecChecker(ast.NodeVisitor):
                 return
             # Only @dataclass or @validated_dataclass decorated classes are allowed.
             allowed_dataclass_decorators = {"dataclass", "validated_dataclass"}
+
+            def _decorator_name(d: ast.expr) -> str | None:
+                if isinstance(d, ast.Name):
+                    return d.id
+                if isinstance(d, ast.Attribute):
+                    return d.attr
+                if isinstance(d, ast.Call):
+                    return _decorator_name(d.func)
+                return None
+
             if not any(
-                (isinstance(d, ast.Name) and d.id in allowed_dataclass_decorators)
-                or (isinstance(d, ast.Attribute) and d.attr in allowed_dataclass_decorators)
-                for d in node.decorator_list
+                _decorator_name(d) in allowed_dataclass_decorators for d in node.decorator_list
             ):
-                self._error(node, "only @dataclass classes are allowed")
+                self._error(node, "only @dataclass or @validated_dataclass classes are allowed")
                 return
             # Validate the class body: only annotated assignments and docstrings.
             for stmt in node.body:

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/src/axis_synome/spec_validator/python_subset.py

@@ -64,6 +64,7 @@ ALLOWED_FROM_IMPORT_PREFIXES: frozenset[str] = frozenset({
     "axis_synome",
     "dataclasses",
     "enum",
+    "math",
     "pydantic",
     "synome",
     "typing",
@@ -92,6 +93,7 @@ ALLOWED_BUILTINS: frozenset[str] = frozenset({
 
 ALLOWED_MATH_FUNCTION_NAMES: frozenset[str] = frozenset({
     "log",
+    "log1p",
     "exp",
     "sqrt",
     "pow",

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26/src/axis_synome.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev16
+Version: 0.1.0.dev26
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT
@@ -10,6 +10,8 @@ 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
 
@@ -18,6 +20,7 @@ A Python framework for defining and validating financial specifications, with a
 - **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
 
@@ -27,6 +30,12 @@ Install from PyPI:
 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
@@ -47,6 +56,22 @@ from axis_synome.spec.asc.entities import primes, tokens, networks, protocol_set
 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

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/src/axis_synome.egg-info/SOURCES.txt

@@ -37,9 +37,12 @@ src/axis_synome/spec/risk_capital/formulas/__init__.py
 src/axis_synome/spec/risk_capital/formulas/required_risk_capital.py
 src/axis_synome/spec_support/__init__.py
 src/axis_synome/spec_support/evm_address.py
-src/axis_synome/spec_support/metadata.py
 src/axis_synome/spec_support/validated_dataclass.py
 src/axis_synome/spec_support/validated_str.py
+src/axis_synome/spec_support/runtime/__init__.py
+src/axis_synome/spec_support/runtime/base.py
+src/axis_synome/spec_support/runtime/math.py
+src/axis_synome/spec_support/runtime/reference.py
 src/axis_synome/spec_validator/__init__.py
 src/axis_synome/spec_validator/checker.py
 src/axis_synome/spec_validator/flake8_plugin.py
@@ -50,7 +53,6 @@ tests/axis_synome/asc/mocks.py
 tests/axis_synome/asc/test_asc.py
 tests/axis_synome/asc/test_asc_collateral_ratio.py
 tests/axis_synome/asc/test_asc_incentive.py
-tests/axis_synome/asc/test_asc_spec_client_parity.py
 tests/axis_synome/asc/test_dab.py
 tests/axis_synome/asc/test_evm_address.py
 tests/axis_synome/asc/test_latent_asc.py
@@ -60,5 +62,9 @@ tests/axis_synome/asc/test_resting_asc.py
 tests/axis_synome/risk_capital/__init__.py
 tests/axis_synome/risk_capital/formulas/__init__.py
 tests/axis_synome/risk_capital/formulas/test_loss_given_default.py
+tests/axis_synome/spec_support/__init__.py
+tests/axis_synome/spec_support/runtime/__init__.py
+tests/axis_synome/spec_support/runtime/test_base.py
+tests/axis_synome/spec_support/runtime/test_math.py
 tests/axis_synome/spec_validator/test_checker.py
 tests/axis_synome/spec_validator/test_flake8_plugin.py

{axis_synome-0.1.0.dev16 → axis_synome-0.1.0.dev26}/src/axis_synome.egg-info/requires.txt

@@ -1,2 +1,5 @@
 eth-hash[pycryptodome]>=0.5.0
 pydantic>=2.0.0
+
+[runtime]
+numpy>=1.26

axis_synome-0.1.0.dev26/tests/axis_synome/spec_support/runtime/test_base.py

@@ -0,0 +1,52 @@
+from collections.abc import Sequence
+
+import pytest
+
+from axis_synome.spec_support.runtime.base import (
+    ENV_VAR,
+    SpecRuntime,
+    _resolve_default_runtime,
+    get_runtime,
+)
+from axis_synome.spec_support.runtime.reference import ReferenceSpecRuntime
+
+
+class _StubRuntime(SpecRuntime):
+    def linear_interp(
+        self,
+        x: Sequence[float],
+        xp: Sequence[float],  # noqa: ARG002
+        fp: Sequence[float],  # noqa: ARG002
+    ) -> list[float]:
+        return [0.0 for _ in x]
+
+
+class _NotARuntime:
+    pass
+
+
+def test_default_runtime_is_reference_runtime():
+    assert isinstance(get_runtime(), ReferenceSpecRuntime)
+
+
+def test_spec_runtime_cannot_be_instantiated_directly():
+    with pytest.raises(TypeError):
+        SpecRuntime()  # type: ignore[abstract]
+
+
+def test_resolve_from_env_var(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv(ENV_VAR, f"{__name__}:_StubRuntime")
+    runtime = _resolve_default_runtime()
+    assert isinstance(runtime, _StubRuntime)
+
+
+def test_resolve_from_env_var_rejects_bad_format(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv(ENV_VAR, "no_colon_here")
+    with pytest.raises(RuntimeError, match="expected 'module.path:AttrName'"):
+        _resolve_default_runtime()
+
+
+def test_resolve_from_env_var_rejects_non_spec_runtime(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv(ENV_VAR, f"{__name__}:_NotARuntime")
+    with pytest.raises(TypeError, match="not a SpecRuntime"):
+        _resolve_default_runtime()