axis-synome 0.1.0.dev69__tar.gz → 0.1.0.dev71__tar.gz

{axis_synome-0.1.0.dev69/src/axis_synome.egg-info → axis_synome-0.1.0.dev71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev69
+Version: 0.1.0.dev71
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT
@@ -74,6 +74,20 @@ If none is available, importing `axis_synome.spec_support.runtime.math` raises `
 
 ### 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](https://github.com/archon-research/synome/blob/main/docs/adr/0002-move-parser-to-next-gen-atlas.md)
+for the rationale behind co-locating the parser with the specs.
+
 ```python
 from axis_synome.spec_validator import validate_file
 

{axis_synome-0.1.0.dev69 → axis_synome-0.1.0.dev71}/README.md

@@ -59,6 +59,20 @@ If none is available, importing `axis_synome.spec_support.runtime.math` raises `
 
 ### 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](https://github.com/archon-research/synome/blob/main/docs/adr/0002-move-parser-to-next-gen-atlas.md)
+for the rationale behind co-locating the parser with the specs.
+
 ```python
 from axis_synome.spec_validator import validate_file
 

{axis_synome-0.1.0.dev69 → axis_synome-0.1.0.dev71}/WRITING_SPECS.md

@@ -269,6 +269,34 @@ def penalty(concentration: float) -> float:
     return penalty_value
 ```
 
+#### Set membership
+
+Membership tests against a closed‑world set lower to finite symbolic case
+analysis, so they stay fully reconstructible (no runtime predicates or
+uninterpreted symbols). The right‑hand side must be a module‑level named
+constant set whose members are enum members or scalar constants — typically a
+`Final[set[...]]` declared in `entities/`. Inline set literals are not allowed
+inside formulas (see the language subset), so always reference a named set.
+
+```python
+TOP_TIER_AUDIT_FIRMS: Final[set[AuditFirm]] = {
+    AuditFirm.CHAINSECURITY,
+    AuditFirm.OPENZEPPELIN,
+}
+
+
+def audit_firm_effectiveness(firm: AuditFirm) -> float:
+    return TOP_TIER_COEFFICIENT if firm in TOP_TIER_AUDIT_FIRMS else MID_TIER_COEFFICIENT
+```
+
+This lowers to a `Piecewise` whose condition expands to
+`Or(Eq(firm, AuditFirm.CHAINSECURITY), Eq(firm, AuditFirm.OPENZEPPELIN))`;
+`not in` expands to the conjunction of inequalities, and an empty set collapses
+to `False` (`in`) or `True` (`not in`). When the right‑hand side cannot be
+resolved statically the converter falls back to its uninterpreted comparison
+form and emits a warning, so prefer named constant sets to keep formulas
+reconstructible.
+
 #### Example
 
 A simple example of a function is given below:

{axis_synome-0.1.0.dev69 → axis_synome-0.1.0.dev71}/pyproject.toml

@@ -47,6 +47,9 @@ dev = [
     "ruff>=0.15",
     "ty>=0.0.16",
     "lefthook>=1.9.5",
+    "hypothesis>=6.100",
+    "sympy>=1.14.0",
+    "typing-extensions>=4.12.0",
     "axis-synome[runtime]",
 ]
 

{axis_synome-0.1.0.dev69 → axis_synome-0.1.0.dev71}/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.dev69'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev69')
+__version__ = version = '0.1.0.dev71'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev71')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev71/src/axis_synome/parser/__main__.py

@@ -0,0 +1,6 @@
+"""CLI entry point for synome parser module."""
+
+from axis_synome.parser.parse_expressions import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

axis_synome-0.1.0.dev71/src/axis_synome/parser/ast_normalizer.py

@@ -0,0 +1,34 @@
+"""Lightweight AST normalizer for expression nodes (no behavior changes).
+
+Transforms a minimal subset of nodes to simplify downstream conversion:
+- Flatten non-math attribute access: `obj.attr` -> Name("obj_attr")
+- Leave `math.*` attributes intact to preserve existing math mapping
+
+This pre-pass is intentionally conservative to avoid altering semantics.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Final
+
+MATH_PREFIXES: Final[tuple[str, ...]] = ("math",)
+
+
+class _ExprNormalizer(ast.NodeTransformer):
+    """AST NodeTransformer that flattens selected attributes for expressions."""
+
+    def visit_Attribute(self, node: ast.Attribute):  # noqa: N802 - ast API
+        value = self.visit(node.value)
+        # Only flatten simple Name.attr cases where base is not a math-like module
+        if isinstance(value, ast.Name) and value.id not in MATH_PREFIXES:
+            # Use double underscore to reduce name-collision risk and let downstream
+            # converters reconstruct attr(value) if desired.
+            return ast.copy_location(ast.Name(id=f"{value.id}__{node.attr}"), node)
+        # Default: rebuild node with transformed value
+        return ast.copy_location(ast.Attribute(value=value, attr=node.attr, ctx=node.ctx), node)
+
+
+def normalize_expr(expr_node: ast.expr) -> ast.expr:
+    """Normalize an expression AST node without changing its meaning."""
+    return _ExprNormalizer().visit(expr_node)

axis_synome-0.1.0.dev71/src/axis_synome/parser/ast_utils.py

@@ -0,0 +1,37 @@
+"""AST parsing utilities for extracting function structure."""
+
+import ast
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def find_function_def(tree: ast.Module, func_name: str) -> ast.FunctionDef:
+    """Find function definition node in AST, raise ValueError if not found."""
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name == func_name:
+            return node
+    raise ValueError(f"Could not find function {func_name} in AST")
+
+
+def is_docstring(stmt: ast.stmt) -> bool:
+    """Check if statement is a docstring."""
+    return (
+        isinstance(stmt, ast.Expr)
+        and isinstance(stmt.value, ast.Constant)
+        and isinstance(stmt.value.value, str)
+    )
+
+
+def extract_parameter_metadata(func: Callable) -> list[dict[str, Any]]:
+    """Extract parameter names from function signature."""
+    sig = inspect.signature(func)
+    params = []
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls"):
+            continue
+        params.append({
+            "name": param_name,
+            "has_default": param.default != inspect.Parameter.empty,
+        })
+    return params

axis_synome-0.1.0.dev71/src/axis_synome/parser/checks/numeric_fidelity.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+# ruff: noqa: T201 -- CLI tool that legitimately prints results to stdout/stderr.
+"""Numeric fidelity gate for the parser (standalone spec-validation tool).
+
+For every scalar formula extracted from a spec module, generate random inputs
+(via Hypothesis), evaluate both the original Python function and the SymPy
+expression the parser produced, and assert that the two agree to within a small
+tolerance. A disagreement means the parser silently changed the semantics of
+the formula.
+
+Run it directly (it is intentionally *not* a pytest test, so spec validation is
+driven by tools rather than the test runner)::
+
+    uv run python -m axis_synome.parser.checks.numeric_fidelity
+
+Exits non-zero if any scalar formula disagrees with its SymPy lowering.
+
+Scope:
+
+- This gate covers **scalar formulas** -- functions whose declared parameter
+  annotations are all primitive (``int``, ``float``, ``bool``) and whose
+  extracted ``sympy_expr`` therefore depends only on bare parameter symbols.
+- Entity-typed formulas (parameters annotated with dataclasses, ``list[X]``,
+  ``Enum`` subclasses, etc.) are out of scope here: faithfully evaluating the
+  SymPy side would require fabricating real dataclass instances and substituting
+  dotted/indexed sympy symbols accordingly. Their fidelity is guarded by
+  ``validate_formula_free_symbols`` and ``validate_entity_attribute_paths`` from
+  ``parser.validation``.
+
+Failures from this tool are real bugs -- either in the parser's lowering or in
+the spec author's assumptions about how their formula should evaluate.
+
+Hypothesis is a dev/CI dependency only; this module is intended for local/CI
+checks, not as part of the package's runtime import surface.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import math
+import pkgutil
+import sys
+from collections.abc import Callable
+from typing import Any, cast, get_origin
+
+import sympy as sp
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from axis_synome.parser.formula_extraction import _extract_function_identities
+from axis_synome.parser.validation import _unwrap_annotation
+
+SPEC_ROOT_PKG = "axis_synome.spec"
+
+# Conservative finite range to keep sympy evaluation cheap and avoid overflow in
+# functions like ``exp`` / ``log``. Authors targeting exotic domains can narrow
+# the strategy in their formula's parameter metadata in the future.
+_FLOAT_STRAT = st.floats(
+    min_value=-1e3,
+    max_value=1e3,
+    allow_nan=False,
+    allow_infinity=False,
+    allow_subnormal=False,
+)
+_INT_STRAT = st.integers(min_value=-1000, max_value=1000)
+_BOOL_STRAT = st.booleans()
+
+# Absolute and relative tolerance for fidelity comparison. Generous to absorb
+# float reassociation; narrow enough to catch sign flips, missing factors, etc.
+_ATOL = 1e-9
+_RTOL = 1e-6
+
+# Examples per formula. ``derandomize`` makes a failure reproducible across runs
+# so the gate behaves like the other deterministic spec-validation tools.
+_MAX_EXAMPLES = 50
+
+ScalarCase = tuple[str, Callable[..., Any], sp.Basic, dict[str, st.SearchStrategy[Any]]]
+
+
+def _iter_spec_modules() -> list[str]:
+    """Walk ``axis_synome.spec`` and yield every importable submodule."""
+    pkg = importlib.import_module(SPEC_ROOT_PKG)
+    names: list[str] = []
+    for info in pkgutil.walk_packages(pkg.__path__, prefix=SPEC_ROOT_PKG + "."):
+        if info.ispkg:
+            continue
+        names.append(info.name)
+    return names
+
+
+def _is_scalar_annotation(ann: Any) -> bool:
+    ann = _unwrap_annotation(ann)
+    if ann is inspect.Parameter.empty:
+        return False
+    if ann in (int, float, bool):
+        return True
+    origin = get_origin(ann)
+    if origin is None:
+        return False
+    # ``list[int]`` etc. are not scalar at the call site, but list-of-scalars is
+    # not used for any current scalar-path formula -- keep simple.
+    return False
+
+
+def _strategy_for(ann: Any) -> st.SearchStrategy[Any] | None:
+    ann = _unwrap_annotation(ann)
+    if ann is bool:
+        return _BOOL_STRAT
+    if ann is int:
+        return _INT_STRAT
+    if ann is float:
+        return _FLOAT_STRAT
+    return None
+
+
+def _is_pure_scalar_formula(
+    func: Callable[..., Any],
+    expr: sp.Basic,
+    sibling_exprs: dict[str, sp.Basic],
+    module_constants: dict[str, Any],
+) -> tuple[bool, sp.Basic, dict[str, st.SearchStrategy[Any]]]:
+    """Return (eligible, fully-substituted-expr, strategies-by-param-name).
+
+    Eligible iff every declared parameter has a primitive annotation AND every
+    free symbol in ``expr`` (after substituting sibling-formula intermediates and
+    module-level numeric constants) matches a declared parameter name.
+    """
+    try:
+        sig = inspect.signature(func)
+    except (TypeError, ValueError):
+        return False, expr, {}
+
+    strategies: dict[str, st.SearchStrategy[Any]] = {}
+    for name, param in sig.parameters.items():
+        if not _is_scalar_annotation(param.annotation):
+            return False, expr, {}
+        strat = _strategy_for(param.annotation)
+        if strat is None:
+            return False, expr, {}
+        strategies[name] = strat
+
+    param_names = set(strategies.keys())
+    seen_subs: set[str] = set()
+    while True:
+        unresolved = {str(s) for s in expr.free_symbols} - param_names
+        if not unresolved:
+            break
+        progress = False
+        for name in sorted(unresolved):
+            if name in seen_subs:
+                continue
+            sub_expr = sibling_exprs.get(name)
+            if sub_expr is not None:
+                expr = expr.subs(sp.Symbol(name), sub_expr)
+                seen_subs.add(name)
+                progress = True
+                continue
+            const = module_constants.get(name)
+            if isinstance(const, (int, float)) and not isinstance(const, bool):
+                expr = expr.subs(sp.Symbol(name), sp.Float(float(const)))
+                seen_subs.add(name)
+                progress = True
+                continue
+        if not progress:
+            return False, expr, {}
+
+    return True, expr, strategies
+
+
+def _collect_scalar_formula_cases() -> list[ScalarCase]:
+    """Discover every scalar formula across the spec tree."""
+    import types
+
+    cases: list[ScalarCase] = []
+    for mod_name in _iter_spec_modules():
+        try:
+            module = importlib.import_module(mod_name)
+        except Exception:
+            continue
+        module_globals = vars(module)
+        for attr_name in sorted(dir(module)):
+            if attr_name.startswith("_"):
+                continue
+            obj = getattr(module, attr_name, None)
+            if not isinstance(obj, types.FunctionType):
+                continue
+            if getattr(obj, "__module__", None) != module.__name__:
+                continue
+            # Per-function extraction so a single failing formula doesn't mask
+            # all the rest in its module. Pass a *copy* of module_globals because
+            # _extract_function_identities mutates it (replaces callables with
+            # IdentityData placeholders), which would break subsequent direct
+            # calls to those functions in the python-vs-sympy comparison below.
+            try:
+                identities = _extract_function_identities(
+                    obj,
+                    description=None,
+                    atlas_section=None,
+                    target_globals=dict(module_globals),
+                )
+            except Exception:
+                continue
+            # Build a sibling map of intermediate name -> sympy expression so the
+            # "main" formula can be substituted into a parameter-only form.
+            sibling_exprs: dict[str, sp.Basic] = {}
+            for identity in identities:
+                expr = getattr(identity, "sympy_expr", None)
+                node_id = getattr(identity, "node_id", "") or ""
+                if expr is None or not isinstance(expr, sp.Basic):
+                    continue
+                short = node_id.rsplit(".", 1)[-1]
+                if short:
+                    sibling_exprs[short] = expr
+
+            # Only check the identity that represents the function's return.
+            main_id = f"{obj.__module__}.{attr_name}"
+            for identity in identities:
+                node_id = getattr(identity, "node_id", "") or ""
+                if node_id != main_id and node_id != attr_name:
+                    continue
+                expr = getattr(identity, "sympy_expr", None)
+                if expr is None or not isinstance(expr, sp.Basic):
+                    continue
+                ok, sub_expr, strategies = _is_pure_scalar_formula(
+                    obj, expr, sibling_exprs, module_globals
+                )
+                if not ok:
+                    continue
+                case_id = f"{mod_name}.{attr_name}"
+                cases.append((case_id, obj, sub_expr, strategies))
+    return cases
+
+
+def _values_close(a: float, b: float) -> bool:
+    if isinstance(a, bool) or isinstance(b, bool):
+        return bool(a) == bool(b)
+    af = float(a)
+    bf = float(b)
+    if math.isnan(af) and math.isnan(bf):
+        return True
+    if math.isinf(af) or math.isinf(bf):
+        return af == bf
+    return math.isclose(af, bf, abs_tol=_ATOL, rel_tol=_RTOL)
+
+
+def _run_case(case: ScalarCase) -> str | None:
+    """Run the fidelity check for one scalar formula.
+
+    Returns ``None`` on success or a human-readable failure message (carrying the
+    falsifying inputs) otherwise.
+    """
+    case_id, func, expr, strategies = case
+    symbol_map = {name: sp.Symbol(name) for name in strategies}
+
+    @given(values=st.fixed_dictionaries({name: strategies[name] for name in strategies}))
+    @settings(max_examples=_MAX_EXAMPLES, deadline=None, derandomize=True)
+    def _check(values: dict[str, Any]) -> None:
+        try:
+            py_value = func(**values)
+        except (ZeroDivisionError, ValueError, ArithmeticError):
+            # Inputs outside the function's natural domain -- skip.
+            return
+        sub = {
+            symbol_map[name]: sp.Float(v) if isinstance(v, float) else sp.Integer(int(v))
+            for name, v in values.items()
+            if name in symbol_map
+        }
+        try:
+            substituted = cast(Any, expr.subs(cast(Any, sub)))
+            if isinstance(substituted, sp.logic.boolalg.Boolean):
+                sym_value = bool(substituted)
+            else:
+                sym_value = float(substituted.evalf())
+        except (TypeError, ValueError, ZeroDivisionError, AttributeError):
+            return
+
+        assert _values_close(py_value, sym_value), (
+            f"Numeric mismatch for {case_id} with {values}: "
+            f"python={py_value!r} sympy={sym_value!r} expr={expr!r}"
+        )
+
+    try:
+        _check()
+    except Exception as exc:  # noqa: BLE001 -- report any failure as a gate failure.
+        return f"{type(exc).__name__}: {exc}"
+    return None
+
+
+def main() -> int:
+    cases = _collect_scalar_formula_cases()
+    failures: list[tuple[str, str]] = []
+    for case in cases:
+        error = _run_case(case)
+        if error is not None:
+            failures.append((case[0], error))
+
+    if failures:
+        for case_id, error in failures:
+            print(f"FAIL: {case_id}\n  {error}", file=sys.stderr)
+        print(
+            f"\n{len(failures)} of {len(cases)} scalar formulas disagree with their "
+            f"SymPy lowering.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"OK: all {len(cases)} scalar formulas match their SymPy lowering.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())